bmad-plus 0.12.1 → 0.13.0

package/tools/cli/lib/stack-detect.js

@@ -1,102 +1,102 @@
-/**
- * BMAD+ Stack Detection — Shared Module
- * Unified project stack detection for autoconfig and scan commands.
- * Merges patterns from both original implementations.
- */
-
-const path = require('node:path');
-const fs = require('node:fs');
-
-// ── Project Detection Markers (for scan.js) ──
-
-const PROJECT_MARKERS = [
-  { file: 'package.json', stack: 'Node.js', detect: (dir) => {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      if (deps['next']) return 'Next.js';
-      if (deps['nuxt']) return 'Nuxt';
-      if (deps['react']) return 'React';
-      if (deps['vue']) return 'Vue.js';
-      if (deps['svelte']) return 'Svelte';
-      if (deps['express']) return 'Express';
-      if (deps['fastify']) return 'Fastify';
-      if (deps['electron']) return 'Electron';
-      if (deps['tauri']) return 'Tauri';
-      return 'Node.js';
-    } catch {
-      return 'Node.js';
-    }
-  }},
-  { file: 'Cargo.toml', stack: 'Rust' },
-  { file: 'pyproject.toml', stack: 'Python' },
-  { file: 'requirements.txt', stack: 'Python' },
-  { file: 'go.mod', stack: 'Go' },
-  { file: 'composer.json', stack: 'PHP' },
-  { file: 'Gemfile', stack: 'Ruby' },
-  { file: 'pom.xml', stack: 'Java' },
-  { file: 'build.gradle', stack: 'Java/Kotlin' },
-];
-
-// ── Full Stack Detection (for autoconfig.js) ──
-
-function detectStack(dir) {
-  const result = {
-    language: null,
-    framework: null,
-    runtime: null,
-    packageManager: null,
-    hasTypeScript: false,
-  };
-
-  // Package.json analysis
-  const pkgPath = path.join(dir, 'package.json');
-  if (fs.existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      result.runtime = 'Node.js';
-      result.language = deps['typescript'] || fs.existsSync(path.join(dir, 'tsconfig.json')) ? 'TypeScript' : 'JavaScript';
-      result.hasTypeScript = result.language === 'TypeScript';
-
-      // Framework detection
-      if (deps['next']) result.framework = 'Next.js';
-      else if (deps['nuxt']) result.framework = 'Nuxt';
-      else if (deps['@angular/core']) result.framework = 'Angular';
-      else if (deps['react']) result.framework = 'React';
-      else if (deps['vue']) result.framework = 'Vue.js';
-      else if (deps['svelte']) result.framework = 'Svelte';
-      else if (deps['express']) result.framework = 'Express';
-      else if (deps['fastify']) result.framework = 'Fastify';
-      else if (deps['hono']) result.framework = 'Hono';
-      else if (deps['electron']) result.framework = 'Electron';
-      else if (deps['tauri']) result.framework = 'Tauri';
-      else if (deps['react-native']) result.framework = 'React Native';
-
-      // Package manager
-      if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) result.packageManager = 'pnpm';
-      else if (fs.existsSync(path.join(dir, 'yarn.lock'))) result.packageManager = 'yarn';
-      else if (fs.existsSync(path.join(dir, 'bun.lockb'))) result.packageManager = 'bun';
-      else result.packageManager = 'npm';
-    } catch (e) {
-      console.warn('stack-detect: Failed to parse package.json in detectStack', e.message);
-    }
-  }
-
-  // Other languages
-  if (!result.runtime) {
-    if (fs.existsSync(path.join(dir, 'Cargo.toml'))) { result.language = 'Rust'; result.runtime = 'Rust'; }
-    else if (fs.existsSync(path.join(dir, 'pyproject.toml')) || fs.existsSync(path.join(dir, 'requirements.txt'))) { result.language = 'Python'; result.runtime = 'Python'; }
-    else if (fs.existsSync(path.join(dir, 'go.mod'))) { result.language = 'Go'; result.runtime = 'Go'; }
-    else if (fs.existsSync(path.join(dir, 'composer.json'))) { result.language = 'PHP'; result.runtime = 'PHP'; }
-    else if (fs.existsSync(path.join(dir, 'Gemfile'))) { result.language = 'Ruby'; result.runtime = 'Ruby'; }
-    else if (fs.existsSync(path.join(dir, 'pom.xml')) || fs.existsSync(path.join(dir, 'build.gradle'))) { result.language = 'Java'; result.runtime = 'JVM'; }
-  }
-
-  return result;
-}
-
-module.exports = {
-  detectStack,
-  PROJECT_MARKERS,
-};
+/**
+ * BMAD+ Stack Detection — Shared Module
+ * Unified project stack detection for autoconfig and scan commands.
+ * Merges patterns from both original implementations.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+// ── Project Detection Markers (for scan.js) ──
+
+const PROJECT_MARKERS = [
+  { file: 'package.json', stack: 'Node.js', detect: (dir) => {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps['next']) return 'Next.js';
+      if (deps['nuxt']) return 'Nuxt';
+      if (deps['react']) return 'React';
+      if (deps['vue']) return 'Vue.js';
+      if (deps['svelte']) return 'Svelte';
+      if (deps['express']) return 'Express';
+      if (deps['fastify']) return 'Fastify';
+      if (deps['electron']) return 'Electron';
+      if (deps['tauri']) return 'Tauri';
+      return 'Node.js';
+    } catch {
+      return 'Node.js';
+    }
+  }},
+  { file: 'Cargo.toml', stack: 'Rust' },
+  { file: 'pyproject.toml', stack: 'Python' },
+  { file: 'requirements.txt', stack: 'Python' },
+  { file: 'go.mod', stack: 'Go' },
+  { file: 'composer.json', stack: 'PHP' },
+  { file: 'Gemfile', stack: 'Ruby' },
+  { file: 'pom.xml', stack: 'Java' },
+  { file: 'build.gradle', stack: 'Java/Kotlin' },
+];
+
+// ── Full Stack Detection (for autoconfig.js) ──
+
+function detectStack(dir) {
+  const result = {
+    language: null,
+    framework: null,
+    runtime: null,
+    packageManager: null,
+    hasTypeScript: false,
+  };
+
+  // Package.json analysis
+  const pkgPath = path.join(dir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      result.runtime = 'Node.js';
+      result.language = deps['typescript'] || fs.existsSync(path.join(dir, 'tsconfig.json')) ? 'TypeScript' : 'JavaScript';
+      result.hasTypeScript = result.language === 'TypeScript';
+
+      // Framework detection
+      if (deps['next']) result.framework = 'Next.js';
+      else if (deps['nuxt']) result.framework = 'Nuxt';
+      else if (deps['@angular/core']) result.framework = 'Angular';
+      else if (deps['react']) result.framework = 'React';
+      else if (deps['vue']) result.framework = 'Vue.js';
+      else if (deps['svelte']) result.framework = 'Svelte';
+      else if (deps['express']) result.framework = 'Express';
+      else if (deps['fastify']) result.framework = 'Fastify';
+      else if (deps['hono']) result.framework = 'Hono';
+      else if (deps['electron']) result.framework = 'Electron';
+      else if (deps['tauri']) result.framework = 'Tauri';
+      else if (deps['react-native']) result.framework = 'React Native';
+
+      // Package manager
+      if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) result.packageManager = 'pnpm';
+      else if (fs.existsSync(path.join(dir, 'yarn.lock'))) result.packageManager = 'yarn';
+      else if (fs.existsSync(path.join(dir, 'bun.lockb'))) result.packageManager = 'bun';
+      else result.packageManager = 'npm';
+    } catch (e) {
+      console.warn('stack-detect: Failed to parse package.json in detectStack', e.message);
+    }
+  }
+
+  // Other languages
+  if (!result.runtime) {
+    if (fs.existsSync(path.join(dir, 'Cargo.toml'))) { result.language = 'Rust'; result.runtime = 'Rust'; }
+    else if (fs.existsSync(path.join(dir, 'pyproject.toml')) || fs.existsSync(path.join(dir, 'requirements.txt'))) { result.language = 'Python'; result.runtime = 'Python'; }
+    else if (fs.existsSync(path.join(dir, 'go.mod'))) { result.language = 'Go'; result.runtime = 'Go'; }
+    else if (fs.existsSync(path.join(dir, 'composer.json'))) { result.language = 'PHP'; result.runtime = 'PHP'; }
+    else if (fs.existsSync(path.join(dir, 'Gemfile'))) { result.language = 'Ruby'; result.runtime = 'Ruby'; }
+    else if (fs.existsSync(path.join(dir, 'pom.xml')) || fs.existsSync(path.join(dir, 'build.gradle'))) { result.language = 'Java'; result.runtime = 'JVM'; }
+  }
+
+  return result;
+}
+
+module.exports = {
+  detectStack,
+  PROJECT_MARKERS,
+};

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

@@ -0,0 +1,153 @@
+/** Bounded release discovery. This module never downloads or applies a package. */
+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 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)) {
+    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)))) {
+    throw new Error('Registry returned an invalid Node engine requirement.');
+  }
+  return { version: value.version, engines: engines.node ? { node: engines.node } : {} };
+}
+
+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 });
+  return validateRelease(JSON.parse(stdout));
+}
+
+function timestamp(value, now) {
+  const time = typeof value === 'string' ? Date.parse(value) : NaN;
+  return Number.isFinite(time) && time <= now ? time : null;
+}
+
+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.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; }
+}
+
+function saveCache(projectDir, cache) {
+  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,
+}) {
+  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,
+  };
+  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'));
+    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' };
+  }
+  let policy;
+  try { policy = readUpdatePolicy(projectDir); } catch {
+    return { ...result, status: 'invalid-policy', reason: 'unreadable-or-invalid-update-policy' };
+  }
+  result.channel = policy.channel;
+  if (policy.mode === 'off') return { ...result, status: 'off', reason: 'updates-disabled' };
+
+  let cache = readCache(projectDir, policy, time);
+  const cachedAt = cache?.release ? timestamp(cache.checkedAt, time) : null;
+  const failedAt = cache?.failedAt === undefined ? null : timestamp(cache.failedAt, time);
+  let release;
+  if (offline) {
+    result.reason = 'offline';
+  } else if (!refresh && failedAt !== null && time - failedAt < FAILURE_BACKOFF_MS) {
+    result.reason = 'registry-retry-backoff';
+  } else if (!refresh && cachedAt !== null && failedAt === null && time - cachedAt < CACHE_TTL_MS) {
+    release = cache.release;
+    result.source = 'cache';
+    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() };
+      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() });
+    }
+  }
+  if (!release) {
+    if (cache?.release) {
+      result.targetVersion = cache.release.version;
+      result.latestVersion = policy.channel === 'latest' ? cache.release.version : null;
+      result.engines = cache.release.engines;
+      result.checkedAt = cache.checkedAt;
+      result.source = 'stale-cache';
+      result.stale = true;
+    }
+    return result;
+  }
+
+  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);
+  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';
+  if (comparison <= 0) return result;
+  if (!result.engineCompatible) return { ...result, reason: 'incompatible-node-version' };
+  if (!policy.allowPrerelease && semver.prerelease(release.version)) {
+    return { ...result, reason: 'prerelease-not-allowed' };
+  }
+  result.releaseEligible = true;
+  const authorization = authorizeTarget(policy, release.version);
+  result.versionEligible = authorization.allowed;
+  result.reason = authorization.reason;
+  if (authorization.allowed) {
+    if (!checkReadiness) return { ...result, reason: 'ownership-readiness-not-checked' };
+    try {
+      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'; }
+  }
+  return result;
+}
+
+module.exports = { CACHE_FILE, CACHE_TTL_MS, FAILURE_BACKOFF_MS, checkForUpdate, queryNpmRelease };

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

@@ -0,0 +1,182 @@
+/** Discover and execute one exact, approved BMAD+ release. */
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const assert = require('node:assert/strict');
+const semver = require('semver');
+const {
+  OFFICIAL_REGISTRY,
+  isExactVersion,
+  readUpdatePolicy,
+  authorizeTarget,
+} = require('./update-policy');
+
+function readProjectManifest(projectDir) {
+  const { safeAdapterPath } = require('./installed-adapters');
+  const { readInstallManifest } = require('./install-manifest');
+  return readInstallManifest(safeAdapterPath(projectDir, '_bmad/.bmad-plus-install.json'));
+}
+
+function refusal(reason, detail) {
+  return Object.assign(new Error(`Update refused: ${detail || reason}.`), {
+    code: 'UPDATE_REFUSED',
+    reason,
+  });
+}
+
+function requirePolicy(policy, targetVersion, auto) {
+  if (policy.registry !== OFFICIAL_REGISTRY) throw refusal('unsupported-registry');
+  if (policy.mode === 'off') throw refusal('updates-disabled');
+  if (semver.prerelease(targetVersion) && !policy.allowPrerelease)
+    throw refusal('prerelease-not-allowed');
+  if (auto) {
+    const authorization = authorizeTarget(policy, targetVersion);
+    if (!authorization.allowed) throw refusal(authorization.reason);
+  }
+}
+
+async function withExecutionDirectory(action) {
+  const parent = fs.realpathSync(os.tmpdir());
+  const directory = fs.mkdtempSync(path.join(parent, 'bmad-update-exec-'));
+  try {
+    // npm exec may otherwise select a project-local .cmd shim. npm's Windows
+    // shim fails on metacharacters in its own path; target argv is escaped by npm.
+    return await action(directory);
+  } finally {
+    const actual = fs.realpathSync(directory);
+    assert(
+      path.dirname(actual) === parent &&
+      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 });
+  }
+}
+
+async function runLatestUpdate({ projectDir, auto = false, yes = false }, injectedDeps = {}) {
+  if (typeof auto !== 'boolean' || typeof yes !== 'boolean')
+    throw refusal('invalid-confirmation-options');
+  const directory = path.resolve(projectDir || process.cwd());
+  const checkForUpdate = injectedDeps.checkForUpdate || require('./update-check').checkForUpdate;
+  const runNpm = injectedDeps.runNpm || require('./npm-runner').runNpm;
+  const readManifest = injectedDeps.readManifest || readProjectManifest;
+  const readPolicy = injectedDeps.readPolicy || readUpdatePolicy;
+  const platform = injectedDeps.platform || process.platform;
+  const nodeVersion = injectedDeps.nodeVersion || process.version;
+  const executeInDirectory = injectedDeps.withExecutionDirectory || withExecutionDirectory;
+  const manifest = readManifest(directory);
+  if (!isExactVersion(manifest.version)) throw refusal('invalid-installation');
+  const initialPolicy = readPolicy(directory);
+  if (initialPolicy.mode === 'off') throw refusal('updates-disabled');
+  if (auto && initialPolicy.mode !== 'auto') throw refusal('automatic-updates-not-authorized');
+
+  const check = await checkForUpdate({ projectDir: directory, refresh: true });
+  if (!check || check.source !== 'registry' || check.stale !== false)
+    throw refusal('fresh-metadata-required');
+  const targetVersion = check.targetVersion;
+  if (!isExactVersion(targetVersion)) throw refusal('invalid-target-version');
+  if (check.channel !== initialPolicy.channel) throw refusal('policy-channel-changed');
+  if (check.installedVersion !== manifest.version)
+    throw refusal('installation-changed-during-discovery');
+  if (check.status === 'ahead' || semver.lt(targetVersion, manifest.version))
+    throw refusal('downgrade-not-allowed');
+  if (check.status === 'current' && semver.eq(targetVersion, manifest.version)) {
+    return { status: 'current', targetVersion, installedVersion: manifest.version, updated: false };
+  }
+  if (
+    check.status !== 'update-available' ||
+    check.updateAvailable !== true ||
+    check.releaseEligible !== true ||
+    check.engineCompatible !== true ||
+    !semver.gt(targetVersion, manifest.version)
+  ) {
+    throw refusal(check.reason || 'release-not-eligible');
+  }
+  const engine = check.engines?.node;
+  if (
+    !check.engines ||
+    typeof check.engines !== 'object' ||
+    Array.isArray(check.engines) ||
+    (engine !== undefined &&
+      (typeof engine !== 'string' ||
+        !semver.validRange(engine) ||
+        !semver.satisfies(nodeVersion, engine)))
+  ) {
+    throw refusal('incompatible-or-invalid-node-engine');
+  }
+  requirePolicy(initialPolicy, targetVersion, auto);
+
+  const args = [
+    'exec',
+    '--yes',
+    `--package=bmad-plus@${targetVersion}`,
+    `--registry=${OFFICIAL_REGISTRY}`,
+    `--script-shell=${platform === 'win32' ? 'cmd.exe' : 'sh'}`,
+    '--',
+    'bmad-plus',
+    'update',
+    '--yes',
+    ...(auto ? ['--auto'] : []),
+    '--directory',
+    directory,
+    '--expected-version',
+    targetVersion,
+  ];
+  if (!auto && !yes) {
+    return {
+      status: 'approval-required',
+      reason: 'Confirm this exact update with --yes.',
+      installedVersion: manifest.version,
+      targetVersion,
+      updated: false,
+      command: ['npm', ...args],
+    };
+  }
+  if (auto) {
+    const evaluateReadiness =
+      injectedDeps.evaluateReadiness || require('./update-transaction').evaluateUpdateReadiness;
+    const readiness = await evaluateReadiness({ projectDir: directory, manifest });
+    if (readiness?.ready !== true || readiness.legacy || readiness.conflicts?.length) {
+      throw refusal(
+        'ownership-preflight-failed',
+        readiness?.reason || 'The installation is not ready for an automatic update'
+      );
+    }
+  }
+  // Re-read authorization after asynchronous work, including potential revocation.
+  const finalPolicy = readPolicy(directory);
+  requirePolicy(finalPolicy, targetVersion, auto);
+  if (finalPolicy.channel !== check.channel) throw refusal('policy-channel-changed');
+  const beforeExec = readManifest(directory);
+  if (beforeExec.version !== manifest.version)
+    throw refusal('installation-changed-before-execution');
+  const output = await executeInDirectory((cwd) =>
+    runNpm(args, { cwd, timeout: 120000, maxBuffer: 4 * 1024 * 1024 })
+  );
+  const updated = readManifest(directory);
+  if (updated.version !== targetVersion) {
+    throw Object.assign(
+      new Error(
+        `Updater finished without the expected manifest version ${targetVersion}. Inspect the project before retrying.\n${output}`
+      ),
+      {
+        code: 'UPDATE_UNVERIFIED',
+        reason: 'manifest-version-mismatch',
+        targetVersion,
+        stdout: output,
+      }
+    );
+  }
+  return {
+    status: 'updated',
+    installedVersion: updated.version,
+    previousVersion: manifest.version,
+    targetVersion,
+    updated: true,
+    reloadInstructions: true,
+    output,
+  };
+}
+
+module.exports = { runLatestUpdate };

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

@@ -0,0 +1,90 @@
+/** Explicit project policy for release discovery and automatic application. */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const semver = require('semver');
+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,
+});
+
+function isExactVersion(version) {
+  return typeof version === 'string' &&
+    /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version) &&
+    semver.valid(version) !== null;
+}
+
+function validatePolicy(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Update policy must be an object.');
+  }
+  if (value.schemaVersion !== undefined && value.schemaVersion !== 1) {
+    throw new Error('Unsupported update policy schemaVersion.');
+  }
+  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 (policy.mode === 'auto' && policy.allowedRange === null) {
+    throw new Error('Automatic updates require an explicit allowedRange.');
+  }
+  return policy;
+}
+
+function readUpdatePolicy(projectDir) {
+  const file = safeAdapterPath(projectDir, POLICY_FILE);
+  try {
+    return validatePolicy(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch (error) {
+    if (error.code === 'ENOENT') return { ...DEFAULT_POLICY };
+    throw new Error(`Update policy is unreadable or invalid: ${error.message}`, { cause: error });
+  }
+}
+
+/** Atomic project-local JSON write; never follow linked destinations or parents. */
+function writeProjectJson(projectDir, relativeFile, data) {
+  const file = safeAdapterPath(projectDir, relativeFile);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  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' });
+    safeAdapterPath(projectDir, relativeFile);
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.unlinkSync(temporary); } catch { /* Preserve the original write error if cleanup fails. */ }
+  }
+}
+
+function writeUpdatePolicy(projectDir, value) {
+  const policy = validatePolicy(value);
+  writeProjectJson(projectDir, POLICY_FILE, { schemaVersion: 1, ...policy });
+  return policy;
+}
+
+function authorizeTarget(value, version) {
+  let 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 })) {
+    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,
+};