@fluojs/cli 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/commands/generate.js

@@ -10,6 +10,53 @@ function writeFileIfChanged(filePath, content) {
   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) {
   return {
     ...options,
@@ -17,6 +64,15 @@ function createGeneratorOptions(kind, domainDirectory, kebab, options) {
     hasService: options.hasService ?? (kind === 'controller' ? existsSync(join(domainDirectory, `${kebab}.service.ts`)) : undefined)
   };
 }
+function resolveDomainDirectory(kind, resolvedBase, kebab, options) {
+  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) {
@@ -88,7 +144,7 @@ function prepareModuleUpdate(domainDirectory, normalizedName, kind, classSuffix,
  * @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.
+ * @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.
  */
@@ -97,11 +153,23 @@ export function runGenerateCommand(kind, name, baseDirectory, options = {}) {
   const kebab = assertValidResourceName(normalizedName);
   const generator = findGeneratorDefinition(kind);
   const resolvedBase = resolve(baseDirectory);
-  const domainDirectory = join(resolvedBase, toPlural(kebab));
+  const domainDirectory = resolveDomainDirectory(kind, resolvedBase, kebab, options);
   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;
+  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
   });
@@ -129,6 +197,7 @@ export function runGenerateCommand(kind, name, baseDirectory, options = {}) {
     moduleRegistered: moduleRegistered,
     modulePath: resolvedModulePath,
     nextStepHint: generator.nextStepHint,
+    plannedFiles: modulePlan ? [...plannedFiles, modulePlan] : plannedFiles,
     wiringBehavior: generator.wiringBehavior
   };
 }

package/dist/commands/inspect.d.ts

@@ -1,14 +1,34 @@
+import { type PlatformShellSnapshot } from '@fluojs/runtime';
 type CliStream = {
     write(message: string): unknown;
 };
+type InspectPrompter = {
+    close?(): void;
+    confirm(message: string, defaultValue: boolean): Promise<boolean>;
+};
+type ReadableStream = {
+    isTTY?: boolean;
+};
+type StudioMermaidRenderer = (snapshot: PlatformShellSnapshot) => string;
+type StudioMermaidRendererLoader = (cwd: string) => Promise<StudioMermaidRenderer | undefined>;
 /**
  * Runtime options for the inspect command when used programmatically.
  */
 export interface InspectCommandRuntimeOptions {
+    /** Whether the caller is running under CI/non-interactive automation. */
+    ci?: boolean;
     /** Current working directory for module resolution. */
     cwd?: string;
+    /** Force or disable interactive prompts for optional Studio guidance. */
+    interactive?: boolean;
+    /** Optional test/editor hook for resolving Studio's Mermaid renderer. */
+    loadStudioMermaidRenderer?: StudioMermaidRendererLoader;
+    /** Custom prompt implementation used only when Studio is missing for Mermaid output. */
+    prompt?: InspectPrompter;
     /** Custom stream for error output. */
     stderr?: CliStream;
+    /** Custom stream for terminal detection. */
+    stdin?: ReadableStream;
     /** Custom stream for standard output. */
     stdout?: CliStream;
 }

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

@@ -1 +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"}
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,qBAAqB,EAE3B,MAAM,iBAAiB,CAAC;AAKzB,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;AAkFD;;;;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,CA4EnH"}

package/dist/commands/inspect.js

@@ -1,7 +1,11 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { resolve } from 'node:path';
+import * as clack from '@clack/prompts';
 import { FluoFactory, PLATFORM_SHELL } from '@fluojs/runtime';
 import { renderAliasList, renderHelpTable } from '../help.js';
+import { CliPromptCancelledError, isCliPromptCancelledError } from '../prompt-cancel.js';
 
 /**
  * Runtime options for the inspect command when used programmatically.
@@ -13,12 +17,20 @@ const INSPECT_OPTION_HELP = [{
   option: '--json'
 }, {
   aliases: [],
-  description: 'Emit platform component dependency chains as a Mermaid diagram.',
+  description: 'Emit a Mermaid graph through the optional @fluojs/studio rendering contract.',
   option: '--mermaid'
 }, {
   aliases: [],
   description: 'Bootstrap the application context and emit versioned timing diagnostics.',
   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).',
@@ -28,6 +40,8 @@ const INSPECT_OPTION_HELP = [{
   description: 'Show help for the inspect command.',
   option: '--help'
 }];
+const STUDIO_CONTRACT_ENTRYPOINT = '@fluojs/studio/contracts';
+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');
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
@@ -54,6 +68,8 @@ function parseInspectArgs(argv) {
   let exportName = 'AppModule';
   let json = false;
   let mermaid = false;
+  let outputPath;
+  let report = false;
   let timing = false;
   for (let index = 0; index < argv.length; index += 1) {
     const option = argv[index];
@@ -72,6 +88,19 @@ function parseInspectArgs(argv) {
       timing = true;
       continue;
     }
+    if (option === '--report') {
+      report = true;
+      continue;
+    }
+    if (option === '--output') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('Expected --output to have a file path value.');
+      }
+      outputPath = next;
+      index += 1;
+      continue;
+    }
     if (option === '--export') {
       const next = argv[index + 1];
       if (!next || next.startsWith('-')) {
@@ -92,18 +121,23 @@ function parseInspectArgs(argv) {
   if (!modulePath) {
     throw new Error(inspectUsage());
   }
-  if (!json && !mermaid && !timing) {
+  if (!json && !mermaid && !timing && !report) {
     json = true;
   }
-  const selectedModes = [json, mermaid, timing].filter(Boolean).length;
+  const selectedModes = [json, mermaid, report].filter(Boolean).length;
   if (selectedModes > 1) {
-    throw new Error('Choose only one inspect output mode: --json, --mermaid, or --timing.');
+    throw new Error('Choose only one inspect output mode: --json, --mermaid, or --report.');
+  }
+  if (mermaid && timing) {
+    throw new Error('Use --timing only with JSON inspect output or --report. Mermaid rendering remains delegated to @fluojs/studio.');
   }
   return {
     exportName,
     json,
     mermaid,
     modulePath,
+    outputPath,
+    report,
     timing
   };
 }
@@ -124,33 +158,111 @@ function stringifyTiming(timing) {
 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}"]`);
+function createEmptyTimingDiagnostics() {
+  return {
+    phases: [],
+    totalMs: 0,
+    version: 1
+  };
+}
+function createInspectReport(snapshot, timing) {
+  const resolvedTiming = timing ?? createEmptyTimingDiagnostics();
+  const errorCount = snapshot.diagnostics.filter(diagnostic => diagnostic.severity === 'error').length;
+  const warningCount = snapshot.diagnostics.filter(diagnostic => diagnostic.severity === 'warning').length;
+  return {
+    generatedAt: snapshot.generatedAt,
+    snapshot,
+    summary: {
+      componentCount: snapshot.components.length,
+      diagnosticCount: snapshot.diagnostics.length,
+      errorCount,
+      healthStatus: snapshot.health.status,
+      readinessStatus: snapshot.readiness.status,
+      timingTotalMs: resolvedTiming.totalMs,
+      warningCount
+    },
+    timing: resolvedTiming,
+    version: 1
+  };
+}
+function stringifySnapshotWithTiming(snapshot, timing) {
+  return JSON.stringify({
+    snapshot,
+    timing: timing ?? createEmptyTimingDiagnostics()
+  }, null, 2);
+}
+async function emitInspectPayload(payload, parsed, cwd, stdout) {
+  if (!parsed.outputPath) {
+    stdout.write(`${payload}\n`);
+    return;
   }
-  for (const component of snapshot.components) {
-    const from = nodeByComponentId.get(component.id);
-    if (!from) {
-      continue;
+  const outputPath = resolve(cwd, parsed.outputPath);
+  await mkdir(dirname(outputPath), {
+    recursive: true
+  });
+  await writeFile(outputPath, `${payload}\n`, 'utf8');
+}
+function createInspectPrompter() {
+  return {
+    async confirm(message, defaultValue) {
+      const result = await clack.confirm({
+        initialValue: defaultValue,
+        message
+      });
+      if (clack.isCancel(result)) {
+        clack.cancel('Operation cancelled.');
+        throw new CliPromptCancelledError();
+      }
+      return result;
     }
-    for (const dependency of component.dependencies) {
-      const to = nodeByComponentId.get(dependency);
-      if (!to) {
-        continue;
+  };
+}
+function shouldPromptForStudio(runtime) {
+  if (runtime.prompt !== undefined) {
+    return runtime.interactive ?? true;
+  }
+  if (runtime.ci === true) {
+    return false;
+  }
+  return runtime.stdout === undefined && runtime.stderr === undefined && (runtime.interactive ?? true) && Boolean(runtime.stdin?.isTTY ?? process.stdin.isTTY);
+}
+async function loadStudioMermaidRenderer(cwd) {
+  const resolvers = [createRequire(resolve(cwd, 'package.json')), createRequire(import.meta.url)];
+  for (const resolver of resolvers) {
+    try {
+      const resolvedEntrypoint = resolver.resolve(STUDIO_CONTRACT_ENTRYPOINT);
+      const importedContract = await import(pathToFileURL(resolvedEntrypoint).href);
+      if (typeof importedContract.renderMermaid !== 'function') {
+        throw new Error(`${STUDIO_CONTRACT_ENTRYPOINT} does not export renderMermaid(snapshot).`);
+      }
+      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') {
+        throw error;
       }
-      lines.push(`  ${from} --> ${to}`);
     }
   }
-  return lines.join('\n');
+  return undefined;
+}
+async function resolveStudioMermaidRenderer(cwd, runtime) {
+  const renderer = await (runtime.loadStudioMermaidRenderer ?? loadStudioMermaidRenderer)(cwd);
+  if (renderer) {
+    return renderer;
+  }
+  if (!shouldPromptForStudio(runtime)) {
+    throw new Error(STUDIO_MISSING_MESSAGE);
+  }
+  const prompt = runtime.prompt ?? createInspectPrompter();
+  try {
+    const approvedInstall = await prompt.confirm('Install @fluojs/studio before rendering Mermaid output?', false);
+    if (!approvedInstall) {
+      throw new Error(`${STUDIO_MISSING_MESSAGE}\nInstallation declined; no package-manager command was run.`);
+    }
+    throw new Error(`${STUDIO_MISSING_MESSAGE}\nAutomatic installation is not run by fluo inspect. Install @fluojs/studio explicitly, then rerun the command.`);
+  } finally {
+    prompt.close?.();
+  }
 }
 
 /**
@@ -173,7 +285,7 @@ export async function runInspectCommand(argv, runtime = {}) {
     const modulePath = resolve(cwd, parsed.modulePath);
     const importedModule = await import(pathToFileURL(modulePath).href);
     const rootModule = resolveRootModule(importedModule[parsed.exportName], parsed.exportName);
-    if (parsed.timing) {
+    if (parsed.timing && !parsed.json && !parsed.report) {
       const context = await FluoFactory.createApplicationContext(rootModule, {
         diagnostics: {
           timing: true
@@ -186,13 +298,16 @@ export async function runInspectCommand(argv, runtime = {}) {
         }
       });
       try {
-        stdout.write(`${stringifyTiming(context.bootstrapTiming)}\n`);
+        await emitInspectPayload(stringifyTiming(context.bootstrapTiming), parsed, cwd, stdout);
       } finally {
         await context.close();
       }
       return 0;
     }
     const context = await FluoFactory.createApplicationContext(rootModule, {
+      diagnostics: parsed.timing || parsed.report ? {
+        timing: true
+      } : undefined,
       logger: {
         debug() {},
         error() {},
@@ -204,16 +319,23 @@ export async function runInspectCommand(argv, runtime = {}) {
       const platformShell = await context.get(PLATFORM_SHELL);
       const snapshot = await platformShell.snapshot();
       if (parsed.json) {
-        stdout.write(`${stringifySnapshot(snapshot)}\n`);
+        await emitInspectPayload(parsed.timing ? stringifySnapshotWithTiming(snapshot, context.bootstrapTiming) : stringifySnapshot(snapshot), parsed, cwd, stdout);
+      }
+      if (parsed.report) {
+        await emitInspectPayload(JSON.stringify(createInspectReport(snapshot, context.bootstrapTiming), null, 2), parsed, cwd, stdout);
       }
       if (parsed.mermaid) {
-        stdout.write(`${renderPlatformSnapshotMermaid(snapshot)}\n`);
+        const renderMermaid = await resolveStudioMermaidRenderer(cwd, runtime);
+        await emitInspectPayload(renderMermaid(snapshot), parsed, cwd, stdout);
       }
     } finally {
       await context.close();
     }
     return 0;
   } catch (error) {
+    if (isCliPromptCancelledError(error)) {
+      return 0;
+    }
     const message = error instanceof Error ? error.message : String(error);
     stderr.write(`${message}\n`);
     return 1;

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

@@ -1 +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"}
+{"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"}

package/dist/commands/migrate.js

@@ -10,6 +10,10 @@ const MIGRATE_OPTION_HELP = [{
   aliases: ['-a'],
   description: 'Apply file changes. Dry-run is the default mode.',
   option: '--apply'
+}, {
+  aliases: [],
+  description: 'Emit a machine-readable JSON migration report to stdout. Errors still go to stderr.',
+  option: '--json'
 }, {
   aliases: [],
   description: `Run only selected transforms. Available: ${MIGRATION_TRANSFORMS.join(', ')}.`,
@@ -40,6 +44,7 @@ function parseTransformList(rawValue, optionName) {
 function parseArgs(argv) {
   let pathArgument;
   let apply = false;
+  let json = false;
   let onlyTransforms;
   let skipTransforms = [];
   for (let index = 0; index < argv.length; index += 1) {
@@ -48,6 +53,13 @@ function parseArgs(argv) {
       apply = true;
       continue;
     }
+    if (arg === '--json') {
+      if (json) {
+        throw new Error('Duplicate --json option.');
+      }
+      json = true;
+      continue;
+    }
     if (arg === '--only' || arg === '--skip') {
       const rawValue = argv[index + 1];
       if (!rawValue || rawValue.startsWith('-')) {
@@ -85,10 +97,36 @@ function parseArgs(argv) {
   }
   return {
     apply,
+    json,
     path: pathArgument,
     transforms: enabled
   };
 }
+function renderJsonReport(report, transforms) {
+  return `${JSON.stringify({
+    command: 'migrate',
+    mode: report.apply ? 'apply' : 'dry-run',
+    apply: report.apply,
+    dryRun: !report.apply,
+    transforms,
+    scannedFiles: report.scannedFiles,
+    changedFiles: report.changedFiles,
+    warningCount: report.warningCount,
+    files: report.fileResults.map(fileResult => ({
+      filePath: fileResult.filePath,
+      changed: fileResult.changed,
+      appliedTransforms: fileResult.appliedTransforms,
+      warningCount: fileResult.warnings.length,
+      warnings: fileResult.warnings.map(warning => ({
+        category: warning.category,
+        categoryLabel: getWarningCategoryLabel(warning.category),
+        filePath: warning.filePath,
+        line: warning.line,
+        message: warning.message
+      }))
+    }))
+  }, null, 2)}\n`;
+}
 
 /**
  * Returns usage information for the migrate command.
@@ -131,6 +169,10 @@ export async function runMigrateCommand(argv, runtime = {}) {
       enabledTransforms: parsed.transforms,
       targetPath
     });
+    if (parsed.json) {
+      stdout.write(renderJsonReport(report, transforms));
+      return 0;
+    }
     stdout.write(`Mode: ${parsed.apply ? 'apply' : 'dry-run'}\n`);
     stdout.write(`Enabled transforms: ${renderTransformList(transforms)}\n`);
     stdout.write(`Scanned files: ${report.scannedFiles}\n`);

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

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAUnF,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAuBF;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiSD;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA0BjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAiG3G"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAOA,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAWnF,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAuBF;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0UD;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA0BjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CA4G3G"}

package/dist/commands/new.js

@@ -1,8 +1,10 @@
 import { resolve } from 'node:path';
 import { spinner as clackSpinner, log as clackLog } from '@clack/prompts';
 import { renderAliasList, renderHelpTable } from '../help.js';
+import { isCliPromptCancelledError } from '../prompt-cancel.js';
 import { installDependencies } from '../new/install.js';
 import { collectBootstrapAnswers } from '../new/prompt.js';
+import { resolveBootstrapPlan } from '../new/resolver.js';
 import { scaffoldBootstrapApp } from '../new/scaffold.js';
 import { SUPPORTED_BOOTSTRAP_PLATFORMS, SUPPORTED_BOOTSTRAP_RUNTIMES, SUPPORTED_BOOTSTRAP_SHAPES, SUPPORTED_BOOTSTRAP_TOOLING_PRESETS, SUPPORTED_BOOTSTRAP_TOPOLOGY_MODES, SUPPORTED_BOOTSTRAP_TRANSPORTS } from '../new/starter-profiles.js';
 function shouldUseInteractiveShell(runtime) {
@@ -79,6 +81,10 @@ const NEW_OPTION_HELP = [{
   aliases: [],
   description: 'Skip git repository initialization in the generated starter.',
   option: '--no-git'
+}, {
+  aliases: [],
+  description: 'Print the resolved scaffold plan without writing files, installing dependencies, or initializing git.',
+  option: '--print-plan'
 }, {
   aliases: ['-h'],
   description: 'Show help for the new command.',
@@ -163,7 +169,7 @@ function parseArgs(argv) {
         }
         parsed.platform = readOptionValue(argv, index, '--platform');
         if (!SUPPORTED_PLATFORMS.has(parsed.platform)) {
-          throw new Error('Invalid --platform value "' + parsed.platform + '". Use one of: bun, cloudflare-workers, deno, fastify, express, nodejs, none.');
+          throw new Error(`Invalid --platform value "${parsed.platform}". Use one of: bun, cloudflare-workers, deno, fastify, express, nodejs, none.`);
         }
         index += 1;
         break;
@@ -204,6 +210,9 @@ function parseArgs(argv) {
       case '--force':
         parsed.force = true;
         break;
+      case '--print-plan':
+        parsed.printPlan = true;
+        break;
       case '--install':
         parsed.installDependencies = setBooleanSelection(parsed.installDependencies, true, '--install', '--no-install');
         break;
@@ -232,6 +241,13 @@ function parseArgs(argv) {
   }
   return parsed;
 }
+function renderDependencyList(dependencies) {
+  return dependencies.length > 0 ? dependencies.join(', ') : '(none)';
+}
+function renderScaffoldPlanPreview(answers, resolvedTargetDirectory) {
+  const bootstrapPlan = resolveBootstrapPlan(answers);
+  return ['fluo new scaffold plan', '', `Project name: ${answers.projectName}`, `Target directory: ${answers.targetDirectory}`, `Resolved target: ${resolvedTargetDirectory}`, `Shape: ${answers.shape}`, `Runtime: ${answers.runtime}`, `Platform: ${answers.platform}`, `Transport: ${answers.transport}`, `Tooling preset: ${answers.tooling}`, `Topology: ${answers.topology.mode}${answers.topology.deferred ? ' (deferred)' : ''}`, `Starter recipe: ${bootstrapPlan.profile.id}`, `Emitter: ${bootstrapPlan.emitter.type}`, `Package manager: ${answers.packageManager}`, `Install dependencies: ${answers.installDependencies ? 'yes' : 'no'}`, `Initialize git: ${answers.initializeGit ? 'yes' : 'no'}`, '', 'Dependencies:', `  runtime: ${renderDependencyList(bootstrapPlan.dependencies.dependencies)}`, `  dev: ${renderDependencyList(bootstrapPlan.dependencies.devDependencies)}`, '', 'Side effects: none. Preview mode does not create files, install dependencies, or initialize git.'].join('\n');
+}
 
 /**
  * Renders CLI help text for `fluo new`.
@@ -287,11 +303,16 @@ export async function runNewCommand(argv, runtime = {}) {
     }
     const answers = await collectBootstrapAnswers(partialAnswers, runtime.cwd ?? process.cwd(), runtime.userAgent, {
       interactive: runtime.interactive,
+      completionMessage: parsed.printPlan ? 'Scaffold plan resolved. No files were written.' : undefined,
       prompt: runtime.prompt,
       stdin: runtime.stdin,
       stdout
     });
     const targetDirectory = resolve(runtime.cwd ?? process.cwd(), answers.targetDirectory);
+    if (parsed.printPlan) {
+      stdout.write(`${renderScaffoldPlanPreview(answers, targetDirectory)}\n`);
+      return 0;
+    }
     const options = {
       ...answers,
       dependencySource: runtime.dependencySource,
@@ -346,6 +367,9 @@ export async function runNewCommand(argv, runtime = {}) {
     stdout.write(`Next steps:\n  cd ${answers.targetDirectory}\n  ${answers.packageManager === 'npm' ? 'npm run dev' : answers.packageManager === 'bun' ? 'bun run dev' : `${answers.packageManager} dev`}\n`);
     return 0;
   } catch (error) {
+    if (isCliPromptCancelledError(error)) {
+      return 0;
+    }
     const message = error instanceof Error ? error.message : String(error);
     stderr.write(`${message}\n`);
     return 1;

package/dist/generator-types.d.ts

@@ -3,11 +3,17 @@ export interface GeneratedFile {
     content: string;
     path: string;
 }
-/** Optional generation flags that influence overwrite behavior and sibling-aware templates. */
+/** Optional generation flags that influence overwrite behavior, target placement, plan previews, and sibling-aware templates. */
 export interface GenerateOptions {
+    /** Preview planned writes and module updates without mutating the workspace. */
+    dryRun?: boolean;
     force?: boolean;
     hasRepo?: boolean;
     hasService?: boolean;
+    /**
+     * Feature or slice directory that should receive feature-local files such as request DTOs.
+     */
+    targetFeature?: string;
 }
 /**
  * Produces the in-memory files for one schematic/resource pair.
@@ -15,7 +21,15 @@ export interface GenerateOptions {
 export type GeneratorFactory = (name: string, options?: GenerateOptions) => GeneratedFile[];
 /** Registry shape used by generator manifests to bind a factory to CLI metadata. */
 export interface GeneratorRegistration {
+    collectionId?: string;
     factory: GeneratorFactory;
     description?: string;
 }
+/** Describes a supported option for generator metadata, help output, and docs alignment tests. */
+export interface GeneratorOptionSchema {
+    aliases: readonly string[];
+    description: string;
+    name: string;
+    value: 'boolean' | 'path';
+}
 //# sourceMappingURL=generator-types.d.ts.map

package/dist/generator-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator-types.d.ts","sourceRoot":"","sources":["../src/generator-types.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,aAAa,EAAE,CAAC;AAE5F,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"generator-types.d.ts","sourceRoot":"","sources":["../src/generator-types.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iIAAiI;AACjI,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,aAAa,EAAE,CAAC;AAE5F,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kGAAkG;AAClG,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;CAC3B"}

package/dist/generators/controller.d.ts

@@ -1,3 +1,10 @@
 import type { GenerateOptions, GeneratedFile } from '../types.js';
+/**
+ * Generate controller files.
+ *
+ * @param name The name.
+ * @param options The options.
+ * @returns The generate controller files result.
+ */
 export declare function generateControllerFiles(name: string, options?: GenerateOptions): GeneratedFile[];
 //# sourceMappingURL=controller.d.ts.map

package/dist/generators/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/generators/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKlE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,aAAa,EAAE,CAkBpG"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/generators/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKlE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,aAAa,EAAE,CAkBpG"}