@bridge_gpt/mcp-server 0.2.31 → 0.2.32

package/build/doctor.js

@@ -20,7 +20,7 @@ import os from "os";
 import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
 import { VERSION } from "./version.generated.js";
-import { collectInstallStatusChecks, formatInstallStatusReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
+import { collectInstallStatusChecks, formatInstallStatusReport, formatInstallStatusFallbackReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
 import { parseDefaultOnEnvFlag } from "./env-flags.js";
 import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
@@ -28,21 +28,37 @@ import { resolveBapiCredentials } from "./credential-store.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
+/**
+ * The report/usage title (BAPI-669, U9b). `doctor` diagnoses the whole Bridge
+ * install — install status, prerequisites, launcher cache, and tool surface — so it
+ * is no longer titled as a start-tickets-only tool. Defined once and shared by
+ * {@link getDoctorUsage} and {@link buildDoctorReportHeader} so the two cannot drift.
+ */
+export const DOCTOR_REPORT_TITLE = "bridge doctor — read-only diagnostics";
 /** User-facing usage text for the read-only `doctor` subcommand. */
 export function getDoctorUsage() {
     return [
         "Usage:",
         "  npx -y @bridge_gpt/mcp-server doctor [--agent <name>]",
         "",
-        "Read-only diagnostics for the start-tickets CLI. It only checks your",
-        "environment and prints manual install instructions — it does not install",
-        "anything, modify your system, or start the MCP server.",
+        // BAPI-669 (U9b): `doctor` is the general Bridge diagnostic command, not a
+        // start-tickets-only one — and its report leads with install status, so the
+        // usage text describes it in that order too.
+        `${DOCTOR_REPORT_TITLE}. It only checks your environment and prints manual`,
+        "install instructions — it does not install anything, modify your system, or",
+        "start the MCP server.",
         "",
         "Flags:",
         "  --agent claude|cursor-agent   Agent to include in the prerequisite check (default: claude)",
         "  -h, --help                    Show this help",
         "",
-        "Checks (for the current OS): the start-tickets preflight prerequisites plus",
+        "The report opens with an advisory 'Install status' section (easy-install done",
+        "criteria): repo identity, credential resolution, server connectivity,",
+        "bootstrap-field completeness, integration credentials, and repository-indexing",
+        "state. It performs read-only GETs only and never affects the exit code.",
+        "",
+        "After that come the start-tickets prerequisite checks (for the current OS):",
+        "the start-tickets preflight prerequisites plus",
         "uv, the selected agent's command, Bridge API credential resolution, and",
         "worktree MCP registration reachability. Credential resolution reports the",
         "source it would use (env vs. store target bapi:<repo>); it never reads or",
@@ -50,11 +66,6 @@ export function getDoctorUsage() {
         "migrate a credential, use /install-bridge or the `credentials` subcommand —",
         "doctor stays strictly read-only.",
         "",
-        "The report also includes an advisory 'Install status' section (easy-install",
-        "done criteria): repo identity, credential resolution, server connectivity,",
-        "bootstrap-field completeness, and repository-indexing state. It performs",
-        "read-only GETs only and never affects the exit code.",
-        "",
         "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
         "dynamic capability gating would advertise for this repo. It performs at most",
         "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
@@ -155,20 +166,31 @@ export async function collectDoctorResults(deps, agentName) {
     return { ok: true, results };
 }
 /**
- * Render the doctor report: platform + selected agent header, one found/missing
- * line per prerequisite, the exact manual install hint for each missing one
- * (framed as manual instructions only), and the selected agent's auth note
- * (especially the `cursor-agent login` reminder). Pure formatting — no probing.
+ * The BROAD report header: title plus the run's platform / agent / profile
+ * metadata (BAPI-669, U9b). Split out from the prerequisite body so `runDoctorCli`
+ * has a clear insertion point for the Install-status section between the two — the
+ * ordering change is the whole point, and it must not require rewriting the
+ * prerequisite formatting below.
  */
-export function formatDoctorReport(platform, agent, collection) {
+export function buildDoctorReportHeader(platform, agent) {
     const activeGroups = Array.from(resolveProfiles(process.env.BRIDGE_MCP_PROFILE)).join(", ");
-    const lines = [
-        "start-tickets doctor (read-only diagnostics)",
+    return [
+        DOCTOR_REPORT_TITLE,
         `Platform: ${platform}`,
         `Selected agent: ${agent.name} (command: ${agent.command})`,
         `Active MCP Groups: \`${activeGroups}\``,
         "",
     ];
+}
+/**
+ * The start-tickets PREREQUISITE section: one found/missing line per prerequisite,
+ * the exact manual install hint for each missing one (framed as manual instructions
+ * only), and the selected agent's auth note (especially the `cursor-agent login`
+ * reminder). Pure formatting — no probing. Byte-identical to what
+ * {@link formatDoctorReport} has always rendered below its header.
+ */
+export function formatDoctorPrereqSection(platform, collection) {
+    const lines = [];
     if (!collection.ok) {
         lines.push(`Platform '${platform}' is unsupported. start-tickets supports darwin, win32, and linux.`);
         return lines.join("\n");
@@ -193,6 +215,17 @@ export function formatDoctorReport(platform, agent, collection) {
     lines.push("For conductor ledger/native-module diagnostics, run: conductor doctor");
     return lines.join("\n");
 }
+/**
+ * Header + prerequisite section, composed. Retained as the single-call rendering
+ * used by direct callers and tests; `runDoctorCli` composes the two halves itself so
+ * it can slot Install status between them (BAPI-669, U9c).
+ */
+export function formatDoctorReport(platform, agent, collection) {
+    return [
+        ...buildDoctorReportHeader(platform, agent),
+        formatDoctorPrereqSection(platform, collection),
+    ].join("\n");
+}
 // ---------------------------------------------------------------------------
 // Launcher-cache diagnostics (BAPI-451 W3, E-4/E-9) — strictly read-only.
 //
@@ -504,25 +537,20 @@ export async function runDoctorCli(argv, overrides = {}) {
     const deps = overrides.deps ?? createDefaultStartTicketsDeps();
     const agent = resolveAgentSpec(parsed.options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
     const collection = await collectDoctorResults(deps, parsed.options.agentName);
-    log(formatDoctorReport(deps.platform, agent, collection));
-    // Strictly read-only launcher-cache diagnostics (BAPI-451). Best-effort: a probe
-    // failure never changes the doctor exit code (cold-start readiness is advisory,
-    // not a hard prerequisite). The exit code remains driven by required prereqs.
-    try {
-        const launcherDeps = {
-            cwd: overrides.launcherProbe?.cwd ?? deps.cwd,
-            readFile: overrides.launcherProbe?.readFile ?? ((p) => readFile(p, "utf-8")),
-            probeNpxNoInstall: overrides.launcherProbe?.probeNpxNoInstall ?? probeNpxNoInstallDefault,
-        };
-        const launcherInspections = await inspectLauncherCache(launcherDeps);
-        log(formatLauncherCacheReport(launcherInspections));
-    }
-    catch {
-        /* launcher-cache diagnostics are advisory; never block the doctor report */
-    }
+    // ---- Section order (BAPI-669, U9c) ----
+    // Broad header → Install status → start-tickets prerequisites → launcher cache →
+    // MCP tool surface. Install status renders FIRST and UNCONDITIONALLY: it answers
+    // "is this project actually set up?", which is what someone running `doctor` after
+    // an install is asking. There is deliberately no "invocation context" flag to gate
+    // the ordering on — the report has a single caller and carries no context, so
+    // always-first is both simpler and equivalent. The `installStatus: false` override
+    // remains a dependency-injection-only seam for hermetic tests; a normal CLI
+    // invocation never takes it.
+    log(buildDoctorReportHeader(deps.platform, agent).join("\n"));
     // Advisory install-status section (easy-install done criteria). Read-only GETs
     // only; any failure degrades to WARN/SKIP lines inside the section, and any
-    // unexpected throw is swallowed — the exit code is never affected.
+    // unexpected throw renders the sanitized fallback rather than dropping the
+    // report's first section — the exit code is never affected either way.
     if (overrides.installStatus !== false) {
         try {
             // Reuse fs deps injected on `deps` (doctor's credential probes place them
@@ -543,9 +571,26 @@ export async function runDoctorCli(argv, overrides = {}) {
             log(formatInstallStatusReport(checks));
         }
         catch {
-            /* install-status diagnostics are advisory; never block the doctor report */
+            // Advisory, but never silently absent: the first section always renders.
+            log(formatInstallStatusFallbackReport());
         }
     }
+    log(formatDoctorPrereqSection(deps.platform, collection));
+    // Strictly read-only launcher-cache diagnostics (BAPI-451). Best-effort: a probe
+    // failure never changes the doctor exit code (cold-start readiness is advisory,
+    // not a hard prerequisite). The exit code remains driven by required prereqs.
+    try {
+        const launcherDeps = {
+            cwd: overrides.launcherProbe?.cwd ?? deps.cwd,
+            readFile: overrides.launcherProbe?.readFile ?? ((p) => readFile(p, "utf-8")),
+            probeNpxNoInstall: overrides.launcherProbe?.probeNpxNoInstall ?? probeNpxNoInstallDefault,
+        };
+        const launcherInspections = await inspectLauncherCache(launcherDeps);
+        log(formatLauncherCacheReport(launcherInspections));
+    }
+    catch {
+        /* launcher-cache diagnostics are advisory; never block the doctor report */
+    }
     // Advisory MCP tool-surface capability section (BAPI-641). Strictly read-only:
     // one 500 ms GET (or none, under the kill switch). Any timeout, malformed
     // response, or unexpected throw degrades to a "fail-open to full surface" line