rcf-lite 0.28.2 → 0.29.0

package/src/view/index.js

@@ -6,16 +6,33 @@
 
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { stat } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 
-import { walkTree } from '#core/store';
+import { resolveTestPointers, walkTree } from '#core/store';
+import { computeReadiness } from '../query/readiness.js';
+import { computeQuestions } from '../query/questions.js';
+import { loadFreezeRecord } from '../define/freeze-record.js';
+import { loadAllLedgers } from '../define/ledgers.js';
 import { renderContent, renderPage } from './html-page.js';
+import { renderProductMapGrouping } from './product-map.js';
 import { buildTreeModel } from './tree-model.js';
+import { serialiseViewIndex } from './view-index.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 export const VENDORED_MERMAID_PATH = resolve(here, 'vendored', 'mermaid.min.js');
 export const STYLE_CSS_PATH = resolve(here, 'style.css');
 export const LIVE_CLIENT_PATH = resolve(here, 'live-client.js');
+// Viewer UI refresh PR 1 (Dex / wespa 2026-10-02 #263): the former
+// inline <script> block from html-page.js now lives at this path and
+// is served over the new /page-init.js route. Release notes name it so
+// wespa's proxy allow-list is extended before any version pin bump.
+export const PAGE_INIT_PATH = resolve(here, 'page-init.js');
+// Viewer UI refresh PR 9 (TAC-4134, ADR-4136): wespa host fixture
+// client script. Served over /test-host.js only when the server is
+// started with testHost: true (CLI --test-host or RCF_VIEW_TEST_HOST=1).
+// Off the default route surface so wespa's proxy allow-list is
+// unaffected.
+export const TEST_HOST_CLIENT_PATH = resolve(here, 'test-host', 'embed-client.js');
 
 /**
  * Walk up from `start` looking for an ancestor directory containing a
@@ -56,8 +73,97 @@ export async function findProjectRoot(start) {
  */
 export async function renderModelToPage({ projectRoot }) {
   const { tree, errors } = await walkTree({ projectRoot });
+
+  // Load the readiness inputs once per rewalk; the viewer is pure
+  // (never recomputes readiness). Failures load as `null` so the tab
+  // still renders when a tree is partial.
+  const [freezeRecord, ledgers, testPointers, profileText] = await Promise.all([
+    loadFreezeRecord({ projectRoot }).catch(() => null),
+    loadAllLedgers({ projectRoot }).catch(() => ({})),
+    resolveTestPointers({ projectRoot, tree }).catch(() => undefined),
+    readProfileText(projectRoot),
+  ]);
+
+  let readiness = null;
+  try {
+    readiness = computeReadiness(tree, {
+      freeze: freezeRecord,
+      ledgers,
+      profile: undefined,
+      profileText,
+      testPointers,
+      validateErrors: errors,
+    });
+  } catch (err) {
+    // A malformed tree should not block the viewer; the Readiness tab
+    // renders its "could not be computed" placeholder in that case.
+    readiness = null;
+  }
+
+  // Viewer UI refresh PR 8 (TAC-4133, ADR-4135, AC-18002-1): fold the
+  // DEFINE step 3 PR 2 `computeQuestions` output onto the readiness
+  // object before the view reads it, so the PO layer's question
+  // adapter feature-detects the real shape (`questions[]`, `groups[]`,
+  // `optional[]`, `engineer.blockers`) rather than falling back to the
+  // blockers path. Pure fold; `computeQuestions` is a composer over
+  // the same readiness object and writes nothing under rcf/.
+  if (readiness) {
+    try {
+      const q = computeQuestions(readiness, {
+        tree,
+        ledgers,
+        profileText,
+        persona: 'productOwner',
+      });
+      readiness.questions = q.questions;
+      readiness.questionGroups = q.groups;
+      readiness.questionOptional = q.optional;
+      readiness.questionEngineer = q.engineer ?? null;
+    } catch {
+      // Composition failure never blocks the viewer; the adapter falls
+      // back to the blockers path when `readiness.questions` is absent.
+    }
+  }
+
   const model = buildTreeModel({ tree, errors });
+  model.readiness = readiness;
+  model.profileText = profileText;
+  model.freezeRecord = freezeRecord;
   const fullPageHtml = renderPage(model);
   const contentHtml = renderContent(model);
-  return { fullPageHtml, contentHtml, errors, tree };
+  // Pre-rendered partials for the /product-map/<group> endpoint
+  // (AC-17007-1). The full page ships only the shape grouping's REQ
+  // cards; the client fetches the other three on demand from these
+  // strings. Regenerated on every rewalk so the cache stays consistent
+  // with the tree on disk.
+  const pmPartials = {
+    shape: renderProductMapGrouping(model, 'shape'),
+    component: renderProductMapGrouping(model, 'component'),
+    trace: renderProductMapGrouping(model, 'trace'),
+    capability: renderProductMapGrouping(model, 'capability'),
+    blueprint: renderProductMapGrouping(model, 'blueprint'),
+  };
+  // Viewer UI refresh PR 7 (TAC-4132, ADR-4134): the ID lookup index
+  // is built on every rewalk from BuiltTreeModel and served from the
+  // new `./index.json` route (release-noted so wespa's proxy allow-
+  // list is extended before the version pin bump). One row per doc id
+  // plus one row per AC under each US.
+  const indexJson = serialiseViewIndex(model);
+  return { fullPageHtml, contentHtml, errors, tree, pmPartials, indexJson };
+}
+
+/**
+ * Read `rcf/.identity/profile.md` text or return null when the file
+ * is absent (the Readiness tab orders persona groups as PO-first in
+ * the absent case).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string | null>}
+ */
+async function readProfileText(projectRoot) {
+  try {
+    return await readFile(join(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
+  } catch (err) {
+    return null;
+  }
 }

package/src/view/live-client.js

@@ -185,7 +185,10 @@
   function fetchScope(slug, fetchImpl) {
     var f = typeof fetchImpl === 'function' ? fetchImpl : (typeof fetch === 'function' ? fetch : null);
     if (!f) return Promise.reject(new Error('no fetch available'));
-    var url = '/scope.json?blueprint=' + encodeURIComponent(slug);
+    // Dex / wespa 2026-10-02 (#263, PR 1): asset references are relative
+    // so the viewer works under the proxy mount (/rcf-viewer/) without
+    // path rewrites.
+    var url = './scope.json?blueprint=' + encodeURIComponent(slug);
     return Promise.resolve(f(url)).then(function (resp) {
       if (!resp) throw new Error('scope: no response');
       var okFlag = resp.ok !== undefined ? resp.ok : (resp.status >= 200 && resp.status < 300);
@@ -410,7 +413,9 @@
       setState('disconnected');
       return;
     }
-    var source = new EventSourceCtor('/events');
+    // Dex / wespa 2026-10-02 (#263, PR 1): relative so the stream
+    // works under the proxy mount without a rewrite rule.
+    var source = new EventSourceCtor('./events');
 
     source.onopen = function () {
       lastEventAt = Date.now();
@@ -434,6 +439,17 @@
         host.innerHTML = payload.contentHtml;
       }
       currentVersion = payload.version;
+      // The Product Map panel keeps a client-side partial cache
+      // (window.__rcfPmPartialCache is opaque to us). A tree-update
+      // invalidates every partial: the next activatePmGroup on a lazy
+      // grouping refetches instead of using the stale cache. See
+      // hydrateLazyGroup in the inline script.
+      win.__rcfPmDirty = true;
+      // Viewer UI refresh PR 7 (TAC-4132, ADR-4134): the ID lookup
+      // index is a snapshot of the tree. A tree-update invalidates
+      // whichever rows the client last fetched; wireLookup refetches
+      // on the next modal open instead of staying stale.
+      win.__rcfLookupDirty = true;
       // Tab buttons live in the header (outside the swap wrapper) so
       // their click handlers survive. But the swap serves every panel
       // with the same `hidden` state Phase 3.6 renders (Overview
@@ -442,6 +458,13 @@
       // Mermaid inside the selected panel because .mermaid nodes in
       // the payload have no `data-processed` yet.
       resyncTabsAfterSwap(doc, win);
+      // Re-invoke the page init so pm-group-btn / pm-status-select
+      // listeners (which lived inside the swapped wrapper) are attached
+      // to the fresh DOM. onReady is idempotent for the header-scoped
+      // bindings that survive the swap.
+      if (win.rcfPage && typeof win.rcfPage.init === 'function') {
+        try { win.rcfPage.init(); } catch (e) { /* soft */ }
+      }
       restoreState(deps);
       applyScope();
       setState('connected');
@@ -484,8 +507,15 @@
   // the panels back in line with the aria-selected button and re-run
   // Mermaid in the visible one.
   function resyncTabsAfterSwap(doc, win) {
-    var TABS = ['overview', 'requirements', 'architecture', 'build'];
-    var selectedBtn = doc.querySelector('[role="tab"][aria-selected="true"]');
+    // Phase 3.8 tabs; Phase 3.9 added product-map. Product Map MUST be
+    // in this list so an SSE swap while it is the active tab keeps the
+    // panel visible; without it, resolveActiveTab falls back to
+    // overview and the freshly-swapped pm listeners have already been
+    // rewired by the rcfPage.init() call below.
+    var TABS = ['overview', 'requirements', 'architecture', 'build', 'product-map'];
+    // Scope to the top-level nav.tabs to avoid matching pm-group-btn
+    // nodes (they also carry role="tab").
+    var selectedBtn = doc.querySelector('nav.tabs [role="tab"][aria-selected="true"]');
     var selected = selectedBtn && selectedBtn.getAttribute ? selectedBtn.getAttribute('data-tab') : null;
     if (!selected || TABS.indexOf(selected) === -1) selected = 'overview';
     for (var i = 0; i < TABS.length; i += 1) {
@@ -515,8 +545,25 @@
     };
   }
 
+  // Connection pill: the shell footer renders #rcf-conn-pill (viewer UI
+   // refresh PR 1 follow-up: pill moved from a floating top-right dot
+   // into the footer). If the pill is missing (older shell, embedded
+   // snippet, no-shell contexts), fall back to injecting a floating dot
+   // so the live-status signal is never silently dropped.
+  function pillLabelFor(state) {
+    if (state === 'connected') return 'Live updates on';
+    if (state === 'reconnecting') return 'Reconnecting…';
+    return 'Disconnected';
+  }
+
+  function pillTitleFor(state) {
+    if (state === 'connected') return 'Connected - live updates on';
+    if (state === 'reconnecting') return 'Reconnecting to view server...';
+    return 'Disconnected from view server';
+  }
+
   function injectConnectionDot(doc) {
-    if (doc.getElementById('rcf-conn-dot')) return;
+    if (doc.getElementById('rcf-conn-pill') || doc.getElementById('rcf-conn-dot')) return;
     var style = doc.createElement('style');
     style.textContent = [
       '#rcf-conn-dot {',
@@ -540,12 +587,18 @@
   }
 
   function updateDot(doc, state) {
+    var pill = doc.getElementById('rcf-conn-pill');
+    if (pill) {
+      pill.className = 'live ' + state;
+      pill.title = pillTitleFor(state);
+      var label = pill.querySelector('.label');
+      if (label) label.textContent = pillLabelFor(state);
+      return;
+    }
     var dot = doc.getElementById('rcf-conn-dot');
     if (!dot) return;
     dot.className = state;
-    if (state === 'connected') dot.title = 'Connected - live updates on';
-    else if (state === 'reconnecting') dot.title = 'Reconnecting to view server...';
-    else dot.title = 'Disconnected from view server';
+    dot.title = pillTitleFor(state);
   }
 
   // ---- module exports (for node:vm tests) --------------------------------

package/src/view/needs-work.js

@@ -0,0 +1,79 @@
+// Viewer UI refresh PR 3 (decision 3, decision 14): compute the set of
+// REQ ids that still "need work" from the readiness result. The source
+// is the readiness result the server already carries on `model.readiness`
+// (built once per rewalk by `computeReadiness`), so we never re-run gates
+// in the client and never recompute them from the tree.
+//
+// The design doc section 8 names the three PO-persona checks that call
+// out specific REQ ids: `skeleton:reqIntent` (requirement needs a plain
+// description), `stories:reqHasUs` (who uses this requirement, what do
+// they do), and `skeleton:resolvedBy` (brief kinds that could become a
+// REQ). The first two name REQ ids directly on the blocker's `ids`
+// array. `skeleton:resolvedBy` names brief statement ids (SK-x), not
+// REQ ids, so it is informational for the Requirements tab and only
+// gets picked up when the suggestion names a REQ. Any REQ id that ends
+// up in any of the above blocker lists is in the Needs-work set.
+//
+// Decision 14: Requirements is the engineer view at all times. The
+// Needs-work chip uses engineer-plain language (no PO phrasebook text);
+// the data behind it is still the PO blockers so a product-owner and
+// an engineer looking at the same tree see the same "still needs work"
+// requirements.
+
+const NEEDS_WORK_CHECKS = new Set([
+  'skeleton:reqIntent',
+  'stories:reqHasUs',
+  'skeleton:resolvedBy',
+]);
+
+/**
+ * @param {import('../query/readiness.js').ReadinessResult | null | undefined} readiness
+ * @returns {Set<string>}  REQ ids that still need work
+ */
+export function computeReqNeedsWorkIds(readiness) {
+  /** @type {Set<string>} */
+  const out = new Set();
+  if (!readiness) return out;
+  const level = readiness.levels?.intentComplete;
+  if (!level || !Array.isArray(level.blockedBy)) return out;
+  for (const blocker of level.blockedBy) {
+    if (!blocker || !NEEDS_WORK_CHECKS.has(blocker.check)) continue;
+    const ids = Array.isArray(blocker.ids) ? blocker.ids : [];
+    for (const id of ids) {
+      if (typeof id === 'string' && id.startsWith('REQ-')) out.add(id);
+    }
+  }
+  return out;
+}
+
+/**
+ * Return a short, engineer-plain reason for a REQ being in the needs-
+ * work set. Decision 14 keeps PO phrasebook text out of the Requirements
+ * tab, so we map the check name to a terse engineer-facing label rather
+ * than reproducing CHECK_QUESTION. Returns null when the REQ is not in
+ * any needs-work check.
+ *
+ * @param {import('../query/readiness.js').ReadinessResult | null | undefined} readiness
+ * @param {string} reqId
+ * @returns {string | null}
+ */
+export function needsWorkReasonFor(readiness, reqId) {
+  if (!readiness) return null;
+  const level = readiness.levels?.intentComplete;
+  if (!level || !Array.isArray(level.blockedBy)) return null;
+  const reasons = [];
+  for (const blocker of level.blockedBy) {
+    if (!blocker || !NEEDS_WORK_CHECKS.has(blocker.check)) continue;
+    const ids = Array.isArray(blocker.ids) ? blocker.ids : [];
+    if (!ids.includes(reqId)) continue;
+    reasons.push(REASON_BY_CHECK[blocker.check] ?? blocker.check);
+  }
+  if (reasons.length === 0) return null;
+  return reasons.join('; ');
+}
+
+const REASON_BY_CHECK = {
+  'skeleton:reqIntent': 'missing plain description or domain',
+  'stories:reqHasUs': 'no user story yet',
+  'skeleton:resolvedBy': 'resolved-by target still open',
+};