@bridge_gpt/mcp-server 0.2.25 → 0.2.27

package/build/mcp-host-config.js

@@ -0,0 +1,521 @@
+/**
+ * Per-platform MCP host-config emission + provisioning (BAPI-635).
+ *
+ * Converts the single logical Bridge entry (from
+ * {@link file:./install-bridge.ts} `buildInstallBridgeServerEntry`) into each
+ * platform's physical JSON or TOML representation, and writes it without
+ * clobbering user-managed configuration.
+ *
+ * Write strategy per target comes from the data-only registry
+ * {@link file:./mcp-host-targets.ts}:
+ *   - vendor-first — prefer the official vendor CLI, fall back to a safe direct
+ *     write (Claude Code, Copilot CLI, Codex).
+ *   - direct — merge-write the JSON file directly (Cursor, Copilot VS Code).
+ *   - manual-instructions — never auto-write; emit redacted instructions
+ *     (Windsurf).
+ *
+ * SECRET DISCIPLINE: the API key lives only inside the logical entry's `env`.
+ * When a verified vendor contract delivers it via argv (all three do — none
+ * expose a stdin channel), the argv is constructed and spawned INSIDE the vendor
+ * adapter and is never stringified, logged, previewed, returned, or interpolated
+ * into a warning. Structured outcomes and inspectors carry presence + launcher
+ * args only, never env values.
+ *
+ * TOML NOTE: there is no comment-preserving TOML library available, so Codex
+ * direct writes render a canonical document for a missing file, APPEND canonical
+ * tables to an existing file that has no `bridge-api` table (preserving every
+ * existing byte), and DECLINE (`manual-required`) an existing `bridge-api` table
+ * rather than reserialize unrelated content.
+ */
+import { VERSION } from "./version.generated.js";
+// ---------------------------------------------------------------------------
+// Path helpers (POSIX-normalized; module stays free of node:path).
+// ---------------------------------------------------------------------------
+function joinPath(base, rel) {
+    const b = base.endsWith("/") ? base.slice(0, -1) : base;
+    const r = rel.startsWith("/") ? rel.slice(1) : rel;
+    return `${b}/${r}`;
+}
+function dirnameOf(p) {
+    const i = p.lastIndexOf("/");
+    if (i <= 0)
+        return "/";
+    return p.slice(0, i);
+}
+/** Resolve a target's absolute path from injected cwd/homedir. */
+export function resolveTargetAbsPath(target, ctx) {
+    if (target.scope === "project") {
+        if (!target.relPath)
+            throw new Error(`${target.id} missing relPath`);
+        return joinPath(ctx.cwd, target.relPath);
+    }
+    if (!target.absPathResolver)
+        throw new Error(`${target.id} missing absPathResolver`);
+    return target.absPathResolver(ctx.homedir);
+}
+// ---------------------------------------------------------------------------
+// Entry adaptation
+// ---------------------------------------------------------------------------
+/**
+ * Adapt the shared logical entry into a target's physical JSON entry: copy
+ * command/args/env, conditionally add the registry `transportType` as `type`,
+ * and merge `extraEntryKeys`. Claude Code omits `type`; Cursor/Copilot VS Code
+ * use `stdio`; Copilot CLI uses `local` + `tools: ["*"]`.
+ */
+export function adaptBridgeEntryForHostTarget(entry, target) {
+    const physical = {};
+    if (target.transportType !== undefined) {
+        physical.type = target.transportType;
+    }
+    physical.command = entry.command;
+    physical.args = [...entry.args];
+    physical.env = { ...entry.env };
+    if (target.extraEntryKeys) {
+        for (const [k, v] of Object.entries(target.extraEntryKeys)) {
+            physical[k] = v;
+        }
+    }
+    return physical;
+}
+// ---------------------------------------------------------------------------
+// JSON read / merge / write
+// ---------------------------------------------------------------------------
+function isEnoent(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+/** Read a JSON host config into distinct outcomes; malformed is never `{}`. */
+export async function readJsonHostConfig(path, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(path);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return { state: "missing" };
+        return { state: "read-error", message: "config could not be read" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { state: "invalid" };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { state: "invalid" };
+    }
+    return { state: "valid", value: parsed };
+}
+/**
+ * Merge the adapted `bridge-api` entry into an existing JSON document under the
+ * registry-selected root key. Unrelated top-level keys and unrelated servers are
+ * preserved; only the `bridge-api` entry is replaced.
+ */
+export function mergeJsonHostConfig(existing, target, adaptedEntry) {
+    const merged = { ...existing };
+    const rootRaw = merged[target.topLevelKey];
+    const root = rootRaw && typeof rootRaw === "object" && !Array.isArray(rootRaw)
+        ? { ...rootRaw }
+        : {};
+    root["bridge-api"] = adaptedEntry;
+    merged[target.topLevelKey] = root;
+    return merged;
+}
+/** Build a fresh JSON document containing only the Bridge entry. */
+function freshJsonDocument(target, adaptedEntry) {
+    return { [target.topLevelKey]: { "bridge-api": adaptedEntry } };
+}
+/**
+ * Direct-write a JSON host config. Malformed existing JSON is skipped with an
+ * explicit `skipped — invalid JSON` result and is never overwritten.
+ */
+export async function writeJsonHostConfig(path, target, adaptedEntry, deps) {
+    const read = await readJsonHostConfig(path, deps);
+    if (read.state === "invalid" || read.state === "read-error") {
+        return { status: "skipped-invalid", message: "skipped — invalid JSON" };
+    }
+    const isCreate = read.state === "missing";
+    const doc = isCreate
+        ? freshJsonDocument(target, adaptedEntry)
+        : mergeJsonHostConfig(read.value, target, adaptedEntry);
+    await deps.mkdir(dirnameOf(path), { recursive: true });
+    await deps.writeFile(path, JSON.stringify(doc, null, 2) + "\n");
+    return { status: isCreate ? "created" : "direct-written", path };
+}
+// ---------------------------------------------------------------------------
+// Codex TOML rendering + safe merge
+// ---------------------------------------------------------------------------
+/** Escape a string for a TOML basic string literal. */
+export function tomlEscapeString(value) {
+    let out = "";
+    for (const ch of value) {
+        switch (ch) {
+            case "\\":
+                out += "\\\\";
+                break;
+            case '"':
+                out += '\\"';
+                break;
+            case "\n":
+                out += "\\n";
+                break;
+            case "\r":
+                out += "\\r";
+                break;
+            case "\t":
+                out += "\\t";
+                break;
+            case "\b":
+                out += "\\b";
+                break;
+            case "\f":
+                out += "\\f";
+                break;
+            default: {
+                const code = ch.codePointAt(0);
+                if (code < 0x20) {
+                    out += "\\u" + code.toString(16).padStart(4, "0");
+                }
+                else {
+                    out += ch;
+                }
+            }
+        }
+    }
+    return out;
+}
+function tomlBasicString(value) {
+    return `"${tomlEscapeString(value)}"`;
+}
+function tomlStringArray(values) {
+    return `[${values.map(tomlBasicString).join(", ")}]`;
+}
+/** Deterministic env-key order for the Codex table (matches the web snippet). */
+const CODEX_ENV_ORDER = [
+    "BAPI_BASE_URL",
+    "BAPI_REPO_NAME",
+    "BAPI_API_KEY",
+    "BAPI_DOCS_DIR",
+    "BAPI_PROJECT_ROOT",
+];
+function orderedEnvKeys(env) {
+    const known = CODEX_ENV_ORDER.filter((k) => k in env);
+    const extra = Object.keys(env)
+        .filter((k) => !CODEX_ENV_ORDER.includes(k))
+        .sort();
+    return [...known, ...extra];
+}
+/**
+ * Render the canonical Codex TOML for the Bridge entry. Every string, path, URL,
+ * and launcher arg is TOML-escaped so it cannot produce malformed TOML.
+ */
+export function renderCodexBridgeToml(entry) {
+    const lines = [
+        "[mcp_servers.bridge-api]",
+        `command = ${tomlBasicString(entry.command)}`,
+        `args = ${tomlStringArray(entry.args)}`,
+        "",
+        "[mcp_servers.bridge-api.env]",
+    ];
+    for (const key of orderedEnvKeys(entry.env)) {
+        lines.push(`${key} = ${tomlBasicString(entry.env[key])}`);
+    }
+    return lines.join("\n") + "\n";
+}
+/** Whether a TOML document already declares a `[mcp_servers.bridge-api]` table. */
+export function codexHasBridgeTable(content) {
+    // Match the bare table header or any dotted subtable header, at line start
+    // (allowing leading whitespace). Never reserialize — presence only.
+    return /^[ \t]*\[mcp_servers\.bridge-api(\.[^\]]*)?\][ \t]*$/m.test(content);
+}
+/**
+ * Compute the safe Codex merge action. A missing document → canonical create; an
+ * existing document without a Bridge table → append (existing bytes preserved,
+ * minimal newline boundary); an existing Bridge table → decline (manual-required)
+ * rather than reserialize.
+ */
+export function mergeCodexHostConfig(existing, entry) {
+    if (existing.state === "missing") {
+        return { action: "create", content: renderCodexBridgeToml(entry) };
+    }
+    if (existing.state === "read-error" || existing.state === "invalid") {
+        // Cannot safely reason about the file → decline.
+        return { action: "manual-required" };
+    }
+    const content = existing.state === "text"
+        ? existing.content
+        : // "valid" JsonReadResult is not used for TOML; guard anyway.
+            "";
+    if (codexHasBridgeTable(content)) {
+        return { action: "manual-required" };
+    }
+    const boundary = content.length === 0 || content.endsWith("\n") ? "\n" : "\n\n";
+    return { action: "append", content: content + boundary + renderCodexBridgeToml(entry) };
+}
+/** Read a TOML file into a missing / text / read-error result. */
+async function readTomlHostConfig(path, deps) {
+    try {
+        const content = await deps.readFile(path);
+        return { state: "text", content };
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return { state: "missing" };
+        return { state: "read-error", message: "config could not be read" };
+    }
+}
+/** Direct-write the Codex TOML config using the safe merge strategy. */
+export async function writeCodexHostConfig(path, entry, deps) {
+    const read = await readTomlHostConfig(path, deps);
+    const merge = mergeCodexHostConfig(read, entry);
+    if (merge.action === "manual-required") {
+        return { status: "manual-required" };
+    }
+    await deps.mkdir(dirnameOf(path), { recursive: true });
+    await deps.writeFile(path, merge.content);
+    return { status: merge.action === "create" ? "created" : "direct-written", path };
+}
+/** Inspect a JSON host config for a `bridge-api` entry (no env values read). */
+export async function inspectJsonHostEntry(path, target, deps) {
+    const read = await readJsonHostConfig(path, deps);
+    if (read.state !== "valid")
+        return { present: false };
+    const root = read.value[target.topLevelKey];
+    if (!root || typeof root !== "object" || Array.isArray(root))
+        return { present: false };
+    const entry = root["bridge-api"];
+    if (!entry || typeof entry !== "object")
+        return { present: false };
+    const args = entry.args;
+    return {
+        present: true,
+        args: Array.isArray(args) ? args.filter((a) => typeof a === "string") : undefined,
+    };
+}
+/** Inspect a Codex TOML config for a `bridge-api` table (no env values read). */
+export async function inspectTomlHostEntry(path, deps) {
+    const read = await readTomlHostConfig(path, deps);
+    if (read.state !== "text")
+        return { present: false };
+    if (!codexHasBridgeTable(read.content))
+        return { present: false };
+    // Extract the args = [...] line from the main table for pin classification.
+    const m = read.content.match(/^\s*args\s*=\s*\[(.*?)\]/m);
+    let args;
+    if (m) {
+        args = m[1]
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+            .filter((s) => s.length > 0);
+    }
+    return { present: true, args };
+}
+/** Inspect any target (format-aware) for a `bridge-api` entry. */
+export async function inspectHostEntry(target, ctx, deps) {
+    const path = resolveTargetAbsPath(target, ctx);
+    return target.format === "toml"
+        ? inspectTomlHostEntry(path, deps)
+        : inspectJsonHostEntry(path, target, deps);
+}
+// ---------------------------------------------------------------------------
+// Vendor CLI invocation builders (argv-isolated; secret-bearing for some kinds)
+// ---------------------------------------------------------------------------
+/**
+ * Whether a vendor kind's secret-delivery contract is VERIFIED. Only verified
+ * contracts are ever invoked; an uncertain contract falls back to a direct
+ * write rather than guessing argv. Verified from empirical probes (BAPI-635):
+ * claude `mcp add-json <name> <json>` and copilot `mcp add --env` both deliver
+ * the secret through argv. Codex's contract is unverified (binary absent at
+ * authoring time) → never invoked; always direct-written.
+ */
+function isVendorContractVerified(kind) {
+    return kind === "claude-add-json" || kind === "copilot-add";
+}
+/**
+ * Build the vendor add invocation for a target. Returns `null` when the
+ * contract is unverified (caller must fall back to a direct write). The returned
+ * `args` may be secret-bearing and MUST be handed straight to the process
+ * boundary without logging.
+ */
+function buildVendorInvocation(target, entry) {
+    const vendor = target.vendorCli;
+    if (!vendor || !isVendorContractVerified(vendor.kind))
+        return null;
+    if (vendor.kind === "claude-add-json") {
+        // claude mcp add-json <name> <json> --scope project
+        // The JSON payload carries env.BAPI_API_KEY → secret-bearing argv.
+        const json = JSON.stringify({
+            command: entry.command,
+            args: entry.args,
+            env: entry.env,
+        });
+        return {
+            bin: vendor.bin,
+            args: ["mcp", "add-json", "bridge-api", json, "--scope", "project"],
+        };
+    }
+    if (vendor.kind === "copilot-add") {
+        // copilot mcp add bridge-api --tools "*" --env K=V ... -- <command> <args...>
+        // Env pairs (incl BAPI_API_KEY) are secret-bearing argv.
+        const envArgs = [];
+        for (const [k, v] of Object.entries(entry.env)) {
+            envArgs.push("--env", `${k}=${v}`);
+        }
+        return {
+            bin: vendor.bin,
+            args: [
+                "mcp",
+                "add",
+                "bridge-api",
+                "--tools",
+                "*",
+                ...envArgs,
+                "--",
+                entry.command,
+                ...entry.args,
+            ],
+        };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Provisioning orchestration
+// ---------------------------------------------------------------------------
+function outcome(target, status, detail) {
+    return {
+        platform: target.id,
+        status,
+        displayPath: target.displayPath,
+        detail,
+    };
+}
+/** Direct-write a single target (JSON or Codex TOML) and map to an outcome. */
+async function directWriteTarget(target, entry, deps) {
+    const path = resolveTargetAbsPath(target, deps);
+    if (target.format === "toml") {
+        const res = await writeCodexHostConfig(path, entry, deps.fs);
+        if (res.status === "manual-required") {
+            return outcome(target, "manual-required", "existing config could not be safely updated");
+        }
+        return outcome(target, "direct-written");
+    }
+    const adapted = adaptBridgeEntryForHostTarget(entry, target);
+    const res = await writeJsonHostConfig(path, target, adapted, deps.fs);
+    if (res.status === "skipped-invalid") {
+        return outcome(target, "skipped-invalid", res.message);
+    }
+    return outcome(target, "direct-written");
+}
+/**
+ * Provision a single host target, honoring its write strategy:
+ *   - manual-instructions → `manual-required`
+ *   - direct → JSON merge-write (or Codex safe write)
+ *   - vendor-first → probe + invoke the verified vendor CLI, verify the entry
+ *     landed, else fall back to a safe direct write. Any missing binary, spawn
+ *     error, timeout, non-zero exit, or missing post-write entry triggers the
+ *     fallback rather than a fatal error.
+ */
+export async function provisionHostTarget(target, entry, deps) {
+    if (target.writeStrategy === "manual-instructions") {
+        return outcome(target, "manual-required", "global config — manual setup");
+    }
+    if (target.writeStrategy === "direct") {
+        return directWriteTarget(target, entry, deps);
+    }
+    // vendor-first
+    const invocation = buildVendorInvocation(target, entry);
+    if (invocation) {
+        const available = await deps.vendor.probeBinary(invocation.bin, deps.env);
+        if (available) {
+            const result = await deps.vendor.invokeVendorAdd(invocation, deps.env);
+            if (result.ok) {
+                // Verify the entry actually landed before trusting the vendor CLI.
+                const inspected = await inspectHostEntry(target, deps, deps.fs);
+                if (inspected.present) {
+                    return outcome(target, "vendor-written");
+                }
+            }
+        }
+    }
+    // Fallback: safe direct write (covers unverified contracts like Codex, a
+    // missing/failed vendor binary, or a nominally-successful write that left no
+    // entry).
+    return directWriteTarget(target, entry, deps);
+}
+// ---------------------------------------------------------------------------
+// Default vendor process boundary (spawns real vendor CLIs, secret-safe)
+// ---------------------------------------------------------------------------
+/** Env keys stripped from a read-only probe environment. */
+const PROBE_SECRET_KEYS = ["BAPI_API_KEY", "BAPI_INVITE", "BAPI_SIGNUP_EMAIL"];
+/** Return a shallow env clone with credential sentinels removed. */
+export function sanitizeProbeEnv(env) {
+    const clone = { ...env };
+    for (const key of PROBE_SECRET_KEYS)
+        delete clone[key];
+    return clone;
+}
+/** The launcher spec for the current version (pins are version-locked). */
+export function currentLauncherSpec() {
+    return `@bridge_gpt/mcp-server@${VERSION}`;
+}
+/** Bounded probe/invoke timeout (ms). */
+const VENDOR_PROCESS_TIMEOUT_MS = 8000;
+/**
+ * Build the default vendor process boundary. Both operations use array-based
+ * spawning with `shell:false`, ignored stdio, a bounded timeout, and a sanitized
+ * env for the read-only probe. Every path resolves (never rejects) so a vendor
+ * failure is a fallback trigger, not a crash. Secret-bearing argv is passed
+ * straight to `spawn` and never logged.
+ */
+export function createDefaultVendorProcessDeps(spawnFn) {
+    return {
+        probeBinary: (bin, env) => new Promise((resolve) => {
+            let settled = false;
+            const done = (ok) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(ok);
+            };
+            try {
+                const child = spawnFn(bin, ["--version"], {
+                    stdio: "ignore",
+                    shell: false,
+                    env: sanitizeProbeEnv(env),
+                    timeout: VENDOR_PROCESS_TIMEOUT_MS,
+                });
+                child.on("error", () => done(false));
+                child.on("close", (code) => done(code === 0));
+            }
+            catch {
+                done(false);
+            }
+        }),
+        invokeVendorAdd: (invocation, env) => new Promise((resolve) => {
+            let settled = false;
+            const done = (ok) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve({ ok });
+            };
+            try {
+                const child = spawnFn(invocation.bin, invocation.args, {
+                    stdio: "ignore",
+                    shell: false,
+                    // The add command needs the credential sentinels in argv, not env;
+                    // env stays sanitized so nothing leaks through a second channel.
+                    env: sanitizeProbeEnv(env),
+                    timeout: VENDOR_PROCESS_TIMEOUT_MS,
+                });
+                child.on("error", () => done(false));
+                child.on("close", (code) => done(code === 0));
+            }
+            catch {
+                done(false);
+            }
+        }),
+    };
+}