# 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

- when consulting the wiki, read `wiki/index.md` first
- `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 and Lint are wiki maintenance workflows and require an explicit user
request. Query is read-only by default; its write-back steps apply only when
the user also explicitly requests wiki construction or maintenance.

### 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. Only within an explicitly requested wiki task, write durable findings back into the wiki.
5. Only within that wiki task, 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

Only an explicit user request to build or maintain the wiki triggers wiki
output. Code or documentation changes and newly discovered findings do not
trigger it automatically. Leave existing wiki files unchanged during ordinary
tasks.