@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/connect-bitbucket-api.js

@@ -0,0 +1,370 @@
+/**
+ * Bridge API access + polling primitives for the sessionless Bitbucket connect flow
+ * (BAPI-966).
+ *
+ * Mirrors `connect-github-api.ts`'s request contract, lifecycle vocabulary, and polling
+ * policy, adapted to the Bitbucket Forge backend (`api/routes/setup/bitbucket_connection_codes.py`):
+ * candidates are identified by an immutable `(workspace_uuid, repository_uuid)` pair
+ * rather than a single numeric id, and there is no delegated-handoff mode — BAPI-686 is
+ * GitHub-only.
+ *
+ * Two rules shape everything here, unchanged from the GitHub client:
+ *
+ * 1. **Nothing secret is ever returned in a message.** Failures collapse to coarse,
+ *    enumerated categories. Fetch exception text, response bodies, headers, the state
+ *    nonce, the install URL, and the API key never reach a string a caller might print.
+ * 2. **A malformed success is a failure.** Responses are validated against explicit
+ *    unions; a 200 whose body does not match is rejected rather than guessed at, so a
+ *    server change can never be silently reinterpreted as a connection outcome.
+ */
+/** Statuses that end the flow — polling past one of these is pointless. */
+const TERMINAL_STATUSES = new Set([
+    "staged",
+    "connected",
+    "no-repositories",
+    "expired",
+    "invalid",
+]);
+const ALL_STATUSES = new Set([
+    "waiting",
+    ...TERMINAL_STATUSES,
+]);
+/** Per-request timeout. Generous enough for a cold server, short enough to retry. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * POST JSON to a Bridge endpoint.
+ *
+ * The state nonce travels in the BODY, never the query string: query strings land in
+ * server access logs, proxy logs, and browser history in a way request bodies do not.
+ */
+async function postJson(deps, path, payload) {
+    let resp;
+    try {
+        resp = await deps.fetch(`${deps.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": deps.apiKey,
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        // Deliberately does not forward `e`: fetch exception text can echo the URL, which
+        // carries the state nonce.
+        const isTimeout = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+        return { ok: false, kind: isTimeout ? "timeout" : "network" };
+    }
+    let body = null;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        /* Non-JSON body. The status still classifies the outcome. */
+    }
+    return {
+        ok: true,
+        value: { status: resp.status, body, retryAfter: resp.headers.get("Retry-After") },
+    };
+}
+/** Map a non-2xx status to a coarse category. */
+function classifyStatus(status) {
+    if (status === 401 || status === 403)
+        return "unauthorized";
+    if (status === 404)
+        return "not-found";
+    return "server";
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asNullableString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+// ---------------------------------------------------------------------------
+// Retry-After
+// ---------------------------------------------------------------------------
+/**
+ * Parse a `Retry-After` header to milliseconds.
+ *
+ * Handles both RFC forms — delta-seconds and an HTTP-date — and clamps the result to
+ * `remainingMs` so a server (or a bogus far-future date) can never push a wait past the
+ * caller's own deadline. Returns null for absent/unparseable/negative values.
+ */
+export function parseRetryAfterMs(header, remainingMs, nowMs) {
+    if (!header)
+        return null;
+    const trimmed = header.trim();
+    if (!trimmed)
+        return null;
+    const clamp = (ms) => {
+        if (!Number.isFinite(ms) || ms < 0)
+            return null;
+        return Math.min(ms, Math.max(0, remainingMs));
+    };
+    // delta-seconds
+    if (/^\d+$/.test(trimmed)) {
+        return clamp(Number(trimmed) * 1_000);
+    }
+    // HTTP-date
+    const parsed = Date.parse(trimmed);
+    if (Number.isNaN(parsed))
+        return null;
+    return clamp(parsed - nowMs);
+}
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+/** Mint a CLI-origin connection code and its Forge install-page URL. */
+export async function mintBitbucketConnection(deps, repoName) {
+    const res = await postJson(deps, "/setup/bitbucket/cli/connection-code", {
+        repo_name: repoName,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const state = asString(body?.state);
+    const installUrl = asString(body?.install_url);
+    const ttlSeconds = body?.ttl_seconds;
+    if (!body || !state || !installUrl || typeof ttlSeconds !== "number") {
+        return { ok: false, kind: "malformed" };
+    }
+    return { ok: true, value: { state, installUrl, ttlSeconds } };
+}
+/** Strictly parse candidates. A candidate missing a usable identity fails the whole list. */
+function parseCandidates(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const raw of value) {
+        const rec = asRecord(raw);
+        const workspaceUuid = asString(rec?.workspace_uuid);
+        const repositoryUuid = asString(rec?.repository_uuid);
+        const workspaceSlug = asString(rec?.workspace_slug);
+        const repositorySlug = asString(rec?.repository_slug);
+        const defaultBranch = asString(rec?.default_branch);
+        // A candidate without every usable selection identifier is a malformed response,
+        // not a candidate to silently drop — dropping it would show an incomplete picker.
+        if (!rec || !workspaceUuid || !repositoryUuid || !workspaceSlug || !repositorySlug || !defaultBranch) {
+            return null;
+        }
+        out.push({
+            workspace_uuid: workspaceUuid,
+            repository_uuid: repositoryUuid,
+            workspace_slug: workspaceSlug,
+            repository_slug: repositorySlug,
+            display_name: asNullableString(rec.display_name),
+            default_branch: defaultBranch,
+        });
+    }
+    return out;
+}
+/** Read one connection code's current lifecycle state. */
+export async function fetchBitbucketConnectionStatus(deps, repoName, state, nowMs = Date.now()) {
+    const res = await postJson(deps, "/setup/bitbucket/cli/status", {
+        repo_name: repoName,
+        state,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const status = asString(body?.status);
+    if (!body || !status || !ALL_STATUSES.has(status)) {
+        return { ok: false, kind: "malformed" };
+    }
+    const candidates = parseCandidates(body.candidates ?? []);
+    if (candidates === null)
+        return { ok: false, kind: "malformed" };
+    return {
+        ok: true,
+        value: {
+            status: status,
+            candidates,
+            repoDisplayName: asNullableString(body.repo_display_name),
+            // A single read has no deadline of its own to clamp against; the poller applies
+            // its own bound. POLL_DEADLINE_MS is the widest a caller could honor.
+            retryAfterMs: parseRetryAfterMs(res.value.retryAfter, POLL_DEADLINE_MS, nowMs),
+        },
+    };
+}
+/** Bind one chosen repository. Sends no installation id — the server owns that. */
+export async function confirmBitbucketConnection(deps, repoName, state, workspaceUuid, repositoryUuid) {
+    const res = await postJson(deps, "/setup/bitbucket/cli/confirm", {
+        repo_name: repoName,
+        state,
+        workspace_uuid: workspaceUuid,
+        repository_uuid: repositoryUuid,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const repoName_ = asString(body?.repo_name);
+    if (!body || body.status !== "connected" || !repoName_) {
+        return { ok: false, kind: "malformed" };
+    }
+    return {
+        ok: true,
+        value: {
+            repoName: repoName_,
+            workspaceSlug: asNullableString(body.workspace_slug),
+            repositorySlug: asNullableString(body.repository_slug),
+        },
+    };
+}
+/**
+ * Read whether Bitbucket is already configured for a project.
+ *
+ * Uses the existing authenticated install-manifest/capability surface — read-only, and
+ * unrelated to any in-flight connection attempt. `unavailable` is a real answer and is
+ * deliberately distinct from `unconfigured`: callers must be able to skip rather than
+ * fabricate "not configured" from a probe that simply failed.
+ */
+export async function fetchBitbucketConfigurationState(deps, repoName) {
+    let resp;
+    try {
+        resp = await deps.fetch(`${deps.baseUrl}/jira/config/install-manifest?repo_name=${encodeURIComponent(repoName)}`, {
+            headers: { "X-API-Key": deps.apiKey },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return "unavailable";
+    }
+    if (resp.status !== 200)
+        return "unavailable";
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        return "unavailable";
+    }
+    const integrations = asRecord(body)?.integrations;
+    if (!Array.isArray(integrations))
+        return "unavailable";
+    for (const raw of integrations) {
+        const rec = asRecord(raw);
+        if (rec?.id !== "vcs_access_token")
+            continue;
+        if (typeof rec.is_configured !== "boolean")
+            return "unavailable";
+        return rec.is_configured ? "configured" : "unconfigured";
+    }
+    // The checklist is provider-scoped: this descriptor is legitimately absent for a
+    // GitHub project. Absent is not "unconfigured" — there is nothing here to connect.
+    return "unavailable";
+}
+/**
+ * Slightly longer than the server's 15-minute code TTL, so an expiry is reported by the
+ * server as `expired` rather than guessed at by a local timeout.
+ */
+export const POLL_DEADLINE_MS = 15.5 * 60 * 1_000;
+/** Back off gently: quick early (the common case is fast), then settle. */
+const POLL_DELAYS_MS = [2_000, 3_000, 5_000];
+const MAX_JITTER_MS = 400;
+/**
+ * TRANSPORT faults worth retrying — the request never produced a response at all.
+ *
+ * Deliberately does NOT list "server": `postJson` only ever reports these two kinds,
+ * because any HTTP response (500 included) comes back as `ok: true` with a status. HTTP
+ * statuses are classified by {@link isRetryableStatus} instead.
+ */
+const RETRYABLE_TRANSPORT = new Set([
+    "network",
+    "timeout",
+]);
+/**
+ * Is this HTTP status worth retrying rather than surfacing?
+ *
+ * Every 5xx, not just 502/503: a transient server-side hiccup and a 504 gateway timeout
+ * are exactly as transient as a dropped packet, and the user's alternative is restarting
+ * the whole mint → browser → poll flow. 429 is retried because it is literally a request
+ * to retry. 4xx is terminal: the request itself is the problem, so repeating it cannot help.
+ */
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/**
+ * Poll until a terminal status, an unrecoverable failure, or the deadline.
+ *
+ * Terminal statuses return immediately — including the failure ones. Waiting out a
+ * 15-minute deadline on a code the server already called `expired` would be theatre.
+ *
+ * Transient transport faults (network blips, timeouts, 502/503) are retried, because a
+ * dropped packet is not a failed connection. `Retry-After` is honored when the server
+ * sends it, including on a 429.
+ */
+export async function pollBitbucketConnection(deps, poll, repoName, state) {
+    const started = poll.now();
+    let attempt = 0;
+    for (;;) {
+        const elapsed = poll.now() - started;
+        const remaining = POLL_DEADLINE_MS - elapsed;
+        if (remaining <= 0)
+            return { ok: false, kind: "deadline" };
+        const res = await postJson(deps, "/setup/bitbucket/cli/status", {
+            repo_name: repoName,
+            state,
+        });
+        let waitMs = null;
+        if (!res.ok) {
+            if (!RETRYABLE_TRANSPORT.has(res.kind))
+                return { ok: false, kind: res.kind };
+        }
+        else if (res.value.status === 200) {
+            const body = asRecord(res.value.body);
+            const status = asString(body?.status);
+            if (!body || !status || !ALL_STATUSES.has(status)) {
+                return { ok: false, kind: "malformed" };
+            }
+            const candidates = parseCandidates(body.candidates ?? []);
+            if (candidates === null)
+                return { ok: false, kind: "malformed" };
+            const typed = status;
+            if (TERMINAL_STATUSES.has(typed)) {
+                return {
+                    ok: true,
+                    value: {
+                        status: typed,
+                        candidates,
+                        repoDisplayName: asNullableString(body.repo_display_name),
+                        retryAfterMs: null,
+                    },
+                };
+            }
+            // `waiting` — honor server pacing if offered.
+            waitMs = parseRetryAfterMs(res.value.retryAfter, remaining, poll.now());
+        }
+        else if (isRetryableStatus(res.value.status)) {
+            waitMs = parseRetryAfterMs(res.value.retryAfter, remaining, poll.now());
+        }
+        else {
+            return { ok: false, kind: classifyStatus(res.value.status) };
+        }
+        if (waitMs === null) {
+            const base = POLL_DELAYS_MS[Math.min(attempt, POLL_DELAYS_MS.length - 1)];
+            waitMs = base + Math.floor(poll.jitter() * MAX_JITTER_MS);
+        }
+        attempt += 1;
+        // Never sleep past the deadline.
+        const capped = Math.min(waitMs, Math.max(0, POLL_DEADLINE_MS - (poll.now() - started)));
+        if (capped <= 0)
+            return { ok: false, kind: "deadline" };
+        await poll.sleep(capped);
+    }
+}