@fluojs/cli 1.1.0 → 3.0.0

package/dist/commands/generate.js

@@ -1,214 +1 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, normalize, relative, resolve, sep } from 'node:path';
-import { findGeneratorDefinition } from '../generators/manifest.js';
-import { ensureModuleImport, generateModuleFiles, registerInModule } from '../generators/module.js';
-import { toKebabCase, toPascalCase, toPlural } from '../generators/utils.js';
-function writeFileIfChanged(filePath, content) {
-  if (existsSync(filePath) && readFileSync(filePath, 'utf8') === content) {
-    return false;
-  }
-  writeFileSync(filePath, content, 'utf8');
-  return true;
-}
-
-/** Describes how one generated artifact would interact with the workspace. */
-
-/** One path-level action reported by generate dry-run previews and structured results. */
-
-function planFileWrite(filePath, content, options) {
-  if (!existsSync(filePath)) {
-    return {
-      action: 'create',
-      path: filePath
-    };
-  }
-  if (!options.force) {
-    return {
-      action: 'skip',
-      path: filePath
-    };
-  }
-  if (readFileSync(filePath, 'utf8') === content) {
-    return {
-      action: 'unchanged',
-      path: filePath
-    };
-  }
-  return {
-    action: 'overwrite',
-    path: filePath
-  };
-}
-function planModuleWrite(modulePath, content) {
-  if (!existsSync(modulePath)) {
-    return {
-      action: 'module-create',
-      path: modulePath
-    };
-  }
-  if (readFileSync(modulePath, 'utf8') === content) {
-    return {
-      action: 'module-unchanged',
-      path: modulePath
-    };
-  }
-  return {
-    action: 'module-update',
-    path: modulePath
-  };
-}
-function createGeneratorOptions(kind, domainDirectory, kebab, options, resolvedBase) {
-  return {
-    ...options,
-    e2eRootModuleImport: options.e2eRootModuleImport ?? (kind === 'e2e' ? resolveE2eRootModuleImport(domainDirectory, resolvedBase) : undefined),
-    hasRepo: options.hasRepo ?? (kind === 'service' ? existsSync(join(domainDirectory, `${kebab}.repo.ts`)) : undefined),
-    hasService: options.hasService ?? (kind === 'controller' ? existsSync(join(domainDirectory, `${kebab}.service.ts`)) : undefined)
-  };
-}
-function toImportSpecifier(path) {
-  const normalized = path.split(sep).join('/');
-  return normalized.startsWith('.') ? normalized : `./${normalized}`;
-}
-function resolveE2eRootModuleImport(domainDirectory, resolvedBase) {
-  return toImportSpecifier(relative(domainDirectory, join(resolvedBase, 'app')));
-}
-function resolveDomainDirectory(kind, resolvedBase, kebab, options) {
-  if (kind === 'e2e') {
-    return basename(resolvedBase) === 'src' ? join(dirname(resolvedBase), 'test') : join(resolvedBase, 'test');
-  }
-  if (kind === 'request-dto' && options.targetFeature !== undefined) {
-    const normalizedFeature = options.targetFeature.trim();
-    const featureKebab = assertValidResourceName(normalizedFeature);
-    const featureDirectory = /^[A-Z]/u.test(normalizedFeature) ? toPlural(featureKebab) : featureKebab;
-    return join(resolvedBase, featureDirectory);
-  }
-  return join(resolvedBase, toPlural(kebab));
-}
-function assertValidResourceName(name) {
-  const kebab = toKebabCase(name);
-  if (name.trim().length === 0) {
-    throw new Error('Invalid resource name: name must not be empty.');
-  }
-  if (kebab !== normalize(kebab) || kebab.includes('/') || kebab.includes('\\') || kebab.includes('..')) {
-    throw new Error(`Invalid resource name "${name}": must not contain path separators or traversal sequences.`);
-  }
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(kebab)) {
-    throw new Error(`Invalid resource name "${name}": use letters, numbers, spaces, underscores, or hyphens only.`);
-  }
-  return kebab;
-}
-function resolveModulePath(domainDirectory, name) {
-  const kebab = toKebabCase(name);
-  return join(domainDirectory, `${kebab}.module.ts`);
-}
-function readOrCreateModuleSource(modulePath, name) {
-  if (existsSync(modulePath)) {
-    return readFileSync(modulePath, 'utf8');
-  }
-  const [moduleFile] = generateModuleFiles(name);
-  if (!moduleFile) {
-    throw new Error(`Unable to generate module file for resource "${name}".`);
-  }
-  return moduleFile.content;
-}
-function buildUpdatedModuleSource(moduleSource, arrayKey, className, importPath) {
-  let source = moduleSource;
-  source = ensureModuleImport(source, className, importPath);
-  source = registerInModule(source, arrayKey, className);
-  return source;
-}
-function prepareModuleUpdate(domainDirectory, normalizedName, kind, classSuffix, arrayKey) {
-  const kebab = toKebabCase(normalizedName);
-  const modulePath = resolveModulePath(domainDirectory, normalizedName);
-  const className = `${toPascalCase(normalizedName)}${classSuffix}`;
-  const importPath = `${kebab}.${kind}`;
-  const moduleSource = readOrCreateModuleSource(modulePath, normalizedName);
-  return {
-    modulePath,
-    source: buildUpdatedModuleSource(moduleSource, arrayKey, className, importPath)
-  };
-}
-
-/**
- * Structured result returned by {@link runGenerateCommand} for tooling-friendly automation.
- *
- * `generatedFiles` only includes files whose on-disk content changed during the command.
- * `moduleRegistered` reports whether the target schematic participates in automatic module wiring,
- * even when the target module file was already up to date.
- */
-
-/**
- * Generates one CLI schematic into a source directory and returns structured wiring metadata.
- *
- * The command keeps generation idempotent where possible: unchanged files are not rewritten, and
- * auto-registered schematics reuse an existing module file when it already contains the required import
- * and registration entry.
- *
- * @example
- * ```ts
- * const result = runGenerateCommand('service', 'Post', './src');
- *
- * console.log(result.wiringBehavior);
- * console.log(result.nextStepHint);
- * ```
- *
- * @param kind Generator kind to execute.
- * @param name Resource name supplied by the caller before normalization.
- * @param baseDirectory Source directory that should receive the generated domain folder.
- * @param options Optional generation flags that control overwrites, request DTO feature placement, and sibling-aware templates.
- * @returns Structured file and wiring metadata for the completed generation run.
- * @throws {Error} When the resource name is invalid, the generator kind is unknown, or the target module source cannot be updated safely.
- */
-export function runGenerateCommand(kind, name, baseDirectory, options = {}) {
-  const normalizedName = name.trim();
-  const kebab = assertValidResourceName(normalizedName);
-  const generator = findGeneratorDefinition(kind);
-  const resolvedBase = resolve(baseDirectory);
-  const domainDirectory = resolveDomainDirectory(kind, resolvedBase, kebab, options);
-  const generatorOptions = createGeneratorOptions(kind, domainDirectory, kebab, options, resolvedBase);
-  const files = generator.factory(normalizedName, generatorOptions);
-  const moduleRegistration = 'moduleRegistration' in generator ? generator.moduleRegistration : undefined;
-  const moduleUpdate = moduleRegistration ? prepareModuleUpdate(domainDirectory, normalizedName, kind, moduleRegistration.classSuffix, moduleRegistration.arrayKey) : undefined;
-  const plannedFiles = files.map(file => planFileWrite(join(domainDirectory, file.path), file.content, options));
-  const modulePlan = moduleUpdate ? planModuleWrite(moduleUpdate.modulePath, moduleUpdate.source) : undefined;
-  if (options.dryRun) {
-    return {
-      generatedFiles: [],
-      moduleRegistered: moduleUpdate !== undefined,
-      modulePath: moduleUpdate?.modulePath,
-      nextStepHint: generator.nextStepHint,
-      plannedFiles: modulePlan ? [...plannedFiles, modulePlan] : plannedFiles,
-      wiringBehavior: generator.wiringBehavior
-    };
-  }
-  mkdirSync(domainDirectory, {
-    recursive: true
-  });
-  const writtenPaths = files.map(file => {
-    const filePath = join(domainDirectory, file.path);
-    if (!options.force && existsSync(filePath)) {
-      return null;
-    }
-    return writeFileIfChanged(filePath, file.content) ? filePath : null;
-  }).filter(filePath => filePath !== null);
-  let moduleRegistered = false;
-  let resolvedModulePath;
-  if (moduleUpdate && writeFileIfChanged(moduleUpdate.modulePath, moduleUpdate.source)) {
-    moduleRegistered = true;
-    resolvedModulePath = moduleUpdate.modulePath;
-    if (!writtenPaths.includes(moduleUpdate.modulePath)) {
-      writtenPaths.push(moduleUpdate.modulePath);
-    }
-  } else if (moduleUpdate) {
-    moduleRegistered = true;
-    resolvedModulePath = moduleUpdate.modulePath;
-  }
-  return {
-    generatedFiles: writtenPaths,
-    moduleRegistered: moduleRegistered,
-    modulePath: resolvedModulePath,
-    nextStepHint: generator.nextStepHint,
-    plannedFiles: modulePlan ? [...plannedFiles, modulePlan] : plannedFiles,
-    wiringBehavior: generator.wiringBehavior
-  };
-}
+export { runGenerateCommand } from '../generate-command.js';

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. */
@@ -32,12 +36,6 @@ export interface InspectCommandRuntimeOptions {
     /** Custom stream for standard output. */
     stdout?: CliStream;
 }
-/**
- * Returns the usage information string for the inspect command.
- *
- * @returns Formatted help text including usage and options.
- */
-export declare function inspectUsage(): string;
 /**
  * Executes the inspect command to visualize the application module graph.
  *

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;AAmFD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAarC;AA+PD;;;;;;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"}

package/dist/commands/inspect.js

@@ -1,70 +1,27 @@
+import { existsSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import * as clack from '@clack/prompts';
-import { FluoFactory, PLATFORM_SHELL } from '@fluojs/runtime';
 import { tsImport } from 'tsx/esm/api';
-import { renderAliasList, renderHelpTable } from '../help.js';
 import { CliPromptCancelledError, isCliPromptCancelledError } from '../prompt-cancel.js';
+import { inspectUsage } from '../usage.js';
+import { createCliDiagnosticsLogger } from './diagnostics.js';
+import { assertOutputDoesNotAliasModule } from './output-path-safety.js';
 
 /**
  * Runtime options for the inspect command when used programmatically.
  */
 
-const INSPECT_OPTION_HELP = [{
-  aliases: [],
-  description: 'Emit the runtime platform snapshot/diagnostics payload as JSON (default when no output mode is selected).',
-  option: '--json'
-}, {
-  aliases: [],
-  description: 'Emit a Mermaid graph through the optional @fluojs/studio rendering contract.',
-  option: '--mermaid'
-}, {
-  aliases: [],
-  description: 'Include bootstrap timing diagnostics next to JSON inspect output.',
-  option: '--timing'
-}, {
-  aliases: [],
-  description: 'Emit a CI-friendly JSON report with summary, snapshot, diagnostics, and timing.',
-  option: '--report'
-}, {
-  aliases: [],
-  description: 'Write the selected inspect payload to a file instead of stdout.',
-  option: '--output <path>'
-}, {
-  aliases: [],
-  description: 'Select the exported module symbol name (default: AppModule).',
-  option: '--export <name>'
-}, {
-  aliases: ['-h'],
-  description: 'Show help for the inspect command.',
-  option: '--help'
-}];
 const STUDIO_CONTRACT_ENTRYPOINT = '@fluojs/studio/contracts';
+const RUNTIME_ENTRYPOINT = '@fluojs/runtime';
 const TYPESCRIPT_MODULE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const RUNTIME_MISSING_MESSAGE = ['Runtime inspection requires @fluojs/runtime, but it is not resolvable from this project.', 'Install a version whose Node.js engine supports your current Node.js version (for example: pnpm add -D @fluojs/runtime) and rerun fluo inspect.'].join('\n');
 const STUDIO_MISSING_MESSAGE = ['Mermaid graph rendering is owned by @fluojs/studio, but @fluojs/studio is not resolvable from this project.', 'Install @fluojs/studio explicitly (for example: pnpm add -D @fluojs/studio) and rerun fluo inspect --mermaid.'].join('\n');
+const CLACK_MISSING_MESSAGE = ['Interactive inspect guidance requires @clack/prompts, but it is not resolvable from this installation.', 'Install a version whose Node.js engine supports your current Node.js version and rerun fluo inspect.'].join('\n');
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
-
-/**
- * Returns the usage information string for the inspect command.
- *
- * @returns Formatted help text including usage and options.
- */
-export function inspectUsage() {
-  return ['Usage: fluo inspect <module-path> [options]', '', 'Options', renderHelpTable(INSPECT_OPTION_HELP, [{
-    header: 'Option',
-    render: entry => entry.option
-  }, {
-    header: 'Aliases',
-    render: entry => renderAliasList(entry.aliases)
-  }, {
-    header: 'Description',
-    render: entry => entry.description
-  }]), '', 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/quick-start.md'].join('\n');
-}
 function parseInspectArgs(argv) {
   let modulePath;
   let exportName = 'AppModule';
@@ -82,6 +39,18 @@ function parseInspectArgs(argv) {
       json = true;
       continue;
     }
+    if (option === '--format') {
+      const format = argv[index + 1];
+      if (!format || format.startsWith('-')) {
+        throw new Error('Expected --format to have a value of "json".');
+      }
+      if (format !== 'json') {
+        throw new Error(`Invalid --format value "${format}". Use "json".`);
+      }
+      json = true;
+      index += 1;
+      continue;
+    }
     if (option === '--mermaid') {
       mermaid = true;
       continue;
@@ -152,6 +121,13 @@ function resolveRootModule(exportedValue, exportName) {
 async function importInspectModule(modulePath) {
   const moduleUrl = pathToFileURL(modulePath).href;
   if (TYPESCRIPT_MODULE_EXTENSIONS.has(extname(modulePath))) {
+    const adjacentTsconfigPath = resolve(dirname(modulePath), 'tsconfig.json');
+    if (existsSync(adjacentTsconfigPath)) {
+      return tsImport(moduleUrl, {
+        parentURL: import.meta.url,
+        tsconfig: adjacentTsconfigPath
+      });
+    }
     return tsImport(moduleUrl, import.meta.url);
   }
   return import(moduleUrl);
@@ -192,18 +168,26 @@ function stringifySnapshotWithTiming(snapshot, timing) {
     timing: timing ?? createEmptyTimingDiagnostics()
   }, null, 2);
 }
-async function emitInspectPayload(payload, parsed, cwd, stdout) {
-  if (!parsed.outputPath) {
+async function emitInspectPayload(payload, outputPath, stdout) {
+  if (!outputPath) {
     stdout.write(`${payload}\n`);
     return;
   }
-  const outputPath = resolve(cwd, parsed.outputPath);
   await mkdir(dirname(outputPath), {
     recursive: true
   });
   await writeFile(outputPath, `${payload}\n`, 'utf8');
 }
-function createInspectPrompter() {
+async function createInspectPrompter() {
+  let clack;
+  try {
+    clack = await import('@clack/prompts');
+  } catch (error) {
+    if (isModuleNotFoundError(error)) {
+      throw new Error(CLACK_MISSING_MESSAGE);
+    }
+    throw error;
+  }
   return {
     async confirm(message, defaultValue) {
       const result = await clack.confirm({
@@ -227,6 +211,29 @@ function shouldPromptForStudio(runtime) {
   }
   return runtime.stdout === undefined && runtime.stderr === undefined && (runtime.interactive ?? true) && Boolean(runtime.stdin?.isTTY ?? process.stdin.isTTY);
 }
+function isModuleNotFoundError(error) {
+  const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+  return code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND';
+}
+async function loadRuntimeInspectionModule(cwd) {
+  const resolver = createRequire(resolve(cwd, 'package.json'));
+  try {
+    const resolvedEntrypoint = resolver.resolve(RUNTIME_ENTRYPOINT);
+    return await import(pathToFileURL(resolvedEntrypoint).href);
+  } catch (error) {
+    if (isModuleNotFoundError(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+async function resolveRuntimeInspectionModule(cwd, runtime) {
+  const runtimeModule = await (runtime.loadRuntimeInspectionModule ?? loadRuntimeInspectionModule)(cwd);
+  if (!runtimeModule) {
+    throw new Error(RUNTIME_MISSING_MESSAGE);
+  }
+  return runtimeModule;
+}
 async function loadStudioMermaidRenderer(cwd) {
   const resolvers = [createRequire(resolve(cwd, 'package.json')), createRequire(import.meta.url)];
   for (const resolver of resolvers) {
@@ -238,8 +245,7 @@ async function loadStudioMermaidRenderer(cwd) {
       }
       return importedContract.renderMermaid;
     } catch (error) {
-      const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
-      if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND') {
+      if (!isModuleNotFoundError(error)) {
         throw error;
       }
     }
@@ -254,7 +260,7 @@ async function resolveStudioMermaidRenderer(cwd, runtime) {
   if (!shouldPromptForStudio(runtime)) {
     throw new Error(STUDIO_MISSING_MESSAGE);
   }
-  const prompt = runtime.prompt ?? createInspectPrompter();
+  const prompt = runtime.prompt ?? (await createInspectPrompter());
   try {
     const approvedInstall = await prompt.confirm('Install @fluojs/studio before rendering Mermaid output?', false);
     if (!approvedInstall) {
@@ -284,28 +290,42 @@ export async function runInspectCommand(argv, runtime = {}) {
     }
     const parsed = parseInspectArgs(argv);
     const modulePath = resolve(cwd, parsed.modulePath);
+    const outputPath = parsed.outputPath === undefined ? undefined : resolve(cwd, parsed.outputPath);
+    if (outputPath !== undefined) {
+      await assertOutputDoesNotAliasModule(modulePath, outputPath);
+    }
+    const {
+      createRuntimeInspectionSnapshot,
+      FluoFactory,
+      PLATFORM_SHELL
+    } = await resolveRuntimeInspectionModule(cwd, runtime);
     const importedModule = await importInspectModule(modulePath);
     const rootModule = resolveRootModule(importedModule[parsed.exportName], parsed.exportName);
-    const context = await FluoFactory.createApplicationContext(rootModule, {
+    const application = await FluoFactory.create(rootModule, {
       diagnostics: parsed.timing || parsed.report ? {
         timing: true
-      } : undefined
+      } : undefined,
+      ...(parsed.json || parsed.report ? {
+        logger: createCliDiagnosticsLogger(stderr)
+      } : {})
     });
     try {
-      const platformShell = await context.get(PLATFORM_SHELL);
-      const snapshot = await platformShell.snapshot();
+      const platformShell = await application.get(PLATFORM_SHELL);
+      const platformSnapshot = await platformShell.snapshot();
+      const routes = application.dispatcher.describeRoutes?.() ?? [];
+      const snapshot = createRuntimeInspectionSnapshot(platformSnapshot, routes);
       if (parsed.json) {
-        await emitInspectPayload(parsed.timing ? stringifySnapshotWithTiming(snapshot, context.bootstrapTiming) : stringifySnapshot(snapshot), parsed, cwd, stdout);
+        await emitInspectPayload(parsed.timing ? stringifySnapshotWithTiming(snapshot, application.bootstrapTiming) : stringifySnapshot(snapshot), outputPath, stdout);
       }
       if (parsed.report) {
-        await emitInspectPayload(JSON.stringify(createInspectReport(snapshot, context.bootstrapTiming), null, 2), parsed, cwd, stdout);
+        await emitInspectPayload(JSON.stringify(createInspectReport(snapshot, application.bootstrapTiming), null, 2), outputPath, stdout);
       }
       if (parsed.mermaid) {
         const renderMermaid = await resolveStudioMermaidRenderer(cwd, runtime);
-        await emitInspectPayload(renderMermaid(snapshot), parsed, cwd, stdout);
+        await emitInspectPayload(renderMermaid(snapshot), outputPath, stdout);
       }
     } finally {
-      await context.close();
+      await application.close();
     }
     return 0;
   } catch (error) {

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAaA,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AA4KD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAgBrC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEnH"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAgBA,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAqLD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAgBrC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAyEnH"}

package/dist/commands/migrate.js

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path';
 import { renderAliasList, renderHelpTable } from '../help.js';
-import { MIGRATION_TRANSFORMS, getWarningCategoryLabel, groupWarningsByCategory, renderTransformList, runNestJsMigration } from '../transforms/nestjs-migrate.js';
+import { getWarningCategoryLabel, groupWarningsByCategory, MIGRATION_TRANSFORMS, renderTransformList, runNestJsMigration } from '../transforms/nestjs-migrate.js';
+import { MIGRATION_TRANSFORM_CLI_TOKENS, parseMigrationTransformList } from './migration-transform-tokens.js';
 
 /**
  * Runtime configuration for the migrate command.
@@ -16,12 +17,16 @@ const MIGRATE_OPTION_HELP = [{
   option: '--json'
 }, {
   aliases: [],
-  description: `Run only selected transforms. Available: ${MIGRATION_TRANSFORMS.join(', ')}.`,
+  description: `Run only selected transforms. Available: ${MIGRATION_TRANSFORM_CLI_TOKENS.join(', ')}.`,
   option: '--only <comma-list>'
 }, {
   aliases: [],
-  description: `Skip selected transforms. Available: ${MIGRATION_TRANSFORMS.join(', ')}.`,
+  description: `Skip selected transforms. Available: ${MIGRATION_TRANSFORM_CLI_TOKENS.join(', ')}.`,
   option: '--skip <comma-list>'
+}, {
+  aliases: [],
+  description: 'Select the HTTP platform for bootstrap rewrites. Required for automatic bootstrap migration; supported: express.',
+  option: '--platform <name>'
 }, {
   aliases: ['-h'],
   description: 'Show help for the migrate command.',
@@ -30,22 +35,12 @@ const MIGRATE_OPTION_HELP = [{
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
-function parseTransformList(rawValue, optionName) {
-  const values = rawValue.split(',').map(value => value.trim()).filter(value => value.length > 0);
-  if (values.length === 0) {
-    throw new Error(`${optionName} requires a non-empty comma-separated transform list.`);
-  }
-  const invalid = values.filter(value => !MIGRATION_TRANSFORMS.includes(value));
-  if (invalid.length > 0) {
-    throw new Error(`Unknown transform(s): ${invalid.join(', ')}. Available transforms: ${MIGRATION_TRANSFORMS.join(', ')}.`);
-  }
-  return values;
-}
 function parseArgs(argv) {
   let pathArgument;
   let apply = false;
   let json = false;
   let onlyTransforms;
+  let platform;
   let skipTransforms = [];
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -65,7 +60,7 @@ function parseArgs(argv) {
       if (!rawValue || rawValue.startsWith('-')) {
         throw new Error(`Expected ${arg} to have a comma-separated value.`);
       }
-      const parsed = parseTransformList(rawValue, arg);
+      const parsed = parseMigrationTransformList(rawValue, arg);
       if (arg === '--only') {
         if (onlyTransforms) {
           throw new Error('Duplicate --only option.');
@@ -77,6 +72,21 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (arg === '--platform') {
+      const rawValue = argv[index + 1];
+      if (!rawValue || rawValue.startsWith('-')) {
+        throw new Error('Expected --platform to have a platform name.');
+      }
+      if (platform) {
+        throw new Error('Duplicate --platform option.');
+      }
+      if (rawValue !== 'express') {
+        throw new Error(`Unsupported bootstrap platform: ${rawValue}. Supported platform: express.`);
+      }
+      platform = rawValue;
+      index += 1;
+      continue;
+    }
     if (arg.startsWith('-')) {
       throw new Error(`Unknown option for migrate command: ${arg}`);
     }
@@ -99,6 +109,7 @@ function parseArgs(argv) {
     apply,
     json,
     path: pathArgument,
+    platform,
     transforms: enabled
   };
 }
@@ -166,6 +177,7 @@ export async function runMigrateCommand(argv, runtime = {}) {
     const transforms = [...parsed.transforms];
     const report = runNestJsMigration({
       apply: parsed.apply,
+      bootstrapPlatform: parsed.platform,
       enabledTransforms: parsed.transforms,
       targetPath
     });

package/dist/commands/migration-transform-tokens.d.ts

@@ -0,0 +1,15 @@
+import { type MigrationTransformKind } from '../transforms/nestjs-migrate.js';
+/**
+ * Provides canonical migration transform tokens accepted by CLI options.
+ */
+export declare const MIGRATION_TRANSFORM_CLI_TOKENS: readonly ["imports", "inject-params", "scope", "bootstrap", "tests", "tsconfig"];
+/**
+ * Parse canonical or legacy migration transform tokens from one CLI option.
+ *
+ * @param rawValue Comma-separated transform tokens passed to the CLI.
+ * @param optionName CLI option that supplied the transform tokens.
+ * @returns Canonical migration transform kinds.
+ * @throws When the option has no tokens or includes an unsupported token.
+ */
+export declare function parseMigrationTransformList(rawValue: string, optionName: '--only' | '--skip'): MigrationTransformKind[];
+//# sourceMappingURL=migration-transform-tokens.d.ts.map

package/dist/commands/migration-transform-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-transform-tokens.d.ts","sourceRoot":"","sources":["../../src/commands/migration-transform-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEpG;;GAEG;AACH,eAAO,MAAM,8BAA8B,kFAAmF,CAAC;AAS/H;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAC9B,sBAAsB,EAAE,CA2B1B"}

package/dist/commands/migration-transform-tokens.js

@@ -0,0 +1,41 @@
+import { MIGRATION_TRANSFORMS } from '../transforms/nestjs-migrate.js';
+
+/**
+ * Provides canonical migration transform tokens accepted by CLI options.
+ */
+export const MIGRATION_TRANSFORM_CLI_TOKENS = ['imports', 'inject-params', 'scope', 'bootstrap', 'tests', 'tsconfig'];
+const MIGRATION_TRANSFORM_ALIASES = {
+  'inject-params': 'injectable',
+  injectable: 'injectable',
+  tests: 'testing',
+  testing: 'testing'
+};
+
+/**
+ * Parse canonical or legacy migration transform tokens from one CLI option.
+ *
+ * @param rawValue Comma-separated transform tokens passed to the CLI.
+ * @param optionName CLI option that supplied the transform tokens.
+ * @returns Canonical migration transform kinds.
+ * @throws When the option has no tokens or includes an unsupported token.
+ */
+export function parseMigrationTransformList(rawValue, optionName) {
+  const values = rawValue.split(',').map(value => value.trim()).filter(value => value.length > 0);
+  if (values.length === 0) {
+    throw new Error(`${optionName} requires a non-empty comma-separated transform list.`);
+  }
+  const transforms = [];
+  const invalid = [];
+  for (const value of values) {
+    const transform = MIGRATION_TRANSFORMS.find(candidate => candidate === value) ?? (Object.hasOwn(MIGRATION_TRANSFORM_ALIASES, value) ? MIGRATION_TRANSFORM_ALIASES[value] : undefined);
+    if (transform) {
+      transforms.push(transform);
+    } else {
+      invalid.push(value);
+    }
+  }
+  if (invalid.length > 0) {
+    throw new Error(`Unknown transform(s): ${invalid.join(', ')}. Available transforms: ${MIGRATION_TRANSFORM_CLI_TOKENS.join(', ')}.`);
+  }
+  return transforms;
+}