@fluojs/cli 2.0.1 → 3.0.0

package/dist/cli.js

@@ -1,35 +1,14 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { diagnosticsUsage, runAnalyzeCommand, runDoctorCommand, runInfoCommand } from './commands/diagnostics.js';
-import { runGenerateCommand } from './commands/generate.js';
-import { runInspectCommand } from './commands/inspect.js';
-import { migrateUsage, runMigrateCommand } from './commands/migrate.js';
-import { runNewCommand } from './commands/new.js';
-import { addUsage, runAddCommand, runUpgradeCommand, upgradeUsage } from './commands/package-workflow.js';
-import { runScriptCommand, scriptUsage } from './commands/scripts.js';
-import { runNodeRestartRunner } from './dev-runner/node-restart-runner.js';
-import { builtInGeneratorCollection, generatorManifest, generatorOptionSchemas, resolveGeneratorKind } from './generators/manifest.js';
 import { renderAliasList, renderHelpTable } from './help.js';
 import { removeUpdateCheckFlags, runCliUpdateCheck } from './update-check.js';
-import { inspectUsage, newUsage } from './usage.js';
+import { inspectUsage, newUsage, typegenUsage } from './usage.js';
 
 /**
  * Runtime dependency overrides for embedding the CLI in tests or higher-level tooling.
  */
 
-const GENERATE_KIND_HELP = [...generatorManifest.map(entry => ({
-  aliases: [...entry.aliases],
-  description: entry.description,
-  kind: entry.kind,
-  schematic: entry.schematic,
-  wiring: entry.wiringBehavior === 'auto-registered' ? 'auto' : 'manual'
-}))];
-const GENERATE_OPTION_HELP = [...generatorOptionSchemas.map(option => ({
-  aliases: [...option.aliases],
-  description: option.description,
-  option: option.name
-}))];
 const TOP_LEVEL_COMMAND_HELP = [{
   aliases: ['create'],
   command: 'new',
@@ -70,6 +49,10 @@ const TOP_LEVEL_COMMAND_HELP = [{
   aliases: [],
   command: 'inspect',
   description: 'Inspect runtime platform snapshot/diagnostics and emit timing optionally.'
+}, {
+  aliases: [],
+  command: 'typegen',
+  description: 'Generate, check, or watch path-only React page route types.'
 }, {
   aliases: [],
   command: 'migrate',
@@ -114,7 +97,10 @@ function parseDevRunnerInvocation(argv) {
     runtime
   };
 }
-function normalizeGeneratorKind(value) {
+async function normalizeGeneratorKind(value) {
+  const {
+    resolveGeneratorKind
+  } = await import('./generators/manifest.js');
   return resolveGeneratorKind(value);
 }
 function isHelpFlag(value) {
@@ -137,8 +123,25 @@ function readCliVersion() {
   }
   return manifest.version;
 }
-function generateUsage() {
-  return ['Usage: fluo generate|g <kind> <name> [options]', '       fluo generate|g request-dto|req <feature> <name> [options]', '       fluo generate|g e2e <name> [options]', '', 'Schematics', renderHelpTable(GENERATE_KIND_HELP, [{
+async function generateUsage() {
+  const {
+    builtInGeneratorCollection,
+    generatorManifest,
+    generatorOptionSchemas
+  } = await import('./generators/manifest.js');
+  const generateKindHelp = generatorManifest.map(entry => ({
+    aliases: [...entry.aliases],
+    description: entry.description,
+    kind: entry.kind,
+    schematic: entry.schematic,
+    wiring: entry.wiringBehavior === 'auto-registered' ? 'auto' : 'manual'
+  }));
+  const generateOptionHelp = generatorOptionSchemas.map(option => ({
+    aliases: [...option.aliases],
+    description: option.description,
+    option: option.name
+  }));
+  return ['Usage: fluo generate|g <kind> <name> [options]', '       fluo generate|g request-dto|req <feature> <name> [options]', '       fluo generate|g e2e <name> [options]', '', 'Schematics', renderHelpTable(generateKindHelp, [{
     header: 'Schematic',
     render: entry => entry.schematic
   }, {
@@ -150,7 +153,7 @@ function generateUsage() {
   }, {
     header: 'Description',
     render: entry => entry.description
-  }]), '', '  auto   = class is auto-registered in the domain module (created if absent)', '  manual = files only; you must wire the generated class into a module yourself', '', 'Collections', `  ${builtInGeneratorCollection.id} (${builtInGeneratorCollection.source})`, '  External or app-local generator collections are intentionally deferred; no packages or config files are loaded by generate.', '', 'Options', renderHelpTable(GENERATE_OPTION_HELP, [{
+  }]), '', '  auto   = class is auto-registered in the domain module (created if absent)', '  manual = files only; you must wire the generated class into a module yourself', '', 'Collections', `  ${builtInGeneratorCollection.id} (${builtInGeneratorCollection.source})`, '  External or app-local generator collections are intentionally deferred; no packages or config files are loaded by generate.', '', 'Options', renderHelpTable(generateOptionHelp, [{
     header: 'Option',
     render: entry => entry.option
   }, {
@@ -191,14 +194,14 @@ function resolveDefaultTargetDirectory(startDirectory) {
   }
   return resolvedStartDirectory;
 }
-function parseGenerateArgs(argv) {
+async function parseGenerateArgs(argv) {
   const [command, rawKind, firstName, ...optionArgs] = argv;
-  const kind = normalizeGeneratorKind(rawKind);
+  const kind = await normalizeGeneratorKind(rawKind);
   if (!(command === 'g' || command === 'generate')) {
     throw new Error(usage());
   }
   if (!kind || !firstName) {
-    throw new Error(generateUsage());
+    throw new Error(await generateUsage());
   }
   if (firstName.startsWith('-')) {
     throw new Error(`Invalid resource name "${firstName}": names cannot start with "-".`);
@@ -280,7 +283,7 @@ function parseGenerateArgs(argv) {
     targetDirectory
   };
 }
-function parseCommand(argv) {
+async function parseCommand(argv) {
   const [command] = argv;
   if (command === 'analyze') {
     return {
@@ -336,10 +339,16 @@ function parseCommand(argv) {
       command: 'inspect'
     };
   }
+  if (command === 'typegen') {
+    return {
+      argv: argv.slice(1),
+      command: 'typegen'
+    };
+  }
   return {
     argv,
     command: 'generate',
-    parsed: parseGenerateArgs(argv)
+    parsed: await parseGenerateArgs(argv)
   };
 }
 
@@ -363,7 +372,7 @@ function parseCommand(argv) {
  *
  * @param argv Argument vector to execute. Defaults to the current process arguments without the node/bin prefix.
  * @param runtime Optional runtime overrides shared by the top-level dispatcher and delegated commands.
- * @returns `0` when the command completes successfully, otherwise `1` after writing the error message to `stderr`.
+ * @returns `0` when the command completes successfully, otherwise the delegated command exit code.
  */
 export async function runCli(argv = process.argv.slice(2), runtime = {}) {
   const cwd = runtime.cwd ? resolve(runtime.cwd) : process.cwd();
@@ -379,6 +388,9 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
   try {
     if (commandArgv[0] === NODE_DEV_RUNNER_COMMAND || commandArgv[0] === DEV_RUNNER_COMMAND) {
       const runnerInvocation = parseDevRunnerInvocation(commandArgv);
+      const {
+        runNodeRestartRunner
+      } = await import('./dev-runner/node-restart-runner.js');
       return runNodeRestartRunner({
         appArgs: runnerInvocation.appArgs,
         env,
@@ -418,30 +430,48 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return 0;
       }
       if (topic === 'g' || topic === 'generate') {
-        stdout.write(`${generateUsage()}\n`);
+        stdout.write(`${await generateUsage()}\n`);
         return 0;
       }
       if (topic === 'doctor' || topic === 'info') {
+        const {
+          diagnosticsUsage
+        } = await import('./commands/diagnostics.js');
         stdout.write(`${diagnosticsUsage(topic)}\n`);
         return 0;
       }
       if (topic === 'analyze') {
+        const {
+          diagnosticsUsage
+        } = await import('./commands/diagnostics.js');
         stdout.write(`${diagnosticsUsage('analyze')}\n`);
         return 0;
       }
       if (topic === 'build' || topic === 'dev' || topic === 'start') {
+        const {
+          scriptUsage
+        } = await import('./commands/scripts.js');
         stdout.write(`${scriptUsage(topic)}\n`);
         return 0;
       }
       if (topic === 'add') {
+        const {
+          addUsage
+        } = await import('./commands/package-workflow.js');
         stdout.write(`${addUsage()}\n`);
         return 0;
       }
       if (topic === 'upgrade') {
+        const {
+          upgradeUsage
+        } = await import('./commands/package-workflow.js');
         stdout.write(`${upgradeUsage()}\n`);
         return 0;
       }
       if (topic === 'migrate') {
+        const {
+          migrateUsage
+        } = await import('./commands/migrate.js');
         stdout.write(`${migrateUsage()}\n`);
         return 0;
       }
@@ -449,6 +479,10 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         stdout.write(`${inspectUsage()}\n`);
         return 0;
       }
+      if (topic === 'typegen') {
+        stdout.write(`${typegenUsage()}\n`);
+        return 0;
+      }
       stdout.write(`${usage()}\n`);
       return 0;
     }
@@ -457,30 +491,48 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       return 0;
     }
     if ((commandArgv[0] === 'g' || commandArgv[0] === 'generate') && commandArgv.slice(1).some(isHelpFlag)) {
-      stdout.write(`${generateUsage()}\n`);
+      stdout.write(`${await generateUsage()}\n`);
       return 0;
     }
     if ((commandArgv[0] === 'doctor' || commandArgv[0] === 'info') && commandArgv.slice(1).some(isHelpFlag)) {
+      const {
+        diagnosticsUsage
+      } = await import('./commands/diagnostics.js');
       stdout.write(`${diagnosticsUsage(commandArgv[0])}\n`);
       return 0;
     }
     if (commandArgv[0] === 'analyze' && commandArgv.slice(1).some(isHelpFlag)) {
+      const {
+        diagnosticsUsage
+      } = await import('./commands/diagnostics.js');
       stdout.write(`${diagnosticsUsage('analyze')}\n`);
       return 0;
     }
     if ((commandArgv[0] === 'build' || commandArgv[0] === 'dev' || commandArgv[0] === 'start') && commandArgv.slice(1).some(isHelpFlag)) {
+      const {
+        scriptUsage
+      } = await import('./commands/scripts.js');
       stdout.write(`${scriptUsage(commandArgv[0])}\n`);
       return 0;
     }
     if (commandArgv[0] === 'add' && commandArgv.slice(1).some(isHelpFlag)) {
+      const {
+        addUsage
+      } = await import('./commands/package-workflow.js');
       stdout.write(`${addUsage()}\n`);
       return 0;
     }
     if (commandArgv[0] === 'upgrade' && commandArgv.slice(1).some(isHelpFlag)) {
+      const {
+        upgradeUsage
+      } = await import('./commands/package-workflow.js');
       stdout.write(`${upgradeUsage()}\n`);
       return 0;
     }
     if (commandArgv[0] === 'migrate' && commandArgv.slice(1).some(isHelpFlag)) {
+      const {
+        migrateUsage
+      } = await import('./commands/migrate.js');
       stdout.write(`${migrateUsage()}\n`);
       return 0;
     }
@@ -488,38 +540,78 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       stdout.write(`${inspectUsage()}\n`);
       return 0;
     }
-    const parsedCommand = parseCommand(commandArgv);
+    if (commandArgv[0] === 'typegen' && commandArgv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${typegenUsage()}\n`);
+      return 0;
+    }
+    const parsedCommand = await parseCommand(commandArgv);
     if (parsedCommand.command === 'analyze') {
+      const {
+        runAnalyzeCommand
+      } = await import('./commands/diagnostics.js');
       return runAnalyzeCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'add') {
+      const {
+        runAddCommand
+      } = await import('./commands/package-workflow.js');
       return runAddCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'doctor') {
+      const {
+        runDoctorCommand
+      } = await import('./commands/diagnostics.js');
       return runDoctorCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'info') {
+      const {
+        runInfoCommand
+      } = await import('./commands/diagnostics.js');
       return runInfoCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'build' || parsedCommand.command === 'dev' || parsedCommand.command === 'start') {
+      const {
+        runScriptCommand
+      } = await import('./commands/scripts.js');
       return await runScriptCommand(parsedCommand.command, parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'upgrade') {
+      const {
+        runUpgradeCommand
+      } = await import('./commands/package-workflow.js');
       return runUpgradeCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'new') {
+      const {
+        runNewCommand
+      } = await import('./commands/new.js');
       return runNewCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'migrate') {
+      const {
+        runMigrateCommand
+      } = await import('./commands/migrate.js');
       return runMigrateCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'inspect') {
+      const {
+        runInspectCommand
+      } = await import('./commands/inspect.js');
       return runInspectCommand(parsedCommand.argv, commandRuntime);
     }
+    if (parsedCommand.command === 'typegen') {
+      const {
+        runTypegenCommand
+      } = await import('./commands/typegen.js');
+      return runTypegenCommand(parsedCommand.argv, commandRuntime);
+    }
     if (parsedCommand.command !== 'generate') {
       throw new Error(usage());
     }
     const targetDirectory = resolve(cwd, parsedCommand.parsed.targetDirectory ?? resolveDefaultTargetDirectory(cwd));
+    const {
+      runGenerateCommand
+    } = await import('./commands/generate.js');
     const result = runGenerateCommand(parsedCommand.parsed.kind, parsedCommand.parsed.name, targetDirectory, parsedCommand.parsed.options);
     if (parsedCommand.parsed.options.dryRun) {
       stdout.write('Dry run: no files were written.\n');

package/dist/commands/diagnostics.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationLogger } from '@fluojs/runtime';
 type CliStream = {
     write(message: string): unknown;
 };
@@ -7,9 +8,43 @@ type DiagnosticRuntimeOptions = {
     fetchDistTags?: (packageName: string) => Promise<Record<string, string> | undefined>;
     stdout?: CliStream;
 };
+/**
+ * Creates the runtime logger used when a CLI command reserves stdout for an artifact.
+ *
+ * @param stderr Stream that receives human-readable runtime diagnostics.
+ * @returns A logger that preserves the default runtime diagnostic format on stderr.
+ */
+export declare function createCliDiagnosticsLogger(stderr: CliStream): ApplicationLogger;
+/**
+ * Returns usage text for a diagnostics command.
+ *
+ * @param command Diagnostics command whose usage text is requested.
+ * @returns Usage text for the selected command.
+ */
 export declare function diagnosticsUsage(command?: 'analyze' | 'doctor' | 'info'): string;
+/**
+ * Runs the doctor diagnostics command.
+ *
+ * @param argv Command arguments after `doctor`.
+ * @param runtime Runtime overrides for diagnostics output and lookup.
+ * @returns Process-style exit code from the command.
+ */
 export declare function runDoctorCommand(argv: string[], runtime?: DiagnosticRuntimeOptions): Promise<number>;
+/**
+ * Runs the info diagnostics command.
+ *
+ * @param argv Command arguments after `info`.
+ * @param runtime Runtime overrides for diagnostics output and lookup.
+ * @returns Process-style exit code from the command.
+ */
 export declare function runInfoCommand(argv: string[], runtime?: DiagnosticRuntimeOptions): Promise<number>;
+/**
+ * Runs the analyze diagnostics command.
+ *
+ * @param argv Command arguments after `analyze`.
+ * @param runtime Runtime overrides for diagnostics output and lookup.
+ * @returns Process-style exit code from the command.
+ */
 export declare function runAnalyzeCommand(argv: string[], runtime?: DiagnosticRuntimeOptions): Promise<number>;
 export {};
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/commands/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/commands/diagnostics.ts"],"names":[],"mappings":"AAKA,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACrF,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAuHF,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,SAAS,GAAG,QAAQ,GAAG,MAAiB,GAAG,MAAM,CAoB1F;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC9G;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5G;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB/G"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/commands/diagnostics.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACrF,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAQF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAsB/E;AAiHD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,SAAS,GAAG,QAAQ,GAAG,MAAiB,GAAG,MAAM,CAoB1F;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC9G;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5G;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB/G"}

package/dist/commands/diagnostics.js

@@ -5,6 +5,35 @@ import { fileURLToPath } from 'node:url';
 const DEFAULT_PACKAGE_NAME = '@fluojs/cli';
 const DEFAULT_REGISTRY_TIMEOUT_MS = 5_000;
 const EMPTY_ENV = {};
+
+/**
+ * Creates the runtime logger used when a CLI command reserves stdout for an artifact.
+ *
+ * @param stderr Stream that receives human-readable runtime diagnostics.
+ * @returns A logger that preserves the default runtime diagnostic format on stderr.
+ */
+export function createCliDiagnosticsLogger(stderr) {
+  const write = (level, message, context = 'fluo') => {
+    stderr.write(`[fluo] ${level} [${context}] ${message}\n`);
+  };
+  return {
+    debug(message, context = 'fluo') {
+      write('DEBUG', message, context);
+    },
+    error(message, error, context = 'fluo') {
+      write('ERROR', message, context);
+      if (error) {
+        stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+      }
+    },
+    log(message, context = 'fluo') {
+      write('LOG', message, context);
+    },
+    warn(message, context = 'fluo') {
+      write('WARN', message, context);
+    }
+  };
+}
 function isRecord(value) {
   return typeof value === 'object' && value !== null;
 }
@@ -100,12 +129,27 @@ function listScripts(manifest) {
   }
   return Object.keys(scripts).sort();
 }
+
+/**
+ * Returns usage text for a diagnostics command.
+ *
+ * @param command Diagnostics command whose usage text is requested.
+ * @returns Usage text for the selected command.
+ */
 export function diagnosticsUsage(command = 'doctor') {
   if (command === 'analyze') {
     return ['Usage: fluo analyze [options]', '', 'Summarize the current project and point to deeper inspect/report diagnostics.', '', 'Options', '  --help  Show help for the analyze command.'].join('\n');
   }
   return [`Usage: fluo ${command} [options]`, '', 'Print CLI, registry, update-cache, runtime, and project diagnostics.', '', 'Options', `  --help  Show help for the ${command} command.`].join('\n');
 }
+
+/**
+ * Runs the doctor diagnostics command.
+ *
+ * @param argv Command arguments after `doctor`.
+ * @param runtime Runtime overrides for diagnostics output and lookup.
+ * @returns Process-style exit code from the command.
+ */
 export async function runDoctorCommand(argv, runtime = {}) {
   if (argv.includes('--help') || argv.includes('-h')) {
     (runtime.stdout ?? process.stdout).write(`${diagnosticsUsage('doctor')}\n`);
@@ -135,6 +179,14 @@ export async function runDoctorCommand(argv, runtime = {}) {
   stdout.write(`  Project scripts: ${scripts.length > 0 ? scripts.join(', ') : 'none'}\n`);
   return 0;
 }
+
+/**
+ * Runs the info diagnostics command.
+ *
+ * @param argv Command arguments after `info`.
+ * @param runtime Runtime overrides for diagnostics output and lookup.
+ * @returns Process-style exit code from the command.
+ */
 export async function runInfoCommand(argv, runtime = {}) {
   if (argv.includes('--help') || argv.includes('-h')) {
     (runtime.stdout ?? process.stdout).write(`${diagnosticsUsage('info')}\n`);
@@ -142,6 +194,14 @@ export async function runInfoCommand(argv, runtime = {}) {
   }
   return runDoctorCommand(argv, runtime);
 }
+
+/**
+ * Runs the analyze diagnostics command.
+ *
+ * @param argv Command arguments after `analyze`.
+ * @param runtime Runtime overrides for diagnostics output and lookup.
+ * @returns Process-style exit code from the command.
+ */
 export async function runAnalyzeCommand(argv, runtime = {}) {
   if (argv.includes('--help') || argv.includes('-h')) {
     (runtime.stdout ?? process.stdout).write(`${diagnosticsUsage('analyze')}\n`);

package/dist/commands/inspect.d.ts

@@ -1,4 +1,4 @@
-import { type PlatformShellSnapshot } from '@fluojs/runtime';
+import type { PlatformShellSnapshot } from '@fluojs/runtime';
 type CliStream = {
     write(message: string): unknown;
 };
@@ -11,6 +11,8 @@ type ReadableStream = {
 };
 type StudioMermaidRenderer = (snapshot: PlatformShellSnapshot) => string;
 type StudioMermaidRendererLoader = (cwd: string) => Promise<StudioMermaidRenderer | undefined>;
+type RuntimeInspectionModule = Pick<typeof import('@fluojs/runtime'), 'createRuntimeInspectionSnapshot' | 'FluoFactory' | 'PLATFORM_SHELL'>;
+type RuntimeInspectionModuleLoader = (cwd: string) => Promise<RuntimeInspectionModule | undefined>;
 /**
  * Runtime options for the inspect command when used programmatically.
  */
@@ -21,6 +23,8 @@ export interface InspectCommandRuntimeOptions {
     cwd?: string;
     /** Force or disable interactive prompts for optional Studio guidance. */
     interactive?: boolean;
+    /** Optional test/editor hook for resolving the runtime inspection dependency. */
+    loadRuntimeInspectionModule?: RuntimeInspectionModuleLoader;
     /** Optional test/editor hook for resolving Studio's Mermaid renderer. */
     loadStudioMermaidRenderer?: StudioMermaidRendererLoader;
     /** Custom prompt implementation used only when Studio is missing for Mermaid output. */

package/dist/commands/inspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAMA,OAAO,EAOL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAMzB,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,CAAC;AAEzE,KAAK,2BAA2B,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;AAE/F;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,yBAAyB,CAAC,EAAE,2BAA2B,CAAC;IACxD,wFAAwF;IACxF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAoSD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDnH"}
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAKV,qBAAqB,EAEtB,MAAM,iBAAiB,CAAC;AAQzB,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,CAAC;AAEzE,KAAK,2BAA2B,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;AAE/F,KAAK,uBAAuB,GAAG,IAAI,CACjC,cAAc,iBAAiB,CAAC,EAChC,iCAAiC,GAAG,aAAa,GAAG,gBAAgB,CACrE,CAAC;AAEF,KAAK,6BAA6B,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iFAAiF;IACjF,2BAA2B,CAAC,EAAE,6BAA6B,CAAC;IAC5D,yEAAyE;IACzE,yBAAyB,CAAC,EAAE,2BAA2B,CAAC;IACxD,wFAAwF;IACxF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AA2WD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DnH"}