bmad-plus 0.17.0 → 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,

package/tools/cli/lib/update-check.js

@@ -3,20 +3,37 @@ const fs = require('node:fs');
 const semver = require('semver');
 const { safeAdapterPath } = require('./installed-adapters');
 const { readInstallManifest } = require('./install-manifest');
-const { readUpdatePolicy, validatePolicy, authorizeTarget, isExactVersion, writeProjectJson } = require('./update-policy');
+const {
+  readUpdatePolicy,
+  validatePolicy,
+  authorizeTarget,
+  isExactVersion,
+  writeProjectJson,
+} = require('./update-policy');
 
 const CACHE_FILE = '.bmad/update-check.json';
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const FAILURE_BACKOFF_MS = 60 * 60 * 1000;
 
 function validateRelease(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value) || !isExactVersion(value.version)) {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    !isExactVersion(value.version)
+  ) {
     throw new Error('Registry returned an invalid exact version.');
   }
   const engines = value.engines === undefined ? {} : value.engines;
-  if (!engines || typeof engines !== 'object' || Array.isArray(engines) ||
-      (engines.node !== undefined && (typeof engines.node !== 'string' ||
-        !engines.node.trim() || !semver.validRange(engines.node)))) {
+  if (
+    !engines ||
+    typeof engines !== 'object' ||
+    Array.isArray(engines) ||
+    (engines.node !== undefined &&
+      (typeof engines.node !== 'string' ||
+        !engines.node.trim() ||
+        !semver.validRange(engines.node)))
+  ) {
     throw new Error('Registry returned an invalid Node engine requirement.');
   }
   return { version: value.version, engines: engines.node ? { node: engines.node } : {} };
@@ -25,10 +42,20 @@ function validateRelease(value) {
 async function queryNpmRelease({ projectDir, channel, registry }) {
   validatePolicy({ channel, registry });
   const { runNpm } = require('./npm-runner');
-  const stdout = await runNpm([
-    'view', `bmad-plus@${channel}`, 'version', 'engines', '--json', `--registry=${registry}`,
-    '--prefer-online', '--fetch-timeout=4000', '--fetch-retries=0',
-  ], { cwd: projectDir, timeout: 6000, maxBuffer: 64 * 1024 });
+  const stdout = await runNpm(
+    [
+      'view',
+      `bmad-plus@${channel}`,
+      'version',
+      'engines',
+      '--json',
+      `--registry=${registry}`,
+      '--prefer-online',
+      '--fetch-timeout=4000',
+      '--fetch-retries=0',
+    ],
+    { cwd: projectDir, timeout: 6000, maxBuffer: 64 * 1024 }
+  );
   return validateRelease(JSON.parse(stdout));
 }
 
@@ -40,45 +67,88 @@ function timestamp(value, now) {
 function readCache(projectDir, policy, now) {
   try {
     const cache = JSON.parse(fs.readFileSync(safeAdapterPath(projectDir, CACHE_FILE), 'utf8'));
-    if (!cache || cache.schemaVersion !== 1 || cache.package !== 'bmad-plus' ||
-        cache.registry !== policy.registry || cache.channel !== policy.channel) return null;
+    if (
+      !cache ||
+      cache.schemaVersion !== 1 ||
+      cache.package !== 'bmad-plus' ||
+      cache.registry !== policy.registry ||
+      cache.channel !== policy.channel
+    )
+      return null;
     if (cache.release) {
       cache.release = validateRelease(cache.release);
       if (timestamp(cache.checkedAt, now) === null) return null;
     }
     if (cache.failedAt !== undefined && timestamp(cache.failedAt, now) === null) return null;
     return cache;
-  } catch { return null; }
+  } catch {
+    return null;
+  }
 }
 
 function saveCache(projectDir, cache) {
-  try { writeProjectJson(projectDir, CACHE_FILE, cache); } catch { /* A read-only cache is nonfatal. */ }
+  try {
+    writeProjectJson(projectDir, CACHE_FILE, cache);
+  } catch {
+    /* A read-only cache is nonfatal. */
+  }
 }
 
 async function checkForUpdate({
-  projectDir, runningVersion = require('../../../package.json').version, refresh = false, offline = false,
-  now = Date.now, queryRelease = queryNpmRelease, checkReadiness, nodeVersion = process.version,
+  projectDir,
+  runningVersion = require('../../../package.json').version,
+  refresh = false,
+  offline = false,
+  now = Date.now,
+  queryRelease = queryNpmRelease,
+  checkReadiness,
+  nodeVersion = process.version,
 }) {
   const time = typeof now === 'function' ? now() : now;
   const result = {
-    schemaVersion: 1, installedVersion: null, runningVersion, latestVersion: null,
-    targetVersion: null, channel: null, status: 'unknown', checkedAt: null,
-    source: 'none', stale: false, updateAvailable: null, releaseEligible: false,
-    versionEligible: false, canAutoApply: false, engineCompatible: null, engines: {}, reason: null,
+    schemaVersion: 1,
+    installedVersion: null,
+    runningVersion,
+    latestVersion: null,
+    targetVersion: null,
+    channel: null,
+    status: 'unknown',
+    checkedAt: null,
+    source: 'none',
+    stale: false,
+    updateAvailable: null,
+    releaseEligible: false,
+    versionEligible: false,
+    canAutoApply: false,
+    engineCompatible: null,
+    engines: {},
+    reason: null,
   };
-  if (!isExactVersion(runningVersion) || !Number.isFinite(time) ||
-      !Number.isFinite(new Date(time).getTime()) || !semver.valid(nodeVersion)) {
+  if (
+    !isExactVersion(runningVersion) ||
+    !Number.isFinite(time) ||
+    !Number.isFinite(new Date(time).getTime()) ||
+    !semver.valid(nodeVersion)
+  ) {
     return { ...result, status: 'invalid-runtime', reason: 'invalid-running-version-or-clock' };
   }
   try {
-    const manifest = readInstallManifest(safeAdapterPath(projectDir, '_bmad/.bmad-plus-install.json'));
+    const manifest = readInstallManifest(
+      safeAdapterPath(projectDir, '_bmad/.bmad-plus-install.json')
+    );
     if (!isExactVersion(manifest.version)) throw new Error('Invalid installed version');
     result.installedVersion = manifest.version;
   } catch {
-    return { ...result, status: 'invalid-installation', reason: 'missing-or-invalid-installation-manifest' };
+    return {
+      ...result,
+      status: 'invalid-installation',
+      reason: 'missing-or-invalid-installation-manifest',
+    };
   }
   let policy;
-  try { policy = readUpdatePolicy(projectDir); } catch {
+  try {
+    policy = readUpdatePolicy(projectDir);
+  } catch {
     return { ...result, status: 'invalid-policy', reason: 'unreadable-or-invalid-update-policy' };
   }
   result.channel = policy.channel;
@@ -98,16 +168,30 @@ async function checkForUpdate({
     result.checkedAt = cache.checkedAt;
   } else {
     try {
-      release = validateRelease(await queryRelease({ projectDir, channel: policy.channel, registry: policy.registry }));
-      cache = { schemaVersion: 1, package: 'bmad-plus', registry: policy.registry, channel: policy.channel,
-        release, checkedAt: new Date(time).toISOString() };
+      release = validateRelease(
+        await queryRelease({ projectDir, channel: policy.channel, registry: policy.registry })
+      );
+      cache = {
+        schemaVersion: 1,
+        package: 'bmad-plus',
+        registry: policy.registry,
+        channel: policy.channel,
+        release,
+        checkedAt: new Date(time).toISOString(),
+      };
       saveCache(projectDir, cache);
       result.source = 'registry';
       result.checkedAt = cache.checkedAt;
     } catch {
       result.reason = 'registry-unavailable';
-      saveCache(projectDir, { ...cache, schemaVersion: 1, package: 'bmad-plus',
-        registry: policy.registry, channel: policy.channel, failedAt: new Date(time).toISOString() });
+      saveCache(projectDir, {
+        ...cache,
+        schemaVersion: 1,
+        package: 'bmad-plus',
+        registry: policy.registry,
+        channel: policy.channel,
+        failedAt: new Date(time).toISOString(),
+      });
     }
   }
   if (!release) {
@@ -125,11 +209,17 @@ async function checkForUpdate({
   result.targetVersion = release.version;
   result.latestVersion = policy.channel === 'latest' ? release.version : null;
   result.engines = release.engines;
-  result.engineCompatible = !release.engines.node || semver.satisfies(nodeVersion, release.engines.node);
+  result.engineCompatible =
+    !release.engines.node || semver.satisfies(nodeVersion, release.engines.node);
   const comparison = semver.compare(release.version, result.installedVersion);
   result.updateAvailable = comparison > 0;
   result.status = comparison > 0 ? 'update-available' : comparison === 0 ? 'current' : 'ahead';
-  result.reason = comparison > 0 ? null : comparison === 0 ? 'installed-matches-channel' : 'installed-ahead-of-channel';
+  result.reason =
+    comparison > 0
+      ? null
+      : comparison === 0
+        ? 'installed-matches-channel'
+        : 'installed-ahead-of-channel';
   if (comparison <= 0) return result;
   if (!result.engineCompatible) return { ...result, reason: 'incompatible-node-version' };
   if (!policy.allowPrerelease && semver.prerelease(release.version)) {
@@ -142,10 +232,18 @@ async function checkForUpdate({
   if (authorization.allowed) {
     if (!checkReadiness) return { ...result, reason: 'ownership-readiness-not-checked' };
     try {
-      const readiness = await checkReadiness({ projectDir, targetVersion: release.version, policy });
+      const readiness = await checkReadiness({
+        projectDir,
+        targetVersion: release.version,
+        policy,
+      });
       result.canAutoApply = readiness?.ready === true;
-      result.reason = result.canAutoApply ? 'ready-for-authorized-update' : readiness?.reason || 'ownership-not-ready';
-    } catch { result.reason = 'ownership-readiness-failed'; }
+      result.reason = result.canAutoApply
+        ? 'ready-for-authorized-update'
+        : readiness?.reason || 'ownership-not-ready';
+    } catch {
+      result.reason = 'ownership-readiness-failed';
+    }
   }
   return result;
 }

package/tools/cli/lib/update-dispatch.js

@@ -46,8 +46,8 @@ async function withExecutionDirectory(action) {
     const actual = fs.realpathSync(directory);
     assert(
       path.dirname(actual) === parent &&
-      path.basename(actual).startsWith('bmad-update-exec-') &&
-      !fs.lstatSync(directory).isSymbolicLink(),
+        path.basename(actual).startsWith('bmad-update-exec-') &&
+        !fs.lstatSync(directory).isSymbolicLink(),
       'Refusing to remove an unexpected updater temporary directory.'
     );
     fs.rmSync(actual, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });

package/tools/cli/lib/update-policy.js

@@ -8,14 +8,19 @@ const { safeAdapterPath } = require('./installed-adapters');
 const POLICY_FILE = '_bmad/update-policy.json';
 const OFFICIAL_REGISTRY = 'https://registry.npmjs.org/';
 const DEFAULT_POLICY = Object.freeze({
-  mode: 'notify', channel: 'latest', allowedRange: null,
-  allowPrerelease: false, registry: OFFICIAL_REGISTRY,
+  mode: 'notify',
+  channel: 'latest',
+  allowedRange: null,
+  allowPrerelease: false,
+  registry: OFFICIAL_REGISTRY,
 });
 
 function isExactVersion(version) {
-  return typeof version === 'string' &&
+  return (
+    typeof version === 'string' &&
     /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version) &&
-    semver.valid(version) !== null;
+    semver.valid(version) !== null
+  );
 }
 
 function validatePolicy(value) {
@@ -27,13 +32,21 @@ function validatePolicy(value) {
   }
   const policy = { ...DEFAULT_POLICY, ...value };
   delete policy.schemaVersion;
-  if (Object.keys(policy).some(key => !Object.hasOwn(DEFAULT_POLICY, key)) ||
-      !['off', 'notify', 'auto'].includes(policy.mode) ||
-      typeof policy.channel !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(policy.channel) ||
-      typeof policy.allowPrerelease !== 'boolean' || policy.registry !== OFFICIAL_REGISTRY ||
-      (policy.allowedRange !== null && (typeof policy.allowedRange !== 'string' ||
-        !policy.allowedRange.trim() || !semver.validRange(policy.allowedRange)))) {
-    throw new Error('Invalid update policy: check mode, channel, range, prerelease flag and official registry.');
+  if (
+    Object.keys(policy).some((key) => !Object.hasOwn(DEFAULT_POLICY, key)) ||
+    !['off', 'notify', 'auto'].includes(policy.mode) ||
+    typeof policy.channel !== 'string' ||
+    !/^[a-z][a-z0-9_-]{0,31}$/.test(policy.channel) ||
+    typeof policy.allowPrerelease !== 'boolean' ||
+    policy.registry !== OFFICIAL_REGISTRY ||
+    (policy.allowedRange !== null &&
+      (typeof policy.allowedRange !== 'string' ||
+        !policy.allowedRange.trim() ||
+        !semver.validRange(policy.allowedRange)))
+  ) {
+    throw new Error(
+      'Invalid update policy: check mode, channel, range, prerelease flag and official registry.'
+    );
   }
   if (policy.mode === 'auto' && policy.allowedRange === null) {
     throw new Error('Automatic updates require an explicit allowedRange.');
@@ -58,11 +71,18 @@ function writeProjectJson(projectDir, relativeFile, data) {
   const temporaryName = `${relativeFile}.${process.pid}.${crypto.randomUUID()}.tmp`;
   const temporary = safeAdapterPath(projectDir, temporaryName);
   try {
-    fs.writeFileSync(temporary, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', flag: 'wx' });
+    fs.writeFileSync(temporary, JSON.stringify(data, null, 2) + '\n', {
+      encoding: 'utf8',
+      flag: 'wx',
+    });
     safeAdapterPath(projectDir, relativeFile);
     fs.renameSync(temporary, file);
   } finally {
-    try { fs.unlinkSync(temporary); } catch { /* Preserve the original write error if cleanup fails. */ }
+    try {
+      fs.unlinkSync(temporary);
+    } catch {
+      /* Preserve the original write error if cleanup fails. */
+    }
   }
 }
 
@@ -74,17 +94,35 @@ function writeUpdatePolicy(projectDir, value) {
 
 function authorizeTarget(value, version) {
   let policy;
-  try { policy = validatePolicy(value); } catch { return { allowed: false, reason: 'invalid-policy' }; }
+  try {
+    policy = validatePolicy(value);
+  } catch {
+    return { allowed: false, reason: 'invalid-policy' };
+  }
   if (!isExactVersion(version)) return { allowed: false, reason: 'invalid-target-version' };
-  if (policy.mode !== 'auto') return { allowed: false, reason: policy.mode === 'off' ? 'updates-disabled' : 'approval-required' };
-  if (!policy.allowPrerelease && semver.prerelease(version)) return { allowed: false, reason: 'prerelease-not-allowed' };
-  if (!semver.satisfies(version, policy.allowedRange, { includePrerelease: policy.allowPrerelease })) {
+  if (policy.mode !== 'auto')
+    return {
+      allowed: false,
+      reason: policy.mode === 'off' ? 'updates-disabled' : 'approval-required',
+    };
+  if (!policy.allowPrerelease && semver.prerelease(version))
+    return { allowed: false, reason: 'prerelease-not-allowed' };
+  if (
+    !semver.satisfies(version, policy.allowedRange, { includePrerelease: policy.allowPrerelease })
+  ) {
     return { allowed: false, reason: 'outside-allowed-range' };
   }
   return { allowed: true, reason: 'authorized-policy' };
 }
 
 module.exports = {
-  DEFAULT_POLICY, POLICY_FILE, OFFICIAL_REGISTRY, isExactVersion,
-  validatePolicy, readUpdatePolicy, writeUpdatePolicy, authorizeTarget, writeProjectJson,
+  DEFAULT_POLICY,
+  POLICY_FILE,
+  OFFICIAL_REGISTRY,
+  isExactVersion,
+  validatePolicy,
+  readUpdatePolicy,
+  writeUpdatePolicy,
+  authorizeTarget,
+  writeProjectJson,
 };