feat(egg-bin): add manifest CLI command

.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 ../../ecosystem-ci/scripts/verify-manifest.mjs
+              cd ..
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
       - uses: ./.github/actions/clone

ecosystem-ci/scripts/verify-manifest.mjs

@@ -0,0 +1,128 @@
+#!/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';
+
+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 || '30', 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);
+      if (status === '200') {
+        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;
+    }
+
+    execSync('sleep 2');
+  }
+
+  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! ===');

tools/egg-bin/package.json

@@ -30,6 +30,7 @@
     "./baseCommand": "./src/baseCommand.ts",
     "./commands/cov": "./src/commands/cov.ts",
     "./commands/dev": "./src/commands/dev.ts",
+    "./commands/manifest": "./src/commands/manifest.ts",
     "./commands/test": "./src/commands/test.ts",
     "./types": "./src/types.ts",
     "./utils": "./src/utils.ts",
@@ -42,6 +43,7 @@
       "./baseCommand": "./dist/baseCommand.js",
       "./commands/cov": "./dist/commands/cov.js",
       "./commands/dev": "./dist/commands/dev.js",
+      "./commands/manifest": "./dist/commands/manifest.js",
       "./commands/test": "./dist/commands/test.js",
       "./types": "./dist/types.js",
       "./utils": "./dist/utils.js",
@@ -56,6 +58,7 @@
     "ci": "npm run cov"
   },
   "dependencies": {
+    "@eggjs/core": "workspace:*",
     "@eggjs/tegg-vitest": "workspace:*",
     "@eggjs/utils": "workspace:*",
     "@oclif/core": "catalog:",

tools/egg-bin/scripts/manifest-generate.mjs

@@ -0,0 +1,54 @@
+import { debuglog } from 'node:util';
+
+import { importModule } from '@eggjs/utils';
+
+const debug = debuglog('egg/bin/scripts/manifest-generate');
+
+async function main() {
+  debug('argv: %o', process.argv);
+  const options = JSON.parse(process.argv[2]);
+  debug('manifest generate options: %o', options);
+
+  // Set server env before importing framework
+  if (options.env) {
+    process.env.EGG_SERVER_ENV = options.env;
+  }
+
+  const framework = await importModule(options.framework);
+  const app = await framework.start({
+    baseDir: options.baseDir,
+    framework: options.framework,
+    env: options.env,
+    metadataOnly: true,
+  });
+
+  // Generate manifest from collected metadata
+  const manifest = app.loader.generateManifest();
+
+  // Write manifest to .egg/manifest.json
+  // Resolve @eggjs/core from the framework path (not the project root),
+  // because pnpm strict mode may not hoist it to the project's node_modules.
+  const { ManifestStore } = await importModule('@eggjs/core', {
+    paths: [options.framework],
+  });
+  await ManifestStore.write(options.baseDir, manifest);
+
+  // Log stats
+  const resolveCacheCount = Object.keys(manifest.resolveCache).length;
+  const fileDiscoveryCount = Object.keys(manifest.fileDiscovery).length;
+  const extensionCount = Object.keys(manifest.extensions).length;
+  console.log('[manifest] Generated manifest v%d at %s', manifest.version, manifest.generatedAt);
+  console.log('[manifest]   resolveCache entries: %d', resolveCacheCount);
+  console.log('[manifest]   fileDiscovery entries: %d', fileDiscoveryCount);
+  console.log('[manifest]   extension entries: %d', extensionCount);
+  console.log('[manifest] Written to %s/.egg/manifest.json', options.baseDir);
+
+  // Clean up and exit
+  await app.close();
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[manifest] Generation failed:', err);
+  process.exit(1);
+});

tools/egg-bin/src/baseCommand.ts

@@ -325,6 +325,22 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
     }
   }
 
+  protected async buildRequiresExecArgv(): Promise<string[]> {
+    const requires = await this.formatRequires();
+    const execArgv: string[] = [];
+    for (const r of requires) {
+      const module = this.formatImportModule(r);
+      // Remove the quotes from the path
+      // --require "module path" -> ['--require', 'module path']
+      // --import "module path" -> ['--import', 'module path']
+      const splitIndex = module.indexOf(' ');
+      if (splitIndex !== -1) {
+        execArgv.push(module.slice(0, splitIndex), module.slice(splitIndex + 2, -1));
+      }
+    }
+    return execArgv;
+  }
+
   protected async forkNode(modulePath: string, forkArgs: string[], options: ForkNodeOptions = {}) {
     const env = {
       ...this.env,

tools/egg-bin/src/commands/dev.ts

@@ -41,19 +41,7 @@ export default class Dev<T extends typeof Dev> extends BaseCommand<T> {
     const serverBin = getSourceFilename(`../scripts/start-cluster.${ext}`);
     const eggStartOptions = await this.formatEggStartOptions();
     const args = [JSON.stringify(eggStartOptions)];
-    const requires = await this.formatRequires();
-    const execArgv: string[] = [];
-    for (const r of requires) {
-      const module = this.formatImportModule(r);
-
-      // Remove the quotes from the path
-      // --require "module path" -> ['--require', 'module path']
-      // --import "module path" -> ['--import', 'module path']
-      const splitIndex = module.indexOf(' ');
-      if (splitIndex !== -1) {
-        execArgv.push(module.slice(0, splitIndex), module.slice(splitIndex + 2, -1));
-      }
-    }
+    const execArgv = await this.buildRequiresExecArgv();
     await this.forkNode(serverBin, args, { execArgv });
   }
 

tools/egg-bin/src/commands/manifest.ts

@@ -0,0 +1,125 @@
+import { debuglog } from 'node:util';
+
+import { getFrameworkPath } from '@eggjs/utils';
+import { Args, Flags } from '@oclif/core';
+
+import { BaseCommand } from '../baseCommand.ts';
+import { getSourceFilename } from '../utils.ts';
+
+const debug = debuglog('egg/bin/commands/manifest');
+
+export default class Manifest<T extends typeof Manifest> extends BaseCommand<T> {
+  static override description = 'Generate, validate, or clean the startup manifest for faster cold starts';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %> generate',
+    '<%= config.bin %> <%= command.id %> generate --env=prod',
+    '<%= config.bin %> <%= command.id %> validate --env=prod',
+    '<%= config.bin %> <%= command.id %> clean',
+  ];
+
+  static override args = {
+    action: Args.string({
+      required: true,
+      description: 'Action to perform',
+      options: ['generate', 'validate', 'clean'],
+    }),
+  };
+
+  static override flags = {
+    framework: Flags.string({
+      description: 'specify framework that can be absolute path or npm package',
+    }),
+    env: Flags.string({
+      description: 'server environment for manifest generation/validation',
+      default: 'prod',
+    }),
+    scope: Flags.string({
+      description: 'server scope for manifest validation',
+      default: '',
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { action } = this.args;
+    switch (action) {
+      case 'generate':
+        await this.runGenerate();
+        break;
+      case 'validate':
+        await this.runValidate();
+        break;
+      case 'clean':
+        await this.runClean();
+        break;
+    }
+  }
+
+  private async runGenerate(): Promise<void> {
+    const { flags } = this;
+    const framework = getFrameworkPath({
+      framework: flags.framework,
+      baseDir: flags.base,
+    });
+    debug('generate manifest: baseDir=%s, framework=%s, env=%s', flags.base, framework, flags.env);
+
+    const options = {
+      baseDir: flags.base,
+      framework,
+      env: flags.env,
+    };
+
+    const serverBin = getSourceFilename('../scripts/manifest-generate.mjs');
+    const args = [JSON.stringify(options)];
+    const execArgv = await this.buildRequiresExecArgv();
+    await this.forkNode(serverBin, args, { execArgv });
+  }
+
+  private async runValidate(): Promise<void> {
+    const { flags } = this;
+    debug('validate manifest: baseDir=%s, env=%s, scope=%s', flags.base, flags.env, flags.scope);
+
+    // Bypass the local-env guard since the user explicitly asked to validate
+    const savedEggManifest = process.env.EGG_MANIFEST;
+    process.env.EGG_MANIFEST = 'true';
+
+    try {
+      const { ManifestStore } = await import('@eggjs/core');
+      const store = ManifestStore.load(flags.base, flags.env, flags.scope);
+
+      if (!store) {
+        console.error('[manifest] Manifest is invalid or does not exist');
+        return this.exit(1);
+      }
+
+      const { data } = store;
+      const resolveCacheCount = Object.keys(data.resolveCache).length;
+      const fileDiscoveryCount = Object.keys(data.fileDiscovery).length;
+      const extensionCount = Object.keys(data.extensions).length;
+      console.log('[manifest] Manifest is valid');
+      console.log('[manifest]   version: %d', data.version);
+      console.log('[manifest]   generatedAt: %s', data.generatedAt);
+      console.log('[manifest]   serverEnv: %s', data.invalidation.serverEnv);
+      console.log('[manifest]   serverScope: %s', data.invalidation.serverScope);
+      console.log('[manifest]   resolveCache entries: %d', resolveCacheCount);
+      console.log('[manifest]   fileDiscovery entries: %d', fileDiscoveryCount);
+      console.log('[manifest]   extension entries: %d', extensionCount);
+    } finally {
+      // Restore original env
+      if (savedEggManifest === undefined) {
+        delete process.env.EGG_MANIFEST;
+      } else {
+        process.env.EGG_MANIFEST = savedEggManifest;
+      }
+    }
+  }
+
+  private async runClean(): Promise<void> {
+    const { flags } = this;
+    debug('clean manifest: baseDir=%s', flags.base);
+
+    const { ManifestStore } = await import('@eggjs/core');
+    ManifestStore.clean(flags.base);
+    console.log('[manifest] Manifest cleaned');
+  }
+}