@bridge_gpt/mcp-server 0.2.51 → 0.2.53

package/build/conductor/local-merge.js

@@ -35,20 +35,26 @@
 import { spawn } from "child_process";
 import { pollCiChecksForCommit, ConductorBridgeApiError, safeDiagnosticMessage, } from "./bridge-api-client.js";
 import { isLikelyGhMergeConflictOutput, isPrMergeConflict, parseGhPrMergeabilityFields, } from "./github-mergeability.js";
-import { selectLatestChecksByName } from "./latest-check-selector.js";
+import { normalizeSelectorCheckName, selectLatestChecksByName } from "./latest-check-selector.js";
 const MERGE_METHODS = new Set(["squash", "merge", "rebase"]);
 /**
  * `gh pr view` field set for a merged-state / head-drift read. Includes
  * `mergeCommit` so an already-merged PR can be detected (and its merge commit
  * SHA recorded) directly from the same read that guards head drift.
+ *
+ * BAPI-1021: also includes `baseRefName`/`headRefName` so the ref-verification
+ * guard (AC-11) can compare the PR's CURRENT base/head branches against the
+ * caller's expectations from the same single read — no extra `gh pr view`
+ * subprocess is added solely for ref verification.
  */
-const PR_STATE_JSON = "headRefOid,state,mergeCommit";
+const PR_STATE_JSON = "headRefOid,state,mergeCommit,baseRefName,headRefName";
 /**
  * Broader `gh pr view` field set used only for the post-merge-failure re-read:
  * it must detect BOTH "already merged at the expected head" and a merge conflict
- * (`mergeable` / `mergeStateStatus`) from a single read.
+ * (`mergeable` / `mergeStateStatus`) from a single read. BAPI-1021: also carries
+ * `baseRefName`/`headRefName` for the same ref-verification reason as above.
  */
-const PR_STATE_MERGEABILITY_JSON = "headRefOid,state,mergeCommit,mergeable,mergeStateStatus";
+const PR_STATE_MERGEABILITY_JSON = "headRefOid,state,mergeCommit,mergeable,mergeStateStatus,baseRefName,headRefName";
 /**
  * Hard wall-clock cap on every `gh` subprocess. The epic-tick runs in a single
  * stateless process — a `gh` call that hangs (network stall, an auth prompt that
@@ -166,12 +172,50 @@ function buildResponse(request, status, reason, terminal, ledgerEvents) {
         ledger_events: ledgerEvents,
     };
 }
+/**
+ * BAPI-1001 — check-run conclusions GitHub itself treats as NEUTRAL. A required
+ * check concluding `skipped` or `neutral` does not hold a pull request back on
+ * GitHub, which reports it CLEAN/MERGEABLE. Deliberately NOT a catch-all for
+ * "not success": `failure`, `cancelled`, `timed_out`, `action_required`, every
+ * pending/queued state, and every unrecognized conclusion stay non-green.
+ *
+ * Kept LOCAL to merge admission rather than pushed into the shared selector: the
+ * selector's other consumers render CI state for humans, where a skipped check
+ * is worth showing as skipped rather than silently folded into "pass".
+ */
+const NEUTRAL_CHECK_CONCLUSIONS = new Set(["skipped", "neutral"]);
+/** True when a check record's `conclusion` is one GitHub treats as neutral. */
+function isNeutralCheckRecord(record) {
+    if (!record)
+        return false;
+    const conclusion = typeof record.conclusion === "string" ? record.conclusion.trim().toLowerCase() : "";
+    return NEUTRAL_CHECK_CONCLUSIONS.has(conclusion);
+}
 /**
  * Decide whether every required CI check is green for the polled head SHA. When
  * the gate lists no required checks, fall back to the poll's `all_passed` flag.
  * Defensive against the poll response's exact shape: a check counts as green if
  * any of `conclusion==="success"`, `status==="success"`, `green===true`, or
  * `bucket==="pass"`.
+ *
+ * BAPI-1001 adds neutral arbitration AHEAD of the BAPI-933 latest-wins selection.
+ * Four outcomes, and each is a distinct case:
+ *
+ * - `success` (by any of the four spellings above) — green, unchanged.
+ * - `skipped` / `neutral` — non-blocking. It never becomes the selected record
+ *   for a name that also carries a meaningful observation, and when it is the
+ *   ONLY observation for a required name it passes, because GitHub admits it.
+ * - a meaningful failure (`failure`, `cancelled`, `timed_out`,
+ *   `action_required`, an unorderable conflict) — non-green, unchanged. A
+ *   neutral duplicate can never hide one, because neutral records are the ones
+ *   dropped, never the meaningful ones.
+ * - pending, queued, missing, malformed — non-green, unchanged.
+ *
+ * The defect this closes: BAPI-996's PR #1177 carried two `claude-review`
+ * check-runs at the head, one `success` and one NEWER `skipped`. Latest-wins
+ * selected the `skipped` record, `isGreen` read it as not-green, and the bounded
+ * CI-green wait refused a CLEAN/MERGEABLE pull request with `ci_not_green` until
+ * the merge re-fire budget parked the ticket.
  */
 export function allRequiredChecksGreen(pollResponse, requiredChecks) {
     if (pollResponse === null || typeof pollResponse !== "object")
@@ -198,14 +242,43 @@ export function allRequiredChecksGreen(pollResponse, requiredChecks) {
     // reported MERGEABLE/CLEAN (BAPI-912 / PR #1107, three parked attempts).
     // `selectLatestChecksByName` also OMITS a name whose duplicates could not be
     // ordered, so the `every(...)` below fails it closed as a missing context.
-    const { byName } = selectLatestChecksByName(rawChecks);
+    // Neutral arbitration runs BEFORE selection, because recency cannot arbitrate
+    // between "a verdict" and "no verdict". A neutral duplicate is withheld from
+    // the selector whenever the same name also carries a meaningful observation,
+    // so latest-wins then arbitrates only among records that actually decided
+    // something. Names with nothing but neutral records keep them and are judged
+    // by `isGreen` below; every meaningful record is passed through untouched, so
+    // the selector's ambiguity/fail-closed handling is unchanged.
+    const meaningfulNames = new Set();
+    for (const record of rawChecks) {
+        if (record === null || typeof record !== "object" || Array.isArray(record))
+            continue;
+        const name = normalizeSelectorCheckName(record.name);
+        if (name !== null && !isNeutralCheckRecord(record))
+            meaningfulNames.add(name);
+    }
+    const arbitrated = rawChecks.filter((record) => {
+        if (record === null || typeof record !== "object" || Array.isArray(record))
+            return true;
+        const name = normalizeSelectorCheckName(record.name);
+        if (name === null)
+            return true;
+        return !(isNeutralCheckRecord(record) && meaningfulNames.has(name));
+    });
+    const { byName } = selectLatestChecksByName(arbitrated);
     const isGreen = (c) => {
         if (!c)
             return false;
         const conclusion = typeof c.conclusion === "string" ? c.conclusion.toLowerCase() : "";
         const status = typeof c.status === "string" ? c.status.toLowerCase() : "";
         const bucket = typeof c.bucket === "string" ? c.bucket.toLowerCase() : "";
-        return c.green === true || conclusion === "success" || status === "success" || bucket === "pass";
+        return (c.green === true ||
+            conclusion === "success" ||
+            status === "success" ||
+            bucket === "pass" ||
+            // Only reachable when the name carried no meaningful observation at all;
+            // otherwise the arbitration above already removed this record.
+            isNeutralCheckRecord(c));
     };
     return requiredChecks.every((name) => isGreen(byName.get(name)));
 }
@@ -229,11 +302,26 @@ function isMergedAtExpectedHead(state, headOid, expectedSha) {
         headOid.toLowerCase() === expectedSha.toLowerCase());
 }
 /**
- * Read the PR's `headRefOid` + `state` + `mergeCommit` via `gh pr view`. Extracted
- * so the head-drift / not-open / already-merged guard can run BOTH before the CI
- * wait and again right before provider merge (BAPI-566 Bug B: the head can drift
- * while we wait for CI). Returns the raw parsed values; the caller applies the
- * MERGED-at-head / OPEN / exact-head checks.
+ * Coerce a parsed `gh pr view` field to a bounded, nonblank ref name, or
+ * `undefined` when the field is absent, not a string, or whitespace-only.
+ * BAPI-1021: an unusable observed ref must be treated by the ref-verification
+ * guard as a MISMATCH when the caller supplied an expectation, never silently
+ * skipped — this coercion just normalizes the raw value, it does not decide
+ * that policy.
+ */
+function readBoundedRefName(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Read the PR's `headRefOid` + `state` + `mergeCommit` + `baseRefName` +
+ * `headRefName` via `gh pr view`. Extracted so the head-drift / not-open /
+ * already-merged / ref-mismatch guard can run BOTH before the CI wait and
+ * again right before provider merge (BAPI-566 Bug B: the head can drift while
+ * we wait for CI). Returns the raw parsed values; the caller applies the
+ * MERGED-at-head / OPEN / exact-head / matching-ref checks.
  */
 async function readPrMergeState(run, ghEnv, pr, json = PR_STATE_JSON) {
     const view = await run("gh", ["pr", "view", String(pr), "--json", json], ghEnv);
@@ -248,6 +336,8 @@ async function readPrMergeState(run, ghEnv, pr, json = PR_STATE_JSON) {
             headOid: parsed.headRefOid,
             state: parsed.state,
             mergeCommitOid: extractMergeCommitOid(parsed),
+            baseRefName: readBoundedRefName(parsed.baseRefName),
+            headRefName: readBoundedRefName(parsed.headRefName),
             raw: parsed,
         };
     }
@@ -381,6 +471,8 @@ async function waitForRequiredChecksGreen(pollCi, access, expectedSha, requiredC
  */
 export function makeLocalMergeExecutor(options = {}, deps = {}) {
     const method = resolveLocalMergeMethod(options.method);
+    const expectedBaseBranch = readBoundedRefName(options.expectedBaseBranch);
+    const expectedHeadBranch = readBoundedRefName(options.expectedHeadBranch);
     const rawRun = deps.runCommand ?? defaultRunCommand;
     // Always await the runner: the production default is async (a hung `gh` would
     // otherwise block the event loop and starve the executor heartbeat), and
@@ -479,6 +571,15 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
         if (isMergedAtExpectedHead(firstRead.state, firstRead.headOid, expectedSha)) {
             return buildAlreadyMergedResponse(request, baseDetails, firstRead.mergeCommitOid);
         }
+        // 2b. BAPI-1021 (AC-11) — refuse before any provider merge if the PR's current
+        //     base or head branch does not match the caller's expectation. Ordered
+        //     after the already-merged short-circuit (an idempotent success must not
+        //     be turned into a refusal by a since-changed ref) and before the
+        //     head-drift / pr_not_open guards below.
+        const firstRefMismatch = findRefMismatch(expectedBaseBranch, expectedHeadBranch, firstRead);
+        if (firstRefMismatch) {
+            return buildRefMismatchResponse(request, baseDetails, firstRefMismatch);
+        }
         if (typeof firstRead.headOid !== "string" || firstRead.headOid.toLowerCase() !== expectedSha.toLowerCase()) {
             return fail("head_drift");
         }
@@ -517,6 +618,13 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
             if (isMergedAtExpectedHead(secondRead.state, secondRead.headOid, expectedSha)) {
                 return buildAlreadyMergedResponse(request, baseDetails, secondRead.mergeCommitOid);
             }
+            // 3c. BAPI-1021 (AC-11) — repeat the ordered ref guard here too, so a PR
+            //     retargeted while CI was pending cannot reach the merge command. Same
+            //     ordering rationale as the first-read guard above.
+            const secondRefMismatch = findRefMismatch(expectedBaseBranch, expectedHeadBranch, secondRead);
+            if (secondRefMismatch) {
+                return buildRefMismatchResponse(request, baseDetails, secondRefMismatch);
+            }
             if (typeof secondRead.headOid !== "string" || secondRead.headOid.toLowerCase() !== expectedSha.toLowerCase()) {
                 return fail("head_drift");
             }
@@ -625,6 +733,57 @@ function buildConflictResponse(request, baseDetails, expectedSha, mergeability)
         { type: "merge.conflict", status: "failed", reason, details: conflictDetails },
     ]);
 }
+/**
+ * Compare the PR's CURRENT base/head refs (from a {@link readPrMergeState}
+ * read) against the caller's supplied expectations. Returns the first
+ * mismatch found (base checked before head), or `undefined` when every
+ * supplied expectation matches.
+ *
+ * An expectation with no corresponding usable actual ref — absent, not a
+ * string, or whitespace-only, already normalized to `undefined` by
+ * {@link readBoundedRefName} — counts as a MISMATCH, never a skip. Silently
+ * treating an unreadable ref as "nothing to check" would let exactly the
+ * unverifiable case slip through the guard it exists to provide.
+ */
+function findRefMismatch(expectedBaseBranch, expectedHeadBranch, actual) {
+    if (expectedBaseBranch !== undefined && actual.baseRefName !== expectedBaseBranch) {
+        return { field: "base", expected: expectedBaseBranch, actual: actual.baseRefName ?? "" };
+    }
+    if (expectedHeadBranch !== undefined && actual.headRefName !== expectedHeadBranch) {
+        return { field: "head", expected: expectedHeadBranch, actual: actual.headRefName ?? "" };
+    }
+    return undefined;
+}
+/**
+ * Build a `ref_mismatch` failure (AC-11): a deliberate, terminal safety
+ * refusal issued BEFORE any provider-merge subprocess when the PR's current
+ * base or head branch does not match the caller's expectation.
+ *
+ * Details are allowlisted to the expected/actual branch values only — never
+ * raw `gh` output, stderr, response bodies, credentials, or exception text,
+ * mirroring {@link buildConflictResponse}'s secret-safety contract. The
+ * message states plainly that no provider merge was attempted and directs the
+ * operator to rebuild or cherry-pick the change against the expected run base
+ * — retargeting the pull request in the GitHub UI would only relabel a branch
+ * that has already drifted from what the run actually intends to merge, not
+ * fix it.
+ */
+function buildRefMismatchResponse(request, baseDetails, mismatch) {
+    const reason = "ref_mismatch";
+    const details = {
+        ...baseDetails,
+        mismatched_field: mismatch.field,
+        [`expected_${mismatch.field}_branch`]: mismatch.expected,
+        [`actual_${mismatch.field}_branch`]: mismatch.actual,
+        message: `No provider merge was attempted: the pull request's current ${mismatch.field} branch ` +
+            `does not match the run's expected ${mismatch.field} branch. Rebuild or cherry-pick the ` +
+            "change against the expected run base rather than retargeting the pull request in the " +
+            "GitHub UI.",
+    };
+    return buildResponse(request, "failed", reason, false, [
+        { type: "merge.failed", status: "failed", reason, details },
+    ]);
+}
 /**
  * Probe whether this host can merge with `gh` at all, BEFORE any merge is
  * attempted.

package/build/conductor/readiness-cli.js

@@ -0,0 +1,152 @@
+/**
+ * The `conductor readiness` command surface (BAPI-1055, AC-6).
+ *
+ * A CLI subcommand, deliberately, and NOT an MCP tool. Every peer diagnostic in
+ * this package — `doctor`, `plane`, `drive-epic`, `executor`, `install` — is an
+ * `argv[0]` subcommand dispatched before MCP server construction, and this one
+ * inherits that standard: stdout carries the report, stderr carries only fixed
+ * sanitized notices, and no tool is registered, so the budget-pinned `tools/list`
+ * surface is untouched.
+ *
+ * THIN BY CONSTRUCTION. Argument parsing, dependency construction, and
+ * formatting live here; every probe, verdict, and mapping belongs to
+ * {@link file:./readiness.ts} and the collectors it composes.
+ *
+ * ## Advisory exit policy
+ *
+ * This command returns 0 for every readiness outcome — pass, warn, fail, skip,
+ * an unavailable source, and a malformed upstream response alike. It never
+ * mutates `process.exitCode`, never brings a plane up, never approves a run, and
+ * never executes a remediation. An advisory command that could exit non-zero
+ * would be a gate, and the hard gates are `drive-epic`'s
+ * `V2_READINESS_REQUIREMENTS` and the server-side admission.
+ *
+ * The only non-zero path is a usage error (an unknown flag), which is the
+ * command failing to run at all rather than a readiness verdict.
+ *
+ * ## Credentials
+ *
+ * Resolution goes through `resolveConductorBridgeApiAccess`, which reads
+ * `BAPI_API_KEY` from the parent environment and then the user-scoped store at
+ * `~/.config/bridge/credentials.json`. That is the shell-spawned credential
+ * rule: this command runs in a plain shell, which never sees `.mcp.json` env —
+ * that file is visible to the MCP server process only.
+ */
+import os from "node:os";
+import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import { collectConductorReadinessGate, formatConductorReadinessGateReport, } from "./readiness.js";
+import { resolveConductorBridgeApiAccess } from "./bridge-api-client.js";
+import { claudeReviewWorkflowPath } from "../claude-review-workflow.js";
+import { runDefaultPlanePreflight } from "../plane/cli.js";
+/** Fixed notice emitted to stderr when a source could not be collected. */
+export const READINESS_COLLECTION_NOTICE = "one or more readiness sources could not be collected; the affected prerequisites are reported as failures.";
+/** Usage text for `conductor readiness`. */
+export function getReadinessUsage() {
+    return [
+        "Usage: conductor readiness [--json] [--no-deny-probe]",
+        "",
+        "Read-only ADVISORY report of every conductor prerequisite, consolidated from the",
+        "Bridge install checklist, the conductor doctor, the plane preflight, and the",
+        "server conductor-readiness collector. Each prerequisite reports pass/warn/fail/skip",
+        "and, on a failure, exactly ONE named remediation.",
+        "",
+        "Remediations are NOT run automatically. This command changes nothing: it starts no",
+        "plane, approves no run, writes no file, and always exits 0 — `drive-epic` remains",
+        "the only route-selection gate and the server-side admission the only hard refusal.",
+        "",
+        "Options:",
+        "  --json            Print the versioned structured report as JSON",
+        "  --no-deny-probe   Accepted for parity with `conductor doctor`; inert here, because",
+        "                    this command never spawns the deny-enforcement probe",
+        "  --help            Print this usage message",
+    ].join("\n");
+}
+/** Parse `conductor readiness` argv. Unknown flags and positionals are errors. */
+export function parseReadinessArgs(argv) {
+    const parsed = { json: false, help: false, noDenyProbe: false };
+    for (const token of argv) {
+        if (token === "--json")
+            parsed.json = true;
+        else if (token === "--no-deny-probe")
+            parsed.noDenyProbe = true;
+        else if (token === "--help" || token === "-h")
+            parsed.help = true;
+        else
+            return { error: `Unknown argument "${token}". Run "conductor readiness --help" for usage.` };
+    }
+    return parsed;
+}
+/**
+ * Build the production report for `repoRoot`.
+ *
+ * Every seam is a real, READ-ONLY one: the install doctor's own GET, the
+ * conductor doctor's local inspections, and the same plane preflight
+ * `plane up` and `drive-epic` run. Nothing is re-implemented here.
+ */
+async function collectProductionReport(repoRoot, env) {
+    const accessResult = await resolveConductorBridgeApiAccess({ env, cwd: repoRoot });
+    const access = accessResult.ok ? accessResult.access : null;
+    return collectConductorReadinessGate({
+        // Never guessed: an unresolved identity is reported as such rather than
+        // invented, and the repository ROOT is never placed in the report at all.
+        repoName: access?.repoName ?? null,
+        installDoctor: {
+            access,
+            accessError: accessResult.ok ? undefined : accessResult.error,
+            fetch: (...args) => fetch(...args),
+            // The consolidated gate reports workflow presence as a fact; it selects no
+            // per-run review policy, so applicability is evaluated under the policy
+            // that always consumes the workflow's verdict.
+            reviewPolicySource: "verdict_protocol",
+            readWorkflowFile: () => fsReadFile(claudeReviewWorkflowPath(repoRoot), "utf-8"),
+            projectRoot: repoRoot,
+            installDoctorDeps: {
+                env,
+                cwd: repoRoot,
+                platform: process.platform,
+                homedir: os.homedir,
+                readFile: (filePath) => fsReadFile(filePath, "utf-8"),
+                stat: (filePath) => fsStat(filePath),
+                fetch: (...args) => fetch(...args),
+            },
+        },
+        // The deny-enforcement probe is never spawned from this command; the check
+        // is reported as an explicit skip naming `conductor doctor` instead.
+        conductorDoctorDeps: { env, skipDenyProbe: true },
+        runPlanePreflight: () => runDefaultPlanePreflight(repoRoot, env),
+    });
+}
+/**
+ * Run `conductor readiness`.
+ *
+ * Returns 0 for every readiness outcome; see the module docstring. The only
+ * non-zero return is a usage error.
+ */
+export async function runConductorReadinessCommand(argv, deps = {}) {
+    const sinks = deps.sinks ?? {
+        stdout: (line) => console.log(line),
+        stderr: (line) => console.error(line),
+    };
+    const parsed = parseReadinessArgs(argv);
+    if ("error" in parsed) {
+        sinks.stderr(`Error: ${parsed.error}`);
+        return 1;
+    }
+    if (parsed.help) {
+        sinks.stdout(getReadinessUsage());
+        return 0;
+    }
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const collect = deps.collect ?? ((repoRoot) => collectProductionReport(repoRoot, env));
+    const report = await collect(cwd);
+    // Fixed, sanitized, and stderr-only: never a credential, exception, header,
+    // body, subprocess output, or absolute path. It fires on a COLLECTION gap,
+    // not on a failed prerequisite — a report that says "a source is missing"
+    // every time an ordinary check fails teaches operators to ignore it.
+    if (report.unavailableSources.length > 0)
+        sinks.stderr(READINESS_COLLECTION_NOTICE);
+    sinks.stdout(parsed.json ? JSON.stringify(report) : formatConductorReadinessGateReport(report));
+    // Advisory: the exit code is a constant, never derived from a check status.
+    return 0;
+}