@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/upgrade-cli.js

@@ -30,9 +30,41 @@
  *
  * Every launcher claim is verified by RE-READING the configs after the write.
  * The command never reports a transition it did not confirm on disk.
+ *
+ * ---------------------------------------------------------------------------
+ * BAPI-1445 — Codex's global config
+ * ---------------------------------------------------------------------------
+ * The three project JSON configs are not the only place a Bridge pin lives:
+ * Codex keeps its registration in one per-user TOML file
+ * (`~/.codex/config.toml`, or `$CODEX_HOME/config.toml` for an absolute
+ * override). A repin that skipped it left Codex on an old server for every
+ * project on the machine. Upgrade now inspects, repins, and verifies that file
+ * too, beside the JSON targets, with these boundaries:
+ *
+ *   - Preflight refusal guarantees NO writes. An unsafe Codex file (a range, tag,
+ *     or ahead pin, a duplicate or unlocatable registration, an unreadable file)
+ *     stops the run in Phase 2, before local-install removal, `runInit`, any
+ *     config write, or the permission write.
+ *   - A failure AFTER `runInit` can leave the JSON configs upgraded. It exits
+ *     through `did NOT converge` with exit code 1 — no rollback, no automatic
+ *     retry, no completion line, and no reload guidance.
+ *   - The Codex write is one surgical splice of the package specifier, written in
+ *     place only if the file is byte-identical to what Phase 2 read. That compare
+ *     is optimistic protection, not a lock.
+ *   - Install is unchanged: it keeps its existing-table detection, its
+ *     `manual-required` outcome, and its current guidance. Upgrade adds no install
+ *     handoff and makes no repair calls. `LAUNCHER_CONFIG_TARGETS`, `runInit`,
+ *     doctor, and Phases 1, 4, and 8 are untouched.
+ *   - Windsurf is excluded by its `manual-instructions` write strategy: upgrade
+ *     never inspects or writes its file, never prints its reload guidance, and
+ *     leaves its manual setup with the operator.
+ *   - Upgrade-notice delivery is a separate concern. The one thing this file does
+ *     for it (BAPI-1446) is Phase 8's advisory SessionStart hook request, for a
+ *     Claude Code installation only, pinned to the converged target version.
  */
 import { spawn } from "child_process";
 import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import os from "os";
 import path from "path";
 import { VERSION } from "./version.generated.js";
 import { runInit } from "./init.js";
@@ -40,15 +72,18 @@ import { InitPreflightError } from "./init.js";
 import { isNewerVersion } from "./update-check.js";
 import { fetchLatestVersion } from "./cli-release.js";
 import { CANONICAL_UPGRADE_COMMAND } from "./upgrade-advice.js";
-import { describeLauncherReason, inspectLauncherConfigs, isApplicableStandardLauncher, isPrerequisiteFailure, LAUNCHER_CONFIG_TARGETS, } from "./launcher-config-inspection.js";
+import { applyCodexRepin, inspectCodexLauncher } from "./codex-launcher-pin.js";
+import { describeLauncherReason, inspectGlobalLauncherConfigs, inspectLauncherConfigs, isApplicableStandardLauncher, isPrerequisiteFailure, LAUNCHER_CONFIG_TARGETS, resolveCodexConfigLocation, } from "./launcher-config-inspection.js";
+import { allHostTargets, HOST_PLATFORM_ORDER, MCP_HOST_TARGETS, } from "./mcp-host-targets.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
-import { applyProjectPermissions, BRIDGE_PERMISSIONS_MANIFEST_RELPATH, BRIDGE_PROJECT_SETTINGS_RELPATH, } from "./bridge-permissions.js";
+import { applyProjectPermissions, BRIDGE_PERMISSIONS_MANIFEST_RELPATH, BRIDGE_PROJECT_SETTINGS_RELPATH, describeSessionStartHookOutcome, } from "./bridge-permissions.js";
+import { readMcpInstallState } from "./mcp-install-state.js";
 import { ensureGitignored } from "./git-ignore-utils.js";
 import { defaultNpmEntryFileExists, resolveNpmEntry } from "./windows-npm-entry.js";
 /** The sentinel this CLI passes to the child it re-execs from `@latest`. */
 const INTERNAL_REEXEC_FLAG = "--internal-reexec";
 /** Production binding of {@link UpgradeCliDeps.applyBridgePermissions}. */
-export async function defaultApplyBridgePermissions(cwd, env) {
+export async function defaultApplyBridgePermissions(cwd, env, sessionStartHook) {
     const fsDeps = {
         readFile: (filePath) => readFile(filePath, "utf-8"),
         writeFile: (filePath, data) => writeFile(filePath, data, "utf-8"),
@@ -62,7 +97,22 @@ export async function defaultApplyBridgePermissions(cwd, env) {
             // Advisory: the files are still written, and doctor reads them either way.
         }
     }
-    return applyProjectPermissions({ cwd, env }, fsDeps);
+    return applyProjectPermissions({ cwd, env, sessionStartHook }, fsDeps);
+}
+/**
+ * Is this a Claude Code installation? Answered from the install state `install`
+ * recorded, not from a bare `.mcp.json`: that file is also written for other hosts
+ * and by hand, so its presence proves nothing about Claude Code. A missing,
+ * invalid, or unreadable state is "no", so the hook is never written on a guess.
+ */
+async function isClaudeCodeInstallation(deps) {
+    try {
+        const state = await readMcpInstallState(deps.cwd, { readFile: deps.readFile });
+        return state.status === "valid" && state.state.selectedPlatforms.includes("claude-code");
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * The fixed, secret-free message printed when, on Windows, the latest CLI could
@@ -198,6 +248,10 @@ export function createDefaultUpgradeCliDeps(cwd) {
         cwd,
         fetchLatestVersion,
         readFile: (filePath) => readFile(filePath, "utf-8"),
+        // In place on purpose: writing through the existing file keeps its mode, owner,
+        // and symlink behavior, none of which a rename-based write would preserve.
+        writeFile: (filePath, content) => writeFile(filePath, content, "utf-8"),
+        homedir: () => os.homedir(),
         hasCompetingLocalInstall: defaultHasCompetingLocalInstall,
         removeCompetingLocalInstall: (installCwd) => defaultRemoveCompetingLocalInstall(installCwd),
         runInit,
@@ -316,6 +370,177 @@ export function isEveryLauncherAlreadyCurrent(actions) {
     return applicable.every((a) => a.kind === "already-current");
 }
 // ---------------------------------------------------------------------------
+// Global (Codex) config — BAPI-1445
+// ---------------------------------------------------------------------------
+/** The label that tells a reader this config is machine-wide, not per-project. */
+const GLOBAL_SCOPE_LABEL = "global — applies to every project on this machine";
+/** The path-plus-scope label a global config line carries before its colon. */
+function globalConfigLabel(displayPath) {
+    return `${displayPath} (${GLOBAL_SCOPE_LABEL})`;
+}
+/**
+ * Project a global inspection onto the project-inspection shape so the report
+ * helpers reuse the existing transition, current, normalization, and shim wording
+ * rather than growing a second set that could drift.
+ */
+function asProjectInspection(found) {
+    return { ...found, relPath: globalConfigLabel(found.displayPath), topLevelKey: "mcp_servers" };
+}
+/** Render the dry-run preview line for the global Codex config, or null when inactive. */
+export function formatGlobalDryRunLine(found) {
+    return formatDryRunLine(asProjectInspection(found));
+}
+/**
+ * The real-run action for the global Codex config, in the form
+ * {@link formatResultLine} already renders. Called only after verification
+ * passed: a failed write is never advertised as a completed repin.
+ */
+function globalResultAction(initial, targetVersion) {
+    const relPath = globalConfigLabel(initial.displayPath);
+    const registrationKey = initial.registrationKey ?? undefined;
+    switch (initial.action) {
+        case "repin":
+            return {
+                relPath,
+                kind: "repinned",
+                registrationKey,
+                fromVersion: initial.currentVersion ?? undefined,
+                toVersion: targetVersion,
+            };
+        case "normalize-unpinned":
+            return {
+                relPath,
+                kind: "normalized",
+                registrationKey,
+                fromSpec: initial.spec ?? undefined,
+                toVersion: targetVersion,
+            };
+        case "already-current":
+            return { relPath, kind: "already-current", registrationKey, toVersion: targetVersion };
+        case "skip-worktree-shim":
+            return { relPath, kind: "skipped-worktree-shim", registrationKey };
+        default:
+            return null;
+    }
+}
+async function snapshotCodexConfig(deps, env, targetVersion) {
+    const home = deps.homedir();
+    const location = resolveCodexConfigLocation(env, home);
+    const captured = { source: null };
+    const inspection = await inspectGlobalLauncherConfigs({
+        env,
+        homedir: home,
+        targetVersion,
+        readFile: async (filePath) => {
+            const text = await deps.readFile(filePath);
+            captured.source = text;
+            return text;
+        },
+    });
+    return { ...location, inspection, source: captured.source };
+}
+/**
+ * The guarded Phase 5 Codex write. Computes the one-token splice from the Phase 2
+ * snapshot, re-reads the file, and writes ONLY if it is still byte-identical to
+ * that snapshot. The comparison is optimistic protection against a concurrent
+ * edit, not a lock. Every failure is a fixed, path-specific sentence — never the
+ * TOML, an argument, an environment value, or exception text.
+ */
+async function applyGuardedCodexWrite(deps, snapshot, targetVersion) {
+    const where = snapshot.displayPath;
+    let expected;
+    try {
+        if (snapshot.source === null)
+            throw new Error("no snapshot");
+        expected = applyCodexRepin(snapshot.source, inspectCodexLauncher(snapshot.source), targetVersion);
+    }
+    catch {
+        return { failure: `${where}: the Codex configuration could not be updated safely; it was left unchanged` };
+    }
+    let current;
+    try {
+        current = await deps.readFile(snapshot.filePath);
+    }
+    catch {
+        return { failure: `${where}: the Codex configuration could not be re-read before writing; it was left unchanged` };
+    }
+    if (current !== snapshot.source) {
+        return { failure: `${where}: the Codex configuration changed after it was inspected; it was left unchanged` };
+    }
+    try {
+        await deps.writeFile(snapshot.filePath, expected);
+    }
+    catch {
+        return { failure: `${where}: the Codex configuration could not be written` };
+    }
+    return { expected };
+}
+/**
+ * Phase 6 for Codex: re-inspect and prove the claim. A written config must be
+ * current at the exact target under its ORIGINAL registration name AND equal the
+ * expected spliced text exactly — a correct pin beside any other difference is
+ * still a failure. Initially inactive configs are nonparticipants and are never
+ * verified, created, or repaired.
+ */
+async function verifyCodexConfig(deps, env, snapshot, targetVersion, expected) {
+    const initial = snapshot.inspection;
+    if (initial.action === "skip-inactive")
+        return { inspection: null, failures: [] };
+    const where = snapshot.displayPath;
+    let after;
+    try {
+        after = await snapshotCodexConfig(deps, env, targetVersion);
+    }
+    catch {
+        return {
+            inspection: null,
+            failures: [`${where}: could not verify the Codex configuration after writing`],
+        };
+    }
+    const found = after.inspection;
+    const fail = (message) => ({ inspection: found, failures: [`${where}: ${message}`] });
+    if (!found.filePresent)
+        return fail("the Codex configuration disappeared after the write");
+    if (found.reason === "file-unreadable") {
+        return fail("the Codex configuration could not be read back after the write");
+    }
+    if (found.action === "duplicate-registration") {
+        return fail("the Codex configuration now carries two Bridge registrations");
+    }
+    if (found.reason === "unlocatable" || found.action === "skip-inactive") {
+        return fail("the Codex Bridge launcher can no longer be located after the write");
+    }
+    if (found.registrationKey !== initial.registrationKey) {
+        return fail("the Codex Bridge entry no longer lives under its original registration name");
+    }
+    if (initial.action === "skip-worktree-shim") {
+        return found.action === "skip-worktree-shim"
+            ? { inspection: found, failures: [] }
+            : fail("a worktree shim was expected to be preserved but no longer looks like one");
+    }
+    if (found.action !== "already-current" || found.currentVersion !== targetVersion) {
+        return fail(`expected ${MCP_PACKAGE_NAME}@${targetVersion} after the write`);
+    }
+    if (expected !== null && after.source !== expected) {
+        return fail("the Codex configuration differs from the expected upgraded text");
+    }
+    return { inspection: found, failures: [] };
+}
+/** The host a project config path belongs to, derived from the registry. */
+function hostIdForRelPath(relPath) {
+    return allHostTargets().find((t) => t.scope === "project" && t.relPath === relPath)?.id;
+}
+/**
+ * One `Reload <host>: <hint>.` line per changed, automatically managed host, in
+ * registry order. Hint text lives on the registry entry; nothing here names a
+ * host or a path.
+ */
+export function reloadGuidanceLines(changed) {
+    return HOST_PLATFORM_ORDER.map((id) => MCP_HOST_TARGETS[id])
+        .filter((t) => changed.has(t.id) && t.writeStrategy !== "manual-instructions" && t.reloadHint)
+        .map((t) => `Reload ${t.label}: ${t.reloadHint}.`);
+}
+// ---------------------------------------------------------------------------
 // The command
 // ---------------------------------------------------------------------------
 export async function runUpgradeCli(argv, injected) {
@@ -361,13 +586,32 @@ export async function runUpgradeCli(argv, injected) {
         stderr(`Bridge API upgrade failed: could not inspect launcher configs: ${msg}`);
         return 1;
     }
+    // BAPI-1445: Codex's global config, inspected beside the project targets in its
+    // OWN error boundary so an unexpected failure is reported with fixed text and
+    // the safe display path, never with exception text that could carry a path.
+    const env = deps.env ?? {};
+    let codexSnapshot;
+    try {
+        codexSnapshot = await snapshotCodexConfig(deps, env, target.version);
+    }
+    catch {
+        const where = resolveCodexConfigLocation(env, "").displayPath;
+        stderr(`Bridge API upgrade failed: could not inspect the Codex configuration at ${where}.`);
+        stderr("  Nothing was changed.");
+        return 1;
+    }
+    const codex = codexSnapshot.inspection;
     const blocking = inspections.filter(isPrerequisiteFailure);
     const ahead = inspections.filter((i) => i.action === "ahead");
-    if (blocking.length > 0 || ahead.length > 0) {
+    const codexRefused = isPrerequisiteFailure(codex) || codex.action === "ahead";
+    if (blocking.length > 0 || ahead.length > 0 || codexRefused) {
         stderr("Bridge API upgrade aborted — these configs cannot be safely reconciled:");
         for (const found of [...blocking, ...ahead]) {
             stderr(`  ${found.relPath}: ${describeLauncherReason(found.reason)}`);
         }
+        if (codexRefused) {
+            stderr(`  ${codex.displayPath}: ${describeLauncherReason(codex.reason)}`);
+        }
         stderr("  Nothing was changed. Resolve these by hand, then re-run the upgrade.");
         return 1;
     }
@@ -381,9 +625,7 @@ export async function runUpgradeCli(argv, injected) {
         }
         stdout(`- Would detect and remove competing local install in node_modules/${MCP_PACKAGE_NAME} if present.`);
         stdout(`- Launcher pins (target ${MCP_PACKAGE_NAME}@${target.version}):`);
-        const lines = inspections
-            .map(formatDryRunLine)
-            .filter((l) => l !== null);
+        const lines = [...inspections.map(formatDryRunLine), formatGlobalDryRunLine(codex)].filter((l) => l !== null);
         if (lines.length === 0) {
             stdout("    (no applicable launcher configs found)");
         }
@@ -391,11 +633,24 @@ export async function runUpgradeCli(argv, injected) {
             for (const line of lines)
                 stdout(line);
         }
-        if (isEveryLauncherAlreadyCurrent(toPlannedActions(inspections))) {
+        const plannedInspections = [...inspections, asProjectInspection(codex)];
+        if (isEveryLauncherAlreadyCurrent(toPlannedActions(plannedInspections))) {
             stdout(`- Would print: Already up-to-date.`);
         }
         stdout(`- Would refresh scaffolded artifacts (commands, agents, pipelines).`);
-        stdout(`- Would print a reminder to reload/restart your MCP.`);
+        // Reload guidance only for hosts whose configuration this run would change.
+        const plannedHosts = new Set();
+        for (const found of inspections) {
+            if (PLANNED_CHANGE_ACTIONS.has(found.action)) {
+                const id = hostIdForRelPath(found.relPath);
+                if (id)
+                    plannedHosts.add(id);
+            }
+        }
+        if (PLANNED_CHANGE_ACTIONS.has(codex.action))
+            plannedHosts.add(codex.hostId);
+        for (const line of reloadGuidanceLines(plannedHosts))
+            stdout(`- Would print: ${line}`);
         return 0;
     }
     // ---- Phase 4: competing local install — a reconciliation, not a transition ----
@@ -434,6 +689,21 @@ export async function runUpgradeCli(argv, injected) {
         stderr(`Bridge API upgrade failed: ${msg}`);
         return 1;
     }
+    // ---- Phase 5b (BAPI-1445): the guarded Codex write ----
+    // Only after `runInit` succeeded, and only for a pin that has to move. A failure
+    // here is recorded as a convergence failure, never thrown: the JSON configs
+    // `runInit` already upgraded stay upgraded (no rollback) and nothing retries.
+    const codexFailures = [];
+    let codexExpected = null;
+    if (codex.action === "repin" || codex.action === "normalize-unpinned") {
+        const written = await applyGuardedCodexWrite(deps, codexSnapshot, target.version);
+        if ("failure" in written) {
+            codexFailures.push(written.failure);
+        }
+        else {
+            codexExpected = written.expected;
+        }
+    }
     // ---- Phase 6: verify every claim by re-reading the configs ----
     let verified;
     try {
@@ -491,16 +761,41 @@ export async function runUpgradeCli(argv, injected) {
                 `after the write, found ${after.registrationKey ? `\`${after.registrationKey}\`` : "no recognized registration"}`);
         }
     }
+    // Codex is verified independently — and only when its write did not already fail.
+    let codexVerified = null;
+    if (codexFailures.length === 0) {
+        const codexCheck = await verifyCodexConfig(deps, env, codexSnapshot, target.version, codexExpected);
+        codexVerified = codexCheck.inspection;
+        codexFailures.push(...codexCheck.failures);
+    }
+    verificationFailures.push(...codexFailures);
+    // A Codex transition is reported only once it verified.
+    const codexAction = codexFailures.length === 0 ? globalResultAction(codex, target.version) : null;
     // ---- Phase 7: report what actually happened ----
-    const resultLines = initResult.configActions
-        .map(formatResultLine)
-        .filter((l) => l !== null);
+    const codexLine = codexAction ? formatResultLine(codexAction) : null;
+    const resultLines = [
+        ...initResult.configActions.map(formatResultLine),
+        codexLine,
+    ].filter((l) => l !== null);
     if (resultLines.length > 0) {
         stdout("Launcher pins:");
         for (const line of resultLines)
             stdout(line);
     }
     stdout("Refreshed scaffolded artifacts (commands, agents, pipelines).");
+    // BAPI-1470: `runInit` already printed the notice and any probe warnings in
+    // full. Summarize with counts only. A caller that omits the optional fields has
+    // told us nothing, so absent fields print nothing rather than "none found".
+    const legacyCopyCount = initResult.legacyProcedureCopies?.length ?? 0;
+    const legacyWarningCount = initResult.legacyProcedureProbeWarnings?.length ?? 0;
+    if (legacyCopyCount > 0 || legacyWarningCount > 0) {
+        const parts = [];
+        if (legacyCopyCount > 0)
+            parts.push(`${legacyCopyCount} old fallback ${legacyCopyCount === 1 ? "copy" : "copies"} found`);
+        if (legacyWarningCount > 0)
+            parts.push(`${legacyWarningCount} old ${legacyWarningCount === 1 ? "path" : "paths"} could not be checked`);
+        stdout(`Old procedure copies: ${parts.join(", ")} (details above).`);
+    }
     if (verificationFailures.length > 0) {
         stderr("\nBridge API upgrade did NOT converge:");
         for (const failure of verificationFailures)
@@ -518,16 +813,26 @@ export async function runUpgradeCli(argv, injected) {
     // ---- Phase 8 (BAPI-1398): the project's /drive-epic-run permission rules ----
     // Only after every gate above passed. Advisory: a malformed settings file or a
     // refused launcher is reported and never changes the exit code.
+    // BAPI-1446: the same step carries the pinned SessionStart upgrade-notice hook,
+    // requested only for a Claude Code installation and pinned to the CONVERGED
+    // target version (never `VERSION`, `@latest`, or the fake-latest override).
     if (deps.applyBridgePermissions) {
         try {
-            reportUpgradePermissions(await deps.applyBridgePermissions(deps.cwd, deps.env ?? {}), stdout, stderr);
+            const sessionStartHook = (await isClaudeCodeInstallation(deps))
+                ? { pinnedVersion: target.version }
+                : undefined;
+            reportUpgradePermissions(await deps.applyBridgePermissions(deps.cwd, deps.env ?? {}, sessionStartHook), stdout, stderr);
         }
         catch {
             stderr("Warning: could not write Bridge's permission rules (non-fatal).");
         }
     }
-    const applicableStandard = verified.filter(isApplicableStandardLauncher);
-    if (isEveryLauncherAlreadyCurrent(initResult.configActions)) {
+    const applicableStandard = [
+        ...verified.filter(isApplicableStandardLauncher),
+        ...(codexVerified && isApplicableStandardLauncher(codexVerified) ? [codexVerified] : []),
+    ];
+    const everyAction = [...initResult.configActions, ...(codexAction ? [codexAction] : [])];
+    if (isEveryLauncherAlreadyCurrent(everyAction)) {
         // The exact string `/upgrade-bridge` is contracted to relay verbatim.
         stdout("\nAlready up-to-date.");
     }
@@ -538,15 +843,50 @@ export async function runUpgradeCli(argv, injected) {
     }
     else {
         stdout(`\nUpgrade complete: launcher pins are at ${target.version}.`);
-        // The running session still holds the OLD MCP connection — MCP config is only
-        // read at session startup, so a launcher repin does not hot-reload it. Tell the
-        // user the concrete action instead of spawning a fresh session for them.
-        stdout("Reload your MCP now (run /mcp) or restart your session to pick up the upgraded server.");
+        // Running sessions still hold the OLD MCP connection — MCP config is only read
+        // at session startup, so a launcher repin does not hot-reload it. Name the
+        // concrete action for each host whose configuration actually changed, from the
+        // registry's own hints and in its order.
+        const changedHosts = new Set();
+        for (const action of initResult.configActions) {
+            if (!CHANGED_ACTION_KINDS.has(action.kind))
+                continue;
+            const id = hostIdForRelPath(action.relPath);
+            if (id)
+                changedHosts.add(id);
+        }
+        if (codexAction && CHANGED_ACTION_KINDS.has(codexAction.kind))
+            changedHosts.add(codex.hostId);
+        for (const line of reloadGuidanceLines(changedHosts))
+            stdout(line);
     }
     return 0;
 }
+/** Planned actions that change a configuration and so warrant reload guidance. */
+const PLANNED_CHANGE_ACTIONS = new Set([
+    "repin",
+    "normalize-unpinned",
+    "add",
+    "create",
+]);
+/** Real-run action kinds that changed a configuration. */
+const CHANGED_ACTION_KINDS = new Set([
+    "repinned",
+    "normalized",
+    "added",
+    "created",
+]);
 /** Render the project permission result in upgrade's own report style. */
 export function reportUpgradePermissions(result, stdout, stderr) {
+    if (result.hook) {
+        // Reported on its own, so a refused launcher or a malformed hooks structure
+        // never hides, or is hidden by, the permission-rule result.
+        const described = describeSessionStartHookOutcome(result.hook);
+        for (const line of described.lines)
+            stdout(line);
+        for (const warning of described.warnings)
+            stderr(`Warning: ${warning}.`);
+    }
     if (!result.launcher.ok) {
         stderr(`Warning: Bridge permission rules were not written: ${result.launcher.reason}.`);
         return;