bmad-plus 0.12.2 → 0.14.0

package/tools/cli/commands/studio.js

@@ -0,0 +1,68 @@
+/** Inspect installed Dev Studio routes and prepare actual host instructions. */
+const path = require('node:path');
+const { installedPack, validatePack, prepare } = require('../lib/studio');
+
+module.exports = {
+  command: 'studio <action> [workflow]',
+  description: 'List Dev Studio workflows or prepare read-only execution context',
+  options: [
+    ['-d, --directory <path>', 'Installed project directory'],
+    ['--request <text>', 'Task scope for the host assistant'],
+    [
+      '--input <file>',
+      'Project-relative input file (repeatable)',
+      (file, files) => [...files, file],
+      [],
+    ],
+    ['--json', 'Print machine-readable context and evidence'],
+  ],
+  action: (action, workflow, options = {}) => {
+    try {
+      const projectDir = path.resolve(options.directory || process.cwd());
+      let result;
+      if (action === 'list' && !workflow) {
+        const { catalog, resources } = validatePack(installedPack(projectDir));
+        result = {
+          schemaVersion: 1,
+          execution: 'host-managed',
+          ...catalog,
+          validatedResources: resources.length,
+        };
+      } else if (action === 'prepare' && workflow) {
+        result = prepare({ projectDir, workflow, request: options.request, inputs: options.input });
+      } else throw new Error('Use studio list or studio prepare WORKFLOW.');
+      process.exitCode = result.status === 'needs-input' ? 2 : 0;
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else if (action === 'list')
+        console.log(
+          result.workflows.map((w) => `${w.id} (${w.agent}; input: ${w.input})`).join('\n')
+        );
+      else
+        console.log(
+          [
+            `${result.workflow}: ${result.status} — prepared for the host, not executed.`,
+            `Project: ${result.projectDir}`,
+            `Request: ${result.request || '(none supplied)'}`,
+            `Resolved configuration:\n${JSON.stringify(result.config.values, null, 2)}`,
+            `Defaulted fields: ${result.config.defaultsUsed.join(', ') || '(none)'}`,
+            `Proposed report: ${result.outputPath}`,
+            ...result.missingInputs,
+            ...result.instructions.map(
+              (item) => `\n--- ${item.path} (${item.sha256}) ---\n${item.content}`
+            ),
+            ...result.inputs.map(
+              (item) => `\n--- Project input: ${item.path} (${item.sha256}) ---\n${item.content}`
+            ),
+            result.previousReport
+              ? `\n--- Continue existing report ---\n${result.previousReport.content}`
+              : '',
+          ].join('\n')
+        );
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }));
+      else console.error('Dev Studio: ' + error.message);
+    }
+  },
+};

package/tools/cli/commands/uninstall.js

@@ -1,101 +1,209 @@
 /**
  * BMAD+ Uninstall Command
- * Removes BMAD+ agents, skills, and configs from the current project
- * Internationalized — uses i18n system
- *
+ * Removes identifiable BMAD+ files while preserving project memory and edits.
  * Author: Laurent Rochetta
  */
 
 const path = require('node:path');
 const fs = require('node:fs');
-const fsExtra = require('fs-extra');
 const clack = require('@clack/prompts');
 const pc = require('picocolors');
 const { t } = require('../i18n');
+const { PACKS, DERIVED } = require('../lib/packs');
+const { readInstallManifest } = require('../lib/install-manifest');
+const { generateUserFiles, USER_CONFIG_MARKER } = require('../../build/generate-adapters');
+const { contentHash } = require('../lib/installed-adapters');
+
+// Never follow a junction/symlink in a path used for deletion, including parents.
+function safeStat(projectDir, target) {
+  const relative = path.relative(projectDir, target);
+  if (!relative || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new Error('Path outside the project: ' + target);
+  }
+  let current = projectDir;
+  let stat;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    try {
+      stat = fs.lstatSync(current);
+    } catch (err) {
+      if (err.code === 'ENOENT') return undefined;
+      throw err;
+    }
+    if (stat.isSymbolicLink()) {
+      const error = new Error('Symbolic link or junction: ' + current);
+      error.code = 'BMAD_UNSAFE_LINK';
+      throw error;
+    }
+  }
+  return stat;
+}
+
+function removalPlan(projectDir, manifest, manifestPath) {
+  const packageRoot = path.join(__dirname, '..', '..', '..');
+  const sourceRoot = path.join(packageRoot, 'src', 'bmad-plus');
+  const files = new Map();
+  const directories = new Set();
+  const targetPath = (...parts) => path.join(projectDir, ...parts);
+
+  // Old manifests contain pack IDs, not file hashes. Match shipped files byte for
+  // byte; anything unknown or modified stays, including files inside a pack.
+  function matchSource(source, target) {
+    const targetStat = safeStat(projectDir, target);
+    if (!targetStat || !fs.existsSync(source)) return;
+    const sourceStat = fs.lstatSync(source);
+    if (sourceStat.isDirectory() && targetStat.isDirectory()) {
+      directories.add(target);
+      for (const name of fs.readdirSync(source)) matchSource(path.join(source, name), path.join(target, name));
+    } else if (sourceStat.isFile() && targetStat.isFile()) {
+      const expected = fs.readFileSync(source);
+      if (fs.readFileSync(target).equals(expected)) files.set(target, expected);
+    }
+  }
+
+  for (const relative of ['.agents', '.agents/skills', '.agents/data', '_bmad', '_bmad-output']) {
+    const target = targetPath(relative);
+    if (safeStat(projectDir, target)?.isDirectory()) directories.add(target);
+  }
+
+  for (const packId of manifest.packs) {
+    if (!Object.hasOwn(PACKS, packId)) throw new Error('Unknown installed pack: ' + packId);
+    const pack = PACKS[packId];
+    for (const name of pack.agents || []) matchSource(path.join(sourceRoot, 'agents', name), targetPath('.agents', 'skills', name));
+    for (const name of pack.skills || []) matchSource(path.join(sourceRoot, 'skills', name), targetPath('.agents', 'skills', name));
+    for (const name of pack.data || []) matchSource(path.join(sourceRoot, 'data', name), targetPath('.agents', 'data', name));
+    if (pack.packDir) matchSource(path.join(sourceRoot, pack.packSrcDir || 'agents', pack.packDir), targetPath('.agents', 'skills', pack.packDir));
+    if (pack.externalPackage) matchSource(path.join(packageRoot, pack.externalPackage, 'skills'), targetPath('.agents', 'skills'));
+  }
+  for (const name of ['module.yaml', 'module-help.csv']) matchSource(path.join(sourceRoot, name), targetPath('_bmad', name));
+  const renderOptions = {
+    packs: manifest.packs,
+    userName: typeof manifest.user === 'string' ? manifest.user : 'Developer',
+    language: typeof manifest.language === 'string' ? manifest.language : 'English',
+  };
+  const expectedFiles = new Map(generateUserFiles(DERIVED, renderOptions).map(entry => [entry.file, entry.content]));
+  const hashes = manifest.adapterHashes && typeof manifest.adapterHashes === 'object' && !Array.isArray(manifest.adapterHashes)
+    ? manifest.adapterHashes : {};
+  // Only registry-declared paths can become deletion candidates, even when the
+  // manifest contains arbitrary hash keys. Keep previously owned tool targets.
+  const claimed = new Set(Object.keys(hashes).filter(file => expectedFiles.has(file)));
+  if (Array.isArray(manifest.ides)) {
+    const tools = manifest.ides.filter(id => DERIVED.targets.adapters.some(adapter => adapter.tool === id));
+    if (tools.length) {
+      for (const entry of generateUserFiles(DERIVED, { ...renderOptions, tools })) {
+        claimed.add(entry.file);
+        expectedFiles.set(entry.file, entry.content);
+      }
+    }
+  }
+  const legacyFallback = !Array.isArray(manifest.ides) && Object.keys(hashes).length === 0;
+  for (const [file, rendered] of expectedFiles) {
+    if (!legacyFallback && !claimed.has(file)) continue;
+    const target = targetPath(file);
+    let stat;
+    try {
+      stat = safeStat(projectDir, target);
+    } catch (error) {
+      // A link with no ownership evidence is user content, not an uninstall target.
+      if (legacyFallback && error.code === 'BMAD_UNSAFE_LINK') continue;
+      throw error;
+    }
+    if (stat?.isFile()) {
+      const content = fs.readFileSync(target);
+      const text = content.toString('utf8');
+      const expectedHash = hashes[file];
+      const matches = expectedHash ? contentHash(text) === expectedHash : text === rendered;
+      if (text.includes(USER_CONFIG_MARKER) && matches) {
+        files.set(target, content);
+        let parent = path.dirname(target);
+        while (parent !== projectDir) {
+          directories.add(parent);
+          parent = path.dirname(parent);
+        }
+      }
+    }
+  }
+  // Keep config.yaml: it contains the user's settings and has no ownership hash.
+  files.set(manifestPath, fs.readFileSync(manifestPath));
+  return { files, directories };
+}
 
 module.exports = {
   command: 'uninstall',
   description: 'Remove BMAD+ from your project',
   options: [
+    ['-y, --yes', 'Confirm removal without prompting'],
     ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it'],
   ],
   action: async (options) => {
-    const projectDir = process.cwd();
-
+    const projectDir = fs.realpathSync(process.cwd());
+    let i = t(options.lang || 'en');
     clack.intro(pc.bgRed(pc.white(' BMAD+ Uninstaller ')));
 
-    // Check if installed
     const manifestPath = path.join(projectDir, '_bmad', '.bmad-plus-install.json');
-    if (!fs.existsSync(manifestPath)) {
-      clack.log.warn('BMAD+ is not installed in this directory.');
-      clack.outro('Nothing to remove.');
+    let manifest;
+    try {
+      if (!safeStat(projectDir, manifestPath)) {
+        clack.log.warn(i.uninstall_not_installed);
+        return;
+      }
+      manifest = readInstallManifest(manifestPath);
+    } catch (err) {
+      clack.log.error(i.manifest_invalid(err.message));
+      clack.outro(pc.red(i.manifest_repair));
+      process.exitCode = 1;
       return;
     }
-
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-
-    // Use --lang flag, or fall back to manifest language
-    let lang = options.lang || manifest.uiLanguage || 'en';
-    const i = t(lang);
-
-    clack.log.info(`BMAD+ v${manifest.version} (${i.installed_on || 'installed'} ${manifest.installed.split('T')[0]})`);
-    clack.log.info(`${i.selected_packs}: ${(manifest.packs || ['core']).join(', ')}`);
-
-    const confirm = await clack.confirm({
-      message: i.uninstall_confirm || 'Remove BMAD+ from this project?',
-    });
-
-    if (!confirm || clack.isCancel(confirm)) {
-      clack.cancel(i.cancelled);
+    i = t(options.lang || manifest.uiLanguage || 'en');
+    if (!options.yes && !process.stdin.isTTY) {
+      clack.log.error(i.noninteractive_requires_yes('uninstall'));
+      process.exitCode = 1;
       return;
     }
 
-    const spinner = clack.spinner();
-    spinner.start(i.uninstall_removing || 'Removing...');
-
-    let removed = 0;
-
-    // Remove .agents/skills/ (BMAD+ agents & skills)
-    const agentsDir = path.join(projectDir, '.agents');
-    if (fs.existsSync(agentsDir)) {
-      fsExtra.removeSync(agentsDir);
-      removed++;
-    }
-
-    // Remove _bmad/ config
-    const bmadDir = path.join(projectDir, '_bmad');
-    if (fs.existsSync(bmadDir)) {
-      fsExtra.removeSync(bmadDir);
-      removed++;
+    let plan;
+    try {
+      plan = removalPlan(projectDir, manifest, manifestPath);
+    } catch (err) {
+      clack.log.error(i.uninstall_aborted(err.message));
+      process.exitCode = 1;
+      return;
     }
-
-    // Remove _bmad-output/ (only if empty)
-    const outputDir = path.join(projectDir, '_bmad-output');
-    if (fs.existsSync(outputDir)) {
-      const contents = fs.readdirSync(outputDir, { recursive: true }).filter(f => !f.startsWith('.'));
-      if (contents.length === 0) {
-        fsExtra.removeSync(outputDir);
-        removed++;
-      } else {
-        clack.log.info(i.uninstall_output_kept || '📁 _bmad-output/ kept (contains files)');
+    clack.log.info('BMAD+ v' + manifest.version + ' (' + i.installed_on + ' ' + manifest.installed.split('T')[0] + ')');
+    clack.log.info(i.selected_packs + ': ' + manifest.packs.join(', '));
+    if (!options.yes) {
+      const confirm = await clack.confirm({ message: i.uninstall_confirm });
+      if (!confirm || clack.isCancel(confirm)) {
+        clack.cancel(i.cancelled);
+        return;
       }
     }
 
-    // Remove IDE configs (only BMAD+-generated ones)
-    for (const configFile of ['CLAUDE.md', 'GEMINI.md', 'AGENTS.md', 'OPENCODE.md']) {
-      const p = path.join(projectDir, configFile);
-      if (fs.existsSync(p)) {
-        const content = fs.readFileSync(p, 'utf8');
-        // NODE-05: only remove a config BMAD+ actually generated (it carries the
-        // marker below). A hand-authored file that merely mentions "BMAD+" is kept.
-        if (content.includes('BMAD+ — AI Agent Configuration')) {
-          fs.unlinkSync(p);
+    const spinner = clack.spinner();
+    spinner.start(i.uninstall_removing);
+    let removed = 0;
+    try {
+      // Revalidate after the prompt, before deleting any file.
+      for (const target of [...plan.files.keys(), ...plan.directories]) safeStat(projectDir, target);
+      for (const [target, expected] of plan.files) {
+        if (safeStat(projectDir, target)?.isFile() && fs.readFileSync(target).equals(expected)) {
+          fs.unlinkSync(target);
           removed++;
         }
       }
+      // No recursive deletion: hidden files, nested user content, and memory stay.
+      for (const target of [...plan.directories].sort((a, b) => b.length - a.length)) {
+        if (safeStat(projectDir, target)?.isDirectory() && fs.readdirSync(target).length === 0) {
+          fs.rmdirSync(target);
+          removed++;
+        }
+      }
+    } catch (err) {
+      spinner.stop(i.uninstall_aborted(err.message));
+      process.exitCode = 1;
+      return;
     }
-
-    spinner.stop(i.uninstall_done ? i.uninstall_done(removed) : `✅ BMAD+ removed (${removed} items)`);
-    clack.outro(pc.green(i.guide_ready ? '👋 Done!' : 'Done!'));
+    spinner.stop(i.uninstall_done(removed));
+    clack.outro(i.uninstall_preserved);
   },
 };

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

@@ -0,0 +1,31 @@
+/** Report release status without applying updates. */
+const path = require('node:path');
+const { checkForUpdate } = require('../lib/update-check');
+
+module.exports = {
+  command: 'update-check',
+  description: 'Check the published BMAD+ release without applying it',
+  options: [
+    ['-d, --directory <path>', 'Project directory (default: current directory)'],
+    ['--refresh', 'Bypass the release cache and retry backoff'],
+    ['--offline', 'Report local state without network access'],
+    ['--json', 'Print machine-readable JSON'],
+  ],
+  action: async (options = {}) => {
+    const result = await checkForUpdate({
+      projectDir: path.resolve(options.directory || process.cwd()),
+      runningVersion: require('../../../package.json').version,
+      refresh: Boolean(options.refresh), offline: Boolean(options.offline),
+      checkReadiness: ({ projectDir }) => {
+        const { evaluateUpdateReadiness } = require('../lib/update-transaction');
+        return evaluateUpdateReadiness({ projectDir });
+      },
+    });
+    if (result.status.startsWith('invalid-')) process.exitCode = 1;
+    if (options.json) console.log(JSON.stringify(result));
+    else {
+      console.log(`Installed: ${result.installedVersion || 'unknown'}; running: ${result.runningVersion}; channel ${result.channel || 'unknown'}: ${result.targetVersion || 'unknown'}`);
+      console.log(`${result.status}: ${result.reason}${result.stale ? ' (cached result is stale)' : ''}`);
+    }
+  },
+};

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

@@ -0,0 +1,39 @@
+/** Show or explicitly configure the local update policy; never updates packages. */
+const path = require('node:path');
+const { readUpdatePolicy, writeUpdatePolicy } = require('../lib/update-policy');
+
+module.exports = {
+  command: 'update-policy',
+  description: 'Show or configure the project update policy',
+  options: [
+    ['-d, --directory <path>', 'Project directory (default: current directory)'],
+    ['--mode <mode>', 'off, notify, or auto (auto requires --range)'],
+    ['--range <range>', 'Explicit semantic-version range for automatic updates'],
+    ['--channel <tag>', 'npm release tag (default: latest)'],
+    ['--allow-prerelease', 'Explicitly allow prerelease targets'],
+    ['--stable-only', 'Disable prerelease targets'],
+    ['--json', 'Print machine-readable JSON'],
+  ],
+  action: async (options = {}) => {
+    try {
+      if (options.allowPrerelease && options.stableOnly) throw new Error('Choose --allow-prerelease or --stable-only.');
+      if (options.mode === 'auto' && !options.range) throw new Error('--mode auto requires an explicit --range.');
+      const projectDir = path.resolve(options.directory || process.cwd());
+      const policy = readUpdatePolicy(projectDir);
+      const changing = options.mode !== undefined || options.range !== undefined ||
+        options.channel !== undefined || options.allowPrerelease || options.stableOnly;
+      if (options.mode !== undefined) policy.mode = options.mode;
+      if (options.range !== undefined) policy.allowedRange = options.range;
+      if (options.channel !== undefined) policy.channel = options.channel;
+      if (options.allowPrerelease) policy.allowPrerelease = true;
+      if (options.stableOnly) policy.allowPrerelease = false;
+      const saved = changing ? writeUpdatePolicy(projectDir, policy) : policy;
+      if (options.json) console.log(JSON.stringify({ policy: saved, changed: Boolean(changing) }));
+      else console.log(`Update policy${changing ? ' saved' : ''}: ${saved.mode}; channel=${saved.channel}; range=${saved.allowedRange || 'none'}; prereleases=${saved.allowPrerelease}`);
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json) console.log(JSON.stringify({ error: error.message }));
+      else console.error(error.message);
+    }
+  },
+};

package/tools/cli/commands/update.js

@@ -1,134 +1,123 @@
 /**
- * BMAD+ Update Command
- * Updates agents and skills while preserving user config
- *
+ * BMAD+ Update Command — planned updates with recoverable backups.
  * Author: Laurent Rochetta
  */
-
 const path = require('node:path');
 const fs = require('node:fs');
-const fsExtra = require('fs-extra');
+const semver = require('semver');
 const clack = require('@clack/prompts');
 const pc = require('picocolors');
 const { t } = require('../i18n');
-const { PACKS } = require('../lib/packs');
-const { copyPackFiles } = require('../lib/pack-copy');
-
-// Pack definitions imported from shared module: require('../lib/packs').PACKS
+const { safeTarget } = require('../../build/generate-adapters');
+const { readInstallManifest } = require('../lib/install-manifest');
+const { isExactVersion } = require('../lib/update-policy');
+const { planUpdate, applyPlan, restoreUpdate, MANIFEST } = require('../lib/update-transaction');
+
+function authorizeAuto(projectDir, version) {
+  const { readUpdatePolicy, authorizeTarget } = require('../lib/update-policy');
+  const decision = authorizeTarget(readUpdatePolicy(projectDir), version);
+  if (!decision.allowed) throw new Error('Automatic update refused: ' + decision.reason);
+}
+
+async function confirmAction(options, message, lang = 'en') {
+  if (options.yes || options.auto) return true;
+  const i = t(lang);
+  if (!process.stdin.isTTY) throw new Error(i.noninteractive_requires_yes('update'));
+  const confirmed = await clack.confirm({ message });
+  if (!confirmed || clack.isCancel(confirmed)) {
+    clack.cancel(i.cancelled);
+    return false;
+  }
+  return true;
+}
 
 module.exports = {
   command: 'update',
-  description: 'Update BMAD+ agents and skills (preserves config)',
+  description: 'Update BMAD+ agents and skills (preserves local changes)',
   options: [
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
+    ['-y, --yes', 'Confirm update without prompting'],
     ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it'],
+    ['--latest', 'Resolve and run the exact latest compatible published package'],
+    ['--expected-version <version>', 'Require this exact executing package version'],
+    ['--auto', 'Apply only when automatic update policy and ownership allow it'],
+    ['--restore <receipt-id>', 'Restore files from an update receipt'],
   ],
   action: async (options) => {
     const projectDir = path.resolve(options.directory || process.cwd());
-    const bmadSrc = path.join(__dirname, '..', '..', '..', 'src', 'bmad-plus');
-    const packageJson = require('../../../package.json');
-
-    clack.intro(pc.bgMagenta(pc.white(` BMAD+ Updater v${packageJson.version} `)));
-
-    // Check if installed
-    const manifestPath = path.join(projectDir, '_bmad', '.bmad-plus-install.json');
-    if (!fs.existsSync(manifestPath)) {
-      clack.log.error('BMAD+ is not installed in this directory.');
-      clack.log.info('Run `npx bmad-plus install` first.');
-      clack.outro(pc.red('Update aborted.'));
-      return;
-    }
-
-    let manifest;
+    const version = require('../../../package.json').version;
+    let spinner;
     try {
-      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    } catch (err) {
-      clack.log.error(`Install manifest is unreadable or corrupt: ${err.message}`);
-      clack.log.info('Re-run `npx bmad-plus install` to repair the installation.');
-      clack.outro(pc.red('Update aborted.'));
-      return;
+      if (options.restore && (options.latest || options.expectedVersion)) {
+        throw new Error('--restore cannot be combined with --latest or --expected-version.');
+      }
+      // The dispatcher resolves the target package; this local package may be older.
+      if (options.latest) {
+        const result = await require('../lib/update-dispatch').runLatestUpdate({
+          projectDir, auto: Boolean(options.auto), yes: Boolean(options.yes),
+        });
+        clack.log.info(result.reason || result.status);
+        if (result.output) clack.log.info(result.output);
+        if (result.targetVersion) clack.log.info('Target: v' + result.targetVersion);
+        if (result.reloadInstructions) clack.log.info('Reload your agent instructions or start a new session.');
+        return;
+      }
+
+      clack.intro(pc.bgMagenta(pc.white(' BMAD+ Updater v' + version + ' ')));
+      if (options.restore) {
+        if (options.auto) throw new Error('Recovery requires manual approval.');
+        if (!await confirmAction(options, 'Restore the files saved in receipt ' + options.restore + '?', options.lang)) return;
+        const restored = restoreUpdate({ projectDir, receiptId: options.restore });
+        clack.log.success('Restored BMAD+ v' + restored.restoredVersion);
+        clack.log.info('Receipt: ' + restored.receiptPath);
+        clack.outro('Reload your agent instructions or start a new session.');
+        return;
+      }
+
+      if (options.auto && !options.expectedVersion) throw new Error('Automatic update requires --expected-version.');
+      if (options.expectedVersion && options.expectedVersion !== version) {
+        throw new Error('Executing package version ' + version + ' does not match expected version ' + options.expectedVersion + '.');
+      }
+      const manifestPath = safeTarget(projectDir, MANIFEST);
+      if (!fs.existsSync(manifestPath)) throw new Error('BMAD+ is not installed in this directory. Run bmad-plus install first.');
+      let manifest;
+      try { manifest = readInstallManifest(manifestPath); } catch (error) {
+        throw new Error('Install manifest is unreadable or corrupt: ' + error.message, { cause: error });
+      }
+      if (!isExactVersion(version) || !isExactVersion(manifest.version)) throw new Error('Update versions must be strict semantic versions.');
+      if (semver.lt(version, manifest.version)) throw new Error('Downgrade refused: ' + manifest.version + ' -> ' + version);
+      const lang = options.lang || manifest.uiLanguage || 'en';
+      clack.log.info('Installed: v' + manifest.version + ' -> Executing package: v' + version);
+      if (manifest.version === version) {
+        clack.log.success('The installed version matches this executing package. Use --latest to check the registry.');
+        clack.outro(pc.green('Nothing to update.'));
+        return;
+      }
+      const plan = planUpdate({ projectDir, manifest, version, auto: Boolean(options.auto) });
+      if (options.auto) {
+        authorizeAuto(projectDir, version);
+        const fresh = await require('../lib/update-check').checkForUpdate({ projectDir, runningVersion: version, refresh: true });
+        if (fresh.source !== 'registry' || fresh.stale || !fresh.versionEligible || fresh.targetVersion !== options.expectedVersion) {
+          throw new Error('Automatic update requires a fresh, eligible registry target matching --expected-version.');
+        }
+      }
+
+      clack.log.info('Planned changes: ' + (plan.files.length - 1) + ' files; preserved conflicts: ' + plan.conflicts.length + '.');
+      if (plan.legacy) clack.log.warn('Legacy installation: original pack files will be backed up before replacement because ownership hashes are unavailable. Review the receipt to recover local edits.');
+      for (const conflict of plan.conflicts) clack.log.warn(conflict.file + ': preserved (' + conflict.reason + ').');
+      if (!await confirmAction(options, 'Apply this update from v' + manifest.version + ' to v' + version + '?', lang)) return;
+
+      spinner = clack.spinner();
+      spinner.start('Updating managed files...');
+      const result = applyPlan(plan, { reauthorize: () => authorizeAuto(projectDir, version) });
+      spinner.stop(result.changedFiles.length + ' files updated; ' + result.conflicts.length + ' local conflicts preserved.');
+      spinner = null;
+      clack.log.info('Receipt and backups: ' + result.receiptPath);
+      clack.outro(pc.green('BMAD+ v' + version + (result.conflicts.length ? ' applied partially.' : ' installed.') + ' Reload your agent instructions or start a new session.'));
+    } catch (error) {
+      if (spinner) spinner.stop('Update failed.');
+      clack.log.error(error.message);
+      process.exitCode = 1;
     }
-    if (!manifest || typeof manifest !== 'object') {
-      clack.log.error('Install manifest is malformed (not an object).');
-      clack.log.info('Re-run `npx bmad-plus install` to repair the installation.');
-      clack.outro(pc.red('Update aborted.'));
-      return;
-    }
-    const lang = options.lang || manifest.uiLanguage || 'en';
-    const i = t(lang);
-
-    clack.log.info(`📦 Installed: v${manifest.version} → Available: v${packageJson.version}`);
-
-    if (manifest.version === packageJson.version) {
-      clack.log.success(i.update_current || '✅ Already up to date!');
-      clack.outro(pc.green('Nothing to update.'));
-      return;
-    }
-
-    // Guard against a missing/malformed `packs` field (NODE-04): coerce to an array.
-    const selectedPacks = Array.isArray(manifest.packs) && manifest.packs.length > 0
-      ? manifest.packs
-      : ['core'];
-    clack.log.info(`${i.selected_packs}: ${selectedPacks.join(', ')}`);
-
-    const confirm = await clack.confirm({
-      message: i.update_confirm || `Update from v${manifest.version} to v${packageJson.version}?`,
-    });
-
-    if (!confirm || clack.isCancel(confirm)) {
-      clack.cancel(i.cancelled);
-      return;
-    }
-
-    const spinner = clack.spinner();
-    spinner.start(i.update_updating || 'Updating agents and skills...');
-
-    const targetAgentsDir = path.join(projectDir, '.agents', 'skills');
-    const targetDataDir = path.join(projectDir, '.agents', 'data');
-
-    fsExtra.ensureDirSync(targetAgentsDir);
-    fsExtra.ensureDirSync(targetDataDir);
-
-    let updated = 0;
-
-    const projectRoot = path.join(bmadSrc, '..', '..');
-
-    for (const packId of selectedPacks) {
-      const pack = PACKS[packId];
-      if (!pack) continue;
-
-      const result = copyPackFiles({
-        bmadSrc,
-        targetAgentsDir,
-        targetDataDir,
-        projectRoot,
-        pack,
-      });
-      updated += result.copiedAgents + result.copiedSkills + result.copiedFiles;
-    }
-
-    // Update module config (always)
-    const moduleYaml = path.join(bmadSrc, 'module.yaml');
-    const targetBmadDir = path.join(projectDir, '_bmad');
-    if (fs.existsSync(moduleYaml)) {
-      fsExtra.copySync(moduleYaml, path.join(targetBmadDir, 'module.yaml'));
-      updated++;
-    }
-
-    const helpCsv = path.join(bmadSrc, 'module-help.csv');
-    if (fs.existsSync(helpCsv)) {
-      fsExtra.copySync(helpCsv, path.join(targetBmadDir, 'module-help.csv'));
-      updated++;
-    }
-
-    // Update manifest version (preserve everything else)
-    manifest.version = packageJson.version;
-    manifest.lastUpdated = new Date().toISOString();
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
-
-    spinner.stop(i.update_done ? i.update_done(updated) : `✅ ${updated} files updated to v${packageJson.version}`);
-
-    clack.log.info('📋 Config preserved: config.yaml, IDE configs, output directories');
-    clack.outro(pc.green(i.update_ready || `BMAD+ v${packageJson.version} is ready! 🚀`));
   },
 };