@bridge_gpt/mcp-server 0.2.52 → 0.2.54

package/build/conductor/readiness-cli.js

@@ -0,0 +1,152 @@
+/**
+ * The `conductor readiness` command surface (BAPI-1055, AC-6).
+ *
+ * A CLI subcommand, deliberately, and NOT an MCP tool. Every peer diagnostic in
+ * this package — `doctor`, `plane`, `drive-epic`, `executor`, `install` — is an
+ * `argv[0]` subcommand dispatched before MCP server construction, and this one
+ * inherits that standard: stdout carries the report, stderr carries only fixed
+ * sanitized notices, and no tool is registered, so the budget-pinned `tools/list`
+ * surface is untouched.
+ *
+ * THIN BY CONSTRUCTION. Argument parsing, dependency construction, and
+ * formatting live here; every probe, verdict, and mapping belongs to
+ * {@link file:./readiness.ts} and the collectors it composes.
+ *
+ * ## Advisory exit policy
+ *
+ * This command returns 0 for every readiness outcome — pass, warn, fail, skip,
+ * an unavailable source, and a malformed upstream response alike. It never
+ * mutates `process.exitCode`, never brings a plane up, never approves a run, and
+ * never executes a remediation. An advisory command that could exit non-zero
+ * would be a gate, and the hard gates are `drive-epic`'s
+ * `V2_READINESS_REQUIREMENTS` and the server-side admission.
+ *
+ * The only non-zero path is a usage error (an unknown flag), which is the
+ * command failing to run at all rather than a readiness verdict.
+ *
+ * ## Credentials
+ *
+ * Resolution goes through `resolveConductorBridgeApiAccess`, which reads
+ * `BAPI_API_KEY` from the parent environment and then the user-scoped store at
+ * `~/.config/bridge/credentials.json`. That is the shell-spawned credential
+ * rule: this command runs in a plain shell, which never sees `.mcp.json` env —
+ * that file is visible to the MCP server process only.
+ */
+import os from "node:os";
+import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import { collectConductorReadinessGate, formatConductorReadinessGateReport, } from "./readiness.js";
+import { resolveConductorBridgeApiAccess } from "./bridge-api-client.js";
+import { claudeReviewWorkflowPath } from "../claude-review-workflow.js";
+import { runDefaultPlanePreflight } from "../plane/cli.js";
+/** Fixed notice emitted to stderr when a source could not be collected. */
+export const READINESS_COLLECTION_NOTICE = "one or more readiness sources could not be collected; the affected prerequisites are reported as failures.";
+/** Usage text for `conductor readiness`. */
+export function getReadinessUsage() {
+    return [
+        "Usage: conductor readiness [--json] [--no-deny-probe]",
+        "",
+        "Read-only ADVISORY report of every conductor prerequisite, consolidated from the",
+        "Bridge install checklist, the conductor doctor, the plane preflight, and the",
+        "server conductor-readiness collector. Each prerequisite reports pass/warn/fail/skip",
+        "and, on a failure, exactly ONE named remediation.",
+        "",
+        "Remediations are NOT run automatically. This command changes nothing: it starts no",
+        "plane, approves no run, writes no file, and always exits 0 — `drive-epic` remains",
+        "the only route-selection gate and the server-side admission the only hard refusal.",
+        "",
+        "Options:",
+        "  --json            Print the versioned structured report as JSON",
+        "  --no-deny-probe   Accepted for parity with `conductor doctor`; inert here, because",
+        "                    this command never spawns the deny-enforcement probe",
+        "  --help            Print this usage message",
+    ].join("\n");
+}
+/** Parse `conductor readiness` argv. Unknown flags and positionals are errors. */
+export function parseReadinessArgs(argv) {
+    const parsed = { json: false, help: false, noDenyProbe: false };
+    for (const token of argv) {
+        if (token === "--json")
+            parsed.json = true;
+        else if (token === "--no-deny-probe")
+            parsed.noDenyProbe = true;
+        else if (token === "--help" || token === "-h")
+            parsed.help = true;
+        else
+            return { error: `Unknown argument "${token}". Run "conductor readiness --help" for usage.` };
+    }
+    return parsed;
+}
+/**
+ * Build the production report for `repoRoot`.
+ *
+ * Every seam is a real, READ-ONLY one: the install doctor's own GET, the
+ * conductor doctor's local inspections, and the same plane preflight
+ * `plane up` and `drive-epic` run. Nothing is re-implemented here.
+ */
+async function collectProductionReport(repoRoot, env) {
+    const accessResult = await resolveConductorBridgeApiAccess({ env, cwd: repoRoot });
+    const access = accessResult.ok ? accessResult.access : null;
+    return collectConductorReadinessGate({
+        // Never guessed: an unresolved identity is reported as such rather than
+        // invented, and the repository ROOT is never placed in the report at all.
+        repoName: access?.repoName ?? null,
+        installDoctor: {
+            access,
+            accessError: accessResult.ok ? undefined : accessResult.error,
+            fetch: (...args) => fetch(...args),
+            // The consolidated gate reports workflow presence as a fact; it selects no
+            // per-run review policy, so applicability is evaluated under the policy
+            // that always consumes the workflow's verdict.
+            reviewPolicySource: "verdict_protocol",
+            readWorkflowFile: () => fsReadFile(claudeReviewWorkflowPath(repoRoot), "utf-8"),
+            projectRoot: repoRoot,
+            installDoctorDeps: {
+                env,
+                cwd: repoRoot,
+                platform: process.platform,
+                homedir: os.homedir,
+                readFile: (filePath) => fsReadFile(filePath, "utf-8"),
+                stat: (filePath) => fsStat(filePath),
+                fetch: (...args) => fetch(...args),
+            },
+        },
+        // The deny-enforcement probe is never spawned from this command; the check
+        // is reported as an explicit skip naming `conductor doctor` instead.
+        conductorDoctorDeps: { env, skipDenyProbe: true },
+        runPlanePreflight: () => runDefaultPlanePreflight(repoRoot, env),
+    });
+}
+/**
+ * Run `conductor readiness`.
+ *
+ * Returns 0 for every readiness outcome; see the module docstring. The only
+ * non-zero return is a usage error.
+ */
+export async function runConductorReadinessCommand(argv, deps = {}) {
+    const sinks = deps.sinks ?? {
+        stdout: (line) => console.log(line),
+        stderr: (line) => console.error(line),
+    };
+    const parsed = parseReadinessArgs(argv);
+    if ("error" in parsed) {
+        sinks.stderr(`Error: ${parsed.error}`);
+        return 1;
+    }
+    if (parsed.help) {
+        sinks.stdout(getReadinessUsage());
+        return 0;
+    }
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const collect = deps.collect ?? ((repoRoot) => collectProductionReport(repoRoot, env));
+    const report = await collect(cwd);
+    // Fixed, sanitized, and stderr-only: never a credential, exception, header,
+    // body, subprocess output, or absolute path. It fires on a COLLECTION gap,
+    // not on a failed prerequisite — a report that says "a source is missing"
+    // every time an ordinary check fails teaches operators to ignore it.
+    if (report.unavailableSources.length > 0)
+        sinks.stderr(READINESS_COLLECTION_NOTICE);
+    sinks.stdout(parsed.json ? JSON.stringify(report) : formatConductorReadinessGateReport(report));
+    // Advisory: the exit code is a constant, never derived from a check status.
+    return 0;
+}