@ikunin/sprintpilot 2.1.1 → 2.1.3

package/lib/commands/install.js

@@ -31,6 +31,8 @@ const {
 } = require('../core/markers');
 const { renderString, buildContext, isTextFile } = require('../substitute');
 const { fetchLatestVersion, compareVersions } = require('../core/update-check');
+const { mergeYamlConfig, mergeTemplateFile } = require('../core/config-merger');
+const { scanForLeftoverSnapshots } = require('../core/v2-upgrade-recovery');
 const prompts = require('../prompts');
 
 const execFileAsync = promisify(execFile);
@@ -79,6 +81,37 @@ const RUNTIME_RESOURCES = [
   'scripts',
   'templates',
 ];
+
+// Files under _Sprintpilot/ that users edit. Step 6 nukes these along
+// with everything else when copying the bundled tree; we snapshot them
+// BEFORE step 6 and restore them AFTER, using a per-file strategy:
+//
+//   strategy: 'yaml'     — line-aware merge (config-merger.mergeYamlConfig).
+//                          User scalars patched into the freshly-copied
+//                          bundled file. Bundled comments + new keys
+//                          preserved. Orphan user keys land in a footer
+//                          `# Preserved from prior install` block.
+//
+//   strategy: 'template' — skip-if-exists. If the user file differs from
+//                          bundled, keep the user version verbatim and
+//                          write bundled next door as <file>.bundled.
+const USER_OWNED_FILES = [
+  { path: 'modules/git/config.yaml', strategy: 'yaml' },
+  { path: 'modules/ma/config.yaml', strategy: 'yaml' },
+  { path: 'modules/autopilot/config.yaml', strategy: 'yaml' },
+  { path: 'modules/git/templates/pr-body.md', strategy: 'template' },
+  { path: 'modules/git/templates/commit-story.txt', strategy: 'template' },
+  { path: 'modules/git/templates/commit-patch.txt', strategy: 'template' },
+  { path: '.secrets-allowlist', strategy: 'template' },
+];
+
+// Explicit dot-path renames the installer maps when reading old user
+// configs. Empty for the 2.1.x baseline; add entries when a future
+// release renames a key so user customizations land at the new path.
+const KEY_RENAMES = Object.freeze({
+  // 'old.dotted.path': 'new.dotted.path'
+});
+
 const V1_MODULE_NAMES = ['git', 'ma', 'autopilot'];
 
 // Sentinel thrown by evictV1Installation when the user declines migration.
@@ -275,6 +308,99 @@ async function applyV1ModuleConfigs(projectRoot, snapshot) {
   return applied;
 }
 
+// Snapshot user-owned files BEFORE the destructive step-6 copy. For each
+// path in USER_OWNED_FILES that exists under targetAddonDir today, capture
+// its current content along with the strategy. Returns an array; entries
+// for files that don't exist yet (fresh installs) are simply absent.
+async function snapshotUserOwnedFiles(targetAddonDir) {
+  const out = [];
+  for (const entry of USER_OWNED_FILES) {
+    const abs = path.join(targetAddonDir, entry.path);
+    if (!(await fs.pathExists(abs))) continue;
+    try {
+      const buffer = await fs.readFile(abs);
+      out.push({ path: entry.path, strategy: entry.strategy, buffer });
+    } catch {
+      // Unreadable user file — skip; the bundled default will land.
+    }
+  }
+  return out;
+}
+
+// Apply the user-owned snapshot back over the freshly-copied bundled files,
+// using the per-file strategy. Writes are atomic via writeAtomic. Returns
+// an array of `{ path, strategy, preserved, orphans, sidecar }` describing
+// what happened for each file — the caller pretty-prints this to the user.
+async function applyUserOwnedFiles(targetAddonDir, snapshot, keyRenames = {}) {
+  const results = [];
+  for (const entry of snapshot) {
+    const abs = path.join(targetAddonDir, entry.path);
+    const userText = entry.buffer.toString('utf8');
+    let bundledText = '';
+    try {
+      bundledText = await fs.readFile(abs, 'utf8');
+    } catch {
+      // Bundled file no longer ships at this path — treat user file as
+      // an orphan: keep it as-is, no sidecar (nothing to compare against).
+      await writeAtomic(abs, entry.buffer);
+      results.push({
+        path: entry.path,
+        strategy: entry.strategy,
+        preserved: [],
+        orphans: [],
+        sidecar: false,
+        note: 'bundled file no longer ships; user copy preserved',
+      });
+      continue;
+    }
+
+    if (entry.strategy === 'yaml') {
+      const r = mergeYamlConfig(bundledText, userText, keyRenames);
+      if (r.fallback) {
+        // Merge couldn't parse — fall back to template strategy so the
+        // user doesn't lose their file. Sidecar the bundled version.
+        const t = mergeTemplateFile(bundledText, userText);
+        await writeAtomic(abs, t.text);
+        if (t.sidecar !== null) {
+          await writeAtomic(`${abs}.bundled`, t.sidecar);
+        }
+        results.push({
+          path: entry.path,
+          strategy: 'template-fallback',
+          preserved: [],
+          orphans: [],
+          sidecar: t.sidecar !== null,
+          note: 'YAML merge fell back to skip-if-exists',
+        });
+        continue;
+      }
+      await writeAtomic(abs, r.text);
+      results.push({
+        path: entry.path,
+        strategy: 'yaml',
+        preserved: r.preserved,
+        orphans: r.orphans,
+        sidecar: false,
+      });
+    } else {
+      // template strategy
+      const t = mergeTemplateFile(bundledText, userText);
+      await writeAtomic(abs, t.text);
+      if (t.sidecar !== null) {
+        await writeAtomic(`${abs}.bundled`, t.sidecar);
+      }
+      results.push({
+        path: entry.path,
+        strategy: 'template',
+        preserved: t.kept === 'user' ? ['(verbatim)'] : [],
+        orphans: [],
+        sidecar: t.sidecar !== null,
+      });
+    }
+  }
+  return results;
+}
+
 // Emergency fallback when applyV1ModuleConfigs throws: the in-memory
 // snapshot is stringified to a recovery file so the user can re-apply
 // manually after fixing whatever blocked the write. Without this the
@@ -976,6 +1102,31 @@ async function runInstall(options = {}) {
   process.stdout.write(pc.cyan(renderBanner(addonVersion)));
   console.log('');
 
+  // 0a. Recovery banner: surface any leftover backups/snapshots from a
+  //     prior installer run that may have silently clobbered user configs
+  //     before v2.1.2's preservation logic landed. Read-only; nothing is
+  //     deleted — the user decides.
+  try {
+    const leftovers = await scanForLeftoverSnapshots(projectRoot);
+    if (leftovers.length > 0) {
+      console.log(
+        pc.yellow('NOTE: detected leftover config snapshots from a prior install:'),
+      );
+      for (const f of leftovers) {
+        console.log(pc.yellow(`  - ${path.relative(projectRoot, f)}`));
+      }
+      console.log(
+        pc.yellow(
+          '  These may contain config you customized but lost during a prior upgrade.',
+        ),
+      );
+      console.log(pc.yellow('  Review before deleting.'));
+      console.log('');
+    }
+  } catch {
+    // Non-fatal — banner is purely informational.
+  }
+
   // 1. Verify BMad Method installed
   const bmadManifest = await verifyBmadInstalled(projectRoot);
   if (!bmadManifest) {
@@ -1216,6 +1367,12 @@ async function runInstall(options = {}) {
   if (dryRun) {
     console.log(pc.dim(`[DRY RUN] Would copy runtime resources to ${targetAddonDir}`));
   } else {
+    // 6-pre. Snapshot user-owned files BEFORE the destructive copy. On a
+    //        fresh install the snapshot is empty; on upgrade it captures
+    //        config.yaml edits, template customizations, and the secrets
+    //        allowlist so they can be re-applied after step 6.
+    const userOwnedSnapshot = await snapshotUserOwnedFiles(targetAddonDir);
+
     await fs.ensureDir(targetAddonDir);
     for (const item of RUNTIME_RESOURCES) {
       const src = path.join(ADDON_DIR, item);
@@ -1279,6 +1436,42 @@ async function runInstall(options = {}) {
     //     so the existing upgrade test coverage (readExistingAutopilotConfig /
     //     patchAutopilotConfig) is unaffected by the new key.
     await patchComplexityProfile(projectRoot, complexityProfile);
+
+    // 6d. Re-apply the user-owned snapshot taken before step 6. YAML configs
+    //     get a line-aware merge (user scalars patched into the freshly
+    //     copied bundled file, comments preserved, new bundled keys land).
+    //     Templates fall back to skip-if-exists with a .bundled sidecar.
+    //     Runs AFTER 6a (v1 reapply) and AFTER 6b / 6c so prompt-resolved
+    //     autopilot values are not overwritten by a stale snapshot.
+    if (userOwnedSnapshot.length > 0) {
+      const merged = await applyUserOwnedFiles(targetAddonDir, userOwnedSnapshot, KEY_RENAMES);
+      let anySidecar = false;
+      for (const r of merged) {
+        const detail =
+          r.strategy === 'yaml' && r.preserved.length > 0
+            ? ` (preserved ${r.preserved.length} setting${r.preserved.length === 1 ? '' : 's'})`
+            : r.strategy === 'template' && r.preserved.length > 0
+              ? ' (kept user version)'
+              : '';
+        console.log(`  Preserved ${r.path}${detail}`);
+        if (r.note) console.log(pc.dim(`    note: ${r.note}`));
+        if (r.orphans && r.orphans.length > 0) {
+          console.log(
+            pc.dim(`    orphan keys appended to file footer: ${r.orphans.join(', ')}`),
+          );
+        }
+        if (r.sidecar) anySidecar = true;
+      }
+      if (anySidecar) {
+        console.log('');
+        console.log(
+          pc.yellow(
+            '  Some bundled defaults were written next to user files as .bundled sidecars.',
+          ),
+        );
+        console.log(pc.yellow('  Diff them by hand to pick up new options.'));
+      }
+    }
   }
 
   // 7. Verify git check-ignore
@@ -1380,5 +1573,9 @@ module.exports = {
     COMPLEXITY_PROFILES,
     DEFAULT_COMPLEXITY_PROFILE,
     RUNTIME_RESOURCES,
+    USER_OWNED_FILES,
+    KEY_RENAMES,
+    snapshotUserOwnedFiles,
+    applyUserOwnedFiles,
   },
 };

package/lib/core/config-merger.js

@@ -0,0 +1,238 @@
+// config-merger.js — preserve user edits when the installer rewrites
+// _Sprintpilot/ on upgrade.
+//
+// Two strategies, picked per-file in `lib/commands/install.js`:
+//
+//   mergeYamlConfig(bundledText, userText, keyRenames)
+//     For modules/*/config.yaml. Bundled file is freshly copied. We
+//     parse both files into flat dot-path → scalar maps, compute the
+//     user-customized set (paths whose user value differs from bundled
+//     default OR doesn't exist in bundled), and patch each customization
+//     back into the bundled text by line-substitution. Bundled inline
+//     comments and section structure are preserved verbatim.
+//
+//   mergeTemplateFile(bundledText, userText)
+//     For free-form templates (.md / .txt / .secrets-allowlist) where
+//     line-based YAML merging doesn't apply. If user file exists and
+//     differs from bundled, keep the user file; the caller writes the
+//     bundled version next door as a .bundled sidecar so the user can
+//     diff and merge by hand.
+//
+// Both functions are pure. They never read or write disk; the caller
+// (applyUserOwnedFiles in install.js) owns I/O via writeAtomic.
+
+// -----------------------------------------------------------------------------
+// YAML scalar/path parsing
+// -----------------------------------------------------------------------------
+
+// One non-empty, non-comment line of the form:
+//   <indent><key>: [value][ # trailing-comment]
+// Captures: indent, key, value-with-optional-trailing-comment.
+const KV_RE = /^(?<indent>\s*)(?<key>[A-Za-z_][\w-]*):\s*(?<rest>.*)$/;
+const COMMENT_ONLY_RE = /^\s*#/;
+const BLANK_RE = /^\s*$/;
+
+function isBlank(line) {
+  return BLANK_RE.test(line);
+}
+
+function isCommentOnly(line) {
+  return COMMENT_ONLY_RE.test(line);
+}
+
+// Split a value-and-maybe-trailing-comment chunk (the `rest` capture above)
+// into { value, trailing } where `trailing` is everything from the first
+// unquoted `#` onward (with its leading whitespace). YAML inline comments
+// require whitespace before the `#`, which `KV_RE` already enforces by
+// matching the colon-then-whitespace before `rest`.
+function splitInlineComment(rest) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < rest.length; i++) {
+    const ch = rest[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '#' && !inSingle && !inDouble) {
+      // YAML requires whitespace before `#` for an inline comment.
+      if (i === 0 || /\s/.test(rest[i - 1])) {
+        return { value: rest.slice(0, i).trimEnd(), trailing: rest.slice(i) };
+      }
+    }
+  }
+  return { value: rest.trimEnd(), trailing: '' };
+}
+
+// Parse a YAML-ish file into a flat map of dot-paths → string values.
+// Lines that don't match `KV_RE` are ignored. Container lines (`key:`
+// with empty value followed by deeper-indented children) are tracked
+// via an indent stack so dot-paths nest correctly. Throws on malformed
+// indentation; the caller catches and falls back to template strategy.
+function parseFlat(text) {
+  const lines = text.split(/\r?\n/);
+  const stack = []; // [{ indent: number, key: string }]
+  const out = Object.create(null);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isBlank(line) || isCommentOnly(line)) continue;
+    const m = line.match(KV_RE);
+    if (!m) continue; // list items, multi-line strings, etc. — not in our scope
+    const indent = m.groups.indent.length;
+    const key = m.groups.key;
+    const { value } = splitInlineComment(m.groups.rest);
+    // Pop deeper-or-equal scopes off the stack.
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const path = [...stack.map((s) => s.key), key].join('.');
+    if (value.length === 0) {
+      // Container — push and continue. Don't record an empty scalar.
+      stack.push({ indent, key });
+    } else {
+      out[path] = value;
+    }
+  }
+  return out;
+}
+
+// Patch a single scalar value at the given dot-path into the bundled
+// text. Returns the new text. If the path can't be found, returns the
+// text unchanged (the caller decides whether to append the orphan).
+function patchScalarInPlace(text, dotPath, newValue) {
+  const targetSegments = dotPath.split('.');
+  const lines = text.split(/\r?\n/);
+  const stack = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isBlank(line) || isCommentOnly(line)) continue;
+    const m = line.match(KV_RE);
+    if (!m) continue;
+    const indent = m.groups.indent.length;
+    const key = m.groups.key;
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const currentPath = [...stack.map((s) => s.key), key];
+    const isContainer = m.groups.rest.length === 0;
+    if (isContainer) {
+      stack.push({ indent, key });
+      continue;
+    }
+    if (
+      currentPath.length === targetSegments.length &&
+      currentPath.every((seg, idx) => seg === targetSegments[idx])
+    ) {
+      const { trailing } = splitInlineComment(m.groups.rest);
+      const sep = trailing ? ' ' : '';
+      lines[i] = `${m.groups.indent}${key}: ${newValue}${sep}${trailing}`;
+      return lines.join('\n');
+    }
+  }
+  return text; // not found — caller may append as orphan
+}
+
+// -----------------------------------------------------------------------------
+// Public: mergeYamlConfig
+// -----------------------------------------------------------------------------
+
+/**
+ * Merge user YAML into freshly-copied bundled YAML, preserving the
+ * bundled file's structure and inline comments.
+ *
+ * @param {string} bundledText - the freshly-copied bundled file contents
+ * @param {string} userText - the user's pre-upgrade contents
+ * @param {Object<string, string>} keyRenames - { 'old.path': 'new.path' }
+ * @returns {{ text: string, preserved: string[], orphans: string[], fallback: boolean }}
+ *   text: merged file text to write
+ *   preserved: dot-paths whose user value was patched into the bundled text
+ *   orphans: dot-paths present only in user (appended as a footer block)
+ *   fallback: true if parse failed and we returned bundledText unchanged
+ */
+function mergeYamlConfig(bundledText, userText, keyRenames = {}) {
+  if (typeof bundledText !== 'string' || typeof userText !== 'string') {
+    return { text: bundledText || '', preserved: [], orphans: [], fallback: true };
+  }
+  let bundledMap;
+  let userMap;
+  try {
+    bundledMap = parseFlat(bundledText);
+    userMap = parseFlat(userText);
+  } catch {
+    return { text: bundledText, preserved: [], orphans: [], fallback: true };
+  }
+
+  // Apply renames before computing the diff: a user key at `old.path`
+  // is treated as if it sat at `new.path`.
+  const renamed = Object.create(null);
+  for (const [k, v] of Object.entries(userMap)) {
+    const remapped = Object.hasOwn(keyRenames, k) ? keyRenames[k] : k;
+    renamed[remapped] = v;
+  }
+
+  let text = bundledText;
+  const preserved = [];
+  const orphans = [];
+
+  for (const [path, userValue] of Object.entries(renamed)) {
+    const bundledValue = bundledMap[path];
+    if (bundledValue === userValue) continue; // no customization
+    if (bundledValue === undefined) {
+      orphans.push(path);
+      continue;
+    }
+    const next = patchScalarInPlace(text, path, userValue);
+    if (next === text) {
+      // Path exists in bundled map but couldn't be re-located — treat as
+      // orphan rather than silently dropping the user value.
+      orphans.push(path);
+    } else {
+      text = next;
+      preserved.push(path);
+    }
+  }
+
+  if (orphans.length > 0) {
+    // Append as a clearly-labeled footer block so the user notices and
+    // can re-integrate or delete by hand. Use a `# Preserved` header
+    // followed by literal `key: value` lines — these will round-trip
+    // through `parseFlat` on the next upgrade.
+    const footer = [
+      '',
+      '# Preserved from prior install — verify these still apply:',
+      ...orphans.map((p) => `# ${p}: ${renamed[p]}`),
+      '',
+    ].join('\n');
+    text = text.endsWith('\n') ? text + footer : text + '\n' + footer;
+  }
+
+  return { text, preserved, orphans, fallback: false };
+}
+
+// -----------------------------------------------------------------------------
+// Public: mergeTemplateFile
+// -----------------------------------------------------------------------------
+
+/**
+ * For free-form template files (.md / .txt / .secrets-allowlist).
+ *
+ * @param {string} bundledText - freshly-copied bundled contents
+ * @param {string|null} userText - user's pre-upgrade contents, or null/undefined if absent
+ * @returns {{ kept: 'user' | 'bundled', text: string, sidecar: string | null }}
+ *   When kept === 'user', `text` is the user contents and `sidecar` is the
+ *   bundled contents (caller writes it as <file>.bundled). When kept ===
+ *   'bundled', `text` is the bundled contents and `sidecar` is null.
+ */
+function mergeTemplateFile(bundledText, userText) {
+  const bundled = typeof bundledText === 'string' ? bundledText : '';
+  const user = typeof userText === 'string' ? userText : '';
+  if (user.length === 0 || user === bundled) {
+    return { kept: 'bundled', text: bundled, sidecar: null };
+  }
+  return { kept: 'user', text: user, sidecar: bundled };
+}
+
+module.exports = {
+  mergeYamlConfig,
+  mergeTemplateFile,
+  // Exported for tests only.
+  _internals: { parseFlat, patchScalarInPlace, splitInlineComment },
+};

package/lib/core/v2-upgrade-recovery.js

@@ -0,0 +1,47 @@
+// v2-upgrade-recovery.js — detect leftover snapshot/backup files from
+// prior installer runs that may have silently clobbered user configs.
+//
+// Used at the top of `runInstall` to print a banner pointing the user
+// at recoverable data. Returns paths only; the installer never deletes
+// these — the user decides when they've been restored or are safe to
+// discard.
+
+const path = require('node:path');
+const fs = require('fs-extra');
+
+// Patterns we scan for, relative to projectRoot:
+//   - *.bak-sprintpilot-migration*       (legacy marker strip backups)
+//   - .sprintpilot-v1-snapshot*.json     (v1 module-config recovery dumps)
+//
+// Both are written today by the v1→v2 migration path (lib/commands/install.js
+// pickBackupPath + persistSnapshotForRecovery). The same pattern could end
+// up triggered if a future installer hits a write failure mid-merge.
+
+const BACKUP_GLOB = /\.bak-sprintpilot-migration/;
+const SNAPSHOT_GLOB = /^\.sprintpilot-v1-snapshot.*\.json$/;
+
+async function scanForLeftoverSnapshots(projectRoot) {
+  const out = [];
+  // Top-level scan only (non-recursive). The two patterns are always
+  // written at the project root or alongside the file they backed up.
+  try {
+    const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (SNAPSHOT_GLOB.test(entry.name) || BACKUP_GLOB.test(entry.name)) {
+        out.push(path.join(projectRoot, entry.name));
+      }
+    }
+  } catch {
+    // projectRoot unreadable — caller can't act on the banner anyway.
+    return out;
+  }
+
+  // Also scan a couple of well-known directories where backup files
+  // accumulate (AGENTS.md.bak-sprintpilot-migration is at root, but
+  // .clinerules.bak-... could live wherever the rules file lives).
+  // For now, root-only is enough — extend if real reports surface.
+  return out;
+}
+
+module.exports = { scanForLeftoverSnapshots };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikunin/sprintpilot",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Sprintpilot — autopilot and multi-agent addon for BMad Method v6: git workflow, parallel agents, autonomous story execution",
   "license": "Apache-2.0",
   "repository": {