@bridge_gpt/mcp-server 0.2.33 → 0.2.36

package/build/conductor/install-doctor.js

@@ -0,0 +1,462 @@
+/**
+ * Unified conductor install doctor (BAPI-679).
+ *
+ * Three read-only diagnostics already exist and each answers part of "is the
+ * conductor installed correctly": `buildConductorDoctorReport` (local ledger,
+ * hooks, schedule), `collectExecutorPreflight` (local executor tooling), and
+ * `collectInstallStatusChecks` (Bridge install status). None of them can see
+ * SERVER-side conductor state, because the CLI holds neither Postgres access nor
+ * the GitHub App token. This module composes all three with the server readiness
+ * endpoint — plus the read-only BAPI-688 executor service-unit diagnostics
+ * (`collectExecutorServiceDiagnostics`) — so one command reports every gap.
+ *
+ * COMPOSITION, NOT MERGING. Each existing builder's report object is stored
+ * verbatim in its own field and rendered by its own formatter. Nothing here
+ * mutates, rewrites, reclassifies, or drops a legacy finding — three reports plus
+ * a set of new named sections, never one flattened schema. That keeps this module
+ * additive: a change to any legacy builder cannot silently alter what the unified
+ * doctor reports about it.
+ *
+ * STRICTLY READ-ONLY. No POST, no filesystem write, no install-state write, no
+ * workflow scaffold, no schema migration, no hook installation. It is invoked
+ * from a write-capable installer, so that boundary is pinned by tests.
+ */
+import { readdir as fsReaddir, readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import os from "node:os";
+import { buildConductorDoctorReport, formatConductorDoctorReport, } from "./doctor.js";
+import { collectExecutorServiceDiagnostics, formatExecutorServiceDiagnosticsReport, } from "../doctor.js";
+import { collectInstallStatusChecks, formatInstallStatusReport, } from "../install-doctor.js";
+import { ConductorBridgeApiError, fetchConductorReadiness, } from "./bridge-api-client.js";
+/** Operator runbook pointer surfaced beside the executor gap. */
+export const CONDUCTOR_OPERATOR_RUNBOOK_POINTER = "docs/claude/epic-conductor-v2-operator-runbook.md";
+/**
+ * Capability-matrix guidance for the executor leg (BAPI-688 shipped in the same
+ * build as BAPI-679): a persistent unit is *generated* by `executor
+ * install-service`, but starting/stopping it stays operator-managed, so the
+ * executor is never claimed as provisioned by a bootstrap alone.
+ */
+export const EXECUTOR_PROVISIONING_GUIDANCE = "generate a unit with `executor install-service`; start/stop stays operator-managed";
+/** Remediation surfaced whenever no healthy generated service unit is detected. */
+export const EXECUTOR_INSTALL_SERVICE_REMEDIATION = "generate a persistent unit with `executor install-service` (or run the executor by hand) — " +
+    `see ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`;
+// ---------------------------------------------------------------------------
+// Section builders
+// ---------------------------------------------------------------------------
+function supervisorSection(readiness) {
+    const s = readiness.supervisor;
+    const sections = [];
+    if (!s.setup_present || !s.config_present) {
+        const missing = [
+            !s.setup_present ? "setup" : null,
+            !s.config_present ? "config" : null,
+        ].filter(Boolean).join(" and ");
+        sections.push({
+            id: "supervisor-configuration",
+            label: "Supervisor configuration",
+            status: "degraded",
+            detail: `project-default supervisor ${missing} absent`,
+            remediation: "bootstrap writes the safe project-default posture.",
+        });
+    }
+    else {
+        sections.push({
+            id: "supervisor-configuration",
+            label: "Supervisor configuration",
+            status: "ok",
+            detail: `setup=${s.setup_source}, config=${s.config_source}`,
+        });
+    }
+    // Deliberately its OWN section, not folded into the one above: "configured but
+    // unsafe" and "not configured" drive different operator actions, and an empty
+    // required-check list makes the CI gate pass unconditionally rather than fail.
+    sections.push(s.required_checks_empty
+        ? {
+            id: "supervisor-required-checks",
+            label: "Supervisor required CI checks",
+            status: "degraded",
+            detail: "required-check list is EMPTY — the done gate would pass unconditionally",
+            remediation: "bootstrap writes a non-empty required-check list into done_gate_config.",
+        }
+        : {
+            id: "supervisor-required-checks",
+            label: "Supervisor required CI checks",
+            status: "ok",
+            detail: `${s.required_checks_count} required check(s) configured`,
+        });
+    return sections;
+}
+function githubCredentialsSection(readiness) {
+    const g = readiness.github;
+    if (g.credentials_complete) {
+        return {
+            id: "github-credentials",
+            label: "GitHub App credentials",
+            status: "ok",
+            detail: "owner, repository id, and installation id all resolved",
+        };
+    }
+    const missing = [
+        !g.owner_resolved ? "owner" : null,
+        !g.repo_id_resolved ? "repository id" : null,
+        !g.installation_id_resolved ? "installation id" : null,
+    ].filter(Boolean).join(", ");
+    return {
+        id: "github-credentials",
+        label: "GitHub App credentials",
+        status: "degraded",
+        detail: g.credentials_readable
+            ? `incomplete: ${missing} unresolved`
+            : "no GitHub credential row for this repository",
+        remediation: "connect GitHub from the Bridge setup UI (`install-bridge connect-github`).",
+    };
+}
+function githubActionsSection(readiness) {
+    const g = readiness.github;
+    if (g.actions_write) {
+        return {
+            id: "github-actions-permission",
+            label: "GitHub App actions permission",
+            status: "ok",
+            detail: "actions: write",
+        };
+    }
+    if (!g.actions_probe_succeeded) {
+        // "Could not be checked" is NOT the same finding as "confirmedly missing" —
+        // the first needs a retry, the second needs a permission grant.
+        return {
+            id: "github-actions-permission",
+            label: "GitHub App actions permission",
+            status: "degraded",
+            detail: "permission could not be checked",
+            remediation: "re-run once credentials resolve; the workflow rerun lane fails open on 403 until this reads `write`.",
+        };
+    }
+    return {
+        id: "github-actions-permission",
+        label: "GitHub App actions permission",
+        status: "degraded",
+        detail: `actions: ${g.actions_permission_level}`,
+        remediation: "grant the GitHub App `actions: write`; the conductor's workflow rerun lane fails open on 403 without it.",
+    };
+}
+function reconcilerSection(readiness) {
+    const r = readiness.reconciler;
+    if (!r.liveness_readable) {
+        return {
+            id: "reconciler-liveness",
+            label: "Reconciler tick liveness",
+            status: "degraded",
+            detail: "liveness could not be read",
+        };
+    }
+    if (!r.stale) {
+        return {
+            id: "reconciler-liveness",
+            label: "Reconciler tick liveness",
+            status: "ok",
+            detail: `last tick ${r.last_tick_age_seconds}s ago across ${r.active_run_count} active run(s)`,
+        };
+    }
+    return {
+        id: "reconciler-liveness",
+        label: "Reconciler tick liveness",
+        status: "degraded",
+        detail: r.last_tick_at === null
+            ? "no reconciler tick recorded for this repository"
+            : `last tick ${r.last_tick_age_seconds}s ago (threshold ${readiness.thresholds.reconciler_stale_after_seconds}s)`,
+        remediation: "start the reconciler (`conductor epic-tick` schedule) for this repository.",
+    };
+}
+function workflowSection(presence, reviewPolicySource) {
+    if (presence === "present") {
+        return {
+            id: "claude-review-workflow",
+            label: "claude-review workflow",
+            status: "ok",
+            detail: ".github/workflows/claude-review.yml present",
+        };
+    }
+    // Applicability is policy-dependent: a run whose review signal is GitHub's own
+    // review decision does not need the Claude workflow at all, so its absence is
+    // not a gap. Reporting it as degraded there would train operators to ignore
+    // this section.
+    if (reviewPolicySource === "native_review_decision" || reviewPolicySource === "none") {
+        return {
+            id: "claude-review-workflow",
+            label: "claude-review workflow",
+            status: "ok",
+            detail: `not applicable for review policy '${reviewPolicySource}'`,
+        };
+    }
+    return {
+        id: "claude-review-workflow",
+        label: "claude-review workflow",
+        status: "degraded",
+        detail: presence === "unreadable"
+            ? ".github/workflows/claude-review.yml could not be read"
+            : ".github/workflows/claude-review.yml absent",
+        remediation: "the selected review policy consumes the sticky verdict this workflow emits; install the template.",
+    };
+}
+/**
+ * Real detection of BAPI-688 generated service units, composed from
+ * `collectExecutorServiceDiagnostics`. Never `fatal` (a missing unit is a
+ * repairable gap, and blocking every install on it would be wrong) and never
+ * omitted (the flow must not read as fully provisioned by silence). A healthy
+ * unit reports `ok` for *provisioning* only — whether the service is running is
+ * the capability matrix's `executor_ready`, observed server-side.
+ */
+function executorProvisioningSection(diagnostics) {
+    const base = { id: "executor-provisioning", label: "Executor provisioning" };
+    if (diagnostics === null) {
+        return {
+            ...base,
+            status: "degraded",
+            detail: "executor service-unit diagnostics could not be collected",
+            remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+        };
+    }
+    if (diagnostics.status === "skipped") {
+        // The collector's `reason` is already sanitized and secret-free (fixed
+        // convention paths only): "no units found", unsupported platform, or the
+        // Windows manual-Task-Scheduler case.
+        return {
+            ...base,
+            status: "degraded",
+            detail: diagnostics.reason,
+            remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+        };
+    }
+    const unhealthy = diagnostics.units.filter((unit) => unit.warnings.length > 0 || unit.credentials.some((cred) => !cred.resolved));
+    const ids = diagnostics.units.map((unit) => unit.executorId).join(", ");
+    if (unhealthy.length === 0 && diagnostics.warnings.length === 0) {
+        return {
+            ...base,
+            status: "ok",
+            detail: `${diagnostics.units.length} generated service unit(s) found (${ids}); ` +
+                "lifecycle stays operator-managed",
+        };
+    }
+    return {
+        ...base,
+        status: "degraded",
+        detail: `${diagnostics.units.length} generated service unit(s) found (${ids}), but ` +
+            `${unhealthy.length} unit(s) carry warnings or unresolved credentials — see the ` +
+            "embedded executor-provisioning report",
+        remediation: EXECUTOR_INSTALL_SERVICE_REMEDIATION,
+    };
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+async function inspectWorkflowPresence(readWorkflowFile) {
+    try {
+        await readWorkflowFile();
+        return "present";
+    }
+    catch (err) {
+        // ENOENT is the ordinary "absent" case; anything else is "unreadable". The
+        // error's message is never surfaced — it can echo an absolute path.
+        const code = err?.code;
+        return code === "ENOENT" ? "absent" : "unreadable";
+    }
+}
+/**
+ * Build the unified report. Never throws: every probe failure becomes a section.
+ */
+export async function runConductorInstallDoctor(deps) {
+    const sections = [];
+    // --- Legacy builders, composed verbatim ---------------------------------
+    const buildConductor = deps.buildConductorReport ?? buildConductorDoctorReport;
+    let legacyConductor = null;
+    try {
+        legacyConductor = await buildConductor(deps.conductorDoctorDeps);
+    }
+    catch {
+        sections.push({
+            id: "conductor-ledger",
+            label: "Conductor ledger doctor",
+            status: "degraded",
+            detail: "the local conductor doctor could not be built",
+        });
+    }
+    let legacyExecutorPreflight = null;
+    if (deps.collectExecutorPreflight) {
+        try {
+            legacyExecutorPreflight = await deps.collectExecutorPreflight();
+        }
+        catch {
+            sections.push({
+                id: "executor-preflight",
+                label: "Executor preflight",
+                status: "degraded",
+                detail: "the executor preflight could not be collected",
+            });
+        }
+    }
+    let legacyInstallChecks = null;
+    const collectInstall = deps.collectInstallChecks ??
+        (deps.installDoctorDeps
+            ? () => collectInstallStatusChecks(deps.installDoctorDeps)
+            : null);
+    if (collectInstall) {
+        try {
+            legacyInstallChecks = await collectInstall();
+        }
+        catch {
+            sections.push({
+                id: "install-status",
+                label: "Bridge install status",
+                status: "degraded",
+                detail: "the install-status checklist could not be collected",
+            });
+        }
+    }
+    // --- Server readiness ---------------------------------------------------
+    let readiness = null;
+    if (!deps.access) {
+        // No resolvable identity/credential means every server-side section below is
+        // unknowable — the operator must fix this before any of it can be judged.
+        sections.push({
+            id: "bridge-access",
+            label: "Bridge API access",
+            status: "fatal",
+            detail: deps.accessError ?? "Bridge API repository/credential could not be resolved",
+            remediation: "run `install-bridge` (or set BAPI_API_KEY) for this repository.",
+        });
+    }
+    else {
+        try {
+            readiness = await fetchConductorReadiness(deps.access, deps.fetch);
+        }
+        catch (err) {
+            const kind = err instanceof ConductorBridgeApiError ? err.kind : "network";
+            // Authentication failure and a malformed 200 are FATAL: in both cases the
+            // report cannot be trusted, and continuing would present unknown server
+            // state as healthy. A transient transport failure is degraded — the local
+            // sections are still meaningful and a retry may succeed.
+            const fatalKind = kind === "unauthorized" || kind === "invalid-input";
+            sections.push({
+                id: "server-readiness",
+                label: "Server readiness",
+                status: fatalKind ? "fatal" : "degraded",
+                detail: kind === "unauthorized"
+                    ? "Bridge API rejected the credential for this repository"
+                    : kind === "invalid-input"
+                        ? "the readiness response failed shape validation"
+                        : "the readiness endpoint could not be reached",
+                remediation: fatalKind
+                    ? "re-check the API key and repository, then re-run."
+                    : "retry; the local sections above are unaffected.",
+            });
+        }
+    }
+    if (readiness) {
+        sections.push(...supervisorSection(readiness));
+        sections.push(githubCredentialsSection(readiness));
+        sections.push(githubActionsSection(readiness));
+    }
+    const presence = await inspectWorkflowPresence(deps.readWorkflowFile);
+    sections.push(workflowSection(presence, deps.reviewPolicySource));
+    if (readiness) {
+        sections.push(reconcilerSection(readiness));
+    }
+    // --- Executor provisioning (BAPI-688): real, read-only unit detection -----
+    const collectServiceUnits = deps.collectExecutorServiceUnits ??
+        (() => collectExecutorServiceDiagnostics({
+            platform: process.platform,
+            env: process.env,
+            homedir: os.homedir,
+            readdir: (dirPath) => fsReaddir(dirPath),
+            readFile: (filePath) => fsReadFile(filePath, "utf-8"),
+            stat: (filePath) => fsStat(filePath),
+        }));
+    let executorService = null;
+    try {
+        executorService = await collectServiceUnits();
+    }
+    catch {
+        // The collector itself never throws; this guards an injected fake. The
+        // section reports the collection gap rather than losing the section.
+    }
+    sections.push(executorProvisioningSection(executorService));
+    return {
+        legacyConductor,
+        legacyExecutorPreflight,
+        legacyInstallChecks,
+        executorService,
+        readiness,
+        sections,
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatting + exit code
+// ---------------------------------------------------------------------------
+/** Status tag, matching `formatConductorDoctorReport`'s visual hierarchy. */
+function statusTag(status) {
+    if (status === "fatal")
+        return "✗ FATAL";
+    if (status === "degraded")
+        return "! DEGRADED";
+    return "✓ OK";
+}
+/**
+ * Render the unified report. The three legacy reports are EMBEDDED unchanged via
+ * their own formatters — never re-rendered from a merged schema.
+ */
+export function formatConductorInstallDoctorReport(report) {
+    const lines = [
+        "Conductor install doctor",
+        "════════════════════════",
+        "",
+    ];
+    for (const section of report.sections) {
+        lines.push(`${statusTag(section.status)}  ${section.label}`);
+        lines.push(`           ${section.detail}`);
+        if (section.remediation)
+            lines.push(`           → ${section.remediation}`);
+    }
+    // Each legacy formatter is called defensively. They are written for the exact
+    // shape their own builder returns, so a builder that degrades (or an injected
+    // fake) can make one throw — and this renderer runs inside the installer right
+    // before its write decisions, where an unhandled throw would abort the run with
+    // a raw stack instead of the report the operator needs to act on.
+    const embed = (label, render) => {
+        lines.push("");
+        try {
+            lines.push(render());
+        }
+        catch {
+            lines.push(`${label}: report could not be rendered.`);
+        }
+    };
+    if (report.legacyInstallChecks) {
+        embed("Bridge install status", () => formatInstallStatusReport(report.legacyInstallChecks));
+    }
+    if (report.legacyConductor) {
+        embed("Conductor ledger doctor", () => formatConductorDoctorReport(report.legacyConductor));
+    }
+    if (report.legacyExecutorPreflight) {
+        const p = report.legacyExecutorPreflight;
+        lines.push("");
+        lines.push("executor preflight (local)");
+        lines.push("──────────────────────────");
+        lines.push(`ok:                    ${p.ok}`);
+        for (const finding of p.fatalFindings)
+            lines.push(`  fatal: ${finding}`);
+        for (const warning of p.warnings)
+            lines.push(`  warn:  ${warning}`);
+    }
+    if (report.executorService) {
+        embed("Executor provisioning", () => formatExecutorServiceDiagnosticsReport(report.executorService));
+    }
+    return lines.join("\n");
+}
+/** `1` when any section is fatal; `0` for ok/degraded-only reports. */
+export function conductorInstallDoctorExitCode(report) {
+    return report.sections.some((s) => s.status === "fatal") ? 1 : 0;
+}
+/** True when the report has a fatal section (the pre-write abort predicate). */
+export function conductorInstallDoctorHasFatal(report) {
+    return report.sections.some((s) => s.status === "fatal");
+}