bmad-plus 0.21.0 → 0.22.0

package/tools/cli/commands/assurance.js

@@ -0,0 +1,162 @@
+/**
+ * Security assurance cases: start one from the Shield template, run the checks that produce
+ * evidence, verify a case against them.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const assurance = require('../lib/assurance');
+
+const ACTIONS = ['init', 'run', 'verify'];
+
+function print(json, payload, lines) {
+  if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
+  else for (const line of lines) console.log(line);
+}
+
+/** `--emit-check` writes a JSON file atomically, never over the case or its ledger. */
+function writeCheck(projectDir, value, kase, ledger, result) {
+  const file = path.resolve(projectDir, value);
+  if (!/\.json$/i.test(file)) throw new Error('--emit-check writes a .json file');
+  const protectedFiles = [path.resolve(projectDir, kase.file), ledger];
+  if (protectedFiles.some((taken) => path.relative(taken, file) === ''))
+    throw new Error('--emit-check must not overwrite the case or its ledger');
+  if (fs.existsSync(file) && !fs.statSync(file).isFile())
+    throw new Error(`--emit-check: ${file} is not a file`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx' });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+  return file;
+}
+
+function initAction(projectDir, caseFile, json) {
+  const { file, id } = assurance.initCase(projectDir, caseFile);
+  print(json, { action: 'init', case: id, file }, [
+    `${file}: case ${id} started from the Shield template.`,
+    'Replace every example claim and check with those of the project, commit it, then run it.',
+  ]);
+}
+
+async function runAction(projectDir, kase, options, json) {
+  const { file, results, head, authenticated } = await assurance.runChecks(projectDir, kase, {
+    dir: options.dir,
+    only: options.check,
+  });
+  const failed = results.filter((result) => result.failures.length);
+  print(
+    json,
+    {
+      action: 'run',
+      case: kase.id,
+      ledger: file,
+      head,
+      authenticated,
+      results: results.map(({ check, failures, record }) => ({
+        check,
+        status: failures.length ? 'failed' : 'passed',
+        failures,
+        sequence: record.sequence,
+        exitCode: record.exitCode,
+        revision: record.revision,
+        dirty: record.dirty,
+        sha256: record.sha256,
+      })),
+    },
+    [
+      `${file}`,
+      ...results.map(
+        ({ check, failures, record }) =>
+          `  ${failures.length ? 'failed' : 'passed'} ${check.padEnd(24)} exit ${record.exitCode ?? '-'} in ${Math.round(record.durationMs / 100) / 10} s${failures.length ? ` — ${failures.join('; ')}` : ''}`
+      ),
+      ...(results.some(({ record }) => record.dirty !== false)
+        ? [
+            '  Ran on uncommitted changes, untracked files or outside git: a case bound to a commit will not accept these runs.',
+          ]
+        : []),
+      `Recorded ${results.length} run(s)${authenticated ? ', authenticated by key' : ''}; ledger head ${head}.`,
+      `Keep the head outside the ledger and verify with bmad-plus assurance verify ${kase.file} --ledger-head ${head}.`,
+    ]
+  );
+  process.exitCode = failed.length ? 1 : 0;
+}
+
+function verifyAction(projectDir, kase, options, json) {
+  const verdict = assurance.verifyCase(projectDir, kase, {
+    dir: options.dir,
+    head: options.ledgerHead ?? null,
+  });
+  let check = null;
+  if (options.emitCheck)
+    check = writeCheck(
+      projectDir,
+      options.emitCheck,
+      kase,
+      assurance.ledgerFile(projectDir, options.dir, kase.id),
+      assurance.checkResult(verdict)
+    );
+  print(
+    json,
+    { action: 'verify', ...verdict, check },
+    [
+      `${kase.id}: ${verdict.status} — ${verdict.claims.filter((c) => c.status === 'supported').length}/${verdict.claims.length} claim(s) supported, ${verdict.ledger.runs} recorded run(s)`,
+      ...verdict.reasons.map((reason) => `  - ${reason}`),
+      ...Object.entries(verdict.checks)
+        .filter(([, judged]) => judged.status !== 'passed')
+        .map(([id, judged]) => `  ${judged.status.padEnd(7)} ${id}: ${judged.reasons.join('; ')}`),
+      ...verdict.claims
+        .filter((claim) => claim.status !== 'supported')
+        .map((claim) => `  unsupported claim ${claim.id}: ${claim.reasons.join('; ')}`),
+      ...(verdict.controls.supported.length
+        ? [`  controls with executed evidence: ${verdict.controls.supported.join(', ')}`]
+        : []),
+      check ? `  check: ${check}` : '',
+    ].filter(Boolean)
+  );
+  process.exitCode = verdict.exitCode;
+}
+
+module.exports = {
+  command: 'assurance <action> <case>',
+  description: 'Security assurance case bound to executed checks: init, run, verify',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--dir <path>', 'Evidence folder inside the project', assurance.DEFAULT_DIR],
+    ['--check <id>', 'run: only this check (repeatable)', (v, all) => [...all, v], []],
+    ['--ledger-head <sha256>', 'verify: fail unless the ledger still holds this record'],
+    ['--emit-check <file>', 'verify: also write the verdict as a JSON check result for CI'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: async (action, caseFile, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const json = Boolean(options.json);
+    const settings = { dir: options.dir || assurance.DEFAULT_DIR, check: options.check || [] };
+    try {
+      if (!ACTIONS.includes(action))
+        throw new Error(`unknown action "${action}" (${ACTIONS.join(', ')})`);
+      if (action === 'init') return initAction(projectDir, caseFile, json);
+      const kase = assurance.loadCase(projectDir, caseFile);
+      if (action === 'run') await runAction(projectDir, kase, settings, json);
+      else
+        verifyAction(
+          projectDir,
+          kase,
+          { ...settings, emitCheck: options.emitCheck, ledgerHead: options.ledgerHead },
+          json
+        );
+    } catch (error) {
+      if (json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', message: error.message }, null, 2)
+        );
+      else console.error(`assurance: ${error.message}`);
+      process.exitCode = 3;
+    }
+  },
+};

package/tools/cli/commands/review.js

@@ -169,23 +169,30 @@ function rulesAction(projectDir, target, json) {
       action: 'rules',
       path: file,
       sha256: ruleset.sha256,
+      packFiles: ruleset.packFiles,
       projectFile: ruleset.projectFile,
       disabled: ruleset.disabled,
-      rules: listed.map(({ id, title, group, layer, globs, source }) => ({
+      rules: listed.map(({ id, title, group, layer, pack, globs, controls, source }) => ({
         id,
         title,
         group,
         layer,
+        ...(pack ? { pack } : {}),
         globs,
+        controls,
         source,
       })),
+      controls: reviewRules.controlsOf(
+        ruleset,
+        listed.map((rule) => rule.id)
+      ),
     },
     [
-      `rule set ${ruleset.sha256.slice(0, 12)}${ruleset.projectFile ? ` (built-in + ${ruleset.projectFile})` : ' (built-in)'}`,
+      `rule set ${ruleset.sha256.slice(0, 12)} (${['built-in', ...ruleset.packFiles, ...(ruleset.projectFile ? [ruleset.projectFile] : [])].join(' + ')})`,
       ...(file ? [`${file} gets ${listed.length} rule(s):`] : []),
       ...listed.map(
         (rule) =>
-          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
+          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}${rule.controls.length ? `\n  ${''.padEnd(24)} controls: ${rule.controls.join(' ')}` : ''}`
       ),
       ...ruleset.disabled.map((id) => `  ${id.padEnd(24)} disabled by the project`),
     ]

package/tools/cli/lib/ai-register.js

@@ -0,0 +1,393 @@
+/**
+ * The AI processing register: which AI tools a project uses, what data they see, for what
+ * purpose, on which legal basis, for how long and where it goes. `checkRegister` compares it
+ * with the integrations present in the project (the adapters BMAD+ installs, the tools'
+ * own configuration folders, declared MCP servers) and warns about any it does not cover.
+ * The gate is soft: an unregistered tool is a warning, never a failure.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('js-yaml');
+const { DERIVED } = require('./packs');
+
+const SCHEMA = 'bmad-plus/ai-processing-register/1';
+const CHECK_SCHEMA = 'bmad-plus/ai-register-check/1';
+const REGISTER_FILE = '_bmad/ai-processing-register.yaml';
+const MAX_BYTES = 256 * 1024;
+const MAX_TEXT = 2000;
+const REVIEW_INTERVAL_DAYS = 365;
+const TEMPLATE = path.join(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'src',
+  'bmad-plus',
+  'packs',
+  'pack-shield',
+  'shared',
+  'ai-processing-register-template.yaml'
+);
+const BOM = String.fromCharCode(0xfeff);
+
+const REGISTER_KEYS = ['schema', 'controller', 'reviewed', 'tools'];
+const ENTRY_KEYS = [
+  'id',
+  'name',
+  'provider',
+  'integrations',
+  'purpose',
+  'data',
+  'personalData',
+  'legalBasis',
+  'retention',
+  'transfers',
+  'agreement',
+];
+/** GDPR Art. 6(1)(a) to (f). */
+const LEGAL_BASES = [
+  'consent',
+  'contract',
+  'legal-obligation',
+  'vital-interests',
+  'public-task',
+  'legitimate-interests',
+];
+/** GDPR Art. 45, 46(2)(c), 47 and 49. */
+const TRANSFER_MECHANISMS = [
+  'adequacy-decision',
+  'standard-contractual-clauses',
+  'binding-corporate-rules',
+  'derogation',
+];
+const ENTRY_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** A tool id, or mcp: and a server name exactly as declared, control characters excepted. */
+const INTEGRATION_ID = /^(?:[a-z0-9][a-z0-9.-]{0,63}|mcp:[^\p{Cc}]{1,256})$/u;
+
+/**
+ * Where an AI tool shows it is set up in a project, beyond the adapter files the registry
+ * declares. Each marker names the integration ids that cover it.
+ */
+const TOOL_MARKERS = [
+  { ids: ['claude-code'], paths: ['.claude'] },
+  { ids: ['cursor'], paths: ['.cursor', '.cursorrules'] },
+  { ids: ['gemini-cli', 'antigravity'], paths: ['.gemini'] },
+  { ids: ['codex-cli'], paths: ['.codex'] },
+  { ids: ['opencode'], paths: ['.opencode', 'opencode.json'] },
+  { ids: ['aider'], paths: ['.aider.conf.yml'] },
+  { ids: ['github-copilot'], paths: ['.github/copilot-instructions.md'] },
+  { ids: ['windsurf'], paths: ['.windsurf', '.windsurfrules'] },
+  { ids: ['continue'], paths: ['.continue'] },
+];
+
+/** Project files that declare MCP servers, and the key that holds them. */
+const MCP_FILES = [
+  { file: '.mcp.json', key: 'mcpServers' },
+  { file: '.cursor/mcp.json', key: 'mcpServers' },
+  { file: '.gemini/settings.json', key: 'mcpServers' },
+  { file: '.vscode/mcp.json', key: 'servers' },
+];
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function only(value, keys, where) {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    fail(`${where}: must be a mapping`);
+  const unknown = Object.keys(value).filter((key) => !keys.includes(key));
+  if (unknown.length) fail(`${where}: unknown key(s) ${unknown.join(', ')}`);
+}
+
+function text(value, where) {
+  if (typeof value !== 'string' || !value.trim() || value.length > MAX_TEXT)
+    fail(`${where}: expected text of 1 to ${MAX_TEXT} characters`);
+  return value.trim();
+}
+
+function list(value, where, check) {
+  if (!Array.isArray(value) || !value.length) fail(`${where}: must be a non-empty list`);
+  return value.map((item, index) => check(item, `${where} ${index + 1}`));
+}
+
+/** A calendar date written YYYY-MM-DD; YAML may already have parsed it as a Date. */
+function isoDate(value, where) {
+  const written = value instanceof Date ? value.toISOString().slice(0, 10) : value;
+  if (
+    typeof written !== 'string' ||
+    !/^\d{4}-\d{2}-\d{2}$/.test(written) ||
+    new Date(`${written}T00:00:00Z`).toISOString().slice(0, 10) !== written
+  )
+    fail(`${where}: expected a date written YYYY-MM-DD`);
+  return written;
+}
+
+function parseEntry(raw, index) {
+  const at = `tool ${raw?.id ?? index + 1}`;
+  only(raw, ENTRY_KEYS, at);
+  if (typeof raw.id !== 'string' || !ENTRY_ID.test(raw.id)) fail(`${at}: invalid id`);
+  if (typeof raw.personalData !== 'boolean')
+    fail(`${at}: personalData must say true or false whether the tool sees personal data`);
+  if (raw.personalData && !LEGAL_BASES.includes(raw.legalBasis))
+    fail(`${at}: legalBasis must be one of ${LEGAL_BASES.join(', ')}`);
+  if (!raw.personalData && raw.legalBasis !== undefined)
+    fail(`${at}: legalBasis applies only when the tool sees personal data`);
+  if (!Array.isArray(raw.transfers))
+    fail(`${at}: transfers must list where data goes outside the EEA ([] for nowhere)`);
+  return {
+    id: raw.id,
+    name: text(raw.name, `${at}: name`),
+    provider: text(raw.provider, `${at}: provider`),
+    integrations: list(raw.integrations, `${at}: integration`, (id, where) => {
+      if (typeof id !== 'string' || !INTEGRATION_ID.test(id))
+        fail(`${where}: "${id}" is not an integration id (a tool id, or mcp:<server>)`);
+      return id;
+    }),
+    purpose: text(raw.purpose, `${at}: purpose`),
+    data: list(raw.data, `${at}: data category`, text),
+    personalData: raw.personalData,
+    legalBasis: raw.legalBasis ?? null,
+    retention: text(raw.retention, `${at}: retention`),
+    transfers: raw.transfers.map((transfer, i) => {
+      const where = `${at}: transfer ${i + 1}`;
+      only(transfer, ['to', 'mechanism'], where);
+      if (!TRANSFER_MECHANISMS.includes(transfer.mechanism))
+        fail(`${where}: mechanism must be one of ${TRANSFER_MECHANISMS.join(', ')}`);
+      return { to: text(transfer.to, `${where}: to`), mechanism: transfer.mechanism };
+    }),
+    agreement: raw.agreement === undefined ? null : text(raw.agreement, `${at}: agreement`),
+  };
+}
+
+/** Validate a parsed register. Throws on the first defect. */
+function parseRegister(doc) {
+  only(doc, REGISTER_KEYS, 'register');
+  if (doc.schema !== SCHEMA) fail(`register: schema must be "${SCHEMA}"`);
+  const tools = Array.isArray(doc.tools) ? doc.tools : fail('register: tools must be a list');
+  const entries = tools.map(parseEntry);
+  const ids = new Set();
+  const covered = new Map();
+  for (const entry of entries) {
+    if (ids.has(entry.id)) fail(`tool ${entry.id}: duplicate id`);
+    ids.add(entry.id);
+    for (const integration of entry.integrations) {
+      if (covered.has(integration))
+        fail(`tool ${entry.id}: ${integration} is already covered by ${covered.get(integration)}`);
+      covered.set(integration, entry.id);
+    }
+  }
+  return {
+    controller: text(doc.controller, 'register: controller'),
+    reviewed: isoDate(doc.reviewed, 'register: reviewed'),
+    tools: entries,
+  };
+}
+
+/** A name shortened and with its control characters escaped, safe to print. */
+function printable(name) {
+  const shown = name.length > 64 ? `${name.slice(0, 64)}...` : name;
+  return shown.replace(/\p{Cc}/gu, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/** The index just past the JSON string that opens at `start`. */
+function stringEnd(text, start) {
+  let end = start + 1;
+  while (end < text.length && text[end] !== '"') end += text[end] === '\\' ? 2 : 1;
+  return end + 1;
+}
+
+const CLOSING = /\s*[}\]]/y;
+
+/**
+ * JSON with comments, as VS Code and Gemini write their settings: line and block comments,
+ * then trailing commas, are removed outside strings before the text is parsed as JSON.
+ */
+function parseJsonc(source) {
+  let bare = '';
+  for (let i = 0; i < source.length;) {
+    if (source[i] === '"') {
+      const end = stringEnd(source, i);
+      bare += source.slice(i, end);
+      i = end;
+    } else if (source.startsWith('//', i)) {
+      const end = source.indexOf('\n', i);
+      i = end === -1 ? source.length : end;
+    } else if (source.startsWith('/*', i)) {
+      const end = source.indexOf('*/', i + 2);
+      if (end === -1) fail('a block comment is not closed');
+      bare += ' ';
+      i = end + 2;
+    } else bare += source[i++];
+  }
+  let json = '';
+  for (let i = 0; i < bare.length;) {
+    if (bare[i] === '"') {
+      const end = stringEnd(bare, i);
+      json += bare.slice(i, end);
+      i = end;
+      continue;
+    }
+    CLOSING.lastIndex = i + 1;
+    if (bare[i] !== ',' || !CLOSING.test(bare)) json += bare[i];
+    i += 1;
+  }
+  return JSON.parse(json);
+}
+
+/** A regular file or folder inside the project, reached without a symbolic link. */
+function present(root, relative) {
+  let current = root;
+  for (const part of relative.split('/')) {
+    current = path.join(current, part);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function readProjectFile(root, relative) {
+  if (!present(root, relative)) return null;
+  const file = path.join(root, ...relative.split('/'));
+  const stat = fs.statSync(file);
+  if (!stat.isFile()) return null;
+  if (stat.size > MAX_BYTES) fail(`${relative} exceeds ${MAX_BYTES} bytes`);
+  const content = fs.readFileSync(file, 'utf8');
+  return content.startsWith(BOM) ? content.slice(1) : content;
+}
+
+/**
+ * The AI integrations present in the project, each with the ids that would cover it and
+ * the files that show it. Unreadable MCP declarations come back as warnings.
+ */
+function detectIntegrations(projectDir, { adapters = DERIVED.targets.adapters } = {}) {
+  const root = path.resolve(projectDir);
+  const found = new Map();
+  const add = (ids, source) => {
+    const key = ids.join('|');
+    const entry = found.get(key) || { ids, sources: [] };
+    if (!entry.sources.includes(source)) entry.sources.push(source);
+    found.set(key, entry);
+  };
+  // One adapter file can serve several tools (GEMINI.md): any of them covers it.
+  const byFile = new Map();
+  for (const { tool, file } of adapters) byFile.set(file, [...(byFile.get(file) || []), tool]);
+  for (const [file, tools] of byFile) if (present(root, file)) add(tools, file);
+  for (const { ids, paths } of TOOL_MARKERS)
+    for (const marker of paths) if (present(root, marker)) add(ids, marker);
+  const warnings = [];
+  for (const { file, key } of MCP_FILES) {
+    let doc;
+    try {
+      const content = readProjectFile(root, file);
+      if (content === null) continue;
+      doc = parseJsonc(content);
+    } catch (error) {
+      warnings.push(`${file} cannot be read (${error.message}); its MCP servers are not checked`);
+      continue;
+    }
+    const servers = doc && typeof doc[key] === 'object' && doc[key] ? Object.keys(doc[key]) : [];
+    for (const server of servers) {
+      // Only a name the register can hold is reported, and never with raw control characters.
+      if (INTEGRATION_ID.test(`mcp:${server}`)) add([`mcp:${server}`], file);
+      else
+        warnings.push(
+          `${file} declares the MCP server "${printable(server)}", whose name cannot be registered; it is not checked`
+        );
+    }
+  }
+  return { integrations: [...found.values()], warnings };
+}
+
+/**
+ * Compare the register with the project. Returns the detected integrations with the entry
+ * covering each, the register entries matching nothing found here, the warnings, and any
+ * error that made the register unreadable.
+ */
+function checkRegister(projectDir, { now = new Date(), adapters } = {}) {
+  const root = path.resolve(projectDir);
+  const detected = detectIntegrations(root, adapters ? { adapters } : {});
+  const warnings = [...detected.warnings];
+  const errors = [];
+  let register = null;
+  try {
+    const source = readProjectFile(root, REGISTER_FILE);
+    if (source !== null) register = parseRegister(yaml.load(source));
+  } catch (error) {
+    errors.push(`${REGISTER_FILE}: ${error.message}`);
+  }
+  const covering = new Map();
+  for (const entry of register?.tools || [])
+    for (const id of entry.integrations) covering.set(id, entry.id);
+  const integrations = detected.integrations.map(({ ids, sources }) => ({
+    ids,
+    sources,
+    coveredBy: ids.map((id) => covering.get(id)).find(Boolean) || null,
+  }));
+  const missing = integrations.filter((item) => !item.coveredBy);
+  if (!register && !errors.length && integrations.length)
+    warnings.push(`no AI processing register at ${REGISTER_FILE}`);
+  for (const item of missing)
+    warnings.push(
+      `${item.ids.join(' or ')} is set up (${item.sources.join(', ')}) but not in the AI processing register`
+    );
+  if (register) {
+    const age = Math.floor((now - new Date(`${register.reviewed}T00:00:00Z`)) / 86400000);
+    if (age > REVIEW_INTERVAL_DAYS)
+      warnings.push(`the register was last reviewed on ${register.reviewed}, ${age} days ago`);
+  }
+  const seen = new Set(integrations.flatMap((item) => item.ids));
+  return {
+    schema: CHECK_SCHEMA,
+    registerFile: REGISTER_FILE,
+    register: register ? { controller: register.controller, reviewed: register.reviewed } : null,
+    status: errors.length ? 'error' : warnings.length ? 'warning' : 'ok',
+    integrations,
+    unmatched: (register?.tools || [])
+      .filter((entry) => !entry.integrations.some((id) => seen.has(id)))
+      .map((entry) => entry.id),
+    warnings,
+    errors,
+  };
+}
+
+/**
+ * Start the register from the Shield template, never over an existing one. The template's
+ * entries are examples: `check` keeps warning until they describe the project's own tools.
+ */
+function initRegister(projectDir) {
+  const [folder, name] = REGISTER_FILE.split('/');
+  const target = path.join(path.resolve(projectDir), folder);
+  let stat = null;
+  try {
+    stat = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  // A link in place of the folder would write the register outside the project.
+  if (stat && !stat.isDirectory()) fail(`${folder} is not a folder`);
+  fs.mkdirSync(target, { recursive: true });
+  try {
+    fs.writeFileSync(path.join(target, name), fs.readFileSync(TEMPLATE, 'utf8'), { flag: 'wx' });
+  } catch (error) {
+    if (error.code === 'EEXIST') fail(`${REGISTER_FILE} already exists`);
+    throw error;
+  }
+  return REGISTER_FILE;
+}
+
+module.exports = {
+  SCHEMA,
+  CHECK_SCHEMA,
+  REGISTER_FILE,
+  LEGAL_BASES,
+  TRANSFER_MECHANISMS,
+  parseRegister,
+  initRegister,
+  detectIntegrations,
+  checkRegister,
+};