@bridge_gpt/mcp-server 0.2.38 → 0.2.39

package/build/conduct-epic/bridge-client.js

@@ -0,0 +1,345 @@
+/**
+ * Bridge API client for the `conduct-epic` CLI (BAPI-802).
+ *
+ * This module lives OUTSIDE `mcp_server/src/conductor/`, which is frozen v1. It
+ * imports from `conductor/bridge-api-client.ts` in the reuse-only direction the
+ * freeze allows — shared URL construction, the access type, and the timeout/
+ * sanitization fetch helpers — and adds nothing under `conductor/`. That import
+ * is recorded in `conductor/README.md`'s survivor table.
+ *
+ * Two contract properties, fixed by `conduct-epic-bridge-client` and relied on by
+ * BAPI-803, which extends this same file:
+ *
+ * - **No function throws.** Every failure — transport, timeout, HTTP status,
+ *   malformed body, even a bad `baseUrl` — resolves to
+ *   `{ ok: false, status, error }`. A CLI that has to wrap each call in
+ *   `try/catch` gets that wrong exactly once, in the recovery path where it
+ *   matters most.
+ * - **The API key never leaves the `X-API-Key` header.** It is not in a URL, a
+ *   query string, a request body, or any returned error text. Unrecognized
+ *   throw values collapse to a stable generic message rather than being
+ *   stringified, because a stringified unknown is exactly how a credential
+ *   escapes.
+ *
+ * Credentials are NOT resolved here: the caller passes an access object it
+ * already obtained from `resolveConductorBridgeApiAccess()`, which reads
+ * `BAPI_API_KEY` then the user-scoped credential store.
+ *
+ * No MCP tool is registered from this module — the `tools/list` token budget is
+ * effectively frozen.
+ */
+import { buildConductorJiraUrl, fetchConductorJsonPostWithTimeout, fetchConductorJsonPutWithTimeout, fetchConductorJsonWithTimeout, fetchConductorReadiness, fetchEffectiveSupervisorConfig, fetchEffectiveSupervisorSetup, fetchEpicRunState, fetchParseStatus, fetchPrReviewStatus, pollCiChecksForCommit, ConductorBridgeApiError, CONDUCTOR_FETCH_TIMEOUT_MS, } from "../conductor/bridge-api-client.js";
+/**
+ * The one message returned for any failure whose cause cannot be described
+ * without risking the credential. Stable so callers can match on it.
+ */
+const GENERIC_ERROR = "Bridge API request failed";
+/** GET headers. The key travels in this header and nowhere else. */
+function getHeaders(access) {
+    return { "X-API-Key": access.apiKey };
+}
+/** POST headers. Same rule, plus the JSON content type. */
+function postHeaders(access) {
+    return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
+}
+/** PUT headers. Identical to {@link postHeaders}; named for the call site. */
+function putHeaders(access) {
+    return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
+}
+/**
+ * Remove the exact API key from a message that is otherwise safe to surface.
+ *
+ * The shared helpers already redact header values from their diagnostics, so
+ * this is a second, independent pass over the final string: the belt is cheap
+ * and the failure it guards against is unrecoverable. Very short keys are left
+ * alone because scrubbing a 1-3 character string would mangle ordinary prose.
+ */
+function scrubKey(text, apiKey) {
+    if (!apiKey || apiKey.length < 4)
+        return text;
+    return text.split(apiKey).join("[REDACTED]");
+}
+/**
+ * Convert any thrown value into a `{ ok: false }` result.
+ *
+ * A `ConductorBridgeApiError` carries a message the shared helper already built
+ * from the coarse kind, HTTP status, backend error code, and a bounded,
+ * secret-redacted body preview — that is what lets a 409 name the override
+ * branch the server preserved. Anything else is collapsed to
+ * {@link GENERIC_ERROR}: an unknown throw value has unknown contents, and
+ * stringifying it is how a credential or a raw response body escapes.
+ */
+function toFailure(err, access) {
+    if (err instanceof ConductorBridgeApiError) {
+        return {
+            ok: false,
+            status: typeof err.status === "number" ? err.status : null,
+            error: scrubKey(err.message || GENERIC_ERROR, access.apiKey),
+        };
+    }
+    return { ok: false, status: null, error: GENERIC_ERROR };
+}
+/** True when `value` is a plain (non-array, non-null) object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read a `string | null` field, returning `undefined` when it is neither. */
+function nullableString(value) {
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+/** Parse the `override` member, or `undefined` when it is malformed. */
+function parseOverride(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!isRecord(value))
+        return undefined;
+    const original = nullableString(value["original_base_branch"]);
+    if (typeof value["repo_name"] !== "string" ||
+        original === undefined ||
+        typeof value["override_branch"] !== "string" ||
+        typeof value["created_at"] !== "string") {
+        return undefined;
+    }
+    return {
+        repo_name: value["repo_name"],
+        original_base_branch: original,
+        override_branch: value["override_branch"],
+        created_at: value["created_at"],
+    };
+}
+/**
+ * Validate a 200 body against {@link IndexBranchStatus}, returning `null` when it
+ * does not match.
+ *
+ * A body that parsed as JSON but is not this shape is treated as a failure
+ * rather than cast through: `changed` and `current_base_branch` drive
+ * destructive branch decisions in the caller, and a missing `changed` read as
+ * `undefined` would silently mean "nothing happened".
+ */
+function parseStatus(body) {
+    if (!isRecord(body))
+        return null;
+    const current = nullableString(body["current_base_branch"]);
+    const override = parseOverride(body["override"]);
+    if (typeof body["repo_name"] !== "string" ||
+        current === undefined ||
+        override === undefined ||
+        typeof body["changed"] !== "boolean") {
+        return null;
+    }
+    return {
+        repo_name: body["repo_name"],
+        current_base_branch: current,
+        override,
+        changed: body["changed"],
+    };
+}
+/** Wrap a parsed body into a success result, or a generic failure if malformed. */
+function toStatusResult(body) {
+    const status = parseStatus(body);
+    if (status === null) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return { ok: true, value: status };
+}
+/**
+ * `POST /jira/index-branch/repoint` — point the indexed base branch at `branch`.
+ *
+ * A repeat call with the same branch resolves `{ ok: true }` with
+ * `value.changed === false`. A call for a *different* branch while an override is
+ * active resolves `{ ok: false, status: 409 }` with an error naming the override
+ * the server preserved — it is not an exception, because a conflict is an
+ * expected outcome the CLI must report and continue from.
+ */
+export async function repointIndexBranch(access, input, fetchImpl = globalThis.fetch) {
+    try {
+        // `buildConductorJiraUrl` already appends the `/jira` segment.
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-branch/repoint");
+        const body = await fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, branch: input.branch }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return toStatusResult(body);
+    }
+    catch (err) {
+        return toFailure(err, access);
+    }
+}
+/**
+ * `POST /jira/index-branch/restore` — write the stored original branch back and
+ * drop the override.
+ *
+ * Idempotent: with no active override the call resolves `{ ok: true }` with
+ * `value.changed === false` and `value.override === null`. That matters because
+ * restore is the recovery path — it must be safe to run after a crash whose
+ * position is unknown.
+ */
+export async function restoreIndexBranch(access, fetchImpl = globalThis.fetch) {
+    try {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-branch/restore");
+        const body = await fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return toStatusResult(body);
+    }
+    catch (err) {
+        return toFailure(err, access);
+    }
+}
+/**
+ * `GET /jira/index-branch?repo_name=` — report the current indexed branch and any
+ * active override.
+ *
+ * This is how a stale override left behind by a crashed loop becomes visible;
+ * `value.changed` is always `false` because a read changes nothing.
+ */
+export async function getIndexBranch(access, fetchImpl = globalThis.fetch) {
+    try {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-branch", {
+            repo_name: access.repoName,
+        });
+        const body = await fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return toStatusResult(body);
+    }
+    catch (err) {
+        return toFailure(err, access);
+    }
+}
+/**
+ * Run `operation` and convert any thrown value into a sanitized failure result.
+ *
+ * Every +803 read is this shape, so the try/catch lives in one place: a helper
+ * added later cannot forget it and reintroduce a throwing client.
+ */
+async function wrap(access, operation) {
+    try {
+        return { ok: true, value: await operation() };
+    }
+    catch (err) {
+        return toFailure(err, access);
+    }
+}
+/**
+ * `PUT /jira/epic-runs/supervisor-config/defaults/?repo_name=` — replace the
+ * project-default supervisor configuration.
+ *
+ * The complete {@link EpicSupervisorConfigRequest} is sent. `init` builds it by
+ * reading the effective config and flipping exactly one field, so enabling
+ * auto-merge never silently reverts another operator setting.
+ */
+export async function putSupervisorConfigDefaults(access, config, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/epic-runs/supervisor-config/defaults/", { repo_name: access.repoName });
+        return fetchConductorJsonPutWithTimeout(url, putHeaders(access), JSON.stringify(config), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+}
+/** `GET /jira/epic-runs/supervisor-config/defaults/` — the effective config. */
+export async function getEffectiveSupervisorConfig(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchEffectiveSupervisorConfig(access, undefined, fetchImpl));
+}
+/**
+ * `GET /jira/epic-runs/supervisor-setup/defaults/` — the effective setup.
+ *
+ * Returned verbatim, `done_gate_config` included and un-normalized: it is the
+ * raw operator-authored JSONB that `parseDoneGateConfig` is the sole authority
+ * on, and normalizing it here would fork that vocabulary.
+ */
+export async function getEffectiveSupervisorSetup(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchEffectiveSupervisorSetup(access, undefined, fetchImpl));
+}
+/**
+ * `GET /jira/epic-runs/conductor-readiness?repo_name=` — readiness facts.
+ *
+ * `init` reads three of them: `supervisor.auto_merge_enabled`,
+ * `supervisor.required_checks_count`, and `supervisor.required_checks_empty`.
+ * The underlying fetcher validates the body fail-closed, so a 200 whose body is
+ * missing `required_checks_empty` becomes a failure here rather than an
+ * apparently-healthy report.
+ */
+export async function getConductorReadiness(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchConductorReadiness(access, fetchImpl));
+}
+/**
+ * `POST /jira/resolve-ci-checks` — discover and classify the repository's CI
+ * checks, and warm the `poll-ci-checks` cache as a side effect.
+ *
+ * `commitRef` is optional and forwarded only when supplied. The response is the
+ * server's soft envelope, preserved verbatim inside `value`.
+ */
+export async function resolveCiChecks(access, commitRef, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/resolve-ci-checks");
+        const payload = { repo_name: access.repoName };
+        if (typeof commitRef === "string" && commitRef.trim().length > 0) {
+            payload.commit_ref = commitRef;
+        }
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify(payload), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+}
+/**
+ * `GET /jira/poll-ci-checks?repo_name=&commit_ref=` — CI status for one SHA.
+ *
+ * Until `resolve-ci-checks` has run once for the repository this answers 200
+ * with `{ available: false, action: "Call resolve-ci-checks first…" }`. That is
+ * a successful result carrying an instruction, not an error, and it stays in
+ * `value` so `status` can act on it.
+ */
+export async function pollCiChecks(access, commitRef, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => pollCiChecksForCommit(access, commitRef, fetchImpl));
+}
+/**
+ * `GET /vcs/pull-requests/{n}/reviews/status?repo_name=` — normalized review
+ * state. Root-mounted, NOT under `/jira`.
+ *
+ * `prNumber` is validated by the wrapped fetcher before any request is issued,
+ * so a zero/negative/non-integer number fails without a network round trip.
+ */
+export async function getPrReviewStatus(access, prNumber, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchPrReviewStatus(access, prNumber, fetchImpl));
+}
+/** `GET /jira/parse-status?repo_name=` — the durable parse-run status. */
+export async function getParseStatus(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchParseStatus(access, fetchImpl));
+}
+/**
+ * `GET /jira/epic-runs/runs/{epicKey}/state?repo_name=` — the durable epic-run
+ * state.
+ *
+ * A pure READ. `conduct-epic` never creates an `epic_run`; `init` calls this
+ * only to refuse when the server is already conducting the same epic through
+ * the v2 reconciler, which would otherwise drive the same tickets in parallel.
+ */
+export async function getEpicRunState(access, epicKey, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchEpicRunState(access, epicKey, fetchImpl));
+}
+/**
+ * `GET /jira/config-field/base_branch?repo_name=` — the repository's configured
+ * base branch.
+ *
+ * Normalized defensively: an absent `value`, an explicit `null`, and a
+ * blank string all become `base_branch: null`, which the caller reads as "not
+ * configured" and falls through to `main`. A body that is not an object at all
+ * is a failure — silently treating an unparseable response as "not configured"
+ * would provision the epic branch from the wrong base.
+ */
+export async function getConfigFieldBaseBranch(access, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/config-field/base_branch", {
+            repo_name: access.repoName,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    if (!isRecord(result.value)) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    const raw = result.value["value"];
+    if (raw === null || raw === undefined) {
+        return { ok: true, value: { base_branch: null } };
+    }
+    if (typeof raw !== "string") {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    const trimmed = raw.trim();
+    return { ok: true, value: { base_branch: trimmed.length === 0 ? null : trimmed } };
+}