@fluojs/cli 2.0.1 → 3.0.0

package/dist/commands/inspect.js

@@ -1,20 +1,24 @@
+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 { 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 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';
 }
@@ -35,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;
@@ -105,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);
@@ -145,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({
@@ -180,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) {
@@ -191,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;
       }
     }
@@ -207,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) {
@@ -237,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;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,iBAAiB,EAA2B,MAAM,kBAAkB,CAAC;AAWnF,OAAO,KAAK,EAAsC,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAI7F,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAiCF;;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;AAiPD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6G3G"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,iBAAiB,EAA2B,MAAM,kBAAkB,CAAC;AAYnF,OAAO,KAAK,EAAsC,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAI7F,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAmCF;;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;AA+PD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6H3G"}

package/dist/commands/new.js

@@ -1,10 +1,9 @@
 import { resolve } from 'node:path';
-import { log as clackLog, spinner as clackSpinner } from '@clack/prompts';
 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';
+import { SUPPORTED_BOOTSTRAP_PLATFORMS, SUPPORTED_BOOTSTRAP_RUNTIMES, SUPPORTED_BOOTSTRAP_SHAPES, SUPPORTED_BOOTSTRAP_STARTERS, SUPPORTED_BOOTSTRAP_TOOLING_PRESETS, SUPPORTED_BOOTSTRAP_TOPOLOGY_MODES, SUPPORTED_BOOTSTRAP_TRANSPORTS } from '../new/starter-profiles.js';
 import { isCliPromptCancelledError } from '../prompt-cancel.js';
 import { newUsage } from '../usage.js';
 function shouldUseInteractiveShell(runtime) {
@@ -35,6 +34,7 @@ function readInternalScaffoldOverrides(runtime) {
 
 const SUPPORTED_PACKAGE_MANAGERS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
 const SUPPORTED_SHAPES = new Set(SUPPORTED_BOOTSTRAP_SHAPES);
+const SUPPORTED_STARTERS = new Set(SUPPORTED_BOOTSTRAP_STARTERS);
 const SUPPORTED_TRANSPORTS = new Set(SUPPORTED_BOOTSTRAP_TRANSPORTS);
 const SUPPORTED_RUNTIMES = new Set(SUPPORTED_BOOTSTRAP_RUNTIMES);
 const SUPPORTED_PLATFORMS = new Set(SUPPORTED_BOOTSTRAP_PLATFORMS);
@@ -86,6 +86,16 @@ function parseArgs(argv) {
         }
         index += 1;
         break;
+      case '--starter':
+        if (parsed.starter) {
+          throw new Error('Duplicate --starter option.');
+        }
+        parsed.starter = readOptionValue(argv, index, '--starter');
+        if (!SUPPORTED_STARTERS.has(parsed.starter)) {
+          throw new Error(`Invalid --starter value "${parsed.starter}". Use one of: standard, react-vite-ssr.`);
+        }
+        index += 1;
+        break;
       case '--transport':
         if (parsed.transport) {
           throw new Error('Duplicate --transport option.');
@@ -189,7 +199,7 @@ function renderDependencyList(dependencies) {
 }
 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');
+  return ['fluo new scaffold plan', '', `Project name: ${answers.projectName}`, `Target directory: ${answers.targetDirectory}`, `Resolved target: ${resolvedTargetDirectory}`, `Starter: ${answers.starter}`, `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');
 }
 
 /**
@@ -226,9 +236,13 @@ export async function runNewCommand(argv, runtime = {}) {
     if (!partialAnswers.projectName && !(runtime.interactive ?? runtime.prompt ?? runtime.stdin?.isTTY ?? process.stdin.isTTY)) {
       throw new Error(newUsage());
     }
+    let usedInteractivePrompt = false;
     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,
+      onInteractivePrompt: () => {
+        usedInteractivePrompt = true;
+      },
       prompt: runtime.prompt,
       stdin: runtime.stdin,
       stdout
@@ -249,14 +263,15 @@ export async function runNewCommand(argv, runtime = {}) {
       skipInstall: true,
       targetDirectory
     };
-    const isInteractiveShell = shouldUseInteractiveShell(runtime);
+    const isInteractiveShell = usedInteractivePrompt && shouldUseInteractiveShell(runtime);
+    const clack = isInteractiveShell ? await import('@clack/prompts') : undefined;
     let scaffoldSpinner;
     if (!answers.installDependencies && !isInteractiveShell) {
       stdout.write('Skipping dependency installation.\n');
     }
     if (isInteractiveShell) {
-      scaffoldSpinner = clackSpinner();
-      scaffoldSpinner.start('Scaffolding project files');
+      scaffoldSpinner = clack?.spinner();
+      scaffoldSpinner?.start('Scaffolding project files');
     }
     await scaffoldBootstrapApp(options);
     if (scaffoldSpinner) {
@@ -269,7 +284,10 @@ export async function runNewCommand(argv, runtime = {}) {
           stderr
         });
       } else {
-        const installSpinner = clackSpinner();
+        const installSpinner = clack?.spinner();
+        if (!installSpinner) {
+          throw new Error('Interactive dependency installation requires @clack/prompts.');
+        }
         installSpinner.start(`Installing dependencies with ${answers.packageManager}`);
         try {
           await installDependencies(targetDirectory, answers.packageManager, {
@@ -287,10 +305,12 @@ export async function runNewCommand(argv, runtime = {}) {
         }
       }
     } else if (isInteractiveShell) {
-      clackLog.step('Dependency installation skipped');
+      clack?.log.step('Dependency installation skipped');
     }
+    const devCommand = answers.packageManager === 'npm' ? 'npm run dev' : answers.packageManager === 'bun' ? 'bun run dev' : `${answers.packageManager} dev`;
+    const devDescription = answers.starter === 'react-vite-ssr' ? 'builds and starts the React SSR app' : 'runs fluo dev';
     stdout.write('Done.\n');
-    stdout.write(`Next steps:\n  cd ${answers.targetDirectory}\n  ${answers.packageManager === 'npm' ? 'npm run dev' : answers.packageManager === 'bun' ? 'bun run dev' : `${answers.packageManager} dev`}  # runs fluo dev\n`);
+    stdout.write(`Next steps:\n  cd ${answers.targetDirectory}\n  ${devCommand}  # ${devDescription}\n`);
     return 0;
   } catch (error) {
     if (isCliPromptCancelledError(error)) {

package/dist/commands/output-path-safety.d.ts

@@ -0,0 +1,14 @@
+/** Raised when an artifact output resolves to its input application module. */
+export declare class OutputPathAliasesModuleError extends Error {
+    readonly name = "OutputPathAliasesModuleError";
+}
+/**
+ * Rejects an artifact path that directly or through a symlink resolves to the input module.
+ *
+ * @param modulePath Absolute application module path.
+ * @param outputPath Absolute artifact output path.
+ * @returns Resolves when the output path does not identify the input application module.
+ * @throws {OutputPathAliasesModuleError} When the paths identify the same file.
+ */
+export declare function assertOutputDoesNotAliasModule(modulePath: string, outputPath: string): Promise<void>;
+//# sourceMappingURL=output-path-safety.d.ts.map

package/dist/commands/output-path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-path-safety.d.ts","sourceRoot":"","sources":["../../src/commands/output-path-safety.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,kCAAkC;CAChD;AAMD;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/commands/output-path-safety.js

@@ -0,0 +1,34 @@
+import { realpath } from 'node:fs/promises';
+
+/** Raised when an artifact output resolves to its input application module. */
+export class OutputPathAliasesModuleError extends Error {
+  name = 'OutputPathAliasesModuleError';
+}
+function isMissingPathError(error) {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+
+/**
+ * Rejects an artifact path that directly or through a symlink resolves to the input module.
+ *
+ * @param modulePath Absolute application module path.
+ * @param outputPath Absolute artifact output path.
+ * @returns Resolves when the output path does not identify the input application module.
+ * @throws {OutputPathAliasesModuleError} When the paths identify the same file.
+ */
+export async function assertOutputDoesNotAliasModule(modulePath, outputPath) {
+  if (modulePath === outputPath) {
+    throw new OutputPathAliasesModuleError('Output path must not identify the input application module.');
+  }
+  const resolvedModulePath = await realpath(modulePath);
+  try {
+    const resolvedOutputPath = await realpath(outputPath);
+    if (resolvedModulePath === resolvedOutputPath) {
+      throw new OutputPathAliasesModuleError('Output path must not identify the input application module.');
+    }
+  } catch (error) {
+    if (error instanceof OutputPathAliasesModuleError || !isMissingPathError(error)) {
+      throw error;
+    }
+  }
+}

package/dist/commands/scripts.js

@@ -403,7 +403,7 @@ function assertStudioSupport(command, studio, projectRuntime, devRunner, rawWatc
     throw new Error('--studio is only supported for fluo dev.');
   }
   if (projectRuntime !== 'node') {
-    throw new Error(`fluo dev --studio currently supports Node dev runner projects only. ${projectRuntime} Studio support remains experimental until a dedicated bridge is implemented and verified.`);
+    throw new Error(`fluo dev --studio supports Node dev runner projects only. ${projectRuntime} projects can generate Studio-compatible artifacts with fluo inspect <module-path> --json --output <path> or fluo inspect <module-path> --report --output <path>.`);
   }
   if (devRunner !== 'fluo' || rawWatch) {
     throw new Error('fluo dev --studio requires the fluo-owned Node restart runner. Remove --raw-watch and use --runner fluo so Studio lifecycle events stay attached to the CLI restart boundary.');
@@ -597,7 +597,7 @@ async function runScriptWithStudioSidecar(command, projectDirectory, projectRunt
  */
 export function scriptUsage(command) {
   const nodeEnv = command === 'dev' ? 'development' : 'production';
-  return [`Usage: fluo ${command} [options] [-- <args>]`, '', `Run the generated fluo project ${command} lifecycle with NODE_ENV defaulting to ${nodeEnv} when unset.`, '', 'Default output forwards child stdout/stderr without fluo lifecycle UI.', 'Use --reporter pretty for fluo lifecycle status + app │ prefixes.', 'Use --verbose (or FLUO_VERBOSE=1) to expose raw runtime/tooling output.', '', 'Options', '  --dry-run                              Print the command without running it.', command === 'dev' ? '  --raw-watch                            Use the runtime-native Node watcher instead of the fluo restart runner.' : undefined, command === 'dev' ? '  --runner <fluo|native>                 Select fluo restart supervision or runtime-native watch (default: fluo for Node, native for non-Node runtimes).' : undefined, command === 'dev' ? '  --studio                              Start the local Fluo Studio sidecar and inject runtime devtool env.' : undefined, command === 'dev' ? '  --studio-port <port>                  Bind the Studio sidecar to a specific local port (default: 0).' : undefined, '  --reporter <auto|pretty|stream|silent> Choose lifecycle reporter output mode (default: auto).', '  --verbose                             Expose raw child process output; also honored by FLUO_VERBOSE=1.', `  --help                                 Show help for the ${command} command.`].filter(line => typeof line === 'string').join('\n');
+  return [`Usage: fluo ${command} [options] [-- <args>]`, '', `Run the generated fluo project ${command} lifecycle with NODE_ENV defaulting to ${nodeEnv} when unset.`, '', 'Default output forwards child stdout/stderr without fluo lifecycle UI.', 'Use --reporter pretty for fluo lifecycle status + app │ prefixes.', 'Use --verbose (or FLUO_VERBOSE=1) to expose raw runtime/tooling output.', '', 'Options', '  --dry-run                              Print the command without running it.', command === 'dev' ? '  --raw-watch                            Use the runtime-native Node watcher instead of the fluo restart runner.' : undefined, command === 'dev' ? '  --runner <fluo|native>                 Select fluo restart supervision or runtime-native watch (default: fluo for Node, native for non-Node runtimes).' : undefined, command === 'dev' ? '  --studio                              Start the local Fluo Studio sidecar for Node dev runner projects only.' : undefined, command === 'dev' ? '  --studio-port <port>                  Bind the Studio sidecar to a specific local port (default: 0).' : undefined, '  --reporter <auto|pretty|stream|silent> Choose lifecycle reporter output mode (default: auto).', '  --verbose                             Expose raw child process output; also honored by FLUO_VERBOSE=1.', `  --help                                 Show help for the ${command} command.`].filter(line => typeof line === 'string').join('\n');
 }
 
 /**

package/dist/commands/typegen-artifact.d.ts

@@ -0,0 +1,54 @@
+/** Filesystem boundary used by deterministic typegen artifact commits. */
+export type TypegenArtifactFileSystem = {
+    readonly mkdir: (path: string) => Promise<void>;
+    readonly readFile: (path: string) => Promise<string>;
+    readonly rename: (source: string, destination: string) => undefined;
+    readonly rm: (path: string) => Promise<void>;
+    readonly writeFile: (path: string, content: string) => Promise<void>;
+};
+type ArtifactInspection = {
+    readonly status: 'malformed';
+} | {
+    readonly status: 'unsupported-version';
+    readonly version: number;
+} | {
+    readonly status: 'valid';
+    readonly version: number;
+};
+/** Stable non-mutating comparison result for an existing typegen target. */
+export type TypegenArtifactCheck = {
+    readonly status: 'MALFORMED';
+} | {
+    readonly status: 'MISSING';
+} | {
+    readonly status: 'STALE';
+} | {
+    readonly status: 'UNCHANGED';
+} | {
+    readonly status: 'UNSUPPORTED_VERSION';
+    readonly version: number;
+};
+/** Stable write action reported after an atomic typegen artifact commit. */
+export type TypegenArtifactWriteAction = 'CREATE' | 'UNCHANGED' | 'UPDATE';
+/**
+ * Compares an existing artifact with expected generated bytes without writing.
+ *
+ * @param outputPath Target artifact path.
+ * @param expectedSource Authoritative generated source.
+ * @param inspect Structural artifact classifier.
+ * @param fileSystem Filesystem boundary used to read the target.
+ * @returns A stable unchanged, missing, stale, malformed, or unsupported-version result.
+ */
+export declare function checkTypegenArtifact(outputPath: string, expectedSource: string, inspect: (source: string) => ArtifactInspection, fileSystem?: TypegenArtifactFileSystem): Promise<TypegenArtifactCheck>;
+/**
+ * Atomically publishes generated source while skipping byte-identical rewrites.
+ *
+ * @param outputPath Target artifact path.
+ * @param source Complete generated source to publish.
+ * @param fileSystem Filesystem boundary used for the atomic replacement.
+ * @param signal Optional owner cancellation signal checked before publication.
+ * @returns The stable create, update, or unchanged action.
+ */
+export declare function writeTypegenArtifact(outputPath: string, source: string, fileSystem?: TypegenArtifactFileSystem, signal?: AbortSignal): Promise<TypegenArtifactWriteAction>;
+export {};
+//# sourceMappingURL=typegen-artifact.d.ts.map

package/dist/commands/typegen-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen-artifact.d.ts","sourceRoot":"","sources":["../../src/commands/typegen-artifact.ts"],"names":[],"mappings":"AAIA,0EAA0E;AAC1E,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,SAAS,CAAC;IACpE,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE,CAAC;AAEF,KAAK,kBAAkB,GACnB;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,4EAA4E;AAC5E,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAuC3E;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,kBAAkB,EAC/C,UAAU,GAAE,yBAA4C,GACvD,OAAO,CAAC,oBAAoB,CAAC,CAiB/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,yBAA4C,EACxD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,0BAA0B,CAAC,CA0BrC"}