bmad-plus 0.17.1 → 0.18.0

package/tools/cli/lib/uat.js

@@ -472,8 +472,144 @@ function languageCode(value, strings = STRINGS) {
   return Object.keys(strings).find((code) => code.toLowerCase().split('-')[0] === base) || null;
 }
 
+/**
+ * What every built page guarantees a tester, by construction. Each entry names a
+ * behaviour the DOM suite exercises (tests/unit/uat-page.test.js) and the literal
+ * the template must carry for it. A template that lost one does not build: the
+ * FormaPro incident of 2026-09-25 (answers typed before any run existed, then lost
+ * on reload, with a "saved" status nobody had verified) came from exactly such a loss.
+ */
+const PAGE_GUARANTEES = [
+  {
+    id: 'hidden-before-start',
+    what: 'no answer field is shown before a run exists, whatever a class says about display',
+    // The rule must also be the LAST rule of the sheet: a later !important display rule would beat it.
+    markers: [
+      '[hidden] { display: none !important; }\n</style>',
+      '<main class="steps" id="steps" hidden>',
+    ],
+  },
+  {
+    id: 'no-answer-before-run',
+    what: 'a tick or a note before the run starts is refused and explained, never discarded in silence',
+    markers: [
+      'function requireRun(',
+      'T.startFirst',
+      '!requireRun(event)',
+      'if (!requireRun()) return;',
+    ],
+  },
+  {
+    id: 'verified-local-write',
+    what: 'a write to this browser counts only once it reads back; a refused write returns false',
+    markers: ['return localStorage.getItem(k) === v;', 'function saveLocal()'],
+  },
+  {
+    id: 'honest-save-status',
+    what: 'the status line reports the verified outcome, and names a failed save',
+    markers: ['function showSaveState(', 'T.saveFailed', 'T.remoteFailed', 'T.saving'],
+  },
+  {
+    id: 'save-on-every-change',
+    what: 'every tick and every keystroke in a note is saved at once, without waiting for blur, and a save never moves the cursor',
+    markers: [
+      'addEventListener("change"',
+      'addEventListener("input"',
+      'document.activeElement !== field',
+    ],
+  },
+  {
+    id: 'restore-before-capabilities',
+    what: 'the browser copy is restored synchronously, before any optional capability answers',
+    markers: ['function restoreLocal()'],
+    order: ['restoreLocal();', 'probe()'],
+  },
+  {
+    id: 'newer-copy-wins',
+    what: 'an older remote copy never overwrites a newer local one; a copy without a date is the oldest of all',
+    markers: ['function connectDb()', 'remoteNewer', 'function at(', 'function adopt('],
+  },
+  {
+    id: 'revision-guard',
+    what: 'a run that answered another revision is offered, explained and carried by an explicit rule, never poured in blindly',
+    markers: ['function sameRevision(', 'function carry(', 'T.otherRevision', 'T.continueHere'],
+  },
+  {
+    id: 'other-tab-notice',
+    what: 'two tabs on one run converge on the latest change, and the page says so',
+    markers: ['addEventListener("storage"', 'T.otherTab'],
+  },
+  {
+    id: 'unreadable-draft-kept',
+    what: 'a saved run that cannot be read is reported and exportable, never deleted',
+    markers: ['id="draft-problem"', 'T.draftUnreadable', 'id="btn-save-raw"'],
+  },
+  {
+    id: 'progress-accessible',
+    what: 'the share of lines answered is exposed with a progressbar role and value; answered is not passed',
+    markers: ['role="progressbar"', 'aria-valuenow', 'T.percentAnswered'],
+  },
+  {
+    id: 'storage-explained',
+    what: 'the page says where answers live and what can make them disappear',
+    markers: ['id="storage-note"', 'id="mode-note"'],
+  },
+  {
+    id: 'finished-is-not-accepted',
+    what: 'finishing keeps the date and says it is not an acceptance',
+    markers: ['T.finishedNote', 'run.finishedAt = new Date().toISOString();'],
+  },
+  {
+    id: 'unload-guard',
+    what: 'leaving with an unsaved run is questioned; pending remote writes are flushed',
+    markers: ['addEventListener("beforeunload"', 'addEventListener("pagehide"'],
+  },
+  {
+    id: 'utf8-and-escaped-diacritics',
+    what: 'the page declares UTF-8 and writes the combining-mark range as escapes',
+    markers: ['<meta charset="utf-8">', '\\u0300-\\u036f'],
+  },
+  {
+    id: 'export-is-the-run',
+    what: 'the exported JSON is the run as answered, and nothing is exported before a run exists',
+    markers: ['download(runId + ".json", JSON.stringify(run, null, 2))'],
+  },
+];
+
+/**
+ * Which guarantees a template carries: every marker present, in the required order where one
+ * is set. Checked on the TEMPLATE, never on the built page: a recipe's own text must not be
+ * able to satisfy or defeat a marker.
+ */
+function pageGuarantees(template) {
+  const missing = [];
+  for (const guarantee of PAGE_GUARANTEES) {
+    const lost = guarantee.markers.filter((marker) => !template.includes(marker));
+    if (!lost.length && guarantee.order) {
+      const positions = guarantee.order.map((marker) => template.indexOf(marker));
+      if (positions.some((at) => at < 0) || positions.some((at, i) => i && at < positions[i - 1]))
+        lost.push(`order ${guarantee.order.join(' → ')}`);
+    }
+    if (lost.length) missing.push({ id: guarantee.id, what: guarantee.what, lost });
+  }
+  const carried = PAGE_GUARANTEES.map((g) => g.id).filter(
+    (id) => !missing.some((entry) => entry.id === id)
+  );
+  return { ok: missing.length === 0, carried, missing };
+}
+
 function buildPage(spec, options = {}) {
   const template = options.template || fs.readFileSync(TEMPLATE, 'utf8');
+  // A page missing one guarantee is not a page: refusing here is what keeps a tester's
+  // answers safe in an installation that has no test suite of its own.
+  const guarantees = pageGuarantees(template);
+  if (!guarantees.ok) {
+    throw new Error(
+      `the page template (${options.template ? 'the template given' : TEMPLATE}) lost a guarantee — not built: ${guarantees.missing
+        .map((entry) => `${entry.id}: ${entry.what} — missing ${entry.lost.join(', ')}`)
+        .join('; ')}`
+    );
+  }
   const hash = specHash(spec);
   const json = canonical(spec).replace(/<\//g, '<\\/');
   const strings = options.strings || STRINGS;
@@ -502,7 +638,7 @@ function buildPage(spec, options = {}) {
       cause: error,
     });
   }
-  return { html, sha256: hash, language };
+  return { html, sha256: hash, language, guarantees: guarantees.carried };
 }
 
 // ── Runs: legacy adapter, normalisation, reading ──────────────────────────────
@@ -873,6 +1009,8 @@ module.exports = {
   lintSpec,
   screenLabels,
   buildPage,
+  PAGE_GUARANTEES,
+  pageGuarantees,
   languageCode,
   normalizeRun,
   readRuns,