egg

# CLAUDE.md

@AGENTS.md

## Claude-Specific Notes

- Keep shared repository guidance in `AGENTS.md`.
- Keep this file thin and use it only for Claude Code specific imports or overrides.
- For global type definitions, follow the TypeScript Global Types section in `AGENTS.md`.

# AGENTS.md

This is the canonical shared instruction file for coding agents working in this repository.

If another agent-specific file exists, it should import or defer to this file for shared repository guidance.

## Project Map

Egg is maintained as a utoo monorepo.

- `packages/` contains core framework packages and shared internals.
- `plugins/` contains optional Egg integrations.
- `tools/` contains developer tooling such as CLI packages.
- `tegg/` contains the tegg ecosystem.
- `examples/` contains sample applications.
- `site/docs/` contains the English and Chinese documentation site.
- tests usually live beside packages under `test/`, often with fixtures under `test/fixtures/`.

## Core Commands

The repository runs on [utoo](https://github.com/utooland/utoo) (`ut`); the workspace is still defined in `pnpm-workspace.yaml` (catalog mode), so `ut install` reads it via `--from pnpm`.

- `corepack enable utoo` enables utoo on a clean machine.
- `ut install --from pnpm` hydrates the workspace.
- `ut run build` builds all packages.
- `ut run test` runs the main test suite.
- `ut run lint` runs linting.
- `ut run typecheck` runs TypeScript checking.
- use filtered commands for focused work, for example `ut run test --workspace @eggjs/bin` or `ut run build --workspace @eggjs/bin`; prefer the package-name form of `--workspace` (the `./tools/...` path form does not match on Windows); a package without its own script (for example `build` in @eggjs/scripts) needs the root script plus the tsdown workspace path filter instead: `ut run build -- --workspace ./tools/scripts`.

### Local CI

Run tests **without building first**. The CI workflow (`ut install --from pnpm → ut run ci`) never runs `build` before tests. If `dist/` directories exist from a prior build, tegg plugin tests will fail with `duplicate proto` errors because globby scans both `src/*.ts` and `dist/*.js`, loading the same decorated class twice.

When you see `duplicate proto` failures locally:

```bash
find tegg packages plugins tools -name dist -type d \
  -not -path '*/node_modules/*' -not -path '*/test/*' -not -path '*/fixtures/*' \
  -exec rm -rf {} +
```

Then re-run tests.

## Coding Conventions

- prefer existing repo patterns over inventing new ones
- prefer ESM and TypeScript-first changes where applicable
- keep file names lowercase with hyphens
- keep public API changes deliberate and documented
- use `oxfmt` and `oxlint --type-aware` conventions already present in the repo
- **tegg multi-app isolation**: do NOT introduce new process-global mutable
  runtime state in `tegg/`; per-app state must be backed by a `TeggScope` slot.
  Hooks registered through the bag-pinned `app.*LifecycleUtil` getters need no
  extra wrap; detached/escape-point access (timers, emitter listeners, proxy
  handlers, module-level lifecycle-util statics) must run inside
  `TeggScope.run(app._teggScopeBag, ...)`. See the "Multi-App Isolation
  (TeggScope)" section in `tegg/CLAUDE.md` for the full rules.
- **V8 startup snapshot lifecycle**: a snapshot build runs through
  `configWillLoad` and resumes from `configDidLoad` only after restore. Plugin
  constructors and `configWillLoad` must therefore keep only serializable
  configuration and metadata; create cluster clients, sockets, servers, file
  watchers, timers, native clients, and other runtime resources in
  `configDidLoad` or a later hook. If one plugin consumes another plugin's
  runtime instance, declare that plugin dependency so their `configDidLoad`
  ordering is deterministic. Do not hide an early initialization violation
  behind a placeholder/deferred proxy or recorded-call replay; fail fast and
  move the initialization to the correct lifecycle phase. Use
  `snapshotWillSerialize`/`snapshotDidDeserialize` only for framework-owned
  resources that must exist before the cutoff and have an explicit symmetric
  release/restore implementation.
- **V8 startup snapshot dependencies**: the egg-bundler can build a V8 startup
  snapshot (`snapshot: true`), where the app boots only to `configWillLoad` at
  BUILD time. Any module loaded or instantiated during that boot that creates a
  non-serializable native binding — llhttp `HTTPParser` (http/https/undici),
  `nghttp2` (http2, and anything built on it), tls `SecureContext`, dns
  `ChannelWrap`, a `WebAssembly` instance (undici's llhttp; WASM is disabled under
  `--build-snapshot`), fs watchers, native addons, open sockets — makes the
  snapshot build FATAL ("global handle not serialized"). Such modules must be kept
  EXTERNAL (not inlined) so the prelude stubs them at build and forwards to the
  real module via `globalThis.__RUNTIME_REQUIRE` at restore. The framework default
  list is `DEFAULT_SNAPSHOT_LAZY_MODULES` in `tools/egg-bundler/src/lib/prelude.ts`
  (network builtins + `inspector` + `undici` + `urllib`); apps extend it via
  `egg.snapshot.lazyModules` in `package.json`. **When adding a framework
  dependency that touches the network/native stack during boot, check whether it
  must be added to that list.** A package that only reaches the network stack
  _transitively_ is already covered because those builtins are lazy (e.g.
  `@modelcontextprotocol/sdk` → `@hono/node-server` → `http2`, `@grpc/grpc-js` →
  `http2`); only a package that DIRECTLY creates native/WASM state at module-eval
  or boot-time instantiation (like `undici`) needs adding. See the "Snapshot
  lazy-external defaults" section in `wiki/packages/egg-bundler.md` for details.

## TypeScript Global Types

- put package-wide global augmentations in a dedicated `src/global.ts` or `src/global.d.ts`
- shared cross-package global types belong in `@eggjs/typings`, not in one consumer package
- import shared global augmentations from the package entry that needs the type surface, for example `import '@eggjs/typings/global'`
- keep `declare global` files as modules by using an `import type` or `export {}`

## Testing And PR Expectations

- run the most targeted tests that validate the touched area
- include regression coverage when changing loader, cluster, agent, HTTP, or process behavior
- use Angular-style commit messages such as `fix(loader): ensure middleware order`
- keep PR descriptions clear about motivation, scope, and test evidence

## Security And Config

- review `SECURITY.md` before handling vulnerability-related work
- do not commit secrets, credentials, or local-only URLs
- keep local Node.js, utoo, and pnpm versions aligned with the repository configuration (`engines.node`, `packageManager`)

## Shared Knowledge Workflow

This repository also maintains an LLM-owned wiki for durable project knowledge.

Use this three-layer model:

### Raw Sources

Raw sources are the source of truth.

They include:

- repository code under `packages/`, `plugins/`, `tools/`, `tegg/`, `examples/`, and `scripts/`
- user-facing docs under `site/docs/`
- root markdown files such as `README.md`, `README.zh-CN.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `SECURITY.md`
- explicit external artifacts referenced by the user or task
- imported materials stored under `raw/`

Rules:

- do not treat wiki summaries as authoritative when raw sources disagree
- do not rewrite raw sources unless the task requires it
- if you rely on an external source repeatedly, capture it in the wiki

### Wiki

The wiki lives under `wiki/` and stores durable synthesized knowledge.

### Schema

Shared workflow rules live here in `AGENTS.md`.

Agent-specific files should stay thin and point back to this file instead of duplicating the schema.

## Wiki Layout

- `wiki/index.md` is the first wiki file to read
- `wiki/log.md` is the append-only chronological log
- `wiki/packages/` holds package, plugin, tool, and subsystem pages
- `wiki/concepts/` holds architectural and cross-cutting pages
- `wiki/workflows/` holds repeatable procedures
- `wiki/decisions/` holds notable tradeoffs and decisions
- `wiki/sources/` holds summaries of major source documents or external materials

## Wiki Page Rules

Use these page types:

- `package`
- `concept`
- `workflow`
- `decision`
- `source`

Every substantive page should begin with frontmatter:

```yaml
---
title: Short human-readable title
type: package|concept|workflow|decision|source
summary: One-line summary
source_files:
  - path/or/url
updated_at: YYYY-MM-DD
status: seed|active|stale
---
```

Use lowercase kebab-case filenames and keep one topic per page.

Use the workspace-local Asia/Shanghai calendar date for wiki log headings and
frontmatter `updated_at` values.

## Citation And Freshness Rules

- every nontrivial wiki claim should be traceable to raw sources
- list major source paths in `source_files`
- label non-obvious synthesis as `Inference:`
- record conflicts explicitly instead of flattening them
- mark stale or unresolved claims when freshness is uncertain

## Index And Log Rules

`wiki/index.md` should:

- list durable pages by category
- give each page a one-line summary
- stay concise enough to scan quickly

`wiki/log.md` should record:

- ingestion of substantial new sources
- durable findings produced during a query
- material wiki refactors or lint passes
- code or docs changes that alter previously recorded understanding

Do not log trivial typo-only edits.

## Standard Workflows

### Ingest

1. Read `wiki/index.md`.
2. Find existing pages that should absorb the new information.
3. Create or update a `source` page if the source is substantial.
4. Update impacted wiki pages.
5. Update `wiki/index.md`.
6. Append to `wiki/log.md` if the wiki changed materially.

### Query

1. Read `wiki/index.md` and relevant wiki pages first.
2. Use the wiki as the starting point, not the final authority.
3. Read raw sources for verification, detail, or freshness.
4. Write durable new findings back into the wiki.
5. Update the log when the wiki changes materially.

### Lint

Check the wiki for:

- orphan pages
- stale claims after code or docs changes
- duplicated concepts
- missing source references
- missing pages for frequently touched areas
- contradictions between pages

Prefer restructuring pages over making them longer.

## Repo-Specific Wiki Priorities

Prioritize durable wiki coverage for:

- `packages/egg`, `packages/core`, `packages/utils`, and other foundational packages
- plugins under `plugins/`
- tools under `tools/`
- `tegg/`
- docs structure under `site/docs/`
- loading, lifecycle, plugin model, testing, release, and docs-maintenance concepts

## Change Trigger

Update the wiki when a task materially changes:

- public APIs
- docs structure or contributor guidance
- package responsibilities
- architectural behavior
- repeated workflows used by contributors
- testing or release expectations

For code-only tasks, avoid wiki churn unless durable understanding changed.