bmad-plus 0.12.2 → 0.14.0

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

@@ -0,0 +1,334 @@
+/** Planned, locked framework updates with exact ownership and recoverable backups. */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const semver = require('semver');
+const { PACKS, DERIVED } = require('./packs');
+const { listPackFiles, fileHash } = require('./pack-copy');
+const { contentHash, classifyAdapter, INSTALLER_MARKER } = require('./installed-adapters');
+const { generateUserFiles, IDE_CONFIGS, GENERATED_MARKER, USER_CONFIG_MARKER, safeTarget } = require('../../build/generate-adapters');
+const { readInstallManifest } = require('./install-manifest');
+const { isExactVersion } = require('./update-policy');
+
+const MANIFEST = '_bmad/.bmad-plus-install.json';
+const LOCK = '.bmad/update.lock';
+const MODULE_FILES = ['_bmad/module.yaml', '_bmad/module-help.csv'];
+const DEFAULT_PACKAGE_ROOT = path.resolve(__dirname, '../../..');
+const relativeFile = (root, target) => path.relative(root, target).split(path.sep).join('/');
+const currentBytes = (root, file) => {
+  const target = safeTarget(root, file);
+  return fs.existsSync(target) ? fs.readFileSync(target) : null;
+};
+const currentHash = (root, file) => {
+  const content = currentBytes(root, file);
+  return content === null ? null : fileHash(content);
+};
+const isManagedFile = file => typeof file === 'string' && !file.includes('\\') &&
+  path.posix.normalize(file) === file && (MODULE_FILES.includes(file) ||
+  file.startsWith('.agents/skills/') || file.startsWith('.agents/data/'));
+
+function inventoryOf(manifest) {
+  const inventory = manifest.fileInventory;
+  if (!inventory || inventory.schemaVersion !== 1 || !inventory.files ||
+      typeof inventory.files !== 'object' || Array.isArray(inventory.files)) return null;
+  for (const [file, hash] of Object.entries(inventory.files)) {
+    if (!isManagedFile(file) || !/^[a-f0-9]{64}$/.test(hash)) return null;
+  }
+  return inventory.files;
+}
+
+function hasCompleteInventory(manifest, inventory) {
+  return Boolean(inventory && manifest.fileInventory.complete === true && MODULE_FILES.every(file => typeof inventory[file] === 'string'));
+}
+
+function collectManagedFiles({ projectDir, packageRoot = DEFAULT_PACKAGE_ROOT, packs }) {
+  const files = new Map();
+  const bmadSrc = path.join(packageRoot, 'src', 'bmad-plus');
+  for (const id of packs) {
+    if (!Object.hasOwn(PACKS, id)) throw new Error('Unknown installed pack: ' + id);
+    const entries = listPackFiles({ bmadSrc, projectRoot: packageRoot,
+      targetAgentsDir: path.join(projectDir, '.agents', 'skills'),
+      targetDataDir: path.join(projectDir, '.agents', 'data'), pack: PACKS[id] });
+    for (const entry of entries.files) files.set(relativeFile(projectDir, entry.target), entry.source);
+  }
+  for (const file of MODULE_FILES) files.set(file, path.join(bmadSrc, path.basename(file)));
+  return [...files].map(([file, source]) => {
+    safeTarget(packageRoot, relativeFile(packageRoot, source));
+    return { file, content: fs.readFileSync(source), kind: 'pack' };
+  });
+}
+
+function installedTools(projectDir, manifest) {
+  if (Array.isArray(manifest.ides)) return manifest.ides.filter(id => Object.hasOwn(IDE_CONFIGS, id));
+  const tools = Object.keys(IDE_CONFIGS).filter(id => fs.existsSync(safeTarget(projectDir, IDE_CONFIGS[id].configFile)));
+  const spine = currentBytes(projectDir, DERIVED.targets.spine)?.toString('utf8');
+  if (spine?.includes(INSTALLER_MARKER) && !spine.includes(GENERATED_MARKER) && !tools.includes('codex-cli')) tools.push('codex-cli');
+  return tools;
+}
+
+function evaluateUpdateReadiness({ projectDir, manifest }) {
+  try {
+    manifest ||= readInstallManifest(safeTarget(projectDir, MANIFEST));
+    const inventory = inventoryOf(manifest);
+    if (!hasCompleteInventory(manifest, inventory)) return { ready: false, legacy: true, conflicts: [], reason: 'Complete file ownership inventory is required.' };
+    const conflicts = [];
+    if (fs.existsSync(safeTarget(projectDir, LOCK))) conflicts.push({ file: LOCK, reason: 'update-in-progress' });
+    for (const [file, hash] of Object.entries(inventory)) {
+      const current = currentHash(projectDir, file);
+      if (current !== null && current !== hash) conflicts.push({ file, reason: 'modified-managed-file' });
+    }
+    const tools = installedTools(projectDir, manifest);
+    const expected = tools.length ? generateUserFiles(DERIVED, { packs: manifest.packs, tools }) : [];
+    for (const { file } of expected) {
+      const bytes = currentBytes(projectDir, file);
+      if (bytes !== null && (!bytes.toString('utf8').includes(USER_CONFIG_MARKER) ||
+          contentHash(bytes.toString('utf8')) !== manifest.adapterHashes?.[file])) {
+        conflicts.push({ file, reason: 'unowned-or-modified-adapter' });
+      }
+    }
+    return { ready: conflicts.length === 0, legacy: false, conflicts,
+      reason: conflicts.length ? 'Local changes or an active update require manual review.' : 'Managed files are unchanged.' };
+  } catch (error) {
+    return { ready: false, legacy: false, conflicts: [], reason: error.message };
+  }
+}
+
+/** Read-only plan: every destination is checked before the first mutation. */
+function planUpdate({ projectDir, packageRoot = DEFAULT_PACKAGE_ROOT, manifest, version, auto = false }) {
+  projectDir = path.resolve(projectDir);
+  const snapshot = currentBytes(projectDir, MANIFEST);
+  const live = readInstallManifest(safeTarget(projectDir, MANIFEST));
+  if (manifest && JSON.stringify(live) !== JSON.stringify(manifest)) throw new Error('Installation manifest changed; check again.');
+  manifest = live;
+  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 owned = inventoryOf(manifest);
+  let legacy = !hasCompleteInventory(manifest, owned);
+  const nextHashes = { ...(owned || {}) };
+  const nextAdapterHashes = { ...(manifest.adapterHashes || {}) };
+  const tools = installedTools(projectDir, manifest);
+  const expected = collectManagedFiles({ projectDir, packageRoot, packs: manifest.packs });
+  if (tools.length) expected.push(...generateUserFiles(DERIVED, {
+    packs: manifest.packs, tools, userName: manifest.user || 'Developer', language: manifest.language || 'English',
+  }).map(entry => ({ file: entry.file, content: Buffer.from(entry.content), kind: 'adapter' })));
+  const observed = new Map([[MANIFEST, fileHash(snapshot)]]);
+  const files = [];
+  const conflicts = [];
+  for (const [file, hash] of Object.entries(owned || {})) {
+    const current = currentHash(projectDir, file);
+    observed.set(file, current);
+    if (!expected.some(entry => entry.file === file) && current !== null && current !== hash) {
+      conflicts.push({ file, reason: 'modified-managed-file' });
+    }
+  }
+  for (const entry of expected) {
+    const before = currentBytes(projectDir, entry.file);
+    const beforeHash = before === null ? null : fileHash(before);
+    observed.set(entry.file, beforeHash);
+    const afterHash = fileHash(entry.content);
+    let backupLegacy = false;
+    if (entry.kind === 'adapter') {
+      const decision = classifyAdapter({ existing: before?.toString('utf8'), content: entry.content.toString('utf8'),
+        previousHash: manifest.adapterHashes?.[entry.file], update: true });
+      if (decision.action === 'preserve') {
+        conflicts.push({ file: entry.file, reason: decision.reason });
+        continue;
+      }
+      backupLegacy = decision.backup;
+      if (decision.legacy) legacy = true;
+      nextAdapterHashes[entry.file] = contentHash(entry.content.toString('utf8'));
+    } else {
+      if (before !== null && owned?.[entry.file] && beforeHash !== owned[entry.file]) {
+        conflicts.push({ file: entry.file, reason: 'modified-managed-file' });
+        continue;
+      }
+      if (before !== null && !owned?.[entry.file] && beforeHash !== afterHash) {
+        if (owned) {
+          conflicts.push({ file: entry.file, reason: 'unowned-file' });
+          continue;
+        }
+        legacy = true;
+      }
+      nextHashes[entry.file] = afterHash;
+    }
+    if (beforeHash !== afterHash) files.push({ ...entry, beforeHash, afterHash, backupLegacy });
+  }
+  const nextManifest = { ...manifest, version, lastUpdated: new Date().toISOString(), ides: tools,
+    adapterHashes: nextAdapterHashes, fileInventory: { schemaVersion: 1,
+      complete: !conflicts.some(entry => entry.reason === 'unowned-file'), files: nextHashes } };
+  const manifestContent = Buffer.from(JSON.stringify(nextManifest, null, 2));
+  files.push({ file: MANIFEST, kind: 'manifest', content: manifestContent,
+    beforeHash: fileHash(snapshot), afterHash: fileHash(manifestContent) });
+  for (const { file } of files) safeTarget(projectDir, file);
+  if (auto && (legacy || conflicts.length)) throw new Error('Automatic update refused: ' + (legacy ? 'legacy ownership inventory' : 'local file conflicts'));
+  return { projectDir, fromVersion: manifest.version, toVersion: version, files, conflicts, legacy,
+    inventoryComplete: !legacy, nextManifest, observed: [...observed], auto };
+}
+
+function acquireProjectLock(projectDir, { receiptId = null } = {}) {
+  const target = safeTarget(projectDir, LOCK);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const id = crypto.randomUUID();
+  let fd;
+  try { fd = fs.openSync(target, 'wx'); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Another update is in progress: ' + target, { cause: error });
+    throw error;
+  }
+  try { fs.writeFileSync(fd, JSON.stringify({ id, pid: process.pid, receiptId })); } catch (error) {
+    fs.closeSync(fd);
+    fs.unlinkSync(target);
+    throw error;
+  }
+  fs.closeSync(fd);
+  return () => {
+    if (fs.existsSync(safeTarget(projectDir, LOCK)) && JSON.parse(fs.readFileSync(target, 'utf8')).id === id) fs.unlinkSync(target);
+  };
+}
+
+function atomicWrite(projectDir, file, content) {
+  const target = safeTarget(projectDir, file);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const temporaryFile = file + '.update-' + crypto.randomUUID() + '.tmp';
+  const temporary = safeTarget(projectDir, temporaryFile);
+  try {
+    fs.writeFileSync(temporary, content, { flag: 'wx' });
+    safeTarget(projectDir, file);
+    fs.renameSync(temporary, target);
+  } finally {
+    if (fs.existsSync(safeTarget(projectDir, temporaryFile))) fs.unlinkSync(temporary);
+  }
+}
+
+function rollback(projectDir, receipt) {
+  const failures = [];
+  // Restore the manifest last, after restoring the content it describes.
+  const entries = [...receipt.entries.filter(entry => entry.file !== MANIFEST).reverse(),
+    ...receipt.entries.filter(entry => entry.file === MANIFEST)];
+  for (const entry of entries) {
+    try {
+      const current = currentHash(projectDir, entry.file);
+      if (current === entry.beforeHash) continue;
+      if (current !== entry.afterHash && current !== null) throw new Error('File changed since the update; retained');
+      if (entry.beforeHash === null) {
+        if (current !== null) fs.unlinkSync(safeTarget(projectDir, entry.file));
+      } else {
+        if (entry.file === MANIFEST && failures.length) throw new Error('Content recovery is incomplete; manifest retained');
+        const backup = currentBytes(projectDir, entry.backup);
+        if (!backup || fileHash(backup) !== entry.beforeHash) throw new Error('Backup is missing or does not match its recorded hash');
+        atomicWrite(projectDir, entry.file, backup);
+      }
+    } catch (error) { failures.push({ file: entry.file, reason: error.message }); }
+  }
+  return failures;
+}
+
+function applyPlan(plan, { reauthorize } = {}) {
+  const { projectDir } = plan;
+  const id = crypto.randomUUID();
+  const release = acquireProjectLock(projectDir, { receiptId: id });
+  const receiptFile = '.bmad/updates/' + id + '/receipt.json';
+  let receipt;
+  try {
+    if (plan.auto) {
+      if (typeof reauthorize !== 'function') throw new Error('Automatic update requires policy reauthorization under the project lock.');
+      reauthorize();
+    }
+    for (const [file, hash] of plan.observed) {
+      if (currentHash(projectDir, file) !== hash) throw new Error('File changed after preflight: ' + file);
+    }
+    receipt = { schemaVersion: 1, id, status: 'prepared', fromVersion: plan.fromVersion, toVersion: plan.toVersion,
+      createdAt: new Date().toISOString(), conflicts: plan.conflicts, entries: [] };
+    for (const [index, entry] of plan.files.entries()) {
+      let backup = null;
+      if (entry.beforeHash !== null) {
+        backup = '.bmad/updates/' + id + '/backups/' + index;
+        const target = safeTarget(projectDir, backup);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.copyFileSync(safeTarget(projectDir, entry.file), target, fs.constants.COPYFILE_EXCL);
+        if (fileHash(fs.readFileSync(target)) !== entry.beforeHash) throw new Error('File changed while backing up: ' + entry.file);
+      }
+      if (entry.backupLegacy) {
+        let legacyBackup = entry.file + '.bak';
+        let index = 1;
+        while (fs.existsSync(safeTarget(projectDir, legacyBackup))) legacyBackup = entry.file + '.bak.' + index++;
+        fs.copyFileSync(safeTarget(projectDir, entry.file), safeTarget(projectDir, legacyBackup), fs.constants.COPYFILE_EXCL);
+      }
+      receipt.entries.push({ file: entry.file, beforeHash: entry.beforeHash, afterHash: entry.afterHash, backup });
+    }
+    atomicWrite(projectDir, receiptFile, JSON.stringify(receipt, null, 2));
+    for (const entry of plan.files) {
+      if (currentHash(projectDir, entry.file) !== entry.beforeHash) throw new Error('File changed during update: ' + entry.file);
+      atomicWrite(projectDir, entry.file, entry.content);
+      if (currentHash(projectDir, entry.file) !== entry.afterHash) throw new Error('Written file verification failed: ' + entry.file);
+    }
+    receipt.status = 'committed';
+    atomicWrite(projectDir, receiptFile, JSON.stringify(receipt, null, 2));
+    const manifest = readInstallManifest(safeTarget(projectDir, MANIFEST));
+    return { manifest, receiptPath: path.join(projectDir, receiptFile), receiptId: id,
+      changedFiles: plan.files.filter(entry => entry.kind !== 'manifest').map(entry => entry.file), conflicts: plan.conflicts };
+  } catch (error) {
+    if (receipt) {
+      const failures = rollback(projectDir, receipt);
+      receipt.status = failures.length ? 'recovery-required' : 'rolled-back';
+      receipt.failures = failures;
+      try { atomicWrite(projectDir, receiptFile, JSON.stringify(receipt, null, 2)); } catch (writeError) {
+        error.message += '; recovery receipt could not be saved: ' + writeError.message;
+      }
+      error.message += '; ' + receipt.status + '. Recovery: bmad-plus update --restore ' + id + ' --directory "' + projectDir + '" --yes';
+    }
+    throw error;
+  } finally { release(); }
+}
+
+function restoreUpdate({ projectDir, receiptId }) {
+  if (!/^[a-f0-9-]{36}$/.test(receiptId)) throw new Error('Invalid update receipt ID');
+  const receiptFile = '.bmad/updates/' + receiptId + '/receipt.json';
+  const receipt = JSON.parse(currentBytes(projectDir, receiptFile)?.toString('utf8') || 'null');
+  if (!receipt || receipt.schemaVersion !== 1 || receipt.id !== receiptId || !Array.isArray(receipt.entries)) throw new Error('Invalid update receipt');
+  const adapterPaths = new Set([DERIVED.targets.spine, ...DERIVED.targets.adapters.map(entry => entry.file)]);
+  for (const entry of receipt.entries) {
+    if (typeof entry.file !== 'string' || !(entry.file === MANIFEST || isManagedFile(entry.file) || adapterPaths.has(entry.file)) ||
+        !/^[a-f0-9]{64}$/.test(entry.afterHash) || (entry.beforeHash !== null && !/^[a-f0-9]{64}$/.test(entry.beforeHash))) throw new Error('Invalid recovery file entry');
+    safeTarget(projectDir, entry.file);
+    if (entry.beforeHash === null ? entry.backup !== null :
+      typeof entry.backup !== 'string' || !entry.backup.startsWith('.bmad/updates/' + receiptId + '/backups/') ||
+      path.posix.normalize(entry.backup) !== entry.backup || entry.backup.includes('\\')) throw new Error('Invalid backup entry');
+    if (entry.backup) safeTarget(projectDir, entry.backup);
+  }
+  const manifestEntry = receipt.entries.find(entry => entry.file === MANIFEST);
+  const installedHash = currentHash(projectDir, MANIFEST);
+  if (!manifestEntry || (installedHash !== manifestEntry.beforeHash && installedHash !== manifestEntry.afterHash)) throw new Error('Installation changed since this receipt; recovery refused.');
+  const lockPath = safeTarget(projectDir, LOCK);
+  if (fs.existsSync(lockPath)) {
+    const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    if (lock.receiptId !== receiptId || !Number.isInteger(lock.pid) || lock.pid <= 0) throw new Error('Another update owns the project lock.');
+    try {
+      process.kill(lock.pid, 0);
+      throw new Error('The recorded update process is still running.');
+    } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+    fs.unlinkSync(lockPath);
+  }
+  const release = acquireProjectLock(projectDir);
+  try {
+    // Validate every required byte before starting a manual recovery.
+    for (const entry of receipt.entries) {
+      const current = currentHash(projectDir, entry.file);
+      if (current !== entry.beforeHash && current !== entry.afterHash && current !== null) throw new Error('File changed since the update: ' + entry.file);
+      if (entry.beforeHash !== null) {
+        const backup = currentBytes(projectDir, entry.backup);
+        if (backup === null || fileHash(backup) !== entry.beforeHash) throw new Error('Backup is missing or corrupt: ' + entry.file);
+      }
+    }
+    const failures = rollback(projectDir, receipt);
+    receipt.status = failures.length ? 'recovery-required' : 'restored';
+    receipt.failures = failures;
+    atomicWrite(projectDir, receiptFile, JSON.stringify(receipt, null, 2));
+    if (failures.length) throw new Error('Recovery incomplete: ' + failures.map(entry => entry.file + ': ' + entry.reason).join('; '));
+    return { receiptPath: path.join(projectDir, receiptFile), restoredVersion: readInstallManifest(safeTarget(projectDir, MANIFEST)).version };
+  } finally { release(); }
+}
+
+module.exports = { planUpdate, applyPlan, restoreUpdate, acquireProjectLock, evaluateUpdateReadiness,
+  collectManagedFiles, inventoryOf, MANIFEST, LOCK };