bmad-method 6.5.1-next.8 → 6.6.0

package/tools/installer/set-overrides.js

@@ -0,0 +1,330 @@
+// `--set <module>.<key>=<value>` is a post-install patch. The installer runs
+// its normal flow and writes `_bmad/config.toml`, `_bmad/config.user.toml`,
+// and `_bmad/<module>/config.yaml`; afterwards `applySetOverrides` upserts
+// each override into those files.
+//
+// This is intentionally NOT integrated with the prompt/template/schema
+// system. Tradeoffs:
+//   - No `result:` template rendering: `--set bmm.project_knowledge=research`
+//     writes "research" verbatim. Pass `--set bmm.project_knowledge='{project-root}/research'`
+//     if you want the rendered form.
+//   - Carry-forward across installs is best-effort: declared schema keys
+//     persist via the existingValue path on the next interactive run; values
+//     for keys outside any module's schema may need to be re-passed on each
+//     install (or edited directly in `_bmad/config.toml`).
+//   - No "key not in schema" validation: whatever you assert, we write.
+//
+// Names that, when used as object keys, can mutate `Object.prototype` and
+// cascade into every plain-object lookup in the process. The `--set` pipeline
+// assigns into plain `{}` maps keyed by user input, so `--set __proto__.x=1`
+// would otherwise reach `overrides.__proto__[x] = 1` and pollute every plain
+// object. We reject the names at parse time and harden the maps in
+// `parseSetEntries` with `Object.create(null)` for defense-in-depth.
+const PROTOTYPE_POLLUTING_NAMES = new Set(['__proto__', 'prototype', 'constructor']);
+
+const path = require('node:path');
+const fs = require('./fs-native');
+const yaml = require('yaml');
+
+/**
+ * Parse a single `--set <module>.<key>=<value>` entry.
+ * @param {string} entry - raw flag value
+ * @returns {{module: string, key: string, value: string}}
+ * @throws {Error} on malformed input
+ */
+function parseSetEntry(entry) {
+  if (typeof entry !== 'string' || entry.length === 0) {
+    throw new Error('--set: empty entry. Expected <module>.<key>=<value>');
+  }
+  const eq = entry.indexOf('=');
+  if (eq === -1) {
+    throw new Error(`--set "${entry}": missing '='. Expected <module>.<key>=<value>`);
+  }
+  const lhs = entry.slice(0, eq);
+  // Note: only the LHS is trimmed. Values may legitimately contain leading
+  // or trailing whitespace (paths with spaces, quoted strings); module / key
+  // names cannot, so it's safe to be strict on the left.
+  const value = entry.slice(eq + 1);
+  const dot = lhs.indexOf('.');
+  if (dot === -1) {
+    throw new Error(`--set "${entry}": missing '.'. Expected <module>.<key>=<value>`);
+  }
+  const moduleCode = lhs.slice(0, dot).trim();
+  const key = lhs.slice(dot + 1).trim();
+  if (!moduleCode || !key) {
+    throw new Error(`--set "${entry}": empty module or key. Expected <module>.<key>=<value>`);
+  }
+  if (PROTOTYPE_POLLUTING_NAMES.has(moduleCode) || PROTOTYPE_POLLUTING_NAMES.has(key)) {
+    throw new Error(
+      `--set "${entry}": '__proto__', 'prototype', and 'constructor' are reserved and cannot be used as a module or key name.`,
+    );
+  }
+  return { module: moduleCode, key, value };
+}
+
+/**
+ * Parse repeated `--set` entries into a `{ module: { key: value } }` map.
+ * Later entries overwrite earlier ones for the same key. Both the outer
+ * map and the per-module inner maps are `Object.create(null)` so callers
+ * that bypass `parseSetEntry`'s name check still can't pollute prototypes.
+ *
+ * @param {string[]} entries
+ * @returns {Object<string, Object<string, string>>}
+ */
+function parseSetEntries(entries) {
+  const overrides = Object.create(null);
+  if (!Array.isArray(entries)) return overrides;
+  for (const entry of entries) {
+    const { module: moduleCode, key, value } = parseSetEntry(entry);
+    if (!overrides[moduleCode]) overrides[moduleCode] = Object.create(null);
+    overrides[moduleCode][key] = value;
+  }
+  return overrides;
+}
+
+/**
+ * Encode a JS string as a TOML basic string (double-quoted with escapes).
+ * @param {string} value
+ */
+function tomlString(value) {
+  const s = String(value);
+  // Per the TOML spec, basic strings escape `\`, `"`, and control characters.
+  return (
+    '"' +
+    s
+      .replaceAll('\\', '\\\\')
+      .replaceAll('"', String.raw`\"`)
+      .replaceAll('\b', String.raw`\b`)
+      .replaceAll('\f', String.raw`\f`)
+      .replaceAll('\n', String.raw`\n`)
+      .replaceAll('\r', String.raw`\r`)
+      .replaceAll('\t', String.raw`\t`) +
+    '"'
+  );
+}
+
+/**
+ * Section header for a given module code.
+ * - `core`     → `[core]`
+ * - `<other>`  → `[modules.<other>]`
+ *
+ * Mirrors the layout `manifest-generator.writeCentralConfig` produces.
+ */
+function sectionHeader(moduleCode) {
+  return moduleCode === 'core' ? '[core]' : `[modules.${moduleCode}]`;
+}
+
+/**
+ * Insert or update `key = value` inside a TOML section, returning the new
+ * file content. The format produced by the installer is regular and small
+ * enough that a line scanner is more reliable than pulling in a TOML
+ * round-tripper that would normalize the file's existing whitespace and
+ * comment structure.
+ *
+ *   - If `[section]` exists and contains `key`, replace the value on that
+ *     line (preserving any inline comment after the value).
+ *   - If `[section]` exists but `key` doesn't, append `key = value` at the
+ *     end of the section (before the next `[...]` header or EOF, skipping
+ *     trailing blank lines so the section stays tidy).
+ *   - If `[section]` doesn't exist, append a new section block at EOF.
+ *
+ * @param {string} content   existing file content (may be empty)
+ * @param {string} section   exact `[section]` header to target
+ * @param {string} key
+ * @param {string} valueToml already TOML-encoded value (e.g. `"foo"`)
+ * @returns {string} new content
+ */
+function upsertTomlKey(content, section, key, valueToml) {
+  const lines = content.split('\n');
+  // Track whether the file already ended with a newline so we can preserve
+  // that. `split('\n')` on `"a\n"` yields `['a', '']`, which gives us the
+  // marker we need.
+  const hadTrailingNewline = lines.length > 0 && lines.at(-1) === '';
+  if (hadTrailingNewline) lines.pop();
+
+  // Locate the target section.
+  const sectionStart = lines.findIndex((line) => line.trim() === section);
+  if (sectionStart === -1) {
+    // Section doesn't exist — append a new block. Pad with a blank line if
+    // the file is non-empty so sections stay visually separated.
+    if (lines.length > 0 && lines.at(-1).trim() !== '') lines.push('');
+    lines.push(section, `${key} = ${valueToml}`);
+    return lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+  }
+
+  // Find the section's end (next `[...]` header or EOF).
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  // Look for the key inside the section. Match `<key> = ...` allowing
+  // optional leading whitespace; preserve the comment tail (`# ...`) if any.
+  const keyPattern = new RegExp(`^(\\s*)${escapeRegExp(key)}\\s*=\\s*(.*)$`);
+  for (let i = sectionStart + 1; i < sectionEnd; i++) {
+    const match = lines[i].match(keyPattern);
+    if (match) {
+      const indent = match[1];
+      // Preserve trailing comment if present. We split on the first `#` that
+      // is preceded by whitespace — TOML strings can't contain unescaped `#`
+      // in basic-string form so this is safe for the values we emit.
+      const tail = match[2];
+      const commentIdx = tail.search(/\s+#/);
+      const commentSuffix = commentIdx === -1 ? '' : tail.slice(commentIdx);
+      lines[i] = `${indent}${key} = ${valueToml}${commentSuffix}`;
+      return lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+    }
+  }
+
+  // Section exists but key doesn't. Insert before the next section header,
+  // skipping trailing blank lines inside the current section so the new
+  // entry sits with its siblings.
+  let insertAt = sectionEnd;
+  while (insertAt > sectionStart + 1 && lines[insertAt - 1].trim() === '') {
+    insertAt--;
+  }
+  lines.splice(insertAt, 0, `${key} = ${valueToml}`);
+  return lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+}
+
+function escapeRegExp(s) {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+/**
+ * Look up `[section] key` in a TOML file. Returns true if the file exists,
+ * the section is present, and `key` is set within it. Used by
+ * `applySetOverrides` to route an override to the file that already owns
+ * the key (so user-scope keys land in `config.user.toml`, team-scope keys
+ * land in `config.toml`).
+ */
+async function tomlHasKey(filePath, section, key) {
+  if (!(await fs.pathExists(filePath))) return false;
+  const content = await fs.readFile(filePath, 'utf8');
+  const lines = content.split('\n');
+  const sectionStart = lines.findIndex((line) => line.trim() === section);
+  if (sectionStart === -1) return false;
+  const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) return false;
+    if (keyPattern.test(lines[i])) return true;
+  }
+  return false;
+}
+
+/**
+ * Apply parsed `--set` overrides to the central TOML files written by the
+ * installer. Called at the end of an install / quick-update.
+ *
+ * Routing per (module, key):
+ *   1. If `_bmad/config.user.toml` already has `[section] key`, update there
+ *      (user-scope key like `core.user_name`, `bmm.user_skill_level`).
+ *   2. Otherwise update `_bmad/config.toml` (team scope, the default).
+ *
+ * The schema-correct user/team partition lives in `manifest-generator`. We
+ * intentionally don't re-read module schemas here — the only goal is to
+ * match the file the installer just wrote the key to. For brand-new keys
+ * (not in either file yet), team scope is the safe default.
+ *
+ * @param {Object<string, Object<string, string>>} overrides
+ * @param {string} bmadDir absolute path to `_bmad/`
+ * @returns {Promise<Array<{module:string,key:string,scope:'team'|'user',file:string}>>}
+ *          a list of applied entries (for caller logging)
+ */
+async function applySetOverrides(overrides, bmadDir) {
+  const applied = [];
+  if (!overrides || typeof overrides !== 'object') return applied;
+
+  const teamPath = path.join(bmadDir, 'config.toml');
+  const userPath = path.join(bmadDir, 'config.user.toml');
+
+  for (const moduleCode of Object.keys(overrides)) {
+    // Skip overrides for modules not actually installed. The installer writes
+    // `_bmad/<module>/config.yaml` for every installed module (including core),
+    // so its presence is a reliable "is this module here?" signal that works
+    // for both fresh installs and quick-updates without coupling to caller-
+    // supplied module lists.
+    const moduleConfigYaml = path.join(bmadDir, moduleCode, 'config.yaml');
+    if (!(await fs.pathExists(moduleConfigYaml))) {
+      continue;
+    }
+
+    const section = sectionHeader(moduleCode);
+    const moduleOverrides = overrides[moduleCode] || {};
+    for (const key of Object.keys(moduleOverrides)) {
+      const value = moduleOverrides[key];
+      const valueToml = tomlString(value);
+
+      const userOwnsIt = await tomlHasKey(userPath, section, key);
+      const targetPath = userOwnsIt ? userPath : teamPath;
+
+      // The team file always exists post-install; the user file only exists
+      // if the install wrote at least one user-scope key. If we're routing to
+      // it but it doesn't exist yet, create it with a minimal header so it
+      // has the same shape as installer-written user toml.
+      let content = '';
+      if (await fs.pathExists(targetPath)) {
+        content = await fs.readFile(targetPath, 'utf8');
+      } else {
+        content = '# Personal overrides for _bmad/config.toml.\n';
+      }
+
+      const next = upsertTomlKey(content, section, key, valueToml);
+      await fs.writeFile(targetPath, next, 'utf8');
+      applied.push({
+        module: moduleCode,
+        key,
+        scope: userOwnsIt ? 'user' : 'team',
+        file: path.basename(targetPath),
+      });
+    }
+
+    // Also patch the per-module yaml (`_bmad/<module>/config.yaml`). The
+    // installer reads this file as `_existingConfig` on subsequent runs and
+    // surfaces declared values as prompt defaults — under `--yes` those
+    // defaults are accepted, so patching here gives `--set` natural
+    // carry-forward for declared keys without needing schema-strict
+    // partition exemptions in the manifest writer. For undeclared keys the
+    // value lives in the per-module yaml but won't be re-emitted into
+    // config.toml on the next install (the schema-strict partition drops
+    // it); re-pass `--set` if you need it sticky.
+    const moduleYamlPath = path.join(bmadDir, moduleCode, 'config.yaml');
+    if (await fs.pathExists(moduleYamlPath)) {
+      try {
+        const text = await fs.readFile(moduleYamlPath, 'utf8');
+        const parsed = yaml.parse(text);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          // Preserve the installer's banner header (everything up to the
+          // first non-comment line) so `_bmad/<module>/config.yaml` keeps
+          // its provenance comments after we round-trip it.
+          const headerLines = [];
+          for (const line of text.split('\n')) {
+            if (line.startsWith('#') || line.trim() === '') {
+              headerLines.push(line);
+            } else {
+              break;
+            }
+          }
+          for (const key of Object.keys(moduleOverrides)) {
+            parsed[key] = moduleOverrides[key];
+          }
+          const body = yaml.stringify(parsed, { indent: 2, lineWidth: 0, minContentWidth: 0 });
+          const header = headerLines.length > 0 ? headerLines.join('\n') + '\n' : '';
+          await fs.writeFile(moduleYamlPath, header + body, 'utf8');
+        }
+      } catch {
+        // Per-module yaml unparseable — skip silently. The central toml was
+        // already patched above, which is the user-visible state for the
+        // current install. Carry-forward will fail next install but the
+        // current install reflects the override.
+      }
+    }
+  }
+
+  return applied;
+}
+
+module.exports = { parseSetEntry, parseSetEntries, applySetOverrides, upsertTomlKey, tomlString };

package/tools/installer/ui.js

@@ -16,6 +16,7 @@ const {
 } = require('./modules/channel-plan');
 const channelResolver = require('./modules/channel-resolver');
 const prompts = require('./prompts');
+const { parseSetEntries } = require('./set-overrides');
 
 const manifest = new Manifest();
 
@@ -287,7 +288,7 @@ class UI {
         // Get tool selection
         const toolSelection = await this.promptToolSelection(confirmedDirectory, options);
 
-        const moduleConfigs = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
+        const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
           ...options,
           channelOptions,
         });
@@ -313,6 +314,7 @@ class UI {
           skipIde: toolSelection.skipIde,
           coreConfig: moduleConfigs.core || {},
           moduleConfigs: moduleConfigs,
+          setOverrides,
           skipPrompts: options.yes || false,
           channelOptions,
         };
@@ -364,7 +366,7 @@ class UI {
     await this._interactiveChannelGate({ options, channelOptions, selectedModules });
 
     let toolSelection = await this.promptToolSelection(confirmedDirectory, options);
-    const moduleConfigs = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
+    const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
       ...options,
       channelOptions,
     });
@@ -390,6 +392,7 @@ class UI {
       skipIde: toolSelection.skipIde,
       coreConfig: moduleConfigs.core || {},
       moduleConfigs: moduleConfigs,
+      setOverrides,
       skipPrompts: options.yes || false,
       channelOptions,
     };
@@ -709,6 +712,33 @@ class UI {
    */
   async collectModuleConfigs(directory, modules, options = {}) {
     const { OfficialModules } = require('./modules/official-modules');
+
+    // Parse --set up front purely to surface user-error before the install
+    // burns time on the network / filesystem. The actual application happens
+    // in installer.install() as a post-write TOML patch — see
+    // `tools/installer/set-overrides.js`. We also warn about overrides
+    // targeting modules the user didn't include, since those will silently
+    // miss the file the patch step looks for.
+    let setOverrides = {};
+    try {
+      setOverrides = parseSetEntries(options.set || []);
+    } catch (error) {
+      // install.js validated already; rethrow as-is for the user.
+      throw error;
+    }
+    // Drop overrides for modules that aren't in the install set so the
+    // post-install patch step doesn't create orphan sections in config.toml
+    // for modules that were never installed.
+    const selectedModuleSet = new Set(['core', ...modules]);
+    for (const moduleCode of Object.keys(setOverrides)) {
+      if (!selectedModuleSet.has(moduleCode)) {
+        await prompts.log.warn(
+          `--set ${moduleCode}.* — module '${moduleCode}' is not in the install set; values will be ignored. Add it to --modules to apply.`,
+        );
+        delete setOverrides[moduleCode];
+      }
+    }
+
     const configCollector = new OfficialModules({ channelOptions: options.channelOptions });
 
     // Seed core config from CLI options if provided
@@ -758,6 +788,9 @@ class UI {
         const defaultUsername = safeUsername.charAt(0).toUpperCase() + safeUsername.slice(1);
         configCollector.collectedConfig.core = {
           user_name: defaultUsername,
+          // {directory_name} default per src/core-skills/module.yaml — matches what the
+          // interactive flow resolves via buildQuestion()'s {directory_name} placeholder.
+          project_name: path.basename(directory),
           communication_language: 'English',
           document_output_language: 'English',
           output_folder: '_bmad-output',
@@ -771,7 +804,7 @@ class UI {
       skipPrompts: options.yes || false,
     });
 
-    return configCollector.collectedConfig;
+    return { moduleConfigs: configCollector.collectedConfig, setOverrides };
   }
 
   /**