@bridge_gpt/mcp-server 0.2.34 → 0.2.36

package/build/install-bridge-conductor.js

@@ -0,0 +1,491 @@
+/**
+ * `install-bridge conductor` — the nested conductor bootstrap phase (BAPI-679).
+ *
+ * Standing up Epic Conductor v2 on a fresh repository previously meant a manual
+ * sequence of API calls and hand-written config, with five server-side
+ * prerequisites that were invisible until an epic was already running and
+ * failing. This command replaces that sequence with: diagnose → consent →
+ * bootstrap the safe posture → optionally scaffold the review workflow → report
+ * capabilities → verify → diagnose again.
+ *
+ * Four properties are load-bearing and are pinned by tests:
+ *
+ * 1. **Base-URL consent before ANY network call.** `resolveInstallBridgeBaseUrl`
+ *    silently defaults to production when `BAPI_BASE_URL` is unset, and even the
+ *    read-only doctor's readiness GET carries this repository's API key — so the
+ *    resolved URL is displayed and explicitly confirmed BEFORE the first request
+ *    of any kind, including under `--dry-run`. Non-interactive (no TTY) means no
+ *    consent, which means abort. Only after that does the unified doctor run,
+ *    still BEFORE any write, and a fatal finding aborts. Repairable gaps
+ *    (missing supervisor rows — exactly what bootstrap fixes) are `degraded`
+ *    and do not block.
+ * 2. **`--dry-run` writes nothing, anywhere.** It returns before every POST,
+ *    filesystem write, install-state write, and write-consent prompt. (It still
+ *    asks the base-URL confirmation above, because its doctor GET is a network
+ *    call that reveals the key to the resolved host.)
+ * 3. **Two independent consents.** Confirming the resolved base URL is NOT
+ *    consent to write, and neither is consent to overwrite a workflow file. Each
+ *    write surface asks for itself.
+ * 4. **The executor leg is never claimed as provisioned by a bootstrap.** The
+ *    doctor *detects* generated service units (`executor install-service`,
+ *    BAPI-688), but starting one stays operator-managed, so the capability
+ *    matrix reports `executor_ready` only from a live server-observed claim and
+ *    the run prints `complete-with-manual-steps` until then.
+ *
+ * The command does NOT persist a repository-level review policy: that is
+ * BAPI-694's. The policy selected here is per-run and is reported as such.
+ */
+import { bootstrapConductorSupervisorDefaults, ConductorBridgeApiError, fetchConductorReadiness, } from "./conductor/bridge-api-client.js";
+import { CONDUCTOR_OPERATOR_RUNBOOK_POINTER, EXECUTOR_PROVISIONING_GUIDANCE, conductorInstallDoctorExitCode, conductorInstallDoctorHasFatal, formatConductorInstallDoctorReport, } from "./conductor/install-doctor.js";
+import { CLAUDE_REVIEW_WORKFLOW_RELPATH, renderClaudeReviewWorkflow, } from "./claude-review-workflow.js";
+// ---------------------------------------------------------------------------
+// Options + parsing
+// ---------------------------------------------------------------------------
+/** Review-policy vocabulary accepted on the CLI (the `ReviewPolicy` surface). */
+export const CONDUCTOR_REVIEW_POLICY_SOURCES = [
+    "verdict_protocol",
+    "native_review_decision",
+    "none",
+];
+/** Default per-run review policy when the operator does not select one. */
+export const DEFAULT_CONDUCTOR_REVIEW_POLICY = "verdict_protocol";
+/** Usage text for `install-bridge conductor`. */
+export function getInstallBridgeConductorUsage() {
+    return [
+        "Usage: install conductor [options]",
+        "",
+        "Bootstrap Epic Conductor v2 for this repository: run the unified read-only",
+        "doctor, write the safe project-default supervisor posture, optionally scaffold",
+        "the claude-review workflow, report the capability matrix, and re-run the doctor.",
+        "",
+        "Options:",
+        "  --repo <name>              Repository name (default: BAPI_REPO_NAME / .bridge/config)",
+        "  --required-check <name>    Required CI check for the done gate (repeatable, REQUIRED)",
+        "  --required-checks a,b      Comma-separated form of --required-check",
+        `  --review-policy <source>   One of: ${CONDUCTOR_REVIEW_POLICY_SOURCES.join(", ")}`,
+        `                             (default: ${DEFAULT_CONDUCTOR_REVIEW_POLICY}; PER-RUN only —`,
+        "                             repository defaults are not stored until BAPI-694)",
+        "  --epic-key <KEY>           Epic key for the setup-epic verification phase",
+        "  --plan-file <path>         Plan sidecar for the setup-epic verification phase",
+        "  --allowed-bot <slug>       claude-review workflow: allowed bot login",
+        "  --secret-name <NAME>       claude-review workflow: OAuth token secret NAME",
+        "  --branches a,b             claude-review workflow: PR branch triggers",
+        "  --skip-workflow            Never offer the claude-review workflow",
+        "  --dry-run                  Diagnose and preview only. Performs NO writes:",
+        "                             no POST, no file write, no install-state write,",
+        "                             and no write-consent prompt. Still asks the",
+        "                             base-URL confirmation below first — its doctor",
+        "                             readiness GET carries the repo API key.",
+        "  -h, --help                 Show this help",
+        "",
+        "The resolved BAPI_BASE_URL is displayed and confirmed BEFORE any network call",
+        "(including the read-only doctor GET — BAPI_BASE_URL silently defaults to",
+        "production when unset). The bootstrap POST then asks its own, separate write",
+        "consent. Without a TTY there is no consent, so the command aborts.",
+        "",
+        "Executor provisioning: generate a persistent service unit with",
+        "`executor install-service` (BAPI-688). Starting/stopping it stays",
+        `operator-managed; see ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`,
+    ].join("\n");
+}
+function splitList(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Parse the nested conductor arguments strictly.
+ *
+ * Every invalid form returns an error BEFORE the caller runs the doctor, issues
+ * a fetch, prompts, or writes — an unparseable invocation must have no side
+ * effects at all.
+ */
+export function parseInstallBridgeConductorArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getInstallBridgeConductorUsage() };
+    }
+    let repo;
+    let dryRun = false;
+    let skipWorkflow = false;
+    let reviewPolicy = DEFAULT_CONDUCTOR_REVIEW_POLICY;
+    let epicKey;
+    let planFile;
+    let allowedBot;
+    let secretName;
+    let branches;
+    const requiredChecks = [];
+    const takeValue = (arg, inline, next) => {
+        if (inline !== undefined) {
+            if (inline.trim().length === 0)
+                return { ok: false, error: `${arg} requires a value` };
+            return { ok: true, value: inline.trim(), consumedNext: false };
+        }
+        if (next === undefined || next.startsWith("-") || next.trim().length === 0) {
+            return { ok: false, error: `${arg} requires a value` };
+        }
+        return { ok: true, value: next.trim(), consumedNext: true };
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const raw = argv[i];
+        const eq = raw.indexOf("=");
+        const flag = eq === -1 ? raw : raw.slice(0, eq);
+        const inline = eq === -1 ? undefined : raw.slice(eq + 1);
+        switch (flag) {
+            case "--dry-run":
+                if (inline !== undefined)
+                    return { status: "error", message: "--dry-run takes no value" };
+                dryRun = true;
+                break;
+            case "--skip-workflow":
+                if (inline !== undefined)
+                    return { status: "error", message: "--skip-workflow takes no value" };
+                skipWorkflow = true;
+                break;
+            case "--repo":
+            case "--required-check":
+            case "--required-checks":
+            case "--review-policy":
+            case "--epic-key":
+            case "--plan-file":
+            case "--allowed-bot":
+            case "--secret-name":
+            case "--branches": {
+                const taken = takeValue(flag, inline, argv[i + 1]);
+                if (!taken.ok)
+                    return { status: "error", message: taken.error };
+                if (taken.consumedNext)
+                    i++;
+                const value = taken.value;
+                if (flag === "--repo")
+                    repo = value;
+                else if (flag === "--required-check")
+                    requiredChecks.push(value);
+                else if (flag === "--required-checks")
+                    requiredChecks.push(...splitList(value));
+                else if (flag === "--epic-key")
+                    epicKey = value;
+                else if (flag === "--plan-file")
+                    planFile = value;
+                else if (flag === "--allowed-bot")
+                    allowedBot = value;
+                else if (flag === "--secret-name")
+                    secretName = value;
+                else if (flag === "--branches") {
+                    const list = splitList(value);
+                    if (list.length === 0)
+                        return { status: "error", message: "--branches requires at least one branch" };
+                    branches = list;
+                }
+                else if (flag === "--review-policy") {
+                    if (!CONDUCTOR_REVIEW_POLICY_SOURCES.includes(value)) {
+                        return {
+                            status: "error",
+                            message: `Invalid --review-policy '${value}'. Expected one of: ${CONDUCTOR_REVIEW_POLICY_SOURCES.join(", ")}`,
+                        };
+                    }
+                    reviewPolicy = value;
+                }
+                break;
+            }
+            default:
+                return { status: "error", message: `Unknown option: ${flag}` };
+        }
+    }
+    // Normalize + validate the required-check list at parse time so a bad list can
+    // never reach the bootstrap request. An EMPTY done gate is not a weaker gate —
+    // it passes unconditionally — so it is rejected here, not merely defaulted.
+    const normalizedChecks = [];
+    const seen = new Set();
+    for (const check of requiredChecks) {
+        if (seen.has(check)) {
+            return { status: "error", message: `Duplicate required check: ${check}` };
+        }
+        seen.add(check);
+        normalizedChecks.push(check);
+    }
+    if (normalizedChecks.length === 0) {
+        return {
+            status: "error",
+            message: "At least one --required-check is required. An empty done gate passes unconditionally, " +
+                "so the bootstrap refuses to write one.",
+        };
+    }
+    return {
+        status: "ok",
+        options: {
+            repo,
+            dryRun,
+            requiredChecks: normalizedChecks,
+            reviewPolicy,
+            epicKey,
+            planFile,
+            allowedBot,
+            secretName,
+            branches,
+            skipWorkflow,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+const CONSENT_YES = new Set(["y", "yes"]);
+async function confirm(deps, promptText) {
+    // A missing prompt seam means no TTY. Silence is NOT consent.
+    if (!deps.promptLine)
+        return false;
+    const answer = await deps.promptLine(promptText);
+    return CONSENT_YES.has((answer ?? "").trim().toLowerCase());
+}
+function renderCapabilityMatrix(deps, readiness) {
+    const apiReady = readiness !== null;
+    // Derived from READINESS, never from the bootstrap's HTTP status: a 200 proves
+    // the write was accepted, not that the resulting posture is safe.
+    const configurationReady = readiness !== null &&
+        readiness.supervisor.setup_present &&
+        readiness.supervisor.config_present &&
+        !readiness.supervisor.required_checks_empty;
+    // `ready === null` (never provisioned) and `false` (stale) are both "not ready"
+    // here, but only a recent server-observed claim/heartbeat counts as ready — a
+    // configured command or a local process does not.
+    const executorReady = readiness?.executor.ready === true;
+    deps.log("");
+    deps.log("Capability matrix");
+    deps.log("─────────────────");
+    deps.log(`  api_ready:            ${apiReady}`);
+    deps.log(`  configuration_ready:  ${configurationReady}`);
+    deps.log(`  executor_ready:       ${executorReady}`);
+    deps.log(`  executor provisioning: ${EXECUTOR_PROVISIONING_GUIDANCE}`);
+    deps.log(`  runbook:              ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}`);
+    return { apiReady, configurationReady, executorReady };
+}
+/**
+ * Run the nested conductor installer. Returns the process exit code.
+ */
+export async function runInstallBridgeConductorCli(argv, deps) {
+    const parsed = parseInstallBridgeConductorArgs(argv);
+    if (parsed.status === "help") {
+        deps.log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        deps.errorLog(`Error: ${parsed.message}`);
+        deps.errorLog("");
+        deps.errorLog(getInstallBridgeConductorUsage());
+        return 1;
+    }
+    const options = parsed.options;
+    // ---- Base URL: normalized ONCE, confirmed BEFORE any network call ------
+    const baseUrlResult = deps.resolveBaseUrl(deps.env);
+    if (!baseUrlResult.ok) {
+        deps.errorLog(baseUrlResult.error);
+        return 1;
+    }
+    const baseUrl = baseUrlResult.value;
+    // ---- Consent #1: the resolved base URL ---------------------------------
+    // This consent gates the FIRST network request of any kind — including the
+    // read-only doctor readiness GET (which carries this repository's API key)
+    // and the dry-run flow. The resolver silently defaults to production when
+    // BAPI_BASE_URL is unset, so the operator must see and confirm the target
+    // before the key is sent anywhere. No TTY means no consent means abort.
+    deps.log(`Bridge API base URL: ${baseUrl}`);
+    const baseUrlOk = await confirm(deps, "Bootstrap against this URL? [y/N]: ");
+    if (!baseUrlOk) {
+        deps.log("Aborted — no network call (readiness GET or bootstrap POST) was attempted.");
+        return 0;
+    }
+    const accessResult = await deps.resolveAccess(options.repo, baseUrl);
+    const access = accessResult.ok ? accessResult.access : null;
+    const accessError = accessResult.ok ? undefined : accessResult.error;
+    // ---- Phase 1: unified doctor, BEFORE every write -----------------------
+    deps.log("Phase 1/5 — running the unified conductor doctor (read-only)…");
+    const firstReport = await deps.runDoctor({
+        access,
+        accessError,
+        reviewPolicySource: options.reviewPolicy,
+    });
+    deps.log(formatConductorInstallDoctorReport(firstReport));
+    if (conductorInstallDoctorHasFatal(firstReport)) {
+        deps.errorLog("");
+        deps.errorLog("Fatal prerequisite(s) above. Aborting before any write — no bootstrap, workflow, " +
+            "install-state, or verification step was attempted.");
+        return 1;
+    }
+    // ---- Review policy: per-run, explicitly NOT a repository default -------
+    deps.log("");
+    deps.log(`Review policy (per-run): ${options.reviewPolicy}`);
+    deps.log("  This selection applies to runs created with it. Repository-level review-policy " +
+        "defaults are not stored yet — that is BAPI-694.");
+    // ---- Dry run: preview and RETURN before every write/prompt -------------
+    if (options.dryRun) {
+        deps.log("");
+        deps.log("Dry run — no writes will be performed.");
+        deps.log("  Would POST /jira/epic-runs/supervisor-bootstrap with field NAMES:");
+        // Field NAMES and a COUNT only — never the check values, which are
+        // configuration content, and never the API key.
+        deps.log("    - done_gate_config.required_checks " +
+            `(${options.requiredChecks.length} check(s))`);
+        deps.log("    - review_source");
+        deps.log("    - auto_merge_enabled");
+        deps.log("    - merge_approval_required");
+        deps.log(`  Would target base URL: ${baseUrl}`);
+        deps.log(options.skipWorkflow || options.reviewPolicy !== "verdict_protocol"
+            ? "  Workflow scaffold: skipped (not applicable for this policy)"
+            : `  Workflow scaffold target: ${CLAUDE_REVIEW_WORKFLOW_RELPATH}`);
+        deps.log(options.epicKey && options.planFile
+            ? `  Would verify with: setup-epic --dry-run --epic-key ${options.epicKey}`
+            : "  setup-epic verification: skipped (no --epic-key/--plan-file supplied)");
+        renderCapabilityMatrix(deps, firstReport.readiness);
+        deps.log("");
+        deps.log("complete-with-manual-steps (dry run)");
+        return 0;
+    }
+    // ---- Consent #2: the bootstrap write itself ----------------------------
+    // Deliberately separate from the base-URL consent above (which was given
+    // before any network call). Confirming WHERE to write is not consent TO write.
+    deps.log("");
+    const bootstrapOk = await confirm(deps, "Write the safe project-default supervisor posture now? [y/N]: ");
+    if (!bootstrapOk) {
+        deps.log("Aborted — no server write was attempted.");
+        return 0;
+    }
+    if (!access) {
+        // Unreachable in practice (a null access produces a fatal doctor section
+        // above), but the type must be narrowed before the POST.
+        deps.errorLog("Bridge API access could not be resolved; aborting before the write.");
+        return 1;
+    }
+    // ---- Phase 2: bootstrap ------------------------------------------------
+    deps.log("");
+    deps.log("Phase 2/5 — bootstrapping supervisor project defaults…");
+    let bootstrapResponse;
+    try {
+        bootstrapResponse = await bootstrapConductorSupervisorDefaults(access, {
+            required_checks: options.requiredChecks,
+            review_source: "verdict_protocol",
+            merge_approval_required: "true",
+        }, deps.postJson);
+    }
+    catch (err) {
+        const kind = err instanceof ConductorBridgeApiError ? err.kind : "network";
+        deps.errorLog(`Bootstrap failed (${kind}). No workflow or verification step was run.`);
+        return 1;
+    }
+    deps.log(`  wrote supervisor setup + config (fields: ${bootstrapResponse.audited_field_names.join(", ")})`);
+    // ---- Phase 3: optional workflow scaffold -------------------------------
+    deps.log("");
+    deps.log("Phase 3/5 — claude-review workflow…");
+    if (options.skipWorkflow || options.reviewPolicy !== "verdict_protocol") {
+        deps.log(`  skipped — the '${options.reviewPolicy}' review policy does not consume the ` +
+            "sticky verdict this workflow emits.");
+    }
+    else if (!options.allowedBot || !options.secretName || !options.branches) {
+        deps.log("  skipped — --allowed-bot, --secret-name, and --branches are required to render " +
+            "the workflow template.");
+    }
+    else {
+        const wantWorkflow = await confirm(deps, `Write ${CLAUDE_REVIEW_WORKFLOW_RELPATH}? [y/N]: `);
+        if (!wantWorkflow) {
+            deps.log("  declined — no file was written.");
+        }
+        else {
+            let content;
+            try {
+                content = renderClaudeReviewWorkflow({
+                    allowedBot: options.allowedBot,
+                    secretName: options.secretName,
+                    branches: options.branches,
+                });
+            }
+            catch (err) {
+                deps.errorLog(`  workflow parameters rejected: ${err instanceof Error ? err.message : "invalid"}`);
+                return 1;
+            }
+            let result = await deps.writeWorkflow(deps.cwd, content, {});
+            if (result.ok && result.outcome === "skipped") {
+                // A DIFFERENT file already exists. Overwriting review automation needs
+                // its own decision — never inferred from the earlier consents.
+                const overwrite = await confirm(deps, `${CLAUDE_REVIEW_WORKFLOW_RELPATH} exists and differs. Overwrite? [y/N]: `);
+                if (!overwrite) {
+                    deps.log("  existing workflow left untouched.");
+                }
+                else {
+                    result = await deps.writeWorkflow(deps.cwd, content, { overwriteConsent: true });
+                }
+            }
+            if (!result.ok) {
+                deps.errorLog(`  workflow write failed: ${result.error}`);
+                return 1;
+            }
+            if (result.outcome === "written") {
+                deps.log(`  wrote ${CLAUDE_REVIEW_WORKFLOW_RELPATH}`);
+                const recorded = await deps.recordArtifact(deps.cwd, CLAUDE_REVIEW_WORKFLOW_RELPATH);
+                if (!recorded.ok) {
+                    // Advisory: install-state is a diagnostic aid, not a correctness
+                    // dependency, so a failure here warns rather than failing the run.
+                    deps.errorLog(`  note: install-state not updated (${recorded.error ?? "unknown"})`);
+                }
+            }
+            else if (result.outcome === "unchanged") {
+                deps.log(`  ${CLAUDE_REVIEW_WORKFLOW_RELPATH} already matches — nothing written.`);
+            }
+        }
+    }
+    // ---- Phase 4: capability matrix from POST-bootstrap readiness ----------
+    deps.log("");
+    deps.log("Phase 4/5 — capability report…");
+    let postReadiness = null;
+    try {
+        postReadiness = await fetchConductorReadiness(access, deps.fetchJson);
+    }
+    catch {
+        // Degraded, not fatal: the write already succeeded, and the matrix simply
+        // reports what it can observe.
+        deps.errorLog("  readiness could not be re-read; capability matrix is best-effort.");
+    }
+    const matrix = renderCapabilityMatrix(deps, postReadiness);
+    // ---- setup-epic verification (conditional) -----------------------------
+    // `parseSetupEpicArgs` hard-requires --epic-key AND --plan-file before any
+    // dry-run branch, so this phase can only run when both are supplied. Fresh
+    // repositories skip it with an explicit message rather than hard-failing.
+    if (options.epicKey && options.planFile) {
+        deps.log("");
+        deps.log("  verifying with `setup-epic --dry-run`…");
+        const verification = await deps.runSetupEpicDryRun([
+            "--dry-run",
+            "--epic-key",
+            options.epicKey,
+            "--plan-file",
+            options.planFile,
+            // The SELECTED per-run policy is forwarded so the verification exercises
+            // the same policy a real run would use — including its conflict guard.
+            "--review-policy",
+            options.reviewPolicy,
+            ...(options.repo ? ["--repo", options.repo] : []),
+        ]);
+        if (verification.exitCode !== 0) {
+            deps.errorLog("  setup-epic verification failed.");
+            return 1;
+        }
+        deps.log("  setup-epic verification passed.");
+    }
+    else {
+        deps.log("");
+        deps.log("  setup-epic verification skipped — pass --epic-key and --plan-file once a plan exists.");
+    }
+    // ---- Phase 5: final doctor ---------------------------------------------
+    deps.log("");
+    deps.log("Phase 5/5 — re-running the unified conductor doctor (read-only)…");
+    const finalReport = await deps.runDoctor({
+        access,
+        reviewPolicySource: options.reviewPolicy,
+    });
+    deps.log(formatConductorInstallDoctorReport(finalReport));
+    deps.log("");
+    // The executor leg can only be true when the server observed a recent claim,
+    // so a bootstrap alone can never print `complete`.
+    const allReady = matrix.apiReady && matrix.configurationReady && matrix.executorReady;
+    deps.log(allReady ? "complete" : "complete-with-manual-steps");
+    return conductorInstallDoctorExitCode(finalReport);
+}