bmad-plus 0.12.2 → 0.14.0

package/tools/cli/lib/installation-health.js

@@ -0,0 +1,360 @@
+/** Read-only by default; optional Python import probes never provision or repair. */
+const fs = require('node:fs');
+const path = require('node:path');
+const semver = require('semver');
+const { DERIVED } = require('./packs');
+const { readInstallManifest } = require('./install-manifest');
+const { inventoryOf, collectManagedFiles, MANIFEST } = require('./update-transaction');
+const { fileHash } = require('./pack-copy');
+const { contentHash } = require('./installed-adapters');
+const {
+  safeTarget,
+  GENERATED_MARKER,
+  USER_CONFIG_MARKER,
+} = require('../../build/generate-adapters');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../../..');
+
+function inspectFile(root, file) {
+  try {
+    return { state: 'present', bytes: fs.readFileSync(safeTarget(root, file)) };
+  } catch (error) {
+    return { state: error.code === 'ENOENT' ? 'missing' : 'unreadable' };
+  }
+}
+
+function collectInstallationHealth({
+  projectDir = process.cwd(),
+  packageRoot = PACKAGE_ROOT,
+  cliVersion = require('../../../package.json').version,
+  nodeVersion = process.versions.node,
+  verifyPython = false,
+  pythonRunner,
+} = {}) {
+  projectDir = path.resolve(projectDir);
+  const report = {
+    schemaVersion: 1,
+    projectDir,
+    status: 'ok',
+    versions: { installed: null, cli: cliVersion, published: null },
+    inventory: { status: 'unknown', trackedFiles: 0 },
+    packs: [],
+    integrations: [],
+    runtimes: [],
+    checks: [],
+    summary: { passed: 0, warnings: 0, errors: 0 },
+  };
+  function check(code, status, message, extra = {}) {
+    report.checks.push({ code, status, message, ...extra });
+  }
+  function finish() {
+    for (const entry of report.checks) {
+      report.summary[
+        entry.status === 'pass' ? 'passed' : entry.status === 'warning' ? 'warnings' : 'errors'
+      ]++;
+    }
+    report.status = report.summary.errors ? 'error' : report.summary.warnings ? 'warning' : 'ok';
+    return report;
+  }
+
+  const manifestFile = inspectFile(projectDir, MANIFEST);
+  if (manifestFile.state !== 'present') {
+    check(
+      manifestFile.state === 'missing' ? 'installation.missing' : 'manifest.unreadable',
+      'error',
+      manifestFile.state === 'missing'
+        ? 'BMAD+ is not installed in this directory.'
+        : 'Installation manifest cannot be read safely.',
+      { path: MANIFEST }
+    );
+    return finish();
+  }
+  let manifest;
+  try {
+    manifest = readInstallManifest(safeTarget(projectDir, MANIFEST));
+  } catch (error) {
+    check('manifest.invalid', 'error', 'Invalid installation manifest: ' + error.message, {
+      path: MANIFEST,
+    });
+    return finish();
+  }
+  report.versions.installed = manifest.version;
+  check('manifest.valid', 'pass', 'Manifest found: v' + manifest.version);
+  check(
+    'version.cli',
+    manifest.version === cliVersion ? 'pass' : 'warning',
+    manifest.version === cliVersion
+      ? 'Installed and executing CLI versions match.'
+      : 'Version mismatch: installed v' + manifest.version + ', executing CLI v' + cliVersion + '.'
+  );
+
+  const selectedPacks = [...new Set(manifest.packs)];
+  const validPacks = selectedPacks.filter((id) => Object.hasOwn(DERIVED.packs, id));
+  for (const id of selectedPacks) {
+    if (!validPacks.includes(id))
+      check('pack.unknown', 'error', 'Unknown installed pack: ' + id, { pack: id });
+  }
+  if (!selectedPacks.includes('core'))
+    check('pack.core-missing', 'error', 'The required Core pack is not selected.');
+
+  if (selectedPacks.includes('dev-studio')) {
+    try {
+      const studio = require('./studio');
+      const resolved = studio.validatePack(studio.installedPack(projectDir));
+      studio.resolveConfig(projectDir);
+      check(
+        'studio.resources',
+        'pass',
+        `Dev Studio: ${resolved.catalog.workflows.length} routes and ${resolved.resources.length} resources resolved; host execution is not verified.`
+      );
+    } catch (error) {
+      check(
+        'studio.resources',
+        'error',
+        'Dev Studio cannot prepare its workflows: ' + error.message,
+        { path: '.agents/skills/pack-dev-studio' }
+      );
+    }
+  }
+
+  const inventory = inventoryOf(manifest);
+  const validInventory =
+    inventory &&
+    Object.values(inventory).every((hash) => typeof hash === 'string') &&
+    typeof manifest.fileInventory.complete === 'boolean';
+  report.inventory.status =
+    manifest.fileInventory === undefined
+      ? 'legacy'
+      : !validInventory
+        ? 'invalid'
+        : manifest.fileInventory.complete
+          ? 'complete'
+          : 'incomplete';
+  const owned = validInventory ? inventory : {};
+  report.inventory.trackedFiles = Object.keys(owned).length;
+
+  const expectedFiles = new Set(['_bmad/module.yaml', '_bmad/module-help.csv']);
+  for (const id of validPacks) {
+    const pack = DERIVED.packs[id];
+    report.packs.push({ id, runtimes: pack.runtimes, requiredResources: pack.requiredResources });
+    for (const file of pack.requiredResources) expectedFiles.add(file);
+  }
+  // Check delivery against the executing package, even if a manifest omits a file.
+  try {
+    for (const { file } of collectManagedFiles({ projectDir, packageRoot, packs: validPacks }))
+      expectedFiles.add(file);
+  } catch (error) {
+    check('package.unreadable', 'error', 'Cannot inspect the executing package: ' + error.message);
+  }
+  const resources = new Set([...expectedFiles, ...Object.keys(owned)]);
+  for (const file of [...resources].sort()) {
+    if (!Object.hasOwn(owned, file) && report.inventory.status === 'complete')
+      report.inventory.status = 'incomplete';
+    const observed = inspectFile(projectDir, file);
+    if (observed.state !== 'present') {
+      check(
+        'file.' + observed.state,
+        'error',
+        observed.state === 'missing'
+          ? 'Missing required file: ' + file
+          : 'File cannot be read safely: ' + file,
+        { path: file }
+      );
+    } else if (Object.hasOwn(owned, file)) {
+      const unchanged = fileHash(observed.bytes) === owned[file];
+      check(
+        unchanged ? 'file.unchanged' : 'file.modified',
+        unchanged ? 'pass' : 'warning',
+        unchanged
+          ? 'Managed file unchanged.'
+          : 'Managed file modified locally; review before updating.',
+        { path: file }
+      );
+    } else {
+      check('file.unowned', 'warning', 'File present without a recorded ownership hash.', {
+        path: file,
+      });
+    }
+  }
+  if (manifest.fileInventory?.complete && report.inventory.status === 'incomplete') {
+    check(
+      'inventory.omissions',
+      'warning',
+      'Inventory claims completeness but omits expected files.'
+    );
+  }
+  check(
+    'inventory.' + report.inventory.status,
+    report.inventory.status === 'complete'
+      ? 'pass'
+      : report.inventory.status === 'invalid'
+        ? 'error'
+        : 'warning',
+    'File ownership inventory: ' + report.inventory.status + '.'
+  );
+  const config = inspectFile(projectDir, '_bmad/config.yaml');
+  check(
+    'config.' + config.state,
+    config.state === 'present' ? 'pass' : 'error',
+    config.state === 'present'
+      ? 'Project configuration present.'
+      : 'Project configuration missing or unreadable.',
+    { path: '_bmad/config.yaml' }
+  );
+
+  const contract = DERIVED.diagnostics;
+  const declaredTools = Object.keys(contract.integrations);
+  let selectedTools = [];
+  if (manifest.ides === undefined) {
+    selectedTools = declaredTools.filter(
+      (tool) =>
+        inspectFile(projectDir, contract.integrations[tool].instructionFile).state !== 'missing'
+    );
+    check(
+      'integrations.legacy',
+      'warning',
+      'IDE selection was not recorded; existing adapter paths were inspected.'
+    );
+  } else if (
+    !Array.isArray(manifest.ides) ||
+    manifest.ides.some((id) => typeof id !== 'string' || !declaredTools.includes(id))
+  ) {
+    check(
+      'integrations.invalid',
+      'error',
+      'Manifest IDE selection contains invalid or unknown targets.'
+    );
+  } else selectedTools = [...new Set(manifest.ides)];
+
+  const adapterPaths =
+    selectedTools.length || manifest.ides === undefined
+      ? [
+          ...new Set([
+            DERIVED.targets.spine,
+            ...selectedTools.map((tool) => contract.integrations[tool].instructionFile),
+          ]),
+        ]
+      : [];
+  const ownership = new Map();
+  const hashes = manifest.adapterHashes;
+  const validHashes =
+    hashes === undefined ||
+    (hashes &&
+      typeof hashes === 'object' &&
+      !Array.isArray(hashes) &&
+      Object.entries(hashes).every(
+        ([file, hash]) =>
+          [DERIVED.targets.spine, ...DERIVED.targets.adapters.map((entry) => entry.file)].includes(
+            file
+          ) &&
+          typeof hash === 'string' &&
+          /^[a-f0-9]{64}$/.test(hash)
+      ));
+  if (!validHashes) check('adapters.invalid', 'error', 'Adapter ownership hashes are invalid.');
+  for (const file of adapterPaths) {
+    const observed = inspectFile(projectDir, file);
+    let state = observed.state;
+    if (state === 'present') {
+      const text = observed.bytes.toString('utf8');
+      const previous = validHashes && hashes && Object.hasOwn(hashes, file) ? hashes[file] : null;
+      state =
+        text.includes(GENERATED_MARKER) && !text.includes(USER_CONFIG_MARKER)
+          ? 'adopted'
+          : !previous || !text.includes(USER_CONFIG_MARKER)
+            ? 'unowned'
+            : contentHash(text) === previous
+              ? 'unchanged'
+              : 'modified';
+    }
+    ownership.set(file, state);
+    check(
+      'adapter.' + state,
+      ['missing', 'unreadable'].includes(state)
+        ? 'error'
+        : state === 'unchanged'
+          ? 'pass'
+          : 'warning',
+      'Instruction file: ' + state + '.',
+      { path: file }
+    );
+  }
+  report.integrations = selectedTools.map((tool) => ({
+    tool,
+    ...contract.integrations[tool],
+    ownership: ownership.get(contract.integrations[tool].instructionFile),
+    hostVerified: false,
+  }));
+
+  const nodeMinimum = contract.runtimeMinimums.node;
+  const nodeReady = Boolean(semver.valid(nodeVersion) && semver.gte(nodeVersion, nodeMinimum));
+  report.runtimes.push({
+    runtime: 'node',
+    minimum: nodeMinimum,
+    version: nodeVersion,
+    status: nodeReady ? 'verified' : 'unsupported',
+  });
+  check(
+    'runtime.node',
+    nodeReady ? 'pass' : 'error',
+    'Executing Node.js ' + nodeVersion + '; minimum ' + nodeMinimum + '.'
+  );
+  for (const id of validPacks.filter((pack) => DERIVED.packs[pack].runtimes.includes('python'))) {
+    const requirements = DERIVED.pythonPacks[id].requirements.join('/');
+    const delivery = inspectFile(packageRoot, requirements).state;
+    const environmentFile = '.bmad/venv/' + id + '/pyvenv.cfg';
+    const environment = inspectFile(projectDir, environmentFile).state;
+    const runtime = {
+      runtime: 'python',
+      pack: id,
+      minimum: contract.runtimeMinimums.python,
+      requirements,
+      packageRequirements: delivery,
+      environment,
+      imports: 'not-verified',
+    };
+    report.runtimes.push(runtime);
+    check(
+      'runtime.requirements',
+      delivery === 'present' ? 'pass' : 'error',
+      delivery === 'present'
+        ? 'Python requirements are available in the executing package.'
+        : 'Python requirements are missing or unreadable in the executing package.',
+      { pack: id, path: requirements, scope: 'package' }
+    );
+    if (verifyPython) {
+      const { probePythonRuntime } = require('./python-health');
+      const probe = probePythonRuntime({
+        projectDir,
+        packId: id,
+        minimum: contract.runtimeMinimums.python,
+        verifyModules: DERIVED.pythonPacks[id].verifyModules,
+        runner: pythonRunner,
+      });
+      Object.assign(runtime, probe);
+      check(
+        'runtime.python-probe',
+        probe.status === 'verified' ? 'pass' : 'warning',
+        probe.message +
+          (probe.status === 'verified'
+            ? ''
+            : ' Use bmad-plus install --provision-python to provision selected Python packs.'),
+        {
+          pack: id,
+          path: environmentFile,
+        }
+      );
+    } else {
+      check(
+        'runtime.python-unverified',
+        'warning',
+        'Python environment ' +
+          environment +
+          '; interpreter version and imports have not been executed. Use doctor --verify-python to probe them.',
+        { pack: id, path: environmentFile }
+      );
+    }
+  }
+  return finish();
+}
+
+module.exports = { collectInstallationHealth };

package/tools/cli/lib/installed-adapters.js

@@ -0,0 +1,89 @@
+/** Installed adapter ownership shared by install, update, and uninstall. */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const clack = require('@clack/prompts');
+const { GENERATED_MARKER, USER_CONFIG_MARKER } = require('../../build/generate-adapters');
+
+const INSTALLER_MARKER = 'BMAD+ \u2014 AI Agent Configuration';
+const contentHash = content => crypto.createHash('sha256').update(String(content).replace(/\r\n/g, '\n')).digest('hex');
+
+function classifyAdapter({ existing, content, previousHash, update = false, yes = false }) {
+  if (existing === undefined) return { action: 'write', backup: false };
+  const installed = existing.includes(USER_CONFIG_MARKER);
+  const adopted = existing.includes(GENERATED_MARKER) && !installed;
+  const legacy = existing.includes(INSTALLER_MARKER) && !existing.includes(GENERATED_MARKER);
+  if (installed && existing === content) return { action: 'same', backup: false };
+  const unchanged = installed && previousHash === contentHash(existing);
+  if (adopted || (installed && !unchanged) || (!installed && !legacy && (update || !yes))) {
+    return { action: 'preserve', backup: false, adopted, installed, reason: adopted ? 'repository-adopted' : 'local-instructions' };
+  }
+  return { action: 'write', backup: legacy || (!installed && yes), legacy };
+}
+
+// Refuse redirected parent directories as well as linked destination files.
+function safeAdapterPath(projectDir, file) {
+  const root = path.resolve(projectDir);
+  const target = path.resolve(root, file);
+  const relative = path.relative(root, target);
+  if (!relative || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new Error('Adapter path outside project: ' + file);
+  }
+  let current = root;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) throw new Error('Adapter path is a symbolic link or junction: ' + current);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }
+  return target;
+}
+
+function writeIDEConfigs({ projectDir, files, yes = false, update = false, adapterHashes = {} }) {
+  const outcome = { written: [], skipped: [], backedUp: [], adapterHashes: {} };
+  // Preflight the complete set before writing any adapter.
+  for (const { file } of files) safeAdapterPath(projectDir, file);
+  for (const { file, content } of files) {
+    const target = safeAdapterPath(projectDir, file);
+    const previousHash = Object.hasOwn(adapterHashes, file) ? adapterHashes[file] : undefined;
+    let backup = false;
+    if (fs.existsSync(target)) {
+      const existing = fs.readFileSync(target, 'utf8');
+      const decision = classifyAdapter({ existing, content, previousHash, update, yes });
+      if (decision.action === 'same') {
+        outcome.adapterHashes[file] = contentHash(content);
+        continue;
+      }
+      if (decision.action === 'preserve') {
+        if (previousHash && decision.installed) outcome.adapterHashes[file] = previousHash;
+        outcome.skipped.push(file);
+        const compare = decision.adopted
+          ? ` Compare package defaults: node "${require.resolve('../../build/generate-adapters')}" --target "${path.resolve(projectDir)}" --check`
+          : '';
+        clack.log.warn(`${file}: existing project instructions preserved.${compare}`);
+        continue;
+      }
+      // Older installers did not record hashes. Keep their exact bytes before
+      // migration, including any local additions that cannot be distinguished.
+      backup = decision.backup;
+    }
+    if (backup) {
+      let suffix = '.bak';
+      let index = 1;
+      while (fs.existsSync(safeAdapterPath(projectDir, file + suffix))) suffix = `.bak.${index++}`;
+      fs.copyFileSync(target, safeAdapterPath(projectDir, file + suffix), fs.constants.COPYFILE_EXCL);
+      outcome.backedUp.push(file);
+      clack.log.warn(`${file}: backed up to ${file + suffix} before refreshing.`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    safeAdapterPath(projectDir, file);
+    fs.writeFileSync(target, content, 'utf8');
+    outcome.written.push(file);
+    outcome.adapterHashes[file] = contentHash(content);
+  }
+  return outcome;
+}
+
+module.exports = { INSTALLER_MARKER, contentHash, safeAdapterPath, writeIDEConfigs, classifyAdapter };

package/tools/cli/lib/npm-runner.js

@@ -0,0 +1,177 @@
+/** Run npm through Node with bounded output and no shell interpolation. */
+const fs = require('node:fs');
+const path = require('node:path');
+const childProcess = require('node:child_process');
+
+function resolveNpmCli({
+  env = process.env,
+  execPath = process.execPath,
+  platform = process.platform,
+  realpath = fs.realpathSync,
+  isFile = (file) => fs.statSync(file).isFile(),
+} = {}) {
+  const paths = platform === 'win32' ? path.win32 : path.posix;
+  const searchPath = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] || '';
+  const directories = searchPath.split(platform === 'win32' ? ';' : ':').filter(Boolean);
+  const nodeDir = paths.dirname(execPath);
+  const candidates = [
+    env.npm_execpath,
+    paths.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    paths.resolve(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ...directories.flatMap((dir) => [
+      paths.join(dir, 'npm'),
+      paths.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ]),
+  ];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try {
+      const resolved = realpath(candidate);
+      if (paths.basename(resolved).toLowerCase() === 'npm-cli.js' && isFile(resolved))
+        return resolved;
+    } catch {
+      /* Try the next standard npm installation location. */
+    }
+  }
+  throw new Error('npm-cli.js was not found. Install Node.js with npm or repair its PATH.');
+}
+
+/** Injectable process boundary; tests never need to fetch a package. */
+function createNpmRunner({
+  spawn = childProcess.spawn,
+  resolveCli = resolveNpmCli,
+  platform = process.platform,
+  execPath = process.execPath,
+  kill = process.kill.bind(process),
+} = {}) {
+  return async function runNpm(
+    args,
+    { cwd, timeout = 6000, env = process.env, maxBuffer = 1024 * 1024, signal } = {}
+  ) {
+    if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string' || arg.includes('\0'))) {
+      throw new Error('npm arguments must be an array of strings without NUL bytes.');
+    }
+    if (
+      !Number.isSafeInteger(timeout) ||
+      timeout <= 0 ||
+      !Number.isSafeInteger(maxBuffer) ||
+      maxBuffer <= 0
+    ) {
+      throw new Error('npm timeout and maxBuffer must be positive integers.');
+    }
+    if (signal?.aborted)
+      throw Object.assign(new Error('npm operation was cancelled.'), { code: 'ABORT_ERR' });
+    const cli = resolveCli({ env, execPath, platform });
+
+    return new Promise((resolve, reject) => {
+      let child;
+      try {
+        child = spawn(execPath, [cli, ...args], {
+          cwd,
+          env,
+          shell: false,
+          windowsHide: true,
+          detached: platform !== 'win32',
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+      } catch (error) {
+        reject(new Error('Could not start npm.', { cause: error }));
+        return;
+      }
+      let settled = false;
+      let bytes = 0;
+      const stdout = [];
+      const stderr = [];
+      let timer;
+      const finish = (error, output) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        if (error) {
+          error.stdout = Buffer.concat(stdout).toString('utf8');
+          error.stderr = Buffer.concat(stderr).toString('utf8');
+          const diagnostic = [error.stdout.trim(), error.stderr.trim()].filter(Boolean).join('\n');
+          if (diagnostic) error.message += '\n' + diagnostic;
+          reject(error);
+        } else resolve(output);
+      };
+      const killChild = () => {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* The process may already have exited. */
+        }
+      };
+      const stop = () => {
+        if (!Number.isInteger(child.pid) || child.pid <= 0) return killChild();
+        if (platform !== 'win32') {
+          // A detached npm owns this process group, including its updater child.
+          try {
+            kill(-child.pid, 'SIGKILL');
+          } catch {
+            killChild();
+          }
+          return;
+        }
+        try {
+          const terminator = spawn('taskkill.exe', ['/pid', String(child.pid), '/t', '/f'], {
+            shell: false,
+            windowsHide: true,
+            stdio: 'ignore',
+            env,
+          });
+          terminator.once('error', killChild);
+          terminator.once('close', (code) => {
+            if (code !== 0) killChild();
+          });
+        } catch {
+          killChild();
+        }
+      };
+      const cancel = (message, code) => {
+        if (settled) return;
+        stop();
+        finish(Object.assign(new Error(message), { code }));
+      };
+      const abort = () =>
+        cancel('npm operation was cancelled; child termination requested.', 'ABORT_ERR');
+      const collect = (chunk, save) => {
+        if (settled) return;
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > maxBuffer)
+          return cancel('npm output exceeded the configured buffer limit.', 'ENOBUFS');
+        (save ? stdout : stderr).push(buffer);
+      };
+      child.stdout.on('data', (chunk) => collect(chunk, true));
+      child.stderr.on('data', (chunk) => collect(chunk, false));
+      child.once('error', (error) => finish(new Error('Could not run npm.', { cause: error })));
+      child.once('close', (code, exitSignal) => {
+        if (code !== 0 || exitSignal) {
+          finish(
+            Object.assign(new Error(`npm exited unsuccessfully (${exitSignal || code}).`), {
+              code: 'NPM_EXIT',
+              exitCode: code,
+              signal: exitSignal,
+            })
+          );
+        } else finish(null, Buffer.concat(stdout).toString('utf8'));
+      });
+      timer = setTimeout(
+        () =>
+          cancel(
+            `npm exceeded its ${timeout} ms deadline; child termination requested.`,
+            'ETIMEDOUT'
+          ),
+        timeout
+      );
+      timer.unref?.();
+      signal?.addEventListener('abort', abort, { once: true });
+      if (signal?.aborted) abort();
+    });
+  };
+}
+
+const runNpm = createNpmRunner();
+module.exports = { runNpm, resolveNpmCli, createNpmRunner };