@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/merge-pull-request.js

@@ -1,12 +1,30 @@
 /**
  * merge_pull_request — the fail-closed, server-decided protected merge tool (BAPI-799).
  *
- * The agent asks; the SERVER decides. This module holds no VCS credential, spawns
- * no `gh` subprocess, and implements no merge of its own. It resolves the
- * authoritative required-check set, constructs the deterministic action key, POSTs
- * the protected root-mounted route, and renders the server's decision as one
- * compact JSON text envelope. Every branch — including every error branch —
- * resolves to that envelope; nothing throws through the MCP transport.
+ * The agent asks; the SERVER decides. This module holds no VCS credential and
+ * implements no merge policy of its own. It resolves the authoritative
+ * required-check set, constructs the deterministic action key, POSTs the
+ * protected root-mounted route, and renders the server's decision as one compact
+ * JSON text envelope. Every branch — including every error branch — resolves to
+ * that envelope; nothing throws through the MCP transport.
+ *
+ * WHO PERFORMS THE WRITE (BAPI-832)
+ * ---------------------------------
+ * The server decides; the WRITE may happen here. GitHub's merge endpoint needs
+ * `contents: write` and this org's App installation is `contents: read`, so a
+ * server-side merge returns `provider_unauthorized` no matter how green the pull
+ * request is. In `local` mode — the default — the server runs its entire
+ * deterministic tail (action key, lease, head-SHA drift guard, review gate,
+ * workflow-file guard, CI revalidation) and returns
+ * `approved_for_local_execution`; this module then performs the merge with the
+ * OPERATOR's `gh` login, exactly as v2's `merge` job has since BAPI-572, and
+ * reports the result to the completion route so the ledger closes.
+ *
+ * That local path is reachable ONLY from a live approval for this exact pull
+ * request and head SHA. This module still holds no credential of its own — it
+ * borrows the operator's `gh` session — still makes no merge decision, and still
+ * never calls the provider API directly. `merged: true` means the same thing in
+ * both modes, so the caller's mapping is unchanged.
  *
  * WHY A FIXED ENVELOPE
  * --------------------
@@ -43,14 +61,23 @@
  *
  * FROZEN-TREE BOUNDARY
  * --------------------
- * This module lives OUTSIDE `conductor/` and consumes it only through pure,
- * I/O-free seams: `git-ci-types.js`, `done-gate.js`, and `merge-identity.js`. The
+ * This module lives OUTSIDE `conductor/` and consumes it through the pure,
+ * I/O-free seams `git-ci-types.js`, `done-gate.js`, and `merge-identity.js`. The
  * action key and gate identity are imported rather than reimplemented, because a
  * second copy that drifts by one character produces a 409 the caller cannot act on.
+ *
+ * BAPI-832 adds ONE non-pure seam, `local-merge.js`, and only for the local
+ * execution path. It is imported rather than reimplemented for the same reason
+ * the action key is: that module already owns the head-drift guard, the
+ * `--match-head-commit` binding, and the whole ambiguity-resolution ladder that
+ * v2's `merge` job has run in production since BAPI-572. A second `gh pr merge`
+ * call site written from scratch here would be a second chance to get a
+ * privileged write subtly wrong.
  */
 import { DEFAULT_GATE_NAME, REQUIRED_CI_CHECKS_GREEN, REVIEW_STATE, normalizeCheckName, } from "./conductor/git-ci-types.js";
 import { evaluateReviewCondition, normalizeReviewSnapshot, parseDoneGateConfig, } from "./conductor/done-gate.js";
 import { buildGateIdentity, makeMergeActionKey } from "./conductor/merge-identity.js";
+import { resolveLocalMergeMethod, runApprovedLocalMerge, } from "./conductor/local-merge.js";
 /**
  * The exact remediation for a `dry_run`. Fixed text, because a caller that has to
  * infer WHICH setting to flip from a reason code guesses wrong.
@@ -106,6 +133,8 @@ function envelope(merged, outcome, reason, retryHint, evaluatedHeadSha, prNumber
         result.hint = diagnostics.hint;
     if (diagnostics.http_status !== undefined)
         result.http_status = diagnostics.http_status;
+    if (diagnostics.completion !== undefined)
+        result.completion = diagnostics.completion;
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -464,6 +493,162 @@ function interpretMergeResponse(body, expectedHeadSha, prNumber) {
     return malformed();
 }
 // ---------------------------------------------------------------------------
+// BAPI-832: local execution of a server-approved merge
+// ---------------------------------------------------------------------------
+/** The non-terminal status the server returns when it approves a local merge. */
+const LOCAL_APPROVAL_STATUS = "approved_for_local_execution";
+const DEFAULT_MERGE_EXECUTION = "local";
+/** Operator-fixable hints for the two preflight refusals. */
+const LOCAL_GH_HINTS = {
+    local_gh_unavailable: "Install the GitHub CLI (`gh`) on the machine running this MCP server — local merges execute there.",
+    local_gh_unauthenticated: "Run `gh auth login` in the shell that hosts this MCP server — local merges use its GitHub session.",
+};
+/**
+ * Read the repository's merge execution mode.
+ *
+ * Mode is server-side configuration, never a tool argument: an agent must not be
+ * able to choose who performs a privileged write. An unreadable or unrecognized
+ * value falls back to `local`, which is the mode that works on an installation
+ * without `contents: write` — defaulting to the broken mode on a transient
+ * config read failure would park a perfectly mergeable pull request.
+ */
+async function resolveMergeExecutionMode(deps) {
+    try {
+        const resp = await (deps.fetchImpl ?? fetch)(deps.buildGetUrl("/epic-runs/supervisor-config/defaults/", { repo_name: deps.repoName }), { headers: await deps.getHeaders() });
+        if (!resp.ok)
+            return DEFAULT_MERGE_EXECUTION;
+        const body = await readJson(resp);
+        if (!isPlainObject(body))
+            return DEFAULT_MERGE_EXECUTION;
+        return body.merge_execution === "server" ? "server" : DEFAULT_MERGE_EXECUTION;
+    }
+    catch {
+        return DEFAULT_MERGE_EXECUTION;
+    }
+}
+/**
+ * Confirm an approval body really authorizes THIS merge.
+ *
+ * The local path is the one place this tool performs a privileged write, so the
+ * approval it acts on must name the same pull request, the same head commit, and
+ * the same action key the request was built from. Anything else — a stale body, a
+ * mismatched response, a confused proxy — is refused rather than merged.
+ */
+function localApprovalMismatch(body, prNumber, expectedHeadSha, actionKey) {
+    return (body.pr_number !== prNumber ||
+        typeof body.expected_head_sha !== "string" ||
+        body.expected_head_sha.toLowerCase() !== expectedHeadSha.toLowerCase() ||
+        body.action_key !== actionKey);
+}
+/** Pull the merge commit SHA out of the local executor's success ledger events. */
+function mergeShaFromLedger(response) {
+    const events = Array.isArray(response.ledger_events) ? response.ledger_events : [];
+    for (const event of events) {
+        if (!isPlainObject(event) || event.type !== "merge.succeeded")
+            continue;
+        const details = isPlainObject(event.details) ? event.details : {};
+        const sha = details.merge_commit_sha;
+        if (typeof sha === "string" && SHA_RE.test(sha))
+            return sha;
+    }
+    return undefined;
+}
+/**
+ * Report a local execution result to the completion route.
+ *
+ * Returns the parsed response body, or `null` when the report could not be
+ * delivered. The distinction matters in only one direction: an undelivered
+ * report after a SUCCESSFUL merge leaves a real merge unrecorded server-side,
+ * which the caller is told about via `completion: "unreported"`.
+ */
+async function reportLocalCompletion(deps, prNumber, body) {
+    try {
+        const resp = await (deps.fetchImpl ?? fetch)(deps.buildApiUrl(`/vcs/pull-requests/${prNumber}/merge/complete`), {
+            method: "POST",
+            headers: await deps.getPostHeaders(),
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            await deps.handleResponse(resp).catch(() => "");
+            return null;
+        }
+        return await readJson(resp);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Perform a server-approved merge with the operator's `gh`, then close the ledger.
+ *
+ * Fail-closed in both directions. A preflight or executor failure is reported to
+ * the completion route BEFORE returning, so the lease is released rather than
+ * left to time out; and a refusal here is always `needs_human`, because every
+ * local failure this can produce is an operator fix, not a wait.
+ */
+async function executeApprovedLocalMerge(deps, approval, prNumber, expectedHeadSha, actionKey) {
+    if (localApprovalMismatch(approval, prNumber, expectedHeadSha, actionKey)) {
+        return envelope(false, "refused", "local_approval_mismatch", "needs_human", expectedHeadSha, prNumber);
+    }
+    const method = resolveLocalMergeMethod(approval.merge_method);
+    const request = {
+        repo_name: deps.repoName,
+        pr_number: prNumber,
+        expected_head_sha: expectedHeadSha,
+        gate: { name: DEFAULT_GATE_NAME },
+        action_key: actionKey,
+    };
+    let local;
+    try {
+        const runLocal = deps.runLocalMerge ?? runApprovedLocalMerge;
+        local = await runLocal(request, { method }, { env: process.env });
+    }
+    catch {
+        // The executor itself threw. Treat it exactly like a reported failure: close
+        // the lease, then refuse. Never assume a merge that could not be observed.
+        await reportLocalCompletion(deps, prNumber, {
+            repo_name: deps.repoName,
+            action_key: actionKey,
+            expected_head_sha: expectedHeadSha,
+            result: "failed",
+            reason: "gh_merge_failed",
+        });
+        return envelope(false, "refused", "gh_merge_failed", "needs_human", expectedHeadSha, prNumber);
+    }
+    const localReason = typeof local.reason === "string" ? local.reason : null;
+    if (local.status === "succeeded") {
+        const result = localReason === "already_merged" ? "already_merged" : "merged";
+        const mergeSha = mergeShaFromLedger(local);
+        const completion = await reportLocalCompletion(deps, prNumber, {
+            repo_name: deps.repoName,
+            action_key: actionKey,
+            expected_head_sha: expectedHeadSha,
+            result,
+            ...(mergeSha ? { merge_sha: mergeSha } : {}),
+        });
+        // The merge is real whether or not the report landed. Reporting `merged:
+        // false` here because a bookkeeping call failed would strand a merged pull
+        // request and invite a second merge attempt.
+        if (completion === null) {
+            return envelope(true, result === "already_merged" ? "already_merged" : "merged", result, null, expectedHeadSha, prNumber, { completion: "unreported" });
+        }
+        return envelope(true, result === "already_merged" ? "already_merged" : "merged", result, null, expectedHeadSha, prNumber);
+    }
+    // --- local failure ------------------------------------------------------
+    const reason = localReason ?? "gh_merge_failed";
+    await reportLocalCompletion(deps, prNumber, {
+        repo_name: deps.repoName,
+        action_key: actionKey,
+        expected_head_sha: expectedHeadSha,
+        result: "failed",
+        reason,
+    });
+    const hint = LOCAL_GH_HINTS[reason];
+    return envelope(false, "refused", reason, "needs_human", expectedHeadSha, prNumber, {
+        ...(hint ? { hint } : {}),
+    });
+}
+// ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
 /**
@@ -516,6 +701,10 @@ export async function mergePullRequestHandler(deps, args) {
         const actionKey = makeMergeActionKey(deps.repoName, prNumber, expectedHeadSha, gateIdentity);
         // The body is built from server-side values only. No caller-supplied field is
         // spread in, so an extra runtime `repo_name` argument cannot retarget the merge.
+        // Mode is resolved server-side and sent explicitly. The WIRE default is
+        // `server` so pre-BAPI-832 callers are unaffected; this tool's default is
+        // `local`, because `server` cannot merge on a `contents: read` installation.
+        const executionMode = await resolveMergeExecutionMode(deps);
         const mergeBody = {
             repo_name: deps.repoName,
             expected_head_sha: expectedHeadSha,
@@ -525,6 +714,7 @@ export async function mergePullRequestHandler(deps, args) {
                 required_checks: resolution.checks,
             },
             action_key: actionKey,
+            execution: executionMode,
         };
         // (3) POST the protected root-mounted route. Wrapped on its own so a rejection
         // AFTER dispatch is reported as genuinely unknown rather than as a failure.
@@ -552,7 +742,16 @@ export async function mergePullRequestHandler(deps, args) {
                 http_status: mergeResp.status,
             }));
         }
-        return text(interpretMergeResponse(await readJson(mergeResp), expectedHeadSha, prNumber));
+        const mergeJson = await readJson(mergeResp);
+        // (4) A local approval is not a decision to RENDER — it is a decision to ACT
+        // ON. Gated on having actually asked for `local`, so a stray or replayed
+        // approval can never provoke a privileged write this tool did not request.
+        if (executionMode === "local" &&
+            isPlainObject(mergeJson) &&
+            mergeJson.status === LOCAL_APPROVAL_STATUS) {
+            return text(await executeApprovedLocalMerge(deps, mergeJson, prNumber, expectedHeadSha, actionKey));
+        }
+        return text(interpretMergeResponse(mergeJson, expectedHeadSha, prNumber));
     }
     catch {
         // Containment: never throw through the MCP transport, and never serialize the