@bridge_gpt/mcp-server 0.2.24 → 0.2.26

package/build/conductor-bundle-cli.js

@@ -0,0 +1,256 @@
+/**
+ * BAPI-634: thin CLI handler exposing the deterministic conductor-bundle helpers
+ * to `emit-conductor-bundle.md`.
+ *
+ * Why this exists: the instruction ships **compiled** to consuming repositories
+ * inside `build/pipelines.generated.js`. `mcp_server/src/` does not exist there,
+ * so an instruction that told the agent to "call `validateConductorBundleInputs`"
+ * would be referencing a path only this repository has. This subcommand is the
+ * reachable surface, mirroring how `store-and-approve-epic-plan.md` invokes
+ * `setup-epic` rather than hand-rolling HTTP calls.
+ *
+ * It holds no policy of its own: it parses argv, delegates to
+ * `conductor-bundle-artifacts.ts`, and prints a JSON envelope. All I/O is behind
+ * an injectable seam so tests never touch a real disk or construct a server.
+ */
+import path from "node:path";
+import { finalizeEpicPlanSidecar, serializeSiblingTicketManifest, validateConductorBundleInputs, writeJsonAtomically, } from "./conductor-bundle-artifacts.js";
+const USAGE = [
+    "Usage: emit-conductor-bundle <validate|finalize> --input <file> [--docs-dir <dir>] [--json]",
+    "",
+    "  validate   Validate identities, the node->ticket mapping, manifest agreement,",
+    "             and path containment. Writes nothing.",
+    "  finalize   Validate, then finalize epic-plan.dag.json with real keys and",
+    "             per-node touched_files, and write the sibling-ticket manifest.",
+    "",
+    "Options:",
+    "  --input <file>     JSON document with epic_key, epic_slug, mappings,",
+    "                     decomposition_fingerprint, and (for finalize)",
+    "                     touched_files_by_key.",
+    "  --docs-dir <dir>   Docs directory (default: $BAPI_DOCS_DIR, else docs/tmp).",
+    "  --json             Emit a machine-readable result on stdout.",
+    "  -h, --help         Show this help.",
+].join("\n");
+/** Read a flag's value, rejecting a missing or flag-shaped value. */
+function takeValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("-")) {
+        throw new Error(`Flag "${flag}" requires a value.`);
+    }
+    return value;
+}
+/** Parse argv into options, or throw with an actionable message. */
+export function parseConductorBundleArgs(argv) {
+    const mode = argv[0];
+    if (mode === "-h" || mode === "--help" || mode === undefined) {
+        return { mode: "validate", inputFile: "", json: false, help: true };
+    }
+    if (mode !== "validate" && mode !== "finalize") {
+        throw new Error(`Unknown subcommand "${mode}". Expected "validate" or "finalize".`);
+    }
+    let inputFile;
+    let docsDir;
+    let json = false;
+    let help = false;
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--input":
+                inputFile = takeValue(argv, i, "--input");
+                i++;
+                break;
+            case "--docs-dir":
+                docsDir = takeValue(argv, i, "--docs-dir");
+                i++;
+                break;
+            case "--json":
+                json = true;
+                break;
+            case "-h":
+            case "--help":
+                help = true;
+                break;
+            default:
+                throw new Error(`Unknown argument "${arg}".`);
+        }
+    }
+    if (help)
+        return { mode, inputFile: inputFile ?? "", docsDir, json, help: true };
+    if (!inputFile)
+        throw new Error('Flag "--input" is required.');
+    return { mode, inputFile, docsDir, json, help: false };
+}
+/** Parse JSON, converting a syntax error into an actionable message. */
+async function readJson(filePath, fs, label) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath);
+    }
+    catch (err) {
+        throw new Error(`Could not read ${label} at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${label} at ${filePath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Read an optional JSON file, returning null when it does not exist. */
+async function readOptionalJson(filePath, fs, label) {
+    try {
+        await fs.readFile(filePath);
+    }
+    catch {
+        return null;
+    }
+    return readJson(filePath, fs, label);
+}
+/**
+ * Run the `emit-conductor-bundle` subcommand. Returns a process exit code; never
+ * throws for an expected validation failure.
+ */
+export async function runConductorBundleCli(argv, overrides = {}) {
+    const deps = {
+        env: process.env,
+        cwd: process.cwd(),
+        fs: createDefaultBundleFs(),
+        log: (m) => console.log(m),
+        // Diagnostics go to stderr so `--json` keeps stdout a single result object.
+        errorLog: (m) => console.error(m),
+        ...overrides,
+    };
+    let opts;
+    try {
+        opts = parseConductorBundleArgs(argv);
+    }
+    catch (err) {
+        deps.errorLog(err instanceof Error ? err.message : String(err));
+        deps.errorLog(USAGE);
+        return 1;
+    }
+    if (opts.help) {
+        deps.log(USAGE);
+        return 0;
+    }
+    const emitFailure = (error) => {
+        if (opts.json)
+            deps.log(JSON.stringify({ ok: false, error }));
+        else
+            deps.errorLog(`Error: ${error}`);
+        return 1;
+    };
+    const docsDir = path.resolve(deps.cwd, opts.docsDir ?? deps.env.BAPI_DOCS_DIR ?? path.join("docs", "tmp"));
+    let input;
+    try {
+        input = (await readJson(path.resolve(deps.cwd, opts.inputFile), deps.fs, "--input document"));
+    }
+    catch (err) {
+        return emitFailure(err instanceof Error ? err.message : String(err));
+    }
+    if (!input || typeof input !== "object") {
+        return emitFailure("--input document must be a JSON object.");
+    }
+    const epicDir = path.resolve(docsDir, "epic-plans", String(input.epic_slug));
+    const sidecarPath = path.join(epicDir, "epic-plan.dag.json");
+    const manifestPath = path.join(epicDir, "sibling-ticket-manifest.json");
+    let sidecar;
+    let existingManifest;
+    try {
+        sidecar = await readJson(sidecarPath, deps.fs, "epic-plan.dag.json");
+        existingManifest = await readOptionalJson(manifestPath, deps.fs, "sibling-ticket-manifest.json");
+    }
+    catch (err) {
+        return emitFailure(err instanceof Error ? err.message : String(err));
+    }
+    const validation = await validateConductorBundleInputs({
+        epic_key: input.epic_key,
+        epic_slug: input.epic_slug,
+        docs_dir: docsDir,
+        mappings: input.mappings,
+        sidecar,
+        existing_manifest: existingManifest ?? undefined,
+        decomposition_fingerprint: input.decomposition_fingerprint,
+    }, deps.fs);
+    if (!validation.ok)
+        return emitFailure(validation.error);
+    if (opts.mode === "validate") {
+        const result = {
+            ok: true,
+            mode: "validate",
+            epic_key: validation.value.epic_key,
+            plan_version: validation.value.plan_version,
+            mapped_nodes: validation.value.mappings.length,
+            sidecar_path: validation.value.sidecar_path,
+        };
+        if (opts.json)
+            deps.log(JSON.stringify(result));
+        else {
+            deps.log(`Validated ${result.mapped_nodes} node mapping(s) for ${result.epic_key} ` +
+                `(plan v${result.plan_version}). Nothing was written.`);
+        }
+        return 0;
+    }
+    // ---- finalize ----------------------------------------------------------
+    const nodeKeyMap = {};
+    for (const m of validation.value.mappings) {
+        nodeKeyMap[m.plan_node_id] = m.ticket_key;
+    }
+    const finalized = finalizeEpicPlanSidecar({
+        sidecar,
+        node_key_map: nodeKeyMap,
+        touched_files_by_key: input.touched_files_by_key ?? {},
+        plan_version_already_stored: input.plan_version_already_stored === true,
+    });
+    if (!finalized.ok)
+        return emitFailure(finalized.error);
+    const sidecarWrite = await writeJsonAtomically(validation.value.sidecar_path, finalized.value, deps.fs);
+    if (!sidecarWrite.ok)
+        return emitFailure(sidecarWrite.error);
+    const manifest = serializeSiblingTicketManifest({
+        schema_version: 1,
+        epic_key: validation.value.epic_key,
+        epic_slug: validation.value.epic_slug,
+        plan_version: validation.value.plan_version,
+        decomposition_fingerprint: input.decomposition_fingerprint,
+        finalized_fingerprint: null,
+        run_phase: input.run_phase ?? "staged",
+        mappings: validation.value.mappings.map((m) => ({
+            plan_node_id: m.plan_node_id,
+            ticket_key: m.ticket_key,
+            exploration_path: m.exploration_path,
+            draft_path: m.draft_path,
+        })),
+        decisions: [],
+        completed_mutations: [],
+    });
+    const manifestWrite = await writeJsonAtomically(validation.value.manifest_path, manifest, deps.fs);
+    if (!manifestWrite.ok)
+        return emitFailure(manifestWrite.error);
+    const result = {
+        ok: true,
+        mode: "finalize",
+        epic_key: validation.value.epic_key,
+        plan_version: validation.value.plan_version,
+        sidecar_path: validation.value.sidecar_path,
+        manifest_path: validation.value.manifest_path,
+        ticket_keys: validation.value.mappings.map((m) => m.ticket_key),
+    };
+    if (opts.json)
+        deps.log(JSON.stringify(result));
+    else {
+        deps.log(`Finalized ${result.sidecar_path} with ${result.ticket_keys.length} real key(s) ` +
+            `and per-node touched_files. Manifest: ${result.manifest_path}`);
+    }
+    return 0;
+}
+/** Real filesystem seam, loaded lazily so importing this module stays cheap. */
+function createDefaultBundleFs() {
+    return {
+        readFile: async (p) => (await import("node:fs/promises")).readFile(p, "utf-8"),
+        writeFile: async (p, data) => (await import("node:fs/promises")).writeFile(p, data, "utf-8"),
+        rename: async (from, to) => (await import("node:fs/promises")).rename(from, to),
+        unlink: async (p) => (await import("node:fs/promises")).unlink(p),
+        realpath: async (p) => (await import("node:fs/promises")).realpath(p),
+    };
+}

package/build/connect-github-api.js

@@ -0,0 +1,365 @@
+/**
+ * Bridge API access + polling primitives for the sessionless GitHub connect flow
+ * (BAPI-631).
+ *
+ * Split out from `connect-github.ts` so the standalone command and `install-bridge`
+ * share one implementation of the request contract, the lifecycle vocabulary, and the
+ * polling policy — rather than each growing its own slightly-different copy.
+ *
+ * Two rules shape everything here:
+ *
+ * 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",
+    "awaiting-organization-approval",
+    "connected",
+    "expired",
+    "invalid",
+    "verification-failed",
+    "no-repositories",
+    "conflict",
+    "failed",
+]);
+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 install URL. */
+export async function mintGithubConnection(deps, repoName) {
+    const res = await postJson(deps, "/setup/github/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 } };
+}
+function parseCandidates(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const raw of value) {
+        const rec = asRecord(raw);
+        const id = asString(rec?.github_repository_id);
+        const name = asString(rec?.github_repo_name);
+        // A candidate without a usable identity is a malformed response, not a candidate to
+        // silently drop — dropping it would show the user an incomplete picker.
+        if (!rec || !id || !name)
+            return null;
+        out.push({
+            github_repository_id: id,
+            github_repo_name: name,
+            github_repo_full_name: asNullableString(rec.github_repo_full_name),
+            owner: asNullableString(rec.owner),
+        });
+    }
+    return out;
+}
+/** Read one connection code's current lifecycle state. */
+export async function fetchGithubConnectionStatus(deps, repoName, state, nowMs = Date.now()) {
+    const res = await postJson(deps, "/setup/github/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,
+            githubRepoName: asNullableString(body.github_repo_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 confirmGithubConnection(deps, repoName, state, githubRepositoryId) {
+    const res = await postJson(deps, "/setup/github/cli/confirm", {
+        repo_name: repoName,
+        state,
+        github_repository_id: githubRepositoryId,
+    });
+    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 name = asString(body?.github_repo_name);
+    if (!body || body.status !== "connected" || !name) {
+        return { ok: false, kind: "malformed" };
+    }
+    return {
+        ok: true,
+        value: {
+            githubRepoName: name,
+            githubRepoFullName: asNullableString(body.github_repo_full_name),
+        },
+    };
+}
+/**
+ * Read whether GitHub 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 fetchGithubConfigurationState(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 !== "github_app")
+            continue;
+        if (typeof rec.is_configured !== "boolean")
+            return "unavailable";
+        return rec.is_configured ? "configured" : "unconfigured";
+    }
+    // The checklist is provider-scoped: GitHub is legitimately absent for a Bitbucket
+    // 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; conflating the two is
+ * what previously let a plain 500 kill a poll.
+ */
+const RETRYABLE_TRANSPORT = new Set([
+    "network",
+    "timeout",
+]);
+/**
+ * Is this HTTP status worth retrying rather than surfacing?
+ *
+ * Every 5xx, not just 502/503: a 500 from a transient server-side hiccup (the /cli/status
+ * handler raises a bare 500 on a DB read failure) 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 pollGithubConnection(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/github/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,
+                        githubRepoName: asNullableString(body.github_repo_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);
+    }
+}