@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/conductor/bridge-api-client.js

@@ -11,7 +11,8 @@
  */
 import os from "node:os";
 import { readFile, stat } from "node:fs/promises";
-import { resolveBapiCredentials } from "../credential-store.js";
+import { resolveBapiCredentials, resolveEpicLaunchCredential } from "../credential-store.js";
+import { readEpicLaunchProfile, resolveEpicLaunchTarget, } from "../epic-launch-profile.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
 import { normalizePrNumber, normalizeSha } from "./git-ci-types.js";
 import { ConductorValidationError } from "./errors.js";
@@ -63,6 +64,87 @@ export async function resolveConductorBridgeApiAccess(deps = {}) {
         : CONDUCTOR_DEFAULT_BASE_URL;
     return { ok: true, access: { repoName, apiKey: credResult.credentials.apiKey, baseUrl } };
 }
+/**
+ * The STRONGER launch-resolution contract (BAPI-1260), used by `drive-epic` and
+ * by a `setup-epic` that was handed a launch selection. The order is the point:
+ *
+ *   1. the selected profile is read and validated (host-local, read-only);
+ *   2. the TARGET is decided from `--base-url`, the profile, and `BAPI_BASE_URL`
+ *      — conflicts refuse, and an absent target is refused, never defaulted to
+ *      {@link CONDUCTOR_DEFAULT_BASE_URL};
+ *   3. the repository is decided (profile binding, then `--repo`, then the
+ *      shared resolver);
+ *   4. only then is a credential looked up, coupled to that target AND that
+ *      repository ({@link resolveEpicLaunchCredential}).
+ *
+ * Nothing is sent anywhere by this function. {@link resolveConductorBridgeApiAccess}
+ * is deliberately left as it is for every other client.
+ */
+export async function resolveEpicLaunchBridgeApiAccess(selection, deps = {}) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const homedir = deps.homedir ?? os.homedir;
+    const platform = deps.platform ?? process.platform;
+    const readFileImpl = deps.readFile ?? ((p) => readFile(p, "utf-8"));
+    const statImpl = deps.stat ?? ((p) => stat(p));
+    let profile = null;
+    if (selection.profileName !== undefined) {
+        const read = await readEpicLaunchProfile(selection.profileName, {
+            env,
+            homedir,
+            readFile: readFileImpl,
+            host: (deps.hostname ?? os.hostname)(),
+        });
+        if (!read.ok)
+            return { ok: false, kind: "profile-unusable", error: read.message };
+        profile = read.profile;
+    }
+    const target = resolveEpicLaunchTarget({
+        flagBaseUrl: selection.baseUrl,
+        flagRepo: deps.repoName,
+        profile,
+        env,
+    });
+    if (!target.ok)
+        return { ok: false, kind: target.kind, error: target.message };
+    const repoName = target.repoName ||
+        deps.repoName?.trim() ||
+        (await resolveStartTicketsRepoName({ env, cwd, readFile: readFileImpl }));
+    if (!repoName) {
+        return {
+            ok: false,
+            kind: "repo-missing",
+            error: "could not resolve repo name (set BAPI_REPO_NAME or add a valid .bridge/config)",
+        };
+    }
+    let cred;
+    try {
+        cred = await resolveEpicLaunchCredential(repoName, target.baseUrl, {
+            env,
+            homedir,
+            platform,
+            readFile: readFileImpl,
+            stat: statImpl,
+        });
+    }
+    catch {
+        return { ok: false, kind: "credentials-unavailable", error: "failed to resolve Bridge API credentials" };
+    }
+    if (!cred.ok) {
+        const bindingFailure = cred.kind === "binding-unbound" || cred.kind === "binding-mismatch" || cred.kind === "ambient-key-unbound";
+        // The binding messages are fixed sentences naming the target KEY and the
+        // store path only; the generic store failures stay generic as before.
+        return bindingFailure
+            ? { ok: false, kind: "credential-unbound", error: cred.error }
+            : { ok: false, kind: "credentials-unavailable", error: "Bridge API credentials unavailable" };
+    }
+    return {
+        ok: true,
+        access: { repoName, apiKey: cred.apiKey, baseUrl: target.baseUrl },
+        targetSource: target.source,
+        profile,
+    };
+}
 /**
  * Build a `${baseUrl}/jira${apiPath}` URL with query params, trimming trailing
  * slashes on the base so there is never a double slash after the host. Query
@@ -364,8 +446,15 @@ export function safeDiagnosticMessage(err, fallback) {
     }
     return fallback;
 }
-/** GET auth headers. The API key travels ONLY in a header, never in the URL. */
-function conductorGetHeaders(access) {
+/**
+ * GET auth headers. The API key travels ONLY in a header, never in the URL.
+ *
+ * Exported (BAPI-1133) so a caller outside this module — `setup-epic.ts`'s
+ * {@link ConductorBridgeApiAccess}-based adapter for
+ * `resolveMergeExecutionMode`'s narrow dependency shape — can build the same
+ * headers without a second copy of this one-line mapping.
+ */
+export function conductorGetHeaders(access) {
     return { "X-API-Key": access.apiKey };
 }
 /**
@@ -1976,12 +2065,109 @@ export async function getEpicPlan(access, epicKey, planVersion, fetchImpl = glob
     const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+/**
+ * BAPI-1252: the backend's closed canonical refusal vocabulary, mirrored as
+ * string literals (the Python source is `api/models/canonical_index_state.py`;
+ * a test pins the two together). A refusal carries exactly one of these and
+ * nothing else — no SHA, generation, owner, or server error text.
+ */
+export const CANONICAL_REFUSAL_REASONS = [
+    "canonical_validity_unavailable",
+    "canonical_index_unverified",
+    "canonical_source_missing",
+    "canonical_generation_mismatch",
+    "canonical_manifest_mismatch",
+    "canonical_index_advanced",
+    "canonical_capability_unsupported",
+];
+/** The canonical validity states the backend can report. */
+export const CANONICAL_VALIDITY_STATES = ["unverified", "writing", "verified"];
+/** The only canonical manifest versions this client accepts as evidence. */
+export const SUPPORTED_CANONICAL_MANIFEST_VERSIONS = ["v1"];
+const CANONICAL_PROVENANCE_KEYS = [
+    "canonical_validity_state",
+    "canonical_validity_verified",
+    "canonical_source_commit_sha",
+    "canonical_generation",
+    "canonical_manifest_version",
+    "canonical_validity_reason",
+];
+const FULL_COMMIT_SHA_RE = /^[0-9a-f]{40}$/;
+const CANONICAL_GENERATION_RE = /^[A-Za-z0-9_.:-]{1,128}$/;
+/**
+ * BAPI-1252: decode a `/jira/parse-status` body's canonical provenance, failing
+ * CLOSED. Only an explicit `verified` state, a literal `true` verified flag, a
+ * full lowercase 40-character source SHA, a well-formed generation, a supported
+ * manifest version, and no refusal reason decode as evidence. Everything else is
+ * one bounded refusal:
+ *
+ * - all six fields absent (an older server) → `canonical_capability_unsupported`;
+ * - an unknown state, an unknown manifest version, a malformed SHA or
+ *   generation, a non-boolean flag, or an unknown reason token →
+ *   `canonical_capability_unsupported` (the client cannot prove it, so it is not
+ *   proof);
+ * - a known refusal reason → that reason;
+ * - any non-verified state → `canonical_index_unverified`.
+ *
+ * Pure and total: it never throws and never consults lifecycle fields such as
+ * `status` or `indexed_commit_sha`.
+ */
+export function decodeCanonicalProvenance(body) {
+    const unsupported = { verified: false, reason: "canonical_capability_unsupported" };
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return unsupported;
+    const obj = body;
+    const present = CANONICAL_PROVENANCE_KEYS.some((key) => key in obj && obj[key] !== undefined);
+    if (!present)
+        return unsupported;
+    const reason = obj.canonical_validity_reason;
+    if (reason !== undefined && reason !== null) {
+        if (typeof reason !== "string")
+            return unsupported;
+        if (!CANONICAL_REFUSAL_REASONS.includes(reason))
+            return unsupported;
+        return { verified: false, reason: reason };
+    }
+    const flag = obj.canonical_validity_verified;
+    if (flag !== undefined && flag !== null && typeof flag !== "boolean")
+        return unsupported;
+    const state = obj.canonical_validity_state;
+    if (typeof state !== "string")
+        return unsupported;
+    if (!CANONICAL_VALIDITY_STATES.includes(state))
+        return unsupported;
+    if (state !== "verified" || flag !== true) {
+        return { verified: false, reason: "canonical_index_unverified" };
+    }
+    const sha = obj.canonical_source_commit_sha;
+    const generation = obj.canonical_generation;
+    const version = obj.canonical_manifest_version;
+    if (typeof sha !== "string" || !FULL_COMMIT_SHA_RE.test(sha))
+        return unsupported;
+    if (typeof generation !== "string" || !CANONICAL_GENERATION_RE.test(generation)) {
+        return unsupported;
+    }
+    if (typeof version !== "string" ||
+        !SUPPORTED_CANONICAL_MANIFEST_VERSIONS.includes(version)) {
+        return unsupported;
+    }
+    return {
+        verified: true,
+        sourceCommitSha: sha,
+        generation,
+        manifestVersion: version,
+    };
+}
 /**
  * GET `/jira/parse-status?repo_name=<repo>` and return the durable parse-run
  * status. See {@link ParseRepositoryStatusValue} for the full state set (the
  * status surface distinguishes queued/running from terminal succeeded/failed).
  * Throws a sanitized {@link ConductorBridgeApiError} on any transport/auth/server
  * failure. URL + auth are unchanged from the pre-BAPI-527 two-state client.
+ *
+ * BAPI-1252: the body is returned as the server sent it, so a payload from an
+ * older server (no canonical fields) still decodes exactly as before. Canonical
+ * provenance is read from it only through {@link decodeCanonicalProvenance}.
  */
 export async function fetchParseStatus(access, fetchImpl = globalThis.fetch) {
     const url = buildConductorJiraUrl(access.baseUrl, "/parse-status", {
@@ -2085,10 +2271,27 @@ export const CONDUCTOR_REVIEW_ALIGNMENT_STATUSES = new Set([
     "not_configured",
     "invalid",
 ]);
+/** The closed verdict vocabulary the parser accepts. */
+export const REQUIRED_CHECKS_VERIFICATIONS = new Set([
+    "verified",
+    "unknown_name",
+    "unverifiable",
+]);
+/** BAPI-1260 — one mandatory-evidence verdict. Only `confirmed` ever holds. */
+export const ADMISSION_EVIDENCE_VERDICTS = [
+    "confirmed",
+    "denied",
+    "unable_to_verify",
+    "not_applicable",
+];
+/** The evidence schema this client renders. A newer one is shown as unknown, never as held. */
+export const ADMISSION_EVIDENCE_SCHEMA_VERSION = 1;
 /** Upper bound of the server's capped `fresh_reconciler_count` ("two or more"). */
 export const READINESS_FRESH_RECONCILER_COUNT_CAP = 2;
 const READINESS_SOURCES = new Set(["epic", "project_default", "none"]);
 const ACTIONS_LEVELS = new Set(["write", "read", "none", "unknown"]);
+/** The one scope the server reports for the merge-execution block (BAPI-1135). */
+const MERGE_EXECUTION_BRANCH_SCOPES = new Set(["default_branch"]);
 function readinessShapeError() {
     // Deliberately carries NO field name, value, or payload excerpt: a malformed
     // body is untrusted input and its contents must not reach output.
@@ -2169,6 +2372,89 @@ function requireEnum(o, key, allowed) {
         throw readinessShapeError();
     return v;
 }
+/** The five BAPI-1254 supervisor keys, which travel as one all-or-none group. */
+const REQUIRED_CHECKS_VERIFICATION_KEYS = [
+    "required_checks_verification",
+    "required_checks_mismatch_count",
+    "required_checks_unverified_count",
+    "required_checks_evidence_observed_at",
+    "required_checks_evidence_fresh",
+];
+/**
+ * A strict ISO-8601 instant with an EXPLICIT UTC designator (`Z` or `+00:00`).
+ * A timezone-free or offset time is rejected rather than read in local time.
+ */
+const UTC_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|\+00:00)$/;
+function requireNonNegativeInt(o, key) {
+    const v = requireInt(o, key);
+    if (v < 0)
+        throw readinessShapeError();
+    return v;
+}
+/**
+ * Parse the BAPI-1254 required-check verification group, FAIL-CLOSED.
+ *
+ * All five keys ABSENT is an older server: every field becomes `null`, which
+ * every consumer renders as "could not verify" — absence is never verification.
+ * Any key present makes all five mandatory, and each is checked for exact type:
+ * the verdict against its closed vocabulary, both counts as non-negative
+ * integers, the time as an explicit-UTC instant, freshness as a real boolean.
+ * The server's cross-field invariants are then re-applied, because a
+ * contradictory group (a `verified` with a mismatch, a stale `unknown_name`)
+ * is untrusted input, not a verdict to render.
+ */
+function parseRequiredChecksVerification(sup, requiredChecksCount) {
+    const present = REQUIRED_CHECKS_VERIFICATION_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(sup, key) && sup[key] !== undefined);
+    if (present.length === 0) {
+        return {
+            required_checks_verification: null,
+            required_checks_mismatch_count: null,
+            required_checks_unverified_count: null,
+            required_checks_evidence_observed_at: null,
+            required_checks_evidence_fresh: null,
+        };
+    }
+    if (present.length !== REQUIRED_CHECKS_VERIFICATION_KEYS.length)
+        throw readinessShapeError();
+    const verification = requireEnum(sup, "required_checks_verification", REQUIRED_CHECKS_VERIFICATIONS);
+    const mismatch = requireNonNegativeInt(sup, "required_checks_mismatch_count");
+    const unverified = requireNonNegativeInt(sup, "required_checks_unverified_count");
+    const observedAt = sup.required_checks_evidence_observed_at;
+    if (typeof observedAt !== "string" ||
+        !UTC_TIMESTAMP_PATTERN.test(observedAt) ||
+        Number.isNaN(Date.parse(observedAt))) {
+        throw readinessShapeError();
+    }
+    const fresh = requireBool(sup, "required_checks_evidence_fresh");
+    if (requiredChecksCount < 0 || mismatch + unverified > requiredChecksCount) {
+        throw readinessShapeError();
+    }
+    if (verification === "verified" &&
+        !(requiredChecksCount > 0 && mismatch === 0 && unverified === 0 && fresh)) {
+        throw readinessShapeError();
+    }
+    if (verification === "unknown_name" && !(fresh && mismatch > 0))
+        throw readinessShapeError();
+    if (verification === "unverifiable" && mismatch > 0)
+        throw readinessShapeError();
+    return {
+        required_checks_verification: verification,
+        required_checks_mismatch_count: mismatch,
+        required_checks_unverified_count: unverified,
+        required_checks_evidence_observed_at: observedAt,
+        required_checks_evidence_fresh: fresh,
+    };
+}
+/** Optional positive-integer threshold: absent/null from an older server. */
+function parseOptionalPositiveInt(o, key) {
+    const v = o[key];
+    if (v === undefined || v === null)
+        return null;
+    const parsed = requireInt(o, key);
+    if (parsed <= 0)
+        throw readinessShapeError();
+    return parsed;
+}
 /**
  * Validate a raw readiness body into the typed response, FAIL-CLOSED.
  *
@@ -2188,6 +2474,7 @@ export function parseConductorReadinessResponse(body) {
     const rec = requireObject(root.reconciler);
     const exec = requireObject(root.executor);
     const thr = requireObject(root.thresholds);
+    const requiredChecksCount = requireInt(sup, "required_checks_count");
     return {
         repo_name: repoName,
         supervisor: {
@@ -2199,13 +2486,14 @@ export function parseConductorReadinessResponse(body) {
             config_source: requireEnum(sup, "config_source", READINESS_SOURCES),
             config_created_at: requireNullableString(sup, "config_created_at"),
             config_updated_at: requireNullableString(sup, "config_updated_at"),
-            required_checks_count: requireInt(sup, "required_checks_count"),
+            required_checks_count: requiredChecksCount,
             required_checks_empty: requireBool(sup, "required_checks_empty"),
             auto_merge_enabled: requireBool(sup, "auto_merge_enabled"),
             merge_approval_required_set: requireBool(sup, "merge_approval_required_set"),
             review_policy_alignment: parseReviewPolicyAlignment(sup),
             // Absent on a pre-BAPI-694 server, where no repository default can exist.
             review_policy_present: sup.review_policy_present === true,
+            ...parseRequiredChecksVerification(sup, requiredChecksCount),
         },
         github: {
             credentials_readable: requireBool(gh, "credentials_readable"),
@@ -2235,11 +2523,125 @@ export function parseConductorReadinessResponse(body) {
         thresholds: {
             reconciler_stale_after_seconds: requireInt(thr, "reconciler_stale_after_seconds"),
             executor_stale_after_seconds: requireInt(thr, "executor_stale_after_seconds"),
+            required_checks_evidence_max_age_seconds: parseOptionalPositiveInt(thr, "required_checks_evidence_max_age_seconds"),
         },
         review_workflow: parseReviewWorkflow(root),
         conductor_ci_workflow: parseConductorCiWorkflow(root),
         unattended: parseUnattended(root),
         bring_up: parseBringUp(root),
+        merge_execution: parseMergeExecution(root),
+        ...(() => {
+            const evidence = parseAdmissionEvidence(root);
+            return evidence === undefined ? {} : { admission_evidence: evidence };
+        })(),
+    };
+}
+const ADMISSION_EVIDENCE_OWNERS = new Set(["operator", "repository_admin", "bridge_operations"]);
+const BOUNDED_TOKEN = /^[a-z0-9][a-z0-9_.:-]{0,79}$/;
+/**
+ * Parse the optional BAPI-1260 `admission_evidence` block.
+ *
+ * Absent → `undefined` (the key is then omitted from the parsed response).
+ * Present → validated strictly, EXCEPT that an unrecognized verdict is coerced
+ * to `unable_to_verify` rather than failing the whole readiness read: a newer
+ * server's vocabulary must degrade to "not proven", never to "held" and never
+ * to "no readiness at all". Free-text fields are bounded tokens only, so a
+ * payload cannot smuggle prose into operator output.
+ */
+function parseAdmissionEvidence(body) {
+    const raw = body.admission_evidence;
+    if (raw === undefined)
+        return undefined;
+    if (raw === null)
+        return null;
+    const o = requireObject(raw);
+    const schemaVersion = requireInt(o, "schema_version");
+    const observedAt = o.observed_at;
+    if (typeof observedAt !== "string")
+        throw readinessShapeError();
+    if (!Array.isArray(o.records) || o.records.length > 32)
+        throw readinessShapeError();
+    const token = (value, nullable) => {
+        if (value === null && nullable)
+            return null;
+        if (typeof value !== "string" || !BOUNDED_TOKEN.test(value))
+            throw readinessShapeError();
+        return value;
+    };
+    const records = o.records.map((entry) => {
+        const r = requireObject(entry);
+        const verdictRaw = r.verdict;
+        const verdict = ADMISSION_EVIDENCE_VERDICTS.includes(verdictRaw)
+            ? verdictRaw
+            : "unable_to_verify";
+        const owner = r.next_action_owner;
+        if (owner !== null && owner !== undefined && !ADMISSION_EVIDENCE_OWNERS.has(owner)) {
+            throw readinessShapeError();
+        }
+        const maxAge = requireInt(r, "max_age_seconds");
+        if (maxAge <= 0)
+            throw readinessShapeError();
+        const at = r.observed_at;
+        if (at !== null && typeof at !== "string")
+            throw readinessShapeError();
+        return {
+            predicate: token(r.predicate, false),
+            verdict,
+            observed_at: at,
+            source: token(r.source, false),
+            source_version: r.source_version === null || r.source_version === undefined
+                ? null
+                : typeof r.source_version === "string" && r.source_version.length <= 80
+                    ? r.source_version
+                    : (() => {
+                        throw readinessShapeError();
+                    })(),
+            max_age_seconds: maxAge,
+            reason: r.reason === undefined ? null : token(r.reason, true),
+            next_action_owner: (owner ?? null),
+        };
+    });
+    return { schema_version: schemaVersion, observed_at: observedAt, records };
+}
+/**
+ * Parse the optional `merge_execution` block (BAPI-1135).
+ *
+ * Same older-server rule as every optional block above: absent (or null) is
+ * `null`, and a PRESENT block is validated strictly — every boolean through
+ * `requireBool`, the scope through the shared enum parser, and the version as
+ * either `null` or a non-negative integer through `requireInt`.
+ *
+ * A malformed PRESENT block or a malformed present FIELD throws, and is never
+ * degraded to `null`. The distinction is load-bearing: `null` means "this server
+ * does not report it", which is a server-version fact, while a block that claims
+ * to carry merge eligibility and cannot be read is untrusted input. Silently
+ * turning the second into the first would let a corrupt body masquerade as an
+ * older deploy, and the two have different remediations.
+ */
+function parseMergeExecution(body) {
+    const raw = body.merge_execution;
+    if (raw === undefined || raw === null)
+        return null;
+    const o = requireObject(raw);
+    const version = o.merge_workflow_version;
+    let parsedVersion;
+    if (version === null || version === undefined) {
+        parsedVersion = null;
+    }
+    else {
+        parsedVersion = requireInt(o, "merge_workflow_version");
+        if (parsedVersion < 0)
+            throw readinessShapeError();
+    }
+    return {
+        branch_scope: requireEnum(o, "branch_scope", MERGE_EXECUTION_BRANCH_SCOPES),
+        branch_protection_probe_succeeded: requireBool(o, "branch_protection_probe_succeeded"),
+        branch_protection_actions_bot_admitted: requireBool(o, "branch_protection_actions_bot_admitted"),
+        merge_workflow_probe_succeeded: requireBool(o, "merge_workflow_probe_succeeded"),
+        merge_workflow_present: requireBool(o, "merge_workflow_present"),
+        merge_workflow_enabled: requireBool(o, "merge_workflow_enabled"),
+        merge_workflow_version: parsedVersion,
+        merge_workflow_token_write_authority: requireBool(o, "merge_workflow_token_write_authority"),
     };
 }
 /**