@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/plane/member-logs.js

@@ -0,0 +1,147 @@
+/**
+ * Per-member log routing (BAPI-756).
+ *
+ * The split is deliberate: **complete** child output goes to that member's own
+ * file, and only **structured, attributed events** reach the supervisor
+ * terminal. Interleaving four processes' raw stdout in one terminal destroys
+ * attribution exactly when you need it (which process printed the traceback?),
+ * and raw child output is also the most likely place for a credential to appear
+ * in a stack trace or a debug line.
+ */
+import { PLANE_RUNTIME_LOG_FILENAME } from "./types.js";
+/** The one legal log filename for a member, relative to the plane directory. */
+export function memberLogFilename(member) {
+    return `${member}.log`;
+}
+/**
+ * Open a member's log at its fixed, validated path.
+ *
+ * The path is re-checked here rather than trusted from the caller: this helper
+ * is the last point before a filesystem write, and a traversal-shaped path
+ * reaching it would mean an earlier invariant had already been broken.
+ */
+export function openMemberLog(member, planeDir, absolutePath, deps) {
+    const expected = `${planeDir}/${memberLogFilename(member)}`;
+    const normalized = absolutePath.split("\\").join("/");
+    if (normalized !== expected.split("\\").join("/")) {
+        return {
+            ok: false,
+            error: `refusing to open a log outside the plane directory for member '${member}'`,
+        };
+    }
+    try {
+        return { ok: true, stream: deps.openAppendStream(absolutePath) };
+    }
+    catch (err) {
+        const code = err?.code;
+        return { ok: false, error: typeof code === "string" ? code : "log could not be opened" };
+    }
+}
+/**
+ * Open the detached runtime's own startup trace (BAPI-768).
+ *
+ * Kept separate from {@link openMemberLog} rather than folded into it, because
+ * the runtime is not a member: it has no {@link PlaneMemberName}, so it cannot
+ * borrow the member filename generator, and its trace has to exist *before* the
+ * first member log is opened. The containment check is the same one members get
+ * — this is still the last point before a filesystem write.
+ */
+export function openPlaneRuntimeLog(planeDir, absolutePath, deps) {
+    const expected = `${planeDir}/${PLANE_RUNTIME_LOG_FILENAME}`;
+    const normalized = absolutePath.split("\\").join("/");
+    if (normalized !== expected.split("\\").join("/")) {
+        return { ok: false, error: "refusing to open a runtime trace outside the plane directory" };
+    }
+    try {
+        return { ok: true, stream: deps.openAppendStream(absolutePath) };
+    }
+    catch (err) {
+        const code = err?.code;
+        return {
+            ok: false,
+            error: typeof code === "string" ? code : "runtime trace could not be opened",
+        };
+    }
+}
+/**
+ * The complete set of reasons a member can fail *before* its child streams
+ * exist, and therefore the complete set of prose this module will write.
+ *
+ * An allow-list rather than a formatter argument: the values a caller has on
+ * hand at these failure points are exception messages, argv entries, and
+ * environment-derived paths — precisely the three things a log line must never
+ * carry. Fixing the vocabulary means the unsafe value is never in scope.
+ */
+export const PLANE_MEMBER_STARTUP_FAILURES = {
+    spawnThrew: "the process could not be started",
+    noPid: "the process started without a pid",
+    readinessTimeout: "it did not start listening in time",
+};
+const ALLOWED_STARTUP_FAILURES = new Set(Object.values(PLANE_MEMBER_STARTUP_FAILURES));
+/** Substituted for any reason not in the allow-list. Never echoes the input. */
+export const PLANE_MEMBER_STARTUP_FAILURE_FALLBACK = "it failed to start";
+/** Prefix marking a line as supervisor-authored rather than child output. */
+export const PLANE_SUPERVISOR_LOG_PREFIX = "[plane supervisor]";
+/**
+ * Record why a member never reached its child streams.
+ *
+ * Without this the log of a member that failed pre-exec is a zero-byte file, and
+ * `plane status` points the operator straight at it — which is how BAPI-768
+ * presented: an empty log read as "nothing to see" when it actually meant "this
+ * never ran". A write failure is swallowed, because losing a diagnostic must not
+ * change what the supervisor does next.
+ */
+export function writeMemberStartupFailure(log, member, reason) {
+    const safe = ALLOWED_STARTUP_FAILURES.has(reason)
+        ? reason
+        : PLANE_MEMBER_STARTUP_FAILURE_FALLBACK;
+    try {
+        log.write(`${PLANE_SUPERVISOR_LOG_PREFIX} ${member} did not start: ${safe}\n`);
+    }
+    catch {
+        /* a failed diagnostic write never propagates into the supervisor loop */
+    }
+}
+/**
+ * Append one already-sanitized line to the runtime trace.
+ *
+ * The caller owns redaction: the launcher tees the runtime's real stderr here,
+ * which is genuinely useful diagnostic text and cannot come from a fixed
+ * vocabulary the way {@link writeMemberStartupFailure}'s can.
+ */
+export function writeRuntimeTraceLine(log, line) {
+    try {
+        log.write(line.endsWith("\n") ? line : `${line}\n`);
+    }
+    catch {
+        /* a failed trace write never propagates into the launcher */
+    }
+}
+/**
+ * Tee a child's stdout and stderr into its own log file.
+ *
+ * Every received chunk is written in order and nothing is forwarded to the
+ * terminal. A stream error degrades observability for that member and is
+ * swallowed rather than thrown: losing a log line must never take down a plane
+ * that is otherwise running correctly.
+ */
+export function attachMemberOutput(streams, log) {
+    const pipe = (stream) => {
+        if (!stream)
+            return;
+        stream.setEncoding?.("utf8");
+        stream.on("data", (chunk) => {
+            try {
+                log.write(typeof chunk === "string" ? chunk : String(chunk));
+            }
+            catch {
+                /* a failed log write never propagates into the supervisor loop */
+            }
+        });
+        stream.on("error", () => {
+            /* stream errors degrade observability, never correctness */
+        });
+    };
+    pipe(streams.stdout);
+    pipe(streams.stderr);
+}

package/build/plane/member-roster.js

@@ -0,0 +1,147 @@
+/**
+ * The pinned plane member roster (BAPI-756).
+ *
+ * Every invariant an operator currently carries in their head is expressed here
+ * as code, so it cannot be forgotten under time pressure:
+ *
+ * - the server runs **without** `--reload`, and reload is not a configurable
+ *   option at any layer — `--reload` drops long-running MCP calls mid-flight;
+ * - executors run from **this repository's build tree**, by absolute path, never
+ *   `npx` and never a published package;
+ * - the reconciler worker is the ORDINARY worker, explicitly not the dead-man
+ *   observer;
+ * - the dead-man observer is absent by construction — there is no observer
+ *   member, pid, log path, or manifest record anywhere in this file (R-3).
+ *
+ * Credentials travel in the child environment and nowhere else. No argv entry,
+ * member name, log path, or formatted description is built from a secret.
+ */
+import path from "path";
+import { PLANE_SERVER_HOST, PLANE_SERVER_PORT, } from "./types.js";
+import { relativeLogPathFor } from "./manifest.js";
+/** How long a member with a readiness probe gets to start listening. */
+export const PLANE_READINESS_TIMEOUT_MS = 60_000;
+/** Executable used for the Python members. Overridable for a non-default venv. */
+export function resolvePythonExecutable(env) {
+    const configured = env.BAPI_PLANE_PYTHON;
+    return typeof configured === "string" && configured.trim().length > 0
+        ? configured.trim()
+        : "python";
+}
+/** Executable used for the server member. */
+export function resolveUvicornExecutable(env) {
+    const configured = env.BAPI_PLANE_UVICORN;
+    return typeof configured === "string" && configured.trim().length > 0
+        ? configured.trim()
+        : "uvicorn";
+}
+/**
+ * Build a child environment: a copy of the parent plus the resolved values the
+ * existing processes already expect.
+ *
+ * `CONDUCTOR_DEAD_MAN_ONLY` is explicitly deleted rather than merely left
+ * unset. An operator who exported it in this shell to run an observer would
+ * otherwise silently turn the plane's reconciler worker into a second observer,
+ * and the run would sit there with nothing reconciling it.
+ */
+export function buildPlaneChildEnv(parentEnv, context) {
+    const env = {};
+    for (const [key, value] of Object.entries(parentEnv)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    env.BAPI_REPO_NAME = context.repoName;
+    env.BAPI_BASE_URL = context.baseUrl;
+    env.BAPI_API_KEY = context.bridgeApiKey;
+    delete env.CONDUCTOR_DEAD_MAN_ONLY;
+    return env;
+}
+/**
+ * The complete roster: exactly one server, one ordinary worker, and `executors`
+ * executor lanes. Never an observer.
+ */
+export function buildPlaneMemberRoster(params) {
+    const { context, executors, parentEnv, nodeExecutable } = params;
+    const env = buildPlaneChildEnv(parentEnv, context);
+    const cwd = context.repoRoot;
+    const server = {
+        name: "server",
+        command: resolveUvicornExecutable(parentEnv),
+        // NO `--reload`, at any layer, ever. `--reload` restarts the worker process
+        // on file change and drops in-flight MCP calls, which during a conductor run
+        // silently truncates long tool calls the executor is waiting on.
+        args: [
+            "main:app",
+            "--host",
+            PLANE_SERVER_HOST,
+            "--port",
+            String(PLANE_SERVER_PORT),
+        ],
+        cwd,
+        env,
+        logPath: relativeLogPathFor("server"),
+        readiness: {
+            host: PLANE_SERVER_HOST,
+            port: PLANE_SERVER_PORT,
+            timeoutMs: PLANE_READINESS_TIMEOUT_MS,
+        },
+    };
+    const worker = {
+        name: "worker",
+        command: resolvePythonExecutable(parentEnv),
+        args: ["worker.py"],
+        cwd,
+        env,
+        logPath: relativeLogPathFor("worker"),
+        // The reconciler has no listening socket, so "spawned and still alive" is
+        // the only readiness signal available without inventing a health endpoint.
+        readiness: null,
+    };
+    const executorMembers = [];
+    for (let lane = 1; lane <= executors; lane += 1) {
+        const name = `executor-${lane}`;
+        executorMembers.push({
+            name,
+            command: nodeExecutable,
+            args: [
+                // Absolute, repository-local, compiled entrypoint. An `npx` launch would
+                // silently run a PUBLISHED version instead of this tree's code.
+                context.executorEntrypoint,
+                "executor",
+                "--repo",
+                context.repoName,
+                "--base-url",
+                context.baseUrl,
+                "--executor-id",
+                buildExecutorId(context.repoName, lane),
+            ],
+            cwd,
+            env,
+            logPath: relativeLogPathFor(name),
+            readiness: null,
+        });
+    }
+    return [server, worker, ...executorMembers];
+}
+/**
+ * Deterministic, distinct, CLI-safe executor id for one lane.
+ *
+ * The repository name is sanitized down to `[A-Za-z0-9_-]` because it reaches
+ * an argument vector; the lane number, which is the part that must be unique,
+ * comes from a validated integer and cannot be influenced by external text.
+ */
+export function buildExecutorId(repoName, lane) {
+    const safeRepo = repoName.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 40) || "repo";
+    return `plane-${safeRepo}-${lane}`;
+}
+/**
+ * A member rendered for the terminal. Built only from the fixed name, the
+ * command, and the argv — all of which are secret-free by construction.
+ */
+export function describePlaneMember(spec) {
+    return `${spec.name}: ${[spec.command, ...spec.args].join(" ")}`;
+}
+/** Absolute log path for a member under the validated repository root. */
+export function absoluteLogPath(repoRoot, spec) {
+    return path.join(repoRoot, spec.logPath);
+}

package/build/plane/preflight.js

@@ -0,0 +1,289 @@
+/**
+ * All-or-nothing plane preflight (BAPI-756, AC-8).
+ *
+ * Every spawn-blocking invariant is evaluated and **all** failures are reported
+ * together. Failing fast on the first problem is what turns a five-minute setup
+ * into five separate one-minute retries, so this module deliberately keeps
+ * going after a blocking failure and aggregates.
+ *
+ * The other half of "all-or-nothing" is the side-effect rule: preflight creates
+ * no directory, writes no manifest, opens no log, and spawns no process. It
+ * only reads. A refusal therefore leaves the working tree exactly as it found
+ * it — including any manifest belonging to a plane that is already running.
+ */
+import path from "path";
+import { PLANE_SERVER_BASE_URL, PLANE_SERVER_HOST, PLANE_SERVER_PORT, } from "./types.js";
+import { checkPlaneBuildFreshness, checkPlaneRuntimeEntrypoint } from "./build-freshness.js";
+import { checkAlembicHead } from "./alembic-head.js";
+import { manifestHasLiveProcess, readPlaneManifest } from "./manifest.js";
+/** Files that must exist for a path to be this repository's root. */
+const REQUIRED_REPO_FILES = ["main.py", "worker.py", "alembic.ini"];
+/** Bound on the port probe so a black-holed port cannot stall bring-up. */
+export const PLANE_PORT_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Evaluate every spawn-blocking invariant for `plane up`.
+ *
+ * On success the returned context carries the resolved Bridge API key. That is
+ * the only place it exists outside a child environment, and no diagnostic in
+ * the same result can contain it: each message below is built from fixed prose
+ * plus non-secret facts.
+ */
+export async function runPlanePreflight(repoRoot, deps) {
+    const diagnostics = [];
+    const add = (diagnostic) => {
+        if (diagnostic)
+            diagnostics.push(diagnostic);
+    };
+    const rootCheck = await checkRepositoryRoot(repoRoot, deps);
+    add(rootCheck);
+    // Every remaining check is relative to the repository root. Without a valid
+    // one there is nothing coherent left to check, so report and stop here rather
+    // than emitting a cascade of derived failures the operator cannot act on.
+    if (rootCheck)
+        return { ok: false, diagnostics };
+    add(checkRequiredEnvironment(deps.env));
+    const credentials = await checkBridgeCredentials(repoRoot, deps);
+    if (!credentials.ok)
+        add(credentials.diagnostic);
+    add(await checkPlaneBuildFreshness(repoRoot, { fs: deps.fs }));
+    // Read-only, and evaluated alongside the other independent checks so an
+    // unresolvable re-exec target aggregates with them instead of short-circuiting.
+    const runtimeEntrypoint = deps.resolveRuntimeEntrypoint();
+    add(checkPlaneRuntimeEntrypoint(runtimeEntrypoint));
+    add(await checkServerPort(deps));
+    add(await checkAlembicHead(repoRoot, {
+        execFile: deps.execFile,
+        fileExists: (filePath) => fileExists(filePath, deps.fs),
+        platform: deps.platform,
+    }));
+    add(await checkExistingPlane(repoRoot, deps));
+    const blocking = diagnostics.filter((d) => d.severity === "blocking");
+    // `!runtimeEntrypoint.ok` is already covered by the blocking count; it is
+    // repeated here so the compiler narrows the union rather than requiring a
+    // non-null assertion on the context field below.
+    if (blocking.length > 0 || !credentials.ok || !runtimeEntrypoint.ok) {
+        return { ok: false, diagnostics };
+    }
+    return {
+        ok: true,
+        diagnostics,
+        context: {
+            repoRoot,
+            repoName: credentials.repoName,
+            baseUrl: PLANE_SERVER_BASE_URL,
+            // Location-chosen: always THIS repository's build tree, so an executor can
+            // never come from a published package.
+            executorEntrypoint: path.join(repoRoot, "mcp_server", "build", "index.js"),
+            // Identity-chosen: the build already executing. Never substituted for the
+            // executor entrypoint above, nor it for this.
+            runtimeEntrypoint: runtimeEntrypoint.entrypoint,
+            bridgeApiKey: credentials.apiKey,
+            bridgeCredentialSource: credentials.source,
+        },
+    };
+}
+/**
+ * Confirm the working directory really is this repository's root.
+ *
+ * The root is taken from the process's own cwd, never from an operator-supplied
+ * path, so there is no traversal-shaped input to sanitize — but the marker
+ * files are still checked, because running the plane from a sibling worktree's
+ * parent would otherwise spawn `uvicorn main:app` against nothing.
+ */
+async function checkRepositoryRoot(repoRoot, deps) {
+    if (!path.isAbsolute(repoRoot)) {
+        return {
+            check: "repository-root",
+            severity: "blocking",
+            message: "the repository root could not be resolved to an absolute path",
+        };
+    }
+    const missing = [];
+    for (const file of REQUIRED_REPO_FILES) {
+        if (!(await fileExists(path.join(repoRoot, file), deps.fs)))
+            missing.push(file);
+    }
+    if (!(await fileExists(path.join(repoRoot, "mcp_server"), deps.fs))) {
+        missing.push("mcp_server/");
+    }
+    if (missing.length === 0)
+        return null;
+    return {
+        check: "repository-root",
+        severity: "blocking",
+        message: `this does not look like the Bridge API repository root — missing ${missing.join(", ")}. ` +
+            "Run `plane up` from the repository root.",
+    };
+}
+/**
+ * `ANTHROPIC_API_KEY` must be present and non-blank.
+ *
+ * Workers run under an isolated Claude config dir, where the API key is the one
+ * sanctioned credential and an OAuth-only host refuses to spawn outright — so a
+ * missing key is a spawn-blocking condition, not a degradation.
+ *
+ * The message names the key and never its value.
+ */
+export function checkRequiredEnvironment(env) {
+    const value = env.ANTHROPIC_API_KEY;
+    if (typeof value === "string" && value.trim().length > 0)
+        return null;
+    return {
+        check: "anthropic-api-key",
+        severity: "blocking",
+        message: "ANTHROPIC_API_KEY is not set (or is blank) in this shell. Isolated workers have no " +
+            "OAuth session and refuse to spawn without it. Export it before running `plane up`.",
+    };
+}
+/**
+ * Resolve the repository identity, then the Bridge credential for it.
+ *
+ * Both go through the shared resolvers. This is the shell-spawned credential
+ * rule: a plane member is launched from a spawned shell, which never sees
+ * `.mcp.json` env — that file is visible only to the MCP server process.
+ */
+export async function checkBridgeCredentials(repoRoot, deps) {
+    const repo = await deps.resolveRepoName({
+        env: deps.env,
+        cwd: repoRoot,
+        readFile: deps.fs.readFile,
+    });
+    if (!repo.ok) {
+        return {
+            ok: false,
+            diagnostic: {
+                check: "bridge-credentials",
+                severity: "blocking",
+                message: "the Bridge repository identity could not be resolved — set BAPI_REPO_NAME or add a " +
+                    "valid .bridge/config at the repository root.",
+            },
+        };
+    }
+    let result;
+    try {
+        result = await deps.resolveCredentials(repo.repoName, {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.fs.readFile,
+            stat: async (filePath) => {
+                // The resolver only needs POSIX mode bits for its permission warning.
+                // `PlaneFsDeps.stat` is deliberately minimal, so a missing mode is
+                // reported as a fully-open value the resolver will simply warn about
+                // rather than as a fabricated "safe" one.
+                await deps.fs.stat(filePath);
+                return { mode: 0o600 };
+            },
+            stderr: () => {
+                /* the resolver's advisory warnings are not part of plane output */
+            },
+        });
+    }
+    catch {
+        // Sanitized: a resolver throw becomes a category, never exception text
+        // (which could echo file contents).
+        return {
+            ok: false,
+            diagnostic: {
+                check: "bridge-credentials",
+                severity: "blocking",
+                message: `Bridge credentials for target bapi:${repo.repoName} could not be resolved ` +
+                    "(resolver unavailable).",
+            },
+        };
+    }
+    if (!result.ok) {
+        return {
+            ok: false,
+            diagnostic: {
+                check: "bridge-credentials",
+                severity: "blocking",
+                message: `Bridge credentials for target bapi:${repo.repoName} could not be resolved ` +
+                    `(${result.kind}). Set BAPI_API_KEY in this shell, or store it with ` +
+                    "`mcp-server credentials`. A spawned shell never sees .mcp.json env.",
+            },
+        };
+    }
+    return {
+        ok: true,
+        repoName: repo.repoName,
+        apiKey: result.credentials.apiKey,
+        source: result.credentials.source,
+    };
+}
+/**
+ * Probe the local server port with a bounded TCP connect.
+ *
+ * A successful connection means something already owns the port — most often a
+ * sibling worktree's server, which is the trap this refusal names explicitly.
+ * A refused connection is the available case. Anything else is reported as a
+ * warning rather than guessed either way: silently assuming "available" would
+ * let two servers race for the port, and silently assuming "occupied" would
+ * refuse a perfectly good bring-up.
+ */
+export async function checkServerPort(deps) {
+    const result = await deps.probePort(PLANE_SERVER_HOST, PLANE_SERVER_PORT, PLANE_PORT_PROBE_TIMEOUT_MS);
+    if (result.kind === "refused")
+        return null;
+    if (result.kind === "connected") {
+        return {
+            check: "server-port",
+            severity: "blocking",
+            message: `${PLANE_SERVER_HOST}:${PLANE_SERVER_PORT} is already accepting connections. ` +
+                "That port may belong to a SIBLING WORKTREE's server — check before you kill it. " +
+                "Stop the existing server (or wind down its plane) and retry.",
+        };
+    }
+    return {
+        check: "server-port",
+        severity: "warning",
+        message: `could not determine whether ${PLANE_SERVER_HOST}:${PLANE_SERVER_PORT} is free ` +
+            `(${result.error}); startup continues and uvicorn will fail loudly if the port is taken.`,
+    };
+}
+/**
+ * Refuse to start over a plane that is still alive.
+ *
+ * A manifest whose processes are all dead is *classified* stale here but is not
+ * acted on: deleting or replacing it is the atomic claim's job, under ownership,
+ * where the classification can be re-checked. Preflight never mutates disk.
+ */
+export async function checkExistingPlane(repoRoot, deps) {
+    const read = await readPlaneManifest(repoRoot, deps.fs);
+    if (read.kind === "missing")
+        return null;
+    if (read.kind !== "valid") {
+        return {
+            check: "existing-plane",
+            severity: "blocking",
+            message: `an existing .bridge/plane/plane.json could not be validated (${read.error}). ` +
+                "No process was signalled and the file was left untouched — inspect it, then remove " +
+                "it by hand if no plane is running.",
+        };
+    }
+    if (!manifestHasLiveProcess(read.manifest, deps.proc)) {
+        // Stale. Reported as information so the operator understands why an old
+        // manifest is about to be replaced; the claim revalidates before it does.
+        return {
+            check: "existing-plane",
+            severity: "warning",
+            message: "a previous plane manifest is present but every recorded process is gone; it will be " +
+                "replaced after a final liveness re-check.",
+        };
+    }
+    return {
+        check: "existing-plane",
+        severity: "blocking",
+        message: `a plane is already running (supervisor pid ${read.manifest.supervisorPid}). ` +
+            "Run `plane status` to inspect it, or `plane down` to wind it down first.",
+    };
+}
+async function fileExists(filePath, fs) {
+    try {
+        await fs.stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}