bmad-plus 0.17.1 → 0.19.0

package/tools/cli/commands/uat.js

@@ -89,6 +89,13 @@ function serve(spec, paths, options) {
       response.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' });
       response.end(body);
     };
+    // Loopback is not enough against the tester's own browser: a name rebound to 127.0.0.1
+    // is same-origin for it. Only the two names this server answers to are served.
+    const host = String(request.headers.host || '').toLowerCase();
+    const bound = server.address() ? server.address().port : port;
+    if (host !== `127.0.0.1:${bound}` && host !== `localhost:${bound}`) {
+      return send(403, JSON.stringify({ error: 'unexpected host' }));
+    }
     if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '/index.html')) {
       return send(200, html, 'text/html; charset=utf-8');
     }
@@ -116,7 +123,29 @@ function serve(spec, paths, options) {
           const run = uat.normalizeRun(JSON.parse(Buffer.concat(chunks).toString('utf8')), spec);
           if (run.runId !== runId || run.specId !== spec.id)
             fail('run identity does not match the request');
-          fs.writeFileSync(path.join(resultsDir, `${runId}.json`), JSON.stringify(run, null, 2));
+          // The page's rule holds on disk too: a copy older than the file never replaces it.
+          const file = path.join(resultsDir, `${runId}.json`);
+          if (fs.existsSync(file)) {
+            let existing = null;
+            try {
+              existing = JSON.parse(fs.readFileSync(file, 'utf8'));
+            } catch {
+              existing = null;
+            }
+            const was = Date.parse(existing && existing.updatedAt);
+            const now = Date.parse(run.updatedAt);
+            if (!Number.isNaN(was) && (Number.isNaN(now) || was > now)) {
+              send(
+                409,
+                JSON.stringify({
+                  error: 'a newer copy of this run is already stored',
+                  updatedAt: existing.updatedAt,
+                })
+              );
+              return;
+            }
+          }
+          fs.writeFileSync(file, JSON.stringify(run, null, 2));
           const s = run.summary;
           console.log(
             `${new Date().toISOString().slice(11, 19)}  ${runId} — ${s.passed} passed, ${s.failed} failed, ${s.blocked} blocked, ${s.unanswered} to do${run.finishedAt ? ' — finished' : ''}`
@@ -133,7 +162,9 @@ function serve(spec, paths, options) {
 
   // Loopback only: a tester on another machine uses the artifact or the file (decision D5).
   server.listen(port, '127.0.0.1', () => {
-    console.log(`uat serve: http://127.0.0.1:${port}  (${spec.id}, ${spec.steps.length} steps)`);
+    console.log(
+      `uat serve: http://127.0.0.1:${server.address().port}  (${spec.id}, ${spec.steps.length} steps)`
+    );
     console.log(`results → ${resultsDir}`);
     console.log('Ctrl+C to stop.');
   });
@@ -188,9 +219,21 @@ module.exports = {
           process.exitCode = 1;
           return;
         }
-        const page = uat.buildPage(spec, {
-          language: options.language || projectLanguage(projectDir),
-        });
+        let page;
+        try {
+          page = uat.buildPage(spec, {
+            language: options.language || projectLanguage(projectDir),
+          });
+        } catch (error) {
+          // A refused page reads like a refused lint: same shape, so a machine reader sees a refusal, not a crash.
+          print(
+            json,
+            { action, specId: spec.id, status: 'error', errors: [error.message], guarantees: [] },
+            [`${spec.id}: not built`, `  error   ${error.message}`]
+          );
+          process.exitCode = 1;
+          return;
+        }
         fs.mkdirSync(paths.pages, { recursive: true });
         const file = path.join(paths.pages, `uat-${spec.id}.html`);
         fs.writeFileSync(file, page.html, 'utf8');
@@ -203,11 +246,13 @@ module.exports = {
             specSha256: page.sha256,
             language: page.language,
             languages: Object.keys(uat.STRINGS),
+            guarantees: page.guarantees,
             warnings: report.warnings,
           },
           [
             `${file} — ${spec.steps.length} steps, ${(page.html.length / 1024).toFixed(0)} KiB, spec ${page.sha256.slice(0, 12)}`,
             `opens in ${uat.STRINGS[page.language].name}; the tester can switch to any of the ${Object.keys(uat.STRINGS).length} languages on the page`,
+            `carries the ${page.guarantees.length} page guarantees: ${page.guarantees.join(', ')}`,
             ...report.warnings.map((line) => `  warning ${line}`),
           ]
         );

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

@@ -1,6 +1,7 @@
 /** Report release status without applying updates. */
 const path = require('node:path');
 const { checkForUpdate } = require('../lib/update-check');
+const { notInstalledMessage, hasInstallManifest } = require('../lib/install-manifest');
 
 module.exports = {
   command: 'update-check',
@@ -12,8 +13,9 @@ module.exports = {
     ['--json', 'Print machine-readable JSON'],
   ],
   action: async (options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
     const result = await checkForUpdate({
-      projectDir: path.resolve(options.directory || process.cwd()),
+      projectDir,
       runningVersion: require('../../../package.json').version,
       refresh: Boolean(options.refresh),
       offline: Boolean(options.offline),
@@ -23,6 +25,8 @@ module.exports = {
       },
     });
     if (result.status.startsWith('invalid-')) process.exitCode = 1;
+    // stderr keeps --json output parseable while still telling a person where to run it.
+    if (!hasInstallManifest(projectDir)) console.error(notInstalledMessage(projectDir));
     if (options.json) console.log(JSON.stringify(result));
     else {
       console.log(

package/tools/cli/commands/update.js

@@ -9,7 +9,11 @@ const clack = require('@clack/prompts');
 const pc = require('picocolors');
 const { t } = require('../i18n');
 const { safeTarget } = require('../../build/generate-adapters');
-const { readInstallManifest } = require('../lib/install-manifest');
+const {
+  readInstallManifest,
+  notInstalledMessage,
+  hasInstallManifest,
+} = require('../lib/install-manifest');
 const { isExactVersion } = require('../lib/update-policy');
 const { planUpdate, applyPlan, restoreUpdate, MANIFEST } = require('../lib/update-transaction');
 
@@ -51,6 +55,9 @@ module.exports = {
       if (options.restore && (options.latest || options.expectedVersion)) {
         throw new Error('--restore cannot be combined with --latest or --expected-version.');
       }
+      if (!options.restore && !hasInstallManifest(projectDir)) {
+        throw new Error(notInstalledMessage(projectDir));
+      }
       // The dispatcher resolves the target package; this local package may be older.
       if (options.latest) {
         const result = await require('../lib/update-dispatch').runLatestUpdate({
@@ -96,8 +103,7 @@ module.exports = {
         );
       }
       const manifestPath = safeTarget(projectDir, MANIFEST);
-      if (!fs.existsSync(manifestPath))
-        throw new Error('BMAD+ is not installed in this directory. Run bmad-plus install first.');
+      if (!fs.existsSync(manifestPath)) throw new Error(notInstalledMessage(projectDir));
       let manifest;
       try {
         manifest = readInstallManifest(manifestPath);

package/tools/cli/lib/install-manifest.js

@@ -1,5 +1,6 @@
 /** Read the manifest fields used by maintenance commands without unsafe coercion. */
 const fs = require('node:fs');
+const path = require('node:path');
 
 function readInstallManifest(manifestPath) {
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
@@ -21,4 +22,21 @@ function readInstallManifest(manifestPath) {
   return manifest;
 }
 
-module.exports = { readInstallManifest };
+/**
+ * Guidance for maintenance commands run outside an installed project. A person who
+ * opens a terminal in a drive root or a parent folder must learn where to run them.
+ */
+function notInstalledMessage(projectDir) {
+  return [
+    `No BMAD+ installation found in ${projectDir} (missing _bmad/.bmad-plus-install.json).`,
+    'Run this command from your project folder, for example: cd "path/to/your-project"',
+    'or pass the folder explicitly: --directory "path/to/your-project".',
+    'To install BMAD+ in this folder instead: npx bmad-plus@latest install',
+  ].join('\n');
+}
+
+function hasInstallManifest(projectDir) {
+  return fs.existsSync(path.join(projectDir, '_bmad', '.bmad-plus-install.json'));
+}
+
+module.exports = { readInstallManifest, notInstalledMessage, hasInstallManifest };

package/tools/cli/lib/packs.js

@@ -191,7 +191,7 @@ const DERIVED = {
   "product": {
     "code": "bmad-plus",
     "displayName": "BMAD+",
-    "version": "0.17.1",
+    "version": "0.19.0",
     "derivedFrom": "BMAD-METHOD v6.6.0"
   },
   "packOrder": [