rcf-lite 0.0.1 → 0.8.0

package/src/cli/test-suite.js

@@ -0,0 +1,221 @@
+// `rcf test-suite <ts-id> <verb> [options]` subcommand handler
+// (verification-integrity-cluster-spec §5.1, §7).
+//
+// Two verbs:
+//   provenance   author runtimeProvenance on TS/TC (§5.1)
+//   approve      promote TS.status draft -> approved (§7 Option A)
+//
+// Both go through the store's `updateDocument` writer so the post-write
+// validation gate and reference-integrity checks fire uniformly.
+
+import { parseArgs } from 'node:util';
+
+import { isRcfError, writeUnexpectedFailure } from '#core/errors';
+import { updateDocument, walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+
+const PROVENANCE_OPTION_SPEC = {
+  tc: { type: 'string' },
+  profile: { type: 'string' },
+  'env-var': { type: 'string', multiple: true },
+  host: { type: 'string', multiple: true },
+  notes: { type: 'string' },
+  force: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+const APPROVE_OPTION_SPEC = {
+  force: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+const VALID_PROFILES = new Set(['mock', 'stub', 'fixture', 'live', 'mixed']);
+
+export const HELP = `Usage: rcf test-suite <ts-id> <verb> [options]
+
+Verbs:
+  provenance                Author runtimeProvenance on the TS or a specific TC
+  approve                   Promote the TS's authoringStatus to 'approved'
+
+rcf test-suite <ts-id> provenance [--tc <tc-id>] --profile <mock|stub|fixture|live|mixed>
+    [--env-var VAR ...] [--host host ...] [--notes "..."] [--force]
+
+Records the runtime the test actually addressed on a specific TC (or
+every TC in the TS when --tc is omitted and no existing block would be
+overwritten). Refuses to overwrite an existing block without --force.
+
+rcf test-suite <ts-id> approve [--force]
+
+Writes authoringStatus: approved on the TS. Refuses without --force
+when the TS is 'superseded'; --force also allows re-approval after
+needsRevision. Stage-4 auto-promotion invokes this verb after
+coverage --strict + tests pass; the operator only needs it for manual
+override.
+
+Options common:
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `test-suite`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    stdout.write(HELP);
+    return argv[0] ? 0 : 2;
+  }
+
+  const tsId = argv[0];
+  const verb = argv[1];
+  const rest = argv.slice(2);
+  if (!verb) {
+    stderr.write('[error] usage test-suite: verb required (provenance | approve)\n');
+    return 2;
+  }
+  // 0.8.0 slug-train (w-2026-07-28-012 landmine 3, consumer-path
+  // straggler): widened `\d{3}` -> `\d{3,}` in lockstep with rcf-schemas
+  // 0.4.3's TS pattern. The previous shape hard-refused any TS >= 1000 --
+  // silent from the operator's perspective (the tsId matched the schema
+  // but the CLI verb refused with a usage error citing "TS-015").
+  if (!/^TS-\d{3,}$/.test(tsId)) {
+    stderr.write(`[error] usage test-suite: expected a TS id like TS-015 or TS-1000, got '${tsId}'\n`);
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor).\n');
+    return 2;
+  }
+  const walkResult = await walkTree({ projectRoot });
+  const tree = walkResult.tree;
+  const ts = tree.byId.get(tsId);
+  if (!ts || tree.kindById.get(tsId) !== 'testSuite') {
+    stderr.write(`[error] usage test-suite: ${tsId} not found or not a Test Suite\n`);
+    return 2;
+  }
+
+  if (verb === 'provenance') return runProvenance({ tsId, ts, rest, projectRoot, tree, walkResult, stdout, stderr });
+  if (verb === 'approve') return runApprove({ tsId, ts, rest, projectRoot, tree, walkResult, stdout, stderr });
+  stderr.write(`[error] usage test-suite: unknown verb '${verb}' (expected provenance | approve)\n`);
+  return 2;
+}
+
+async function runProvenance({ tsId, ts, rest, projectRoot, tree, walkResult, stdout, stderr }) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: PROVENANCE_OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (!flags.profile) {
+    stderr.write('[error] usage test-suite provenance: --profile required\n');
+    return 2;
+  }
+  if (!VALID_PROFILES.has(flags.profile)) {
+    stderr.write(`[error] usage test-suite provenance: unknown --profile '${flags.profile}' (expected ${[...VALID_PROFILES].join(' | ')})\n`);
+    return 2;
+  }
+  const envVars = flags['env-var'] ?? [];
+  const hosts = flags.host ?? [];
+
+  const block = {
+    profile: flags.profile,
+    envVarsRequired: envVars,
+    externalHostsReached: hosts,
+  };
+  if (typeof flags.notes === 'string' && flags.notes.length > 0) {
+    // Redaction discipline: notes must never contain a token; a naive
+    // pattern grep here (looking for `=` followed by long alphanum
+    // stretches) is a belt-and-braces check that fires on the obvious
+    // paste-a-token mistake without pretending to be a real secret
+    // scanner.
+    if (/[A-Za-z0-9]{20,}/.test(flags.notes) && /=|token|secret|key/i.test(flags.notes)) {
+      stderr.write('[error] usage test-suite provenance: --notes looks like it contains a token or secret; the notes field is prose-only, never quotes credential material.\n');
+      return 2;
+    }
+    block.notes = flags.notes;
+  }
+
+  const tcs = Array.isArray(ts.testCases) ? ts.testCases : [];
+  const targetTcIds = flags.tc ? [flags.tc] : tcs.map((tc) => tc.id);
+  if (targetTcIds.length === 0) {
+    stderr.write(`[error] usage test-suite provenance: ${tsId} has no test cases\n`);
+    return 2;
+  }
+  if (flags.tc && !tcs.find((tc) => tc.id === flags.tc)) {
+    stderr.write(`[error] usage test-suite provenance: TC ${flags.tc} not found on ${tsId}\n`);
+    return 2;
+  }
+
+  const nextTcs = [];
+  for (const tc of tcs) {
+    if (!targetTcIds.includes(tc.id)) { nextTcs.push(tc); continue; }
+    if (tc.runtimeProvenance && !flags.force) {
+      stderr.write(`[error] refused test-suite provenance: TC ${tc.id} already carries runtimeProvenance; re-run with --force to overwrite.\n`);
+      return 4;
+    }
+    nextTcs.push({ ...tc, runtimeProvenance: block });
+  }
+
+  const sets = [{ path: 'testCases', value: nextTcs }];
+  const result = await updateDocument({
+    projectRoot, tree, id: tsId, patch: null, sets, options: {}, walkErrors: walkResult.errors,
+  });
+  if (isRcfError(result)) return handleWriterError(result, stderr);
+  stdout.write(`test-suite ${tsId} provenance updated on ${targetTcIds.length} test case(s).\n`);
+  return 0;
+}
+
+async function runApprove({ tsId, ts, rest, projectRoot, tree, walkResult, stdout, stderr }) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: APPROVE_OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  const current = ts.status;
+  if (current === 'approved') {
+    if (!flags.quiet) stdout.write(`test-suite ${tsId} is already approved (no-op).\n`);
+    return 0;
+  }
+  if (current === 'superseded' && !flags.force) {
+    stderr.write(`[error] refused test-suite approve: ${tsId} is superseded; re-run with --force to re-approve.\n`);
+    return 4;
+  }
+  if (current === 'needsRevision' && !flags.force) {
+    stderr.write(`[error] refused test-suite approve: ${tsId} is needsRevision; re-run with --force after re-work.\n`);
+    return 4;
+  }
+  const sets = [{ path: 'status', value: 'approved' }];
+  const result = await updateDocument({
+    projectRoot, tree, id: tsId, patch: null, sets, options: {}, walkErrors: walkResult.errors,
+  });
+  if (isRcfError(result)) return handleWriterError(result, stderr);
+  if (!flags.quiet) stdout.write(`test-suite ${tsId} approved.\n`);
+  return 0;
+}
+
+function handleWriterError(err, stderr) {
+  if (err.kind === 'ioFailure') { writeUnexpectedFailure(err, stderr); return 1; }
+  stderr.write(`[error] ${err.kind} ${err.message}\n`);
+  if (err.kind === 'usage') return 2;
+  if (err.kind === 'validation' || err.kind === 'brokenReference') return 3;
+  return 1;
+}

package/src/cli/trace.js

@@ -0,0 +1,172 @@
+// `rcf trace <id>` subcommand handler. Walks the graph from a pivot
+// id in one direction or both. Phase 5 §D8 / §D9.
+//
+// --forward walks parent-child children + cross-link children (D7).
+// --back walks parent-child ancestors only (D8: cross-links are NOT
+// traversed by --back). --both emits {pivot, ancestors, descendants}.
+
+import { parseArgs } from 'node:util';
+
+import { formatErrors } from '#core/errors';
+import { walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import {
+  computeTrace,
+  formatJson,
+  formatMermaid,
+  formatTable,
+  kindOf,
+} from '../query/index.js';
+
+const OPTION_SPEC = {
+  forward: { type: 'boolean' },
+  back: { type: 'boolean' },
+  both: { type: 'boolean' },
+  format: { type: 'string' },
+  help: { type: 'boolean' },
+  // Phase 10 (X2 CodeNode bridge): extend a forward/both trace into the
+  // code layer. A backward trace from a <path> reaches code automatically.
+  'to-code': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf trace <id|path> [options]
+
+Walk the graph from <id> forward (descendants), backward (ancestors),
+or both. Default is --forward. When <id> is not a known document id, it
+is tried as a source path (optionally #symbol-suffixed) and traced
+backward from the matching Code Node(s) up to the root PRD / TAD / BS.
+
+Options:
+  --forward                 Walk descendants (default)
+  --back                    Walk ancestors up to the root PRD / TAD / BS
+  --both                    Emit ancestors + descendants around <id>
+  --format <format>         table (default) | json | mermaid
+  --to-code                 Extend the forward fan-out into Code Nodes
+  --help                    Print this help
+
+Notes:
+  --forward, --back and --both are mutually exclusive.
+  Cross-links are NOT traversed by --back (fan-out is what 'impact' is for).
+`;
+
+const VALID_FORMATS = new Set(['table', 'json', 'mermaid']);
+
+/**
+ * @param {string[]} argv - argv slice after `trace`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+
+  // Direction: default forward; --forward | --back | --both mutually
+  // exclusive (spec §D9 test surface).
+  const set = ['forward', 'back', 'both'].filter((k) => flags[k]);
+  if (set.length > 1) {
+    stderr.write('[error] usage trace: --forward, --back and --both are mutually exclusive\n');
+    return 2;
+  }
+  let direction = 'forward';
+  if (flags.back) direction = 'back';
+  if (flags.both) direction = 'both';
+
+  const format = flags.format ?? 'table';
+  if (!VALID_FORMATS.has(format)) {
+    stderr.write(`[error] usage trace: unknown --format ${format} (expected table | json | mermaid)\n`);
+    return 2;
+  }
+
+  if (positionals.length === 0) {
+    stderr.write('[error] usage trace: expected exactly one <id>\n');
+    stderr.write(HELP);
+    return 2;
+  }
+  if (positionals.length > 1) {
+    stderr.write('[error] usage trace: multiple positional ids are not supported\n');
+    return 2;
+  }
+  const id = positionals[0];
+  if (id.includes('*') || id.includes('?')) {
+    stderr.write('[error] usage trace: wildcard / glob positional not supported\n');
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    stderr.write(`${formatErrors(errors, { verbose: false, strict: false })}\n`);
+    return 3;
+  }
+
+  const includeCode = Boolean(flags['to-code']);
+
+  // Phase 10 (X2 CodeNode bridge): path mode. If the positional is not a
+  // known document id, try resolving it as a source path to one or more
+  // Code Nodes, then trace each backward (path -> CN -> AC -> US -> REQ ->
+  // PRD). This is the `rcf trace <path>` blast-radius-from-code query.
+  if (!kindOf(tree, id)) {
+    const cnIds = resolveCodeNodesForPath(tree, id);
+    if (cnIds.length === 0) {
+      stderr.write(`[error] usage trace: id ${id} not found (no document or code node matches)\n`);
+      return 2;
+    }
+    const chunks = [];
+    for (const cnId of cnIds) {
+      const cn = tree.byId.get(cnId);
+      const res = computeTrace(tree, { id: cnId, direction: 'back' });
+      let out;
+      if (format === 'json') out = formatJson(res, 'trace');
+      else if (format === 'mermaid') out = formatMermaid(res, 'trace');
+      else out = `# ${cnId}  (${cn?.path ?? '?'})\n${formatTable(res, 'trace')}`;
+      chunks.push(out);
+    }
+    stdout.write(chunks.join('\n'));
+    return 0;
+  }
+
+  const result = computeTrace(tree, { id, direction, includeCode });
+
+  let output;
+  if (format === 'json') output = formatJson(result, 'trace');
+  else if (format === 'mermaid') output = formatMermaid(result, 'trace');
+  else output = formatTable(result, 'trace');
+  stdout.write(output);
+  return 0;
+}
+
+/**
+ * Phase 10: resolve a source-path query to Code Node ids. Matches a CN
+ * when its `path` equals the query (file-level or file#symbol form) or
+ * when the query names the file that a symbol-level CN lives in.
+ *
+ * @param {object} tree - walker TreeModel
+ * @param {string} query - a repo-relative path, optionally #symbol-suffixed
+ * @returns {string[]} matching CN ids, sorted
+ */
+function resolveCodeNodesForPath(tree, query) {
+  const out = [];
+  for (const cn of tree.codeNodes ?? []) {
+    const cnPath = cn.path ?? '';
+    const cnFile = cnPath.split('#')[0];
+    if (cnPath === query || cnFile === query) out.push(cn.cnId);
+  }
+  return out.sort();
+}

package/src/cli/ui-baseline.js

@@ -0,0 +1,292 @@
+// `rcf ui-baseline <verb>` handler (ui-design-gate-0.7.0-spec §5.5).
+//
+// Three sub-verbs:
+//   init [--prd <prdId>] [--input <file>] [--dry-run] [--reset]
+//     Present the ruled defaults, take operator ack + any opt-outs,
+//     write the uiBaseline record (with --reset appending the prior
+//     record to uiBaselineHistory[]).
+//   show [--json]
+//     Print the current baseline record.
+//   opt-out --field <path> --reason "..."
+//     Append an entry to operatorOptOuts[] on the existing baseline.
+//
+// The init verb also applies the preflight seam pickup (spec §3.2):
+// preflight-recorded design-shape answers whose uiBaselineWritePath
+// targets defaults.* land as defaults on the fresh record. The Track A
+// finalised `skippedUiBaseline` seam is the interlock; the opt-out
+// ledger entries stay in place either way.
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import process from 'node:process';
+
+import { walkTree } from '#core/store';
+import { writeUnexpectedFailure, rcfError } from '#core/errors';
+
+import { findProjectRoot } from '../view/index.js';
+import {
+  UI_BASELINE_DEFAULTS_V1,
+  composeUiBaselineRecord,
+  isKnownBaselinePath,
+  normaliseNonInteractiveInput,
+  preflightSeamOverrides,
+  runInteractiveSession,
+  writeUiBaselineOptOut,
+  writeUiBaselineRecord,
+} from '../ui-baseline/index.js';
+
+const OPTION_SPEC = {
+  prd: { type: 'string' },
+  input: { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  reset: { type: 'boolean' },
+  json: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  field: { type: 'string' },
+  reason: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf ui-baseline <verb> [options]
+
+Manage the project's ruled UI defaults (theme, layout, contrast,
+components, auth flow). Written once per project as a uiBaseline record
+on the manifest; every UI-bearing FBS inherits from it. Every opt-out
+is explicit; silence is never an opt-out.
+
+Sub-verbs:
+  init                      Present the ruled defaults and write the
+                            uiBaseline record. Interactive by default;
+                            --input reads a pre-filled JSON file for CI.
+  show                      Print the current baseline record.
+  opt-out                   Append an entry to operatorOptOuts[].
+
+Options:
+  --prd <prd-id>            PRD id to attach to the baseline (default:
+                            the project's PRD).
+  --input <path>            Non-interactive init: read a JSON file with
+                            { optOuts: [], overrides: {} } shape.
+  --dry-run                 init only: print the composed record; do not
+                            write.
+  --reset                   init only: append the previous baseline to
+                            uiBaselineHistory[] before writing.
+  --json                    show only: emit JSON.
+  --field <path>            opt-out only: dot-path into defaults (for
+                            example 'themeMode' or 'componentVocabulary.declaredComponents').
+  --reason "..."            opt-out only: plain-text reason (>= 20 chars).
+  --quiet                   Suppress non-error confirmations.
+  --help                    Print this help.
+
+Exit codes:
+  0  success
+  1  IO / unexpected runtime failure
+  2  usage error
+  3  schema or tree validation failure
+  4  session cancelled by operator (init only)
+`;
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const stdin = deps.stdin ?? process.stdin;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (parsed.positionals.length !== 1) {
+    stderr.write('[error] usage ui-baseline: expected one sub-verb (init | show | opt-out)\n');
+    return 2;
+  }
+  const sub = parsed.positionals[0];
+  if (!['init', 'show', 'opt-out'].includes(sub)) {
+    stderr.write(`[error] usage ui-baseline: unknown sub-verb '${sub}' (expected init | show | opt-out)\n`);
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `rcf init` first.\n');
+    return 2;
+  }
+  const walkResult = await walkTree({ projectRoot });
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding\n`);
+  }
+  const { tree } = walkResult;
+
+  if (sub === 'show') return runShow({ tree, stdout, flags });
+  if (sub === 'opt-out') return await runOptOut({ tree, projectRoot, stdout, stderr, flags, now: deps.now });
+  return await runInit({ tree, projectRoot, stdin, stdout, stderr, flags, now: deps.now });
+}
+
+function runShow({ tree, stdout, flags }) {
+  const record = tree.manifest?.uiBaseline;
+  if (!record) {
+    stdout.write('ui-baseline: no baseline recorded. Run \'rcf ui-baseline init\'.\n');
+    return 0;
+  }
+  if (flags.json) {
+    stdout.write(`${JSON.stringify(record, null, 2)}\n`);
+    return 0;
+  }
+  stdout.write(`ui-baseline ${record.id} (prd=${record.prdId}, ackedAt=${record.operatorAckAt})\n`);
+  const defaults = record.defaults ?? {};
+  const optOuts = new Set((record.operatorOptOuts ?? []).map((o) => o.field));
+  for (const spec of UI_BASELINE_DEFAULTS_V1) {
+    const value = readDot(defaults, spec.path);
+    const marker = optOuts.has(spec.path) ? '*' : ' ';
+    stdout.write(`  ${marker} ${spec.path}: ${formatValue(value)}\n`);
+  }
+  if ((record.operatorOptOuts ?? []).length > 0) {
+    stdout.write('opt-outs:\n');
+    for (const o of record.operatorOptOuts) {
+      stdout.write(`  * ${o.field} - ${o.reason} (ack ${o.operatorAckAt})\n`);
+    }
+  }
+  return 0;
+}
+
+async function runOptOut({ tree, projectRoot, stdout, stderr, flags, now }) {
+  if (typeof flags.field !== 'string' || flags.field.length === 0) {
+    stderr.write('[error] usage ui-baseline opt-out: --field is required\n');
+    return 2;
+  }
+  if (typeof flags.reason !== 'string' || flags.reason.length < 20) {
+    stderr.write('[error] usage ui-baseline opt-out: --reason is required and must be at least 20 characters\n');
+    return 2;
+  }
+  const normalisedField = flags.field.startsWith('defaults.') ? flags.field.slice('defaults.'.length) : flags.field;
+  if (!isKnownBaselinePath(normalisedField)) {
+    stderr.write(`[error] usage ui-baseline opt-out: unknown baseline field '${normalisedField}' (see 'rcf ui-baseline show' for the field list)\n`);
+    return 2;
+  }
+  const result = await writeUiBaselineOptOut({
+    projectRoot,
+    tree,
+    field: normalisedField,
+    reason: flags.reason,
+    isKnownField: isKnownBaselinePath,
+    now: now ? new Date(now()) : new Date(),
+  });
+  if (result && 'kind' in result && 'message' in result) {
+    if (result.kind === 'ioFailure') { writeUnexpectedFailure(result, stderr); return 1; }
+    stderr.write(`[error] ${result.kind} ${result.message}\n`);
+    if (result.kind === 'usage') return 2;
+    if (result.kind === 'validation') return 3;
+    return 1;
+  }
+  if (!flags.quiet) stdout.write(`ui-baseline: recorded opt-out for ${normalisedField}.\n`);
+  return 0;
+}
+
+async function runInit({ tree, projectRoot, stdin, stdout, stderr, flags, now }) {
+  const prdId = flags.prd ?? tree.prd?.prdId;
+  if (!prdId) {
+    stderr.write('[error] usage ui-baseline init: no --prd given and no PRD found on the tree\n');
+    return 2;
+  }
+  const priorBaseline = tree.manifest?.uiBaseline ?? null;
+  if (priorBaseline && !flags.reset && !flags['dry-run']) {
+    stderr.write(`[error] refused ui-baseline init: a baseline (${priorBaseline.id}) already exists; pass --reset to author a fresh one (the prior lands under uiBaselineHistory[]).\n`);
+    return 2;
+  }
+
+  const preflightOverrides = preflightSeamOverrides(tree.manifest);
+  const isTty = Boolean(stdout.isTTY && stdin.isTTY);
+
+  let session;
+  try {
+    if (flags.input) {
+      const raw = await readFile(flags.input, 'utf8');
+      const parsed = JSON.parse(raw);
+      session = normaliseNonInteractiveInput(parsed);
+      // Merge preflight overrides UNDER the input overrides: input wins.
+      session.overrides = { ...preflightOverrides, ...session.overrides };
+    } else if (isTty) {
+      const rl = createInterface({ input: stdin, output: stdout });
+      const prompt = (q) => rl.question(q);
+      const write = (line) => stdout.write(`${line}\n`);
+      try {
+        session = await runInteractiveSession({ prompt, write, preflightOverrides });
+      } finally {
+        rl.close();
+      }
+    } else {
+      stderr.write('[error] usage ui-baseline init: not on a TTY and no --input file given\n');
+      return 2;
+    }
+  } catch (err) {
+    if (err && String(err.message).includes('session cancelled by operator')) {
+      stderr.write('[error] ui-baseline init: session cancelled; no record written.\n');
+      return 4;
+    }
+    writeUnexpectedFailure(
+      rcfError({ kind: 'ioFailure', message: `ui-baseline init: ${err.message}`, stack: err.stack }),
+      stderr,
+    );
+    return 1;
+  }
+
+  const record = composeUiBaselineRecord({
+    manifest: tree.manifest,
+    prdId,
+    optOuts: session.optOuts,
+    overrides: session.overrides,
+    now: now ? new Date(now()) : new Date(),
+  });
+
+  if (flags['dry-run']) {
+    stdout.write(`${JSON.stringify(record, null, 2)}\n`);
+    if (!flags.quiet) stdout.write(`[dry-run] ui-baseline init: would write ${record.id} (${session.optOuts.length} opt-outs).\n`);
+    return 0;
+  }
+
+  const result = await writeUiBaselineRecord({
+    projectRoot, tree, record, options: { reset: Boolean(flags.reset) },
+  });
+  if (result && 'kind' in result && 'message' in result) {
+    if (result.kind === 'ioFailure') { writeUnexpectedFailure(result, stderr); return 1; }
+    stderr.write(`[error] ${result.kind} ${result.message}\n`);
+    if (result.kind === 'usage') return 2;
+    if (result.kind === 'validation') return 3;
+    return 1;
+  }
+  if (!flags.quiet) {
+    stdout.write(`ui-baseline init: wrote ${record.id} to rcf/manifest.json (${session.optOuts.length} opt-out(s)).\n`);
+    if (Object.keys(preflightOverrides).length > 0) {
+      stdout.write(`  Applied ${Object.keys(preflightOverrides).length} preflight seam pickup(s): ${Object.keys(preflightOverrides).join(', ')}\n`);
+    }
+  }
+  return 0;
+}
+
+function readDot(obj, path) {
+  const parts = String(path).split('.');
+  let cursor = obj;
+  for (const key of parts) {
+    if (cursor === null || cursor === undefined) return undefined;
+    cursor = cursor[key];
+  }
+  return cursor;
+}
+
+function formatValue(v) {
+  if (v === undefined) return '(unset)';
+  if (Array.isArray(v)) return `[${v.map((x) => JSON.stringify(x)).join(', ')}]`;
+  if (typeof v === 'string') return v;
+  return JSON.stringify(v);
+}