@zeyue0329/xiaoma-cli 1.13.0 → 1.15.1

package/tools/{cli/lib → installer}/prompts.js

@@ -10,6 +10,9 @@
 let _clack = null;
 let _clackCore = null;
 let _picocolors = null;
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
 
 /**
  * Lazy-load @clack/prompts (ESM module)
@@ -498,26 +501,6 @@ async function password(options) {
   return result;
 }
 
-/**
- * Group multiple prompts together
- * @param {Object} prompts - Object of prompt functions
- * @param {Object} [options] - Group options
- * @returns {Promise<Object>} Object with all answers
- */
-async function group(prompts, options = {}) {
-  const clack = await getClack();
-
-  const result = await clack.group(prompts, {
-    onCancel: () => {
-      clack.cancel('Operation cancelled');
-      process.exit(0);
-    },
-    ...options,
-  });
-
-  return result;
-}
-
 /**
  * Run tasks with spinner feedback
  * @param {Array} tasks - Array of task objects [{title, task, enabled?}]
@@ -578,42 +561,6 @@ async function box(content, title, options) {
   clack.box(content, title, options);
 }
 
-/**
- * Create a progress bar for visualizing task completion
- * @param {Object} [options] - Progress options (max, style, etc.)
- * @returns {Promise<Object>} Progress controller with start, advance, stop methods
- */
-async function progress(options) {
-  const clack = await getClack();
-  return clack.progress(options);
-}
-
-/**
- * Create a task log for displaying scrolling subprocess output
- * @param {Object} options - TaskLog options (title, limit, retainLog)
- * @returns {Promise<Object>} TaskLog controller with message, success, error methods
- */
-async function taskLog(options) {
-  const clack = await getClack();
-  return clack.taskLog(options);
-}
-
-/**
- * File system path prompt with autocomplete
- * @param {Object} options - Path options
- * @param {string} options.message - The prompt message
- * @param {string} [options.initialValue] - Initial path value
- * @param {boolean} [options.directory=false] - Only allow directories
- * @param {Function} [options.validate] - Validation function
- * @returns {Promise<string>} Selected path
- */
-async function pathPrompt(options) {
-  const clack = await getClack();
-  const result = await clack.path(options);
-  await handleCancel(result);
-  return result;
-}
-
 /**
  * Autocomplete single-select prompt with type-ahead filtering
  * @param {Object} options - Autocomplete options
@@ -631,50 +578,151 @@ async function autocomplete(options) {
   return result;
 }
 
+function hasPathSeparator(value) {
+  return value.endsWith('/') || value.endsWith('\\');
+}
+
+function expandHome(input) {
+  if (!input) return input;
+  if (input === '~') return os.homedir();
+  if (input.startsWith('~/') || input.startsWith('~\\')) {
+    return path.join(os.homedir(), input.slice(2));
+  }
+  return input;
+}
+
+function toDirectoryOption(value, label = value, synthetic = false) {
+  return { value, label, synthetic };
+}
+
+function isExistingDirectory(value) {
+  try {
+    return fs.existsSync(value) && fs.statSync(value).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function listDirectoryOptions(input, options) {
+  const cwd = options.cwd || process.cwd();
+  const rawInput = input.trim();
+  const expandedInput = expandHome(rawInput);
+  const trailingSep = hasPathSeparator(rawInput) || hasPathSeparator(expandedInput);
+  const resolvedInput = expandedInput ? path.resolve(cwd, expandedInput) : cwd;
+  const browseDir = expandedInput && !trailingSep && !isExistingDirectory(resolvedInput) ? path.dirname(resolvedInput) : resolvedInput;
+  const prefix = expandedInput && browseDir !== resolvedInput ? path.basename(resolvedInput).toLowerCase() : '';
+  const results = [];
+
+  if (!trailingSep && isExistingDirectory(resolvedInput)) {
+    results.push(toDirectoryOption(resolvedInput, `. (use this directory)`));
+  }
+
+  if (isExistingDirectory(browseDir)) {
+    try {
+      for (const entry of fs.readdirSync(browseDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (prefix && !entry.name.toLowerCase().startsWith(prefix)) continue;
+        const fullPath = path.join(browseDir, entry.name);
+        if (!results.some((option) => option.value === fullPath)) {
+          results.push(toDirectoryOption(fullPath));
+        }
+      }
+    } catch {
+      // Skip unreadable directories; validation still reports path issues.
+    }
+  }
+
+  const validation = options.validate?.(rawInput);
+  const hasMatchingOption = results.some((option) => option.value === resolvedInput);
+  if (expandedInput && !validation && !hasMatchingOption) {
+    results.unshift(toDirectoryOption(resolvedInput, `Create/use: ${resolvedInput}`, true));
+  }
+
+  return results;
+}
+
 /**
- * Key-based instant selection prompt
- * @param {Object} options - SelectKey options
- * @param {string} options.message - The prompt message
- * @param {Array} options.options - Array of choices [{value, label, hint?}]
- * @returns {Promise<any>} Selected value
+ * Directory prompt with autocomplete candidates and create-directory support.
+ * Uses @clack/core directly so typed paths that do not exist yet can still be
+ * submitted when validation allows creating them.
+ * @param {Object} options - Prompt options
+ * @param {string} options.message - Prompt message
+ * @param {string} [options.default] - Default directory
+ * @param {string} [options.placeholder] - Placeholder text
+ * @param {Function} [options.validate] - Sync validation function
+ * @returns {Promise<string>} Selected or typed directory path
  */
-async function selectKey(options) {
-  const clack = await getClack();
-  const result = await clack.selectKey(options);
+async function directory(options) {
+  const core = await getClackCore();
+  const color = await getPicocolors();
+  const tabCompletion = {
+    prefix: '',
+    index: -1,
+    options: [],
+    lastValue: '',
+  };
+
+  let prompt;
+  prompt = new core.AutocompletePrompt({
+    initialValue: options.default,
+    options: () => listDirectoryOptions(prompt?.userInput || '', options),
+    filter: () => true,
+    validate: (value) => options.validate?.(value ?? prompt.userInput),
+    render() {
+      const title = `${color.gray('◆')}  ${options.message}`;
+      const bar = color.gray('│');
+      const barEnd = color.gray('└');
+      const userInput = this.userInput;
+      const placeholder = options.placeholder || options.default;
+      const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
+      const errorLine = this.state === 'error' ? [`${color.yellow('│')}  ${color.yellow(this.error)}`] : [];
+
+      switch (this.state) {
+        case 'submit': {
+          return `${color.gray('◇')}  ${options.message}\n${bar}  ${color.dim(this.value || '')}`;
+        }
+        case 'cancel': {
+          return `${color.gray('◇')}  ${options.message}\n${bar}  ${color.strikethrough(color.dim(userInput || ''))}`;
+        }
+        default: {
+          return [title, `${bar}  ${inputDisplay}`, ...errorLine, barEnd].join('\n');
+        }
+      }
+    },
+  });
+
+  const hasSetUserInput = typeof prompt._setUserInput === 'function';
+  const hasClearUserInput = typeof prompt._clearUserInput === 'function';
+
+  prompt.on('key', (_, key) => {
+    if (key?.name !== 'tab') return;
+    if (!hasSetUserInput) return; // @clack/core API surface changed — skip Tab silently.
+    const currentInput = prompt.userInput;
+    const isContinuingCycle = tabCompletion.lastValue && currentInput === tabCompletion.lastValue;
+    const completionOptions = isContinuingCycle ? tabCompletion.options : prompt.filteredOptions.filter((option) => !option.synthetic);
+    if (completionOptions.length === 0) return;
+
+    if (isContinuingCycle) {
+      tabCompletion.index = (tabCompletion.index + 1) % completionOptions.length;
+    } else {
+      tabCompletion.prefix = currentInput;
+      tabCompletion.options = completionOptions;
+      tabCompletion.index = 0;
+    }
+
+    const focusedOption = completionOptions[tabCompletion.index];
+    if (!focusedOption) return;
+    const completedValue = focusedOption.value;
+    tabCompletion.lastValue = completedValue;
+    if (hasClearUserInput) prompt._clearUserInput();
+    prompt._setUserInput(completedValue, true);
+  });
+
+  const result = await prompt.prompt();
   await handleCancel(result);
   return result;
 }
 
-/**
- * Stream messages with dynamic content (for LLMs, generators, etc.)
- */
-const stream = {
-  async info(generator) {
-    const clack = await getClack();
-    return clack.stream.info(generator);
-  },
-  async success(generator) {
-    const clack = await getClack();
-    return clack.stream.success(generator);
-  },
-  async step(generator) {
-    const clack = await getClack();
-    return clack.stream.step(generator);
-  },
-  async warn(generator) {
-    const clack = await getClack();
-    return clack.stream.warn(generator);
-  },
-  async error(generator) {
-    const clack = await getClack();
-    return clack.stream.error(generator);
-  },
-  async message(generator, options) {
-    const clack = await getClack();
-    return clack.stream.message(generator, options);
-  },
-};
-
 /**
  * Get the color utility (picocolors instance from @clack/prompts)
  * @returns {Promise<Object>} The color utility (picocolors)
@@ -790,20 +838,15 @@ module.exports = {
   note,
   box,
   spinner,
-  progress,
-  taskLog,
   select,
   multiselect,
   autocompleteMultiselect,
   autocomplete,
-  selectKey,
+  directory,
   confirm,
   text,
-  path: pathPrompt,
   password,
-  group,
   tasks,
   log,
-  stream,
   prompt,
 };

package/tools/installer/set-overrides.js

@@ -0,0 +1,367 @@
+// `--set <module>.<key>=<value>` is a post-install patch. The installer runs
+// its normal flow and writes `_xiaoma/config.toml`, `_xiaoma/config.user.toml`,
+// and `_xiaoma/<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 xmc.project_knowledge=research`
+//     writes "research" verbatim. Pass `--set xmc.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 `_xiaoma/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 `_xiaoma/config.user.toml` already has `[section] key`, update there
+ *      (user-scope key like `core.user_name`, `xmc.user_skill_level`).
+ *   2. Otherwise update `_xiaoma/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} xiaomaDir absolute path to `_xiaoma/`
+ * @returns {Promise<Array<{module:string,key:string,scope:'team'|'user',file:string}>>}
+ *          a list of applied entries (for caller logging)
+ */
+async function applySetOverrides(overrides, xiaomaDir) {
+  const applied = [];
+  if (!overrides || typeof overrides !== 'object') return applied;
+
+  const teamPath = path.join(xiaomaDir, 'config.toml');
+  const userPath = path.join(xiaomaDir, 'config.user.toml');
+
+  for (const moduleCode of Object.keys(overrides)) {
+    // Skip overrides for modules not actually installed. The installer writes
+    // `_xiaoma/<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(xiaomaDir, 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 _xiaoma/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 (`_xiaoma/<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(xiaomaDir, moduleCode, 'config.yaml');
+    await patchModuleYaml(moduleYamlPath, moduleOverrides, { onlyExisting: false });
+
+    // `--set core.<key>` must ALSO refresh the "Core Configuration Values"
+    // snapshot that `generateModuleConfigs` spreads into every non-core
+    // module yaml (e.g. `_xiaoma/xmc/config.yaml`). Those snapshots are
+    // written BEFORE the overrides are applied, and the auto-* pipelines
+    // read the per-module yaml directly at runtime — without this pass a
+    // non-interactive `--set core.communication_language=中文` lands in the
+    // toml + core/config.yaml but the pipelines still see the stale default.
+    // Only keys that already exist in the target yaml are updated (they are
+    // the snapshot keys); core-only keys never leak into module yamls.
+    if (moduleCode === 'core') {
+      const entries = await fs.readdir(xiaomaDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === 'core') continue;
+        const siblingYaml = path.join(xiaomaDir, entry.name, 'config.yaml');
+        if (await fs.pathExists(siblingYaml)) {
+          await patchModuleYaml(siblingYaml, moduleOverrides, { onlyExisting: true });
+        }
+      }
+    }
+  }
+
+  return applied;
+}
+
+/**
+ * Upsert key/value pairs into a per-module `config.yaml`, preserving the
+ * installer's banner header (leading comment block). With `onlyExisting`,
+ * only keys already present in the parsed yaml are updated — used for the
+ * core-snapshot refresh so core-only keys are not introduced into module
+ * yamls that never declared them.
+ *
+ * Unparseable yaml is skipped silently: the central toml was already
+ * patched, which is the user-visible state for the current install.
+ *
+ * @param {string} yamlPath absolute path to `_xiaoma/<module>/config.yaml`
+ * @param {Object<string, string>} keyValues
+ * @param {{onlyExisting: boolean}} opts
+ */
+async function patchModuleYaml(yamlPath, keyValues, { onlyExisting }) {
+  if (!(await fs.pathExists(yamlPath))) return;
+  try {
+    const text = await fs.readFile(yamlPath, 'utf8');
+    const parsed = yaml.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return;
+    // Preserve the installer's banner header (everything up to the
+    // first non-comment line) so the file 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;
+      }
+    }
+    let changed = false;
+    for (const key of Object.keys(keyValues)) {
+      if (onlyExisting && !Object.prototype.hasOwnProperty.call(parsed, key)) continue;
+      parsed[key] = keyValues[key];
+      changed = true;
+    }
+    if (!changed) return;
+    const body = yaml.stringify(parsed, { indent: 2, lineWidth: 0, minContentWidth: 0 });
+    const header = headerLines.length > 0 ? headerLines.join('\n') + '\n' : '';
+    await fs.writeFile(yamlPath, header + body, 'utf8');
+  } catch {
+    // Per-module yaml unparseable — skip silently (see doc comment).
+  }
+}
+
+module.exports = { parseSetEntry, parseSetEntries, applySetOverrides, upsertTomlKey, tomlString };