rcf-lite 0.0.1 → 0.7.1

package/src/verify/chain/index.js

@@ -0,0 +1,190 @@
+// Chain reader (spec §1, §5.2). Verify's ONLY structural input is the RCF
+// chain — the acceptance contract. It reads the acceptance criteria off the
+// chain through the SAME store code build-lite uses (core's walkTree), never
+// the source tree, the test suite, or the builder's self-report (§9
+// independence guarantee 2). It imports core's READ path only — never
+// writer.js / init.js (§7.2 boundary).
+//
+// 0.7.0 additions (verification-integrity-cluster-spec §5.2, ui-design-gate
+// §8.7): the flattened AC read-out is extended with two derived fields —
+// `serviceAttestations` (aggregated from every FBS's `dependsOnServices[]`
+// whose `acIds` include this AC) and `fbsUiBearing` (true when any of the
+// FBSes bound to this AC has `uiBearing: true`). Both derivations live
+// HERE, in verify's chain reader, per the tonight's clarification (Track A
+// changelog 2026-07-31, Track B §18 N2 fold): core's walker surfaces raw
+// document fields only, verify does the AC-level aggregation. Core 0.3.0
+// carries a walker-guard test that asserts no such derivation leaks into
+// core (`packages/rcf-lite/test/core/store/walker-0-7-0-fields.test.js:580`).
+//
+// The manifest fields verify's report and verdict pipelines need
+// (`uiBaseline`, `browserVerification[]`) are read verbatim off `tree.manifest`
+// and surfaced on the read result — verify's downstream code consumes them
+// through the chain reader, not by re-opening the manifest.
+
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { rcfError } from '#core/errors';
+import { walkTree } from '#core/store';
+
+/**
+ * Resolve a --repo path-or-ref to the project root that holds rcf/manifest.json.
+ * v1 treats --repo as a filesystem path (path refs to remote sources are
+ * deferred). Walks the given path and its ancestors, like build's finder.
+ *
+ * @param {string} startPath
+ * @returns {Promise<string | null>}
+ */
+export async function findProjectRoot(startPath) {
+  let dir = resolve(startPath);
+  // Walk up until we find rcf/manifest.json or hit the filesystem root.
+  // Bounded loop guard: dirname stabilises at the root.
+  for (let i = 0; i < 64; i += 1) {
+    try {
+      await access(join(dir, 'rcf', 'manifest.json'));
+      return dir;
+    } catch {
+      // not here — climb
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Aggregate FBS `dependsOnServices[]` into per-AC serviceAttestations. For
+ * each AC that an FBS binds (via `fbs.acIds`), every entry in the FBS's
+ * `dependsOnServices` whose `acIds` mention the AC produces a
+ * `{serviceId, attestationMode}` on that AC's attestation list. An AC bound
+ * by several FBSes accumulates every service dependency across all of them,
+ * so an `AC-101-2` covered by FBS-011 (`resend` attested `mocked`) and
+ * FBS-014 (`stripe` attested `live`) surfaces both attestations on that
+ * AC. Order is deterministic: FBSes visited in `fbsItems` order, services
+ * in each FBS's declared order.
+ *
+ * @param {object[]} fbsItems
+ * @param {string} acId
+ * @returns {Array<{serviceId: string, attestationMode: string}>}
+ */
+function serviceAttestationsFor(fbsItems, acId) {
+  const out = [];
+  for (const fbs of fbsItems ?? []) {
+    if (!Array.isArray(fbs.acIds) || !fbs.acIds.includes(acId)) continue;
+    for (const dep of fbs.dependsOnServices ?? []) {
+      if (!dep || typeof dep.id !== 'string' || typeof dep.attestationMode !== 'string') continue;
+      const acIds = Array.isArray(dep.acIds) ? dep.acIds : [];
+      if (acIds.length === 0 || acIds.includes(acId)) {
+        out.push({ serviceId: dep.id, attestationMode: dep.attestationMode });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * True when any FBS bound to `acId` has `uiBearing: true`. Verify uses this
+ * flag to gate its UI-baseline verdict emission (§8.7) — a UI-bearing AC is
+ * exposed to `UI-BASELINE-UNMET` / `BROWSER-VERIFICATION-MISSING`, while a
+ * non-UI AC is not.
+ *
+ * @param {object[]} fbsItems
+ * @param {string} acId
+ * @returns {boolean}
+ */
+function fbsUiBearingFor(fbsItems, acId) {
+  for (const fbs of fbsItems ?? []) {
+    if (!Array.isArray(fbs.acIds) || !fbs.acIds.includes(acId)) continue;
+    if (fbs.uiBearing === true) return true;
+  }
+  return false;
+}
+
+/**
+ * The FBS ids bound to `acId` (via `fbs.acIds`), preserving `fbsItems`
+ * order. Verify uses this to resolve the browserVerification entries for
+ * an AC when deciding UI-BASELINE-UNMET vs BROWSER-VERIFICATION-MISSING.
+ *
+ * @param {object[]} fbsItems
+ * @param {string} acId
+ * @returns {string[]}
+ */
+function fbsIdsFor(fbsItems, acId) {
+  const out = [];
+  for (const fbs of fbsItems ?? []) {
+    if (!Array.isArray(fbs.acIds) || !fbs.acIds.includes(acId)) continue;
+    if (typeof fbs.fbsId === 'string') out.push(fbs.fbsId);
+  }
+  return out;
+}
+
+/**
+ * Read the acceptance contract from the chain. Returns the flattened list of
+ * acceptance criteria (each mapped back to its user story + requirement — the
+ * chain-node addressing the report carries), plus the resolved chainRef and
+ * the manifest fields verify's downstream stages consume.
+ *
+ * @param {object} opts
+ * @param {string} opts.repo - path-or-ref to the RCF chain source
+ * @param {string} [opts.chainRef] - which PRD/chain; default = the repo's PRD
+ * @returns {Promise<{ acs: Array<object>, chainRef: string, projectRoot: string, manifest: object } | import('#core/errors').RcfError>}
+ */
+export async function readChain({ repo, chainRef } = {}) {
+  if (typeof repo !== 'string' || repo.length === 0) {
+    return rcfError({ kind: 'usage', message: '--repo (the RCF chain source) is required', field: 'repo' });
+  }
+  const projectRoot = await findProjectRoot(repo);
+  if (!projectRoot) {
+    return rcfError({
+      kind: 'missingFile',
+      message: `no RCF chain found at or above "${repo}" (no rcf/manifest.json). Verify needs an existing RCF chain as its acceptance contract.`,
+      filePath: repo,
+    });
+  }
+
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    // A chain that does not load is not verifiable — surface the first
+    // structural error (errors-as-data; the CLI maps to a chain-load exit).
+    return rcfError({
+      kind: 'parseFailure',
+      message: `RCF chain failed to load: ${errors[0].message}`,
+      filePath: errors[0].filePath,
+      documentId: errors[0].documentId,
+    });
+  }
+
+  const resolvedRef = chainRef ?? tree.prd?.prdId ?? 'PRD-UNKNOWN';
+  const fbsItems = tree.fbsItems ?? [];
+  const acs = [];
+  for (const us of tree.userStories ?? []) {
+    for (const ac of us.acceptanceCriteria ?? []) {
+      acs.push({
+        acId: ac.id,
+        usId: us.usId,
+        reqId: us.reqId ?? null,
+        title: us.title ?? null,
+        description: ac.description ?? '',
+        given: ac.given ?? '',
+        when: ac.when ?? '',
+        then: ac.then ?? '',
+        testable: ac.testable !== false,
+        // 0.7.0 derived fields — verify does the aggregation here per Track A
+        // changelog 2026-07-31 and Track B §18 N2 fold; core does not.
+        serviceAttestations: serviceAttestationsFor(fbsItems, ac.id),
+        fbsUiBearing: fbsUiBearingFor(fbsItems, ac.id),
+        fbsIds: fbsIdsFor(fbsItems, ac.id),
+      });
+    }
+  }
+
+  // Manifest carries the ruled UI baseline and the browser-verification
+  // record ledger; verify's report + verdict layers read them from here so
+  // downstream never re-opens the manifest. Missing manifest is not a
+  // failure at this layer (the walker would have surfaced a load error) —
+  // an older chain simply has no 0.7.0 fields, and `manifest` is `{}`.
+  const manifest = tree.manifest ?? {};
+
+  return { acs, chainRef: resolvedRef, projectRoot, manifest };
+}

package/src/verify/cli/cleanup.js

@@ -0,0 +1,61 @@
+// `rcf-verify cleanup` (spec §3, §6 cleanup contract). Tear down provisioned
+// accounts / sandboxes / data recorded in the --provision file. On a
+// persistent target this stops runs accreting `zzverify-` cruft. Reports what
+// it removed. The concrete teardown route is app-specific (injected).
+
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '#core/errors';
+
+import { readProvisionFile, cleanup } from '../provision/index.js';
+
+export const HELP = `Usage: rcf-verify cleanup --provision <file> [--url <app-url>]
+
+Tear down artefacts recorded in the --provision file (all prefixed
+'zzverify-'). Reports what was removed and what could not be.
+
+Required:
+  --provision <file>    The provisioning record written by run/provision
+
+Exit codes:
+  0  cleanup attempted; see the removed/blocked report
+  2  usage error
+  3  provision file could not be read
+`;
+
+/**
+ * @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;
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { provision: { type: 'string' }, url: { type: 'string' }, help: { type: 'boolean' } }, allowPositionals: false, 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 (!flags.provision) {
+    stderr.write('[error] usage cleanup requires --provision <file>\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  const record = await (deps.readProvisionFile ?? readProvisionFile)(flags.provision);
+  if (isRcfError(record)) {
+    stderr.write(`${formatError(record, { verbose: true })}\n`);
+    return 3;
+  }
+
+  const provisioned = (record.credentials ?? []).map((c) => ({ kind: 'authAccount', ref: c.ref }));
+  const result = await cleanup({ provisioned, teardown: deps.teardown });
+  stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}

package/src/verify/cli/help.js

@@ -0,0 +1,56 @@
+// Top-level and per-subcommand help (mirrors build's cli/help.js). British
+// English, ASCII hyphens only.
+
+import { HELP as RUN_HELP } from './run.js';
+import { HELP as REPORT_HELP } from './report.js';
+import { HELP as PROVISION_HELP } from './provision.js';
+import { HELP as CLEANUP_HELP } from './cleanup.js';
+import { HELP as MCP_HELP } from './mcp.js';
+
+export const TOP_LEVEL_HELP = `Usage: rcf-verify <command> [options]
+
+A fresh-context adversarial verifier. Given an RCF chain (the acceptance
+contract) and a running app under a declared runtime profile, it launches an
+isolated verifier agent that walks real user journeys adversarially and emits a
+structured verdict stamped with the runtime it ran against.
+
+This is an independent ship-readiness signal, not a correctness guarantee.
+
+Commands:
+  run            Run adversarial verification and emit a report artifact
+  report <path>  Re-render a prior report artifact
+  provision      Stand up prerequisite accounts/sandboxes/data standalone
+  cleanup        Tear down provisioned artefacts (all prefixed 'zzverify-')
+  mcp            Serve verify over MCP (local stdio)
+  help [command] Print help for a command
+
+Options:
+  --version      Print the package version and exit
+  --help         Print this help and exit
+
+Run 'rcf-verify help <command>' for command-specific help.
+`;
+
+const SUB_HELP = {
+  run: RUN_HELP,
+  report: REPORT_HELP,
+  provision: PROVISION_HELP,
+  cleanup: CLEANUP_HELP,
+  mcp: MCP_HELP,
+};
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const topic = argv[0];
+  if (topic && SUB_HELP[topic]) {
+    stdout.write(SUB_HELP[topic]);
+    return 0;
+  }
+  stdout.write(TOP_LEVEL_HELP);
+  return 0;
+}

package/src/verify/cli/mcp.js

@@ -0,0 +1,98 @@
+// `rcf-verify mcp` subcommand (spec §10 MCP; mirrors build's cli/mcp.js).
+// Wires process stdin/stdout/stderr into the core MCP protocol shell and
+// serves the verify tool registry. stdout carries MCP messages and NOTHING
+// else; all logging goes to stderr.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+import { createMcpServer, serveStreams } from '#core/mcp-shell';
+
+import { createToolRegistry } from '../mcp/tools.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export const HELP = `Usage: rcf-verify mcp [options]
+
+Serve verify over the Model Context Protocol (local stdio). Exposes one tool,
+rcf_verify_run, over the same in-process engine the CLI uses. stdout carries
+protocol messages only; logging goes to stderr.
+
+Options:
+  --verbose     Per-request logging on stderr
+  --help        Print this help
+`;
+
+const INSTRUCTIONS = 'Fresh-context adversarial verifier for RCF chains. rcf_verify_run takes an RCF '
+  + 'chain (the acceptance contract) and a running app under a declared runtime profile, launches an '
+  + 'isolated verifier agent that tries to DISPROVE the app against its acceptance criteria, and '
+  + 'returns a structured verdict stamped with the runtime it ran against. Only a "deployed" profile '
+  + '(or a declared --parity-env runtime) yields a SHIP verdict. This is an independent ship-readiness '
+  + 'signal, not a correctness guarantee.';
+
+/**
+ * @param {string[]} argv - argv slice after `mcp`
+ * @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 onSignal = deps.onSignal ?? ((sig, fn) => process.on(sig, fn));
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { verbose: { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  const verbose = Boolean(parsed.values.verbose);
+  const log = {
+    info: verbose ? (line) => stderr.write(`[rcf-verify mcp] ${line}\n`) : () => {},
+    error: (line) => stderr.write(`${line}\n`),
+  };
+
+  const tools = createToolRegistry(deps);
+
+  const server = createMcpServer({
+    serverInfo: { name: 'rcf-verify-lite', version: await readPackageVersion() },
+    instructions: INSTRUCTIONS,
+    capabilities: { tools: {} },
+    handlers: {
+      'tools/list': async () => ({ tools: tools.definitions }),
+      'tools/call': async (params) => {
+        log.info(`tools/call ${params.name}`);
+        return await tools.call(params.name, params.arguments);
+      },
+    },
+    log,
+  });
+
+  stderr.write('rcf-verify mcp: serving\n');
+
+  const { done, stop } = serveStreams(server, { input: stdin, output: stdout, log });
+  onSignal('SIGINT', () => { log.info('received SIGINT, shutting down'); stop(); });
+  onSignal('SIGTERM', () => { log.info('received SIGTERM, shutting down'); stop(); });
+
+  return await done;
+}
+
+async function readPackageVersion() {
+  try {
+    const pkgPath = resolvePath(here, '..', '..', 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}

package/src/verify/cli/provision.js

@@ -0,0 +1,71 @@
+// `rcf-verify provision` (spec §3, §6). Stand up prerequisites standalone and
+// write credentials to the --provision file. Derives what to provision from
+// the chain's ACs (needs --repo). The concrete signup route is app-specific
+// and agent-driven; where it can't be derived, this BLOCKS honestly rather
+// than silently skipping (§6).
+
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '#core/errors';
+
+import { readChain } from '../chain/index.js';
+import { runProvisioning } from '../provision/index.js';
+
+export const HELP = `Usage: rcf-verify provision --repo <path> --url <app-url> --provision <file>
+
+Stand up prerequisite accounts / sandboxes / seed data for a later run.
+Credentials are written to the --provision FILE only, never echoed.
+
+Required:
+  --repo <path>         RCF chain source (to derive what to provision)
+  --url <app-url>       The running app
+  --provision <file>    Where to write provisioned credentials
+
+Exit codes:
+  0  provisioning attempted; see the report of what was provisioned/blocked
+  2  usage error
+  3  chain could not be loaded
+`;
+
+/**
+ * @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;
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { repo: { type: 'string' }, url: { type: 'string' }, provision: { type: 'string' }, help: { type: 'boolean' } }, allowPositionals: false, 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 (!flags.repo || !flags.url || !flags.provision) {
+    stderr.write('[error] usage provision requires --repo, --url and --provision\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  const chain = await (deps.readChain ?? readChain)({ repo: flags.repo });
+  if (isRcfError(chain)) {
+    stderr.write(`${formatError(chain, { verbose: true })}\n`);
+    return 3;
+  }
+
+  const { provisioning } = await runProvisioning({
+    acs: chain.acs,
+    url: flags.url,
+    provisionPath: flags.provision,
+    mode: 'run',
+    signup: deps.signup,
+  });
+
+  stdout.write(`${JSON.stringify(provisioning, null, 2)}\n`);
+  return 0;
+}

package/src/verify/cli/report.js

@@ -0,0 +1,71 @@
+// `rcf-verify report <report-path>` (spec §3, parallels `rcf view`).
+// Re-render / summarise a prior report artifact using verify's own
+// self-contained finding-renderer (§7.2 — no core view dependency).
+
+import { readFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { formatError, isRcfError } from '#core/errors';
+
+import { parseReport } from '../report/index.js';
+import { renderReport } from '../report/renderer.js';
+
+export const HELP = `Usage: rcf-verify report <report-path> [--json]
+
+Re-render a prior report artifact. Default output is the human-readable
+summary; --json re-emits the parsed artifact as JSON.
+
+Exit codes:
+  0  rendered
+  2  usage error (no path)
+  3  the report could not be read / parsed / is an unsupported schema
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `report`
+ * @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: { json: { type: 'boolean' }, help: { type: 'boolean' } }, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  const target = parsed.positionals[0];
+  if (!target) {
+    stderr.write('[error] usage report: a <report-path> is required\n');
+    stderr.write(HELP);
+    return 2;
+  }
+
+  const reader = deps.readFile ?? readFile;
+  let raw;
+  try {
+    raw = await reader(resolvePath(cwd, target), 'utf8');
+  } catch (err) {
+    stderr.write(`[error] missingFile ${target}: ${err.message}\n`);
+    return 3;
+  }
+
+  const report = parseReport(raw);
+  if (isRcfError(report)) {
+    stderr.write(`${formatError(report, { verbose: true })}\n`);
+    return 3;
+  }
+
+  stdout.write(parsed.values.json ? `${JSON.stringify(report, null, 2)}\n` : renderReport(report));
+  return 0;
+}