@bridge_gpt/mcp-server 0.2.25 → 0.2.26

package/build/mcp-host-targets.js

@@ -0,0 +1,194 @@
+/**
+ * Data-only MCP host-target registry (BAPI-635).
+ *
+ * Every TypeScript mapping of an AI-coding platform to its MCP config format,
+ * path, scope, root key, transport type, write strategy, and vendor CLI lives
+ * here as a single additive, data-only registry — mirroring the convention in
+ * {@link file:./third-party-mcp-targets.ts}. Downstream consumers (install-bridge,
+ * init, mcp-provisioning, doctor, install-doctor) project this registry rather
+ * than re-declaring platform path/key literals.
+ *
+ * This module performs NO I/O. Detection callbacks receive an injected
+ * {@link HostDetectionContext} (cwd, homedir, env, exists) so the registry
+ * performs no direct filesystem, subprocess, home-directory, or environment
+ * reads — every input arrives through the injected context. Adding a new
+ * platform is a matter of adding one entry to {@link MCP_HOST_TARGETS} plus its
+ * `PlatformId` union member.
+ */
+// ---------------------------------------------------------------------------
+// Path helpers (pure)
+// ---------------------------------------------------------------------------
+/** POSIX-style join that avoids importing node:path (keeps module I/O-free). */
+function joinPath(base, rel) {
+    const trimmedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+    const trimmedRel = rel.startsWith("/") ? rel.slice(1) : rel;
+    return `${trimmedBase}/${trimmedRel}`;
+}
+// ---------------------------------------------------------------------------
+// Registry — additive; add a new entry (and a PlatformId member) per platform.
+// ---------------------------------------------------------------------------
+/**
+ * The single source of truth for every platform's MCP host mapping. Consumers
+ * MUST project this registry rather than re-declaring path/key literals.
+ */
+export const MCP_HOST_TARGETS = {
+    "claude-code": {
+        id: "claude-code",
+        label: "Claude Code",
+        scope: "project",
+        relPath: ".mcp.json",
+        displayPath: ".mcp.json",
+        format: "json",
+        topLevelKey: "mcpServers",
+        transportType: undefined, // Claude Code omits `type`.
+        vendorCli: { bin: "claude", kind: "claude-add-json" },
+        worktreeSupported: true,
+        writeStrategy: "vendor-first",
+        // Claude Code is always a candidate default.
+        detect: () => true,
+    },
+    cursor: {
+        id: "cursor",
+        label: "Cursor",
+        scope: "project",
+        relPath: ".cursor/mcp.json",
+        displayPath: ".cursor/mcp.json",
+        format: "json",
+        topLevelKey: "mcpServers",
+        transportType: "stdio",
+        worktreeSupported: true,
+        writeStrategy: "direct",
+        detect: (ctx) => ctx.exists(joinPath(ctx.cwd, ".cursor")) ||
+            typeof ctx.env.CURSOR_TRACE_DIR === "string" &&
+                ctx.env.CURSOR_TRACE_DIR.length > 0,
+    },
+    "copilot-vscode": {
+        id: "copilot-vscode",
+        label: "GitHub Copilot (VS Code)",
+        scope: "project",
+        relPath: ".vscode/mcp.json",
+        displayPath: ".vscode/mcp.json",
+        format: "json",
+        topLevelKey: "servers",
+        transportType: "stdio",
+        worktreeSupported: false,
+        writeStrategy: "direct",
+        detect: (ctx) => ctx.exists(joinPath(ctx.cwd, ".vscode")),
+    },
+    "copilot-cli": {
+        id: "copilot-cli",
+        label: "GitHub Copilot CLI",
+        scope: "global",
+        absPathResolver: (homedir) => joinPath(homedir, ".copilot/mcp-config.json"),
+        displayPath: "~/.copilot/mcp-config.json",
+        format: "json",
+        topLevelKey: "mcpServers",
+        transportType: "local",
+        extraEntryKeys: { tools: ["*"] },
+        vendorCli: { bin: "copilot", kind: "copilot-add" },
+        worktreeSupported: false,
+        writeStrategy: "vendor-first",
+        // No existing probe supports Copilot CLI; never a default.
+        detect: () => false,
+    },
+    codex: {
+        id: "codex",
+        label: "OpenAI Codex",
+        scope: "global",
+        absPathResolver: (homedir) => joinPath(homedir, ".codex/config.toml"),
+        displayPath: "~/.codex/config.toml",
+        format: "toml",
+        topLevelKey: "mcp_servers",
+        transportType: undefined, // TOML table shape has no `type`.
+        vendorCli: { bin: "codex", kind: "codex-add" },
+        worktreeSupported: false,
+        writeStrategy: "vendor-first",
+        detect: (ctx) => ctx.exists(joinPath(ctx.homedir, ".codex")),
+    },
+    windsurf: {
+        id: "windsurf",
+        label: "Windsurf",
+        scope: "global",
+        absPathResolver: (homedir) => joinPath(homedir, ".codeium/windsurf/mcp_config.json"),
+        displayPath: "~/.codeium/windsurf/mcp_config.json",
+        format: "json",
+        topLevelKey: "mcpServers",
+        // Windsurf historically renders with no `type` (like Claude); preserve that.
+        transportType: undefined,
+        worktreeSupported: false,
+        // Preserve current behavior: never auto-modify the global Windsurf file.
+        writeStrategy: "manual-instructions",
+        detect: (ctx) => ctx.exists(joinPath(ctx.cwd, ".windsurf")) ||
+            ctx.exists(joinPath(ctx.cwd, ".windsurfrules")),
+    },
+};
+/** Stable registry order for deterministic prompts, previews, and reports. */
+export const HOST_PLATFORM_ORDER = [
+    "claude-code",
+    "cursor",
+    "copilot-vscode",
+    "copilot-cli",
+    "codex",
+    "windsurf",
+];
+// ---------------------------------------------------------------------------
+// Projections & lookups (pure)
+// ---------------------------------------------------------------------------
+/** All registry definitions in stable {@link HOST_PLATFORM_ORDER}. */
+export function allHostTargets() {
+    return HOST_PLATFORM_ORDER.map((id) => MCP_HOST_TARGETS[id]);
+}
+/** Whether a string is a registered platform ID. */
+export function isHostPlatformId(value) {
+    return Object.prototype.hasOwnProperty.call(MCP_HOST_TARGETS, value);
+}
+/** Look up a definition by ID, or `undefined`. */
+export function getHostTarget(id) {
+    return isHostPlatformId(id) ? MCP_HOST_TARGETS[id] : undefined;
+}
+/** The two worktree-supported targets, in stable order (Claude, Cursor). */
+export function getWorktreeHostTargets() {
+    return allHostTargets().filter((t) => t.worktreeSupported);
+}
+/** Project-scoped JSON targets (used by init, launcher-token merge, doctor). */
+export function getProjectJsonTargets() {
+    return allHostTargets().filter((t) => t.scope === "project" && t.format === "json");
+}
+/** Targets written automatically (vendor-first or direct). */
+export function getAutomaticHostTargets() {
+    return allHostTargets().filter((t) => t.writeStrategy !== "manual-instructions");
+}
+/** Targets that only ever emit manual instructions. */
+export function getManualHostTargets() {
+    return allHostTargets().filter((t) => t.writeStrategy === "manual-instructions");
+}
+/**
+ * Resolve the absolute filesystem path for a target from an injected context.
+ * Project targets resolve below `ctx.cwd`; global targets below `ctx.homedir`.
+ */
+export function resolveHostTargetPath(target, ctx) {
+    if (target.scope === "project") {
+        if (!target.relPath) {
+            throw new Error(`project target ${target.id} is missing relPath`);
+        }
+        return joinPath(ctx.cwd, target.relPath);
+    }
+    if (!target.absPathResolver) {
+        throw new Error(`global target ${target.id} is missing absPathResolver`);
+    }
+    return target.absPathResolver(ctx.homedir);
+}
+/** The user-facing display path for a target (never an absolute home path). */
+export function displayPathForTarget(target) {
+    return target.displayPath;
+}
+/**
+ * Run detection across every registry entry and return the set of platform IDs
+ * whose `detect` callback is true — the seed for interactive multi-select
+ * defaults.
+ */
+export function detectDefaultPlatforms(ctx) {
+    return allHostTargets()
+        .filter((t) => t.detect(ctx))
+        .map((t) => t.id);
+}

package/build/mcp-install-state.js

@@ -0,0 +1,175 @@
+/**
+ * Per-developer MCP install-state persistence (BAPI-635).
+ *
+ * Records which host platforms a developer selected during `install-bridge`, so
+ * the install skill and `doctor` can report selected-vs-present configuration
+ * without re-detecting. The state file `.bridge/install-state.json` is
+ * per-developer and is gitignored before it is written.
+ *
+ * SECURITY: the state is strictly SECRET-FREE. It stores only a validated
+ * platform roster and repo-relative project config paths. It never contains API
+ * keys, env blocks, absolute home paths, or vendor command payloads. Reads
+ * validate every stored platform ID against {@link MCP_HOST_TARGETS}; writes
+ * serialize only the schema-approved fields.
+ *
+ * All filesystem access is through injected dependencies so the module is fully
+ * unit-testable with in-memory fakes.
+ */
+import { HOST_PLATFORM_ORDER, isHostPlatformId, } from "./mcp-host-targets.js";
+/** Current on-disk schema version. */
+export const MCP_INSTALL_STATE_VERSION = 1;
+/** The relative path of the state file within a project. */
+export const MCP_INSTALL_STATE_RELPATH = ".bridge/install-state.json";
+// ---------------------------------------------------------------------------
+// Path helpers (POSIX-normalized; avoids node:path so tests are deterministic).
+// ---------------------------------------------------------------------------
+function joinCwd(cwd, rel) {
+    const base = cwd.endsWith("/") ? cwd.slice(0, -1) : cwd;
+    return `${base}/${rel}`;
+}
+/** Absolute path of the install-state file for a project. */
+export function installStatePath(cwd) {
+    return joinCwd(cwd, MCP_INSTALL_STATE_RELPATH);
+}
+/** Absolute path of the atomic temp file used during writes. */
+function installStateTempPath(cwd) {
+    return joinCwd(cwd, `${MCP_INSTALL_STATE_RELPATH}.tmp`);
+}
+function bridgeDirPath(cwd) {
+    return joinCwd(cwd, ".bridge");
+}
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+/** Dedupe + order platform IDs by the stable registry order. */
+function normalizePlatforms(ids) {
+    const wanted = new Set(ids);
+    return HOST_PLATFORM_ORDER.filter((id) => wanted.has(id));
+}
+/** Dedupe + stably order relative project config paths. */
+function normalizeProjectPaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        if (typeof p === "string" && p.length > 0 && !seen.has(p)) {
+            seen.add(p);
+            out.push(p);
+        }
+    }
+    out.sort();
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+function isEnoent(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+/**
+ * Read and validate the install-state file. Returns a structured outcome; never
+ * throws for the ordinary missing/malformed/invalid cases and never resolves an
+ * arbitrary path from untrusted platform IDs.
+ */
+export async function readMcpInstallState(cwd, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(installStatePath(cwd));
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return { status: "missing" };
+        // A non-ENOENT read error is treated as missing state, not a crash.
+        return { status: "missing" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { status: "malformed" };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { status: "malformed" };
+    }
+    const doc = parsed;
+    if (doc.version !== MCP_INSTALL_STATE_VERSION) {
+        return { status: "unsupported-version", version: doc.version };
+    }
+    const rawPlatforms = doc.selectedPlatforms;
+    if (!Array.isArray(rawPlatforms)) {
+        return { status: "invalid", reason: "selectedPlatforms is not an array" };
+    }
+    for (const id of rawPlatforms) {
+        if (typeof id !== "string" || !isHostPlatformId(id)) {
+            return {
+                status: "invalid",
+                reason: `unknown platform id in selectedPlatforms`,
+            };
+        }
+    }
+    const rawPaths = doc.projectConfigPaths;
+    if (rawPaths !== undefined && !Array.isArray(rawPaths)) {
+        return { status: "invalid", reason: "projectConfigPaths is not an array" };
+    }
+    const projectConfigPaths = Array.isArray(rawPaths)
+        ? rawPaths.filter((p) => typeof p === "string")
+        : [];
+    return {
+        status: "valid",
+        state: {
+            version: MCP_INSTALL_STATE_VERSION,
+            selectedPlatforms: normalizePlatforms(rawPlatforms),
+            projectConfigPaths: normalizeProjectPaths(projectConfigPaths),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+/** Serialize an install-state document deterministically (stable key order). */
+export function serializeMcpInstallState(state) {
+    // Explicit key order — do not rely on object insertion order for stability.
+    const ordered = {
+        version: state.version,
+        selectedPlatforms: state.selectedPlatforms,
+        projectConfigPaths: state.projectConfigPaths,
+    };
+    return JSON.stringify(ordered, null, 2) + "\n";
+}
+/**
+ * Write the install-state file deterministically and atomically (temp file then
+ * rename). Only schema-approved fields are serialized; any extra input data is
+ * ignored, so no secret, env block, absolute home path, or vendor payload can
+ * reach the file. On failure, attempts best-effort temp cleanup and returns a
+ * secret-free error without reporting success.
+ */
+export async function writeMcpInstallState(cwd, input, deps) {
+    const state = {
+        version: MCP_INSTALL_STATE_VERSION,
+        selectedPlatforms: normalizePlatforms(input.selectedPlatforms),
+        projectConfigPaths: normalizeProjectPaths(input.projectConfigPaths),
+    };
+    const finalPath = installStatePath(cwd);
+    const tempPath = installStateTempPath(cwd);
+    const serialized = serializeMcpInstallState(state);
+    try {
+        await deps.mkdir(bridgeDirPath(cwd), { recursive: true });
+        await deps.writeFile(tempPath, serialized);
+        await deps.rename(tempPath, finalPath);
+    }
+    catch (err) {
+        if (deps.unlink) {
+            try {
+                await deps.unlink(tempPath);
+            }
+            catch {
+                // Best-effort cleanup only; ignore secondary failures.
+            }
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `failed to persist install state: ${message}` };
+    }
+    return { ok: true, path: finalPath, state };
+}