@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/plane/defaults.js

@@ -0,0 +1,266 @@
+/**
+ * Real-I/O dependency factories for the plane (BAPI-756).
+ *
+ * Every plane module takes its filesystem, network, process, clock, and spawn
+ * capabilities as injected dependencies so unit tests never touch a real
+ * socket, credential store, or child process. This file is the one place those
+ * dependencies are bound to the actual platform, which keeps the seam honest:
+ * if a module reached for `node:fs` directly, it would show up here as an
+ * unused factory rather than hiding inside the logic.
+ */
+import { createWriteStream, realpathSync, statSync } from "fs";
+import { mkdir, open, readdir, readFile, rename, stat, unlink, writeFile } from "fs/promises";
+import { execFile as execFileCb, spawn as nodeSpawn } from "child_process";
+import net from "net";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { isProcessAlive } from "./manifest.js";
+/** Filesystem primitives bound to `node:fs/promises`. */
+export function createPlaneFsDeps() {
+    return {
+        readFile: (filePath) => readFile(filePath, "utf-8"),
+        writeFile: (filePath, data) => writeFile(filePath, data, "utf-8"),
+        createExclusive: async (filePath, data) => {
+            // `wx` is the atomic mutual-exclusion primitive the manifest claim relies
+            // on: it fails with EEXIST rather than truncating a competing plane's file.
+            const handle = await open(filePath, "wx");
+            try {
+                await handle.writeFile(data, "utf-8");
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        rename: (from, to) => rename(from, to),
+        unlink: (filePath) => unlink(filePath),
+        mkdir: async (dirPath) => {
+            await mkdir(dirPath, { recursive: true });
+        },
+        stat: async (filePath) => {
+            const result = await stat(filePath);
+            return { mtimeMs: result.mtimeMs };
+        },
+        readdir: async (dirPath) => {
+            const entries = await readdir(dirPath, { withFileTypes: true });
+            return entries.map((entry) => ({
+                name: entry.name,
+                isDirectory: () => entry.isDirectory(),
+                isFile: () => entry.isFile(),
+            }));
+        },
+    };
+}
+/** Wall-clock time and real sleeps. */
+export function createPlaneClock() {
+    return {
+        now: () => new Date(),
+        sleep: (ms) => new Promise((resolve) => {
+            setTimeout(resolve, ms).unref?.();
+        }),
+    };
+}
+/** Liveness and signal delivery bound to `process.kill`. */
+export function createPlaneProcessDeps() {
+    return {
+        isAlive: (pid) => isProcessAlive(pid, (target, signal) => process.kill(target, signal)),
+        signal: (pid, signal) => {
+            try {
+                process.kill(pid, signal);
+                return "sent";
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code === "ESRCH")
+                    return "no-such-process";
+                if (code === "EPERM")
+                    return "permission-denied";
+                return "error";
+            }
+        },
+    };
+}
+/**
+ * Bounded TCP connect probe.
+ *
+ * Connect-only, never bind: binding to test a port would itself occupy it, and
+ * a failed unbind would leave the plane unable to start.
+ */
+export function probeTcpPort(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(result);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish({ kind: "connected" }));
+        socket.once("timeout", () => finish({ kind: "error", error: "probe timed out" }));
+        socket.once("error", (err) => {
+            if (err.code === "ECONNREFUSED")
+                finish({ kind: "refused" });
+            else
+                finish({ kind: "error", error: err.code ?? "probe failed" });
+        });
+        socket.connect(port, host);
+    });
+}
+/** `execFile`, argument arrays only. No shell, ever. */
+export function createPlaneExecFile() {
+    return (file, args, options) => new Promise((resolve) => {
+        execFileCb(file, args, { cwd: options.cwd, shell: false, windowsHide: true, timeout: 30_000 }, (error, stdout, stderr) => {
+            if (error) {
+                const code = error.code;
+                resolve({ ok: false, error: typeof code === "string" ? code : "command failed" });
+                return;
+            }
+            resolve({ ok: true, stdout: String(stdout), stderr: String(stderr) });
+        });
+    });
+}
+/** Child spawning. `shell: false` is pinned: argv arrays only, never a string. */
+export function createPlaneSpawn() {
+    return (command, args, options) => {
+        const child = nodeSpawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            detached: options.detached,
+            shell: false,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return child;
+    };
+}
+/** Append-mode member log streams. */
+export function createMemberLogDeps() {
+    return {
+        openAppendStream: (absolutePath) => {
+            const stream = createWriteStream(absolutePath, { flags: "a" });
+            stream.on("error", () => {
+                /* a log write failure degrades observability, never the plane */
+            });
+            return {
+                write: (chunk) => {
+                    stream.write(chunk);
+                },
+                end: () => stream.end(),
+            };
+        },
+    };
+}
+/** Registers a signal handler and returns a disposer. */
+export function registerSignalHandler(signal, handler) {
+    process.on(signal, handler);
+    return () => {
+        process.off(signal, handler);
+    };
+}
+/**
+ * Absolute path of the compiled entrypoint belonging to the artifact that is
+ * currently executing (BAPI-768).
+ *
+ * ## Why this cannot be path arithmetic
+ *
+ * This package ships in two layouts, and `npm run build` produces both:
+ *
+ * - **tsc-emitted** — this module is `build/plane/defaults.js`, and the
+ *   entrypoint is one directory up at `build/index.js`.
+ * - **esbuild-bundled** — `scripts/bundle-esbuild.js` inlines this module *into*
+ *   `build/index.js` and overwrites it, so `import.meta.url` becomes the
+ *   entrypoint itself and the directory hop lands outside `build/` entirely.
+ *
+ * The original implementation hard-coded the first mapping. In the shipped
+ * bundle it returned `mcp_server/index.js`, which has never existed; the
+ * detached runtime spawn of that path died with `ERR_MODULE_NOT_FOUND` before it
+ * could write anything, and `plane up` printed its success banner over the
+ * corpse. So this resolver *probes* instead of assuming, and every candidate
+ * must be an existing regular file before it is returned.
+ *
+ * ## Why identity, not location
+ *
+ * Candidates come only from this module's own URL and from Node's actual
+ * invocation target. `repoRoot`, `process.cwd()`, and any assumed package
+ * location are excluded on purpose: re-execing "an entrypoint that looks right"
+ * from a sibling worktree would silently run a *different build* than the one
+ * the operator launched, which is the stale-build trap wearing a new hat.
+ */
+export function resolvePackageEntrypoint(overrides = {}) {
+    const deps = {
+        moduleUrl: overrides.moduleUrl ?? import.meta.url,
+        argv1: overrides.argv1 ?? process.argv[1],
+        realpath: overrides.realpath ?? defaultRealpath,
+        isFile: overrides.isFile ?? defaultIsFile,
+    };
+    const moduleFile = moduleFilePath(deps.moduleUrl);
+    const candidates = [];
+    if (moduleFile !== null) {
+        const dir = path.dirname(moduleFile);
+        // Bundled layout: this module IS the entrypoint. Checked first so the
+        // parent-directory candidate below can never win in a bundle.
+        if (path.basename(moduleFile) === "index.js")
+            candidates.push(moduleFile);
+        // A sibling entrypoint covers a bundle emitted under a different bin name.
+        candidates.push(path.join(dir, "index.js"));
+        // tsc layout: `build/plane/defaults.js` → `build/index.js`.
+        candidates.push(path.join(dir, "..", "index.js"));
+    }
+    // Last resort, and only ever a *validated* one: a packaged install launches
+    // through a `node_modules/.bin` symlink, so the invocation target must be
+    // canonicalized before it can identify the real package build.
+    if (typeof deps.argv1 === "string" && deps.argv1.length > 0) {
+        candidates.push(deps.argv1);
+    }
+    const seen = new Set();
+    for (const candidate of candidates) {
+        // Canonicalize BEFORE probing: it collapses duplicates that differ only by
+        // symlink or `..` segment, and it rejects a dangling symlink outright rather
+        // than letting it reach the regular-file check.
+        const canonical = deps.realpath(candidate);
+        if (canonical === null)
+            continue;
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        if (deps.isFile(canonical))
+            return { ok: true, entrypoint: canonical };
+    }
+    return { ok: false, candidatesChecked: seen.size };
+}
+/** `file://` URL → filesystem path, or `null` when the URL is unusable. */
+function moduleFilePath(moduleUrl) {
+    try {
+        return fileURLToPath(moduleUrl);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultRealpath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultIsFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Node executable used for the runtime re-exec and executor members. */
+export function resolveNodeExecutable() {
+    return process.execPath;
+}
+/** Home directory seam used by the credential resolver. */
+export function resolveHomedir() {
+    return os.homedir();
+}

package/build/plane/manifest.js

@@ -0,0 +1,377 @@
+/**
+ * Plane manifest: the durable source of lifecycle truth (BAPI-756).
+ *
+ * `plane status` and `plane down` run in a different process from the
+ * supervisor, so this file is the only thing they can trust. Three properties
+ * make that safe:
+ *
+ * 1. **Strict parsing precedes every action.** A pid is never signalled, and a
+ *    file is never replaced, until the whole record has validated. An
+ *    attacker-controlled or corrupted manifest must not become a kill list.
+ * 2. **Ownership is atomic.** Claiming uses an exclusive create, so two
+ *    successful preflights cannot both start spawning. A manifest that preflight
+ *    classified as stale is re-validated while the claim is held, because the
+ *    gap between "preflight looked" and "we are about to overwrite" is exactly
+ *    where a competing plane can appear.
+ * 3. **Nothing secret is persisted.** The schema has no environment object, no
+ *    argv, and no credential field, and unknown keys are rejected outright.
+ */
+import path from "path";
+import { PLANE_MANIFEST_FILENAME, PLANE_MANIFEST_SCHEMA_VERSION, PLANE_RUNTIME_DIR, } from "./types.js";
+/**
+ * Derive every runtime path beneath a validated repository root.
+ *
+ * Member log paths are a pure function of the fixed member name, so no
+ * externally supplied value — repository name, credential metadata, operator
+ * argument — can steer a write outside `.bridge/plane/`.
+ */
+export function getPlanePaths(repoRoot) {
+    const planeDir = path.join(repoRoot, ".bridge", "plane");
+    return {
+        planeDir,
+        manifestPath: path.join(planeDir, PLANE_MANIFEST_FILENAME),
+        logPathFor: (member) => path.join(planeDir, `${member}.log`),
+    };
+}
+/** Repository-relative log path recorded in the manifest for a member. */
+export function relativeLogPathFor(member) {
+    return `${PLANE_RUNTIME_DIR}/${member}.log`;
+}
+const VALID_STATES = new Set([
+    "spawning",
+    "running",
+    "ready",
+    "exited",
+]);
+const MANIFEST_KEYS = new Set([
+    "schemaVersion",
+    "planeId",
+    "repoRoot",
+    "supervisorPid",
+    "supervisorPgid",
+    "createdAt",
+    "updatedAt",
+    "members",
+]);
+const MEMBER_KEYS = new Set([
+    "name",
+    "pid",
+    "state",
+    "exitCode",
+    "exitSignal",
+    "logPath",
+]);
+/** `server`, `worker`, or `executor-<positive integer>`. Nothing else. */
+export function isPlaneMemberName(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value === "server" || value === "worker")
+        return true;
+    return /^executor-[1-9][0-9]*$/.test(value);
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isIsoTimestamp(value) {
+    return typeof value === "string" && value.length > 0 && !Number.isNaN(Date.parse(value));
+}
+/**
+ * Validate an untrusted parsed-JSON value into a manifest.
+ *
+ * Unknown keys are a hard rejection rather than an ignored extra: that is what
+ * makes "the manifest cannot carry a secret" a checkable property instead of a
+ * convention someone can quietly break.
+ */
+export function parsePlaneManifest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, error: "manifest is not an object" };
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!MANIFEST_KEYS.has(key)) {
+            return { ok: false, error: `manifest has an unsupported field '${key}'` };
+        }
+    }
+    if (record.schemaVersion !== PLANE_MANIFEST_SCHEMA_VERSION) {
+        return { ok: false, error: "manifest schema version is not supported" };
+    }
+    if (typeof record.planeId !== "string" || !/^[0-9a-f-]{8,}$/i.test(record.planeId)) {
+        return { ok: false, error: "manifest plane identity is missing or malformed" };
+    }
+    if (typeof record.repoRoot !== "string" || record.repoRoot.length === 0) {
+        return { ok: false, error: "manifest repository root is missing" };
+    }
+    if (!isPositiveInteger(record.supervisorPid)) {
+        return { ok: false, error: "manifest supervisor pid is not a positive integer" };
+    }
+    if (!isPositiveInteger(record.supervisorPgid)) {
+        return { ok: false, error: "manifest supervisor process-group id is not a positive integer" };
+    }
+    if (!isIsoTimestamp(record.createdAt) || !isIsoTimestamp(record.updatedAt)) {
+        return { ok: false, error: "manifest timestamps are missing or malformed" };
+    }
+    if (!Array.isArray(record.members) || record.members.length === 0) {
+        return { ok: false, error: "manifest members are missing" };
+    }
+    const members = [];
+    const seen = new Set();
+    for (const raw of record.members) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return { ok: false, error: "manifest member is not an object" };
+        }
+        const member = raw;
+        for (const key of Object.keys(member)) {
+            if (!MEMBER_KEYS.has(key)) {
+                return { ok: false, error: `manifest member has an unsupported field '${key}'` };
+            }
+        }
+        if (!isPlaneMemberName(member.name)) {
+            return { ok: false, error: "manifest member name is not a recognized plane member" };
+        }
+        if (seen.has(member.name)) {
+            return { ok: false, error: `manifest lists member '${member.name}' more than once` };
+        }
+        seen.add(member.name);
+        if (member.pid !== null && !isPositiveInteger(member.pid)) {
+            return { ok: false, error: `manifest member '${member.name}' has an invalid pid` };
+        }
+        if (typeof member.state !== "string" || !VALID_STATES.has(member.state)) {
+            return { ok: false, error: `manifest member '${member.name}' has an invalid state` };
+        }
+        if (member.exitCode !== null && !Number.isSafeInteger(member.exitCode)) {
+            return { ok: false, error: `manifest member '${member.name}' has an invalid exit code` };
+        }
+        if (member.exitSignal !== null && typeof member.exitSignal !== "string") {
+            return { ok: false, error: `manifest member '${member.name}' has an invalid exit signal` };
+        }
+        // Containment is exact-match, not prefix-match: a `..` segment or an
+        // absolute path can never satisfy the one legal spelling for this member.
+        if (member.logPath !== relativeLogPathFor(member.name)) {
+            return { ok: false, error: `manifest member '${member.name}' has an unexpected log path` };
+        }
+        members.push({
+            name: member.name,
+            pid: member.pid,
+            state: member.state,
+            exitCode: member.exitCode,
+            exitSignal: member.exitSignal,
+            logPath: member.logPath,
+        });
+    }
+    return {
+        ok: true,
+        manifest: {
+            schemaVersion: PLANE_MANIFEST_SCHEMA_VERSION,
+            planeId: record.planeId,
+            repoRoot: record.repoRoot,
+            supervisorPid: record.supervisorPid,
+            supervisorPgid: record.supervisorPgid,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            members,
+        },
+    };
+}
+/**
+ * Read and validate the manifest, distinguishing every outcome.
+ *
+ * `malformed` and `unreadable` deliberately carry no pid: a record that failed
+ * validation must not hand the caller an actionable kill target.
+ */
+export async function readPlaneManifest(repoRoot, fs) {
+    const { manifestPath } = getPlanePaths(repoRoot);
+    let raw;
+    try {
+        raw = await fs.readFile(manifestPath);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "unreadable", error: typeof code === "string" ? code : "read failed" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "malformed", error: "manifest is not valid JSON" };
+    }
+    const result = parsePlaneManifest(parsed);
+    if (!result.ok)
+        return { kind: "malformed", error: result.error };
+    return { kind: "valid", manifest: result.manifest };
+}
+/**
+ * Signal-zero liveness.
+ *
+ * `EPERM` means the process exists but belongs to someone else — evidence of
+ * life, never of death. Any other error is `unknown`, which callers must not
+ * collapse into "safely gone".
+ */
+export function isProcessAlive(pid, kill) {
+    if (!isPositiveInteger(pid))
+        return "unknown";
+    try {
+        kill(pid, 0);
+        return "alive";
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ESRCH")
+            return "dead";
+        if (code === "EPERM")
+            return "alive";
+        return "unknown";
+    }
+}
+/** Combine recorded state with a fresh liveness probe. Never mutates anything. */
+export function probeManifestMembers(manifest, proc) {
+    return manifest.members.map((member) => {
+        if (member.state === "exited" || member.pid === null) {
+            return { member, liveness: "dead" };
+        }
+        return { member, liveness: proc.isAlive(member.pid) };
+    });
+}
+/** True when the supervisor or any recorded member is alive or unaccounted for. */
+export function manifestHasLiveProcess(manifest, proc) {
+    if (proc.isAlive(manifest.supervisorPid) !== "dead")
+        return true;
+    return probeManifestMembers(manifest, proc).some((probe) => probe.liveness !== "dead");
+}
+/** Serialize deterministically: 2-space indent plus a trailing newline. */
+export function formatPlaneManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+/**
+ * Persist a state transition through a same-directory temporary file and an
+ * atomic rename, so a crash mid-write can never leave a half-written manifest
+ * that a subsequent `plane down` would read as a kill list.
+ */
+export async function writePlaneManifest(manifest, fs) {
+    const { manifestPath } = getPlanePaths(manifest.repoRoot);
+    const tempPath = `${manifestPath}.${manifest.planeId}.tmp`;
+    await fs.writeFile(tempPath, formatPlaneManifest(manifest));
+    await fs.rename(tempPath, manifestPath);
+}
+/**
+ * Remove the manifest, but only when it still belongs to `planeId`.
+ *
+ * The ownership check is what stops a slow shutdown from deleting the manifest
+ * of a *newer* plane that has since claimed the same path.
+ */
+export async function clearPlaneManifest(repoRoot, planeId, fs) {
+    const read = await readPlaneManifest(repoRoot, fs);
+    if (read.kind === "missing")
+        return { ok: true, removed: false };
+    if (read.kind !== "valid") {
+        return {
+            ok: false,
+            reason: "ambiguous",
+            message: `refusing to remove an unvalidated manifest (${read.error})`,
+        };
+    }
+    if (read.manifest.planeId !== planeId) {
+        return {
+            ok: false,
+            reason: "not-owned",
+            message: "refusing to remove a manifest owned by a different plane",
+        };
+    }
+    try {
+        await fs.unlink(getPlanePaths(repoRoot).manifestPath);
+        return { ok: true, removed: true };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { ok: true, removed: false };
+        return {
+            ok: false,
+            reason: "error",
+            message: `manifest could not be removed (${typeof code === "string" ? code : "unlink failed"})`,
+        };
+    }
+}
+/**
+ * Take exclusive ownership of `.bridge/plane/plane.json`.
+ *
+ * The exclusive create is the mutual-exclusion primitive: whoever wins it owns
+ * the plane. On `EEXIST` the existing record is re-read and re-probed **while
+ * the loser is still holding nothing** — a stale classification from preflight
+ * is never trusted to authorize a replacement, because a competing plane can
+ * have started in between.
+ */
+export async function claimPlaneManifest(params) {
+    const { manifest, fs, proc } = params;
+    const { planeDir, manifestPath } = getPlanePaths(manifest.repoRoot);
+    try {
+        await fs.mkdir(planeDir);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== "EEXIST") {
+            return {
+                ok: false,
+                reason: "error",
+                message: `could not create ${PLANE_RUNTIME_DIR}/ (${typeof code === "string" ? code : "mkdir failed"})`,
+            };
+        }
+    }
+    const serialized = formatPlaneManifest(manifest);
+    try {
+        await fs.createExclusive(manifestPath, serialized);
+        return { ok: true, manifest };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== "EEXIST") {
+            return {
+                ok: false,
+                reason: "error",
+                message: `could not claim the plane manifest (${typeof code === "string" ? code : "create failed"})`,
+            };
+        }
+    }
+    // Something is already there. Re-validate under the claim attempt.
+    const existing = await readPlaneManifest(manifest.repoRoot, fs);
+    if (existing.kind === "missing") {
+        // It vanished between our create and our read — another claimant is
+        // actively racing. Refuse rather than retry into an unbounded loop.
+        return {
+            ok: false,
+            reason: "conflict",
+            message: "another `plane up` is claiming the manifest right now",
+        };
+    }
+    if (existing.kind !== "valid") {
+        return {
+            ok: false,
+            reason: "ambiguous",
+            message: `an existing ${PLANE_RUNTIME_DIR}/${PLANE_MANIFEST_FILENAME} could not be validated ` +
+                `(${existing.error}); refusing to signal or replace it — inspect and remove it by hand`,
+        };
+    }
+    if (manifestHasLiveProcess(existing.manifest, proc)) {
+        return {
+            ok: false,
+            reason: "live-plane",
+            message: `a plane is already running (supervisor pid ${existing.manifest.supervisorPid}); ` +
+                "run `plane status` to inspect it, or `plane down` to wind it down",
+        };
+    }
+    // Confirmed dead under the claim: replace it atomically.
+    try {
+        await writePlaneManifest(manifest, fs);
+    }
+    catch (err) {
+        const code = err?.code;
+        return {
+            ok: false,
+            reason: "error",
+            message: `could not replace the stale plane manifest (${typeof code === "string" ? code : "write failed"})`,
+        };
+    }
+    return { ok: true, manifest };
+}