@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/implement-epic/cut-protocol.js

@@ -0,0 +1,392 @@
+/**
+ * The shared EXACT-CUT protocol and scope-readiness poll (BAPI-843; BAPI-850).
+ *
+ * Extracted from `implement-epic init` so that the LLM-conductor pilot and the v2
+ * `setup-epic --feature-branch` entry point drive ONE implementation of the
+ * local cut — the same local `git` fetch, the same remote-ref existence check,
+ * the same exact-SHA push, and the same mismatch classification. This module is
+ * the single owner of those operations; neither CLI re-implements any of them.
+ *
+ * What the cut is: the server leases a hold on the canonical parse lock and
+ * names the commit the canonical index actually covers (`cut/begin`); this
+ * module creates `origin/<feature>` at EXACTLY that commit with the operator's
+ * own `git` — never the GitHub App, which is `contents: read` and cannot create
+ * refs — reads the ref back, and asks the server to record it as the scope's
+ * immutable cut (`cut/commit`). The hold is released on every outcome.
+ *
+ * Contract properties, fixed here and relied on by both CLIs:
+ *
+ * - **Never force-updates an existing branch.** The push refspec has no leading
+ *   `+`, so it can only create. A branch that already exists at any commit other
+ *   than the held cut commit is a refusal, never a repoint.
+ * - **Takes an already validated branch and SHA.** Callers validate the branch
+ *   name (`validateBranchName`) and normalize the candidate SHA before calling;
+ *   this module re-proves the SHA shape it pushes, but it is not a parser.
+ * - **No credential ever reaches argv.** The only subprocess is `git`, and its
+ *   arguments are refs, remotes, and SHAs. Bridge and GitHub credentials travel
+ *   only inside the typed client's headers.
+ * - **Every failure is classified, never thrown.** Callers get a discriminated
+ *   outcome with operator-ready sentences and the bounded facts (expected and
+ *   observed SHAs) they need to report; there is nothing to `try/catch`.
+ */
+import { execFile } from "node:child_process";
+import { abandonIndexScopeCut, beginIndexScopeCut, commitIndexScopeCut, getIndexScopeStatus, } from "./bridge-client.js";
+/**
+ * Poll bound for a scope bootstrap, shared by `implement-epic init` and
+ * `setup-epic`. A seed copies a repository's whole parse cache and the
+ * verifying parse then downloads and change-detects it, so the ceiling is
+ * generous; the interval is what keeps the poll cheap.
+ */
+export const SCOPE_BOOTSTRAP_POLL_INTERVAL_MS = 5_000;
+export const SCOPE_BOOTSTRAP_MAX_POLLS = 240; // ~20 minutes at the interval above.
+/**
+ * Build the default list-argument subprocess runner both CLIs use for `git`.
+ *
+ * One body rather than two copies: `execFile` with `shell: false`, a generous
+ * buffer for porcelain output, and an exit code that never throws — a missing
+ * binary resolves to a non-zero code the caller classifies.
+ */
+export function createExecFileRunCommand() {
+    return (file, args, options) => new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: options?.cwd,
+            // Git porcelain output for a many-worktree checkout can be large.
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: "utf-8",
+            timeout: options?.timeoutMs,
+            // Explicit: arguments are a list, never a concatenated shell string.
+            shell: false,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                exitCode: typeof code === "number" ? code : error ? 1 : 0,
+            });
+        });
+    });
+}
+/** Run `git` in the operator's checkout. */
+export function runGit(deps, args) {
+    return Promise.resolve(deps.runCommand("git", args, { cwd: deps.cwd }));
+}
+/** The single trimmed line a `git rev-parse`-style command produced, or null. */
+export function firstOutputLine(result) {
+    const value = result.stdout.split("\n")[0]?.trim() ?? "";
+    return value.length === 0 ? null : value;
+}
+/** The SHA from `git ls-remote --heads origin <ref>` output, or null. */
+export function lsRemoteSha(result) {
+    const line = firstOutputLine(result);
+    if (line === null)
+        return null;
+    const sha = line.split(/\s+/)[0]?.trim() ?? "";
+    return sha.length === 0 ? null : sha;
+}
+/**
+ * Normalize a commit SHA to its canonical 40-character lowercase form, or `null`.
+ *
+ * Mirrors the server's own guard so a malformed value is refused HERE — before it
+ * becomes a `git push` refspec — rather than becoming an opaque git error or, far
+ * worse, a ref pushed at something that is not a commit.
+ */
+export function normalizeCommitSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return /^[0-9a-f]{40}$/.test(normalized) ? normalized : null;
+}
+/**
+ * Read the head of `origin/<branch>` WITHOUT mutating anything.
+ *
+ * `sha: null` means the branch does not exist on origin. A failed `ls-remote`
+ * (no remote, no network, no git) is its own outcome, never "absent": treating an
+ * unanswered read as absence is how a push lands on top of a branch nobody saw.
+ */
+export async function readRemoteBranchHead(deps, branch) {
+    const result = await runGit(deps, ["ls-remote", "--heads", "origin", `refs/heads/${branch}`]);
+    if (result.exitCode !== 0) {
+        return { ok: false, error: `git ls-remote could not read origin/${branch}.` };
+    }
+    return { ok: true, sha: lsRemoteSha(result) };
+}
+/**
+ * Make sure the exact cut object is resolvable locally, fetching it if needed.
+ *
+ * The cut is pushed BY SHA, so the object must exist in the operator's
+ * repository. A base-branch fetch usually brings it along; when it did not — the
+ * index covers a commit that is no longer an ancestor of the base tip — one
+ * targeted, NON-MUTATING fetch of that SHA is attempted (it updates no ref,
+ * creates no branch, and checks nothing out). Returns `true` when the commit
+ * resolves.
+ */
+export async function ensureCommitResolvableLocally(deps, commitSha) {
+    const present = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    if (present.exitCode === 0)
+        return true;
+    await runGit(deps, ["fetch", "origin", commitSha]);
+    const retry = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    return retry.exitCode === 0;
+}
+/**
+ * Drive the exact cut: `cut/begin` → re-check the remote ref under the hold →
+ * create the ref at the held commit (if absent) → read it back → `cut/commit`,
+ * releasing the hold on EVERY outcome.
+ *
+ * Everything between `begin` and the release happens while the SERVER holds the
+ * canonical repository's parse lock, so the commit the index covers cannot move
+ * underneath the ref this module creates.
+ */
+export async function performExactIndexScopeCut(deps, access, request) {
+    const { featureBranch, baseBranch, candidateCommitSha } = request;
+    const lease = await beginIndexScopeCut(access, {
+        featureBranch,
+        baseBranch,
+        candidateCommitSha,
+        epicRunId: request.epicRunId ?? null,
+    }, deps.fetchImpl);
+    if (!lease.ok) {
+        return {
+            ok: false,
+            kind: "begin_refused",
+            failures: [`The index-scope cut could not begin: ${lease.error}`],
+            lease: null,
+            expectedSha: candidateCommitSha,
+            observedSha: null,
+        };
+    }
+    const cut = lease.value;
+    try {
+        if (cut.cut_commit_sha !== candidateCommitSha) {
+            // The server re-read the canonical snapshot under its own hold and named a
+            // different commit. Nothing has been pushed yet, so refusing costs nothing
+            // and continuing would cut the epic at a commit the preflight never checked.
+            return {
+                ok: false,
+                kind: "canonical_moved",
+                failures: [
+                    `The canonical index moved while init was preparing ` +
+                        `(preflight saw ${candidateCommitSha}, the cut hold names ${cut.cut_commit_sha}). Re-run init.`,
+                ],
+                lease: cut,
+                expectedSha: candidateCommitSha,
+                observedSha: cut.cut_commit_sha,
+            };
+        }
+        // Re-check `origin/<feature>` WHILE the hold is active. A preflight
+        // observation is evidence for a refusal, never for a mutation: another
+        // operator may have created the ref in between.
+        const held = await readRemoteBranchHead(deps, featureBranch);
+        if (!held.ok) {
+            return {
+                ok: false,
+                kind: "ls_remote_failed",
+                failures: [held.error],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: null,
+            };
+        }
+        const heldSha = held.sha;
+        if (heldSha !== null && heldSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "existing_ref_mismatch",
+                failures: [
+                    `origin/${featureBranch} exists at ${heldSha}, which is not the canonical indexed ` +
+                        `commit ${cut.cut_commit_sha}. Delete it or finish the previous run first.`,
+                ],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: heldSha,
+            };
+        }
+        let branchCreated = false;
+        if (heldSha === null) {
+            // Create the ref from the EXACT commit, with the operator's own git. No
+            // local checkout, no branch, no worktree — and deliberately not the GitHub
+            // App, which is `contents: read` and cannot create refs. Not a force push:
+            // the refspec has no leading `+`, so it can only create.
+            const pushed = await runGit(deps, [
+                "push",
+                "origin",
+                `${cut.cut_commit_sha}:refs/heads/${featureBranch}`,
+            ]);
+            if (pushed.exitCode !== 0) {
+                return {
+                    ok: false,
+                    kind: "push_failed",
+                    failures: [
+                        `Could not create origin/${featureBranch} at the canonical indexed commit ${cut.cut_commit_sha}.`,
+                    ],
+                    lease: cut,
+                    expectedSha: cut.cut_commit_sha,
+                    observedSha: null,
+                };
+            }
+            branchCreated = true;
+        }
+        // Read the ref BACK from origin. What matters is what the remote now holds,
+        // not what this process intended to push.
+        const confirmed = await readRemoteBranchHead(deps, featureBranch);
+        const confirmedSha = confirmed.ok ? confirmed.sha : null;
+        if (confirmedSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "confirm_failed",
+                failures: [`origin/${featureBranch} did not resolve to ${cut.cut_commit_sha} after the push.`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        const committed = await commitIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id, epicRefCommitSha: confirmedSha }, deps.fetchImpl);
+        if (!committed.ok) {
+            return {
+                ok: false,
+                kind: "commit_refused",
+                failures: [`The index-scope cut could not be recorded: ${committed.error}`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        return { ok: true, lease: cut, branchCreated, outcome: committed.value.outcome };
+    }
+    finally {
+        // The hold is released on EVERY pre-seed outcome, including the success path
+        // (where the server already released it — abandon is idempotent). The seed
+        // acquires this same canonical lock itself and it is not reentrant, so
+        // handing off while still holding it would deadlock the epic against its own
+        // seed. A failed release never masks the primary failure: it is reported and
+        // the original outcome stands.
+        const abandoned = await abandonIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id }, deps.fetchImpl);
+        if (!abandoned.ok) {
+            deps.errorLog(`announced: the cut hold could not be released cleanly: ${abandoned.error}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Scope-readiness poll (BAPI-843; shared with `setup-epic` by BAPI-850)
+// ---------------------------------------------------------------------------
+/** The operator-facing label for each lifecycle state the poll reports. */
+export const SCOPE_LIFECYCLE_LABELS = Object.freeze({
+    provisioning: "Provisioning",
+    seeding: "Seeding",
+    verifying: "Verifying",
+    ready: "Ready",
+    failed: "Failed",
+});
+/**
+ * The fixed lifecycle label a heartbeat uses when the status READ itself failed
+ * (BAPI-963).
+ *
+ * A read failure is not a lifecycle state, and the raw error is deliberately not
+ * interpolated into a heartbeat: a per-poll line repeated for twenty minutes is
+ * the worst possible place to smuggle unbounded server text.
+ */
+export const SCOPE_BOOTSTRAP_UNREADABLE_STATE = "unreadable";
+/**
+ * Format one bootstrap heartbeat line (BAPI-963).
+ *
+ * Shared with `setup-epic` at this seam so both conductors compute progress the
+ * same way; RENDERING stays with each caller, because the pilot writes to its own
+ * stderr advisory channel and v2 reports progress server-side.
+ *
+ * The shape is fixed and grep-friendly — elapsed first, state second — because a
+ * ~30-minute seed that printed nothing was externally indistinguishable from a
+ * hang (sleeping process, 0% CPU, a frozen `updated_at`). Elapsed seconds are
+ * clamped at zero so a clock adjustment cannot render a negative age.
+ */
+export function formatScopeBootstrapHeartbeat(elapsedMs, state) {
+    const seconds = Math.max(0, Math.floor(elapsedMs / 1000));
+    // `lifecycle_state` is a required non-empty string on the wire, not a closed
+    // set. Bounding it to the known labels (plus the fixed `unreadable` and a
+    // catch-all) keeps an unvalidated server string out of a line that repeats
+    // every interval for up to twenty minutes.
+    return `Seeding scope: elapsed=${seconds}s state=${boundScopeLifecycleLabel(state)}`;
+}
+/** The label an unrecognized lifecycle state collapses to. Never `null`, never raw. */
+export const SCOPE_BOOTSTRAP_UNKNOWN_STATE = "unknown";
+/**
+ * Collapse any lifecycle state to a bounded, safe label (BAPI-1054).
+ *
+ * `lifecycle_state` is a required non-empty string on the wire, not a closed set,
+ * so an unrecognized value is possible and an error-bearing one
+ * (`unreadable (<server error>)`) is routine. Extracted from
+ * {@link formatScopeBootstrapHeartbeat}, which has always applied this rule, so
+ * every surface that renders a state applies the SAME one — a second spelling of
+ * "bounded" is how raw server text eventually reaches a terminal.
+ */
+export function boundScopeLifecycleLabel(state) {
+    return state === SCOPE_BOOTSTRAP_UNREADABLE_STATE || state in SCOPE_LIFECYCLE_LABELS
+        ? state
+        : SCOPE_BOOTSTRAP_UNKNOWN_STATE;
+}
+/**
+ * Describe the nominal polling window up front (BAPI-963).
+ *
+ * Computed from the interval and cap rather than hard-coded, so a change to
+ * either constant cannot leave the operator-facing duration claim stale. The
+ * window is NOMINAL: the observed pilot seed outran even this bound, which is
+ * why the wording promises a poll cadence rather than a completion time.
+ */
+export function describeScopeBootstrapWindow(intervalMs = SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, maxPolls = SCOPE_BOOTSTRAP_MAX_POLLS) {
+    const intervalSeconds = Math.max(1, Math.round(intervalMs / 1000));
+    const windowMinutes = Math.max(1, Math.round((intervalMs * maxPolls) / 60_000));
+    return (`Seeding the epic's index scope. This copies the repository's whole parse cache and ` +
+        `verifies it, and commonly takes many minutes. Progress is reported every ` +
+        `${intervalSeconds}s; the poll gives up after about ${windowMinutes} minutes.`);
+}
+/**
+ * Poll a scope's lifecycle until it is `ready`, `failed`, or the bounded wait
+ * elapses, reporting each NEWLY observed lifecycle transition exactly once, in
+ * order, through `onTransition`.
+ *
+ * Readiness is a server-side fact this poll observes rather than concludes from
+ * any request of its own: `ready` is accepted ONLY when the status also proves
+ * `indexed_commit_sha == cut_commit_sha`. A `ready` whose watermark disagrees is
+ * reported as `ready_mismatch` — the control plane contradicting itself, which
+ * is worth refusing rather than proceeding on.
+ *
+ * A transient read failure is not a verdict: the poll keeps going and lets the
+ * bound be the thing that gives up. The interval and cap are the shared
+ * {@link SCOPE_BOOTSTRAP_POLL_INTERVAL_MS} / {@link SCOPE_BOOTSTRAP_MAX_POLLS}.
+ */
+export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const maxPolls = options.maxPolls ?? SCOPE_BOOTSTRAP_MAX_POLLS;
+    const intervalMs = options.intervalMs ?? SCOPE_BOOTSTRAP_POLL_INTERVAL_MS;
+    const now = options.now ?? (() => new Date());
+    const startedAtMs = now().getTime();
+    let lastState = "unknown";
+    let lastStatus = null;
+    let lastReportedState = null;
+    for (let poll = 0; poll < maxPolls; poll += 1) {
+        await sleep(intervalMs);
+        const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
+        if (!status.ok) {
+            lastState = `unreadable (${status.error})`;
+            options.onPoll?.(now().getTime() - startedAtMs, SCOPE_BOOTSTRAP_UNREADABLE_STATE);
+            continue;
+        }
+        lastStatus = status.value;
+        lastState = status.value.lifecycle_state;
+        options.onPoll?.(now().getTime() - startedAtMs, lastState);
+        if (lastState !== lastReportedState) {
+            lastReportedState = lastState;
+            options.onTransition?.(lastState, status.value);
+        }
+        if (lastState === "ready") {
+            if (status.value.indexed_commit_sha !== null &&
+                status.value.indexed_commit_sha === status.value.cut_commit_sha) {
+                return { kind: "ready", status: status.value };
+            }
+            return { kind: "ready_mismatch", status: status.value };
+        }
+        if (lastState === "failed") {
+            return { kind: "failed", status: status.value, reason: status.value.last_error ?? "unknown" };
+        }
+    }
+    return { kind: "timeout", lastState, lastStatus };
+}