feat(core): add ManifestStore for startup manifest caching

Add ManifestStore class to cache startup filesystem I/O results
(resolveModule lookups, globby scans) in `.egg/manifest.json`.
When a valid manifest exists, the framework skips redundant I/O.

Key design:
- ManifestStore.resolveModule(path, fallback) and globFiles(dir, fallback)
  encapsulate cache-read + collect logic in one place
- All paths stored as relative (forward slashes) for cross-platform portability
- Stat-based fingerprinting (lockfile + config dir) for invalidation
- Generic `extensions: Record<string, unknown>` for plugin-specific data
- `metadataOnly` mode + `loadMetadata` lifecycle hook for manifest generation
- ManifestStore.createCollector() for collection-only mode (no cached data)

Closes #5842

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

Author: killagu

packages/core/src/egg.ts

@@ -31,6 +31,8 @@ export interface EggCoreOptions {
   plugins?: any;
   serverScope?: string;
   env?: string;
+  /** Skip lifecycle hooks, only trigger loadMetadata for manifest generation */
+  metadataOnly?: boolean;
 }
 
 export type EggCoreInitOptions = Partial<EggCoreOptions>;
@@ -218,6 +220,7 @@ export class EggCore extends KoaApplication {
       serverScope: options.serverScope,
       env: options.env ?? '',
       EggCoreClass: EggCore,
+      metadataOnly: options.metadataOnly,
     });
   }
 

packages/core/src/index.ts

@@ -9,6 +9,7 @@ export * from './singleton.ts';
 export * from './loader/egg_loader.ts';
 export * from './loader/file_loader.ts';
 export * from './loader/context_loader.ts';
+export * from './loader/manifest.ts';
 export * from './utils/sequencify.ts';
 export * from './utils/timing.ts';
 export type * from './types.ts';

packages/core/src/lifecycle.ts

@@ -54,6 +54,13 @@ export interface ILifecycleBoot {
    * Do some thing before app close
    */
   beforeClose?(): Promise<void>;
+
+  /**
+   * Collect metadata for manifest generation (metadataOnly mode).
+   * Called instead of configWillLoad/configDidLoad/didLoad/willReady
+   * when the application is started with metadataOnly: true.
+   */
+  loadMetadata?(): Promise<void> | void;
 }
 
 export type BootImplClass<T = ILifecycleBoot> = new (...args: any[]) => T;
@@ -72,6 +79,7 @@ export class Lifecycle extends EventEmitter {
   #bootHooks: (BootImplClass | ILifecycleBoot)[];
   #boots: ILifecycleBoot[];
   #isClosed: boolean;
+  #metadataOnly: boolean;
   #closeFunctionSet: Set<FunWithFullPath>;
   loadReady: Ready;
   bootReady: Ready;
@@ -87,6 +95,7 @@ export class Lifecycle extends EventEmitter {
     this.#boots = [];
     this.#closeFunctionSet = new Set();
     this.#isClosed = false;
+    this.#metadataOnly = false;
     this.#init = false;
 
     this.timing.start(`${this.options.app.type} Start`);
@@ -110,7 +119,9 @@ export class Lifecycle extends EventEmitter {
     });
 
     this.ready((err) => {
-      this.triggerDidReady(err);
+      if (!this.#metadataOnly) {
+        void this.triggerDidReady(err);
+      }
       debug('app ready');
       this.timing.end(`${this.options.app.type} Start`);
     });
@@ -331,6 +342,27 @@ export class Lifecycle extends EventEmitter {
     })();
   }
 
+  async triggerLoadMetadata(): Promise<void> {
+    this.#metadataOnly = true;
+    debug('trigger loadMetadata start');
+    let firstError: Error | undefined;
+    for (const boot of this.#boots) {
+      if (typeof boot.loadMetadata === 'function') {
+        debug('trigger loadMetadata at %o', boot.fullPath);
+        try {
+          await boot.loadMetadata();
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          if (!firstError) firstError = error;
+          debug('trigger loadMetadata error at %o, error: %s', boot.fullPath, error);
+          this.emit('error', error);
+        }
+      }
+    }
+    debug('trigger loadMetadata end');
+    this.ready(firstError ?? true);
+  }
+
   #initReady(): void {
     debug('loadReady init');
     this.loadReady = new Ready({ timeout: this.readyTimeout, lazyStart: true });

packages/core/src/loader/egg_loader.ts

@@ -23,6 +23,7 @@ import { sequencify } from '../utils/sequencify.ts';
 import { Timing } from '../utils/timing.ts';
 import { type ContextLoaderOptions, ContextLoader } from './context_loader.ts';
 import { type FileLoaderOptions, CaseStyle, FULLPATH, FileLoader } from './file_loader.ts';
+import { ManifestStore, type StartupManifest } from './manifest.ts';
 
 const debug = debuglog('egg/core/loader/egg_loader');
 
@@ -47,6 +48,8 @@ export interface EggLoaderOptions {
   serverScope?: string;
   /** custom plugins */
   plugins?: Record<string, EggPluginInfo>;
+  /** Skip lifecycle hooks, only trigger loadMetadata for manifest generation */
+  metadataOnly?: boolean;
 }
 
 export type EggDirInfoType = 'app' | 'plugin' | 'framework';
@@ -67,6 +70,8 @@ export class EggLoader {
   readonly appInfo: EggAppInfo;
   readonly outDir?: string;
   dirs?: EggDirInfo[];
+  /** Startup manifest — loaded from cache or collecting for generation */
+  readonly manifest: ManifestStore;
 
   /**
    * @class
@@ -154,6 +159,11 @@ export class EggLoader {
      * @since 1.0.0
      */
     this.appInfo = this.getAppInfo();
+
+    // Load pre-computed manifest or create a collector for future generation
+    this.manifest =
+      ManifestStore.load(this.options.baseDir, this.serverEnv, this.serverScope) ??
+      ManifestStore.createCollector(this.options.baseDir);
   }
 
   get app(): EggCore {
@@ -1233,15 +1243,23 @@ export class EggLoader {
    */
   async loadCustomApp(): Promise<void> {
     await this.#loadBootHook('app');
-    this.lifecycle.triggerConfigWillLoad();
+    if (this.options.metadataOnly) {
+      await this.lifecycle.triggerLoadMetadata();
+    } else {
+      this.lifecycle.triggerConfigWillLoad();
+    }
   }
 
   /**
    * Load agent.js, same as {@link EggLoader#loadCustomApp}
    */
   async loadCustomAgent(): Promise<void> {
     await this.#loadBootHook('agent');
-    this.lifecycle.triggerConfigWillLoad();
+    if (this.options.metadataOnly) {
+      await this.lifecycle.triggerLoadMetadata();
+    } else {
+      this.lifecycle.triggerConfigWillLoad();
+    }
   }
 
   // FIXME: no logger used after egg removed
@@ -1627,6 +1645,7 @@ export class EggLoader {
       directory: options?.directory ?? directory,
       target,
       inject: this.app,
+      manifest: this.manifest,
     };
 
     const timingKey = `Load "${String(property)}" to Application`;
@@ -1652,6 +1671,7 @@ export class EggLoader {
       directory: options?.directory || directory,
       property,
       inject: this.app,
+      manifest: this.manifest,
     };
 
     const timingKey = `Load "${String(property)}" to Context`;
@@ -1688,11 +1708,15 @@ export class EggLoader {
   }
 
   resolveModule(filepath: string): string | undefined {
+    return this.manifest.resolveModule(filepath, () => this.#doResolveModule(filepath));
+  }
+
+  #doResolveModule(filepath: string): string | undefined {
     let fullPath: string | undefined;
     try {
       fullPath = utils.resolvePath(filepath);
     } catch {
-      // debug('[resolveModule] Module %o resolve error: %s', filepath, err.stack);
+      // ignore resolve errors
     }
     if (!fullPath) {
       fullPath = this.#resolveFromOutDir(filepath);
@@ -1734,6 +1758,19 @@ export class EggLoader {
       }
     }
   }
+
+  /**
+   * Generate startup manifest from collected data.
+   * Should be called after all loading phases complete.
+   */
+  generateManifest(extensions?: Record<string, unknown>): StartupManifest {
+    return this.manifest.generateManifest({
+      serverEnv: this.serverEnv,
+      serverScope: this.serverScope,
+      typescriptEnabled: isSupportTypeScript(),
+      extensions,
+    });
+  }
 }
 
 // convert dep to dependencies for compatibility

packages/core/src/loader/file_loader.ts

@@ -8,6 +8,7 @@ import globby from 'globby';
 import { isClass, isGeneratorFunction, isAsyncFunction, isPrimitive } from 'is-type-of';
 
 import utils, { type Fun } from '../utils/index.ts';
+import type { ManifestStore } from './manifest.ts';
 
 const debug = debuglog('egg/core/file_loader');
 
@@ -49,6 +50,8 @@ export interface FileLoaderOptions {
   /** set property's case when converting a filepath to property list. */
   caseStyle?: CaseStyle | CaseStyleFunction;
   lowercaseFirst?: boolean;
+  /** Startup manifest for caching globby scans and collecting results */
+  manifest?: ManifestStore;
 }
 
 export interface FileLoaderParseItem {
@@ -193,8 +196,11 @@ export class FileLoader {
     const items: FileLoaderParseItem[] = [];
     debug('[parse] parsing directories: %j', directories);
     for (const directory of directories) {
-      const filepaths = globby.sync(files, { cwd: directory });
-      debug('[parse] globby files: %o, cwd: %o => %o', files, directory, filepaths);
+      const manifest = this.options.manifest;
+      const filepaths = manifest
+        ? manifest.globFiles(directory, () => globby.sync(files, { cwd: directory }))
+        : globby.sync(files, { cwd: directory });
+      debug('[parse] files: %o, cwd: %o => %o', files, directory, filepaths);
       for (const filepath of filepaths) {
         const fullpath = path.join(directory, filepath);
         if (!fs.statSync(fullpath).isFile()) continue;