@bridge_gpt/mcp-server 0.1.17 → 0.2.1

package/build/mcp-invoke.js

@@ -0,0 +1,417 @@
+/**
+ * `mcp-invoke` — internal worktree shim subcommand.
+ *
+ * Resolves an MCP target's launch command + environment from an explicit
+ * absolute `--project-root` (NEVER from `process.cwd()`), then spawns the real
+ * MCP server as a child of the current Node process with inherited stdio and
+ * forwarded signals/exit codes. Secrets are passed to the child ONLY through its
+ * environment — never in argv, logs, or error messages.
+ *
+ * Two target families:
+ *   - `bapi` — resolves Bridge API repo identity + `BAPI_API_KEY`, overlays the
+ *     three `BAPI_*` values, and spawns this same Node script (the real Bridge
+ *     API MCP server).
+ *   - any Tier-2 target declared in `.bridge/config` (e.g. `sfcc`) — reads the
+ *     manifest entry, resolves the target's required env overlay atomically from
+ *     the secret store, and spawns the manifest `command`/`args`.
+ *
+ * This file is the highest-risk surface of the worktree-credentials work: the
+ * stdio passthrough plus the signal/exit-code contract is covered exhaustively
+ * by its unit tests.
+ */
+import { spawn, execFile } from "child_process";
+import { stat, readFile } from "fs/promises";
+import path from "path";
+import os from "os";
+import { resolveRepoNameForProjectRoot, readBridgeConfig, validateMcpTarget, } from "./bridge-config.js";
+import { resolveBapiCredentials } from "./credential-store.js";
+import { getThirdPartyTargetDefinition, resolveThirdPartyTargetEnv, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
+// ---------------------------------------------------------------------------
+// Usage / argument parsing
+// ---------------------------------------------------------------------------
+export function getMcpInvokeUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
+        "",
+        "Internal worktree shim: resolves the target's launch command and credentials",
+        "from the given project root, then spawns the real MCP server over stdio.",
+        "",
+        "Flags:",
+        "  --target <target>            MCP target to launch. 'bapi' launches the Bridge",
+        "                               API server; a configured third-party target from",
+        "                               .bridge/config (e.g. sfcc) launches that server.",
+        "  --project-root <ABS_PATH>    Absolute path to the worktree (required)",
+        "  -h, --help                   Show this help",
+    ].join("\n");
+}
+const KNOWN_FLAGS = new Set(["--target", "--project-root"]);
+/**
+ * Parse `--target` and `--project-root` (split or `=` form). Rejects unknown
+ * flags, positional arguments, missing values, and duplicates. Requires a safe
+ * non-empty `--target` identifier and a host-platform-absolute `--project-root`.
+ */
+export function parseMcpInvokeArgs(argv) {
+    let target;
+    let projectRoot;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            return { status: "help", usage: getMcpInvokeUsage() };
+        }
+        let flag = token;
+        let value;
+        const eq = token.indexOf("=");
+        if (token.startsWith("--") && eq !== -1) {
+            flag = token.slice(0, eq);
+            value = token.slice(eq + 1);
+        }
+        if (!KNOWN_FLAGS.has(flag)) {
+            if (token.startsWith("-")) {
+                return { status: "error", message: `Unknown flag: ${flag}` };
+            }
+            return { status: "error", message: `Unexpected positional argument: ${token}` };
+        }
+        if (value === undefined) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                return { status: "error", message: `Missing value for ${flag}` };
+            }
+            value = next;
+            i++;
+        }
+        if (flag === "--target") {
+            if (target !== undefined) {
+                return { status: "error", message: "Duplicate --target flag" };
+            }
+            target = value;
+        }
+        else {
+            if (projectRoot !== undefined) {
+                return { status: "error", message: "Duplicate --project-root flag" };
+            }
+            projectRoot = value;
+        }
+    }
+    if (target === undefined) {
+        return { status: "error", message: "Missing required --target flag" };
+    }
+    const targetValidation = validateMcpTarget(target);
+    if (!targetValidation.ok) {
+        return { status: "error", message: `Invalid --target: ${targetValidation.error}` };
+    }
+    if (projectRoot === undefined) {
+        return { status: "error", message: "Missing required --project-root flag" };
+    }
+    if (!path.isAbsolute(projectRoot)) {
+        return { status: "error", message: "--project-root must be an absolute path" };
+    }
+    return { status: "ok", target: targetValidation.value, projectRoot };
+}
+// ---------------------------------------------------------------------------
+// Validation, env construction, signals
+// ---------------------------------------------------------------------------
+/** Fail fast when `--project-root` does not exist or is not a directory. */
+export async function validateProjectRootDirectory(projectRoot, statFn) {
+    try {
+        const result = await statFn(projectRoot);
+        if (!result.isDirectory()) {
+            return { ok: false, error: `--project-root is not a directory: ${projectRoot}` };
+        }
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, error: `--project-root does not exist: ${projectRoot}` };
+    }
+}
+/**
+ * Build the child environment: start from the parent env, overlay an arbitrary
+ * set of resolved values. The parent env object is never mutated; unrelated
+ * parent values (`BAPI_BASE_URL`, `BAPI_DOCS_DIR`, proxy variables, Node env)
+ * pass through unchanged. Overlay values are typically secrets and must only
+ * ever reach the child through this env object — never argv or logs.
+ */
+export function buildChildEnv(parentEnv, overlay) {
+    return { ...parentEnv, ...overlay };
+}
+/** Map a terminating signal to a conventional `128 + signum` exit code. */
+export function signalExitCode(signal) {
+    if (signal === "SIGINT")
+        return 130;
+    if (signal === "SIGTERM")
+        return 143;
+    const signals = os.constants.signals;
+    const num = signals[signal];
+    if (typeof num === "number")
+        return 128 + num;
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// Child server spawn
+// ---------------------------------------------------------------------------
+/**
+ * Spawn an MCP server child with the given command/args, inherited stdio, and
+ * the merged child env. SIGINT/SIGTERM received by the shim are forwarded to the
+ * child; the returned promise resolves once the child closes, propagating its
+ * numeric exit code (or the signal exit code). Signal handlers are registered
+ * after spawn and removed exactly once on close.
+ */
+export function spawnMcpCommand(deps) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = deps.spawn(deps.command, deps.args, {
+                stdio: "inherit",
+                env: deps.env,
+            });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        const signals = ["SIGINT", "SIGTERM"];
+        const handlers = {};
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            for (const sig of signals)
+                deps.offSignal(sig, handlers[sig]);
+        };
+        for (const sig of signals) {
+            const handler = () => {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* best-effort forward; the close handler still resolves */
+                }
+            };
+            handlers[sig] = handler;
+            deps.onSignal(sig, handler);
+        }
+        child.on("error", (err) => {
+            cleanup();
+            reject(err);
+        });
+        child.on("close", (...args) => {
+            cleanup();
+            const code = args[0];
+            const signal = args[1];
+            if (typeof code === "number") {
+                resolve(code);
+            }
+            else if (signal) {
+                resolve(signalExitCode(signal));
+            }
+            else {
+                resolve(0);
+            }
+        });
+    });
+}
+/**
+ * Back-compat wrapper: spawn the real Bridge API MCP server as
+ * `node <thisScript>` (no `mcp-invoke` subcommand args, so the child enters the
+ * normal no-subcommand startup path). Delegates to {@link spawnMcpCommand}.
+ */
+export function spawnRealMcpServer(deps) {
+    return spawnMcpCommand({
+        spawn: deps.spawn,
+        command: deps.execPath,
+        args: [deps.scriptPath],
+        env: deps.env,
+        onSignal: deps.onSignal,
+        offSignal: deps.offSignal,
+    });
+}
+// ---------------------------------------------------------------------------
+// Default production runners (used when overrides are not supplied)
+// ---------------------------------------------------------------------------
+function defaultRunCommand(file, args, options) {
+    return new Promise((resolve) => {
+        execFile(file, args, { cwd: options?.cwd }, (err, stdout, stderr) => {
+            if (err) {
+                const code = typeof err.code === "number"
+                    ? (err.code)
+                    : 1;
+                resolve({
+                    stdout: stdout?.toString() ?? "",
+                    stderr: stderr?.toString() ?? err.message,
+                    exitCode: code,
+                });
+            }
+            else {
+                resolve({ stdout: stdout.toString(), stderr: stderr.toString(), exitCode: 0 });
+            }
+        });
+    });
+}
+/**
+ * Resolve the Bridge API invocation: derive repo identity, resolve the API key
+ * (env→store), and overlay the three `BAPI_*` values onto the parent env. The
+ * spawned command is `process.execPath` with `[scriptPath]` (no subcommand args
+ * — the child runs the normal server). Secret-free errors on any failure.
+ */
+export async function resolveBapiInvocation(projectRoot, deps) {
+    const repoResult = await deps.resolveRepoName(projectRoot);
+    if (!repoResult.ok) {
+        return { ok: false, error: `failed to resolve repo identity: ${repoResult.error}` };
+    }
+    const repoName = repoResult.value;
+    const credResult = await deps.resolveCredentials(repoName, projectRoot);
+    if (!credResult.ok) {
+        return { ok: false, error: `failed to resolve credentials: ${credResult.error}` };
+    }
+    const env = buildChildEnv(deps.env, {
+        BAPI_API_KEY: credResult.credentials.apiKey,
+        BAPI_PROJECT_ROOT: projectRoot,
+        BAPI_REPO_NAME: repoName,
+    });
+    return {
+        ok: true,
+        invocation: { command: deps.execPath, args: [deps.scriptPath], env },
+    };
+}
+/**
+ * Resolve a Tier-2 third-party invocation: read `.bridge/config`, locate the
+ * requested target entry, resolve the target's required env overlay atomically
+ * from the secret store, and return the manifest `command`/`args` plus the
+ * overlaid child env. Credentials never enter argv. Secret-free errors.
+ */
+export async function resolveThirdPartyInvocation(target, projectRoot, deps) {
+    const definition = deps.getTargetDefinition(target);
+    if (!definition) {
+        return {
+            ok: false,
+            error: `unsupported MCP target '${target}'; not a known third-party target`,
+        };
+    }
+    const read = await deps.readBridgeConfig(projectRoot);
+    if (!read.ok) {
+        if (read.kind === "missing") {
+            return { ok: false, error: `target '${target}' requires a .bridge/config; none was found` };
+        }
+        return { ok: false, error: `unable to read .bridge/config for target '${target}'` };
+    }
+    const entry = read.manifest.mcp.find((m) => m.target === target);
+    if (!entry) {
+        return {
+            ok: false,
+            error: `target '${target}' is not declared in .bridge/config`,
+        };
+    }
+    const entryValidation = validateThirdPartyTargetManifestEntry(entry);
+    if (!entryValidation.ok) {
+        return { ok: false, error: entryValidation.error };
+    }
+    // After validation these are guaranteed present.
+    const command = entry.command;
+    const args = entry.args;
+    const secretBundle = entry.secretBundle;
+    const envResult = await deps.resolveTargetEnv(definition, secretBundle);
+    if (!envResult.ok) {
+        return { ok: false, error: `failed to resolve credentials for '${target}': ${envResult.error}` };
+    }
+    const env = buildChildEnv(deps.env, envResult.env);
+    return { ok: true, invocation: { command, args, env } };
+}
+/**
+ * Run the `mcp-invoke` subcommand. Returns a process exit code (never calls
+ * `process.exit`). Parses args BEFORE any validation/resolution; validates the
+ * project root; dispatches `bapi` to {@link resolveBapiInvocation} and any other
+ * target to {@link resolveThirdPartyInvocation}; then spawns. Any failure prints
+ * an actionable, secret-free message to stderr and returns non-zero without
+ * spawning.
+ */
+export async function runMcpInvokeCli(argv, overrides = {}) {
+    const log = overrides.log ?? ((m) => process.stdout.write(`${m}\n`));
+    const stderr = overrides.stderr ?? ((m) => process.stderr.write(`${m}\n`));
+    const env = overrides.env ?? process.env;
+    const parsed = parseMcpInvokeArgs(argv);
+    if (parsed.status === "help") {
+        log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        stderr(`Error: ${parsed.message}`);
+        stderr("");
+        stderr(getMcpInvokeUsage());
+        return 1;
+    }
+    const { target, projectRoot } = parsed;
+    const statFn = overrides.stat ?? ((p) => stat(p));
+    const dirCheck = await validateProjectRootDirectory(projectRoot, statFn);
+    if (!dirCheck.ok) {
+        stderr(`Error: ${dirCheck.error}`);
+        return 1;
+    }
+    const credentialDeps = {
+        env,
+        homedir: os.homedir,
+        platform: process.platform,
+        readFile: (p) => readFile(p, "utf-8"),
+        stat: (p) => stat(p),
+        stderr,
+    };
+    if (target === "bapi") {
+        const resolveRepoName = overrides.resolveRepoName ??
+            ((pr) => resolveRepoNameForProjectRoot(pr, {
+                readFile: (p) => readFile(p, "utf-8"),
+                runCommand: defaultRunCommand,
+            }));
+        const resolveCredentials = overrides.resolveCredentials ??
+            ((rn) => resolveBapiCredentials(rn, credentialDeps));
+        const resolved = await resolveBapiInvocation(projectRoot, {
+            env,
+            execPath: process.execPath,
+            scriptPath: process.argv[1],
+            resolveRepoName,
+            resolveCredentials,
+        });
+        if (!resolved.ok) {
+            stderr(`Error: ${resolved.error}`);
+            return 1;
+        }
+        return spawnInvocation(resolved.invocation, overrides);
+    }
+    // Tier-2 third-party target.
+    const readConfig = overrides.readBridgeConfig ??
+        ((pr) => readBridgeConfig(pr, { readFile: (p) => readFile(p, "utf-8") }));
+    const getTargetDefinition = overrides.getTargetDefinition ?? getThirdPartyTargetDefinition;
+    const resolveTargetEnv = overrides.resolveThirdPartyEnv ??
+        ((definition, secretBundle) => resolveThirdPartyTargetEnv(definition, secretBundle, credentialDeps));
+    const resolved = await resolveThirdPartyInvocation(target, projectRoot, {
+        env,
+        readBridgeConfig: readConfig,
+        getTargetDefinition,
+        resolveTargetEnv,
+    });
+    if (!resolved.ok) {
+        stderr(`Error: ${resolved.error}`);
+        return 1;
+    }
+    return spawnInvocation(resolved.invocation, overrides);
+}
+/** Spawn a resolved invocation, honoring the legacy and generic spawn overrides. */
+function spawnInvocation(invocation, overrides) {
+    if (overrides.spawnMcpCommand) {
+        return overrides.spawnMcpCommand(invocation);
+    }
+    if (overrides.spawnRealMcpServer) {
+        return overrides.spawnRealMcpServer(invocation.env);
+    }
+    return spawnMcpCommand({
+        spawn: spawn,
+        command: invocation.command,
+        args: invocation.args,
+        env: invocation.env,
+        onSignal: (s, h) => {
+            process.on(s, h);
+        },
+        offSignal: (s, h) => {
+            process.off(s, h);
+        },
+    });
+}