@bridge_gpt/mcp-server 0.2.52 → 0.2.54

package/build/install-doctor.js

@@ -20,6 +20,7 @@
  * required prerequisites only.
  */
 import path from "path";
+import { createReadinessCheck, createReadinessCheckSafely, } from "./readiness-check.js";
 import { resolveBapiCredentials } from "./credential-store.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "./claude-login.js";
 import { getProjectJsonTargets, hostAdapterForTarget } from "./mcp-host-targets.js";
@@ -105,7 +106,16 @@ export async function resolveInstallDoctorTarget(deps) {
     }
     return { repoName, repoSource, baseUrl: baseUrl ?? DEFAULT_BASE_URL };
 }
-/** Read-only GET with a bounded timeout. Never throws. */
+/** Classify a thrown probe failure into the closed category vocabulary. */
+function classifyProbeFailure(error) {
+    // `AbortSignal.timeout` rejects with a DOMException named `TimeoutError`;
+    // fall back to the name check so a polyfilled or wrapped abort still reads as
+    // a timeout rather than as a generic failure.
+    const name = error?.name;
+    return name === "TimeoutError" || name === "AbortError"
+        ? "request timed out"
+        : "request unavailable";
+}
 async function probeGet(deps, url, apiKey) {
     try {
         const resp = await deps.fetch(url, {
@@ -122,7 +132,7 @@ async function probeGet(deps, url, apiKey) {
         return { ok: true, status: resp.status, body };
     }
     catch (e) {
-        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        return { ok: false, error: classifyProbeFailure(e) };
     }
 }
 /** Count set/total bootstrap fields from an install-manifest response body. */
@@ -300,6 +310,8 @@ export async function collectInstallStatusChecks(deps) {
             label: "Server connectivity",
             status: "WARN",
             detail: `unexpected HTTP ${ping.status} from /jira/ping`,
+            remediation: "the server answered but not with a status this check understands — re-run doctor; " +
+                "if it persists the Bridge API is unhealthy and no install fact below can be trusted.",
         });
     }
     // --- bootstrap fields ---
@@ -310,6 +322,7 @@ export async function collectInstallStatusChecks(deps) {
             label: "Bootstrap config fields",
             status: "WARN",
             detail: `manifest unreachable (${manifest.error})`,
+            remediation: `check ${target.baseUrl} and your network, then re-run doctor.`,
         });
     }
     else if (manifest.status === 404) {
@@ -329,6 +342,8 @@ export async function collectInstallStatusChecks(deps) {
                 label: "Bootstrap config fields",
                 status: "WARN",
                 detail: "manifest response had an unexpected shape",
+                remediation: "the manifest could not be read, so no bootstrap field state is known — re-run doctor, " +
+                    "then run /install-bridge to re-derive the project configuration.",
             });
         }
         else if (summary.unset.length === 0) {
@@ -355,6 +370,8 @@ export async function collectInstallStatusChecks(deps) {
             label: "Bootstrap config fields",
             status: "WARN",
             detail: `unexpected HTTP ${manifest.status} from the install manifest`,
+            remediation: "the manifest endpoint answered with an unrecognized status — re-run doctor; " +
+                "if it persists, re-run /install-bridge for this repository.",
         });
     }
     // --- integrations (from the same manifest response; presence booleans only) ---
@@ -509,3 +526,138 @@ export function formatInstallStatusFallbackReport() {
         },
     ]);
 }
+// ---------------------------------------------------------------------------
+// Canonical readiness projection (BAPI-1055)
+// ---------------------------------------------------------------------------
+/**
+ * The complete install-side prerequisite set, in render order.
+ *
+ * A STABLE descriptor set, not a projection of whatever the collector happened
+ * to return. `collectInstallStatusChecks` returns early on an unresolved
+ * identity and again on an unresolved credential, so the checks it omits simply
+ * never appear — and a locus that vanished reads as "nothing to report" rather
+ * than "this could not be established". The adapter walks this list instead, so
+ * every prerequisite is always represented.
+ */
+export const INSTALL_READINESS_DESCRIPTORS = [
+    { id: "claude-login", label: "Claude login" },
+    { id: "identity", label: "Repository identity" },
+    { id: "credential", label: "Bridge API credential" },
+    { id: "connectivity", label: "Server connectivity" },
+    { id: "bootstrap", label: "Bootstrap config fields" },
+    { id: "integrations", label: "Integration credentials" },
+    { id: "github", label: "GitHub connection" },
+    { id: "indexing", label: "Repository indexing" },
+];
+/** Fixed remediation for an install prerequisite whose identity never resolved. */
+export const INSTALL_IDENTITY_REMEDIATION = "run /install-bridge (or set BAPI_REPO_NAME) to configure this project; without a repository " +
+    "identity no server-side conductor fact can be resolved.";
+/** Fixed remediation for the advisory Claude-login gap. */
+export const INSTALL_CLAUDE_LOGIN_REMEDIATION = "run `claude login` on the host that will run conductor workers; Bridge stores no Anthropic " +
+    "credential and cannot confirm this for you.";
+/** Fixed detail for a prerequisite the checklist stopped short of collecting. */
+const INSTALL_NOT_COLLECTED_DETAIL = "not collected — an earlier install prerequisite stopped the checklist";
+/** Fixed detail for a prerequisite whose whole collector could not be run. */
+const INSTALL_UNAVAILABLE_DETAIL = "unknown — the install-status checklist could not be collected at all";
+/** Fixed remediation for a prerequisite whose whole collector could not be run. */
+const INSTALL_UNAVAILABLE_REMEDIATION = "run `doctor` to collect the advisory install-status checklist directly; this prerequisite's " +
+    "state is unknown, not healthy.";
+/**
+ * How each install check's non-canonical statuses project (BAPI-1055).
+ *
+ * `INFO` never becomes a canonical status, and `SKIP` is not automatically
+ * `skip`: an unresolved repository identity is reported as `SKIP` by the
+ * collector because the checklist stops there, but it is a genuine unmet
+ * prerequisite, so it maps to `fail`. The mapping is therefore stated per check
+ * id rather than derived from the source status alone.
+ */
+function projectInstallStatus(check) {
+    if (check.status === "PASS")
+        return { status: "pass" };
+    if (check.status === "WARN") {
+        return { status: "warn", ...(check.remediation ? { remediation: check.remediation } : {}) };
+    }
+    if (check.status === "INFO") {
+        // `claude-login` INFO means "no local login marker found". That is an
+        // actionable conductor gap — a worker cannot run without it — so it warns.
+        if (check.id === "claude-login") {
+            return { status: "warn", remediation: INSTALL_CLAUDE_LOGIN_REMEDIATION };
+        }
+        // `indexing` INFO is genuinely informational in both of its branches (a
+        // parse running, or none running). Neither is a prerequisite gap, so the
+        // information rides on `detail` and the check passes.
+        return { status: "pass" };
+    }
+    // SKIP.
+    if (check.id === "identity") {
+        // Unknown identity is never a successful or guessed repository context.
+        return { status: "fail", remediation: check.remediation ?? INSTALL_IDENTITY_REMEDIATION };
+    }
+    return { status: "skip", ...(check.remediation ? { remediation: check.remediation } : {}) };
+}
+/**
+ * Project the install-status checklist into canonical readiness checks.
+ *
+ * PURE: no probe, no I/O, no re-derivation. Ids are namespaced `install.<id>`
+ * so provenance survives into a consolidated report without being encoded in
+ * display prose, and only the collector's own fixed labels, bounded details, and
+ * authored remediations are carried across.
+ */
+export function mapInstallStatusChecksToReadinessChecks(checks, 
+/**
+ * True when the COLLECTOR itself could not run, as opposed to running and
+ * stopping early.
+ *
+ * `null` alone cannot tell those apart, and they are not the same fact. A
+ * checklist that ran and returned early leaves its later prerequisites
+ * genuinely dependent — a `skip`. A checklist that never ran leaves them
+ * simply unknown, and unknown must never read as healthy, so they fail with a
+ * restoring remediation instead.
+ */
+collectorUnavailable = false) {
+    const byId = new Map();
+    for (const check of checks ?? []) {
+        // First writer wins: the collector emits each id once, and a duplicate from
+        // an injected fake must not silently replace the real finding.
+        if (!byId.has(check.id))
+            byId.set(check.id, check);
+    }
+    return INSTALL_READINESS_DESCRIPTORS.map(({ id, label }) => {
+        const source = byId.get(id);
+        if (!source) {
+            return collectorUnavailable
+                ? createReadinessCheck({
+                    id: `install.${id}`,
+                    source: "install",
+                    label,
+                    status: "fail",
+                    detail: INSTALL_UNAVAILABLE_DETAIL,
+                    remediation: INSTALL_UNAVAILABLE_REMEDIATION,
+                })
+                : // Absent because the checklist never got this far. A dependency case,
+                    // so `skip` — the prerequisite that stopped the chain carries the fix.
+                    createReadinessCheck({
+                        id: `install.${id}`,
+                        source: "install",
+                        label,
+                        status: "skip",
+                        detail: INSTALL_NOT_COLLECTED_DETAIL,
+                    });
+        }
+        const projected = projectInstallStatus(source);
+        return createReadinessCheckSafely({
+            id: `install.${id}`,
+            source: "install",
+            label: source.label || label,
+            status: projected.status,
+            ...(source.detail ? { detail: source.detail } : {}),
+            ...(projected.status === "pass"
+                ? {}
+                : projected.remediation
+                    ? { remediation: projected.remediation }
+                    : projected.status === "fail"
+                        ? { remediation: INSTALL_IDENTITY_REMEDIATION }
+                        : {}),
+        });
+    });
+}

package/build/local-artifact-storage.js

@@ -0,0 +1,130 @@
+/**
+ * Structured local artifact persistence primitives (BAPI-1121).
+ *
+ * WHY THIS EXISTS. `wait_for_ticket_review`'s generation-aware artifact gate
+ * (`ticket-review-artifact-gate.ts`) needs a write/removal outcome it can
+ * branch on — did the accepted clarify leg actually land on disk, did the
+ * withheld critique file actually get removed — without parsing a
+ * human-readable note string. The pre-existing `saveLocally` in `index.ts`
+ * returns exactly that kind of note, and every existing artifact tool (the
+ * six single-artifact request/get tools, the BAPI-342 heavy-read saves, the
+ * combined ticket-review fan-out) depends on its exact rendered shape. This
+ * module extracts the underlying write mechanics into one place, so both the
+ * legacy byte-compatible `saveLocally` and the new structured primitives the
+ * gate uses share a single implementation rather than diverging.
+ *
+ * WHY A SEPARATE MODULE. `index.ts` is the file every other module is
+ * imported INTO; a helper defined there cannot be imported back into a module
+ * `index.ts` itself imports without an import cycle. This module has no
+ * dependency on `index.ts`, so `index.ts` imports `saveLocally` from here
+ * (BAPI-1121) instead of defining it locally, and the artifact gate imports
+ * the structured primitives directly.
+ */
+import { writeFile, mkdir, rename, unlink } from "fs/promises";
+import path from "path";
+import { randomUUID } from "node:crypto";
+/**
+ * Write `content` to `dir/filename` via per-file temporary staging followed by
+ * an atomic rename, so a concurrent reader can never observe a partially
+ * written file and a failed write never leaves a corrupt final artifact.
+ *
+ * The staging filename includes a random suffix so concurrent writes to the
+ * same final filename (unusual, but not prevented at this layer) cannot stage
+ * onto the same temporary path.
+ *
+ * Throws on failure — this is the shared low-level primitive both
+ * {@link saveLocally} (byte-compatible legacy notes) and
+ * {@link writeCanonicalArtifact} (sanitized structured outcome) wrap
+ * differently, because they render a failure to their callers in two
+ * deliberately different shapes.
+ */
+async function writeFileAtomic(dir, filename, content) {
+    const finalPath = path.join(dir, filename);
+    const stagingPath = path.join(dir, `.${filename}.${randomUUID()}.tmp`);
+    await mkdir(dir, { recursive: true });
+    try {
+        await writeFile(stagingPath, content, "utf-8");
+        await rename(stagingPath, finalPath);
+    }
+    catch (err) {
+        // Best-effort cleanup of an orphaned staging file. Cleanup failure (or the
+        // staging file never having been created) does not change the outcome
+        // that matters: the original write/rename error propagates below.
+        try {
+            await unlink(stagingPath);
+        }
+        catch {
+            // Nothing to clean up, or cleanup itself failed — either way the
+            // original error is what the caller needs to see.
+        }
+        throw err;
+    }
+    return finalPath;
+}
+/**
+ * Byte-compatible replacement for the pre-BAPI-1121 `saveLocally` in
+ * `index.ts`. Preserves the exact call shape (`dir`, `filename`, `content` ->
+ * a rendered note string) and the exact rendered success/failure notes every
+ * existing artifact-tool caller depends on — including the raw error suffix
+ * on failure, which existing tests assert verbatim. The only behavioral
+ * change is that the write is now staged-then-renamed rather than written
+ * in place, which is externally invisible on success and, on failure, means
+ * no partial file is ever left at `dir/filename` (an improvement, not a
+ * compatibility break).
+ */
+export async function saveLocally(dir, filename, content) {
+    try {
+        const finalPath = await writeFileAtomic(dir, filename, content);
+        return `\n\n---\nSaved to ${finalPath}`;
+    }
+    catch (writeErr) {
+        const filePath = path.join(dir, filename);
+        return `\n\n---\nNote: Failed to save file to ${filePath}: ${writeErr}`;
+    }
+}
+/**
+ * Structured canonical write for the generation-aware artifact gate. Returns
+ * `{ ok, path, message }` rather than throwing or requiring the caller to
+ * parse a note string. The public `message` is sanitized to the path and
+ * outcome only; any detailed local diagnostic (the underlying filesystem
+ * error) goes only to `console.error`, never through MCP.
+ */
+export async function writeCanonicalArtifact(dir, filename, content) {
+    const finalPath = path.join(dir, filename);
+    try {
+        await writeFileAtomic(dir, filename, content);
+        return { ok: true, path: finalPath, message: `Saved to ${finalPath}` };
+    }
+    catch (err) {
+        console.error(`[local-artifact-storage] write failed for ${finalPath}:`, err);
+        return { ok: false, path: finalPath, message: `Failed to save file to ${finalPath}` };
+    }
+}
+/**
+ * Remove the exact canonical path for a withheld or stale artifact.
+ *
+ * Idempotent by design: an already-absent target (`ENOENT`) is reported as a
+ * SUCCESSFUL cleanup outcome, not an error — a retried removal, or a removal
+ * that runs after an earlier successful one, must never report failure. Only
+ * an actual removal failure (permissions, a directory at that path, etc.) is
+ * reported as `ok: false`.
+ *
+ * Removes exactly the given path — no globbing, no directory recursion, no
+ * inference of sibling files to clean up. The caller is responsible for
+ * passing the exact canonical target; this primitive never widens the blast
+ * radius of a removal on its own.
+ */
+export async function removeCanonicalArtifact(targetPath) {
+    try {
+        await unlink(targetPath);
+        return { ok: true, path: targetPath, message: `Removed ${targetPath}` };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            return { ok: true, path: targetPath, message: `${targetPath} was already absent` };
+        }
+        console.error(`[local-artifact-storage] removal failed for ${targetPath}:`, err);
+        return { ok: false, path: targetPath, message: `Failed to remove ${targetPath}` };
+    }
+}