@fluojs/cli 1.1.0 → 3.0.0

package/dist/commands/new.d.ts

@@ -17,12 +17,6 @@ export interface NewCommandRuntimeOptions extends NewCommandOptions {
     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.
  *

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

@@ -1 +1 @@
-{"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"}
+{"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,12 +1,11 @@
 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';
+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) {
   return runtime.prompt === undefined && runtime.stdout === undefined && runtime.stderr === undefined && (runtime.interactive ?? true) && Boolean(runtime.stdin?.isTTY ?? process.stdin.isTTY);
 }
@@ -20,78 +19,22 @@ function extractDependencyInstallationOutput(error) {
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
+function readInternalScaffoldOverrides(runtime) {
+  const dependencySource = 'dependencySource' in runtime ? runtime.dependencySource : undefined;
+  const repoRoot = 'repoRoot' in runtime ? runtime.repoRoot : undefined;
+  return {
+    dependencySource: dependencySource === 'local' || dependencySource === 'published' ? dependencySource : undefined,
+    repoRoot: typeof repoRoot === 'string' ? repoRoot : undefined
+  };
+}
 
 /**
  * Runtime dependency overrides for the programmatic `fluo new` entry point.
  */
 
-const NEW_OPTION_HELP = [{
-  aliases: [],
-  description: 'Provide the project name without using the positional argument.',
-  option: '--name <project-name>'
-}, {
-  aliases: [],
-  description: 'Select the scaffold shape explicitly (application for HTTP, microservice for the transport-driven starter path, mixed for the API + microservice starter).',
-  option: '--shape <application|microservice|mixed>'
-}, {
-  aliases: [],
-  description: 'Select the transport path explicitly (http for applications, tcp for the runnable microservice starter, plus shipped microservice starter transports).',
-  option: '--transport <http|tcp|redis-streams|nats|kafka|rabbitmq|mqtt|grpc>'
-}, {
-  aliases: [],
-  description: 'Select the runtime explicitly (node, bun, deno, or cloudflare-workers for application starters; node for microservice and mixed starters).',
-  option: '--runtime <node|bun|deno|cloudflare-workers>'
-}, {
-  aliases: [],
-  description: 'Select the platform adapter explicitly (fastify, express, or nodejs on node; bun/deno/cloudflare-workers on their native runtimes; none for microservices).',
-  option: '--platform <fastify|express|nodejs|bun|deno|cloudflare-workers|none>'
-}, {
-  aliases: [],
-  description: 'Select the starter tooling preset explicitly (currently only standard).',
-  option: '--tooling <standard>'
-}, {
-  aliases: [],
-  description: 'Select the starter topology mode explicitly (currently only single-package).',
-  option: '--topology <single-package>'
-}, {
-  aliases: [],
-  description: 'Choose which package manager installs the starter dependencies.',
-  option: '--package-manager <pnpm|npm|yarn|bun>'
-}, {
-  aliases: [],
-  description: 'Write the new app to a custom target directory (always overrides positional name path).',
-  option: '--target-directory <path>'
-}, {
-  aliases: [],
-  description: 'Overwrite files in a non-empty target directory without prompting.',
-  option: '--force'
-}, {
-  aliases: [],
-  description: 'Install starter dependencies after writing files.',
-  option: '--install'
-}, {
-  aliases: [],
-  description: 'Skip starter dependency installation.',
-  option: '--no-install'
-}, {
-  aliases: [],
-  description: 'Initialize a git repository in the generated starter.',
-  option: '--git'
-}, {
-  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.',
-  option: '--help'
-}];
 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);
@@ -143,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.');
@@ -246,25 +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');
-}
-
-/**
- * Renders CLI help text for `fluo new`.
- *
- * @returns Stable help output for the scaffolding command.
- */
-export function newUsage() {
-  return ['Usage: fluo new|create [project-name] [options]', '', 'Options', renderHelpTable(NEW_OPTION_HELP, [{
-    header: 'Option',
-    render: entry => entry.option
-  }, {
-    header: 'Aliases',
-    render: entry => renderAliasList(entry.aliases)
-  }, {
-    header: 'Description',
-    render: entry => entry.description
-  }]), '', 'Next steps:', '  cd <app-name>', '  pnpm dev  # runs fluo dev from the generated package.json script', '', 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/quick-start.md'].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');
 }
 
 /**
@@ -301,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
@@ -313,24 +252,26 @@ export async function runNewCommand(argv, runtime = {}) {
       stdout.write(`${renderScaffoldPlanPreview(answers, targetDirectory)}\n`);
       return 0;
     }
+    const internalScaffoldOverrides = readInternalScaffoldOverrides(runtime);
     const options = {
       ...answers,
-      dependencySource: runtime.dependencySource,
+      dependencySource: internalScaffoldOverrides.dependencySource,
       force: parsed.force ?? runtime.force,
       initializeGit: answers.initializeGit,
       installDependencies: false,
-      repoRoot: runtime.repoRoot,
+      repoRoot: internalScaffoldOverrides.repoRoot,
       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) {
@@ -343,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, {
@@ -361,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.d.ts

@@ -1,4 +1,4 @@
-import { startStudioSidecar } from '../studio/sidecar.js';
+import type { startStudioSidecar } from '../studio/sidecar.js';
 type CliStream = {
     isTTY?: boolean;
     write(message: string): unknown;

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

@@ -1 +1 @@
-{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/commands/scripts.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAiD,MAAM,sBAAsB,CAAC;AAGzG,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAMF,KAAK,mBAAmB,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClG,kBAAkB,CAAC,EAAE,OAAO,kBAAkB,CAAC;IAC/C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAGF,KAAK,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AA2lB/C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAqB1D;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsFlI"}
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/commands/scripts.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,sBAAsB,CAAC;AAGpG,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAMF,KAAK,mBAAmB,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClG,kBAAkB,CAAC,EAAE,OAAO,kBAAkB,CAAC;IAC/C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAKF,KAAK,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAkmB/C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAqB1D;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsFlI"}

package/dist/commands/scripts.js

@@ -3,7 +3,6 @@ import { existsSync, readFileSync } from 'node:fs';
 import { delimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createStudioDevtoolsNodeImport } from '../studio/runtime-config.js';
-import { startStudioSidecar } from '../studio/sidecar.js';
 import { SUPPORTED_PACKAGE_MANAGERS } from './package-manager.js';
 const EMPTY_ENV = {};
 const FAILURE_STDOUT_BUFFER_LIMIT = 16_384;
@@ -119,6 +118,12 @@ function defaultSpawnCommand(command, args, options) {
     child.on('close', code => resolveExitCode(code ?? 1));
   });
 }
+async function loadDefaultStudioSidecarFactory() {
+  const {
+    startStudioSidecar: startStudioSidecarImplementation
+  } = await import('../studio/sidecar.js');
+  return startStudioSidecarImplementation;
+}
 function buildNativeNodeWatchStep(passThrough) {
   return {
     command: 'node',
@@ -398,13 +403,14 @@ 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.');
   }
 }
-function withStudioDryRunEnv(env, project, projectRuntime) {
+function withStudioDryRunEnv(env, project, projectRuntime, studioPort) {
+  const portLabel = studioPort === undefined ? '<auto>' : String(studioPort);
   return {
     ...env,
     FLUO_STUDIO: '1',
@@ -412,7 +418,7 @@ function withStudioDryRunEnv(env, project, projectRuntime) {
     FLUO_STUDIO_EPOCH: '<generated-at-runtime>',
     FLUO_STUDIO_RUNTIME: projectRuntimeToStudioRuntime(projectRuntime),
     FLUO_STUDIO_TOKEN: '<generated-at-runtime>',
-    FLUO_STUDIO_URL: 'http://127.0.0.1:<auto>'
+    FLUO_STUDIO_URL: `http://127.0.0.1:${portLabel}`
   };
 }
 function renderStep(step) {
@@ -591,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');
 }
 
 /**
@@ -635,10 +641,10 @@ export async function runScriptCommand(command, argv, runtime = {}) {
   const verbose = parsed.verbose || isEnabledEnvironmentFlag(env.FLUO_VERBOSE);
   let childEnv = withPipedReporterColorEnv(withProjectLocalBin(withDefaultNodeEnv(env, defaultNodeEnv), project.directory), reporterMode, stdout, stderr);
   if (parsed.studio && parsed.dryRun) {
-    childEnv = withStudioDryRunEnv(childEnv, project, projectRuntime);
+    childEnv = withStudioDryRunEnv(childEnv, project, projectRuntime, parsed.studioPort);
   }
   if (command === 'dev' && parsed.studio && !parsed.dryRun) {
-    const studioSidecarFactory = runtime.startStudioSidecar ?? startStudioSidecar;
+    const studioSidecarFactory = runtime.startStudioSidecar ?? (await loadDefaultStudioSidecarFactory());
     const studioSidecar = await studioSidecarFactory({
       appId: projectDisplayName(project),
       port: parsed.studioPort,

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"}

package/dist/commands/typegen-artifact.js

@@ -0,0 +1,117 @@
+import { renameSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+/** Filesystem boundary used by deterministic typegen artifact commits. */
+
+/** Stable non-mutating comparison result for an existing typegen target. */
+
+/** Stable write action reported after an atomic typegen artifact commit. */
+
+const NODE_FILE_SYSTEM = {
+  async mkdir(path) {
+    await mkdir(path, {
+      recursive: true
+    });
+  },
+  readFile: path => readFile(path, 'utf8'),
+  rename(source, destination) {
+    renameSync(source, destination);
+    return undefined;
+  },
+  async rm(path) {
+    await rm(path, {
+      force: true
+    });
+  },
+  async writeFile(path, content) {
+    await writeFile(path, content, {
+      encoding: 'utf8',
+      flag: 'wx'
+    });
+  }
+};
+let temporaryFileSequence = 0;
+function isMissingFileError(error) {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+async function readExistingArtifact(outputPath, fileSystem) {
+  try {
+    return await fileSystem.readFile(outputPath);
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * 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 async function checkTypegenArtifact(outputPath, expectedSource, inspect, fileSystem = NODE_FILE_SYSTEM) {
+  const existingSource = await readExistingArtifact(outputPath, fileSystem);
+  if (existingSource === undefined) {
+    return {
+      status: 'MISSING'
+    };
+  }
+  if (existingSource === expectedSource) {
+    return {
+      status: 'UNCHANGED'
+    };
+  }
+  const inspection = inspect(existingSource);
+  if (inspection.status === 'malformed') {
+    return {
+      status: 'MALFORMED'
+    };
+  }
+  if (inspection.status === 'unsupported-version') {
+    return {
+      status: 'UNSUPPORTED_VERSION',
+      version: inspection.version
+    };
+  }
+  return {
+    status: 'STALE'
+  };
+}
+
+/**
+ * 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 async function writeTypegenArtifact(outputPath, source, fileSystem = NODE_FILE_SYSTEM, signal) {
+  signal?.throwIfAborted();
+  const existingSource = await readExistingArtifact(outputPath, fileSystem);
+  if (existingSource === source) {
+    return 'UNCHANGED';
+  }
+  await fileSystem.mkdir(dirname(outputPath));
+  temporaryFileSequence += 1;
+  const temporaryPath = join(dirname(outputPath), `.${basename(outputPath)}.${String(process.pid)}.${String(temporaryFileSequence)}.tmp`);
+  let committed = false;
+  try {
+    await fileSystem.writeFile(temporaryPath, source);
+    signal?.throwIfAborted();
+    fileSystem.rename(temporaryPath, outputPath);
+    committed = true;
+  } finally {
+    if (!committed) {
+      await fileSystem.rm(temporaryPath);
+    }
+  }
+  return existingSource === undefined ? 'CREATE' : 'UPDATE';
+}

package/dist/commands/typegen-generation-child.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=typegen-generation-child.d.ts.map

package/dist/commands/typegen-generation-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen-generation-child.d.ts","sourceRoot":"","sources":["../../src/commands/typegen-generation-child.ts"],"names":[],"mappings":""}

package/dist/commands/typegen-generation-child.js

@@ -0,0 +1,59 @@
+import { createProcessIsolatedTypegenSource } from './typegen-isolated-source.js';
+import { TypegenCommandError } from './typegen-options.js';
+function readGenerationArgs() {
+  const [cwd, modulePath, exportName] = process.argv.slice(2);
+  if (cwd === undefined || modulePath === undefined || exportName === undefined) {
+    throw new TypegenCommandError('Typegen generation process received incomplete arguments.');
+  }
+  return {
+    cwd,
+    exportName,
+    modulePath
+  };
+}
+function sendGenerationMessage(message) {
+  if (process.send === undefined) {
+    throw new TypegenCommandError('Typegen generation process requires an IPC channel.');
+  }
+  const send = process.send.bind(process);
+  return new Promise((resolve, reject) => {
+    send(message, error => {
+      if (error === null) {
+        resolve();
+        return;
+      }
+      reject(error);
+    });
+  });
+}
+async function runGenerationChild() {
+  let message;
+  try {
+    const request = readGenerationArgs();
+    const parsed = {
+      check: false,
+      exportName: request.exportName,
+      modulePath: request.modulePath,
+      outputPath: '',
+      watch: false
+    };
+    message = {
+      kind: 'source',
+      source: await createProcessIsolatedTypegenSource(parsed, request.cwd)
+    };
+  } catch (error) {
+    process.exitCode = 1;
+    message = {
+      kind: 'error',
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+  try {
+    await sendGenerationMessage(message);
+  } finally {
+    if (process.connected) {
+      process.disconnect();
+    }
+  }
+}
+await runGenerationChild();