bmad-plus 0.12.2 → 0.13.0

package/tools/cli/lib/ide-config.js

@@ -1,267 +1,10 @@
 /**
- * BMAD+ IDE Configuration Generator
- * Extracted from install.js for modularity.
- * Generates CLAUDE.md, GEMINI.md, AGENTS.md content with pack-aware agent filtering.
- *
+ * Compatibility entry for IDE metadata. Rendering lives in the registry generator.
  * Author: Laurent Rochetta
  */
-
-// ── IDE Configurations ──
-
-const IDE_CONFIGS = {
-  'claude-code': {
-    name: 'Claude Code',
-    detect: ['.claude'],
-    configFile: 'CLAUDE.md',
-  },
-  'gemini-cli': {
-    name: 'Gemini CLI',
-    detect: ['.gemini'],
-    configFile: 'GEMINI.md',
-  },
-  'codex-cli': {
-    name: 'Codex CLI / OpenCode',
-    detect: ['.codex', '.opencode'],
-    configFile: 'AGENTS.md',
-  },
-  'antigravity': {
-    name: 'Antigravity',
-    detect: ['.gemini/antigravity'],
-    configFile: 'GEMINI.md',
-  },
-};
-
-// Shield ships 27 compliance agents (registry.yaml `shield.categories`) AND 11
-// workflows (`shield.workflows`) — two separate dimensions that must never be
-// summed into a single "agents" figure. Summing them is what produced the retired
-// "38" over-count that shipped into every generated user config. Declared once so
-// the two call sites below cannot drift apart; gated by tools/build/check-counts.js.
-const SHIELD_AGENT_LINE =
-  '- **Shield** (GRC) — 27 compliance agents + 11 workflows (GDPR, ISO 27001, SOC 2, HIPAA, EU AI Act, DORA, NIS2...)';
-
-// All 14 BMAD+ agents — always included in templates
-const AGENT_LIST = [
-  '- **Atlas** (Strategist) — Business analysis + Product management',
-  '- **Forge** (Architect-Dev) — Architecture + Development + Documentation',
-  '- **Sentinel** (Quality) — QA + UX review',
-  '- **Nexus** (Orchestrator) — Sprint management + Autopilot + Parallel execution',
-  '- **Shadow** (OSINT) — Investigation + Scraping + Psychoprofiling',
-  SHIELD_AGENT_LINE,
-  '- **Miriam** (מרים) — Business Analyst — Strategic analysis, research, product briefs',
-  '- **Huldah** (חולדה) — Technical Writer — Documentation, diagrams, editorial review',
-  '- **Yosef** (יוסף) — Product Manager — PRD, requirements, feature prioritization',
-  '- **Rachel** (רחל) — UX Designer — User experience, wireframes, empathy mapping',
-  '- **Bezalel** (בצלאל) — System Architect — Architecture, ADRs, epics & stories',
-  '- **Oholiab** (אהליאב) — Senior Engineer — TDD, sprint, code review, implementation',
-  '- **Zecher** (זכר) — Memory Archivist — Consolidation, project scanning, context recall',
-  '- **Maker** (Creator) — Custom agent builder — Create new agents from description',
-];
-
-/**
- * Filter agents based on installed packs.
- * Core agents are always included; others depend on pack selection.
- *
- * @param {string[]} packs - List of installed pack IDs
- * @returns {string[]} Agent description lines
- */
-function getAgentsByPacks(packs) {
-  const agents = [
-    '- **Atlas** (Strategist) — Business analysis + Product management',
-    '- **Forge** (Architect-Dev) — Architecture + Development + Documentation',
-    '- **Sentinel** (Quality) — QA + UX review',
-    '- **Nexus** (Orchestrator) — Sprint management + Autopilot + Parallel execution',
-  ];
-
-  if (packs.includes('osint')) {
-    agents.push('- **Shadow** (OSINT) — Investigation + Scraping + Psychoprofiling');
-  }
-
-  if (packs.includes('shield')) {
-    agents.push(SHIELD_AGENT_LINE);
-  }
-
-  if (packs.includes('maker')) {
-    agents.push('- **Maker** (Creator) — Custom agent builder — Create new agents from description');
-  }
-
-  if (packs.includes('dev-studio')) {
-    agents.push('- **Miriam** (מרים) — Business Analyst — Strategic analysis, research, product briefs');
-    agents.push('- **Huldah** (חולדה) — Technical Writer — Documentation, diagrams, editorial review');
-    agents.push('- **Yosef** (יוסף) — Product Manager — PRD, requirements, feature prioritization');
-    agents.push('- **Rachel** (רחל) — UX Designer — User experience, wireframes, empathy mapping');
-    agents.push('- **Bezalel** (בצלאל) — System Architecture — Architecture, ADRs, epics & stories');
-    agents.push('- **Oholiab** (אהליאב) — Senior Engineer — TDD, sprint, code review, implementation');
-  }
-
-  if (packs.includes('memory')) {
-    agents.push('- **Zecher** (זכר) — Memory Archivist — Consolidation, project scanning, context recall');
-  }
-
-  return agents;
-}
-
-/**
- * Build the Memory Protocol section if the memory pack is installed.
- *
- * @param {string[]} packs - List of installed pack IDs
- * @returns {string} Memory section markdown (empty string if no memory pack)
- */
-function getMemorySection(packs) {
-  if (!packs.includes('memory')) return '';
-  return [
-    '',
-    '## Memory Protocol (Karpathy Guardrails)',
-    '',
-    'Agents MUST follow these behavioral principles:',
-    '',
-    '### G1 — Think Before Coding',
-    '- State assumptions explicitly. If uncertain, ask.',
-    '- Check `.agents/memory/decisions.md` for prior decisions before re-deciding.',
-    '',
-    '### G2 — Simplicity First',
-    '- Minimum code that solves the problem. Nothing speculative.',
-    '- Check `.agents/memory/patterns.md` for existing solutions.',
-    '',
-    '### G3 — Surgical Changes',
-    '- Touch only what you must. Match existing style.',
-    '- Log surprises in `.agents/memory/lessons.md`.',
-    '',
-    '### G4 — Goal-Driven Execution',
-    '- Define success criteria before implementing.',
-    '- Log non-obvious decisions in `.agents/memory/decisions.md`.',
-    '',
-    '### Memory Files',
-    '- `.agents/memory/decisions.md` — Read at session start, write when making decisions',
-    '- `.agents/memory/lessons.md` — Write when something unexpected happens',
-    '- `.agents/memory/patterns.md` — Write when a reusable pattern is validated',
-    '- `.agents/memory/context.md` — Update at session end with project state',
-  ].join('\n');
-}
-
-/**
- * Generate IDE config content with pack-aware agent filtering.
- *
- * @param {string} userName - The user's display name
- * @param {string} language - User-facing communication language
- * @param {string[]} packs - List of installed pack IDs
- * @returns {string} Complete Markdown template
- */
-function generateIDEConfig(userName, language, packs) {
-  const agents = getAgentsByPacks(packs);
-  const memorySection = getMemorySection(packs);
-
-  return `# BMAD+ — AI Agent Configuration
-
-## Project Context
-This project uses BMAD+, an augmented AI-driven development framework.
-Based on BMAD-METHOD v6.6.0 with multi-role agents, autopilot mode, and parallel execution.
-
-## Agents
-To activate an agent, say its name or persona:
-${agents.join('\n')}
-
-## Skills
-- Load skills from \`.agents/skills/\`
-- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules
-- Auto-activation triggers: \`.agents/data/role-triggers.yaml\`
-
-## Key Commands
-- \`bmad-help\` — Show all available agents and skills
-- \`autopilot\` — Launch Nexus in full pipeline mode
-- \`parallel\` — Enable parallel multi-agent execution
-
-## Communication
-- User name: ${userName}
-- Default language: ${language} for user-facing content, English for code and technical docs.
-${memorySection}`;
-}
-
-/**
- * Generate a complete CLAUDE.md / GEMINI.md / AGENTS.md config file
- * (all agents, no filtering — backward compatible)
- *
- * @param {string} userName - The user's display name
- * @param {string} language - User-facing communication language
- * @returns {string} Complete Markdown template
- */
-function generateBaseConfig(userName, language) {
-  return `# BMAD+ — AI Agent Configuration
-
-## Project Context
-This project uses BMAD+, an augmented AI-driven development framework.
-Based on BMAD-METHOD v6.6.0 with multi-role agents, autopilot mode, and parallel execution.
-
-## Agents
-To activate an agent, say its name or persona:
-${AGENT_LIST.join('\n')}
-
-## Skills
-- Load skills from \`.agents/skills/\`
-- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules
-- Auto-activation triggers: \`.agents/data/role-triggers.yaml\`
-
-## Key Commands
-- \`bmad-help\` — Show all available agents and skills
-- \`autopilot\` — Launch Nexus in full pipeline mode
-- \`parallel\` — Enable parallel multi-agent execution
-
-## Communication
-- User name: ${userName}
-- Default language: ${language} for user-facing content, English for code and technical docs.
-
-## Memory Protocol (Karpathy Guardrails)
-
-Agents MUST follow these behavioral principles:
-
-### G1 — Think Before Coding
-- State assumptions explicitly. If uncertain, ask.
-- Check \`.agents/memory/decisions.md\` for prior decisions before re-deciding.
-
-### G2 — Simplicity First
-- Minimum code that solves the problem. Nothing speculative.
-- Check \`.agents/memory/patterns.md\` for existing solutions.
-
-### G3 — Surgical Changes
-- Touch only what you must. Match existing style.
-- Log surprises in \`.agents/memory/lessons.md\`.
-
-### G4 — Goal-Driven Execution
-- Define success criteria before implementing.
-- Log non-obvious decisions in \`.agents/memory/decisions.md\`.
-
-### Memory Files
-- \`.agents/memory/decisions.md\` — Read at session start, write when making decisions
-- \`.agents/memory/lessons.md\` — Write when something unexpected happens
-- \`.agents/memory/patterns.md\` — Write when a reusable pattern is validated
-- \`.agents/memory/context.md\` — Update at session end with project state`;
-}
+const adapters = require('../../build/generate-adapters');
 
 module.exports = {
-  IDE_CONFIGS,
-  generateIDEConfig,
-  getAgentsByPacks,
-
-  /**
-   * Generate CLAUDE.md config for Claude Code
-   * @param {string} userName
-   * @param {string} language
-   * @returns {string}
-   */
-  generateClaudeMD: generateBaseConfig,
-
-  /**
-   * Generate GEMINI.md config for Gemini CLI / Antigravity
-   * @param {string} userName
-   * @param {string} language
-   * @returns {string}
-   */
-  generateGeminiMD: generateBaseConfig,
-
-  /**
-   * Generate AGENTS.md config for Codex CLI / OpenCode
-   * @param {string} userName
-   * @param {string} language
-   * @returns {string}
-   */
-  generateAgentsMD: generateBaseConfig,
+  get IDE_CONFIGS() { return adapters.IDE_CONFIGS; },
+  buildIDEConfigs: adapters.buildIDEConfigs,
 };

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

@@ -0,0 +1,17 @@
+/** Read the manifest fields used by maintenance commands without unsafe coercion. */
+const fs = require('node:fs');
+
+function readInstallManifest(manifestPath) {
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest) ||
+      typeof manifest.version !== 'string' || !manifest.version.trim() ||
+      typeof manifest.installed !== 'string' || !Number.isFinite(Date.parse(manifest.installed)) ||
+      !Array.isArray(manifest.packs) || manifest.packs.length === 0 ||
+      manifest.packs.some(pack => typeof pack !== 'string' || !/^[a-z0-9-]+$/.test(pack)) ||
+      (manifest.uiLanguage !== undefined && typeof manifest.uiLanguage !== 'string')) {
+    throw new Error('Expected version, installed date, and a nonempty array of pack IDs.');
+  }
+  return manifest;
+}
+
+module.exports = { readInstallManifest };

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 };