feat(egg-bin): add manifest CLI command (#5850)

## Summary

- Add `egg-bin manifest` command with three actions: `generate`,
`validate`, `clean`
- `generate`: forks child process to boot app in `metadataOnly` mode,
writes `.egg/manifest.json`
- `validate`: in-process `ManifestStore.load()` check with metadata
output
  - `clean`: removes `.egg/manifest.json`
- Extract `buildRequiresExecArgv()` from `dev.ts` into `BaseCommand` for
reuse
- Add E2E verification script
(`ecosystem-ci/scripts/verify-manifest.mjs`) — tests full manifest
lifecycle including app boot with manifest + health check
- Update `.github/workflows/e2e-test.yml` to run manifest E2E in
hello-tegg

### Local benchmark (cnpmcore, purge before each run)

| Metric | No manifest | With manifest | Improvement |
|--------|------------|---------------|-------------|
| appStart | ~980ms | ~780ms | **~20%** |
| loadFiles | ~660ms | ~490ms | **~26%** |
| Load app.js | ~280ms | ~150ms | **~46%** |
| Load Config | ~10ms | ~5ms | **~50%** |

## Test plan

- [x] `pnpm --filter=@eggjs/bin run typecheck` passes
- [x] `pnpm --filter=@eggjs/bin run pretest` (tsdown build) passes
- [x] Local E2E: manifest generate/validate/clean on helloworld-tegg
- [x] Local E2E: manifest generate/validate/clean + boot on cnpmcore
- [x] Startup benchmark with `sudo purge` confirms ~20% cold start
improvement
- [ ] CI E2E workflow with hello-tegg

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a manifest CLI to generate, validate, and clean startup
manifests.

* **Scripts**
* New manifest generation and verification scripts to produce, assert,
run, and clean manifest lifecycles.

* **Tests**
* End-to-end CI verification added to build, validate, start,
health-check, and clean manifests.

* **Documentation**
* New English and Chinese docs and sidebar entry describing the startup
manifest and workflows.

* **Refactor**
* Simplified construction of Node process arguments for consistent
command execution.

* **Chores**
  * CI matrix updated (Node 20 removed).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: killagu

.github/workflows/ci.yml

@@ -62,7 +62,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
-        node: ['20', '22', '24']
+        node: ['22', '24']
 
     name: Test (${{ matrix.os }}, ${{ matrix.node }})
     runs-on: ${{ matrix.os }}
@@ -170,7 +170,7 @@ jobs:
         run: pnpm run ci
 
       - name: Run example tests
-        if: ${{ matrix.node != '20' && matrix.os != 'windows-latest' }}
+        if: ${{ matrix.os != 'windows-latest' }}
         run: |
           pnpm run example:test:all
 

.github/workflows/e2e-test.yml

@@ -132,6 +132,10 @@ jobs:
               npm run lint
               npm run test
               npm run prepublishOnly
+
+              # Manifest E2E: generate, validate, boot with manifest, clean
+              node ../../scripts/verify-manifest.mjs
+              cd ..
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
       - uses: ./.github/actions/clone

ecosystem-ci/scripts/verify-manifest.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * E2E verification script for the egg-bin manifest CLI.
+ *
+ * Run this inside a project directory that has egg-bin and egg installed.
+ * It tests the full manifest lifecycle:
+ *   1. generate — creates .egg/manifest.json via metadataOnly boot
+ *   2. validate — verifies the manifest is structurally valid
+ *   3. boot with manifest — starts the app using the manifest and health-checks it
+ *   4. clean — removes .egg/manifest.json
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+const projectDir = process.cwd();
+const manifestPath = join(projectDir, '.egg', 'manifest.json');
+const env = process.env.MANIFEST_VERIFY_ENV || 'unittest';
+const healthPort = process.env.MANIFEST_VERIFY_PORT || '7002';
+const healthTimeout = parseInt(process.env.MANIFEST_VERIFY_TIMEOUT || '60', 10);
+
+function run(cmd) {
+  console.log(`\n$ ${cmd}`);
+  execSync(cmd, { stdio: 'inherit', cwd: projectDir });
+}
+
+function runCapture(cmd) {
+  console.log(`\n$ ${cmd}`);
+  return execSync(cmd, { cwd: projectDir, encoding: 'utf-8' });
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    console.error(`FAIL: ${message}`);
+    process.exit(1);
+  }
+  console.log(`PASS: ${message}`);
+}
+
+console.log('=== Manifest E2E Verification ===');
+console.log('Project: %s', projectDir);
+console.log('Env: %s', env);
+
+// Step 1: Clean any pre-existing manifest
+if (existsSync(manifestPath)) {
+  rmSync(manifestPath);
+  console.log('Cleaned pre-existing manifest');
+}
+
+// Step 2: Generate manifest
+console.log('\n--- Step 1: Generate manifest ---');
+run(`npx egg-bin manifest generate --env=${env}`);
+
+// Step 3: Verify manifest file exists and has valid structure
+console.log('\n--- Step 2: Verify manifest structure ---');
+assert(existsSync(manifestPath), '.egg/manifest.json exists after generate');
+
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+assert(manifest.version === 1, 'manifest version is 1');
+assert(typeof manifest.generatedAt === 'string' && manifest.generatedAt.length > 0, 'manifest has generatedAt');
+assert(typeof manifest.invalidation === 'object', 'manifest has invalidation');
+assert(manifest.invalidation.serverEnv === env, `manifest serverEnv matches "${env}"`);
+assert(typeof manifest.resolveCache === 'object', 'manifest has resolveCache');
+assert(typeof manifest.fileDiscovery === 'object', 'manifest has fileDiscovery');
+assert(typeof manifest.extensions === 'object', 'manifest has extensions');
+
+const resolveCacheCount = Object.keys(manifest.resolveCache).length;
+const fileDiscoveryCount = Object.keys(manifest.fileDiscovery).length;
+console.log('  resolveCache: %d entries', resolveCacheCount);
+console.log('  fileDiscovery: %d entries', fileDiscoveryCount);
+
+// Step 4: Validate manifest via CLI
+console.log('\n--- Step 3: Validate manifest via CLI ---');
+run(`npx egg-bin manifest validate --env=${env}`);
+
+// Step 5: Boot the app with manifest and verify it starts correctly
+console.log('\n--- Step 4: Boot app with manifest ---');
+try {
+  run(`npx eggctl start --port=${healthPort} --env=${env} --daemon`);
+
+  const healthUrl = `http://127.0.0.1:${healthPort}/`;
+  const startTime = Date.now();
+  let ready = false;
+
+  console.log(`Waiting for app at ${healthUrl} (timeout: ${healthTimeout}s)...`);
+  while (true) {
+    try {
+      const output = runCapture(`curl -s -o /dev/null -w "%{http_code}" "${healthUrl}"`);
+      const status = output.trim();
+      console.log('  Health check: status=%s', status);
+      // Any HTTP response (not connection refused) means the app is up.
+      // Not all apps have a route on `/`, so we accept any status code.
+      if (status !== '000') {
+        ready = true;
+        break;
+      }
+    } catch {
+      console.log('  Health check: connection refused, retrying...');
+    }
+
+    const elapsed = (Date.now() - startTime) / 1000;
+    if (elapsed >= healthTimeout) {
+      console.log('  Health check timed out after %ds', elapsed);
+      break;
+    }
+
+    await sleep(2000);
+  }
+
+  run(`npx eggctl stop`);
+  assert(ready, 'App booted successfully with manifest');
+} catch (err) {
+  // Try to stop if started
+  try {
+    run(`npx eggctl stop`);
+  } catch {
+    /* ignore */
+  }
+  console.error('Boot test failed:', err.message);
+  process.exit(1);
+}
+
+// Step 6: Clean manifest
+console.log('\n--- Step 5: Clean manifest ---');
+run(`npx egg-bin manifest clean`);
+assert(!existsSync(manifestPath), '.egg/manifest.json removed after clean');
+
+console.log('\n=== All manifest E2E checks passed ===');

pnpm-lock.yaml

@@ -312,6 +312,7 @@ function sidebarCore(): DefaultTheme.SidebarItem[] {
         { text: 'Internationalization', link: 'i18n' },
         { text: 'View Template', link: 'view' },
         { text: 'Security', link: 'security' },
+        { text: 'Startup Manifest', link: 'manifest' },
       ],
     },
   ];
@@ -422,6 +423,7 @@ function sidebarCoreZhCN(): DefaultTheme.SidebarItem[] {
         { text: '国际化', link: 'i18n' },
         { text: '模板渲染', link: 'view' },
         { text: '安全', link: 'security' },
+        { text: '启动清单', link: 'manifest' },
       ],
     },
   ];

site/.vitepress/config.mts

@@ -0,0 +1,141 @@
+# Startup Manifest
+
+Egg provides a startup manifest mechanism that caches file discovery and module resolution results to accelerate application cold starts.
+
+## How It Works
+
+Every time an application starts, the framework performs extensive filesystem operations:
+
+- **Module resolution**: Hundreds of `fs.existsSync` calls probing `.ts`, `.js`, `.mjs` extensions
+- **File discovery**: Multiple `globby.sync` scans across plugin, config, and extension directories
+- **tegg module scanning**: Traversing module directories and `import()`-ing decorator files to collect metadata
+
+The manifest mechanism collects these results on the first startup and writes them to `.egg/manifest.json`. Subsequent startups read from this cache, skipping redundant file I/O.
+
+## Performance Improvement
+
+Measured on cnpmcore in a container cold-start scenario (no filesystem page cache):
+
+| Metric      | No Manifest | With Manifest | Improvement |
+| ----------- | ----------- | ------------- | ----------- |
+| App Start   | ~980ms      | ~780ms        | **~20%**    |
+| Load Files  | ~660ms      | ~490ms        | **~26%**    |
+| Load app.js | ~280ms      | ~150ms        | **~46%**    |
+
+> Note: In local development, the OS page cache makes file I/O nearly zero-cost, so the improvement is negligible. The manifest primarily optimizes container cold starts and CI/CD environments without warm caches.
+
+## Usage
+
+### CLI Management (Recommended)
+
+`egg-bin` provides a `manifest` command to manage the startup manifest:
+
+#### Generate
+
+```bash
+# Generate for production
+$ egg-bin manifest generate --env=prod
+
+# Specify environment and scope
+$ egg-bin manifest generate --env=prod --scope=aliyun
+
+# Specify framework
+$ egg-bin manifest generate --env=prod --framework=yadan
+```
+
+The generation process boots the app in `metadataOnly` mode (skipping lifecycle hooks, only collecting metadata), then writes the results to `.egg/manifest.json`.
+
+#### Validate
+
+```bash
+$ egg-bin manifest validate --env=prod
+```
+
+Example output:
+
+```
+[manifest] Manifest is valid
+[manifest]   version: 1
+[manifest]   generatedAt: 2026-03-29T12:13:18.039Z
+[manifest]   serverEnv: prod
+[manifest]   serverScope:
+[manifest]   resolveCache entries: 416
+[manifest]   fileDiscovery entries: 31
+[manifest]   extension entries: 1
+```
+
+If the manifest is invalid or missing, the command exits with a non-zero code.
+
+#### Clean
+
+```bash
+$ egg-bin manifest clean
+```
+
+### Automatic Generation
+
+After a normal startup, the framework automatically generates a manifest during the `ready` phase (via `dumpManifest`). On the next startup, if the manifest is valid, it is automatically used.
+
+## Invalidation
+
+The manifest includes fingerprint data and is automatically invalidated when:
+
+- **Lockfile changes**: `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock` mtime or size changes
+- **Config directory changes**: Files in `config/` change (MD5 fingerprint)
+- **Environment mismatch**: `serverEnv` or `serverScope` differs from the manifest
+- **TypeScript state change**: `EGG_TYPESCRIPT` enabled/disabled state changes
+- **Version mismatch**: Manifest format version differs
+
+When the manifest is invalid, the framework falls back to normal file discovery — startup is never blocked.
+
+## Environment Variables
+
+| Variable       | Description                  | Default                                               |
+| -------------- | ---------------------------- | ----------------------------------------------------- |
+| `EGG_MANIFEST` | Enable manifest in local env | `false` (manifest not loaded in local env by default) |
+
+> Local development (`serverEnv=local`) does not load the manifest by default, since files change frequently. Set `EGG_MANIFEST=true` to force-enable.
+
+## Deployment Recommendations
+
+### Container Deployment
+
+Generate the manifest in your Dockerfile after building:
+
+```dockerfile
+# Install dependencies and build
+RUN npm install --production
+RUN npm run build
+
+# Generate startup manifest
+RUN npx egg-bin manifest generate --env=prod
+
+# Start the app (manifest is used automatically)
+CMD ["npm", "start"]
+```
+
+### CI/CD Pipelines
+
+Generate the manifest during the build stage and deploy it with the artifact:
+
+```bash
+# Build
+npm run build
+
+# Generate manifest
+npx egg-bin manifest generate --env=prod
+
+# Validate manifest
+npx egg-bin manifest validate --env=prod
+
+# Package (includes .egg/manifest.json)
+tar -zcvf release.tgz .
+```
+
+## Important Notes
+
+1. **Environment-bound**: The manifest is bound to `serverEnv` and `serverScope` (deployment type, e.g. `aliyun`). Different environments or deployment types require separate manifests.
+2. **Regenerate after dependency changes**: Installing or updating dependencies changes the lockfile, which automatically invalidates the manifest.
+3. **`.egg` directory**: The manifest is stored at `.egg/manifest.json`. Consider adding `.egg/` to `.gitignore`.
+4. **Safe fallback**: A missing or invalid manifest causes the framework to fall back to normal discovery — startup is never broken.
+5. **metadataOnly mode**: `manifest generate` does not run the full application lifecycle — no database connections or external services are started.