@rozie/cli 0.1.0

package/src/commands/watch.ts

@@ -0,0 +1,407 @@
+// `rozie watch` subcommand — chokidar-driven incremental recompile.
+//
+// Mirrors `rozie build`'s flag surface (--target, --out, --source-map,
+// --no-types) but is long-running. Intended for a component-library
+// author iterating on a .rozie file while a live framework dev server
+// in another terminal consumes the emitted .tsx/.vue/.svelte/etc.
+//
+// Key behaviours (modelled on `tsc --watch` / `vite build --watch`):
+//   • Always requires --out (no sense streaming to stdout from a daemon).
+//   • Initial build runs the full input set once, so output exists when
+//     the watcher arms; subsequent compiles are per-changed-file only.
+//   • Debounced via chokidar's awaitWriteFinish (text editors fire
+//     multiple events per save; 100 ms stability avoids spurious
+//     re-compiles).
+//   • Per-change log lines are timestamped + colourised; errors render
+//     full diagnostic frames but DON'T tear the watcher down (tsc
+//     --watch's behaviour — keep watching past compile errors).
+//   • Graceful exit on SIGINT/SIGTERM: closes the watcher, prints a
+//     "stopped" line, resolves runWatch() with exit code 0.
+//
+// The compile + write phase intentionally duplicates a small slice of
+// build.ts (~30 lines) instead of refactoring out a shared writer.
+// Drift risk is low (both call the same `compile()` core; the only
+// per-target sidecar logic is React's .d.ts / .css / .global.css,
+// which is stable). If the per-target sidecar matrix grows, the next
+// editor of either file should hoist the shared helper.
+import chokidar from 'chokidar';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname as pathDirname, resolve as pathResolve } from 'node:path';
+import pc from 'picocolors';
+import { compile } from '../../../core/src/compile.js';
+import { renderDiagnostic } from '../../../core/src/diagnostics/frame.js';
+// Phase 22 Plan 22-05 — CLI sidecar fallback (REQ-5): refresh the
+// `.d.rozie.ts` per changed file via the SAME renderer the unplugin + build
+// command use, so the watch-mode sidecar bytes don't drift.
+import { renderSidecar } from '../../../unplugin/src/emitSidecar.js';
+import { expandInputs } from '../utils/expandInputs.js';
+import { computeOutputPath, TARGET_EXTENSIONS } from '../utils/outputPath.js';
+import type { Target } from '../utils/parseTargets.js';
+import { prettyFormat } from '../utils/prettyFormat.js';
+
+export interface WatchOptions {
+  target?: Target | Target[];
+  out?: string;
+  /** D-91 default false. */
+  sourceMap?: boolean;
+  /** D-90 default true. */
+  types?: boolean;
+  /** Project root for source-rel-path computation; defaults to process.cwd(). */
+  root?: string;
+  /**
+   * Off by default per PROJECT.md "Out of Scope" carve-out. Pipes the
+   * per-change emit through prettier before write. Failures degrade
+   * gracefully — raw output still lands on disk + a stderr warning fires.
+   */
+  pretty?: boolean;
+  /**
+   * Phase 23 — Angular-only opt-out for the auto `ControlValueAccessor` emit.
+   * Default ON; `false` maps to `compile({ angular: { cva: false } })`.
+   * Mirrors the `rozie build` flag. No-op for non-Angular targets.
+   */
+  cva?: boolean;
+  /**
+   * Phase 26 (D-11) — the GLOBAL safe-interpolation opt-out. Default ON;
+   * `false` maps to `compile({ safeInterpolation: false })`. Mirrors the
+   * `rozie build` flag. No-op for the Vue target.
+   */
+  safeInterpolation?: boolean;
+}
+
+export interface RunWatchContext {
+  /** When 'throw', invalid-arg exits become thrown errors (vitest-friendly). */
+  exit?: 'process' | 'throw';
+  stderrWrite?: (chunk: string) => void;
+  stdoutWrite?: (chunk: string) => void;
+  /**
+   * Test injection — when this AbortSignal fires, the watcher closes and
+   * runWatch() resolves. Lets vitest drive the lifecycle without sending
+   * real OS signals to the test process.
+   */
+  signal?: AbortSignal;
+}
+
+const VALID_TARGETS = new Set<Target>(['vue', 'react', 'svelte', 'angular', 'solid', 'lit']);
+
+/**
+ * Compact HH:MM:SS timestamp for log lines. en-US 24h matches what
+ * `tsc --watch` does and reads cleanly in PR screenshots.
+ */
+function ts(): string {
+  return new Date().toLocaleTimeString('en-US', { hour12: false });
+}
+
+/**
+ * `rozie watch <inputs...>` entry point. Performs one initial build of
+ * the matched input set, then watches for changes and recompiles per
+ * file. Resolves on graceful shutdown (SIGINT/SIGTERM or ctx.signal).
+ */
+export async function runWatch(
+  inputArgs: string[],
+  opts: WatchOptions = {},
+  ctx: RunWatchContext = {},
+): Promise<void> {
+  const stderrWrite = ctx.stderrWrite ?? ((s) => void process.stderr.write(s));
+  const stdoutWrite = ctx.stdoutWrite ?? ((s) => void process.stdout.write(s));
+
+  const exit = (code: number, msg = ''): never => {
+    if (msg) stderrWrite(msg);
+    if (ctx.exit === 'throw') {
+      throw new Error(`rozie watch exited with code ${code}: ${msg.trim()}`);
+    }
+    process.exit(code);
+  };
+
+  // ----- Normalize + validate the target list --------------------------
+  const targets: Target[] = Array.isArray(opts.target)
+    ? opts.target
+    : opts.target !== undefined
+      ? [opts.target as Target]
+      : ['vue'];
+
+  for (const t of targets) {
+    if (!VALID_TARGETS.has(t)) {
+      return exit(
+        2,
+        pc.red(
+          `[ROZ850] rozie watch: unknown target '${t}' (expected vue|react|svelte|angular|solid|lit)\n`,
+        ),
+      );
+    }
+  }
+
+  // ----- --out is REQUIRED for watch -----------------------------------
+  // A long-running watcher cannot stream to stdout; nothing useful would
+  // consume the unending sequence of per-change compile outputs.
+  if (opts.out === undefined) {
+    return exit(
+      2,
+      pc.red(
+        `[ROZ856] rozie watch: --out <dir> is required (cannot stream to stdout from a long-running watcher)\n`,
+      ),
+    );
+  }
+
+  const outDir = pathResolve(opts.out);
+  const rootDir = opts.root ?? process.cwd();
+  const wantTypes = opts.types !== false;
+  const wantSourceMap = opts.sourceMap === true;
+  const wantPretty = opts.pretty === true;
+  const cvaOff = opts.cva === false; // Phase 23 — Angular CVA opt-out
+  const safeInterpOff = opts.safeInterpolation === false; // Phase 26 — opt-out
+
+  // ----- Initial expansion + build -------------------------------------
+  let inputs: string[];
+  try {
+    inputs = await expandInputs(inputArgs);
+  } catch (err) {
+    return exit(1, pc.red(`${(err as Error).message}\n`));
+  }
+
+  if (inputs.length === 0) {
+    return exit(
+      1,
+      pc.red(`[ROZ851] rozie watch: no .rozie files matched the given inputs\n`),
+    );
+  }
+
+  for (const input of inputs) {
+    await compileOne(input, targets, outDir, rootDir, wantTypes, wantSourceMap, wantPretty, cvaOff, safeInterpOff, stderrWrite, stdoutWrite);
+  }
+
+  stdoutWrite(
+    pc.cyan(
+      `[${ts()}] watching ${inputs.length} file(s) for ${targets.join('+')} (Ctrl-C to stop)\n`,
+    ),
+  );
+
+  // ----- Watcher setup -------------------------------------------------
+  // Pass the raw input args through to chokidar — it handles files, dirs,
+  // and globs natively (same way fast-glob did in expandInputs). For dir
+  // args, chokidar recurses by default, so newly-added .rozie files are
+  // picked up too. `ignoreInitial: true` is important: the initial build
+  // loop above already emitted everything, so we don't want chokidar's
+  // own initial scan to re-fire 'add' events for them.
+  //
+  // awaitWriteFinish coalesces editor-save bursts (Vim/Helix/VSCode all
+  // emit multiple write events per save). 100 ms stability is the
+  // standard tsc/vite tuning.
+  const watcher = chokidar.watch(inputArgs, {
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 30 },
+    ignoreInitial: true,
+    ignored: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.git/**',
+      '**/.turbo/**',
+      '**/.planning/**',
+    ],
+  });
+
+  const onUpsert = async (changedPath: string): Promise<void> => {
+    if (!changedPath.endsWith('.rozie')) return;
+    const abs = pathResolve(changedPath);
+    await compileOne(abs, targets, outDir, rootDir, wantTypes, wantSourceMap, wantPretty, cvaOff, safeInterpOff, stderrWrite, stdoutWrite);
+  };
+
+  watcher.on('add', onUpsert);
+  watcher.on('change', onUpsert);
+  watcher.on('unlink', (removedPath) => {
+    if (removedPath.endsWith('.rozie')) {
+      stdoutWrite(
+        pc.yellow(`[${ts()}] removed ${displayPath(removedPath, rootDir)} (output files left intact)\n`),
+      );
+    }
+  });
+  watcher.on('error', (err) => {
+    // Watcher errors (e.g., EMFILE on Linux when too many files open) get
+    // surfaced but don't tear the watcher down — chokidar internally
+    // recovers from most. We log + keep going.
+    stderrWrite(pc.red(`[${ts()}] watcher error: ${(err as Error).message}\n`));
+  });
+
+  // ----- Wait for shutdown signal --------------------------------------
+  return new Promise<void>((resolve) => {
+    let resolved = false;
+    const cleanup = async (): Promise<void> => {
+      if (resolved) return;
+      resolved = true;
+      stdoutWrite(pc.cyan(`\n[${ts()}] stopped.\n`));
+      try {
+        await watcher.close();
+      } catch {
+        // close() can reject if chokidar already torn down; swallow.
+      }
+      resolve();
+    };
+    if (ctx.signal) {
+      ctx.signal.addEventListener('abort', () => {
+        void cleanup();
+      });
+    }
+    process.once('SIGINT', () => void cleanup());
+    process.once('SIGTERM', () => void cleanup());
+  });
+}
+
+/**
+ * Compile one source file to all configured targets and emit each
+ * artefact to disk. Mirrors the per-tuple write logic in build.ts
+ * (`runBuildMatrix` lines 222-249). Errors render diagnostics but do
+ * not throw — watch mode keeps running past compile failures.
+ */
+async function compileOne(
+  inputAbs: string,
+  targets: Target[],
+  outDir: string,
+  rootDir: string,
+  wantTypes: boolean,
+  wantSourceMap: boolean,
+  wantPretty: boolean,
+  cvaOff: boolean,
+  safeInterpOff: boolean,
+  stderrWrite: (s: string) => void,
+  stdoutWrite: (s: string) => void,
+): Promise<void> {
+  // Local helper — matches the one in build.ts's runBuildMatrix loop. Kept
+  // inline since the two write paths still diverge slightly (watch logs
+  // a per-file summary line; build aggregates failure counts).
+  const maybePretty = async (text: string, name: string): Promise<string> => {
+    if (!wantPretty) return text;
+    const r = await prettyFormat(text, name);
+    if (!r.ok) {
+      stderrWrite(
+        pc.yellow(`[warning] --pretty failed for ${name}: ${r.error}; emitting unformatted\n`),
+      );
+    }
+    return r.formatted;
+  };
+  const startedAt = Date.now();
+  let source: string;
+  try {
+    source = readFileSync(inputAbs, 'utf8');
+  } catch (err) {
+    stderrWrite(
+      pc.red(`[${ts()}] cannot read ${displayPath(inputAbs, rootDir)}: ${(err as Error).message}\n`),
+    );
+    return;
+  }
+
+  // Parallelize across targets — at 6 simultaneous --target invocations
+  // with --pretty on, sequential await would dominate the per-change
+  // latency. Each target's compile + write is independent (single source
+  // file, target-private output paths). Use Promise.all to fan them out;
+  // collect (target, errorCount) results back into ordered logging.
+  const perTarget = await Promise.all(
+    targets.map(async (target): Promise<{ target: Target; errors: number; emitted: boolean }> => {
+      const result = compile(source, {
+        target,
+        filename: inputAbs,
+        types: wantTypes,
+        sourceMap: wantSourceMap,
+        // Phase 23 — attach the `angular` namespace only on opt-out, so the
+        // default-ON path stays byte-identical to unplugin/babel-plugin.
+        ...(cvaOff ? { angular: { cva: false } } : {}),
+        // Phase 26 (D-11) — attach `safeInterpolation` only on opt-out, so the
+        // default-ON path stays byte-identical (dist-parity).
+        ...(safeInterpOff ? { safeInterpolation: false } : {}),
+      });
+
+      const errors = result.diagnostics.filter((d) => d.severity === 'error');
+      const warnings = result.diagnostics.filter((d) => d.severity === 'warning');
+
+      if (errors.length > 0) {
+        stderrWrite(errors.map((d) => `${renderDiagnostic(d, source)}\n`).join(''));
+        return { target, errors: errors.length, emitted: false };
+      }
+      if (warnings.length > 0) {
+        stderrWrite(warnings.map((d) => `${renderDiagnostic(d, source)}\n`).join(''));
+      }
+
+      const outPath = computeOutputPath(inputAbs, target, outDir, rootDir);
+      mkdirSync(pathDirname(outPath), { recursive: true });
+
+      // Phase 22 Plan 22-05 — `.d.rozie.ts` sidecar refresh per changed file
+      // (REQ-5). Same `renderSidecar` dispatch as build.ts / the unplugin, so
+      // a watch-driven re-emit produces byte-identical sidecars. Written RAW
+      // (never prettied) to preserve the do-not-edit hash header.
+      const sidecarText = wantTypes ? renderSidecar(source, target, inputAbs) : null;
+      const sidecarPath =
+        sidecarText !== null
+          ? outPath.slice(0, outPath.length - TARGET_EXTENSIONS[target].length) + '.d.rozie.ts'
+          : null;
+
+      // Pre-compute sidecar paths so we can fire all per-tuple prettier
+      // calls in parallel (mirrors the build.ts shape).
+      const dtsPath =
+        wantTypes && target === 'react' && result.types
+          ? outPath.replace(/\.tsx$/, '.d.ts')
+          : null;
+      // Phase 25 de-CSS-Modules: React emits a side-effect `import './X.css'`
+      // (was `import styles from './X.module.css'`), so the scoped-CSS sibling
+      // is written to a PLAIN `.css` path. (Matches build.ts + babel-plugin +
+      // unplugin `.rozie.css` routing.)
+      const modPath =
+        target === 'react' && result.css !== undefined && result.css.length > 0
+          ? outPath.replace(/\.tsx$/, '.css')
+          : null;
+      const globPath =
+        target === 'react' && result.globalCss !== undefined && result.globalCss.length > 0
+          ? outPath.replace(/\.tsx$/, '.global.css')
+          : null;
+
+      const [mainText, dtsText, modText, globText] = await Promise.all([
+        maybePretty(result.code, outPath),
+        dtsPath ? maybePretty(result.types ?? '', dtsPath) : Promise.resolve(null),
+        modPath ? maybePretty(result.css ?? '', modPath) : Promise.resolve(null),
+        globPath ? maybePretty(result.globalCss ?? '', globPath) : Promise.resolve(null),
+      ]);
+
+      writeFileSync(outPath, mainText, 'utf8');
+      // Phase 22 Plan 22-05: `.d.rozie.ts` sidecar — RAW write (never prettied)
+      // so the hash header bytes match the unplugin/build output.
+      if (sidecarPath !== null && sidecarText !== null) {
+        writeFileSync(sidecarPath, sidecarText, 'utf8');
+      }
+      if (dtsPath !== null && dtsText !== null) writeFileSync(dtsPath, dtsText, 'utf8');
+      if (modPath !== null && modText !== null) writeFileSync(modPath, modText, 'utf8');
+      if (globPath !== null && globText !== null) writeFileSync(globPath, globText, 'utf8');
+      if (wantSourceMap && result.map) {
+        writeFileSync(`${outPath}.map`, result.map.toString(), 'utf8');
+      }
+      return { target, errors: 0, emitted: true };
+    }),
+  );
+
+  // Aggregate ordered by the original target list so the log line is
+  // stable across runs (Promise.all preserves array index order in its
+  // result, so perTarget[i].target === targets[i]).
+  const emitted: Target[] = perTarget.filter((r) => r.emitted).map((r) => r.target);
+  const totalErrors = perTarget.reduce((acc, r) => acc + r.errors, 0);
+
+  const ms = Date.now() - startedAt;
+  const path = displayPath(inputAbs, rootDir);
+  if (totalErrors > 0 && emitted.length === 0) {
+    stdoutWrite(pc.red(`[${ts()}] failed ${path} (${totalErrors} error${totalErrors === 1 ? '' : 's'})\n`));
+  } else if (totalErrors > 0) {
+    stdoutWrite(
+      pc.yellow(
+        `[${ts()}] partial ${path} → ${emitted.join(', ')} (${totalErrors} error${totalErrors === 1 ? '' : 's'} in other targets, ${ms}ms)\n`,
+      ),
+    );
+  } else {
+    stdoutWrite(
+      pc.green(`[${ts()}] compiled ${pc.bold(path)} → ${emitted.join(', ')} (${ms}ms)\n`),
+    );
+  }
+}
+
+/**
+ * Strip the rootDir prefix from a path for compact log output. Absolute
+ * paths outside rootDir are passed through unmodified — matches what
+ * users see in `tsc --watch` output.
+ */
+function displayPath(abs: string, rootDir: string): string {
+  if (abs.startsWith(rootDir + '/')) return abs.slice(rootDir.length + 1);
+  return abs;
+}

package/src/index.ts

@@ -0,0 +1,187 @@
+// @rozie/cli — `rozie` command surface.
+//
+// `rozie build <inputs...>` runs each .rozie file through @rozie/core's
+// compile() public API (DIST-01 / D-80) — the same single source of truth
+// shared with @rozie/unplugin and @rozie/babel-plugin. Comma-separated
+// `--target` (D-87), variadic file/dir/glob inputs (D-88), and the
+// dist/{target}/{rel}/Foo.{ext} output layout (D-89) ship as of Phase 6
+// Plan 03.
+//
+// runCli is exported separately from the bin shebang so tests can drive the
+// CLI in-process without spawning a child node.
+import { Command } from 'commander';
+import {
+  runBuild,
+  runBuildMany,
+  runBuildMatrix,
+  type BuildOptions,
+  type BuildOptionsExt,
+} from './commands/build.js';
+import { runWatch, type WatchOptions } from './commands/watch.js';
+import { parseTargets, type Target } from './utils/parseTargets.js';
+
+export { runBuild, runBuildMany, runBuildMatrix, runWatch };
+export type { BuildOptions, BuildOptionsExt, WatchOptions };
+
+/**
+ * Internal — the parsed shape of `rozie build`'s opts after commander applies
+ * the `parseTargets` parser. `target` is always `Target[]` post-parse (D-87);
+ * `types` defaults true per Commander's `--no-*` semantics (D-90); `sourceMap`
+ * defaults undefined/false (D-91).
+ */
+interface BuildCliOpts {
+  target: Target[];
+  out?: string;
+  sourceMap?: boolean;
+  types?: boolean;
+  pretty?: boolean;
+  /**
+   * Phase 23 — Angular-only. Commander's `--no-cva` inverted boolean: present
+   * on argv → `opts.cva === false`; absent → `opts.cva === true` (default ON).
+   * Maps to `compile({ angular: { cva: false } })` when false.
+   */
+  cva?: boolean;
+  /**
+   * Phase 26 (D-11) — the GLOBAL safe-interpolation opt-out. Commander's
+   * `--no-safe-interpolation` inverted boolean: present on argv →
+   * `opts.safeInterpolation === false`; absent → `true` (default ON). Maps to
+   * `compile({ safeInterpolation: false })` when false (cross-target — applies
+   * to the five non-Vue targets).
+   */
+  safeInterpolation?: boolean;
+}
+
+/**
+ * Programmatic entry — constructs the commander program and parses argv.
+ * `argv` follows Node's `process.argv` shape (argv[0]=node, argv[1]=script).
+ */
+export async function runCli(argv: readonly string[]): Promise<void> {
+  const program = new Command();
+  program
+    .name('rozie')
+    .description('Rozie cross-framework component compiler CLI')
+    .version('0.0.0')
+    // Surface help on `rozie` with no args rather than the silent default.
+    .showHelpAfterError();
+
+  program
+    .command('build <inputs...>')
+    .description('Compile one or more .rozie files to one or more target frameworks')
+    // D-87: comma-separated targets via parseTargets — validates each token.
+    // Default ['vue'] preserves backward-compat with pre-Phase-6 invocations
+    // that omitted --target entirely.
+    .option(
+      '-t, --target <names>',
+      'target framework(s); comma-separated (vue|react|svelte|angular|solid|lit)',
+      parseTargets,
+      ['vue'] as Target[],
+    )
+    .option(
+      '-o, --out <path>',
+      'output directory (required for multiple inputs or multiple targets)',
+    )
+    // D-91: source maps default OFF.
+    .option(
+      '--source-map',
+      'emit .map sidecar files (default off per D-91)',
+    )
+    // D-90: .d.ts emission default ON; --no-types opts out. Commander auto-
+    // creates the inverted boolean: `--no-types` on argv → opts.types === false.
+    .option(
+      '--no-types',
+      'skip .d.ts emission (React-only — no-op for inline-typed Vue/Svelte/Angular)',
+    )
+    // PROJECT.md "Out of Scope" carve-out: --pretty IS in scope for the
+    // CLI specifically; just not v1's default. Off by default so the
+    // dist-parity byte-equal gate (which routes through runBuildMatrix
+    // without --pretty) stays inert.
+    .option(
+      '--pretty',
+      'format emitted artefacts with prettier before write (off by default)',
+    )
+    // Phase 23 — Angular-only opt-out for the auto ControlValueAccessor emit.
+    // Default ON; --no-cva → opts.cva === false → angular: { cva: false }.
+    // Commander auto-creates the inverted boolean from the `--no-` prefix.
+    .option(
+      '--no-cva',
+      'Angular-only: suppress the auto ControlValueAccessor emit on single-model components (no-op for other targets)',
+    )
+    // Phase 26 — GLOBAL opt-out for the safe-interpolation wrap (default ON).
+    // --no-safe-interpolation → opts.safeInterpolation === false →
+    // compile({ safeInterpolation: false }). Commander auto-creates the
+    // inverted boolean from the `--no-` prefix. No-op for the Vue target.
+    .option(
+      '--no-safe-interpolation',
+      'suppress the safe-interpolation rozieDisplay wrap (raw per-target emit; re-exposes the React object-child crash if a non-primitive is interpolated; no-op for Vue)',
+    )
+    .action(async (inputs: string[], opts: BuildCliOpts) => {
+      const ext: BuildOptionsExt = {
+        target: opts.target,
+        ...(opts.out !== undefined ? { out: opts.out } : {}),
+        ...(opts.sourceMap === true ? { sourceMap: true } : {}),
+        ...(opts.types === false ? { types: false } : {}),
+        ...(opts.pretty === true ? { pretty: true } : {}),
+        ...(opts.cva === false ? { cva: false } : {}),
+        ...(opts.safeInterpolation === false ? { safeInterpolation: false } : {}),
+      };
+      await runBuildMatrix(inputs, ext);
+    });
+
+  // `rozie watch <inputs...>` — chokidar-driven incremental recompile.
+  // Mirrors the build flag surface but is long-running. --out is required
+  // here (no sense streaming to stdout from a daemon); the watch command
+  // surfaces that as ROZ856 at the action layer, not via commander.
+  program
+    .command('watch <inputs...>')
+    .description(
+      'Watch .rozie files and recompile on change (long-running; tsc --watch style)',
+    )
+    .option(
+      '-t, --target <names>',
+      'target framework(s); comma-separated (vue|react|svelte|angular|solid|lit)',
+      parseTargets,
+      ['vue'] as Target[],
+    )
+    .option(
+      '-o, --out <path>',
+      'output directory (required for watch mode)',
+    )
+    .option(
+      '--source-map',
+      'emit .map sidecar files (default off per D-91)',
+    )
+    .option(
+      '--no-types',
+      'skip .d.ts emission (React-only — no-op for inline-typed Vue/Svelte/Angular)',
+    )
+    .option(
+      '--pretty',
+      'format emitted artefacts with prettier before write (off by default)',
+    )
+    // Phase 23 — Angular-only opt-out, mirrors `rozie build` (default ON).
+    .option(
+      '--no-cva',
+      'Angular-only: suppress the auto ControlValueAccessor emit on single-model components (no-op for other targets)',
+    )
+    // Phase 26 — GLOBAL safe-interpolation opt-out, mirrors `rozie build`.
+    .option(
+      '--no-safe-interpolation',
+      'suppress the safe-interpolation rozieDisplay wrap (raw per-target emit; re-exposes the React object-child crash if a non-primitive is interpolated; no-op for Vue)',
+    )
+    .action(async (inputs: string[], opts: BuildCliOpts) => {
+      const ext: WatchOptions = {
+        target: opts.target,
+        ...(opts.out !== undefined ? { out: opts.out } : {}),
+        ...(opts.sourceMap === true ? { sourceMap: true } : {}),
+        ...(opts.types === false ? { types: false } : {}),
+        ...(opts.pretty === true ? { pretty: true } : {}),
+        ...(opts.cva === false ? { cva: false } : {}),
+        ...(opts.safeInterpolation === false ? { safeInterpolation: false } : {}),
+      };
+      await runWatch(inputs, ext);
+    });
+
+  // commander 14 returns a promise from parseAsync; await so any thrown errors
+  // bubble to the bin wrapper.
+  await program.parseAsync([...argv]);
+}

package/src/utils/expandInputs.ts

@@ -0,0 +1,98 @@
+// expandInputs — D-88 input expansion for `rozie build <inputs...>`.
+//
+// Each positional arg auto-detects as one of:
+//   - file       → resolved to absolute path, validated to end with `.rozie`
+//   - directory  → fast-glob `${dir}/**/*.rozie`
+//   - glob       → fast-glob direct (detected via `fg.isDynamicPattern`)
+//
+// Phase 06.2 P3 D-122: composing components emit as plain imports; downstream
+// bundlers handle transitive resolution. v1's "one input file → one output
+// unit" assumption holds — `<components>{ Foo: './Foo.rozie' }` does NOT
+// auto-include `./Foo.rozie` in the input list. Authors enumerate the full
+// component graph via the variadic args / glob pattern. v2 may add a
+// `--resolve-transitive` flag.
+//
+// Carries forward security posture from `packages/unplugin/src/transform.ts`:
+//   - Null-byte injection rejected (lines 235-237 of transform.ts)
+//   - Top-level symlink args refused; recursive glob walk skips symlinks
+//   - The same ignore set used by `walkRozieFiles` (node_modules, .git, …)
+//
+// Results are deduplicated via a Set and sorted by absolute path so the
+// downstream (input × target) tuple list is deterministic.
+import fg from 'fast-glob';
+import { lstatSync } from 'node:fs';
+import { resolve as pathResolve } from 'node:path';
+
+/**
+ * D-88: expand variadic positional args into a deduped, sorted list of
+ * absolute `.rozie` paths. Throws on invalid inputs.
+ *
+ * @public — used by `runBuildMatrix` (commands/build.ts) and CLI tests.
+ */
+export async function expandInputs(args: string[]): Promise<string[]> {
+  const out = new Set<string>();
+  for (const arg of args) {
+    // Carry forward null-byte rejection from unplugin/transform.ts:235-237
+    // (T-05-04b-03 mitigation). ROZ853 surface in CLI; here we throw a plain
+    // Error so the caller (runBuildMatrix) can re-shape into a build exit.
+    if (arg.includes('\0')) {
+      throw new Error(
+        `[ROZ853] rozie build: refusing input with null byte: ${JSON.stringify(arg)}`,
+      );
+    }
+
+    // 1. Glob — fast-glob detects magic chars (`*`, `?`, `[]`, `{}`, …).
+    if (fg.isDynamicPattern(arg)) {
+      const matches = await fg(arg, {
+        absolute: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+      });
+      for (const match of matches) {
+        if (match.endsWith('.rozie')) out.add(match);
+      }
+      continue;
+    }
+
+    // 2. File or directory — lstat (NOT stat) so a symlink doesn't get
+    //    transparently followed. The walkRozieFiles posture in
+    //    packages/unplugin/src/transform.ts:737 is the canonical reference.
+    const abs = pathResolve(arg);
+    let stat: ReturnType<typeof lstatSync>;
+    try {
+      stat = lstatSync(abs);
+    } catch {
+      throw new Error(`[ROZ851] rozie build: cannot stat input '${arg}'`);
+    }
+
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `[ROZ851] rozie build: refusing symlink input '${arg}' (defense-in-depth from walkRozieFiles)`,
+      );
+    }
+
+    if (stat.isDirectory()) {
+      const matches = await fg(`${abs}/**/*.rozie`, {
+        absolute: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        ignore: [
+          '**/node_modules/**',
+          '**/dist/**',
+          '**/.git/**',
+          '**/.turbo/**',
+          '**/.planning/**',
+        ],
+      });
+      for (const match of matches) out.add(match);
+    } else if (stat.isFile()) {
+      if (!abs.endsWith('.rozie')) {
+        throw new Error(`[ROZ854] rozie build: file '${arg}' is not a .rozie file`);
+      }
+      out.add(abs);
+    } else {
+      throw new Error(`[ROZ851] rozie build: cannot stat input '${arg}'`);
+    }
+  }
+  return [...out].sort();
+}