AGENTS.md · eggjs/egg

Sections

1. Project Map
2. Core Commands
3. Coding Conventions
4. TypeScript Global Types
5. Testing And PR Expectations
6. Security And Config
7. Shared Knowledge Workflow
8. Wiki Layout
9. Wiki Page Rules
10. Citation And Freshness Rules
11. Index And Log Rules
12. Standard Workflows
13. Repo-Specific Wiki Priorities
14. Change Trigger

First lines (shown under the repo's MIT license)

# 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`); workspace patterns and overrides live in `package.json`, and shared catalogs live in the tracked `.utoo.toml`. CI installs the latest utoo release; the old pnpm configuration is retained only as a migration reference.

- `npm install --global utoo@latest` installs the latest utoo release on a clean machine.
- `ut install` 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 → 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/AGENTS.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 aligned with `engines.node` and use the latest utoo release

## Shared Knowledge Workflow

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

### Explicit Wiki Write Trigger

Create, update, reorganize, or log wiki content only when the user explicitly
requests a wiki build or maintenance task. Reading the wiki for context does
not authorize writing to it.

Ordinary coding, debugging, testing, reviews, documentation edits, and PR work
must not produce wiki changes, even when they reveal durable findings or change
APIs, architecture, contributor workflows, or testing expectations. Do not
include incidental wiki updates in commits or PRs. Report relevant findings in
the task response or PR description instead.

The wiki writing rules below apply only within an explicitly requested wiki
task. 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
- during an explicitly requested wiki task, capture repeatedly used external sources 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