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

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,59 @@
+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/scope before importing framework
+  if (options.env) {
+    process.env.EGG_SERVER_ENV = options.env;
+  }
+  if (options.scope) {
+    process.env.EGG_SERVER_SCOPE = options.scope;
+  }
+
+  // Clean any existing manifest before generation to ensure the collector
+  // captures all lookups (not just cache misses from a stale manifest).
+  const { ManifestStore } = await importModule('@eggjs/core', {
+    paths: [options.framework],
+  });
+  ManifestStore.clean(options.baseDir);
+
+  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
+  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 });
   }