bmad-plus 0.21.0 → 0.23.0

package/tools/cli/lib/control-refs.js

@@ -0,0 +1,132 @@
+/**
+ * Compliance control references: `FRAMEWORK:ID`, e.g. `ISO27001:A.8.28`, `SOC2:CC8.1`,
+ * `GDPR:Art.32(1)(b)`. Framework names are the Shield pack's compliance tags. Each framework
+ * has a closed grammar built from its published numbering, so a mistyped or invented control
+ * is refused instead of travelling into a checklist or an assurance case as if it were real.
+ */
+'use strict';
+
+const range = (prefix, last) => Array.from({ length: last }, (_, i) => `${prefix}${i + 1}`);
+
+/** ISO/IEC 27001:2022 Annex A: themes 5 to 8 and their control counts. */
+const ISO27001 = new Set([
+  ...range('A.5.', 37),
+  ...range('A.6.', 8),
+  ...range('A.7.', 14),
+  ...range('A.8.', 34),
+]);
+
+/** SOC 2 Trust Services Criteria (2017, revised points of focus 2022). */
+const SOC2 = new Set(
+  Object.entries({
+    CC1: 5,
+    CC2: 3,
+    CC3: 4,
+    CC4: 2,
+    CC5: 3,
+    CC6: 8,
+    CC7: 5,
+    CC8: 1,
+    CC9: 2,
+    A1: 3,
+    C1: 2,
+    PI1: 5,
+    P1: 1,
+    P2: 1,
+    P3: 2,
+    P4: 3,
+    P5: 2,
+    P6: 7,
+    P7: 1,
+    P8: 1,
+  }).flatMap(([series, last]) => range(`${series}.`, last))
+);
+
+/** NIST SP 800-53 Rev. 5: control count per family; enhancements are written `AC-2(1)`. */
+const NIST_800_53 = {
+  AC: 25,
+  AT: 6,
+  AU: 16,
+  CA: 9,
+  CM: 14,
+  CP: 13,
+  IA: 13,
+  IR: 10,
+  MA: 7,
+  MP: 8,
+  PE: 23,
+  PL: 11,
+  PM: 32,
+  PS: 9,
+  PT: 8,
+  RA: 10,
+  SA: 23,
+  SC: 51,
+  SI: 23,
+  SR: 12,
+};
+
+/** `Art.N`, optionally a paragraph `(n)` and a point `(x)`, within the act's article count. */
+function article(last) {
+  const form = /^Art\.([1-9]\d{0,2})(?:\(([1-9]\d?)\)(?:\(([a-z])\))?)?$/;
+  return (id) => {
+    const match = form.exec(id);
+    return Boolean(match) && Number(match[1]) <= last;
+  };
+}
+
+const FRAMEWORKS = {
+  ISO27001: { example: 'A.8.28', valid: (id) => ISO27001.has(id) },
+  SOC2: { example: 'CC8.1', valid: (id) => SOC2.has(id) },
+  GDPR: { example: 'Art.32(1)(b)', valid: article(99) },
+  'EU-AI-Act': { example: 'Art.50', valid: article(113) },
+  NIS2: { example: 'Art.21(2)(d)', valid: article(46) },
+  'NIST-800-53': {
+    example: 'AC-6(1)',
+    valid: (id) => {
+      const match = /^([A-Z]{2})-([1-9]\d?)(?:\(([1-9]\d?)\))?$/.exec(id);
+      return Boolean(match) && Number(match[2]) <= (NIST_800_53[match[1]] || 0);
+    },
+  },
+};
+
+const REF = /^([A-Za-z0-9-]{2,20}):(\S{1,40})$/;
+
+/**
+ * Check one reference. Returns the reference split into framework and id, or throws with
+ * the reason and the accepted form.
+ */
+function parseControl(ref) {
+  const match = typeof ref === 'string' ? REF.exec(ref) : null;
+  if (!match) throw new Error(`"${ref}" is not a control reference (FRAMEWORK:ID)`);
+  const [, framework, id] = match;
+  const grammar = FRAMEWORKS[framework];
+  if (!grammar)
+    throw new Error(
+      `"${ref}": no control catalog for ${framework} (${Object.keys(FRAMEWORKS).join(', ')})`
+    );
+  if (!grammar.valid(id))
+    throw new Error(
+      `"${ref}" names no ${framework} control (e.g. ${framework}:${grammar.example})`
+    );
+  return { framework, id };
+}
+
+/** A list of references: each valid, none repeated. Returns the list unchanged. */
+function parseControls(list, where) {
+  if (!Array.isArray(list) || !list.length)
+    throw new Error(`${where}: controls must be a non-empty list of FRAMEWORK:ID references`);
+  const seen = new Set();
+  for (const ref of list) {
+    try {
+      parseControl(ref);
+    } catch (error) {
+      throw new Error(`${where}: ${error.message}`, { cause: error });
+    }
+    if (seen.has(ref)) throw new Error(`${where}: control ${ref} is listed twice`);
+    seen.add(ref);
+  }
+  return [...list];
+}
+
+module.exports = { FRAMEWORKS, parseControl, parseControls };

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

@@ -155,6 +155,23 @@ function collectInstallationHealth({
     }
   }
 
+  if (selectedPacks.includes('shield')) {
+    // Soft by design: an AI tool missing from the register is reported, never an error.
+    const { checkRegister } = require('./ai-register');
+    const result = checkRegister(projectDir);
+    const problems = [...result.errors, ...result.warnings];
+    check(
+      'shield.ai-register',
+      problems.length ? 'warning' : 'pass',
+      problems.length
+        ? 'AI processing register: ' +
+            problems.join('; ') +
+            '. Run `bmad-plus ai-register check` for details.'
+        : `AI processing register covers the ${result.integrations.length} AI integration(s) found.`,
+      { path: result.registerFile }
+    );
+  }
+
   const inventory = inventoryOf(manifest);
   const validInventory =
     inventory &&

package/tools/cli/lib/intake.js

@@ -0,0 +1,202 @@
+/** Read, plan, record and render a pack intake inside one project; the contract decides. */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+const { safeTarget } = require('../../build/generate-adapters');
+const contract = require('../../build/intake-contract');
+
+const MAX_FILE = 1024 * 1024;
+// Trees the intake never writes into, wherever they sit in the project.
+const RESERVED_DIRS = new Set(['.git', '_bmad', '.bmad-plus', 'node_modules']);
+
+/** A user-supplied path, kept inside the project and free of symlinks. */
+function projectFile(projectDir, file) {
+  if (typeof file !== 'string' || file.trim() === '') throw new Error('a file path is required');
+  const root = path.resolve(projectDir);
+  const relative = path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
+  if (!relative || relative === '..' || relative.startsWith('../'))
+    throw new Error(`${file}: outside the project directory ${root}`);
+  return { relative, absolute: safeTarget(root, relative) };
+}
+
+/** A path the intake may write: outside the reserved trees, and never through a link. */
+function writableFile(projectDir, file) {
+  const target = projectFile(projectDir, file);
+  const reserved = target.relative.split('/').find((part) => RESERVED_DIRS.has(part));
+  if (reserved) throw new Error(`${target.relative}: the intake never writes under ${reserved}/`);
+  return target;
+}
+
+function readBounded(absolute, label) {
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile()) throw new Error(`${label}: not a regular file`);
+  if (stat.size > MAX_FILE) throw new Error(`${label}: larger than ${MAX_FILE} bytes`);
+  return fs.readFileSync(absolute, 'utf8');
+}
+
+function describe(problems) {
+  return problems.map((problem) => `  - ${problem}`).join('\n');
+}
+
+/** Parse and validate an intake file; throws listing every problem. */
+function loadIntake(projectDir, file) {
+  const target = projectFile(projectDir, file);
+  let parsed;
+  try {
+    parsed = yaml.load(readBounded(target.absolute, target.relative), { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    throw new Error(`${target.relative}: ${error.message}`, { cause: error });
+  }
+  const result = contract.validateIntake(parsed);
+  if (!result.ok)
+    throw new Error(`${target.relative} is not a valid intake:\n${describe(result.problems)}`);
+  return { file: target.relative, intake: parsed };
+}
+
+/** The parsed JSON of an existing answers file when it belongs to this intake; else throws. */
+function ownedAnswers(target, intake) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readBounded(target.absolute, target.relative));
+  } catch (error) {
+    throw new Error(
+      `${target.relative}: exists and is not an answers file of intake "${intake.id}" (${error.message}); move it away or pick another path`,
+      { cause: error }
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.intake !== intake.id) {
+    throw new Error(
+      `${target.relative}: exists and belongs to ${JSON.stringify(parsed && parsed.intake)}, not to intake "${intake.id}"; move it away or pick another path`
+    );
+  }
+  return parsed;
+}
+
+/** Parse and validate an answers file; an absent file means no answer yet. */
+function loadAnswers(projectDir, file, intake) {
+  const target = writableFile(projectDir, file);
+  if (!fs.existsSync(target.absolute)) {
+    return { file: target.relative, answers: contract.emptyAnswers(intake), exists: false };
+  }
+  const parsed = ownedAnswers(target, intake);
+  const result = contract.validateAnswers(parsed, intake);
+  if (!result.ok)
+    throw new Error(
+      `${target.relative} does not answer this intake:\n${describe(result.problems)}\nRecord again with --reset to start over.`
+    );
+  return { file: target.relative, answers: parsed, exists: true };
+}
+
+function atomicWrite(projectDir, relative, content) {
+  const target = safeTarget(projectDir, relative);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const temporaryFile = `${relative}.${crypto.randomUUID()}.tmp`;
+  const temporary = safeTarget(projectDir, temporaryFile);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx');
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    safeTarget(projectDir, relative);
+    fs.renameSync(temporary, target);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+function check({ projectDir, file }) {
+  const target = projectFile(projectDir, file);
+  let parsed;
+  try {
+    parsed = yaml.load(readBounded(target.absolute, target.relative), { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    return { file: target.relative, ok: false, problems: [error.message] };
+  }
+  const result = contract.validateIntake(parsed);
+  const summary = result.ok
+    ? {
+        id: parsed.id,
+        pack: parsed.pack,
+        questions: contract.listQuestions(parsed).length,
+        mustHave: contract.listQuestions(parsed).filter((q) => q.must_have === true).length,
+      }
+    : {};
+  return { file: target.relative, ...result, ...summary };
+}
+
+function plan({ projectDir, intakeFile, answersFile }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  const { answers, file } = loadAnswers(projectDir, answersFile, intake);
+  return { answersFile: file, ...contract.planIntake(intake, answers) };
+}
+
+/**
+ * `sets` is a list of "id=VALUE" texts, `defaults` a list of question ids. With
+ * `reset`, the file starts again empty for this intake (an existing file must
+ * already belong to it), then takes the sets and defaults of the same call.
+ */
+function record({ projectDir, intakeFile, answersFile, sets = [], defaults = [], reset = false }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  let loaded;
+  if (reset) {
+    const target = writableFile(projectDir, answersFile);
+    if (fs.existsSync(target.absolute)) ownedAnswers(target, intake);
+    loaded = { file: target.relative, answers: contract.emptyAnswers(intake) };
+  } else loaded = loadAnswers(projectDir, answersFile, intake);
+  const pairs = {};
+  for (const assignment of sets) {
+    const at = typeof assignment === 'string' ? assignment.indexOf('=') : -1;
+    if (at < 1) throw new Error(`--set expects id=VALUE, got "${assignment}"`);
+    const id = assignment.slice(0, at);
+    if (Object.hasOwn(pairs, id)) throw new Error(`question "${id}" is set twice in one call`);
+    pairs[id] = assignment.slice(at + 1);
+  }
+  if (!reset && Object.keys(pairs).length === 0 && defaults.length === 0)
+    throw new Error('nothing to record: pass --set id=VALUE, --default id or --reset');
+  const answers = contract.recordAnswers(intake, loaded.answers, { sets: pairs, defaults });
+  const result = contract.validateAnswers(answers, intake);
+  if (!result.ok) throw new Error(`recorded answers are invalid:\n${describe(result.problems)}`);
+  atomicWrite(projectDir, loaded.file, JSON.stringify(answers, null, 2) + '\n');
+  return {
+    answersFile: loaded.file,
+    reset,
+    recorded: [...Object.keys(pairs), ...defaults],
+    ...contract.planIntake(intake, answers),
+  };
+}
+
+/** The brief overwrites only a file it wrote before for the same intake. */
+function render({ projectDir, intakeFile, answersFile, out }) {
+  const { intake } = loadIntake(projectDir, intakeFile);
+  const { answers } = loadAnswers(projectDir, answersFile, intake);
+  const target = writableFile(projectDir, out);
+  if (fs.existsSync(target.absolute)) {
+    const marker = contract.briefMarker(intake);
+    const head = readBounded(target.absolute, target.relative).split(/\r?\n/, 2);
+    if (head[1] !== marker)
+      throw new Error(
+        `${target.relative}: exists and is not a brief of intake "${intake.id}" (its second line is not the ownership marker); move it away or pick another path`
+      );
+  }
+  const brief = contract.renderBrief(intake, answers);
+  atomicWrite(projectDir, target.relative, brief);
+  const planned = contract.planIntake(intake, answers);
+  return { out: target.relative, bytes: Buffer.byteLength(brief), ready: planned.ready };
+}
+
+module.exports = {
+  projectFile,
+  writableFile,
+  loadIntake,
+  loadAnswers,
+  check,
+  plan,
+  record,
+  render,
+};

package/tools/cli/lib/pack-copy.js

@@ -8,11 +8,90 @@ const crypto = require('node:crypto');
 const { safeTarget } = require('../../build/generate-adapters');
 
 const fileHash = (content) => crypto.createHash('sha256').update(content).digest('hex');
+const MAX_MANIFEST = 1024 * 1024;
 
-function listPackFiles({ bmadSrc, targetAgentsDir, targetDataDir, projectRoot, pack }) {
+/** The package name comes from the generated registry data, never from user input. */
+function resolveModule(name, projectRoot) {
+  return require.resolve(name + '/package.json', { paths: [projectRoot] });
+}
+
+/** The node_modules directories Node searches from the BMAD+ package root upwards. */
+function moduleChain(projectRoot) {
+  const chain = [];
+  let current = fs.realpathSync(projectRoot);
+  for (;;) {
+    if (path.basename(current) !== 'node_modules') chain.push(path.join(current, 'node_modules'));
+    const parent = path.dirname(current);
+    if (parent === current) return chain;
+    current = parent;
+  }
+}
+
+/**
+ * The root of an `external_module` package installed next to BMAD+, once its
+ * version is the one the registry pinned. Node resolves through symlinks, so the
+ * resolved package must sit in the node_modules chain itself: a link or a global
+ * module path is refused.
+ */
+function externalModuleRoot({ externalModule, projectRoot, resolve = resolveModule }) {
+  const { package: name, version } = externalModule;
+  let manifestPath;
+  try {
+    manifestPath = resolve(name, projectRoot);
+  } catch (error) {
+    throw new Error(
+      'External module ' + name + ' is not installed next to BMAD+: ' + error.message,
+      { cause: error }
+    );
+  }
+  const expected = moduleChain(projectRoot).map((dir) =>
+    path.join(dir, ...name.split('/'), 'package.json')
+  );
+  if (!expected.includes(manifestPath)) {
+    throw new Error(
+      'External module ' +
+        name +
+        ' resolved to ' +
+        manifestPath +
+        ', outside the node_modules chain of this BMAD+. A symlinked package, a global module path and the isolated layout of pnpm (node_modules/.pnpm) are refused: install bmad-plus with npm so its pinned dependency sits in that chain.'
+    );
+  }
+  const root = path.dirname(manifestPath);
+  safeTarget(root, 'package.json');
+  const stat = fs.lstatSync(manifestPath);
+  if (!stat.isFile() || stat.size > MAX_MANIFEST)
+    throw new Error('External module ' + name + ' has no readable package.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error('External module ' + name + ': ' + error.message, { cause: error });
+  }
+  if (!manifest || manifest.name !== name || manifest.version !== version) {
+    throw new Error(
+      'External module ' +
+        name +
+        ' is ' +
+        String(manifest && manifest.version) +
+        ' but this BMAD+ expects exactly ' +
+        version +
+        '; reinstall bmad-plus so its pinned dependency matches.'
+    );
+  }
+  return root;
+}
+
+function listPackFiles({
+  bmadSrc,
+  targetAgentsDir,
+  targetDataDir,
+  projectRoot,
+  pack,
+  resolveModule: resolve,
+}) {
   const result = { copiedAgents: 0, copiedSkills: 0, copiedFiles: 0, files: [] };
   if (!pack) return result;
-  function walk(source, target) {
+  function walk(source, target, root) {
     // Local Python execution must not turn interpreter caches into owned/shipped
     // framework files. Keep this aligned with the explicit npm files exclusions.
     if (path.basename(source) === '__pycache__' || /\.py[co]$/i.test(source)) return false;
@@ -26,9 +105,9 @@ function listPackFiles({ bmadSrc, targetAgentsDir, targetDataDir, projectRoot, p
     if (stat.isSymbolicLink()) throw new Error('Pack source is a symbolic link: ' + source);
     if (stat.isDirectory()) {
       for (const name of fs.readdirSync(source).sort())
-        walk(path.join(source, name), path.join(target, name));
+        walk(path.join(source, name), path.join(target, name), root);
     } else if (stat.isFile()) {
-      result.files.push({ source, target });
+      result.files.push(root ? { source, target, root } : { source, target });
     } else throw new Error('Pack source is not a regular file: ' + source);
     return true;
   }
@@ -49,6 +128,17 @@ function listPackFiles({ bmadSrc, targetAgentsDir, targetDataDir, projectRoot, p
     walk(path.join(projectRoot, pack.externalPackage, 'skills'), targetAgentsDir)
   )
     result.copiedSkills++;
+  if (pack.externalModule) {
+    const root = externalModuleRoot({ externalModule: pack.externalModule, projectRoot, resolve });
+    for (const name of pack.externalModule.skills) {
+      if (!walk(path.join(root, 'skills', name), path.join(targetAgentsDir, name), root)) {
+        throw new Error(
+          'External module ' + pack.externalModule.package + ' does not ship skill ' + name
+        );
+      }
+      result.copiedSkills++;
+    }
+  }
   if (
     pack.packDir &&
     walk(
@@ -105,4 +195,4 @@ function copyPackFiles(options) {
   return counts;
 }
 
-module.exports = { copyPackFiles, listPackFiles, copyManagedFile, fileHash };
+module.exports = { copyPackFiles, listPackFiles, copyManagedFile, externalModuleRoot, fileHash };