{"owner":"eggjs","repo":"egg","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".github/copilot-instructions.md","CLAUDE.md"],"files":{"AGENTS.md":"# AGENTS.md\n\nThis is the canonical shared instruction file for coding agents working in this repository.\n\nIf another agent-specific file exists, it should import or defer to this file for shared repository guidance.\n\n## Project Map\n\nEgg is maintained as a utoo monorepo.\n\n- `packages/` contains core framework packages and shared internals.\n- `plugins/` contains optional Egg integrations.\n- `tools/` contains developer tooling such as CLI packages.\n- `tegg/` contains the tegg ecosystem.\n- `examples/` contains sample applications.\n- `site/docs/` contains the English and Chinese documentation site.\n- tests usually live beside packages under `test/`, often with fixtures under `test/fixtures/`.\n\n## Core Commands\n\nThe 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`.\n\n- `corepack enable utoo` enables utoo on a clean machine.\n- `ut install --from pnpm` hydrates the workspace.\n- `ut run build` builds all packages.\n- `ut run test` runs the main test suite.\n- `ut run lint` runs linting.\n- `ut run typecheck` runs TypeScript checking.\n- 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`.\n\n### Local CI\n\nRun 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.\n\nWhen you see `duplicate proto` failures locally:\n\n```bash\nfind tegg packages plugins tools -name dist -type d \\\n -not -path '*/node_modules/*' -not -path '*/test/*' -not -path '*/fixtures/*' \\\n -exec rm -rf {} +\n```\n\nThen re-run tests.\n\n## Coding Conventions\n\n- prefer existing repo patterns over inventing new ones\n- prefer ESM and TypeScript-first changes where applicable\n- keep file names lowercase with hyphens\n- keep public API changes deliberate and documented\n- use `oxfmt` and `oxlint --type-aware` conventions already present in the repo\n- **tegg multi-app isolation**: do NOT introduce new process-global mutable\n runtime state in `tegg/`; per-app state must be backed by a `TeggScope` slot.\n Hooks registered through the bag-pinned `app.*LifecycleUtil` getters need no\n extra wrap; detached/escape-point access (timers, emitter listeners, proxy\n handlers, module-level lifecycle-util statics) must run inside\n `TeggScope.run(app._teggScopeBag, ...)`. See the \"Multi-App Isolation\n (TeggScope)\" section in `tegg/CLAUDE.md` for the full rules.\n- **V8 startup snapshot lifecycle**: a snapshot build runs through\n `configWillLoad` and resumes from `configDidLoad` only after restore. Plugin\n constructors and `configWillLoad` must therefore keep only serializable\n configuration and metadata; create cluster clients, sockets, servers, file\n watchers, timers, native clients, and other runtime resources in\n `configDidLoad` or a later hook. If one plugin consumes another plugin's\n runtime instance, declare that plugin dependency so their `configDidLoad`\n ordering is deterministic. Do not hide an early initialization violation\n behind a placeholder/deferred proxy or recorded-call replay; fail fast and\n move the initialization to the correct lifecycle phase. Use\n `snapshotWillSerialize`/`snapshotDidDeserialize` only for framework-owned\n resources that must exist before the cutoff and have an explicit symmetric\n release/restore implementation.\n- **V8 startup snapshot dependencies**: the egg-bundler can build a V8 startup\n snapshot (`snapshot: true`), where the app boots only to `configWillLoad` at\n BUILD time. Any module loaded or instantiated during that boot that creates a\n non-serializable native binding — llhttp `HTTPParser` (http/https/undici),\n `nghttp2` (http2, and anything built on it), tls `SecureContext`, dns\n `ChannelWrap`, a `WebAssembly` instance (undici's llhttp; WASM is disabled under\n `--build-snapshot`), fs watchers, native addons, open sockets — makes the\n snapshot build FATAL (\"global handle not serialized\"). Such modules must be kept\n EXTERNAL (not inlined) so the prelude stubs them at build and forwards to the\n real module via `globalThis.__RUNTIME_REQUIRE` at restore. The framework default\n list is `DEFAULT_SNAPSHOT_LAZY_MODULES` in `tools/egg-bundler/src/lib/prelude.ts`\n (network builtins + `inspector` + `undici` + `urllib`); apps extend it via\n `egg.snapshot.lazyModules` in `package.json`. **When adding a framework\n dependency that touches the network/native stack during boot, check whether it\n must be added to that list.** A package that only reaches the network stack\n _transitively_ is already covered because those builtins are lazy (e.g.\n `@modelcontextprotocol/sdk` → `@hono/node-server` → `http2`, `@grpc/grpc-js` →\n `http2`); only a package that DIRECTLY creates native/WASM state at module-eval\n or boot-time instantiation (like `undici`) needs adding. See the \"Snapshot\n lazy-external defaults\" section in `wiki/packages/egg-bundler.md` for details.\n\n## TypeScript Global Types\n\n- put package-wide global augmentations in a dedicated `src/global.ts` or `src/global.d.ts`\n- shared cross-package global types belong in `@eggjs/typings`, not in one consumer package\n- import shared global augmentations from the package entry that needs the type surface, for example `import '@eggjs/typings/global'`\n- keep `declare global` files as modules by using an `import type` or `export {}`\n\n## Testing And PR Expectations\n\n- run the most targeted tests that validate the touched area\n- include regression coverage when changing loader, cluster, agent, HTTP, or process behavior\n- use Angular-style commit messages such as `fix(loader): ensure middleware order`\n- keep PR descriptions clear about motivation, scope, and test evidence\n\n## Security And Config\n\n- review `SECURITY.md` before handling vulnerability-related work\n- do not commit secrets, credentials, or local-only URLs\n- keep local Node.js, utoo, and pnpm versions aligned with the repository configuration (`engines.node`, `packageManager`)\n\n## Shared Knowledge Workflow\n\nThis repository also maintains an LLM-owned wiki for durable project knowledge.\n\nUse this three-layer model:\n\n### Raw Sources\n\nRaw sources are the source of truth.\n\nThey include:\n\n- repository code under `packages/`, `plugins/`, `tools/`, `tegg/`, `examples/`, and `scripts/`\n- user-facing docs under `site/docs/`\n- root markdown files such as `README.md`, `README.zh-CN.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `SECURITY.md`\n- explicit external artifacts referenced by the user or task\n- imported materials stored under `raw/`\n\nRules:\n\n- do not treat wiki summaries as authoritative when raw sources disagree\n- do not rewrite raw sources unless the task requires it\n- if you rely on an external source repeatedly, capture it in the wiki\n\n### Wiki\n\nThe wiki lives under `wiki/` and stores durable synthesized knowledge.\n\n### Schema\n\nShared workflow rules live here in `AGENTS.md`.\n\nAgent-specific files should stay thin and point back to this file instead of duplicating the schema.\n\n## Wiki Layout\n\n- `wiki/index.md` is the first wiki file to read\n- `wiki/log.md` is the append-only chronological log\n- `wiki/packages/` holds package, plugin, tool, and subsystem pages\n- `wiki/concepts/` holds architectural and cross-cutting pages\n- `wiki/workflows/` holds repeatable procedures\n- `wiki/decisions/` holds notable tradeoffs and decisions\n- `wiki/sources/` holds summaries of major source documents or external materials\n\n## Wiki Page Rules\n\nUse these page types:\n\n- `package`\n- `concept`\n- `workflow`\n- `decision`\n- `source`\n\nEvery substantive page should begin with frontmatter:\n\n```yaml\n---\ntitle: Short human-readable title\ntype: package|concept|workflow|decision|source\nsummary: One-line summary\nsource_files:\n - path/or/url\nupdated_at: YYYY-MM-DD\nstatus: seed|active|stale\n---\n```\n\nUse lowercase kebab-case filenames and keep one topic per page.\n\nUse the workspace-local Asia/Shanghai calendar date for wiki log headings and\nfrontmatter `updated_at` values.\n\n## Citation And Freshness Rules\n\n- every nontrivial wiki claim should be traceable to raw sources\n- list major source paths in `source_files`\n- label non-obvious synthesis as `Inference:`\n- record conflicts explicitly instead of flattening them\n- mark stale or unresolved claims when freshness is uncertain\n\n## Index And Log Rules\n\n`wiki/index.md` should:\n\n- list durable pages by category\n- give each page a one-line summary\n- stay concise enough to scan quickly\n\n`wiki/log.md` should record:\n\n- ingestion of substantial new sources\n- durable findings produced during a query\n- material wiki refactors or lint passes\n- code or docs changes that alter previously recorded understanding\n\nDo not log trivial typo-only edits.\n\n## Standard Workflows\n\n### Ingest\n\n1. Read `wiki/index.md`.\n2. Find existing pages that should absorb the new information.\n3. Create or update a `source` page if the source is substantial.\n4. Update impacted wiki pages.\n5. Update `wiki/index.md`.\n6. Append to `wiki/log.md` if the wiki changed materially.\n\n### Query\n\n1. Read `wiki/index.md` and relevant wiki pages first.\n2. Use the wiki as the starting point, not the final authority.\n3. Read raw sources for verification, detail, or freshness.\n4. Write durable new findings back into the wiki.\n5. Update the log when the wiki changes materially.\n\n### Lint\n\nCheck the wiki for:\n\n- orphan pages\n- stale claims after code or docs changes\n- duplicated concepts\n- missing source references\n- missing pages for frequently touched areas\n- contradictions between pages\n\nPrefer restructuring pages over making them longer.\n\n## Repo-Specific Wiki Priorities\n\nPrioritize durable wiki coverage for:\n\n- `packages/egg`, `packages/core`, `packages/utils`, and other foundational packages\n- plugins under `plugins/`\n- tools under `tools/`\n- `tegg/`\n- docs structure under `site/docs/`\n- loading, lifecycle, plugin model, testing, release, and docs-maintenance concepts\n\n## Change Trigger\n\nUpdate the wiki when a task materially changes:\n\n- public APIs\n- docs structure or contributor guidance\n- package responsibilities\n- architectural behavior\n- repeated workflows used by contributors\n- testing or release expectations\n\nFor code-only tasks, avoid wiki churn unless durable understanding changed.\n",".github/copilot-instructions.md":"# Eggjs Framework - GitHub Copilot Development Instructions\n\n**Always reference these instructions first and fallback to search or additional context gathering only when you encounter unexpected information that does not match the information provided here.**\n\n## Overview\n\nEggjs is a progressive Node.js framework for building enterprise-class server-side applications. Built on top of Koa.js, it provides a plugin system, conventions over configuration, and enterprise-grade features like clustering, logging, and security.\n\nThis is a **utoo monorepo** with multiple packages using utoo workspaces and catalog mode for centralized dependency management.\n\n## Prerequisites and Environment Setup\n\n- **Node.js >= 22.18.0 required** - This is a hard requirement\n- Enable utoo first: `corepack enable utoo`\n- **NEVER CANCEL** any build or test commands - they can take several minutes to complete\n\n## Bootstrap and Build Process\n\n**Run these commands after a fresh clone:**\n\n```bash\n# 1. Enable utoo (required first)\ncorepack enable utoo\n\n# 2. Install all dependencies - takes ~63 seconds. NEVER CANCEL. Set timeout to 120+ seconds.\nut install --from pnpm\n\n# 3. Run lint to check code quality across all packages - takes ~2 seconds\nut run lint\n\n# 4. Build all packages when validating build output - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.\nut run build\n```\n\nRun unit tests from a clean source tree, not immediately after `ut run build`.\nThe main CI test job installs dependencies with `ut install --from pnpm` and\nruns tests with `ut run ci`; it does not run `build` before tests.\n\n## Monorepo Structure\n\n### Key Packages (all in `packages/` directory)\n\n- **`packages/egg/`** - Main Eggjs framework (TypeScript, uses tsdown for builds)\n- **`packages/core/`** - Core plugin framework\n- **`packages/utils/`** - Utility functions\n- **`packages/mock/`** - Testing utilities\n- **`packages/cluster/`** - Cluster management\n- **`packages/koa/`** - Koa web framework\n- **`packages/supertest/`** - HTTP testing utilities\n- **`packages/extend2/`** - Object extension utility\n\n### Supporting Directories\n\n- **`examples/`** - Two example apps: `helloworld-commonjs` and `helloworld-typescript` (currently have runtime issues)\n- **`site/`** - Documentation website built with VitePress\n\n## Essential Commands and Timing\n\n### Build Commands\n\n- `ut run build` - **Build all packages (~14 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**\n- `ut run clean-dist` - Clean all dist directories\n\n### Testing Commands\n\n- `ut run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**\n- `ut run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**\n- `ut run ci` - **Run tests with coverage (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**\n\n### Linting Commands\n\n- `ut run lint` - Run oxlint across all packages (~2 seconds)\n\n### Documentation Commands\n\n- `ut run site:dev` - Start documentation dev server (defaults to VitePress port 5173)\n- `ut run site:build` - **Build documentation site (~24 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**\n\n### Example Applications (Currently Not Working)\n\n- `ut run example:dev:commonjs` - Start CommonJS example (has runtime issues)\n- `ut run example:dev:typescript` - Start TypeScript example (has runtime issues)\n\n## Package-Specific Commands\n\nRun commands for specific packages using `ut --filter=`:\n\n```bash\n# Examples\nut --filter=egg run test\nut --filter=@eggjs/core run build\nut --filter=site run dev\n```\n\n## Development Workflow\n\n### 1. Making Changes\n\n- Work from the source tree first. Build when you need to validate package output, but do not run build immediately before unit tests.\n- Work primarily in `packages/egg/src/` for core framework features\n- Use TypeScript throughout - all packages are TypeScript-based\n- Follow the existing directory conventions in `packages/egg/src/`:\n - `lib/` - Core classes (Application, Agent, EggApplicationCore)\n - `app/extend/` - Framework extensions (context, helper, request, response)\n - `config/` - Default configurations and plugins\n - `lib/core/` - Core components (httpclient, logger, messenger)\n - `lib/loader/` - Application loaders\n\n### 2. Validation Steps\n\n**Always perform these validation steps after making changes:**\n\n```bash\n# 1. Run lint to check code quality across all packages\nut run lint\n\n# 2. Run tests from a clean tree (some failures are expected in fresh environment)\nut run test\n\n# 3. Build all packages when build output or packaging behavior is relevant\nut run build\n\n# 4. Test documentation site when docs changed\nut run site:dev\n```\n\n### 3. Testing Strategy\n\n- **All packages use Vitest for testing** - this is the standard test runner\n- Test files follow pattern: `test/**/*.test.ts`\n- Use `import { describe, it } from 'vitest'` for test functions\n- Use Node.js built-in `assert` module for assertions\n- Create test fixtures in `packages/egg/test/fixtures/apps/` for scenario testing\n\n## Key Framework Concepts\n\n### Architecture\n\n- **EggApplicationCore** - Base application class with core functionality\n- **Application** - Main app class for worker processes\n- **Agent** - Agent process class for background tasks\n- **Context** - Extended Koa context with Egg-specific features\n- **BaseContextClass** - Base for controllers, services, subscriptions\n\n### Loading Convention (Automatic Discovery Order)\n\n1. Plugin system\n2. Configurations\n3. Application/Request/Response/Context extensions\n4. Custom loaders\n5. Services\n6. Middlewares\n7. Controllers\n8. Router\n\n### Cluster vs Single Mode\n\n- **Cluster Mode** (default) - Multi-process with master, agent, and worker processes\n- **Single Mode** - Single process for development/testing\n\n## Working with TypeScript\n\n- All packages use strict TypeScript mode\n- Uses tsdown for unbundled ESM builds (preserves file structure)\n- Each package has `tsdown.config.ts` for build configuration\n- **All sub-project tsconfig.json files MUST extend from root:** `\"extends\": \"../../tsconfig.json\"`\n- Root tsconfig.json includes all packages in `references` array\n\n## utoo Workspace & Catalog Dependencies\n\n- Dependencies defined in `pnpm-workspace.yaml` catalog section\n- Reference catalog entries: `\"package-name\": \"catalog:\"`\n- Internal workspace dependencies: `\"package-name\": \"workspace:*\"`\n- This ensures consistent versions across all packages\n\n## Common Issues and Troubleshooting\n\n### Test Failures\n\n- Some tests may fail in fresh environments - this is normal\n- Focus on fixing only failures related to your changes\n- Examples may have runtime issues - don't use them for validation\n- If tegg tests fail with `duplicate proto` after a local build, remove stale\n `dist/` directories outside fixtures and re-run tests. Built `dist/*.js`\n files can be scanned alongside `src/*.ts`, loading the same decorated class\n twice.\n\n### Build Issues\n\n- Run `ut run build` when validating build output, package exports, or changes\n that affect generated artifacts.\n- TypeScript compilation errors will show clearly\n- Build warnings are generally acceptable\n\n### ESM/CommonJS Issues\n\n- Framework supports both ESM and CommonJS\n- Main package exports both formats\n- If you see \"ERR_UNKNOWN_FILE_EXTENSION\" errors, ensure packages are built first\n\n## File Locations Reference\n\n### Key Configuration Files\n\n- `pnpm-workspace.yaml` - Workspace and catalog configuration\n- `package.json` - Root monorepo scripts and devDependencies\n- `packages/egg/package.json` - Main framework package configuration\n- `packages/egg/tsdown.config.ts` - Build configuration\n- `packages/egg/src/config/plugin.ts` - Built-in plugin configurations\n- `packages/egg/src/config/config.default.ts` - Default framework configuration\n\n### Important Source Files\n\n- `packages/egg/src/lib/application.ts` - Main Application class\n- `packages/egg/src/lib/agent.ts` - Agent process manager\n- `packages/egg/src/lib/egg.ts` - Core EggApplicationCore\n- `packages/egg/src/lib/start.ts` - Application startup logic\n- `packages/egg/src/lib/loader/` - Convention-based loaders\n\n### Build Outputs\n\n- `packages/*/dist/` - Built JavaScript and TypeScript definitions\n- `site/dist/` - Built documentation site\n\n## Validation Scenarios\n\nAfter making changes, always verify:\n\n1. **Linting Passes**: `ut run lint` shows no new errors\n2. **Tests Run From Clean Sources**: `ut run test` executes without stale build artifacts interfering\n3. **Documentation Loads**: `ut run site:dev` starts successfully and the printed VitePress URL responds\n4. **Build Success When Relevant**: `ut run build` completes without errors\n\n**Remember**: This is a complex enterprise framework. Validate incrementally, keep unit tests isolated from stale build artifacts, and focus on the core packages (`egg`, `core`, `utils`) for most development work.\n\n## Commit Message Format\n\n**CRITICAL: All commits MUST follow the [Angular Commit Message Format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) as specified in CONTRIBUTING.md.**\n\n### Required Format Structure\n\n```\n(): \n\n\n\n