@bridge_gpt/mcp-server 0.2.9 → 0.2.10

package/build/install-bridge.js

@@ -0,0 +1,692 @@
+/**
+ * install-bridge — the one-command Bridge API project bootstrap (BAPI-429).
+ *
+ *   npx -y @bridge_gpt/mcp-server@latest install-bridge [--repo <name>] [--api-key <key>] [--force] [--dry-run] [--agent <name>]
+ *
+ * Collapses the previously five-step manual setup into a single CLI subcommand.
+ * It does the DETERMINISTIC work in the shell:
+ *
+ *   Step 1  Scaffold via `runInit` (commands, agents, pipelines, secret-free
+ *           per-host MCP config placeholders, .bridge/config).
+ *   Step 2  Verify connectivity over HTTP (`GET <base>/jira/ping?repo_name=…`
+ *           with the `X-API-Key` header) BEFORE writing the key anywhere durable
+ *           (R5). Halt on failure — so a bad key never lands in the config and
+ *           traps later retries behind overwrite-consent.
+ *   Step 3  Write the per-host MCP config (.mcp.json / .cursor/mcp.json /
+ *           .vscode/mcp.json) with REAL values (BAPI_REPO_NAME / BAPI_API_KEY /
+ *           BAPI_BASE_URL / BAPI_DOCS_DIR), read-merge-write so unrelated servers
+ *           survive, pinning the launcher to the exact running version. Detected
+ *           Windsurf / Codex (global configs we never write into automatically)
+ *           get printed manual instructions.
+ *   Step 4  Persist the routing credential to the user-scoped store
+ *           (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) via
+ *           `upsertBapiCredential`. Non-blocking (fail-open) — mirrors Stage 6.
+ *
+ * then SPAWNS a fresh agent session (Step 5) for the agentic remainder
+ * (`/install-bridge` config-field derivation, then `/learn-repository`). The
+ * fresh session is required because a CLI cannot force the running editor to
+ * reload the just-written `.mcp.json`, and field derivation needs an agent
+ * runtime the shell does not have.
+ *
+ * SECRET DISCIPLINE: the API key is NEVER printed or logged — not in stdout,
+ * stderr, error messages, or --dry-run output (it is redacted to `<REDACTED>`).
+ * The ONLY place the key is durably written is the per-host MCP config (Step 3,
+ * gitignored) and the user-scoped credential store (Step 4).
+ */
+import { readFile, writeFile, mkdir, stat, rename, chmod, unlink } from "fs/promises";
+import os from "os";
+import path from "path";
+import readline from "readline";
+import { runInit, buildBridgeApiEntry } from "./init.js";
+import { validateRepoName } from "./bridge-config.js";
+import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
+import { upsertBapiCredential, getPrimaryCredentialStorePath, } from "./credential-store.js";
+import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
+import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, } from "./start-tickets.js";
+/** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
+export const REDACTED_API_KEY = "<REDACTED>";
+/** The natural-language sequential prompt handed to the spawned agent session. */
+export const INSTALL_BRIDGE_AGENT_PROMPT = "Please execute the /install-bridge command. Once it completes successfully, execute the /learn-repository command.";
+/** Default base URL when `BAPI_BASE_URL` is unset (mirrors index.ts). */
+export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
+/** Default docs dir when `BAPI_DOCS_DIR` is unset (mirrors index.ts). */
+export const DEFAULT_BAPI_DOCS_DIR = "docs/tmp";
+/** User-facing usage text. */
+export function getInstallBridgeUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server@latest install-bridge [flags]",
+        "",
+        "One-command Bridge API project bootstrap. Scaffolds the project, writes the",
+        "per-host MCP config with your credentials, verifies connectivity, persists the",
+        "routing credential, then opens a fresh agent session to derive the remaining",
+        "config and run /learn-repository.",
+        "",
+        "Inputs (the only two irreducible ones):",
+        "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
+        "                    then an interactive (no-echo) prompt. Generate one in the",
+        "                    Bridge API web UI Security page — this command consumes a",
+        "                    key, it does not create one. NEVER printed or logged.",
+        "  --repo <name>     Repository name. Falls back to BAPI_REPO_NAME, then an",
+        "                    inferred default you confirm interactively. MUST match the",
+        "                    server-side repo registration (it keys the credential",
+        "                    store as bapi:<repo>). Required (no inference) when stdin",
+        "                    is non-interactive.",
+        "",
+        "Flags:",
+        "  --force                       Overwrite an existing real BAPI_API_KEY in a",
+        "                                host config without prompting.",
+        "  --dry-run                     Preview every step (scaffold targets, config",
+        "                                files + keys with the key REDACTED, ping",
+        "                                target, credential target, spawn command)",
+        "                                without writing, pinging, or spawning anything.",
+        "  --agent claude|cursor-agent   Agent to launch for the agentic remainder",
+        "                                (default: claude).",
+        "  -h, --help                    Show this help.",
+        "",
+        "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
+        "(default docs/tmp) are read from the environment with the shown fallbacks.",
+    ].join("\n");
+}
+/**
+ * Parse argv strictly. Supports `--api-key`, `--repo`, `--agent` (each with a
+ * `--flag value` or `--flag=value` form), the boolean `--force` / `--dry-run`,
+ * and `-h`/`--help`. Unknown flags and positional args are rejected. The API key
+ * value is captured but never echoed (no error message includes it).
+ */
+export function parseInstallBridgeArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getInstallBridgeUsage() };
+    }
+    let apiKey;
+    let repo;
+    let force = false;
+    let dryRun = false;
+    let agentName = DEFAULT_AGENT_NAME;
+    /** Read a `--flag value` or `--flag=value` value, advancing the index. */
+    const readValue = (arg, flag, i) => {
+        if (arg.startsWith(`${flag}=`)) {
+            return { value: arg.slice(flag.length + 1), nextIndex: i };
+        }
+        if (i + 1 >= argv.length) {
+            return { error: `${flag} requires a value.` };
+        }
+        return { value: argv[i + 1], nextIndex: i + 1 };
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--api-key" || arg.startsWith("--api-key=")) {
+            const r = readValue(arg, "--api-key", i);
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            apiKey = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (arg === "--repo" || arg.startsWith("--repo=")) {
+            const r = readValue(arg, "--repo", i);
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            repo = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (arg === "--agent" || arg.startsWith("--agent=")) {
+            const r = readValue(arg, "--agent", i);
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (!isAgentName(r.value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --agent value: '${r.value}' (allowed agents: ${formatValidAgentNames()}).`,
+                };
+            }
+            agentName = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        return {
+            status: "error",
+            message: `Unexpected positional argument: '${arg}'. install-bridge does not accept positional arguments.`,
+        };
+    }
+    return { status: "ok", options: { apiKey, repo, force, dryRun, agentName } };
+}
+/** No-echo secret prompt on stderr (so it never lands in piped stdout). */
+function promptSecretViaReadline(promptText) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stderr,
+            terminal: true,
+        });
+        // Suppress echo of typed characters: override the internal writer so only the
+        // prompt (written explicitly below) is shown, never the keystrokes.
+        const mutable = rl;
+        let muted = false;
+        mutable._writeToOutput = (s) => {
+            if (!muted)
+                process.stderr.write(s);
+        };
+        process.stderr.write(promptText);
+        muted = true;
+        rl.question("", (answer) => {
+            rl.close();
+            process.stderr.write("\n");
+            resolve(answer.trim());
+        });
+    });
+}
+/** Echoed single-line prompt on stderr (used for repo confirmation / value). */
+function promptLineViaReadline(promptText) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        rl.question(promptText, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/** Build default deps from the live process. */
+export function createDefaultInstallBridgeDeps() {
+    const isTTY = Boolean(process.stdin.isTTY);
+    return {
+        env: process.env,
+        cwd: process.cwd(),
+        platform: process.platform,
+        homedir: os.homedir,
+        isTTY,
+        readFile: (p) => readFile(p, "utf-8"),
+        writeFile: (p, data, options) => writeFile(p, data, options),
+        mkdir: (p, options) => mkdir(p, options),
+        stat: (p) => stat(p),
+        rename: (a, b) => rename(a, b),
+        chmod: (p, m) => chmod(p, m),
+        unlink: (p) => unlink(p),
+        promptSecret: isTTY ? promptSecretViaReadline : undefined,
+        promptLine: isTTY ? promptLineViaReadline : undefined,
+        fetch: (...args) => fetch(...args),
+        runInit,
+        upsertCredential: upsertBapiCredential,
+        buildShellCommand: buildGenericAgentShellCommand,
+        spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
+        startTicketsDeps: createDefaultStartTicketsDeps(),
+        log: (m) => console.log(m),
+        errorLog: (m) => console.error(m),
+    };
+}
+/**
+ * Resolve the API key: `--api-key` → `BAPI_API_KEY` env → interactive no-echo
+ * prompt. Fails (secret-free) when none is available and stdin is non-interactive.
+ */
+export async function resolveApiKey(options, deps) {
+    if (typeof options.apiKey === "string" && options.apiKey.trim().length > 0) {
+        return { ok: true, value: options.apiKey.trim() };
+    }
+    const fromEnv = deps.env.BAPI_API_KEY;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return { ok: true, value: fromEnv.trim() };
+    }
+    if (deps.isTTY && deps.promptSecret) {
+        const entered = (await deps.promptSecret("Bridge API key (input hidden): ")).trim();
+        if (entered.length > 0) {
+            return { ok: true, value: entered };
+        }
+        return { ok: false, error: "No API key entered." };
+    }
+    return {
+        ok: false,
+        error: "An API key is required. Pass --api-key or set the BAPI_API_KEY environment variable " +
+            "(no interactive terminal is available to prompt for it).",
+    };
+}
+/**
+ * Resolve the repo name: `--repo` → `BAPI_REPO_NAME` env → inferred default
+ * (from .bridge/config, else the cwd basename) confirmed interactively. Fails
+ * fast (no inference) when neither is supplied and stdin is non-interactive —
+ * the repo identity keys the credential store and must match server-side
+ * registration, so it is never silently inferred non-interactively.
+ */
+export async function resolveRepoName(options, deps) {
+    if (typeof options.repo === "string" && options.repo.trim().length > 0) {
+        return { ok: true, value: options.repo.trim() };
+    }
+    const fromEnv = deps.env.BAPI_REPO_NAME;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return { ok: true, value: fromEnv.trim() };
+    }
+    // Non-interactive: fail fast and require --repo. Inference is an interactive
+    // convenience only (the user must confirm it).
+    if (!deps.isTTY || !deps.promptLine) {
+        return {
+            ok: false,
+            error: "A repo name is required. Pass --repo or set the BAPI_REPO_NAME environment variable " +
+                "(no interactive terminal is available to confirm an inferred name). It must match the " +
+                "server-side repository registration.",
+        };
+    }
+    // Infer a sensible default: existing .bridge/config, else the cwd basename.
+    let inferred = await resolveStartTicketsRepoName({
+        env: deps.env,
+        cwd: deps.cwd,
+        readFile: deps.readFile,
+    });
+    if (!inferred) {
+        const validated = validateRepoName(path.basename(deps.cwd));
+        if (validated.ok)
+            inferred = validated.value;
+    }
+    if (inferred) {
+        const answer = (await deps.promptLine(`Repo name [${inferred}] (must match server-side registration): `)).trim();
+        const chosen = answer.length > 0 ? answer : inferred;
+        if (chosen.length > 0)
+            return { ok: true, value: chosen };
+    }
+    else {
+        const answer = (await deps.promptLine("Repo name (must match server-side registration): ")).trim();
+        if (answer.length > 0)
+            return { ok: true, value: answer };
+    }
+    return { ok: false, error: "No repo name provided." };
+}
+/** Resolve which project-local host configs to write, mirroring runInit detection. */
+async function resolveHostConfigTargets(deps) {
+    const targets = [
+        { relPath: ".mcp.json", topLevelKey: "mcpServers" },
+    ];
+    const dirExists = async (rel) => {
+        try {
+            await deps.stat(path.join(deps.cwd, rel));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (await dirExists(".vscode")) {
+        targets.push({ relPath: ".vscode/mcp.json", topLevelKey: "servers" });
+    }
+    if ((await dirExists(".cursor")) || deps.env.CURSOR_TRACE_DIR) {
+        targets.push({ relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" });
+    }
+    return targets;
+}
+/** Is this a placeholder (or absent) API-key value rather than a real secret? */
+function isPlaceholderApiKey(value) {
+    if (typeof value !== "string")
+        return true;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return true;
+    return trimmed === "YOUR_API_KEY" || trimmed.startsWith("YOUR_");
+}
+/**
+ * Build the per-host `bridge-api` MCP entry carrying REAL values. Starts from the
+ * secret-free, version-pinned `buildBridgeApiEntry` (so the launcher pin is
+ * identical to `--init`) and overlays the real repo name, base URL, docs dir, and
+ * the API key.
+ */
+export function buildInstallBridgeServerEntry(cwd, repoName, apiKey, baseUrl, docsDir) {
+    const entry = buildBridgeApiEntry(cwd);
+    const env = {
+        ...entry.env,
+        BAPI_REPO_NAME: repoName,
+        BAPI_BASE_URL: baseUrl,
+        BAPI_DOCS_DIR: docsDir,
+        BAPI_API_KEY: apiKey,
+    };
+    return { command: entry.command, args: entry.args, env };
+}
+/** Read + parse an existing host config; `null` if absent/unparseable. */
+async function readHostConfig(deps, fullPath) {
+    let raw;
+    try {
+        raw = await deps.readFile(fullPath);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect whether any resolved host config already carries a real (non-placeholder)
+ * `BAPI_API_KEY` for the `bridge-api` server — the trigger for overwrite consent.
+ */
+async function detectExistingRealKey(deps, targets) {
+    for (const target of targets) {
+        const parsed = await readHostConfig(deps, path.join(deps.cwd, target.relPath));
+        const entry = parsed?.[target.topLevelKey]?.["bridge-api"];
+        if (entry?.env && !isPlaceholderApiKey(entry.env.BAPI_API_KEY)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Write the `bridge-api` entry into each host config via read-merge-write,
+ * preserving unrelated servers and top-level keys. Returns the list of written
+ * relative paths.
+ */
+async function writeHostConfigs(deps, targets, entry) {
+    const written = [];
+    for (const target of targets) {
+        const fullPath = path.join(deps.cwd, target.relPath);
+        const parsed = (await readHostConfig(deps, fullPath)) ?? {};
+        if (!parsed[target.topLevelKey] || typeof parsed[target.topLevelKey] !== "object") {
+            parsed[target.topLevelKey] = {};
+        }
+        parsed[target.topLevelKey]["bridge-api"] = entry;
+        await deps.mkdir(path.dirname(fullPath), { recursive: true });
+        await deps.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", {
+            encoding: "utf-8",
+        });
+        written.push(target.relPath);
+    }
+    return written;
+}
+/** Build the `/jira/ping` URL exactly like the MCP `ping` tool / buildGetUrl. */
+export function buildPingUrl(baseUrl, repoName) {
+    const url = new URL(`${baseUrl.replace(/\/+$/, "")}/jira/ping`);
+    url.searchParams.set("repo_name", repoName);
+    return url.toString();
+}
+/**
+ * Verify connectivity. Distinguishes a rejected key (401/403) from an unknown
+ * repo / not-found (404) where the response allows. The key is sent in the
+ * `X-API-Key` header and NEVER appears in any returned message.
+ */
+export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
+    const url = buildPingUrl(baseUrl, repoName);
+    let resp;
+    try {
+        // Bound the request: if the server accepts the connection but stalls, the
+        // AbortError surfaces through the catch below as the secret-free "could not
+        // reach" message rather than hanging the CLI indefinitely.
+        resp = await deps.fetch(url, {
+            headers: { "X-API-Key": apiKey },
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `Could not reach the Bridge API at ${baseUrl} (${msg}). Check BAPI_BASE_URL and your network.`,
+        };
+    }
+    if (resp.ok)
+        return { ok: true };
+    if (resp.status === 401 || resp.status === 403) {
+        return {
+            ok: false,
+            message: `The Bridge API rejected the credential (HTTP ${resp.status}). The API key may be invalid or expired ` +
+                "— generate a fresh one in the Bridge API web UI Security page. (An expired token can also surface as a " +
+                "permission error.)",
+        };
+    }
+    if (resp.status === 404) {
+        return {
+            ok: false,
+            message: `The Bridge API could not find repo '${repoName}' (HTTP 404). Confirm --repo matches the server-side ` +
+                "repository registration exactly.",
+        };
+    }
+    return {
+        ok: false,
+        message: `Connectivity check failed (HTTP ${resp.status}). Verify your repo, API key, and BAPI_BASE_URL.`,
+    };
+}
+/**
+ * Render the --dry-run preview lines. The API key is ALWAYS redacted — the
+ * spawnCommand and config preview never embed the secret.
+ */
+export function buildDryRunPreview(plan) {
+    return [
+        "install-bridge --dry-run (no writes, no network, no spawns)",
+        `Repo name:        ${plan.repoName}`,
+        `Base URL (ping):  ${plan.baseUrl}`,
+        `Docs dir:         ${plan.docsDir}`,
+        `Agent:            ${plan.agentName}`,
+        "",
+        "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
+        `Step 2 — connectivity ping (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
+        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned):",
+        ...plan.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`),
+        ...(plan.manualEditors.length > 0
+            ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
+            : []),
+        `Step 4 — persist routing credential: target ${plan.credentialTarget} at ${plan.credentialStorePath}`,
+        `Step 5 — spawn agent session: ${plan.spawnCommand}`,
+    ];
+}
+/**
+ * Detect global-config editors that install-bridge cannot safely write into
+ * (their configs live outside the project). Windsurf is detected from the
+ * project-local `.windsurf` dir / `.windsurfrules` file (mirroring `runInit`'s
+ * Phase 2 gate); Codex is detected from the global `~/.codex` directory. The
+ * manual-instructions block is only shown when at least one is detected, so a
+ * user with neither never sees it.
+ */
+export async function detectManualEditors(deps) {
+    const exists = async (p) => {
+        try {
+            await deps.stat(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const windsurf = (await exists(path.join(deps.cwd, ".windsurf"))) ||
+        (await exists(path.join(deps.cwd, ".windsurfrules")));
+    const codex = await exists(path.join(deps.homedir(), ".codex"));
+    return { windsurf, codex };
+}
+/** Human-readable list of the detected manual editors (for the dry-run preview). */
+export function manualEditorNames(editors) {
+    const names = [];
+    if (editors.windsurf)
+        names.push("Windsurf");
+    if (editors.codex)
+        names.push("Codex");
+    return names;
+}
+/**
+ * Build the manual-instruction block for the DETECTED global-config editors only
+ * (key always redacted). Returns `null` when neither Windsurf nor Codex is
+ * detected, so the caller prints nothing for users who don't use them.
+ */
+function buildManualHostInstructions(entry, editors) {
+    if (!editors.windsurf && !editors.codex)
+        return null;
+    const redactedEnv = { ...entry.env, BAPI_API_KEY: REDACTED_API_KEY };
+    const lines = [
+        "",
+        "Detected an editor whose MCP config is global and cannot be written automatically.",
+        "Add the server manually (replace <REDACTED> with your key):",
+    ];
+    if (editors.windsurf) {
+        const windsurfSnippet = JSON.stringify({ mcpServers: { "bridge-api": { command: entry.command, args: entry.args, env: redactedEnv } } }, null, 2);
+        lines.push("", "  Windsurf → ~/.codeium/windsurf/mcp_config.json:", windsurfSnippet);
+    }
+    if (editors.codex) {
+        lines.push("", "  Codex → ~/.codex/config.toml (add an [mcp_servers.bridge-api] table with the", "  same command/args/env shown above, BAPI_API_KEY set to your key).");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+/**
+ * CLI entry for `install-bridge`. Returns a process exit code. Help returns 0;
+ * parser/resolution errors return 1; a ping failure halts (return 1) BEFORE the
+ * credential persist and agent spawn. The API key is never logged on any path.
+ */
+export async function runInstallBridgeCli(argv, overrides = {}) {
+    const deps = { ...createDefaultInstallBridgeDeps(), ...overrides };
+    const { log, errorLog } = deps;
+    const parsed = parseInstallBridgeArgs(argv);
+    if (parsed.status === "help") {
+        log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        errorLog(`Error: ${parsed.message}`);
+        errorLog("");
+        errorLog(getInstallBridgeUsage());
+        return 1;
+    }
+    const options = parsed.options;
+    // ---- Resolve inputs (may prompt when interactive) ----
+    // Resolve the API key first so a fully-empty non-interactive invocation fails
+    // with the (more security-relevant) missing-key message before the repo one.
+    const keyResult = await resolveApiKey(options, deps);
+    if (!keyResult.ok) {
+        errorLog(`Error: ${keyResult.error}`);
+        return 1;
+    }
+    const apiKey = keyResult.value;
+    const repoResult = await resolveRepoName(options, deps);
+    if (!repoResult.ok) {
+        errorLog(`Error: ${repoResult.error}`);
+        return 1;
+    }
+    const repoName = repoResult.value;
+    const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL;
+    const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
+    const agent = resolveAgentSpec(options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
+    const spawnCommand = deps.buildShellCommand(agent, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform);
+    const credentialStorePath = getPrimaryCredentialStorePath({
+        env: deps.env,
+        homedir: deps.homedir,
+    });
+    const targets = await resolveHostConfigTargets(deps);
+    // Read-only detection (safe in dry-run) of global-config editors we can't write.
+    const manualEditors = await detectManualEditors(deps);
+    const plan = {
+        repoName,
+        baseUrl,
+        docsDir,
+        agentName: options.agentName,
+        configTargets: targets.map((t) => t.relPath),
+        manualEditors: manualEditorNames(manualEditors),
+        credentialTarget: `bapi:${repoName}`,
+        credentialStorePath,
+        pingUrl: buildPingUrl(baseUrl, repoName),
+        spawnCommand,
+    };
+    // ---- --dry-run: preview every step, strictly no side effects ----
+    if (options.dryRun) {
+        for (const line of buildDryRunPreview(plan))
+            log(line);
+        return 0;
+    }
+    const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
+    // ---- Overwrite consent: a real existing key requires --force or a prompt ----
+    const hasRealKey = await detectExistingRealKey(deps, targets);
+    if (hasRealKey && !options.force) {
+        if (deps.isTTY && deps.promptLine) {
+            const answer = (await deps.promptLine("A host config already contains a BAPI_API_KEY. Overwrite it? [y/N]: ")).trim().toLowerCase();
+            if (answer !== "y" && answer !== "yes") {
+                errorLog("Aborted: existing API key left unchanged (re-run with --force to overwrite).");
+                return 1;
+            }
+        }
+        else {
+            errorLog("Error: a host config already contains a BAPI_API_KEY. Re-run with --force to overwrite it " +
+                "(refusing to overwrite a credential non-interactively without consent).");
+            return 1;
+        }
+    }
+    // ---- Step 1 — scaffold (secret-free placeholders only) ----
+    log("Step 1/5 — scaffolding project (commands, agents, pipelines, config placeholders)…");
+    await deps.runInit(deps.cwd);
+    // ---- Step 2 — verify connectivity BEFORE writing the key anywhere durable ----
+    // R5: ping before persisting anything durably. Pinging before writeHostConfigs
+    // (and the credential store) means a bad key on a first-time install halts
+    // WITHOUT leaving an invalid key in the config — which would otherwise trip the
+    // overwrite-consent gate on every retry (a trapped state).
+    log("Step 2/5 — verifying connectivity…");
+    const ping = await verifyConnectivity(deps, baseUrl, repoName, apiKey);
+    if (!ping.ok) {
+        errorLog(`Error: ${ping.message}`);
+        return 1;
+    }
+    log("  connectivity OK");
+    // ---- Step 3 — write per-host MCP config with real values ----
+    log("Step 3/5 — writing per-host MCP config…");
+    const written = await writeHostConfigs(deps, targets, entry);
+    for (const relPath of written)
+        log(`  wrote ${relPath}`);
+    // Only print global-editor manual setup when Windsurf/Codex is actually detected.
+    const manualInstructions = buildManualHostInstructions(entry, manualEditors);
+    if (manualInstructions)
+        log(manualInstructions);
+    // ---- Step 4 — persist routing credential (non-blocking / fail-open) ----
+    log("Step 4/5 — persisting routing credential…");
+    try {
+        const writeDeps = {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            mkdir: deps.mkdir,
+            writeFile: (p, d, o) => deps.writeFile(p, d, o),
+            rename: deps.rename,
+            chmod: deps.chmod,
+            unlink: deps.unlink,
+        };
+        const result = await deps.upsertCredential(repoName, apiKey, writeDeps);
+        if (result.ok) {
+            log(`  stored routing credential for ${result.target} at ${result.path}`);
+        }
+        else {
+            log(`  warning: could not persist the routing credential (${result.kind}). ` +
+                `start-tickets model routing may not resolve the key for ${plan.credentialTarget}; ` +
+                "set BAPI_API_KEY in the shell or re-run install-bridge.");
+        }
+    }
+    catch {
+        // Fail-open: persistence is best-effort (mirrors Stage 6). The secret is never
+        // included in the warning.
+        log("  warning: could not persist the routing credential (unexpected error). " +
+            "start-tickets model routing may need BAPI_API_KEY in the shell.");
+    }
+    // ---- Step 5 — spawn a fresh agent session for the agentic remainder ----
+    log(`Step 5/5 — opening a ${agent.name} session for /install-bridge + /learn-repository…`);
+    const terminal = detectTerminal(undefined, deps.env);
+    const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, spawnCommand, {
+        key: "install",
+        worktreePath: deps.cwd,
+    });
+    if (!spawnResult.ok) {
+        // Steps 1–4 (scaffold, config, connectivity-verified, credential persist) all
+        // succeeded and are durable; only the best-effort Step 5 tab spawn failed. The
+        // install itself is complete, so this is a non-fatal warning (exit 0) — the
+        // user can run the agentic remainder by hand. Mirrors start-tickets treating a
+        // spawn failure as non-fatal to the run.
+        errorLog(`Warning: setup completed, but the agent session could not be opened (${spawnResult.error}). ` +
+            "Run /install-bridge then /learn-repository manually in this project.");
+        return 0;
+    }
+    log("");
+    log("install-bridge complete. A fresh agent session is running /install-bridge then /learn-repository.");
+    return 0;
+}