@bridge_gpt/mcp-server 0.2.52 → 0.2.53

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 }
+                        : {}),
+        });
+    });
+}