@fluojs/cli 2.0.1 → 3.0.0

package/dist/commands/typegen-source.js

@@ -0,0 +1,183 @@
+import { existsSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { tsImport } from 'tsx/esm/api';
+import { TypegenCommandError } from './typegen-options.js';
+
+/** Dynamically loaded package surfaces required by typegen. */
+
+/** Structural artifact result returned by the React typegen package. */
+
+const TYPESCRIPT_MODULE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const TYPEGEN_MODULE_IDS = ['@fluojs/react', '@fluojs/react/typegen', '@fluojs/runtime'];
+const SILENT_APPLICATION_LOGGER = Object.freeze({
+  debug() {},
+  error() {},
+  log() {},
+  warn() {}
+});
+let applicationImportSequence = 0;
+function isModuleNotFoundError(error) {
+  return typeof error === 'object' && error !== null && 'code' in error && (error.code === 'MODULE_NOT_FOUND' || error.code === 'ERR_MODULE_NOT_FOUND');
+}
+async function importProjectModule(moduleId, cwd, tsconfig) {
+  const importOptions = [{
+    parentURL: pathToFileURL(resolve(cwd, 'package.json')).href,
+    tsconfig
+  }, {
+    parentURL: import.meta.url,
+    tsconfig: false
+  }];
+  for (const options of importOptions) {
+    try {
+      const imported = await tsImport(moduleId, options);
+      if (typeof imported !== 'object' || imported === null) {
+        throw new TypegenCommandError(`Resolved ${moduleId} to an invalid module namespace.`);
+      }
+      return imported;
+    } catch (error) {
+      if (!isModuleNotFoundError(error)) {
+        throw error;
+      }
+    }
+  }
+  throw new TypegenCommandError(`Unable to resolve ${moduleId} from the inspected project.`);
+}
+async function importTypeScriptApplicationModule(modulePath) {
+  const moduleUrl = pathToFileURL(modulePath).href;
+  const tsconfigPath = resolve(dirname(modulePath), 'tsconfig.json');
+  return existsSync(tsconfigPath) ? tsImport(moduleUrl, {
+    parentURL: import.meta.url,
+    tsconfig: tsconfigPath
+  }) : tsImport(moduleUrl, {
+    parentURL: import.meta.url,
+    tsconfig: false
+  });
+}
+function requireNamespace(owner, name) {
+  const value = Reflect.get(owner, name);
+  if (typeof value !== 'object' || value === null) {
+    throw new TypegenCommandError(`Required typegen namespace ${name} is unavailable.`);
+  }
+  return value;
+}
+async function importNativeApplicationModule(modulePath) {
+  applicationImportSequence += 1;
+  const source = `import * as application from ${JSON.stringify(pathToFileURL(modulePath).href)};\nexport { application };\n`;
+  const graphUrl = `data:text/javascript;charset=utf-8,${encodeURIComponent(source)}#fluo-typegen-${String(applicationImportSequence)}`;
+  const graph = await tsImport(graphUrl, import.meta.url);
+  return requireNamespace(graph, 'application');
+}
+function requireFunction(owner, name) {
+  const value = Reflect.get(owner, name);
+  if (typeof value !== 'function') {
+    throw new TypegenCommandError(`Required typegen function ${name} is unavailable.`);
+  }
+  return value;
+}
+
+/**
+ * Loads typegen package entrypoints from the consumer project or CLI installation.
+ *
+ * @param cwd Consumer project directory used for package resolution.
+ * @param tsconfig TypeScript configuration path, or `false` for native package resolution.
+ * @returns React, React typegen, and runtime module namespaces.
+ */
+export async function loadReactTypegenModules(cwd, tsconfig = false) {
+  const [react, typegen, runtime] = await Promise.all(TYPEGEN_MODULE_IDS.map(moduleId => importProjectModule(moduleId, cwd, tsconfig)));
+  return {
+    react,
+    runtime,
+    typegen
+  };
+}
+
+/**
+ * Bootstraps the selected module and generates source from authoritative route descriptors.
+ *
+ * @param options Parsed command, consumer directory, module namespaces, and native import boundary.
+ * @returns Complete deterministic generated source.
+ */
+export async function createTypegenSource(options) {
+  const modulePath = resolve(options.cwd, options.parsed.modulePath);
+  const importedApplication = TYPESCRIPT_MODULE_EXTENSIONS.has(extname(modulePath)) ? await importTypeScriptApplicationModule(modulePath) : await importNativeApplicationModule(modulePath);
+  return generateTypegenSource({
+    application: importedApplication,
+    modules: options.modules,
+    parsed: options.parsed
+  });
+}
+
+/**
+ * Generates source from one already-imported application and its matching tooling namespaces.
+ *
+ * @param options Application namespace, generation modules, and parsed command selection.
+ * @returns Complete deterministic generated source.
+ */
+export async function generateTypegenSource(options) {
+  const rootModule = Reflect.get(options.application, options.parsed.exportName);
+  if (typeof rootModule !== 'function') {
+    throw new TypegenCommandError(`Export "${options.parsed.exportName}" is not a module class constructor.`);
+  }
+  const factory = Reflect.get(options.modules.runtime, 'FluoFactory');
+  if (typeof factory !== 'function') {
+    throw new TypegenCommandError('Required runtime FluoFactory is unavailable.');
+  }
+  const application = await Reflect.apply(requireFunction(factory, 'create'), factory, [rootModule, {
+    logger: SILENT_APPLICATION_LOGGER
+  }]);
+  if (typeof application !== 'object' || application === null) {
+    throw new TypegenCommandError('Runtime application bootstrap returned an invalid value.');
+  }
+  const close = requireFunction(application, 'close');
+  try {
+    const dispatcher = Reflect.get(application, 'dispatcher');
+    if (typeof dispatcher !== 'object' || dispatcher === null) {
+      throw new TypegenCommandError('Runtime application dispatcher is unavailable.');
+    }
+    const descriptors = Reflect.apply(requireFunction(dispatcher, 'describeRoutes'), dispatcher, []);
+    if (!Array.isArray(descriptors)) {
+      throw new TypegenCommandError('Runtime route descriptors are unavailable.');
+    }
+    const catalog = Reflect.apply(requireFunction(options.modules.react, 'createReactPageCatalog'), undefined, [descriptors]);
+    const source = Reflect.apply(requireFunction(options.modules.typegen, 'generateReactPageTypes'), undefined, [catalog]);
+    if (typeof source !== 'string') {
+      throw new TypegenCommandError('React page typegen returned an invalid artifact.');
+    }
+    return source;
+  } finally {
+    await Reflect.apply(close, application, []);
+  }
+}
+
+/**
+ * Inspects an existing generated source value through the loaded React typegen package.
+ *
+ * @param modules Loaded React typegen module namespace.
+ * @param source Existing artifact source.
+ * @returns Parsed current, malformed, or unsupported-version status.
+ */
+export function inspectReactTypegenArtifact(modules, source) {
+  const inspection = Reflect.apply(requireFunction(modules.typegen, 'inspectReactPageTypeArtifact'), undefined, [source]);
+  if (typeof inspection !== 'object' || inspection === null || !('status' in inspection)) {
+    throw new TypegenCommandError('React page typegen artifact inspection returned an invalid result.');
+  }
+  if (inspection.status === 'malformed') {
+    return {
+      status: 'malformed'
+    };
+  }
+  if (inspection.status === 'unsupported-version' && 'version' in inspection && typeof inspection.version === 'number') {
+    return {
+      status: 'unsupported-version',
+      version: inspection.version
+    };
+  }
+  if (inspection.status === 'valid' && 'version' in inspection && typeof inspection.version === 'number') {
+    return {
+      status: 'valid',
+      version: inspection.version
+    };
+  }
+  throw new TypegenCommandError('React page typegen artifact inspection returned an invalid result.');
+}

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

@@ -0,0 +1,46 @@
+/** Scheduler used to debounce typegen filesystem bursts deterministically. */
+export type TypegenWatchScheduler = {
+    readonly clear: (handle: number) => void;
+    readonly set: (callback: () => void, delayMs: number) => number;
+};
+/** Signal registration boundary owned by one typegen watch invocation. */
+export type TypegenWatchSignalTarget = {
+    readonly off: (signal: 'SIGINT' | 'SIGTERM', listener: () => void) => unknown;
+    readonly once: (signal: 'SIGINT' | 'SIGTERM', listener: () => void) => unknown;
+};
+/** Minimal watcher resource acquired by typegen watch mode. */
+export type TypegenWatcher = {
+    close(): void;
+    on(event: 'error', listener: (error: Error) => void): TypegenWatcher;
+};
+/** One child generation owned by a typegen watch coordinator. */
+export type TypegenWatchGeneration = {
+    cancel(): void;
+    readonly result: Promise<string>;
+};
+type TypegenWatchTarget = (target: string, options: {
+    readonly persistent: boolean;
+    readonly recursive: boolean;
+}, listener: (event: string, filename: string | Buffer | null) => void) => TypegenWatcher;
+/** Dependencies and callbacks for one bounded typegen watch lifecycle. */
+export type TypegenWatchOptions = {
+    readonly commit: (source: string, signal: AbortSignal) => Promise<void>;
+    readonly debounceMs?: number;
+    readonly modulePath: string;
+    readonly onError?: (error: unknown) => void;
+    readonly onReady?: (watchRoot: string) => void;
+    readonly outputPath: string;
+    readonly scheduler?: TypegenWatchScheduler;
+    readonly signalTarget?: TypegenWatchSignalTarget;
+    readonly startGeneration: () => TypegenWatchGeneration;
+    readonly watchTarget?: TypegenWatchTarget;
+};
+/**
+ * Watches the application module directory while generating an initial current artifact.
+ *
+ * @param options Generation, watcher, scheduler, and signal lifecycle dependencies.
+ * @returns Exit code `0` after signal shutdown or `1` after an asynchronous watcher failure.
+ */
+export declare function runTypegenWatch(options: TypegenWatchOptions): Promise<number>;
+export {};
+//# sourceMappingURL=typegen-watch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typegen-watch.d.ts","sourceRoot":"","sources":["../../src/commands/typegen-watch.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACjE,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;IAC9E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;CAChF,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,IAAI,IAAI,CAAC;IACd,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,cAAc,CAAC;CACtE,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,KAAK,kBAAkB,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EACtE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,KAChE,cAAc,CAAC;AAEpB,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,sBAAsB,CAAC;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAC3C,CAAC;AAwCF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0KnF"}

package/dist/commands/typegen-watch.js

@@ -0,0 +1,212 @@
+import { watch } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+
+/** Scheduler used to debounce typegen filesystem bursts deterministically. */
+
+/** Signal registration boundary owned by one typegen watch invocation. */
+
+/** Minimal watcher resource acquired by typegen watch mode. */
+
+/** One child generation owned by a typegen watch coordinator. */
+
+/** Dependencies and callbacks for one bounded typegen watch lifecycle. */
+
+const DEFAULT_DEBOUNCE_MS = 100;
+function createDefaultScheduler() {
+  let sequence = 0;
+  const timers = new Map();
+  return {
+    clear(handle) {
+      const timer = timers.get(handle);
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timers.delete(handle);
+      }
+    },
+    set(callback, delayMs) {
+      sequence += 1;
+      const handle = sequence;
+      const timer = setTimeout(() => {
+        timers.delete(handle);
+        callback();
+      }, delayMs);
+      timers.set(handle, timer);
+      return handle;
+    }
+  };
+}
+const defaultWatchTarget = (target, options, listener) => watch(target, options, listener);
+function isOwnArtifactEvent(changedPath, outputPath) {
+  if (changedPath === outputPath) {
+    return true;
+  }
+  const changedName = basename(changedPath);
+  const outputName = basename(outputPath);
+  return changedName.startsWith(`.${outputName}.`) && changedName.endsWith('.tmp');
+}
+
+/**
+ * Watches the application module directory while generating an initial current artifact.
+ *
+ * @param options Generation, watcher, scheduler, and signal lifecycle dependencies.
+ * @returns Exit code `0` after signal shutdown or `1` after an asynchronous watcher failure.
+ */
+export async function runTypegenWatch(options) {
+  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const onError = options.onError ?? (() => undefined);
+  const scheduler = options.scheduler ?? createDefaultScheduler();
+  const signalTarget = options.signalTarget ?? process;
+  const watchTarget = options.watchTarget ?? defaultWatchTarget;
+  const watchRoot = dirname(options.modulePath);
+  let activeCommit;
+  let activeGeneration;
+  let cleanedUp = false;
+  let rerunRequested = false;
+  let resolved = false;
+  let restartTimer;
+  let stopping = false;
+  let stopCode = 0;
+  let watcher;
+  let startupComplete = false;
+  let resolveResult = () => undefined;
+  const result = new Promise(resolvePromise => {
+    resolveResult = resolvePromise;
+  });
+  const cleanup = () => {
+    if (cleanedUp) {
+      return;
+    }
+    cleanedUp = true;
+    if (restartTimer !== undefined) {
+      scheduler.clear(restartTimer);
+      restartTimer = undefined;
+    }
+    watcher?.close();
+    signalTarget.off('SIGINT', stopForSignal);
+    signalTarget.off('SIGTERM', stopForSignal);
+  };
+  const settleIfIdle = () => {
+    if (!stopping || activeGeneration !== undefined || resolved) {
+      return;
+    }
+    resolved = true;
+    resolveResult(stopCode);
+  };
+  const stop = code => {
+    stopCode = Math.max(stopCode, code);
+    if (!stopping) {
+      stopping = true;
+      cleanup();
+      activeCommit?.abort();
+      activeGeneration?.cancel();
+    }
+    settleIfIdle();
+  };
+  function stopForSignal() {
+    stop(0);
+  }
+  const runGeneration = async reportError => {
+    let generation;
+    try {
+      generation = options.startGeneration();
+      activeGeneration = generation;
+      const source = await generation.result;
+      if (!stopping && !rerunRequested) {
+        const commit = new AbortController();
+        activeCommit = commit;
+        try {
+          await options.commit(source, commit.signal);
+        } finally {
+          if (activeCommit === commit) {
+            activeCommit = undefined;
+          }
+        }
+      }
+    } catch (error) {
+      if (stopping || rerunRequested) {
+        return;
+      }
+      if (reportError) {
+        onError(error);
+        return;
+      }
+      throw error;
+    } finally {
+      if (activeGeneration === generation) {
+        activeGeneration = undefined;
+        settleIfIdle();
+      }
+    }
+  };
+  const regenerate = () => {
+    if (stopping) {
+      return;
+    }
+    if (activeGeneration !== undefined) {
+      rerunRequested = true;
+      return;
+    }
+    void (async () => {
+      do {
+        rerunRequested = false;
+        await runGeneration(true);
+      } while (rerunRequested && !stopping);
+    })();
+  };
+  const scheduleRegeneration = changedPath => {
+    if (stopping || isOwnArtifactEvent(changedPath, options.outputPath)) {
+      return;
+    }
+    if (activeGeneration !== undefined) {
+      rerunRequested = true;
+      activeCommit?.abort();
+      return;
+    }
+    if (!startupComplete) {
+      rerunRequested = true;
+      return;
+    }
+    if (restartTimer !== undefined) {
+      scheduler.clear(restartTimer);
+    }
+    restartTimer = scheduler.set(() => {
+      restartTimer = undefined;
+      regenerate();
+    }, debounceMs);
+  };
+  try {
+    watcher = watchTarget(watchRoot, {
+      persistent: true,
+      recursive: true
+    }, (_event, filename) => {
+      const changedPath = filename === null ? watchRoot : resolve(watchRoot, String(filename));
+      scheduleRegeneration(changedPath);
+    });
+    watcher.on('error', error => {
+      onError(error);
+      stop(1);
+    });
+  } catch (error) {
+    watcher?.close();
+    throw error;
+  }
+  try {
+    signalTarget.once('SIGINT', stopForSignal);
+    signalTarget.once('SIGTERM', stopForSignal);
+    await (async () => {
+      do {
+        rerunRequested = false;
+        await runGeneration(false);
+      } while (rerunRequested && !stopping);
+    })();
+    startupComplete = true;
+    if (stopping) {
+      return result;
+    }
+    options.onReady?.(watchRoot);
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+  return result;
+}

package/dist/commands/typegen.d.ts

@@ -0,0 +1,29 @@
+import { type ReactTypegenModules } from './typegen-source.js';
+type CliStream = {
+    write(message: string): unknown;
+};
+/** Runtime options for the React page typegen command. */
+export interface TypegenCommandRuntimeOptions {
+    /** Current working directory for module and output path resolution. */
+    readonly cwd?: string;
+    /**
+     * Optional build-tooling module loader override for tests and editor integrations.
+     * Supplying it keeps application evaluation in the caller process and uses the returned
+     * namespaces for TypeScript and native modules; omitting it uses isolated generation children.
+     */
+    readonly loadReactTypegenModules?: (cwd: string) => Promise<ReactTypegenModules>;
+    /** Custom stream for error output. */
+    readonly stderr?: CliStream;
+    /** Custom stream for standard output. */
+    readonly stdout?: CliStream;
+}
+/**
+ * Generates, checks, or watches one application-owned React page type artifact.
+ *
+ * @param argv Command arguments after `typegen`.
+ * @param runtime Runtime overrides for module loading and output streams.
+ * @returns Process-style command exit code.
+ */
+export declare function runTypegenCommand(argv: readonly string[], runtime?: TypegenCommandRuntimeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=typegen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typegen.d.ts","sourceRoot":"","sources":["../../src/commands/typegen.ts"],"names":[],"mappings":"AAcA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAI7B,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,4BAA4B;IAC3C,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACjF,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AA+BD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,MAAM,CAAC,CA2EjB"}

package/dist/commands/typegen.js

@@ -0,0 +1,119 @@
+import { resolve } from 'node:path';
+import { TYPEGEN_EXIT_CODES } from '../typegen-contract.js';
+import { typegenUsage } from '../usage.js';
+import { checkTypegenArtifact, writeTypegenArtifact } from './typegen-artifact.js';
+import { runTypegenGenerationProcess, startTypegenGenerationProcess } from './typegen-generation-process.js';
+import { parseTypegenArgs, TypegenCommandError } from './typegen-options.js';
+import { createTypegenSource, inspectReactTypegenArtifact, loadReactTypegenModules } from './typegen-source.js';
+import { runTypegenWatch } from './typegen-watch.js';
+import { assertOutputDoesNotAliasModule } from './output-path-safety.js';
+
+/** Runtime options for the React page typegen command. */
+
+function reportCheckResult(check, outputPath, stdout, stderr) {
+  switch (check.status) {
+    case 'UNCHANGED':
+      stdout.write(`UNCHANGED ${outputPath}\n`);
+      return TYPEGEN_EXIT_CODES.SUCCESS;
+    case 'MISSING':
+      stderr.write(`MISSING ${outputPath}: run fluo typegen without --check to create the artifact.\n`);
+      return TYPEGEN_EXIT_CODES.MISSING;
+    case 'STALE':
+      stderr.write(`STALE ${outputPath}: generated React page types differ from the authoritative compiled catalog.\n`);
+      return TYPEGEN_EXIT_CODES.STALE;
+    case 'MALFORMED':
+      stderr.write(`MALFORMED ${outputPath}: the target is not a complete React page typegen artifact.\n`);
+      return TYPEGEN_EXIT_CODES.MALFORMED;
+    case 'UNSUPPORTED_VERSION':
+      stderr.write(`UNSUPPORTED_VERSION ${outputPath}: artifact version ${String(check.version)} is not supported by this CLI.\n`);
+      return TYPEGEN_EXIT_CODES.UNSUPPORTED_VERSION;
+    default:
+      {
+        const unreachable = check;
+        throw new TypegenCommandError(`Unexpected typegen check result: ${String(unreachable)}`);
+      }
+  }
+}
+
+/**
+ * Generates, checks, or watches one application-owned React page type artifact.
+ *
+ * @param argv Command arguments after `typegen`.
+ * @param runtime Runtime overrides for module loading and output streams.
+ * @returns Process-style command exit code.
+ */
+export async function runTypegenCommand(argv, runtime = {}) {
+  const cwd = runtime.cwd ?? process.cwd();
+  const stdout = runtime.stdout ?? process.stdout;
+  const stderr = runtime.stderr ?? process.stderr;
+  try {
+    if (argv.some(argument => argument === '--help' || argument === '-h')) {
+      stdout.write(`${typegenUsage()}\n`);
+      return 0;
+    }
+    const parsed = parseTypegenArgs(argv);
+    const modulePath = resolve(cwd, parsed.modulePath);
+    const outputPath = resolve(cwd, parsed.outputPath);
+    await assertOutputDoesNotAliasModule(modulePath, outputPath);
+    const customModules = runtime.loadReactTypegenModules?.(cwd);
+    const generateSource = async () => customModules === undefined ? runTypegenGenerationProcess({
+      cwd,
+      exportName: parsed.exportName,
+      modulePath: parsed.modulePath
+    }) : createTypegenSource({
+      cwd,
+      modules: await customModules,
+      parsed
+    });
+    if (parsed.watch) {
+      return await runTypegenWatch({
+        async commit(source, signal) {
+          const action = await writeTypegenArtifact(outputPath, source, undefined, signal);
+          stdout.write(`${action} ${outputPath}\n`);
+        },
+        modulePath,
+        onError(error) {
+          stderr.write(`ERROR ${outputPath}: ${error instanceof Error ? error.message : String(error)}\n`);
+        },
+        onReady(watchRoot) {
+          stdout.write(`WATCHING ${watchRoot}\n`);
+        },
+        outputPath,
+        startGeneration: customModules === undefined ? () => startTypegenGenerationProcess({
+          cwd,
+          exportName: parsed.exportName,
+          modulePath: parsed.modulePath
+        }) : () => {
+          let cancelled = false;
+          const result = generateSource().then(source => {
+            if (cancelled) {
+              throw new TypegenCommandError('Typegen generation was cancelled.');
+            }
+            return source;
+          });
+          return {
+            cancel() {
+              if (cancelled) {
+                return;
+              }
+              cancelled = true;
+            },
+            result
+          };
+        }
+      });
+    }
+    const source = await generateSource();
+    if (parsed.check) {
+      const modules = customModules === undefined ? await loadReactTypegenModules(cwd) : await customModules;
+      const check = await checkTypegenArtifact(outputPath, source, existingSource => inspectReactTypegenArtifact(modules, existingSource));
+      return reportCheckResult(check, outputPath, stdout, stderr);
+    }
+    const action = await writeTypegenArtifact(outputPath, source);
+    stdout.write(`${action} ${outputPath}\n`);
+    return TYPEGEN_EXIT_CODES.SUCCESS;
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return TYPEGEN_EXIT_CODES.ERROR;
+  }
+}

package/dist/dev-runner/node-restart-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-restart-runner.d.ts","sourceRoot":"","sources":["../../src/dev-runner/node-restart-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAA0D,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAKjG,KAAK,mBAAmB,GAAG;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,KAAK,YAAY,CAAC;AACjJ,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,oBAAoB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E,KAAK,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1C,KAAK,mBAAmB,GAAG;IACzB,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAC1D,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAC5D,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,KAAK,SAAS,CAAC;AAE1O,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,MAAM,CAAC;AAErE,KAAK,gBAAgB,GAAG;IACtB,KAAK,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC5C,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAAC;CACpE,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;CACvD,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC;AA6NF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAE,MAAM,EAAoB,GAAG,iBAAiB,CAuB/H;AAkFD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoP7F"}
+{"version":3,"file":"node-restart-runner.d.ts","sourceRoot":"","sources":["../../src/dev-runner/node-restart-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAc,KAAK,SAAS,EAA8C,MAAM,SAAS,CAAC;AAKjG,KAAK,mBAAmB,GAAG;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,KAAK,YAAY,CAAC;AACjJ,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,oBAAoB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E,KAAK,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1C,KAAK,mBAAmB,GAAG;IACzB,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAC1D,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAC5D,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,KAAK,SAAS,CAAC;AAE1O,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,MAAM,CAAC;AAErE,KAAK,gBAAgB,GAAG;IACtB,KAAK,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC5C,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAAC;CACpE,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;CACvD,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC;AA6NF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAE,MAAM,EAAoB,GAAG,iBAAiB,CAuB/H;AAkFD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwS7F"}