@fluojs/cli 1.0.0-beta.1

package/dist/commands/generate.d.ts

@@ -0,0 +1,40 @@
+import type { GenerateOptions, GeneratorKind } from '../types.js';
+import type { GeneratorManifestEntry } from '../generators/manifest.js';
+/**
+ * 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.
+ */
+export type GenerateResult = {
+    generatedFiles: string[];
+    moduleRegistered: boolean;
+    modulePath: string | undefined;
+    nextStepHint: string;
+    wiringBehavior: GeneratorManifestEntry['wiringBehavior'];
+};
+/**
+ * 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 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 declare function runGenerateCommand(kind: GeneratorKind, name: string, baseDirectory: string, options?: GenerateOptions): GenerateResult;
+//# sourceMappingURL=generate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,2BAA2B,CAAC;AA+FxF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAiD1I"}

package/dist/commands/generate.js

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, normalize, resolve } 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;
+}
+function createGeneratorOptions(kind, domainDirectory, kebab, options) {
+  return {
+    ...options,
+    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 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 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 = join(resolvedBase, toPlural(kebab));
+  const generatorOptions = createGeneratorOptions(kind, domainDirectory, kebab, options);
+  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;
+  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,
+    wiringBehavior: generator.wiringBehavior
+  };
+}

package/dist/commands/inspect.d.ts

@@ -0,0 +1,30 @@
+type CliStream = {
+    write(message: string): unknown;
+};
+/**
+ * Runtime options for the inspect command when used programmatically.
+ */
+export interface InspectCommandRuntimeOptions {
+    /** Current working directory for module resolution. */
+    cwd?: string;
+    /** Custom stream for error output. */
+    stderr?: CliStream;
+    /** 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.
+ *
+ * @param argv Command line arguments.
+ * @param runtime Optional custom runtime configuration for output streams and working directory.
+ * @returns Exit code (0 for success, 1 for failure).
+ */
+export declare function runInspectCommand(argv: string[], runtime?: InspectCommandRuntimeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=inspect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAcA,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAgDD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAarC;AA8ID;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEnH"}

package/dist/commands/inspect.js

@@ -0,0 +1,221 @@
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { FluoFactory, PLATFORM_SHELL } from '@fluojs/runtime';
+import { renderAliasList, renderHelpTable } from '../help.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 platform component dependency chains as a Mermaid diagram.',
+  option: '--mermaid'
+}, {
+  aliases: [],
+  description: 'Bootstrap the application context and emit versioned timing diagnostics.',
+  option: '--timing'
+}, {
+  aliases: [],
+  description: 'Select the exported module symbol name (default: AppModule).',
+  option: '--export <name>'
+}, {
+  aliases: ['-h'],
+  description: 'Show help for the inspect command.',
+  option: '--help'
+}];
+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';
+  let json = false;
+  let mermaid = false;
+  let timing = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const option = argv[index];
+    if (!option) {
+      continue;
+    }
+    if (option === '--json') {
+      json = true;
+      continue;
+    }
+    if (option === '--mermaid') {
+      mermaid = true;
+      continue;
+    }
+    if (option === '--timing') {
+      timing = true;
+      continue;
+    }
+    if (option === '--export') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('Expected --export to have a symbol name value.');
+      }
+      exportName = next;
+      index += 1;
+      continue;
+    }
+    if (option.startsWith('-')) {
+      throw new Error(`Unknown option for inspect command: ${option}`);
+    }
+    if (modulePath) {
+      throw new Error(`Unexpected extra positional argument: ${option}`);
+    }
+    modulePath = option;
+  }
+  if (!modulePath) {
+    throw new Error(inspectUsage());
+  }
+  if (!json && !mermaid && !timing) {
+    json = true;
+  }
+  const selectedModes = [json, mermaid, timing].filter(Boolean).length;
+  if (selectedModes > 1) {
+    throw new Error('Choose only one inspect output mode: --json, --mermaid, or --timing.');
+  }
+  return {
+    exportName,
+    json,
+    mermaid,
+    modulePath,
+    timing
+  };
+}
+function resolveRootModule(exportedValue, exportName) {
+  if (typeof exportedValue !== 'function') {
+    throw new Error(`Export "${exportName}" is not a module class constructor.`);
+  }
+  return exportedValue;
+}
+function stringifyTiming(timing) {
+  const value = timing ?? {
+    phases: [],
+    totalMs: 0,
+    version: 1
+  };
+  return JSON.stringify(value, null, 2);
+}
+function stringifySnapshot(snapshot) {
+  return JSON.stringify(snapshot, null, 2);
+}
+function renderPlatformSnapshotMermaid(snapshot) {
+  const lines = ['graph TD'];
+  if (snapshot.components.length === 0) {
+    lines.push('  EMPTY["No registered platform components"]');
+    return lines.join('\n');
+  }
+  const nodeByComponentId = new Map();
+  for (const [index, component] of snapshot.components.entries()) {
+    const nodeId = `C${String(index + 1)}`;
+    nodeByComponentId.set(component.id, nodeId);
+    const summary = [component.id, `kind: ${component.kind}`, `state: ${component.state}`, `readiness: ${component.readiness.status}`, `health: ${component.health.status}`].join('\\n');
+    lines.push(`  ${nodeId}["${summary}"]`);
+  }
+  for (const component of snapshot.components) {
+    const from = nodeByComponentId.get(component.id);
+    if (!from) {
+      continue;
+    }
+    for (const dependency of component.dependencies) {
+      const to = nodeByComponentId.get(dependency);
+      if (!to) {
+        continue;
+      }
+      lines.push(`  ${from} --> ${to}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Executes the inspect command to visualize the application module graph.
+ *
+ * @param argv Command line arguments.
+ * @param runtime Optional custom runtime configuration for output streams and working directory.
+ * @returns Exit code (0 for success, 1 for failure).
+ */
+export async function runInspectCommand(argv, runtime = {}) {
+  const stdout = runtime.stdout ?? process.stdout;
+  const stderr = runtime.stderr ?? process.stderr;
+  const cwd = runtime.cwd ?? process.cwd();
+  try {
+    if (argv.some(isHelpFlag)) {
+      stdout.write(`${inspectUsage()}\n`);
+      return 0;
+    }
+    const parsed = parseInspectArgs(argv);
+    const modulePath = resolve(cwd, parsed.modulePath);
+    const importedModule = await import(pathToFileURL(modulePath).href);
+    const rootModule = resolveRootModule(importedModule[parsed.exportName], parsed.exportName);
+    if (parsed.timing) {
+      const context = await FluoFactory.createApplicationContext(rootModule, {
+        diagnostics: {
+          timing: true
+        },
+        logger: {
+          debug() {},
+          error() {},
+          log() {},
+          warn() {}
+        }
+      });
+      try {
+        stdout.write(`${stringifyTiming(context.bootstrapTiming)}\n`);
+      } finally {
+        await context.close();
+      }
+      return 0;
+    }
+    const context = await FluoFactory.createApplicationContext(rootModule, {
+      logger: {
+        debug() {},
+        error() {},
+        log() {},
+        warn() {}
+      }
+    });
+    try {
+      const platformShell = await context.get(PLATFORM_SHELL);
+      const snapshot = await platformShell.snapshot();
+      if (parsed.json) {
+        stdout.write(`${stringifySnapshot(snapshot)}\n`);
+      }
+      if (parsed.mermaid) {
+        stdout.write(`${renderPlatformSnapshotMermaid(snapshot)}\n`);
+      }
+    } finally {
+      await context.close();
+    }
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`${message}\n`);
+    return 1;
+  }
+}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,30 @@
+type CliStream = {
+    write(message: string): unknown;
+};
+/**
+ * Runtime configuration for the migrate command.
+ */
+export interface MigrateCommandRuntimeOptions {
+    /** Current working directory for path resolution. */
+    cwd?: string;
+    /** Custom stream for error output. */
+    stderr?: CliStream;
+    /** Custom stream for standard output. */
+    stdout?: CliStream;
+}
+/**
+ * Returns usage information for the migrate command.
+ *
+ * @returns Formatted help text including usage and options.
+ */
+export declare function migrateUsage(): string;
+/**
+ * Executes the migrate command to transform NestJS projects into fluo.
+ *
+ * @param argv Command line arguments.
+ * @param runtime Optional custom runtime configuration for output streams and working directory.
+ * @returns Exit code (0 for success, 1 for failure).
+ */
+export declare function runMigrateCommand(argv: string[], runtime?: MigrateCommandRuntimeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAYA,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;AA6HD;;;;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,CAmEnH"}

package/dist/commands/migrate.js

@@ -0,0 +1,173 @@
+import { resolve } from 'node:path';
+import { renderAliasList, renderHelpTable } from '../help.js';
+import { MIGRATION_TRANSFORMS, getWarningCategoryLabel, groupWarningsByCategory, renderTransformList, runNestJsMigration } from '../transforms/nestjs-migrate.js';
+
+/**
+ * Runtime configuration for the migrate command.
+ */
+
+const MIGRATE_OPTION_HELP = [{
+  aliases: ['-a'],
+  description: 'Apply file changes. Dry-run is the default mode.',
+  option: '--apply'
+}, {
+  aliases: [],
+  description: `Run only selected transforms. Available: ${MIGRATION_TRANSFORMS.join(', ')}.`,
+  option: '--only <comma-list>'
+}, {
+  aliases: [],
+  description: `Skip selected transforms. Available: ${MIGRATION_TRANSFORMS.join(', ')}.`,
+  option: '--skip <comma-list>'
+}, {
+  aliases: ['-h'],
+  description: 'Show help for the migrate command.',
+  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 onlyTransforms;
+  let skipTransforms = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--apply' || arg === '-a') {
+      apply = true;
+      continue;
+    }
+    if (arg === '--only' || arg === '--skip') {
+      const rawValue = argv[index + 1];
+      if (!rawValue || rawValue.startsWith('-')) {
+        throw new Error(`Expected ${arg} to have a comma-separated value.`);
+      }
+      const parsed = parseTransformList(rawValue, arg);
+      if (arg === '--only') {
+        if (onlyTransforms) {
+          throw new Error('Duplicate --only option.');
+        }
+        onlyTransforms = parsed;
+      } else {
+        skipTransforms = [...skipTransforms, ...parsed];
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option for migrate command: ${arg}`);
+    }
+    if (pathArgument) {
+      throw new Error(`Unexpected extra positional argument: ${arg}`);
+    }
+    pathArgument = arg;
+  }
+  if (!pathArgument) {
+    throw new Error(migrateUsage());
+  }
+  const enabled = new Set(onlyTransforms ?? MIGRATION_TRANSFORMS);
+  for (const skipped of skipTransforms) {
+    enabled.delete(skipped);
+  }
+  if (enabled.size === 0) {
+    throw new Error('No transforms remain after applying --only/--skip filters.');
+  }
+  return {
+    apply,
+    path: pathArgument,
+    transforms: enabled
+  };
+}
+
+/**
+ * Returns usage information for the migrate command.
+ *
+ * @returns Formatted help text including usage and options.
+ */
+export function migrateUsage() {
+  return ['Usage: fluo migrate <path> [options]', '', 'Options', renderHelpTable(MIGRATE_OPTION_HELP, [{
+    header: 'Option',
+    render: entry => entry.option
+  }, {
+    header: 'Aliases',
+    render: entry => renderAliasList(entry.aliases)
+  }, {
+    header: 'Description',
+    render: entry => entry.description
+  }]), '', 'Next steps:', '  Review warnings in the output, then run again with --apply to write changes.', '', 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/migrate-from-nestjs.md'].join('\n');
+}
+
+/**
+ * Executes the migrate command to transform NestJS projects into fluo.
+ *
+ * @param argv Command line arguments.
+ * @param runtime Optional custom runtime configuration for output streams and working directory.
+ * @returns Exit code (0 for success, 1 for failure).
+ */
+export async function runMigrateCommand(argv, runtime = {}) {
+  const stdout = runtime.stdout ?? process.stdout;
+  const stderr = runtime.stderr ?? process.stderr;
+  try {
+    if (argv.some(isHelpFlag)) {
+      stdout.write(`${migrateUsage()}\n`);
+      return 0;
+    }
+    const parsed = parseArgs(argv);
+    const targetPath = resolve(runtime.cwd ?? process.cwd(), parsed.path);
+    const transforms = [...parsed.transforms];
+    const report = runNestJsMigration({
+      apply: parsed.apply,
+      enabledTransforms: parsed.transforms,
+      targetPath
+    });
+    stdout.write(`Mode: ${parsed.apply ? 'apply' : 'dry-run'}\n`);
+    stdout.write(`Enabled transforms: ${renderTransformList(transforms)}\n`);
+    stdout.write(`Scanned files: ${report.scannedFiles}\n`);
+    stdout.write(`Changed files: ${report.changedFiles}\n`);
+    stdout.write(`Warnings: ${report.warningCount}\n`);
+    if (!parsed.apply && report.changedFiles > 0) {
+      stdout.write('Run again with --apply to write transformed files.\n');
+    }
+    const changedPaths = report.fileResults.filter(fileResult => fileResult.changed).map(fileResult => fileResult.filePath);
+    if (changedPaths.length > 0) {
+      stdout.write('\nAutomated rewrites:\n');
+      for (const filePath of changedPaths) {
+        stdout.write(`  ${filePath}\n`);
+      }
+    }
+    const allWarnings = report.fileResults.flatMap(fileResult => fileResult.warnings);
+    if (allWarnings.length > 0) {
+      stdout.write('\nManual follow-up required:\n');
+      const grouped = groupWarningsByCategory(allWarnings);
+      for (const [category, warnings] of grouped) {
+        stdout.write(`\n  [${getWarningCategoryLabel(category)}]\n`);
+        for (const warning of warnings) {
+          stdout.write(`  - ${warning.filePath}:${warning.line} ${warning.message}\n`);
+        }
+      }
+    }
+    if (report.warningCount === 0 && report.changedFiles > 0) {
+      stdout.write('\nAll transforms applied cleanly. No manual follow-ups detected.\n');
+    }
+    if (report.warningCount > 0) {
+      stdout.write('\nDocs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/migrate-from-nestjs.md\n');
+      stdout.write('Use the post-codemod checklist in the migration guide to address each warning category.\n');
+    }
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`${message}\n`);
+    return 1;
+  }
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,45 @@
+import { type BootstrapPrompter } from '../new/prompt.js';
+import type { NewCommandOptions } from '../new/types.js';
+type CliStream = {
+    write(message: string): unknown;
+};
+/**
+ * Runtime dependency overrides for the programmatic `fluo new` entry point.
+ */
+export interface NewCommandRuntimeOptions extends NewCommandOptions {
+    cwd?: string;
+    interactive?: boolean;
+    prompt?: BootstrapPrompter;
+    stderr?: CliStream;
+    stdin?: {
+        isTTY?: boolean;
+    };
+    stdout?: CliStream;
+    userAgent?: string;
+}
+/**
+ * Renders CLI help text for `fluo new`.
+ *
+ * @returns Stable help output for the scaffolding command.
+ */
+export declare function newUsage(): string;
+/**
+ * Executes `fluo new` with parsed arguments and scaffold options.
+ *
+ * @example
+ * ```ts
+ * import { runNewCommand } from '@fluojs/cli';
+ *
+ * const exitCode = await runNewCommand(['starter-app', '--package-manager', 'pnpm'], {
+ *   cwd: '/workspace',
+ *   skipInstall: true,
+ * });
+ * ```
+ *
+ * @param argv Command arguments after the `new` or `create` token.
+ * @param runtime Optional runtime overrides for prompt resolution, stream output, and scaffold execution.
+ * @returns `0` when scaffolding succeeds, otherwise `1` after reporting the failure to `stderr`.
+ */
+export declare function runNewCommand(argv: string[], runtime?: NewCommandRuntimeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=new.d.ts.map