feat(egg-bin): add manifest CLI command

.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 ===');

site/.vitepress/config.mts

@@ -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/docs/core/manifest.md

@@ -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.