rcf-lite 0.0.1 → 0.8.0

package/src/build/queue.js

@@ -0,0 +1,285 @@
+// Build queue semantics (Phase 6 §D2). Pure projection of the FBS
+// documents into a deterministic queue: per-item derived state
+// (actionable / blocked / inProgress / complete / verified), cycle
+// detection over the dependency graph, aggregate totals and next-item
+// selection. No I/O, no wall clock, no mutation of the tree.
+//
+// An FBS item is ACTIONABLE when its executionStatus is `notStarted`
+// AND every id in dependsOnFbsIds resolves to an FBS whose status is
+// `complete` or `verified`. `notStarted` with an unsatisfied dependency
+// is BLOCKED. `inProgress` is neither: it is in flight and selection
+// skips it (the envelope surfaces it so a harness can notice an
+// abandoned claim). Dependency cycles make every member permanently
+// blocked; the queue labels them `blocked (cycle)` rather than crashing
+// (`rcf validate` remains the integrity surface).
+//
+// Each item also carries a TIER: the length of its longest dependency
+// chain (tier 0 = no dependencies). Items sharing a tier have no
+// dependency path between them, so a tier is a parallel-safe group -
+// its members can be built concurrently (AC-502-2). This is a port of
+// the full RCF platform's `computeTiers` (rcf-common build-graph),
+// adapted to the queue's data model and cycle posture: a cycle member,
+// or any item whose dependency chain runs into a cycle, has no defined
+// chain length, so its tier is null and it joins no group (it is
+// already reported `blocked (cycle)` / blocked above).
+
+/** Lifecycle order (common.schema.json executionStatus enum). */
+export const LIFECYCLE = ['notStarted', 'inProgress', 'complete', 'verified'];
+
+const SATISFIED = new Set(['complete', 'verified']);
+
+/**
+ * @typedef {object} QueueItem
+ * @property {string} fbsId
+ * @property {number} buildOrder
+ * @property {string} title
+ * @property {string} executionStatus
+ * @property {string[]} dependsOnFbsIds
+ * @property {number|null} tier - parallel-safe group (longest dependency
+ *   chain length; null when the chain runs into a cycle)
+ * @property {('actionable'|'blocked'|'inProgress'|'complete'|'verified')} state
+ * @property {string[]} blockedBy - dependency ids not yet complete/verified
+ * @property {boolean} [cycle] - present (true) on blocked cycle members
+ */
+
+/**
+ * @typedef {object} TierGroup
+ * @property {number} tier - 0-based tier number (0 = no dependencies)
+ * @property {string[]} fbsIds - members, in queue order; no dependency
+ *   path exists between any two of them, so they are parallel-safe
+ */
+
+/**
+ * @typedef {object} QueueResult
+ * @property {{bsId: string, title: string, generationStrategy: string}|null} bs
+ * @property {object} totals
+ * @property {string|null} nextActionable
+ * @property {TierGroup[]} tiers - parallel-safe groups, tier ascending
+ * @property {QueueItem[]} items
+ */
+
+/**
+ * Sort comparator: buildOrder ascending, fbsId lexicographic tie-break
+ * (§D2 - the schema does not enforce buildOrder uniqueness, so the
+ * tie-break keeps the total order deterministic).
+ *
+ * @param {{buildOrder?: number, fbsId?: string}} a
+ * @param {{buildOrder?: number, fbsId?: string}} b
+ * @returns {number}
+ */
+export function byBuildOrder(a, b) {
+  const orderA = a.buildOrder ?? 0;
+  const orderB = b.buildOrder ?? 0;
+  if (orderA !== orderB) return orderA - orderB;
+  return (a.fbsId ?? '').localeCompare(b.fbsId ?? '');
+}
+
+/**
+ * Find every FBS id that sits on a dependency cycle. Standard
+ * iterative DFS with a colour map over the dependsOnFbsIds edges;
+ * when a back edge closes a loop, every node on the current stack
+ * segment from the loop entry is a cycle member.
+ *
+ * @param {Map<string, object>} fbsById
+ * @returns {Set<string>}
+ */
+function findCycleMembers(fbsById) {
+  const members = new Set();
+  const state = new Map(); // id -> 'visiting' | 'done'
+  const stack = [];
+
+  const visit = (startId) => {
+    // Iterative DFS frame stack: [id, depIndex].
+    const frames = [[startId, 0]];
+    while (frames.length > 0) {
+      const frame = frames[frames.length - 1];
+      const [id] = frame;
+      if (frame[1] === 0) {
+        state.set(id, 'visiting');
+        stack.push(id);
+      }
+      const deps = fbsById.get(id)?.dependsOnFbsIds ?? [];
+      if (frame[1] >= deps.length) {
+        state.set(id, 'done');
+        stack.pop();
+        frames.pop();
+        continue;
+      }
+      const depId = deps[frame[1]];
+      frame[1] += 1;
+      if (!fbsById.has(depId)) continue;
+      const depState = state.get(depId);
+      if (depState === 'visiting') {
+        // Back edge: every id on the stack from depId onward is a member.
+        const from = stack.indexOf(depId);
+        for (let i = from; i < stack.length; i += 1) members.add(stack[i]);
+      } else if (depState === undefined) {
+        frames.push([depId, 0]);
+      }
+    }
+  };
+
+  for (const id of fbsById.keys()) {
+    if (!state.has(id)) visit(id);
+  }
+  return members;
+}
+
+/**
+ * Compute the tier of every FBS id: the length of its longest
+ * dependency chain (tier 0 = no dependencies). Port of the platform's
+ * `computeTiers` memoised longest-chain DFS, iterative in the style of
+ * findCycleMembers. Cycle handling reuses the members findCycleMembers
+ * already detected rather than re-implementing detection: a member, or
+ * any item whose chain reaches one, gets tier null (no defined chain
+ * length) - the walk short-circuits there, so a cyclic graph can never
+ * loop it. A dependency id that resolves to no FBS contributes chain
+ * length 0 (same as the platform port; `rcf validate` is the
+ * broken-reference surface).
+ *
+ * @param {Map<string, object>} fbsById
+ * @param {Set<string>} cycleMembers
+ * @returns {Map<string, number|null>}
+ */
+function computeTiers(fbsById, cycleMembers) {
+  const tiers = new Map(); // id -> number | null
+
+  const compute = (startId) => {
+    // Iterative DFS frame stack: [id, depIndex, maxDepTier]; maxDepTier
+    // null = poisoned by a cycle somewhere beneath this item.
+    const frames = [[startId, 0, -1]];
+    while (frames.length > 0) {
+      const frame = frames[frames.length - 1];
+      const [id] = frame;
+      if (cycleMembers.has(id)) {
+        tiers.set(id, null);
+        frames.pop();
+        continue;
+      }
+      const deps = fbsById.get(id)?.dependsOnFbsIds ?? [];
+      if (frame[1] >= deps.length) {
+        tiers.set(id, frame[2] === null ? null : frame[2] + 1);
+        frames.pop();
+        continue;
+      }
+      const depId = deps[frame[1]];
+      frame[1] += 1;
+      if (frame[2] === null) continue; // already poisoned; drain remaining deps
+      const depTier = fbsById.has(depId) ? tiers.get(depId) : 0;
+      if (depTier === undefined) {
+        // Unresolved dependency: compute it first, then revisit this edge.
+        frame[1] -= 1;
+        frames.push([depId, 0, -1]);
+      } else if (depTier === null) {
+        frame[2] = null;
+      } else if (depTier > frame[2]) {
+        frame[2] = depTier;
+      }
+    }
+  };
+
+  for (const id of fbsById.keys()) {
+    if (!tiers.has(id)) compute(id);
+  }
+  return tiers;
+}
+
+/**
+ * Group tiered items into parallel-safe TierGroups, tier ascending,
+ * members in queue order. Null-tier (cycle-tainted) items join no
+ * group.
+ *
+ * @param {QueueItem[]} items - already in queue order
+ * @returns {TierGroup[]}
+ */
+function groupTiers(items) {
+  const byTier = new Map(); // tier -> fbsIds
+  for (const item of items) {
+    if (item.tier === null) continue;
+    if (!byTier.has(item.tier)) byTier.set(item.tier, []);
+    byTier.get(item.tier).push(item.fbsId);
+  }
+  return [...byTier.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([tier, fbsIds]) => ({ tier, fbsIds }));
+}
+
+/**
+ * Compute the queue over a walked tree. Deterministic: same tree,
+ * same result, always.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @returns {QueueResult}
+ */
+export function computeQueue(tree) {
+  const fbsItems = [...(tree.fbsItems ?? [])].sort(byBuildOrder);
+  const fbsById = new Map(fbsItems.map((f) => [f.fbsId, f]));
+  const cycleMembers = findCycleMembers(fbsById);
+  const tierById = computeTiers(fbsById, cycleMembers);
+
+  const items = fbsItems.map((fbs) => {
+    const deps = fbs.dependsOnFbsIds ?? [];
+    const blockedBy = deps
+      .filter((depId) => !SATISFIED.has(fbsById.get(depId)?.executionStatus))
+      .map((depId) => fbsById.get(depId) ?? { fbsId: depId, buildOrder: 0 })
+      .sort(byBuildOrder)
+      .map((dep) => dep.fbsId);
+    let state;
+    if (fbs.executionStatus === 'notStarted') {
+      state = blockedBy.length === 0 ? 'actionable' : 'blocked';
+    } else {
+      state = fbs.executionStatus;
+    }
+    const item = {
+      fbsId: fbs.fbsId,
+      buildOrder: fbs.buildOrder,
+      tier: tierById.get(fbs.fbsId),
+      title: fbs.title,
+      executionStatus: fbs.executionStatus,
+      dependsOnFbsIds: deps,
+      state,
+      blockedBy,
+    };
+    if (state === 'blocked' && cycleMembers.has(fbs.fbsId)) item.cycle = true;
+    return item;
+  });
+
+  const totals = {
+    items: items.length,
+    notStarted: items.filter((i) => i.executionStatus === 'notStarted').length,
+    inProgress: items.filter((i) => i.executionStatus === 'inProgress').length,
+    complete: items.filter((i) => i.executionStatus === 'complete').length,
+    verified: items.filter((i) => i.executionStatus === 'verified').length,
+    actionable: items.filter((i) => i.state === 'actionable').length,
+    blocked: items.filter((i) => i.state === 'blocked').length,
+  };
+
+  const next = selectNextItem(items);
+  const bs = tree.bs
+    ? { bsId: tree.bs.bsId, title: tree.bs.title, generationStrategy: tree.bs.generationStrategy }
+    : null;
+
+  return { bs, totals, nextActionable: next ? next.fbsId : null, tiers: groupTiers(items), items };
+}
+
+/**
+ * Select the next actionable item from a computed queue: lowest
+ * buildOrder (fbsId tie-break) among actionable items. Items are
+ * already in total order, so the first actionable wins.
+ *
+ * @param {QueueItem[]} items
+ * @returns {QueueItem|null}
+ */
+function selectNextItem(items) {
+  return items.find((i) => i.state === 'actionable') ?? null;
+}
+
+/**
+ * Select the next actionable FBS item from a QueueResult.
+ *
+ * @param {QueueResult} queue
+ * @returns {QueueItem|null}
+ */
+export function selectNext(queue) {
+  return selectNextItem(queue.items);
+}

package/src/cli/browser-verify.js

@@ -0,0 +1,231 @@
+// `rcf browser-verify <fbs-id>` handler
+// (ui-design-gate-0.7.0-spec §8, §9).
+//
+// Two modes:
+//   --mode operatorSession           record an operator ack (no captures)
+//   --mode agentScreenshotCritique   run the injected browser driver,
+//                                    capture routes x themes, run
+//                                    invariants + auth smoke, write the
+//                                    browserVerification record.
+//
+// The agent driver is injectable via `deps.browserDriver`; the default
+// stub emits zero captures and the record surfaces a warn on the
+// `agentDriverWired` synthetic invariant, so the CLI is testable
+// end-to-end without a live Playwright.
+//
+// --ack marks operatorAckAt on the latest record for the FBS (used to
+// clear a warn verdict per §8.5).
+
+import { parseArgs } from 'node:util';
+import process from 'node:process';
+
+import { walkTree } from '#core/store';
+import { writeUnexpectedFailure, rcfError } from '#core/errors';
+
+import { findProjectRoot } from '../view/index.js';
+import {
+  composeOperatorSessionRecord,
+  runAgentScreenshotCritique,
+  stubBrowserDriver,
+  writeBrowserVerificationAck,
+  writeBrowserVerificationRecord,
+} from '../browser-verify/index.js';
+
+const OPTION_SPEC = {
+  mode: { type: 'string' },
+  url: { type: 'string' },
+  profile: { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  json: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  ack: { type: 'boolean' },
+  notes: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf browser-verify <fbs-id> [options]
+
+Stage 5 browser-verification gate for a UI-bearing FBS. Writes a
+browserVerification record on the manifest; the finalise gate reads it.
+
+Options:
+  --mode <mode>             operatorSession | agentScreenshotCritique
+                            (default: agentScreenshotCritique)
+  --url <url>               Runtime URL to drive against (default: taken
+                            from --profile, else http://127.0.0.1:3000).
+  --profile <profile>       deployed | ci | local-dev (default: local-dev)
+  --notes "..."             Agent-critique rubric findings to record on
+                            the browserVerification.notes field.
+  --dry-run                 Print the composed record; do not write.
+  --json                    Emit the composed record as JSON to stdout.
+  --quiet                   Suppress non-error confirmations.
+  --ack                     Mark operatorAckAt on the latest record for
+                            this FBS (used to clear a warn verdict).
+  --help                    Print this help.
+
+Exit codes:
+  0  verdict pass
+  1  IO / unexpected runtime failure
+  2  usage error
+  3  schema or tree validation failure
+  4  verdict warn or block (Stage 5 refused; --ack clears a warn)
+`;
+
+/**
+ * @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 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 browser-verify: expected exactly one <fbs-id> positional\n');
+    return 2;
+  }
+  const fbsId = parsed.positionals[0];
+  if (!/^FBS-\d{3,}$/.test(fbsId)) {
+    stderr.write(`[error] usage browser-verify: expected an FBS id like FBS-011, got '${fbsId}'\n`);
+    return 2;
+  }
+  const mode = flags.mode ?? 'agentScreenshotCritique';
+  if (!['operatorSession', 'agentScreenshotCritique'].includes(mode)) {
+    stderr.write(`[error] usage browser-verify: unknown --mode '${mode}' (expected operatorSession | agentScreenshotCritique)\n`);
+    return 2;
+  }
+  const profile = flags.profile ?? 'local-dev';
+  if (!['deployed', 'ci', 'local-dev'].includes(profile)) {
+    stderr.write(`[error] usage browser-verify: unknown --profile '${profile}' (expected deployed | ci | local-dev)\n`);
+    return 2;
+  }
+  const runtimeUrl = flags.url ?? defaultUrlForProfile(profile);
+
+  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;
+  const fbs = tree.byId.get(fbsId);
+  if (!fbs || tree.kindById.get(fbsId) !== 'fbs') {
+    stderr.write(`[error] usage browser-verify: ${fbsId} not found or not an FBS\n`);
+    return 2;
+  }
+  if (fbs.uiBearing !== true) {
+    stderr.write(`[warn] browser-verify: ${fbsId} is not uiBearing; the browser gate is a no-op. Set uiBearing=true if this FBS renders UI.\n`);
+  }
+  const now = deps.now ? new Date(deps.now()) : new Date();
+
+  if (flags.ack) {
+    const result = await writeBrowserVerificationAck({
+      projectRoot, tree, fbsId, operatorAckAt: true, now,
+    });
+    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(`browser-verify --ack: recorded operatorAckAt on latest record for ${fbsId}.\n`);
+    return 0;
+  }
+
+  let record;
+  try {
+    if (mode === 'operatorSession') {
+      record = composeOperatorSessionRecord({
+        tree, fbs, runtimeUrl, runtimeProfile: profile,
+        declaredRoutes: [],
+        invariantTicks: [{ invariant: 'operatorAcknowledged', verdict: 'pass', severity: 'block' }],
+        now,
+      });
+    } else {
+      const browserDriver = deps.browserDriver ?? stubBrowserDriver;
+      const fetchFn = deps.fetch ?? (typeof fetch === 'function' ? fetch : null);
+      if (!fetchFn) {
+        stderr.write('[error] usage browser-verify: no fetch available in the runtime; supply deps.fetch\n');
+        return 2;
+      }
+      record = await runAgentScreenshotCritique({
+        tree, fbs, runtimeUrl, runtimeProfile: profile,
+        browserDriver, fetch: fetchFn,
+        artefactDir: `.rcf/artefacts/${fbsId.toLowerCase()}`,
+        critiqueNotes: flags.notes,
+        now,
+      });
+    }
+  } catch (err) {
+    writeUnexpectedFailure(
+      rcfError({ kind: 'ioFailure', message: `browser-verify: ${err.message}`, stack: err.stack }),
+      stderr,
+    );
+    return 1;
+  }
+
+  if (flags.json) stdout.write(`${JSON.stringify(record, null, 2)}\n`);
+
+  if (flags['dry-run']) {
+    if (!flags.quiet) {
+      renderSummary({ stdout, record });
+    }
+    return record.verdict === 'pass' ? 0 : 4;
+  }
+
+  const write = await writeBrowserVerificationRecord({ projectRoot, tree, record });
+  if (write && 'kind' in write && 'message' in write) {
+    if (write.kind === 'ioFailure') { writeUnexpectedFailure(write, stderr); return 1; }
+    stderr.write(`[error] ${write.kind} ${write.message}\n`);
+    if (write.kind === 'usage') return 2;
+    if (write.kind === 'validation') return 3;
+    return 1;
+  }
+  if (!flags.quiet) {
+    renderSummary({ stdout, record });
+    stdout.write(`browser-verify ${fbsId}: wrote ${record.id} to rcf/manifest.json (verdict=${record.verdict}).\n`);
+  }
+  return record.verdict === 'pass' ? 0 : 4;
+}
+
+function defaultUrlForProfile(profile) {
+  if (profile === 'ci') return 'http://127.0.0.1:3000';
+  if (profile === 'deployed') return '';
+  return 'http://127.0.0.1:3000';
+}
+
+function renderSummary({ stdout, record }) {
+  stdout.write(`\nbrowser-verify ${record.fbsId} (${record.mode}, ${record.runtimeProfile})\n`);
+  if (typeof record.notes === 'string' && record.notes.length > 0) {
+    stdout.write('  agent critique:\n');
+    for (const line of record.notes.split('\n')) stdout.write(`    ${line}\n`);
+  }
+  stdout.write('  invariant checks:\n');
+  for (const c of record.invariantChecks) {
+    const detail = c.detail ? ` - ${c.detail}` : '';
+    stdout.write(`    [${c.verdict}] ${c.invariant}${detail}\n`);
+  }
+  if (Array.isArray(record.authSmokeChecks) && record.authSmokeChecks.length > 0) {
+    stdout.write('  auth smoke checks:\n');
+    for (const c of record.authSmokeChecks) {
+      const detail = c.detail ? ` - ${c.detail}` : '';
+      stdout.write(`    [${c.verdict}] ${c.check} (status=${c.status ?? 'n/a'})${detail}\n`);
+    }
+  }
+  stdout.write(`  verdict: ${record.verdict}\n\n`);
+}