baldart 4.7.0 → 4.8.0

package/src/commands/update.js

@@ -4,6 +4,7 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
 const UpdateNotifier = require('../utils/update-notifier');
+const { captureAndVerify } = require('../utils/overlay-capture');
 
 function readEnabledTools(cwd = process.cwd()) {
   try {
@@ -115,6 +116,28 @@ function isBaldartManagedPath(p) {
   return BALDART_MANAGED_PATTERNS.some((rx) => rx.test(p));
 }
 
+// Real preview (v4.8.0+) — the old `git log HEAD..FETCH_HEAD -- .framework/`
+// is always empty under subtree-squash, so the user never saw what changed.
+// Instead, read the UPSTREAM CHANGELOG and return every entry above the
+// version we already have. Best-effort; returns null when unavailable.
+async function changelogSinceInstalled(git, installedVersion) {
+  let text;
+  try { text = await git.git.raw(['show', 'FETCH_HEAD:CHANGELOG.md']); }
+  catch (_) { return null; }
+  const out = [];
+  let started = false;
+  for (const line of text.split('\n')) {
+    const m = /^##\s+\[?v?(\d+\.\d+\.\d+)\]?/.exec(line);
+    if (m) {
+      if (m[1] === installedVersion) break; // reached the version already on disk
+      started = true;
+    }
+    if (started) out.push(line);
+    if (out.length > 120) { out.push('  … (truncated — see .framework/CHANGELOG.md)'); break; }
+  }
+  return out.join('\n').trim() || null;
+}
+
 async function postUpdateAutoCommit(git, newVersion, options) {
   if (options && options.commit === false) {
     UI.info('Auto-commit skipped (--no-commit).');
@@ -185,6 +208,129 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   }
 }
 
+// Single auto-stash engine (v4.8.0+). The ONE place that protects a dirty
+// working tree before a `git subtree pull` (normal flow) OR a `--reset`
+// reinstall. Uses a blanket `git stash push -u` with NO pathspec — a pathspec
+// that lands on a `.gitignore`d directory is exactly what made the previous
+// manual-stash workaround fail. Tracked-but-ignored files (a `.gitignore` that
+// post-dates the file) are still stashed by plain stash; purely-ignored
+// untracked files don't block the pull and aren't added by `git add -A`, so
+// leaving them in place is harmless.
+//
+// Returns { stashRef } on success (or { stashRef: null } when already clean),
+// { aborted: true } when the user declined, or { error } when the stash failed.
+async function autoStashNonFramework(git, { autoStash, interactive }) {
+  const isClean = await git.hasCleanWorkingTree();
+  if (isClean) return { stashRef: null };
+
+  UI.newline();
+  UI.warning('Working tree has uncommitted changes — they will be stashed and re-applied after the update.');
+  const dirty = await git.git.status();
+  const dirtyPaths = [
+    ...dirty.not_added, ...dirty.modified, ...dirty.created,
+    ...dirty.deleted, ...dirty.renamed.map((r) => r.to), ...dirty.staged
+  ];
+  const unique = [...new Set(dirtyPaths)];
+  UI.info(`${unique.length} dirty path(s):`);
+  UI.list(unique.slice(0, 8), 'yellow');
+  if (unique.length > 8) UI.info(`…and ${unique.length - 8} more.`);
+
+  let action = 'stash';
+  if (!autoStash && interactive) {
+    action = await UI.select('How would you like to proceed?', [
+      { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
+      { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
+    ]);
+  } else {
+    UI.info('Auto-stashing dirty paths.');
+  }
+  if (action === 'abort') return { aborted: true };
+
+  const stashRef = `baldart-pre-update-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  try {
+    await git.git.stash(['push', '-u', '-m', stashRef]);
+    UI.success(`Stashed working tree as "${stashRef}".`);
+    return { stashRef };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+// Seamless resolution of `overlay-able` divergence (v4.8.0+). The user's intent
+// is always the same — update and preserve overlays — so this never dead-ends:
+//   - every divergent edit verifiably preserved by an overlay (existing or
+//     freshly captured) → reset-and-reapply (the `.framework/` commits are
+//     redundant; the overlays survive and re-apply on reinstall).
+//   - anything that can't be captured+verified (stale overlay, section deletion,
+//     frontmatter/preamble change, skill with no overlay, unmappable path) →
+//     stop ONCE with the exact list, so nothing is silently lost.
+// On success this calls runReset (which exits the process). On an unrecoverable
+// blocker it emits the single-pause refuse and exits.
+//
+// Pass the FULL touched set to captureAndVerify — never a pre-filtered subset.
+// An overlay-able commit (per classifyCommitByPaths) only touches files under
+// `.claude/{agents,commands,skills}/`, but some (nested agent files, etc.) are
+// not overlay-mappable; pre-filtering them out would let the reset wipe them
+// with no overlay to preserve them. captureAndVerify turns those into blockers.
+async function resolveOverlayDivergenceSeamlessly(git, status, options, autoYes, overlayCommits, remoteVersion) {
+  const cwd = process.cwd();
+  const touched = [...new Set(overlayCommits.flatMap((c) => c.touched || []))];
+
+  UI.newline();
+  UI.info(`Verifying ${touched.length} divergent edit(s) are preserved by overlays (auto-capture + verify)…`);
+  const { captured, blockers } = await captureAndVerify({
+    cwd, git, files: touched, frameworkVersion: remoteVersion,
+  });
+  for (const o of captured) UI.success(`Overlay verified: ${o}`);
+
+  // Commit captured overlays NOW, before the reset. The reset auto-stashes the
+  // working tree, and the symlink/merge step reads overlays FROM DISK — an
+  // untracked, stashed overlay would be invisible to the merge and the
+  // regenerated agent would silently drop the customization. Committing pins
+  // them into HEAD so they survive the reset and feed the merge. (Already-
+  // committed, unchanged overlays stage to nothing and are skipped.)
+  if (captured.length) {
+    try {
+      await git.git.add(captured);
+      const st = await git.git.status();
+      if (st.staged.length) {
+        await git.git.commit(
+          'chore(baldart): capture/verify overlays for divergent framework edits\n\n'
+          + captured.map((c) => `  - ${c}`).join('\n')
+        );
+        UI.success(`Committed ${st.staged.length} overlay file(s).`);
+      }
+    } catch (err) {
+      UI.warning(`Could not commit overlays: ${err.message} — they remain in the working tree.`);
+    }
+  }
+
+  if (blockers.length) {
+    UI.newline();
+    UI.error(`${blockers.length} edit(s) could not be preserved+verified — stopping so nothing is lost:`);
+    UI.list(blockers.map((b) => `${b.file} — ${b.reason}`), 'yellow');
+    UI.newline();
+    UI.info('Resolve these, then re-run `npx baldart update`:');
+    UI.list([
+      'Author / reconcile the overlay with `/overlay` (Claude Code) or `npx baldart overlay scaffold`.',
+      'Or contribute the edit upstream with `/baldart-push` if it is a generic improvement.',
+      'Or keep the commits and merge with `npx baldart update --on-divergence pull`.',
+    ], 'cyan');
+    emitUpdateJson({ ok: false, action: 'divergence-capture-incomplete',
+      divergence_class: status.divergenceClass,
+      captured, blockers,
+      installed_before: status.installedVersion, remote_version: status.remoteVersion,
+      reason: `Preserved ${captured.length} edit(s); ${blockers.length} could not be captured+verified — stopped to avoid data loss.`,
+      next_command: 'npx baldart update --on-divergence pull' }, 1);
+  }
+
+  UI.newline();
+  UI.success('All divergent edits are preserved & verified in `.baldart/overlays/` — resolving via clean reinstall (overlays are re-applied).');
+  // iKnow is implied: the only files reset deletes inside `.framework/` are
+  // framework artifacts that get reinstalled, and every edit is now overlaid.
+  await runReset(git, { ...options, reset: true, iKnow: true }, autoYes);
+}
+
 // --reset nuclear option (v3.26.0+).
 //
 // When the standard update keeps failing due to subtree divergence the user
@@ -220,13 +366,25 @@ async function runReset(git, options, autoYes) {
     '.claude/{agents,skills,commands}/*.md authored by you (non-framework symlinks)',
   ], 'cyan');
 
-  // Safety gate #1: working tree MUST be clean.
-  const clean = await git.hasCleanWorkingTree();
-  if (!clean) {
-    UI.error('Working tree is dirty. Commit or `git stash -u` first, then re-run.');
-    UI.info('Reset cannot run with pending changes — too easy to lose work.');
+  // Safety gate #1: protect any non-framework work. The reset commits a
+  // `git add -A` (the .framework/ deletion), so a dirty tree would otherwise be
+  // swept into that commit — auto-stash it instead and re-apply at the end.
+  // Same engine the normal flow uses; honours the user's stash authorization
+  // instead of hard-refusing (the v4.8.0 fix).
+  const stashOutcome = await autoStashNonFramework(git, {
+    autoStash: autoYes || options.autoStash === true,
+    interactive: !autoYes,
+  });
+  if (stashOutcome.aborted) { UI.info('Reset aborted.'); process.exit(0); }
+  if (stashOutcome.error) {
+    UI.error(`Could not stash working tree before reset: ${stashOutcome.error}`);
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'failed',
+        reason: `Could not stash working tree before reset: ${stashOutcome.error}` }, 1);
+    }
     process.exit(1);
   }
+  const resetStashRef = stashOutcome.stashRef;
 
   // Safety gate #2: any untracked / ignored files inside .framework/?
   let untrackedInsideFramework = '';
@@ -369,9 +527,38 @@ async function runReset(git, options, autoYes) {
     process.exit(1);
   }
 
+  const newVersion = await git.getFrameworkVersion();
+
+  // Finalizer (v4.8.0+): re-apply the stash and commit BALDART-managed
+  // artifacts so the reset path leaves a clean tree — exactly like the normal
+  // update flow. Without this, the freshly-regenerated agents + state.json were
+  // left uncommitted (the half-done handoff the seamless rewrite removes).
+  let stashConflict = false;
+  if (resetStashRef) {
+    try {
+      await git.git.stash(['pop']);
+      UI.success(`Re-applied pre-reset stash "${resetStashRef}".`);
+    } catch (err) {
+      stashConflict = true;
+      UI.warning(`Could not auto-re-apply stash "${resetStashRef}": ${err.message}`);
+      UI.info('Recover with: git stash list && git stash pop');
+    }
+  }
+  try {
+    await postUpdateAutoCommit(git, newVersion, options);
+  } catch (err) {
+    UI.warning(`Auto-commit step skipped: ${err.message}`);
+  }
+
+  if (JSON_MODE) {
+    emitUpdateJson({ ok: true, action: 'reset',
+      installed_after: newVersion, remote_version: newVersion,
+      backup_tag: backupTag, stash_conflict: stashConflict }, 0);
+  }
+
   UI.header('✓ RESET COMPLETE');
   UI.box('RESET RESULT', [
-    `Framework: fresh install (${await git.getFrameworkVersion()})`,
+    `Framework: fresh install (${newVersion})`,
     `Backup tag: ${backupTag}`,
     `Rollback if needed: git reset --hard ${backupTag}`,
     '',
@@ -705,13 +892,10 @@ async function update(options = {}, unknownArgs = []) {
         // picks the cheap, correct resolution. (v3.33.0)
         const allCovered = overlayCommits.length > 0
           && overlayCommits.every((c) => c.overlayCovered === true);
-        if (allCovered) {
-          UI.newline();
-          UI.success('These edits are already preserved in `.baldart/overlays/` — `--reset` is safe (your overlays are re-applied); scaffolding new overlays would be redundant.');
-          UI.info('Fast path: `npx baldart update --reset --yes --i-know`.');
-        }
 
-        // Non-interactive resolution (agents / CI) via --on-divergence.
+        // Explicit, non-interactive overrides (agents / CI) via --on-divergence
+        // still win. With NO strategy the DEFAULT is now seamless (v4.8.0+):
+        // capture+verify any uncovered edit, then reset-and-reapply — no flag maze.
         if (divStrategy === 'scaffold-overlays') {
           UI.newline();
           scaffoldOverlaysForCommits(overlayCommits);
@@ -736,49 +920,14 @@ async function update(options = {}, unknownArgs = []) {
         }
         if (divStrategy === 'pull') {
           UI.info('Keeping the custom commits (--on-divergence pull). The subtree pull will attempt a merge.');
-          // fall through
-        } else if (autoYes) {
-          // --yes without an explicit strategy: never silently overwrite. Tell
-          // the (likely non-TTY) caller exactly which flag completes the update.
-          UI.error('Custom edits present — refusing to resolve them unattended under --yes.');
-          UI.info('Re-run with one of:');
-          UI.list([
-            allCovered
-              ? '--reset --yes --i-know             → SAFE here: these edits are already in `.baldart/overlays/` (recommended)'
-              : '--on-divergence scaffold-overlays  → auto-create overlay skeleton(s), then stop so you can fill them',
-            '--on-divergence pull               → keep the commits and merge the update (non-destructive)',
-            allCovered
-              ? '--on-divergence scaffold-overlays  → would create redundant skeletons (edits already covered)'
-              : '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
-          ], 'cyan');
-          emitUpdateJson({ ok: false, action: 'divergence-refused',
-            divergence_class: status.divergenceClass, overlay_already_covered: allCovered,
-            installed_before: status.installedVersion, remote_version: status.remoteVersion,
-            reason: allCovered
-              ? 'Custom edits present but already preserved in .baldart/overlays/ — `--reset --yes --i-know` is the safe resolution.'
-              : 'Custom edits present — refusing to resolve them unattended under --yes.',
-            next_command: allCovered
-              ? 'npx baldart update --reset --yes --i-know'
-              : 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 1);
+          // fall through to the subtree pull below
         } else {
-          const choice = await UI.select('How would you like to proceed?', [
-            { name: 'Scaffold overlay skeleton(s) now (recommended — then fill them in & re-run)', value: 'overlay' },
-            { name: 'Keep the custom commits (subtree pull may conflict)', value: 'keep' },
-            { name: 'Abort', value: 'abort' },
-          ]);
-          if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
-          if (choice === 'overlay') {
-            UI.newline();
-            scaffoldOverlaysForCommits(overlayCommits);
-            UI.newline();
-            UI.info('Next steps:');
-            UI.list([
-              'Edit the overlay skeleton(s) above to capture your customisations (`/overlay` from Claude Code gives a guided flow).',
-              'Then complete the update with `npx baldart update --reset` — discards the redundant `.framework/` edits, reinstalls clean, re-applies your overlays.',
-            ], 'cyan');
-            process.exit(0);
-          }
-          // 'keep' → fall through, subtree pull will attempt merge
+          // DEFAULT seamless resolution (v4.8.0+). Captures+verifies any
+          // uncovered edit, then reset-and-reapply. Exits the process on
+          // success (reset) or stops once on an unrecoverable blocker.
+          await resolveOverlayDivergenceSeamlessly(
+            git, status, options, autoYes, overlayCommits, status.remoteVersion
+          );
         }
       } else if (status.divergenceClass === 'real-custom' || status.divergenceClass === 'mixed') {
         UI.warning(`Detected ${status.divergenceCommits.filter((c) => c.category === 'custom-other').length} custom commit(s) on .framework/ that are NOT auto-classifiable as overlays.`);
@@ -818,32 +967,47 @@ async function update(options = {}, unknownArgs = []) {
         if (divStrategy === 'pull') {
           UI.info('Pulling over the custom commits (--on-divergence pull). A merge commit will be created — resolve any conflicts that surface.');
           // fall through
-        } else if (autoYes) {
-          UI.error('Custom commits present — refusing to pull over them unattended under --yes.');
-          UI.info('Re-run with one of:');
+        } else {
+          // DEFAULT seamless (v4.8.0+): capture+verify the overlay-able subset
+          // so those edits are preserved, then stop ONCE. The custom-other
+          // commits touch non-overlayable paths (src/, CHANGELOG, …) and cannot
+          // be auto-resolved without risking that work — this is the single
+          // legitimate pause.
+          const cwd = process.cwd();
+          const overlayableTouched = [...new Set(overlayCommits.flatMap((c) => c.touched || []))];
+          let captured = [];
+          let blockers = [];
+          if (overlayableTouched.length) {
+            UI.newline();
+            UI.info(`Capturing ${overlayableTouched.length} overlay-able edit(s) into overlays…`);
+            ({ captured, blockers } = await captureAndVerify({
+              cwd, git, files: overlayableTouched, frameworkVersion: status.remoteVersion,
+            }));
+            for (const o of captured) UI.success(`Overlay verified: ${o}`);
+            for (const b of blockers) UI.warning(`Could not capture ${b.file} — ${b.reason}`);
+            // Persist the verified overlays so the user keeps them when re-running.
+            if (captured.length) {
+              try {
+                await git.git.add(captured);
+                const st = await git.git.status();
+                if (st.staged.length) {
+                  await git.git.commit('chore(baldart): capture/verify overlays (overlay-able subset of mixed divergence)');
+                }
+              } catch (_) { /* non-fatal — overlays remain on disk */ }
+            }
+          }
+          UI.newline();
+          UI.error('Custom commits touch non-overlayable paths (src/, CHANGELOG, …) — these cannot be auto-resolved.');
+          UI.info('Resolve them, then re-run `npx baldart update`:');
           UI.list([
-            '--on-divergence pull               → create a merge commit over your edits (non-destructive)',
-            '--on-divergence scaffold-overlays  → scaffold overlays for the overlay-able subset (custom-other still needs handling)',
-            '--on-divergence abort              → do nothing',
+            'Contribute generic improvements upstream with `/baldart-push` (recommended).',
+            'Or keep the commits and merge with `npx baldart update --on-divergence pull`.',
           ], 'cyan');
-          UI.info('Best practice: contribute generic improvements upstream first with `/baldart-push`.');
-          emitUpdateJson({ ok: false, action: 'divergence-refused',
-            divergence_class: status.divergenceClass,
+          emitUpdateJson({ ok: false, action: 'divergence-capture-incomplete',
+            divergence_class: status.divergenceClass, captured, blockers,
             installed_before: status.installedVersion, remote_version: status.remoteVersion,
-            reason: 'Custom commits present — refusing to pull over them unattended under --yes.',
-            next_command: 'npx baldart update --json --yes --on-divergence pull' }, 1);
-        } else {
-          const choice = await UI.select('How would you like to proceed?', [
-            { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
-            { name: 'Pull anyway (will create a merge commit — possible conflicts)', value: 'pull' },
-            { name: 'Abort', value: 'abort' },
-          ]);
-          if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
-          if (choice === 'push') {
-            UI.info('Run `/baldart-push` from Claude Code (or `npx baldart push`) to contribute upstream, then re-run update.');
-            process.exit(0);
-          }
-          // 'pull' → fall through
+            reason: 'Overlay-able subset captured; custom-other commit(s) touch non-overlayable paths and need /baldart-push or --on-divergence pull.',
+            next_command: 'npx baldart update --on-divergence pull' }, 1);
         }
       }
       // 'unknown' → conservative: continue silently, the subtree pull will
@@ -853,14 +1017,14 @@ async function update(options = {}, unknownArgs = []) {
     // Step 3: Show changes preview
     UI.header('STEP 3/5: Preview Changes');
 
-    const diff = await git.diffWithRemote();
-    if (diff) {
-      UI.info('Changes detected. Review recommended.');
-      const showDiff = await confirm('Show detailed diff?', false);
-
-      if (showDiff) {
-        console.log(diff);
-      }
+    const changelog = await changelogSinceInstalled(git, status.installedVersion);
+    if (changelog) {
+      UI.info(`What's new (v${status.installedVersion} → v${status.remoteVersion}):`);
+      // Human mode only — keep STDOUT clean in --json mode (UI already routes
+      // its own lines to STDERR there; a raw console.log would break the contract).
+      if (!JSON_MODE) console.log(changelog);
+    } else {
+      UI.info(`Updating v${status.installedVersion} → v${status.remoteVersion} (CHANGELOG preview unavailable).`);
     }
 
     const proceedUpdate = await confirm('Proceed with update?', true);
@@ -869,49 +1033,20 @@ async function update(options = {}, unknownArgs = []) {
       process.exit(0);
     }
 
-    // Pre-flight: git subtree pull --squash refuses a dirty worktree with
-    // "fatal: working tree has modifications. Cannot add." Offer to stash
-    // and re-apply after the update, so the user doesn't have to abort mid-flow.
-    let stashRef = null;
+    // Pre-flight: git subtree pull --squash refuses a dirty worktree. Auto-stash
+    // via the single shared engine and re-apply after the update (v4.8.0+).
     let stashConflict = false; // surfaced in the --json result (v3.32.0+)
-    const isClean = await git.hasCleanWorkingTree();
-    if (!isClean) {
-      UI.newline();
-      UI.warning('Working tree has uncommitted changes. `git subtree pull` requires a clean tree.');
-      const dirty = await git.git.status();
-      const dirtyPaths = [
-        ...dirty.not_added, ...dirty.modified, ...dirty.created,
-        ...dirty.deleted, ...dirty.renamed.map((r) => r.to), ...dirty.staged
-      ];
-      const unique = [...new Set(dirtyPaths)];
-      UI.info(`${unique.length} dirty path(s):`);
-      UI.list(unique.slice(0, 8), 'yellow');
-      if (unique.length > 8) UI.info(`…and ${unique.length - 8} more.`);
-
-      let action;
-      if (autoStash) {
-        UI.info('Auto-stashing dirty paths (--yes / --auto-stash).');
-        action = 'stash';
-      } else {
-        action = await UI.select('How would you like to proceed?', [
-          { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
-          { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
-        ]);
-      }
-      if (action === 'abort') {
-        UI.info('Aborted. Commit or `git stash -u`, then re-run `npx baldart update`.');
-        process.exit(0);
-      }
-      stashRef = `baldart-pre-update-${new Date().toISOString().replace(/[:.]/g, '-')}`;
-      try {
-        await git.git.stash(['push', '-u', '-m', stashRef]);
-        UI.success(`Stashed working tree as "${stashRef}".`);
-      } catch (err) {
-        UI.error(`Could not stash: ${err.message}`);
-        emitUpdateJson({ ok: false, action: 'failed',
-          reason: `Could not stash working tree before update: ${err.message}` }, 1);
-      }
+    const stashOutcome = await autoStashNonFramework(git, { autoStash, interactive: !autoYes });
+    if (stashOutcome.aborted) {
+      UI.info('Aborted. Commit or `git stash -u`, then re-run `npx baldart update`.');
+      process.exit(0);
+    }
+    if (stashOutcome.error) {
+      UI.error(`Could not stash: ${stashOutcome.error}`);
+      emitUpdateJson({ ok: false, action: 'failed',
+        reason: `Could not stash working tree before update: ${stashOutcome.error}` }, 1);
     }
+    const stashRef = stashOutcome.stashRef;
 
     // Step 4: Create backup
     UI.header('STEP 4/5: Create Backup');