baldart 3.24.0 → 3.26.0

package/src/utils/git.js

@@ -177,6 +177,205 @@ class GitUtils {
     }
   }
 
+  // ────────────────────────────────────────────────────────────────────
+  // SSOT update-status check (v3.25.0+).
+  //
+  // Before v3.25.0 three commands answered the same question — "is this
+  // consumer up-to-date with upstream BALDART?" — with three different
+  // queries, none of them right:
+  //
+  //   - `update.js` used `hasChangesToPush()` (origin/main..HEAD — wrong
+  //     remote AND wrong direction).
+  //   - `version.js` and `doctor.js` used `HEAD...FETCH_HEAD` full-repo
+  //     symmetric diff, which counts every subtree-merge commit ever
+  //     generated by `git subtree pull --squash`. That count never
+  //     decreases (squash merges are never "equal" on both sides), so
+  //     even a perfectly-synced consumer is shown "N commits ahead".
+  //
+  // The authority for "aligned or not" is the VERSION file. The upstream
+  // BALDART repo has `VERSION` at root, so `git show FETCH_HEAD:VERSION`
+  // gives the remote version directly. Local `.framework/VERSION` gives
+  // the installed version. Identical strings → aligned, full stop.
+  //
+  // The commit count remains in the return value for diagnostic display
+  // (behind `--verbose` flags), explicitly labeled as subtree-merge noise
+  // so users don't misread it as a problem.
+  // ────────────────────────────────────────────────────────────────────
+  // ────────────────────────────────────────────────────────────────────
+  // Divergence classifier (v3.25.0+).
+  //
+  // When `aheadScoped > 0` (consumer has commits on `.framework/` not in
+  // upstream), we need to know WHETHER those commits are git plumbing
+  // noise (auto-resolve OK) or real user content (must prompt before
+  // anything destructive).
+  //
+  // Categories (in matching order — first match wins):
+  //   - subtree-merge:  `git subtree pull --squash` merge commits
+  //   - subtree-squash: the squash payload commits themselves
+  //   - chore-wrapper:  CLI-generated [CHORE]/chore(baldart): commits
+  //   - custom-overlay-able: user edited a framework agent/skill/command
+  //                          → should migrate to .baldart/overlays/
+  //   - custom-other:   anything else (src/, CHANGELOG, ad-hoc fixes)
+  //
+  // Aggregate `class`:
+  //   - all-noise:    every commit is subtree-* / chore-wrapper → auto-resolve
+  //   - overlay-able: every non-noise commit is overlay-able → suggest /overlay
+  //   - real-custom:  every non-noise commit is custom-other → prompt 3-way
+  //   - mixed:        non-noise commits span both → prompt 3-way
+  //
+  // Default-conservative: any commit whose subject + touched-paths don't
+  // match a known pattern is classified `custom-other`, never auto-resolved.
+  // ────────────────────────────────────────────────────────────────────
+  classifyCommitSubject(subject) {
+    if (/^Merge (commit '[a-f0-9]+'|branch '[^']+') into \S+$/.test(subject)) {
+      return 'subtree-merge';
+    }
+    if (/^Squashed '\.framework\/' (changes from|content from)/.test(subject)) {
+      return 'subtree-squash';
+    }
+    // Two separate conditions: must look like a chore commit AND mention
+    // baldart anywhere (subject or scope). `chore(baldart): foo` is a
+    // common case — the keyword is in the scope, not after the colon.
+    const isChorePrefix = /^(\[CHORE\]|chore(\([^)]*\))?:)/.test(subject);
+    const hasBaldartKeyword = /baldart/i.test(subject);
+    if (isChorePrefix && hasBaldartKeyword) {
+      return 'chore-wrapper';
+    }
+    return null;
+  }
+
+  classifyCommitByPaths(touched) {
+    if (!touched.length) return 'custom-other';
+    const overlayablePrefix = '.framework/framework/.claude/';
+    const overlayableDirs = ['agents/', 'skills/', 'commands/'];
+    const allOverlayable = touched.every((p) => {
+      if (!p.startsWith(overlayablePrefix)) return false;
+      const rest = p.slice(overlayablePrefix.length);
+      return overlayableDirs.some((d) => rest.startsWith(d));
+    });
+    return allOverlayable ? 'custom-overlay-able' : 'custom-other';
+  }
+
+  async classifyDivergence() {
+    // Inspect aheadScoped commits — those not on FETCH_HEAD that touch .framework/.
+    const commits = [];
+    try {
+      const raw = await this.git.raw([
+        'log',
+        'FETCH_HEAD..HEAD',
+        '--pretty=format:%H%x00%s',
+        '--',
+        FRAMEWORK_DIR
+      ]);
+      for (const line of raw.split('\n')) {
+        if (!line.trim()) continue;
+        const [sha, ...rest] = line.split('');
+        const subject = rest.join('');
+        let category = this.classifyCommitSubject(subject);
+        if (!category) {
+          // Need file list to disambiguate custom-overlay-able vs custom-other.
+          let touched = [];
+          try {
+            const filesRaw = await this.git.raw(['diff-tree', '--no-commit-id', '--name-only', '-r', sha]);
+            touched = filesRaw.split('\n').filter((l) => l.trim());
+          } catch (_) { /* leave empty → custom-other */ }
+          category = this.classifyCommitByPaths(touched);
+        }
+        commits.push({ sha, subject, category });
+      }
+    } catch (_) {
+      return { class: 'unknown', commits: [] };
+    }
+
+    if (commits.length === 0) return { class: 'all-noise', commits: [] };
+
+    const noiseCategories = new Set(['subtree-merge', 'subtree-squash', 'chore-wrapper']);
+    const nonNoise = commits.filter((c) => !noiseCategories.has(c.category));
+    if (nonNoise.length === 0) return { class: 'all-noise', commits };
+
+    const hasOverlayable = nonNoise.some((c) => c.category === 'custom-overlay-able');
+    const hasOther = nonNoise.some((c) => c.category === 'custom-other');
+    let aggregate = 'real-custom';
+    if (hasOverlayable && !hasOther) aggregate = 'overlay-able';
+    else if (hasOverlayable && hasOther) aggregate = 'mixed';
+
+    return { class: aggregate, commits };
+  }
+
+  async getUpdateStatus(repo, branch = 'main') {
+    const result = {
+      installedVersion: 'unknown',
+      remoteVersion: 'unknown',
+      isAligned: false,
+      commitCount: {
+        behind: 0,
+        ahead: 0,
+        note: 'Includes subtree-merge commits autogenerated by `git subtree pull --squash`. Does not reflect real content drift; use `isAligned` for update status.'
+      },
+      aheadScoped: 0,
+      hasDivergence: false,
+      hasFetchHead: false,
+      fetched: false,
+    };
+
+    try {
+      result.installedVersion = await this.getFrameworkVersion();
+    } catch (_) { /* leave 'unknown' */ }
+
+    try {
+      await this.fetch(repo, branch);
+      result.fetched = true;
+    } catch (_) {
+      // Offline — leave fetched=false, fall through with best-effort.
+    }
+
+    try {
+      const head = await this.git.raw(['rev-parse', 'FETCH_HEAD']);
+      result.hasFetchHead = head.trim().length > 0;
+    } catch (_) { /* no FETCH_HEAD */ }
+
+    if (result.hasFetchHead) {
+      try {
+        const v = await this.git.raw(['show', 'FETCH_HEAD:VERSION']);
+        result.remoteVersion = v.trim();
+      } catch (_) { /* upstream missing VERSION — leave 'unknown' */ }
+
+      try {
+        const out = await this.git.raw(['rev-list', '--left-right', '--count', 'HEAD...FETCH_HEAD']);
+        const [ahead, behind] = out.trim().split(/\s+/).map(Number);
+        if (!Number.isNaN(ahead)) result.commitCount.ahead = ahead;
+        if (!Number.isNaN(behind)) result.commitCount.behind = behind;
+      } catch (_) { /* leave 0/0 */ }
+
+      try {
+        const out = await this.git.raw(['rev-list', '--count', 'FETCH_HEAD..HEAD', '--', FRAMEWORK_DIR]);
+        result.aheadScoped = Number(out.trim()) || 0;
+      } catch (_) { /* leave 0 */ }
+    }
+
+    if (result.installedVersion !== 'unknown' && result.remoteVersion !== 'unknown') {
+      result.isAligned = result.installedVersion === result.remoteVersion;
+    }
+
+    result.hasDivergence = !result.isAligned && result.aheadScoped > 0;
+
+    if (result.hasDivergence) {
+      try {
+        const d = await this.classifyDivergence();
+        result.divergenceClass = d.class;
+        result.divergenceCommits = d.commits;
+      } catch (_) {
+        result.divergenceClass = 'unknown';
+        result.divergenceCommits = [];
+      }
+    } else {
+      result.divergenceClass = 'none';
+      result.divergenceCommits = [];
+    }
+
+    return result;
+  }
+
   // ────────────────────────────────────────────────────────────────────
   // `.framework/` is a git subtree — it MUST be tracked. If anything in
   // the gitignore chain (project .gitignore, .git/info/exclude, global