@bridge_gpt/mcp-server 0.2.21 → 0.2.24

package/build/setup-epic.js

@@ -0,0 +1,483 @@
+/**
+ * `setup-epic` — one-command bootstrap for an Epic Conductor v2 run.
+ *
+ * Creates the epic run, stores the plan DAG, and approves it. Before this
+ * existed the only path was hand-rolled HTTP with a hand-computed plan hash,
+ * which is why the shipped `store-and-approve-epic-plan` pipeline step told the
+ * agent to "make a direct API call" — there was no tool to call.
+ *
+ * Ordering is load-bearing:
+ *
+ *   0. GET the run state FIRST. `POST /epic-runs/runs` cannot be probed with a
+ *      "create and tolerate 409" — it never returned 409, so a blind repeat
+ *      create used to mint a SECOND active run, wedging the epic permanently
+ *      (every later plan call 409s on "Multiple active runs") and double-charging
+ *      billing. The server is idempotent now, but the pre-check is still what
+ *      lets us report honestly and skip work.
+ *   1. Create only when no live run exists.
+ *   2. Hash locally — ADVISORY ONLY. The server re-hashes after applying
+ *      file-overlap serialization, so a divergence is legitimate, not corruption.
+ *   3. Store, then approve.
+ *
+ * Read-only against the local filesystem: it reads the plan sidecar and writes
+ * nothing.
+ */
+import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import os from "node:os";
+import { approveEpicPlan, createEpicRun, fetchEpicRunState, resolveConductorBridgeApiAccess, storeEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
+import { hashPlan } from "./conductor/plan.js";
+export function createDefaultSetupEpicDeps() {
+    return {
+        env: process.env,
+        cwd: process.cwd(),
+        platform: process.platform,
+        homedir: os.homedir,
+        readFile: (p) => fsReadFile(p, "utf-8"),
+        stat: (p) => fsStat(p),
+        fetch: globalThis.fetch,
+        log: (m) => console.log(m),
+        errorLog: (m) => console.error(m),
+    };
+}
+/** User-facing usage text. */
+export function getSetupEpicUsage() {
+    return [
+        "Usage: mcp-server setup-epic --epic-key <KEY> --plan-file <path> [options]",
+        "",
+        "Bootstraps an Epic Conductor v2 run: creates the run, stores the plan DAG,",
+        "and approves it. Idempotent — re-running reuses an existing live run.",
+        "",
+        "Required:",
+        "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
+        "  --plan-file <path>     Path to epic-plan.dag.json (from decompose-epic)",
+        "",
+        "Options:",
+        "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
+        "  --plan-version <n>     Assert the sidecar's plan_version equals <n>",
+        "  --dry-run              Validate and preview; make no mutating calls",
+        "  --json                 Emit a single JSON result object on stdout",
+        "  -h, --help             Show this help",
+        "",
+        "After setup, the server-side reconciler picks the run up within ~30s.",
+        "To execute claimed jobs on this machine, run:",
+        "  npx -y @bridge_gpt/mcp-server executor --repo <name>",
+    ].join("\n");
+}
+function takeValue(argv, i, flag) {
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("-"))
+        return null;
+    return next;
+}
+export function parseSetupEpicArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getSetupEpicUsage() };
+    }
+    let epicKey;
+    let planFile;
+    let repo;
+    let planVersion;
+    let dryRun = false;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--epic-key": {
+                const v = takeValue(argv, i, arg);
+                if (v === null)
+                    return { status: "error", message: "--epic-key requires a value." };
+                epicKey = v;
+                i++;
+                break;
+            }
+            case "--plan-file": {
+                const v = takeValue(argv, i, arg);
+                if (v === null)
+                    return { status: "error", message: "--plan-file requires a value." };
+                planFile = v;
+                i++;
+                break;
+            }
+            case "--repo": {
+                const v = takeValue(argv, i, arg);
+                if (v === null)
+                    return { status: "error", message: "--repo requires a value." };
+                repo = v;
+                i++;
+                break;
+            }
+            case "--plan-version": {
+                const v = takeValue(argv, i, arg);
+                if (v === null)
+                    return { status: "error", message: "--plan-version requires a value." };
+                if (!/^\d+$/.test(v)) {
+                    return { status: "error", message: `--plan-version must be a positive integer, got '${v}'.` };
+                }
+                planVersion = Number(v);
+                if (planVersion < 1) {
+                    return { status: "error", message: "--plan-version must be >= 1." };
+                }
+                i++;
+                break;
+            }
+            case "--dry-run":
+                dryRun = true;
+                break;
+            case "--json":
+                json = true;
+                break;
+            default:
+                return {
+                    status: "error",
+                    message: `Unknown argument '${arg}'. Run "setup-epic --help" for usage.`,
+                };
+        }
+    }
+    if (!epicKey)
+        return { status: "error", message: "setup-epic requires --epic-key <KEY>." };
+    if (!planFile)
+        return { status: "error", message: "setup-epic requires --plan-file <path>." };
+    return {
+        status: "ok",
+        options: { epicKey, planFile, repo, planVersion, dryRun, json },
+    };
+}
+/**
+ * Validate the plan DAG locally, mirroring the server's `validate_epic_plan_dag`.
+ *
+ * This is not belt-and-braces: without it, a malformed plan surfaces as a bare
+ * HTTP 400 with no indication of which node is at fault. Fail here, legibly.
+ */
+export function validateEpicPlanSidecar(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, error: "Plan sidecar must be a JSON object." };
+    }
+    const plan = parsed;
+    const version = plan.plan_version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        return {
+            ok: false,
+            error: `plan_version must be an integer >= 1, got ${JSON.stringify(version)}.`,
+        };
+    }
+    if (!Array.isArray(plan.nodes) || plan.nodes.length === 0) {
+        return { ok: false, error: "plan.nodes must be a non-empty array." };
+    }
+    if (!Array.isArray(plan.edges)) {
+        return { ok: false, error: "plan.edges must be an array (use [] for none)." };
+    }
+    const keys = new Set();
+    const warnings = [];
+    for (const node of plan.nodes) {
+        if (!node || typeof node !== "object") {
+            return { ok: false, error: "Every plan node must be an object." };
+        }
+        const key = typeof node.ticket_key === "string" ? node.ticket_key.trim() : "";
+        if (!key)
+            return { ok: false, error: "Every plan node needs a non-empty ticket_key." };
+        if (keys.has(key))
+            return { ok: false, error: `Duplicate ticket_key in plan: ${key}.` };
+        keys.add(key);
+        if (node.touched_files === undefined) {
+            // Only fatal when the repo has file-overlap serialization enabled, in
+            // which case the server 400s. Warn either way — it is the difference
+            // between siblings serializing and colliding.
+            warnings.push(`Node ${key} has no touched_files. File-overlap serialization cannot ` +
+                `protect it; if the repo has that flag on, the server will reject this plan.`);
+        }
+    }
+    // Build one adjacency in a consistent predecessor -> successor direction, the
+    // same way the server does. `depends_on` points at the predecessor; an edge's
+    // `from` IS the predecessor.
+    const adjacency = new Map();
+    const addEdge = (from, to) => {
+        const list = adjacency.get(from) ?? [];
+        list.push(to);
+        adjacency.set(from, list);
+    };
+    for (const node of plan.nodes) {
+        const deps = Array.isArray(node.depends_on) ? node.depends_on : [];
+        for (const dep of deps) {
+            if (!keys.has(dep)) {
+                return {
+                    ok: false,
+                    error: `Node ${node.ticket_key} depends_on unknown ticket '${dep}'.`,
+                };
+            }
+            addEdge(dep, node.ticket_key);
+        }
+    }
+    for (const edge of plan.edges) {
+        if (!edge || typeof edge !== "object") {
+            return { ok: false, error: "Every plan edge must be an object." };
+        }
+        if (!keys.has(edge.from) || !keys.has(edge.to)) {
+            return {
+                ok: false,
+                error: `Edge ${JSON.stringify(edge.from)} -> ${JSON.stringify(edge.to)} references an unknown ticket.`,
+            };
+        }
+        addEdge(edge.from, edge.to);
+    }
+    const cycle = findCycle(keys, adjacency);
+    if (cycle) {
+        return { ok: false, error: `Plan DAG has a cycle: ${cycle.join(" -> ")}.` };
+    }
+    return { ok: true, plan: parsed, warnings };
+}
+/** Iterative DFS cycle detection; returns the offending path or null. */
+function findCycle(keys, adjacency) {
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    for (const k of keys)
+        color.set(k, WHITE);
+    for (const start of keys) {
+        if (color.get(start) !== WHITE)
+            continue;
+        const stack = [{ node: start, path: [start] }];
+        while (stack.length > 0) {
+            const { node, path } = stack[stack.length - 1];
+            if (color.get(node) === WHITE) {
+                color.set(node, GREY);
+                for (const next of adjacency.get(node) ?? []) {
+                    if (color.get(next) === GREY)
+                        return [...path, next];
+                    if (color.get(next) === WHITE) {
+                        stack.push({ node: next, path: [...path, next] });
+                    }
+                }
+            }
+            else {
+                if (color.get(node) === GREY)
+                    color.set(node, BLACK);
+                stack.pop();
+            }
+        }
+    }
+    return null;
+}
+function errorDetail(err) {
+    if (err instanceof ConductorBridgeApiError) {
+        const status = err.status !== undefined ? ` (HTTP ${err.status})` : "";
+        const preview = err.bodyPreview ? `: ${err.bodyPreview}` : "";
+        return `${err.message}${status}${preview}`;
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+export async function runSetupEpicCli(argv, overrides = {}) {
+    const deps = { ...createDefaultSetupEpicDeps(), ...overrides };
+    const parsed = parseSetupEpicArgs(argv);
+    if (parsed.status === "help") {
+        deps.log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        deps.errorLog(parsed.message);
+        deps.errorLog("");
+        deps.errorLog(getSetupEpicUsage());
+        return 1;
+    }
+    const opts = parsed.options;
+    // With --json, stdout carries the single result object and nothing else.
+    const say = opts.json ? deps.errorLog : deps.log;
+    // --- Read + validate the plan sidecar (no network yet) -------------------
+    let raw;
+    try {
+        raw = await deps.readFile(opts.planFile);
+    }
+    catch (err) {
+        deps.errorLog(`Could not read plan file '${opts.planFile}': ${errorDetail(err)}`);
+        return 1;
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (err) {
+        deps.errorLog(`Plan file '${opts.planFile}' is not valid JSON: ${errorDetail(err)}`);
+        return 1;
+    }
+    const validation = validateEpicPlanSidecar(parsedJson);
+    if (!validation.ok) {
+        deps.errorLog(`Invalid plan DAG: ${validation.error}`);
+        return 1;
+    }
+    const plan = validation.plan;
+    const warnings = [...validation.warnings];
+    if (opts.planVersion !== undefined && opts.planVersion !== plan.plan_version) {
+        deps.errorLog(`--plan-version ${opts.planVersion} does not match the sidecar's plan_version ` +
+            `${plan.plan_version}. Fix the sidecar (or drop the flag) — setup-epic never ` +
+            `rewrites the blob, because that would change its hash.`);
+        return 1;
+    }
+    const localHash = hashPlan(plan);
+    // --- Resolve access ------------------------------------------------------
+    const accessResult = await resolveConductorBridgeApiAccess({
+        env: deps.env,
+        cwd: deps.cwd,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        repoName: opts.repo,
+    });
+    if (!accessResult.ok) {
+        deps.errorLog(`Cannot reach the Bridge API: ${accessResult.error}`);
+        return 1;
+    }
+    const access = accessResult.access;
+    say(`Epic:       ${opts.epicKey}`);
+    say(`Repo:       ${access.repoName}`);
+    say(`Plan:       v${plan.plan_version}, ${plan.nodes.length} node(s), ${plan.edges.length} edge(s)`);
+    say(`Local hash: ${localHash}`);
+    for (const w of warnings)
+        say(`  [warn] ${w}`);
+    // --- Step 0: pre-check ---------------------------------------------------
+    // Never create on an ambiguous read. A wrong answer here mints a duplicate run.
+    let existingRunId = null;
+    let existingStatus = null;
+    try {
+        const state = await fetchEpicRunState(access, opts.epicKey, deps.fetch);
+        existingRunId = state.epic_run?.epic_run_id ?? null;
+        existingStatus = state.epic_run?.status ?? null;
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError && err.status === 404) {
+            existingRunId = null; // No live run — the normal first-run path.
+        }
+        else if (err instanceof ConductorBridgeApiError && err.status === 409) {
+            deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — it is wedged, and every ` +
+                `plan call will keep failing. Abandon the duplicate before retrying:\n` +
+                `  PATCH /jira/epic-runs/runs/<epic_run_id> {"status": "abandoned"}\n` +
+                `Detail: ${errorDetail(err)}`);
+            return 1;
+        }
+        else {
+            deps.errorLog(`Could not read the epic run state, so creating one would risk a duplicate ` +
+                `(which wedges the epic permanently). Refusing to continue.\n` +
+                `Detail: ${errorDetail(err)}`);
+            return 1;
+        }
+    }
+    if (opts.dryRun) {
+        say("");
+        say("[dry-run] No changes made. Would:");
+        if (existingRunId) {
+            say(`  - reuse existing run ${existingRunId} (status: ${existingStatus})`);
+        }
+        else {
+            say(`  - POST /jira/epic-runs/runs  (create run for ${opts.epicKey})`);
+        }
+        say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/plan          (v${plan.plan_version})`);
+        say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/approve-plan  (v${plan.plan_version})`);
+        if (opts.json) {
+            deps.log(JSON.stringify({
+                dry_run: true,
+                epic_key: opts.epicKey,
+                repo_name: access.repoName,
+                plan_version: plan.plan_version,
+                local_plan_hash: localHash,
+                existing_run_id: existingRunId,
+                warnings,
+            }, null, 2));
+        }
+        return 0;
+    }
+    const result = {
+        epic_run_id: existingRunId ?? "",
+        epic_key: opts.epicKey,
+        repo_name: access.repoName,
+        plan_version: plan.plan_version,
+        plan_hash: null,
+        local_plan_hash: localHash,
+        status: existingStatus,
+        run_created: false,
+        plan_stored: false,
+        plan_approved: false,
+        warnings,
+    };
+    // --- Step 1: create (only when there is no live run) ---------------------
+    if (existingRunId) {
+        say(`Run:        reusing ${existingRunId} (status: ${existingStatus})`);
+    }
+    else {
+        try {
+            const run = await createEpicRun(access, { epicKey: opts.epicKey }, deps.fetch);
+            result.epic_run_id = run.epic_run_id;
+            result.status = run.status;
+            result.run_created = true;
+            say(`Run:        created ${run.epic_run_id}`);
+        }
+        catch (err) {
+            deps.errorLog(`Failed to create the epic run: ${errorDetail(err)}`);
+            return 1;
+        }
+    }
+    // --- Step 2/3: store the plan -------------------------------------------
+    try {
+        const stored = await storeEpicPlan(access, {
+            epicKey: opts.epicKey,
+            planVersion: plan.plan_version,
+            planBlob: plan,
+            planHash: localHash,
+        }, deps.fetch);
+        result.plan_stored = true;
+        const serverHash = stored?.plan_hash;
+        if (typeof serverHash === "string")
+            result.plan_hash = serverHash;
+        say(`Plan:       stored v${plan.plan_version}`);
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError && err.status === 409) {
+            deps.errorLog(`Plan v${plan.plan_version} is already stored with a DIFFERENT hash. The stored ` +
+                `blob is immutable — bump plan_version in the sidecar and re-run.\n` +
+                `Detail: ${errorDetail(err)}`);
+            return 1;
+        }
+        deps.errorLog(`Failed to store the plan: ${errorDetail(err)}`);
+        return 1;
+    }
+    // --- Step 4: approve -----------------------------------------------------
+    const approval = await approveEpicPlan(access, { epicKey: opts.epicKey, planVersion: plan.plan_version }, deps.fetch).catch((err) => {
+        deps.errorLog(`Failed to approve the plan: ${errorDetail(err)}`);
+        return null;
+    });
+    if (approval === null)
+        return 1;
+    if (approval.ok) {
+        result.plan_approved = true;
+        result.plan_hash = approval.plan_hash;
+        result.status = "active";
+        say(`Plan:       approved v${plan.plan_version}`);
+    }
+    else if (approval.reason === "multiple_active_runs") {
+        deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — the plan could not be approved ` +
+            `and the epic is wedged. Abandon the duplicate run, then re-run setup-epic.`);
+        return 1;
+    }
+    else {
+        // A strictly later version is already approved. Benign: the caller is behind.
+        const msg = `A later plan version is already approved — approval skipped.`;
+        result.warnings.push(msg);
+        say(`Plan:       [warn] ${msg}`);
+    }
+    if (result.plan_hash && result.plan_hash !== localHash) {
+        // Expected when the repo serializes file-overlapping siblings: the server
+        // rewrites edges and re-hashes. Report, do not fail.
+        result.warnings.push(`Server plan hash differs from the local hash (the server re-hashes after ` +
+            `applying file-overlap serialization). The server hash is authoritative.`);
+    }
+    if (opts.json) {
+        deps.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        say("");
+        say(`Epic run ${result.epic_run_id} is ${result.status ?? "unknown"}.`);
+        say("The server-side reconciler will pick it up within ~30s.");
+        say("To execute claimed jobs on this machine, run:");
+        say(`  npx -y @bridge_gpt/mcp-server executor --repo ${access.repoName}`);
+    }
+    return 0;
+}

package/build/sfcc/log-gate.js

@@ -0,0 +1,85 @@
+/**
+ * Call-time SFCC *log-capability* gate (T7 / BAPI-556).
+ *
+ * Wraps the `sfcc_log_query` handler. Evaluated at call time (NOT startup) so the
+ * tool is always registered under the `sfcc` profile — the gate decides at
+ * invocation whether the repo's LOG capability (WebDAV Basic auth) is configured.
+ *
+ * This gate is deliberately distinct from `withSfccGate` (tool-wrapper.ts): it
+ * does NOT read the `version` config field, does NOT resolve `dw.json`, and does
+ * NOT acquire an Account Manager OAuth token. Log access uses HTTP Basic auth
+ * (BM username + 40-char WebDAV access key) that lives entirely server-side; the
+ * spike proved an AM bearer token 401s on `/Logs`. Readiness is resolved by the
+ * backend `GET /jira/sfcc/logs/capability` probe, which never returns a secret.
+ */
+// ---------------------------------------------------------------------------
+// Envelope helpers
+// ---------------------------------------------------------------------------
+function jsonResult(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+function notConfigured(failureClass, message, limits) {
+    return jsonResult({
+        error: "NOT_CONFIGURED",
+        status: 503,
+        failure_class: failureClass,
+        message,
+        ...(limits !== undefined ? { limits } : {}),
+    });
+}
+// ---------------------------------------------------------------------------
+// Gate
+// ---------------------------------------------------------------------------
+/**
+ * Wrap the log-query handler with the call-time log-capability gate.
+ *
+ * The returned handler:
+ * 1. GETs `/jira/sfcc/logs/capability` via Bridge API.
+ * 2. On a Bridge transport/auth failure, returns a distinct (non-NOT_CONFIGURED)
+ *    secret-free envelope so a temporary outage is not misread as "not set up".
+ * 3. On `configured: false`, returns the structured NOT_CONFIGURED 503 envelope
+ *    pointing the caller at `sfcc_setup_status`.
+ * 4. Calls the inner handler only when the capability is configured.
+ *
+ * Every failure is caught inside the wrapper and returned as normal MCP content —
+ * an exception never escapes to the stdio transport.
+ */
+export function withSfccLogGate(deps, handler) {
+    return async (args) => {
+        let body;
+        try {
+            const url = deps.buildGetUrl("/sfcc/logs/capability", {
+                repo_name: deps.repoName,
+            });
+            const resp = await fetch(url, { headers: await deps.getGetHeaders() });
+            if (!resp.ok) {
+                // Distinguish a Bridge auth/connectivity failure from "not configured".
+                return jsonResult({
+                    error: resp.status === 401 || resp.status === 403 ? "UNAUTHORIZED" : "SERVICE_UNAVAILABLE",
+                    status: resp.status,
+                    message: "Could not read the SFCC log capability from Bridge API " +
+                        "(/jira/sfcc/logs/capability). Ensure your Bridge API key is set and the " +
+                        "repo is authorized. Run sfcc_setup_status for a full diagnostic.",
+                });
+            }
+            body = (await resp.json());
+        }
+        catch {
+            return jsonResult({
+                error: "BAD_GATEWAY",
+                status: 502,
+                message: "Could not reach Bridge API to resolve the SFCC log capability. " +
+                    "Check that BAPI_BASE_URL points to a running Bridge API instance.",
+            });
+        }
+        if (body?.configured !== true) {
+            const failureClass = typeof body?.failure_class === "string" ? body.failure_class : "not_configured";
+            const message = typeof body?.message === "string"
+                ? body.message
+                : "SFCC on-demand log queries are not configured for this repository. " +
+                    "Run sfcc_setup_status for a diagnostic.";
+            return notConfigured(failureClass, message, body?.limits);
+        }
+        return handler(args);
+    };
+}