@bongos/core 1.17.0

package/modules/lifecycle/conflict-resolve.js

@@ -0,0 +1,436 @@
+'use strict';
+
+// Server-side merge-conflict auto-resolver (task 1385 / ADR 0082) — the SERVER
+// half of the task-1243 generated-file self-heal.
+//
+// WHY THIS EXISTS
+// The active merge driver (task 1162) merges a PR the moment it is mergeable AND
+// CLEAN, but bails on ANY conflict (mergeIfGreen → reason:'merge_conflict'). Task
+// 1243 added the `otb-regen` git merge driver + a `union` attribute so a LOCAL
+// `git merge` auto-resolves the two conflict classes that two parallel branches
+// reliably hit:
+//   • generated artifacts (docs/repo-map.md, docs/file-map.md, docs/session-log-
+//     index.md, the nested CLAUDE.md symbol blocks) — regenerated from the merged
+//     tree by `otb-regen` (scripts/gds/git-merge-regen.js); and
+//   • the docs/adr/README.md append-index — `merge=union` keeps both new rows.
+// But that machinery only runs in a LOCAL merge (a builder's box, /merge-mode,
+// ship's pre-stage). The default ship path is server-mediated (ADR 0055): the box
+// uploads a branch, the server pushes + arms auto-merge, GitHub merges. GitHub's
+// own merge CANNOT run a custom merge driver (`otb-regen`), so a confirmed PR that
+// later conflicts only on these files sits open forever — exactly the PR #300 /
+// #167 stall — until a human with a credentialed checkout runs a local merge.
+//
+// THE FIX. Give the server the same local-merge superpower. When the publish-
+// reconciler sees a confirmed task whose PR reports `merge_conflict`, this module
+// does a real `git merge origin/main` in a THROWAWAY clone with the `otb-regen`
+// driver registered (union needs no registration), so the driver + union resolve
+// exactly the files they resolve locally. If the merge comes out fully clean it
+// pushes the resolved branch; the PR's normal checks (unit / trufflehog / audit /
+// gate-review) re-run on the new head and the next mergeIfGreen sweep lands it.
+//
+// SAFETY — this never bypasses a gate and is never worse than today:
+//   • It pushes a COMMIT; it does not merge to main. Every required check re-runs
+//     before anything lands. It cannot bypass the grader, gate-review, or rank.
+//   • It resolves ONLY what the registered driver / union resolve. A genuine
+//     hand-written conflict leaves git's merge non-zero → we `git merge --abort`
+//     and leave the PR exactly as we found it (a human resolves it).
+//   • It works in an isolated temp clone, never the deploy worktree (mirrors
+//     github-push.pushBundle), so it can't race ~/deploy.sh.
+//   • Best-effort + kill-switchable (CONFLICT_RESOLVE_DISABLED=1). Any failure is
+//     a no-op for the strand, identical to the pre-1385 behaviour.
+//
+// Pure w.r.t. injected deps (exec / githubPush / repoInfo / registerMergeDriver /
+// mkdtemp) so the whole orchestration is unit-tested with no git and no network.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const githubPush = require('./github-push');
+const { repoInfo, branding } = require('../../src/module-api');
+const { loadRepoInfo } = repoInfo;
+const { registerMergeDriver } = require('../../scripts/gds/install-git-hooks');
+
+const execFileP = promisify(execFile);
+
+// The server's own checkout — a fast LOCAL object+worktree source for the clone
+// (mirrors github-push.REPO_ROOT). We clone it, never mutate it.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The merge-bot git identity, derived from the instance branding pack so a non-OTB
+// Cloud Bongos instance signs its auto-resolved merge commits with ITS OWN name +
+// apex, never a hardcoded "Off the Boats GDS" / "amazonprimea.com" (ADR 0062 §3/§5;
+// the branding contract). Falls back to a neutral identity if branding fails to
+// resolve so the resolver never crashes on a config error. NEVER a real person.
+function botIdentity() {
+  let name = 'Cloud Bongos GDS';
+  let apex = 'cloudbongos.com';
+  try {
+    const b = branding();
+    name = `${b.identity?.productName || 'Cloud Bongos'} GDS`;
+    apex = String(b.domains?.cookieDomain || b.domains?.publicOrigin || '')
+      .replace(/^https?:\/\//, '')
+      .replace(/^\./, '')
+      .split('/')[0]
+      .toLowerCase() || apex;
+  } catch { /* fall through to the neutral defaults */ }
+  return { name, email: `gds-bot@${apex}` };
+}
+
+// Conflict START/END markers only. We deliberately do NOT scan for `=======`:
+// a markdown setext heading underline can be seven `=`, so the middle marker
+// alone would false-positive. A line starting with seven `<` or `>` never occurs
+// in real content. Used as defence-in-depth; a clean `git merge` already implies
+// no markers (otb-regen exits non-zero if any survive — git-merge-regen.js).
+const MARKER_GREP_RE = '^(<{7}|>{7})( |\t|$)';
+
+function err(code, extra = {}) {
+  const e = new Error(code);
+  e.code = code;
+  Object.assign(e, extra);
+  return e;
+}
+
+// Default git seam: returns { code, stdout, stderr } and NEVER throws, so a
+// caller can distinguish a merge that conflicted (non-zero, expected) from one
+// that succeeded. Mirrors github-push's shell:false / no-argv-echo discipline so
+// the (credentialed) push URL is never surfaced on an error path.
+async function defaultExec(args, opts = {}) {
+  try {
+    const { stdout, stderr } = await execFileP('git', args, {
+      encoding: 'utf8',
+      timeout: 120000,
+      maxBuffer: 64 * 1024 * 1024,
+      ...opts,
+      shell: false,
+    });
+    return { code: 0, stdout: stdout || '', stderr: stderr || '' };
+  } catch (e) {
+    // execFile rejects on a non-zero exit; the exit code + captured output are on
+    // the error. Normalise to the same shape so callers branch on `.code`.
+    return {
+      code: typeof e.code === 'number' ? e.code : 1,
+      stdout: (e && e.stdout) || '',
+      stderr: '', // never echo stderr: a failing git step may include the auth URL
+    };
+  }
+}
+
+// Paths git still considers unmerged (index stage > 0). Empty after a clean merge.
+async function unmergedPaths(gitIn) {
+  const r = await gitIn(['diff', '--name-only', '--diff-filter=U']);
+  return (r.stdout || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+// Defence-in-depth: any conflict START/END marker left in a tracked file? git grep
+// exits 1 (no match = clean), 0 (match found = markers present), >1 (error). Treat
+// only an explicit match as "markers remain"; an error is inconclusive → we rely on
+// the merge exit code, which is the authoritative signal.
+async function hasConflictMarkers(gitIn) {
+  const r = await gitIn(['grep', '-lE', MARKER_GREP_RE]);
+  return r.code === 0 && (r.stdout || '').trim().length > 0;
+}
+
+// resolveBranchConflicts — attempt to auto-resolve a generated-file / append-index
+// merge conflict on `branch` against origin/main, server-side. Returns a structured
+// result (never throws for the expected outcomes; throws only on misconfiguration):
+//   { resolved: true,  head_sha, branch }                         — merged + pushed
+//   { resolved: false, skipped: '<why>' [, conflicted: [...] ] }  — left as-is
+// skipped reasons: disabled | unconfigured | already_up_to_date | clone_failed |
+//   fetch_failed | checkout_failed | markers_remain | push_failed |
+//   unresolvable_conflict (with conflicted[]).
+async function resolveBranchConflicts({ branch } = {}, deps = {}) {
+  // Kill-switch: deps.disabled wins for tests; otherwise the env flag (matches the
+  // publish-reconciler's PUBLISH_RECONCILER_DISABLED idiom).
+  const disabled = deps.disabled !== undefined ? deps.disabled : process.env.CONFLICT_RESOLVE_DISABLED === '1';
+  if (disabled) return { resolved: false, skipped: 'disabled' };
+  const push = deps.githubPush || githubPush;
+  // No server push credential → nothing we could push anyway (local dev, tests).
+  if (!push.isConfigured()) return { resolved: false, skipped: 'unconfigured' };
+  if (!push.isSafeBranch(branch)) throw err('BAD_BRANCH');
+
+  const token = await push.resolveToken(deps);
+  if (!token) return { resolved: false, skipped: 'unconfigured' };
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const authUrl = (deps.buildAuthUrl || push.buildAuthUrl)(owner, repo, token);
+
+  const exec = deps.exec || defaultExec;
+  const repoRoot = deps.repoRoot || REPO_ROOT;
+  const register = deps.registerMergeDriver || registerMergeDriver;
+  const tmp = (deps.mkdtemp || (() => fs.mkdtempSync(path.join(os.tmpdir(), 'otb-resolve-'))))();
+  const work = path.join(tmp, 'work');
+  const git = (args, opts) => exec(['-C', work, ...args], opts);
+
+  try {
+    // 1. Fast LOCAL clone (objects + a working tree) of the server's checkout.
+    //    Fall back to a shallow network clone where the local checkout isn't a
+    //    repo (stripped container / test env).
+    let r = await exec(['clone', '--local', repoRoot, work]);
+    if (r.code !== 0) {
+      r = await exec(['clone', '--depth=200', authUrl, work]);
+      if (r.code !== 0) return { resolved: false, skipped: 'clone_failed' };
+    }
+
+    // 2. A bot identity for the merge commit — never a real person's name.
+    //    Derived from the instance branding pack (botIdentity) so a non-OTB
+    //    instance signs with its own name + apex.
+    const bot = botIdentity();
+    await git(['config', 'user.email', bot.email]);
+    await git(['config', 'user.name', bot.name]);
+
+    // 3. Register the otb-regen driver in THIS clone so the merge regenerates the
+    //    generated files instead of conflicting (union needs no registration).
+    //    Best-effort: without it, a generated conflict simply stays unresolved and
+    //    we abort below — never wrong, just less effective.
+    try {
+      register(work);
+    } catch (_) {
+      /* fall through — the merge will just leave generated conflicts unresolved */
+    }
+
+    // 4. Fetch fresh origin/main + the feature branch over the authed URL (the
+    //    local clone's refs may trail origin).
+    r = await git([
+      'fetch', '--no-tags', authUrl,
+      '+refs/heads/main:refs/remotes/origin/main',
+      `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+    ]);
+    if (r.code !== 0) return { resolved: false, skipped: 'fetch_failed' };
+
+    // 5. Check out the feature branch at its real origin tip.
+    r = await git(['checkout', '-B', branch, `refs/remotes/origin/${branch}`]);
+    if (r.code !== 0) return { resolved: false, skipped: 'checkout_failed' };
+    const before = (await git(['rev-parse', 'HEAD'])).stdout.trim();
+
+    // 6. Merge origin/main into the branch. The otb-regen driver resolves the
+    //    generated files; union resolves docs/adr/README.md; any genuine conflict
+    //    leaves the merge non-zero.
+    const m = await git(['merge', '--no-edit', 'refs/remotes/origin/main']);
+
+    if (m.code !== 0) {
+      // Genuine (hand-written) conflict in a file neither the driver nor union can
+      // resolve. Abort so we never leave a dirty clone or push a half-merge.
+      const conflicted = await unmergedPaths(git);
+      await git(['merge', '--abort']);
+      return { resolved: false, skipped: 'unresolvable_conflict', conflicted };
+    }
+
+    // 7. Clean merge. If nothing actually changed, the branch wasn't behind —
+    //    not our case (mergeIfGreen reported a conflict), so report a no-op.
+    const after = (await git(['rev-parse', 'HEAD'])).stdout.trim();
+    if (after === before) return { resolved: false, skipped: 'already_up_to_date' };
+
+    // 8. Belt-and-braces: a clean `git merge` already implies no unmerged paths and
+    //    no markers, but assert both before we push anything.
+    if ((await unmergedPaths(git)).length || (await hasConflictMarkers(git))) {
+      return { resolved: false, skipped: 'markers_remain' };
+    }
+
+    // 9. Push the resolved branch (updates the PR head). No --force, ever: a
+    //    non-fast-forward (someone else moved the branch) fails safely and the
+    //    next sweep retries against the new tip.
+    const p = await git(['push', authUrl, `HEAD:refs/heads/${branch}`]);
+    if (p.code !== 0) return { resolved: false, skipped: 'push_failed' };
+
+    return { resolved: true, head_sha: after, branch };
+  } finally {
+    try {
+      (deps.rmtmp || ((d) => fs.rmSync(d, { recursive: true, force: true })))(tmp);
+    } catch (_) {
+      /* temp cleanup is best-effort */
+    }
+  }
+}
+
+// The generated indexes CI re-checks on a PR's MERGE REF (gen-*-map --check). The
+// heal regenerates exactly these from the merged tree. Kept as the clone's OWN
+// scripts (each resolves its repo root from its __dirname), never the server's.
+const GENERATOR_SCRIPTS = [
+  'scripts/gds/gen-repo-map.js',
+  'scripts/gds/gen-file-map.js',
+  'scripts/gds/gen-session-index.js',
+];
+
+// Run the CLONE's generator scripts in WRITE mode against the merged working tree.
+// Invoking the clone's OWN copy (cwd + path both under `work`) means each script's
+// `__dirname`-derived repo root is the clone — it regenerates the clone, never the
+// server's checkout. Returns { code } = the worst child exit code (0 = all clean).
+// A non-zero exit (e.g. gen-file-map's exit 2 when a hand-written note is missing,
+// or a hard crash) is surfaced so the caller can decline to push a half-baked tree.
+//
+// Env hardening: gen-file-map writes to resolveInstanceRoot(), which honours a
+// <PREFIX>_INSTANCE_ROOT env var BEFORE falling back to cwd. cwd=work already pins
+// the fallback (prod sets no such var), but since this runs in the LIVE server
+// process we strip any *_INSTANCE_ROOT override so a misconfigured host can never
+// make a generator write into the deploy tree instead of the throwaway clone.
+async function defaultRunGenerators({ work, execFile = execFileP } = {}) {
+  const childEnv = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!/_INSTANCE_ROOT$/.test(k)) childEnv[k] = v;
+  }
+  let worstCode = 0;
+  for (const rel of GENERATOR_SCRIPTS) {
+    try {
+      await execFile(process.execPath, [path.join(work, rel)], {
+        cwd: work, env: childEnv, encoding: 'utf8', timeout: 120000, maxBuffer: 64 * 1024 * 1024,
+      });
+    } catch (e) {
+      // execFile rejects on a non-zero exit; keep the worst code seen.
+      const c = typeof e.code === 'number' ? e.code : 1;
+      if (c) worstCode = c;
+    }
+  }
+  return { code: worstCode };
+}
+
+// refreshStaleGenerated — heal the "clean-merge-but-STALE-generated-content" strand
+// (task 1915 / idea 499; the ADR 0082 gap resolveBranchConflicts never reaches).
+//
+// WHY THIS EXISTS
+// resolveBranchConflicts only fires when mergeIfGreen reports `merge_conflict`. But a
+// busy fleet produces a CLEAN-merge-but-STALE case it never touches: CI runs
+// `gen-*-map --check` on the PR's MERGE REF, so any main merge during the CI window
+// re-stales a pending branch's committed docs/repo-map.md (etc.). The `unit` check
+// fails, GitHub's auto-merge never fires, mergeIfGreen needs merge_state=CLEAN so it
+// bails — and the block reason is a failing CHECK, never merge_conflict, so
+// resolveBranchConflicts is never invoked. The strand sits credited-but-unlanded
+// while main churns (task 1899 / PR 616, 2026-07-03: manual re-freshen laps to land).
+//
+// THE HEAL. In a throwaway clone, merge origin/main into the branch (expected CLEAN
+// here — the PR was mergeable) and REGENERATE the indexes from the merged tree.
+//   • Discriminator (needs no CI-log access): if regeneration produces a diff, the
+//     red check WAS staleness → commit + push (fast-forward; the PR's checks re-run
+//     on the new head and the next mergeIfGreen sweep lands it).
+//   • If regeneration produces NO diff, the merged tree's indexes are already fresh
+//     → the red check is a REAL failure, not staleness → leave it for a human.
+// It deliberately does NOT register the otb-regen merge driver: a genuine conflict
+// must surface as `merge_conflict` (aborted here) so the resolveBranchConflicts path
+// owns it — this function only ever regenerates a cleanly-merged tree.
+//
+// SAFETY (identical posture to resolveBranchConflicts):
+//   • Pushes a COMMIT, never merges to main — every required check re-runs before
+//     anything lands. It cannot bypass the grader, gate-review, or rank, and it
+//     NEVER ships a task (the reconciler still requires landProvenForTask).
+//   • No --force: a non-fast-forward (someone moved the branch) fails safely; the
+//     next sweep retries against the new tip.
+//   • Best-effort + kill-switchable (shares CONFLICT_RESOLVE_DISABLED). Any failure
+//     is a no-op for the strand.
+// Returns { refreshed: true, head_sha, branch } | { refreshed: false, skipped }.
+// skipped reasons: disabled | unconfigured | clone_failed | fetch_failed |
+//   checkout_failed | merge_conflict | generator_failed | no_regen_diff |
+//   markers_remain | commit_failed | push_failed.
+async function refreshStaleGenerated({ branch } = {}, deps = {}) {
+  const disabled = deps.disabled !== undefined ? deps.disabled : process.env.CONFLICT_RESOLVE_DISABLED === '1';
+  if (disabled) return { refreshed: false, skipped: 'disabled' };
+  const push = deps.githubPush || githubPush;
+  if (!push.isConfigured()) return { refreshed: false, skipped: 'unconfigured' };
+  if (!push.isSafeBranch(branch)) throw err('BAD_BRANCH');
+
+  const token = await push.resolveToken(deps);
+  if (!token) return { refreshed: false, skipped: 'unconfigured' };
+  const repoInfoResolved = deps.repoInfo || loadRepoInfo();
+  if (!repoInfoResolved || repoInfoResolved.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfoResolved;
+  const authUrl = (deps.buildAuthUrl || push.buildAuthUrl)(owner, repo, token);
+
+  const exec = deps.exec || defaultExec;
+  const repoRoot = deps.repoRoot || REPO_ROOT;
+  const runGenerators = deps.runGenerators || defaultRunGenerators;
+  const tmp = (deps.mkdtemp || (() => fs.mkdtempSync(path.join(os.tmpdir(), 'otb-refresh-'))))();
+  const work = path.join(tmp, 'work');
+  const git = (args, opts) => exec(['-C', work, ...args], opts);
+
+  try {
+    // 1. Fast LOCAL clone (falls back to a shallow network clone) — mirrors
+    //    resolveBranchConflicts so both heals share the same isolation posture.
+    let r = await exec(['clone', '--local', repoRoot, work]);
+    if (r.code !== 0) {
+      r = await exec(['clone', '--depth=200', authUrl, work]);
+      if (r.code !== 0) return { refreshed: false, skipped: 'clone_failed' };
+    }
+
+    // 2. Bot identity for the regen commit — never a real person.
+    const bot = botIdentity();
+    await git(['config', 'user.email', bot.email]);
+    await git(['config', 'user.name', bot.name]);
+
+    // 3. Fetch fresh origin/main + the feature branch over the authed URL.
+    r = await git([
+      'fetch', '--no-tags', authUrl,
+      '+refs/heads/main:refs/remotes/origin/main',
+      `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+    ]);
+    if (r.code !== 0) return { refreshed: false, skipped: 'fetch_failed' };
+
+    // 4. Check out the feature branch at its real origin tip.
+    r = await git(['checkout', '-B', branch, `refs/remotes/origin/${branch}`]);
+    if (r.code !== 0) return { refreshed: false, skipped: 'checkout_failed' };
+
+    // 5. Merge origin/main. Expected CLEAN for this strand (the PR was mergeable and
+    //    the failing signal was a stale-generated CHECK, not a conflict). A genuine
+    //    conflict → abort + report merge_conflict so the resolveBranchConflicts path
+    //    (which the reconciler routes to on a `merge_conflict` reason) owns it.
+    const m = await git(['merge', '--no-edit', 'refs/remotes/origin/main']);
+    if (m.code !== 0) {
+      await git(['merge', '--abort']);
+      return { refreshed: false, skipped: 'merge_conflict' };
+    }
+
+    // 6. Regenerate the indexes from the (now clean, committed) merged tree. HEAD is
+    //    the merge commit, so a dirty working tree AFTER this step is exactly the
+    //    generators' output — isolating regen's effect from the merge's.
+    const gen = await runGenerators({ work });
+    if (gen && gen.code !== 0) {
+      // A generator hard-error / a missing hand-written note (gen-file-map exit 2):
+      // pushing a half-regenerated tree wouldn't pass CI anyway. Leave it.
+      return { refreshed: false, skipped: 'generator_failed' };
+    }
+
+    // 7. THE DISCRIMINATOR. No diff → the merged tree's indexes were already fresh →
+    //    the red check is a real failure, not staleness → leave it for a human.
+    const dirty = (await git(['status', '--porcelain'])).stdout.trim();
+    if (!dirty) return { refreshed: false, skipped: 'no_regen_diff' };
+
+    // 8. Belt-and-braces: never push a tree with surviving conflict markers.
+    if (await hasConflictMarkers(git)) return { refreshed: false, skipped: 'markers_remain' };
+
+    // 9. Commit the regenerated indexes (atop the clean main merge) and push
+    //    fast-forward. No --force, ever.
+    await git(['add', '-A']);
+    const c = await git([
+      'commit', '-m',
+      'chore(gds): refresh generated indexes after merging main (publish-reconciler self-heal, task 1915)',
+    ]);
+    if (c.code !== 0) return { refreshed: false, skipped: 'commit_failed' };
+    const after = (await git(['rev-parse', 'HEAD'])).stdout.trim();
+
+    const p = await git(['push', authUrl, `HEAD:refs/heads/${branch}`]);
+    if (p.code !== 0) return { refreshed: false, skipped: 'push_failed' };
+
+    return { refreshed: true, head_sha: after, branch };
+  } finally {
+    try {
+      (deps.rmtmp || ((d) => fs.rmSync(d, { recursive: true, force: true })))(tmp);
+    } catch (_) {
+      /* temp cleanup is best-effort */
+    }
+  }
+}
+
+module.exports = {
+  resolveBranchConflicts,
+  refreshStaleGenerated,
+  // exported for unit tests
+  defaultExec,
+  defaultRunGenerators,
+  unmergedPaths,
+  hasConflictMarkers,
+  GENERATOR_SCRIPTS,
+  MARKER_GREP_RE,
+};