@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/install-bridge-conductor.js

@@ -23,9 +23,13 @@
  *    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.
+ * 3. **One consent per write surface.** Confirming the resolved base URL is NOT
+ *    consent to write; consent to overwrite a workflow file is not consent to
+ *    edit host MCP configuration; and neither is consent to install Git hooks.
+ *    The rule is per-SURFACE, not a fixed count — BAPI-775 added two more write
+ *    surfaces (host MCP configs, managed Git hooks) and each asks for itself, so
+ *    counting consents was never the invariant. A missing prompt seam (no TTY)
+ *    is a decline everywhere, never a default-yes.
  * 4. **The executor leg is never claimed as provisioned by local success.**
  *    AMENDED BY BAPI-779 (R-1): this command can now write the service unit
  *    *and* start it. What did not change — and must not — is where readiness
@@ -36,6 +40,20 @@
  *    otherwise. Local lifecycle success and server observation are reported as
  *    two separate facts, and the second is never derived from the first.
  *
+ * The two local out-of-the-box phases (BAPI-775) run between the workflow
+ * scaffold and setup-epic verification, each behind its own consent:
+ *
+ *   tool visibility — merge the `conductor` token into EXISTING supported host
+ *     MCP entries (`.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json` only,
+ *     never Codex or Copilot), then print the restart advisory, because
+ *     `ACTIVE_GROUPS` is frozen at MCP server startup.
+ *   local observability — install the managed conductor Git hooks, then report
+ *     native ledger loadability. The ledger probe is READ-ONLY, so it needs no
+ *     consent and runs whether hook consent was accepted or declined.
+ *
+ * Neither can produce `complete`: they provision LOCAL capability, and the
+ * terminal outcome still turns only on the live server-observed executor claim.
+ *
  * The executor phase (BAPI-779) is opt-in via `--executor-id` and runs behind
  * TWO independent consents, per property 3: writing the unit is not consent to
  * start a persistent daemon. Its shape is:
@@ -57,6 +75,9 @@
  */
 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 { describeNativeLedgerAvailability, } from "./conductor/doctor.js";
+import { CONDUCTOR_BIN_UNRESOLVED_ERROR, MANAGED_HOOK_NAMES, } from "./conductor/git-hooks.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 import { CLAUDE_REVIEW_WORKFLOW_RELPATH, renderClaudeReviewWorkflow, } from "./claude-review-workflow.js";
 import { formatExecutorInstallPreflight, } from "./executor/install-preflight.js";
 import { buildExecutorServiceStartPlan, formatExecutorServiceStartFailure, } from "./executor/service-lifecycle.js";
@@ -101,9 +122,11 @@ export function getInstallBridgeConductorUsage() {
         "  --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,",
-        "                             no service-unit write, no launchctl/systemctl",
-        "                             command, and no write- or start-consent prompt.",
+        "                             no POST, no file write, no host MCP config write,",
+        "                             no Git hook write, no install-state or capability",
+        "                             write, no service-unit write, no launchctl/systemctl",
+        "                             or other lifecycle command, and no write- or",
+        "                             start-consent prompt.",
         "                             Still asks the base-URL confirmation below first —",
         "                             its doctor readiness GET carries the repo API key.",
         "  -h, --help                 Show this help",
@@ -113,6 +136,22 @@ export function getInstallBridgeConductorUsage() {
         "production when unset). The bootstrap POST then asks its own, separate write",
         "consent. Without a TTY there is no consent, so the command aborts.",
         "",
+        "Tool visibility (its own consent): adds the `conductor` token to the",
+        "BRIDGE_MCP_PROFILE of the Bridge entry in host MCP configurations that",
+        "ALREADY have one. Automatic merging covers .mcp.json, .vscode/mcp.json, and",
+        ".cursor/mcp.json only — never Codex or Copilot, which are neither inspected",
+        "nor changed. No file is ever created: when no supported config carries a",
+        "a Bridge entry, the run says so and points at the base `install` command.",
+        "The MCP server captures its active groups at startup, so a merge activates on",
+        "the next launch — restart your MCP client to see the conductor tools.",
+        "",
+        "Local observability (a SEPARATE consent): installs or updates this",
+        "repository's managed conductor Git hooks (post-commit,",
+        "reference-transaction) and reports each hook's action. It then probes native",
+        "ledger loadability, which is READ-ONLY and therefore runs with or without",
+        "hook consent; a degraded ledger reports the module, NODE_MODULE_VERSION, and",
+        "failure kind, and never triggers an install, rebuild, or migration.",
+        "",
         "Executor provisioning: `executor install-service` still generates a unit and",
         "nothing else, and remains available for operators who want the file only.",
         "",
@@ -503,6 +542,216 @@ async function runExecutorProvisioningPhase(deps, executor, plans, access) {
     deps.log("  executor_ready is NOT claimed — only a live server observation can produce it.");
     return null;
 }
+// ---------------------------------------------------------------------------
+// Local out-of-the-box phases (BAPI-775)
+// ---------------------------------------------------------------------------
+/**
+ * The exact restart advisory the SFCC profile merge prints (`index.ts`), reused
+ * verbatim in shape for the conductor token.
+ *
+ * `ACTIVE_GROUPS` is frozen when the MCP server process starts, so a merged
+ * profile changes nothing about the session that is already running. Printing
+ * this after EVERY non-empty merge — including an idempotent one where the token
+ * was already present — is deliberate: an operator whose second run silently
+ * said nothing would reasonably conclude the tools were already visible.
+ */
+export function formatConductorRestartAdvisory(mergedProfile) {
+    return (`⚠️  Conductor profile updated: BRIDGE_MCP_PROFILE is now set to \`${mergedProfile}\` ` +
+        "in your local MCP config file(s). The running MCP server captured its active groups " +
+        "at startup, so this activates on the next MCP server launch — restart your MCP " +
+        "client to gain access to the conductor tools.");
+}
+/** Remediation printed when no supported host config carries a Bridge entry. */
+export const CONDUCTOR_PROFILE_EMPTY_MERGE_REMEDIATION = `run \`npx ${MCP_PACKAGE_NAME} install\` to create and register the host MCP entry, ` +
+    "then re-run `install conductor`.";
+/** Remediation printed whenever the managed conductor hooks were not installed. */
+export const CONDUCTOR_HOOKS_MANUAL_REMEDIATION = "re-run `install conductor` and accept the local-observability consent, or run " +
+    "`conductor install-git-hooks` directly.";
+/**
+ * Phase: tool visibility.
+ *
+ * Adds the `conductor` token to EXISTING supported host MCP entries behind its
+ * own consent, then prints the restart advisory. It never creates a host config
+ * — the merge helper's never-create rule is what keeps a declined or
+ * unconfigured repository from acquiring files it did not ask for.
+ */
+async function runConductorToolVisibilityPhase(deps, local) {
+    const consented = await confirm(deps, "Update existing supported host MCP configurations (.mcp.json, .vscode/mcp.json, " +
+        ".cursor/mcp.json) to add the `conductor` profile? [y/N]: ");
+    if (!consented) {
+        deps.log("  declined — no host MCP configuration and no install state were written.");
+        return {
+            manualActions: [
+                "tool visibility: re-run `install conductor` and accept the profile consent to " +
+                    "make the conductor MCP tools visible.",
+            ],
+        };
+    }
+    let mergedProfile;
+    try {
+        mergedProfile = await local.mergeProfileToken();
+    }
+    catch {
+        // The thrown value is discarded: it can carry an absolute config path.
+        deps.errorLog("  the host MCP profile could not be updated.");
+        return { manualActions: [], fatal: true };
+    }
+    if (mergedProfile === "") {
+        deps.log("  no supported host MCP configuration carries a Bridge entry, so nothing " +
+            "was written (this command never creates one).");
+        return {
+            manualActions: [
+                `tool visibility: ${CONDUCTOR_PROFILE_EMPTY_MERGE_REMEDIATION}`,
+            ],
+        };
+    }
+    // Which configs actually carry the token now. Derived from the READ-ONLY
+    // inspector rather than guessed from the merged profile string, which says
+    // nothing about which files it came from.
+    let carrying = [];
+    try {
+        const inspection = await local.inspectProfileToken();
+        carrying = inspection.configs
+            .filter((c) => c.state === "token-present")
+            .map((c) => c.path);
+    }
+    catch {
+        // A failed read-back is not a failed merge. The advisory below still prints.
+    }
+    deps.log(carrying.length > 0
+        ? `  updated: ${carrying.join(", ")}`
+        : "  the conductor profile was merged into your supported host MCP config(s).");
+    // Coverage honesty: the merge path writes these three files and no others.
+    deps.log("  Codex and Copilot host configuration was NOT inspected or changed.");
+    deps.log(`  ${formatConductorRestartAdvisory(mergedProfile)}`);
+    const recorded = await local.recordCapability("conductor_tool_visibility");
+    if (!recorded.ok) {
+        // Advisory: install state is a diagnostic aid. A recording failure does not
+        // invalidate the host-config change that just landed.
+        deps.errorLog(`  note: install-state not updated (${recorded.error ?? "unknown"})`);
+    }
+    return { manualActions: [] };
+}
+/**
+ * Phase: local observability.
+ *
+ * Installs the managed conductor Git hooks behind its OWN consent — never
+ * inferred from the base-URL, bootstrap, workflow, profile-token, or executor
+ * consents — and then always reports native ledger loadability, which is
+ * read-only and therefore needs no consent at all.
+ */
+async function runConductorLocalObservabilityPhase(deps, local) {
+    const manualActions = [];
+    let fatal = false;
+    const consented = await confirm(deps, "Install or update this repository's managed conductor Git hooks " +
+        "(post-commit, reference-transaction)? [y/N]: ");
+    if (!consented) {
+        deps.log("  declined — no Git hook and no install state were written.");
+        manualActions.push(`local observability: ${CONDUCTOR_HOOKS_MANUAL_REMEDIATION}`);
+    }
+    else {
+        let result = null;
+        try {
+            result = await local.installGitHooks();
+        }
+        catch {
+            // Generic by design: the caught value can carry a hooks-directory path.
+            // The phase is marked fatal but does NOT return here — the read-only
+            // ledger report below still owes the operator its answer.
+            deps.errorLog("  the conductor Git hooks could not be installed.");
+            manualActions.push(`local observability: ${CONDUCTOR_HOOKS_MANUAL_REMEDIATION}`);
+            fatal = true;
+        }
+        if (result !== null && !result.ok) {
+            // BAPI-772's fail-loud case: nothing was created, merged, or chmodded, and
+            // `reason` is already a sanitized sentence. This one IS a command failure —
+            // a hook that cannot resolve its binary is a dead hook, and the whole point
+            // of that ticket is that it no longer gets written silently.
+            deps.errorLog(result.error === CONDUCTOR_BIN_UNRESOLVED_ERROR
+                ? `  hook installation refused — ${result.reason}`
+                : "  hook installation refused.");
+            manualActions.push(`local observability: ${CONDUCTOR_HOOKS_MANUAL_REMEDIATION}`);
+            fatal = true;
+        }
+        else if (result !== null && result.ok) {
+            if (!result.is_worktree) {
+                deps.log("  not a git worktree, so no managed hook was installed (degraded optional capability).");
+                manualActions.push("local observability: run `install conductor` from a git worktree to install the " +
+                    "managed conductor hooks.");
+            }
+            else {
+                for (const hook of result.installed) {
+                    // The per-hook warning is rendered beside its action, not merely
+                    // counted: a hook reported as `created` while carrying "could not
+                    // chmod +x" reads as provisioned unless the warning is visible, and
+                    // that warning is exactly what makes it unusable.
+                    deps.log(hook.warning === undefined
+                        ? `  ${hook.name}: ${hook.action}`
+                        : `  ${hook.name}: ${hook.action} — warning: ${hook.warning}`);
+                }
+                // Sanitized: the installer's own warnings are secret-free sentences, and
+                // hook CONTENT, env, and caught errors are never rendered.
+                for (const warning of result.warnings)
+                    deps.log(`  warning: ${warning}`);
+                // Completeness is checked against the managed-hook ROSTER, not against
+                // "at least one hook was installed": a partial install that wrote only
+                // post-commit and warned about nothing would otherwise be recorded as
+                // provisioned observability, and the missing reference-transaction hook
+                // is precisely the one that stops half the events from ever being
+                // emitted.
+                const usable = (name) => {
+                    const hook = result.installed.find((h) => h.name === name);
+                    return hook !== undefined && hook.action !== "skipped" && hook.warning === undefined;
+                };
+                const complete = MANAGED_HOOK_NAMES.every((name) => usable(name)) && result.warnings.length === 0;
+                if (complete) {
+                    const recorded = await local.recordCapability("conductor_local_observability");
+                    if (!recorded.ok) {
+                        deps.errorLog(`  note: install-state not updated (${recorded.error ?? "unknown"})`);
+                    }
+                }
+                else {
+                    // A skipped or warned hook is NOT provisioned local observability, and
+                    // recording the capability here would make install state claim
+                    // something a `conductor doctor` run would immediately contradict.
+                    deps.log("  the managed hooks are not fully usable, so local observability was not recorded.");
+                    manualActions.push(`local observability: ${CONDUCTOR_HOOKS_MANUAL_REMEDIATION}`);
+                }
+            }
+        }
+    }
+    // The ledger probe runs whether hook consent was accepted or DECLINED: it is
+    // strictly read-only, so it needs no consent, and its result is exactly what
+    // an operator needs to know before a hook can produce an event. It also runs
+    // before any fail-loud return below, so a hook-binary refusal never costs the
+    // operator this diagnostic.
+    let inspection = null;
+    try {
+        inspection = await local.probeNativeLedger();
+    }
+    catch {
+        inspection = null;
+    }
+    if (inspection === null) {
+        deps.log("  ledger loadability could not be probed on this host.");
+    }
+    else {
+        const availability = describeNativeLedgerAvailability(inspection);
+        if (availability.status === "available") {
+            deps.log("  ledger available — the native binding loads.");
+        }
+        else {
+            // Never fatal, and never an install/rebuild/migration attempt: the module,
+            // ABI, and sanitized failure kind are what make an npm optional-dependency
+            // build skip diagnosable.
+            deps.log(`  ledger degraded — ${availability.module} did not load ` +
+                `(NODE_MODULE_VERSION ${availability.nodeModulesAbi}, failure: ${availability.failureKind}).`);
+            manualActions.push(`local observability: reinstall ${availability.module} for this Node runtime to ` +
+                "restore the local conductor event ledger.");
+        }
+    }
+    return { manualActions, fatal };
+}
 /**
  * Run the nested conductor installer. Returns the process exit code.
  */
@@ -542,7 +791,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     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/6 — running the unified conductor doctor (read-only)…");
+    deps.log("Phase 1/8 — running the unified conductor doctor (read-only)…");
     const firstReport = await deps.runDoctor({
         access,
         accessError,
@@ -571,6 +820,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     // effect — provisioning a service that cannot run is worse than refusing —
     // and before the dry-run return, so `--dry-run` reports the same refusal.
     const executor = deps.executorProvisioning;
+    const local = deps.localProvisioning;
     const executorRequested = Boolean(executor && options.executorId);
     let executorPlans = null;
     if (executor && executorRequested) {
@@ -638,6 +888,18 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         // would actually happen. Still zero writes: no unit writer, no
         // install-state recorder, no lifecycle runner, and no consent prompt has
         // been reached on this branch.
+        // BAPI-775: named as SEPARATE consents so the preview cannot read as one
+        // blanket approval. Nothing below this line invokes the profile merger, the
+        // hook installer, the capability recorder, or the phase's ledger probe —
+        // this branch returns before every one of them.
+        deps.log(local
+            ? "  Tool visibility: would ask its OWN consent before adding the `conductor` " +
+                "profile to existing .mcp.json / .vscode/mcp.json / .cursor/mcp.json entries."
+            : "  Tool visibility: skipped (this caller supplied no local-provisioning seams)");
+        deps.log(local
+            ? "  Local observability: would ask a SEPARATE consent before installing the " +
+                "managed conductor Git hooks; the ledger probe is read-only."
+            : "  Local observability: skipped (this caller supplied no local-provisioning seams)");
         if (executorPlans) {
             deps.log(`  Would write executor unit: ${executorPlans.install.unitPath}`);
             deps.log(`  Would start it with:       ${executorPlans.start.manualCommand}`);
@@ -668,7 +930,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     }
     // ---- Phase 2: bootstrap ------------------------------------------------
     deps.log("");
-    deps.log("Phase 2/6 — bootstrapping supervisor project defaults…");
+    deps.log("Phase 2/8 — bootstrapping supervisor project defaults…");
     let bootstrapResponse;
     try {
         bootstrapResponse = await bootstrapConductorSupervisorDefaults(access, {
@@ -692,7 +954,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     deps.log(`  wrote supervisor setup + config (fields: ${bootstrapResponse.audited_field_names.join(", ")})`);
     // ---- Phase 3: optional workflow scaffold -------------------------------
     deps.log("");
-    deps.log("Phase 3/6 — claude-review workflow…");
+    deps.log("Phase 3/8 — 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.");
@@ -749,12 +1011,47 @@ export async function runInstallBridgeConductorCli(argv, deps) {
             }
         }
     }
-    // ---- Phase 4: setup-epic verification (conditional) --------------------
+    // ---- Phases 4 + 5: local out-of-the-box provisioning (BAPI-775) --------
+    // Placed after the workflow scaffold and BEFORE setup-epic verification,
+    // executor provisioning, and the capability report, so a run that stops at a
+    // later phase has still closed the local gap it consented to close.
+    const manualActions = [];
+    deps.log("");
+    deps.log("Phase 4/8 — conductor tool visibility…");
+    if (local) {
+        const outcome = await runConductorToolVisibilityPhase(deps, local);
+        manualActions.push(...outcome.manualActions);
+        if (outcome.fatal)
+            return 1;
+    }
+    else {
+        deps.log("  skipped — this caller supplied no local-provisioning seams.");
+        manualActions.push("tool visibility: run the packaged `install conductor` command to add the " +
+            "`conductor` profile to your host MCP configuration.");
+    }
+    deps.log("");
+    deps.log("Phase 5/8 — conductor local observability…");
+    let observabilityFatal = false;
+    if (local) {
+        const outcome = await runConductorLocalObservabilityPhase(deps, local);
+        manualActions.push(...outcome.manualActions);
+        observabilityFatal = outcome.fatal === true;
+    }
+    else {
+        deps.log("  skipped — this caller supplied no local-provisioning seams.");
+        manualActions.push("local observability: run the packaged `install conductor` command, or " +
+            "`conductor install-git-hooks`, to install the managed conductor Git hooks.");
+    }
+    // The fail-loud hook-binary refusal exits 1 — but only AFTER the phase's
+    // read-only ledger report has been printed, which the phase guarantees.
+    if (observabilityFatal)
+        return 1;
+    // ---- Phase 6: 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.
     deps.log("");
-    deps.log("Phase 4/6 — setup-epic verification…");
+    deps.log("Phase 6/8 — setup-epic verification…");
     if (options.epicKey && options.planFile) {
         deps.log("  verifying with `setup-epic --dry-run`…");
         const verification = await deps.runSetupEpicDryRun([
@@ -783,7 +1080,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     // started daemon behind, and BEFORE the capability report so the matrix can
     // use the readiness this phase actually observed.
     deps.log("");
-    deps.log("Phase 5/6 — executor provisioning…");
+    deps.log("Phase 7/8 — executor provisioning…");
     let observedReadiness = null;
     if (executor && executorPlans) {
         observedReadiness = await runExecutorProvisioningPhase(deps, executor, executorPlans, access);
@@ -796,7 +1093,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     }
     // ---- Phase 6: capability matrix + final doctor -------------------------
     deps.log("");
-    deps.log("Phase 6/6 — capability report…");
+    deps.log("Phase 8/8 — capability report…");
     // The observed payload WINS when the executor phase actually saw the server
     // report readiness. Otherwise the matrix re-reads readiness itself — it is
     // never handed a synthesized response, so `executor_ready` still originates
@@ -820,9 +1117,21 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         reviewPolicySource: options.reviewPolicy,
     });
     deps.log(formatConductorInstallDoctorReport(finalReport));
+    // Manual actions (BAPI-775): every declined, unavailable, empty, or incomplete
+    // local phase leaves a pointer here. Collected in one place because an
+    // operator who scrolled past a phase still needs to know what is outstanding.
+    if (manualActions.length > 0) {
+        deps.log("");
+        deps.log("Manual actions");
+        deps.log("──────────────");
+        for (const action of manualActions)
+            deps.log(`  → ${action}`);
+    }
     deps.log("");
     // The executor leg can only be true when the server observed a recent claim,
-    // so a bootstrap alone can never print `complete`.
+    // so a bootstrap alone can never print `complete`. The two local phases above
+    // deliberately do NOT feed this predicate: local provisioning cannot
+    // manufacture `complete`, and the terminal outcome is unchanged by BAPI-775.
     const allReady = matrix.apiReady && matrix.configurationReady && matrix.executorReady;
     deps.log(allReady ? "complete" : "complete-with-manual-steps");
     return conductorInstallDoctorExitCode(finalReport);