rcf-lite 0.0.1 → 0.8.0

package/src/browser-verify/runner.js

@@ -0,0 +1,171 @@
+// Browser-verify runner (ui-design-gate-0.7.0-spec §8.2).
+//
+// Two modes:
+// - `operatorSession`: the operator loaded the app and cleared the
+//   pages themselves; the runner takes a minimal input (the routes
+//   they visited, the invariants they ticked) and writes the record.
+// - `agentScreenshotCritique`: the runner drives a browser (injected)
+//   over every enumerated route × theme, captures a DOM string per
+//   capture, runs the versioned invariant set (§8.3), runs the auth
+//   smoke pack when the FBS binds an auth REQ, aggregates the record
+//   verdict per §8.5.
+//
+// Everything driver-shaped is injectable (browser driver, fetch,
+// artefact writer) so unit tests do not need a live Playwright and CI
+// can run this without a real browser. The default agent-mode driver
+// is a stub that returns an empty capture and a `verdict: warn` record
+// with a note pointing at "no driver wired"; production wiring lands
+// via `deps.browserDriver` on the CLI handler.
+
+import { runInvariantsForCapture, foldInvariantsForRecord, compareTopLevelStructure } from './invariants.js';
+import { runAuthSmokeChecks, shouldRunAuthSmokeChecks } from './auth-smoke.js';
+import { composeBrowserVerificationRecord } from './manifest-writer.js';
+
+/**
+ * @typedef {object} BrowserCapture
+ * @property {string} routePath
+ * @property {'light'|'dark'} themeApplied
+ * @property {string} dom
+ * @property {string} screenshotPath
+ * @property {boolean} [authenticated]
+ */
+
+/**
+ * @typedef {object} BrowserDriver
+ * @property {(args: { url: string, routes: object[], themes: ('light'|'dark')[], artefactDir: string }) => Promise<BrowserCapture[]>} capture
+ */
+
+/**
+ * Default agent-mode driver stub. Emits no captures; a warning surfaces
+ * on the record notes. Callers wire a real Playwright driver via
+ * `deps.browserDriver` on the CLI.
+ *
+ * @type {BrowserDriver}
+ */
+export const stubBrowserDriver = Object.freeze({
+  async capture() { return []; },
+});
+
+/**
+ * Run the agent-screenshot-critique mode against a FBS.
+ *
+ * @param {object} args
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {object} args.fbs
+ * @param {string} args.runtimeUrl
+ * @param {'deployed'|'ci'|'local-dev'} args.runtimeProfile
+ * @param {BrowserDriver} args.browserDriver
+ * @param {(url: string, init?: object) => Promise<any>} args.fetch
+ * @param {string} args.artefactDir
+ * @param {string} [args.critiqueNotes]  agent-critique rubric findings (spec §8.4)
+ * @param {Date} [args.now]
+ * @returns {Promise<object>}  the composed browserVerification record
+ */
+export async function runAgentScreenshotCritique({
+  tree, fbs, runtimeUrl, runtimeProfile, browserDriver, fetch, artefactDir, critiqueNotes, now = new Date(),
+}) {
+  const routes = fbs?.designStage?.navModel?.routes ?? [];
+  const themes = readThemesFromBaseline(tree.manifest?.uiBaseline);
+  const captures = await browserDriver.capture({ url: runtimeUrl, routes, themes, artefactDir });
+
+  const perCapture = [];
+  const routesChecked = [];
+  for (const cap of captures) {
+    const results = runInvariantsForCapture({
+      routePath: cap.routePath,
+      themeApplied: cap.themeApplied,
+      fbs,
+      uiBaseline: tree.manifest?.uiBaseline,
+      dom: cap.dom,
+      authenticated: cap.authenticated,
+    });
+    perCapture.push({ routePath: cap.routePath, themeApplied: cap.themeApplied, results });
+    routesChecked.push({ path: cap.routePath, screenshotPath: cap.screenshotPath, themeApplied: cap.themeApplied });
+  }
+
+  // Structural cross-route compare for `sharedLayoutModule`.
+  const structuralResult = compareTopLevelStructure(
+    captures.filter((c) => c.themeApplied === 'light'),
+    tree.manifest?.uiBaseline,
+  );
+
+  let invariantChecks = foldInvariantsForRecord(perCapture);
+  // Replace / append the structural sharedLayoutModule result.
+  invariantChecks = invariantChecks.filter((c) => c.invariant !== 'sharedLayoutModule');
+  invariantChecks.push({
+    invariant: structuralResult.invariant,
+    verdict: structuralResult.verdict,
+    ...(structuralResult.detail ? { detail: structuralResult.detail } : {}),
+    severity: structuralResult.severity,
+  });
+
+  // If no captures came back at all, record a synthetic warn so the
+  // operator sees the "driver was not wired" state distinctly from a
+  // clean pass.
+  let notes = critiqueNotes;
+  if (captures.length === 0) {
+    invariantChecks.push({
+      invariant: 'agentDriverWired',
+      verdict: 'fail',
+      detail: 'browser driver returned zero captures; wire a Playwright driver via deps.browserDriver or run in --mode operatorSession',
+      severity: 'warn',
+    });
+    notes = notes ? `${notes}\n\nDriver: no captures produced.` : 'Driver: no captures produced.';
+    // Ensure schema minimums are met even without captures.
+    if (routesChecked.length === 0) {
+      routesChecked.push({ path: routes[0]?.path ?? '/', screenshotPath: `${artefactDir}/placeholder.png`, themeApplied: 'light' });
+    }
+  }
+
+  let authSmokeChecks;
+  if (shouldRunAuthSmokeChecks(fbs, tree.manifest?.uiBaseline)) {
+    authSmokeChecks = await runAuthSmokeChecks({ fetch, runtimeUrl });
+  }
+
+  return composeBrowserVerificationRecord({
+    manifest: tree.manifest,
+    fbsId: fbs.fbsId,
+    mode: 'agentScreenshotCritique',
+    runtimeProfile,
+    runtimeUrl,
+    routesChecked,
+    invariantChecks,
+    authSmokeChecks,
+    notes,
+    now,
+  });
+}
+
+/**
+ * Compose the operator-session record. No captures; the operator's
+ * declared list of routes plus their invariant ticks are the evidence.
+ *
+ * @param {object} args
+ * @returns {object}
+ */
+export function composeOperatorSessionRecord({
+  tree, fbs, runtimeUrl, runtimeProfile, declaredRoutes, invariantTicks, now = new Date(),
+}) {
+  const routesChecked = declaredRoutes.length > 0
+    ? declaredRoutes.map((r) => ({ path: r.path, screenshotPath: `.rcf/artefacts/operator-session/${fbs.fbsId}${r.path.replace(/\W+/g, '_')}.png`, themeApplied: r.themeApplied ?? 'light' }))
+    : [{ path: fbs?.designStage?.navModel?.routes?.[0]?.path ?? '/', screenshotPath: `.rcf/artefacts/operator-session/${fbs.fbsId}-declared.png`, themeApplied: 'light' }];
+  const invariantChecks = invariantTicks && invariantTicks.length > 0
+    ? invariantTicks.map((t) => ({ invariant: t.invariant, verdict: t.verdict ?? 'pass', ...(t.detail ? { detail: t.detail } : {}), severity: t.severity ?? 'block' }))
+    : [{ invariant: 'operatorAcknowledged', verdict: 'pass', severity: 'block' }];
+  return composeBrowserVerificationRecord({
+    manifest: tree.manifest,
+    fbsId: fbs.fbsId,
+    mode: 'operatorSession',
+    runtimeProfile,
+    runtimeUrl,
+    routesChecked,
+    invariantChecks,
+    now,
+  });
+}
+
+function readThemesFromBaseline(baseline) {
+  const mode = baseline?.defaults?.themeMode;
+  if (mode === 'single-theme-declared') return ['light'];
+  return ['light', 'dark'];
+}

package/src/build/bundle.js

@@ -0,0 +1,198 @@
+// Spec-bundle assembly (Phase 6 §D3). Pure projection of one FBS item
+// and its surroundings into the seven-section bundle shape: header,
+// queue and dependency context, the work, acceptance criteria with
+// US/REQ ancestry, architectural context, existing test surface, and
+// the build-cycle runbook parameters. No I/O, no wall clock, no
+// semantic judgement (§D13): the bundle reports what the tree says.
+//
+// Ordering rules (§D10): acIds and every contextRequirements list
+// render in authored order; dependency and dependent lists sort by
+// buildOrder then fbsId; US groups order by first appearance in the
+// authored acIds.
+
+import { byBuildOrder, computeQueue } from './queue.js';
+
+/**
+ * Copy `fields` from `source` onto a new object, skipping fields not
+ * present. Preserves the given key order (JSON key order is
+ * construction order, §D10).
+ *
+ * @param {object} source
+ * @param {string[]} fields
+ * @returns {object}
+ */
+function pick(source, fields) {
+  const out = {};
+  for (const f of fields) {
+    if (source?.[f] !== undefined) out[f] = source[f];
+  }
+  return out;
+}
+
+/**
+ * Assemble the bundle for one FBS item. The caller (handler) is
+ * responsible for id classification; this function returns null when
+ * the id does not resolve to an FBS document.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {object} opts
+ * @param {string} opts.fbsId
+ * @returns {object|null} BundleResult
+ */
+export function assembleBundle(tree, { fbsId }) {
+  const fbs = tree.byId.get(fbsId);
+  if (!fbs || tree.kindById.get(fbsId) !== 'fbs') return null;
+
+  const queue = computeQueue(tree);
+  const position = queue.items.findIndex((i) => i.fbsId === fbsId) + 1;
+  const queueItem = queue.items[position - 1];
+  const fbsById = new Map((tree.fbsItems ?? []).map((f) => [f.fbsId, f]));
+
+  // Section 1 - header identity (order follows §D14 fbs shape, then
+  // the optional estimate fields and the header's "spec last touched").
+  const fbsBlock = pick(fbs, [
+    'fbsId', 'title', 'buildOrder', 'executionStatus',
+    'summary', 'approach', 'deliverables', 'notes',
+    'estimatedSize', 'estimatedHours', 'riskLevel', 'domain', 'updatedAt',
+  ]);
+
+  // Section 2 - queue and dependency context.
+  const dependencies = (fbs.dependsOnFbsIds ?? [])
+    .map((depId) => fbsById.get(depId) ?? { fbsId: depId })
+    .sort(byBuildOrder)
+    .map((dep) => pick(dep, ['fbsId', 'title', 'executionStatus']));
+  const dependents = (tree.dependentsByFbsId.get(fbsId) ?? [])
+    .map((depId) => fbsById.get(depId) ?? { fbsId: depId })
+    .sort(byBuildOrder)
+    .map((dep) => dep.fbsId);
+  const blockedBy = queueItem ? queueItem.blockedBy : [];
+
+  // Section 4 - acceptance criteria with US/REQ ancestry. Groups order
+  // by first appearance in the authored acIds; ACs within a group keep
+  // the authored acIds order.
+  const usOrder = [];
+  const acsByUs = new Map();
+  for (const acId of fbs.acIds ?? []) {
+    const usId = tree.parentByChild.get(acId);
+    const us = usId ? tree.byId.get(usId) : null;
+    if (!us) continue; // Broken cross-links cannot occur post-walker (§D6).
+    if (!acsByUs.has(usId)) {
+      usOrder.push(usId);
+      acsByUs.set(usId, []);
+    }
+    const ac = (us.acceptanceCriteria ?? []).find((a) => a.id === acId);
+    if (ac) acsByUs.get(usId).push(ac);
+  }
+
+  const acceptanceCriteria = [];
+  const userStories = [];
+  const requirements = [];
+  const seenReqs = new Set();
+  for (const usId of usOrder) {
+    const us = tree.byId.get(usId);
+    userStories.push(pick(us, ['usId', 'title', 'asA', 'iWant', 'soThat', 'status']));
+    const req = tree.byId.get(us.reqId);
+    if (req && !seenReqs.has(req.reqId)) {
+      seenReqs.add(req.reqId);
+      requirements.push(pick(req, ['reqId', 'title', 'description', 'category', 'priority', 'rationale']));
+    }
+    for (const ac of acsByUs.get(usId)) {
+      acceptanceCriteria.push({
+        ...pick(ac, ['id', 'description', 'given', 'when', 'then', 'testable']),
+        usId,
+        reqId: us.reqId,
+      });
+    }
+  }
+
+  // Section 5 - architectural context (§D11). Omitted entirely when
+  // contextRequirements is absent.
+  let context;
+  const ctx = fbs.contextRequirements;
+  if (ctx) {
+    const tacs = (ctx.tacIds ?? [])
+      .map((id) => tree.byId.get(id))
+      .filter(Boolean)
+      .map((tac) => pick(tac, [
+        'tacId', 'name', 'purpose', 'responsibilities', 'interfaces',
+        'dependencies', 'tradeoffs', 'notes',
+      ]));
+    const adrs = (ctx.adrIds ?? [])
+      .map((id) => tree.byId.get(id))
+      .filter(Boolean)
+      .map((adr) => pick(adr, [
+        'adrId', 'title', 'status', 'context', 'decision', 'consequences',
+        'alternativesConsidered',
+      ]));
+    const unresolvedSections = [];
+    const resolveSections = (names, doc) => {
+      const out = {};
+      for (const name of names ?? []) {
+        if (doc && Object.prototype.hasOwnProperty.call(doc, name)) {
+          out[name] = doc[name];
+        } else {
+          unresolvedSections.push(name);
+        }
+      }
+      return out;
+    };
+    const tadSections = resolveSections(ctx.tadSections, tree.tad);
+    const prdSections = resolveSections(ctx.prdSections, tree.prd);
+    context = {
+      tacs,
+      adrs,
+      tadSections,
+      prdSections,
+      unresolvedSections,
+      passThrough: {
+        existingModules: ctx.existingModules ?? [],
+        schemas: ctx.schemas ?? [],
+        externalDocs: ctx.externalDocs ?? [],
+        other: ctx.other ?? [],
+      },
+    };
+  }
+
+  // Section 6 - existing test surface. Presence reporting off the
+  // walker maps, not a coverage verdict (§D7). The per-AC `covered`
+  // flag here is PRESENCE-based (at least one TC row via tcsByAcId);
+  // since w-2026-07-28-005, computeCoverage's own leaf test is stricter
+  // (the TC's testPointer must resolve to a real test). `rcf coverage`
+  // is the coverage surface; this section only lists what is on the
+  // tree, pointers included, so the builder can see what exists.
+  const tests = acceptanceCriteria.map((ac) => {
+    const suites = tree.tsByAcId.get(ac.id) ?? [];
+    const cases = (tree.tcsByAcId.get(ac.id) ?? []).map(({ tsId, tcId }) => {
+      const ts = tree.byId.get(tsId);
+      const tc = (ts?.testCases ?? []).find((c) => c.id === tcId) ?? {};
+      return { tcId, tsId, ...pick(tc, ['description', 'status', 'testPointer']) };
+    });
+    return { acId: ac.id, covered: cases.length > 0, suites, cases };
+  });
+
+  // Section 7 - completion contract (static, parameterised by fbsId).
+  const completionContract = {
+    markInProgress: `rcf build ${fbsId} --mark inProgress`,
+    markComplete: `rcf build ${fbsId} --mark complete`,
+    finalise: `rcf finalise ${fbsId} --url <deploy-url>`,
+  };
+
+  const result = {
+    fbs: fbsBlock,
+    queue: { position, total: queue.items.length },
+    bs: tree.bs
+      ? pick(tree.bs, ['bsId', 'title', 'buildPhilosophy', 'generationStrategy'])
+      : null,
+    prd: tree.prd ? pick(tree.prd, ['prdId', 'productName']) : null,
+    blockedBy,
+    dependencies,
+    dependents,
+    acceptanceCriteria,
+    userStories,
+    requirements,
+    ...(context ? { context } : {}),
+    tests,
+    completionContract,
+  };
+  return result;
+}

package/src/build/formatters/json.js

@@ -0,0 +1,18 @@
+// JSON formatter for the build verb (Phase 6 §D14). Envelope shapes
+// are stable-by-convention, same contract discipline as Phase 5 D15:
+// no in-place reshape without a new flag or subcommand. These
+// envelopes are the Phase 7 MCP layer's anchor. camelCase throughout;
+// serialisation via JSON.stringify with construction-ordered keys
+// (§D10 determinism).
+
+/**
+ * Format a build result as a JSON envelope.
+ *
+ * @param {object} result - QueueResult | BundleResult | next-mode empty envelope
+ * @param {('queue'|'bundle'|'next')} mode
+ * @returns {string}
+ */
+export function formatJson(result, mode) {
+  const envelope = { ok: true, mode, ...result };
+  return `${JSON.stringify(envelope, null, 2)}\n`;
+}