@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/plane/cli.js

@@ -0,0 +1,480 @@
+/**
+ * `plane` CLI surface (BAPI-756).
+ *
+ * Two responsibilities live here and nothing else: a pure argument parser, and
+ * a coordinator that sequences preflight → claim → launch (or status, or down)
+ * behind one exception-contained entrypoint.
+ *
+ * All operator output goes through injected sinks. The global console helpers
+ * are banned throughout this directory — a static review step greps for them —
+ * because this package also hosts an MCP stdio server: anything that writes to
+ * the process's real stdout from shared code can corrupt the protocol transport
+ * if it is ever reused on the server path.
+ */
+import { randomUUID } from "crypto";
+import { PLANE_ENTRYPOINT_ACTION, PLANE_ID_ENV_VAR, PLANE_MANIFEST_SCHEMA_VERSION, PLANE_OBSERVER_CHANNEL_TYPE_ENV, PLANE_OBSERVER_COMMAND, PLANE_OBSERVER_DESTINATION_ENV, PLANE_RUNTIME_ACTION, PLANE_RUNTIME_DIR, } from "./types.js";
+import { PLANE_RUNTIME_ENTRYPOINT_REFUSAL } from "./build-freshness.js";
+import { relativeLogPathFor } from "./manifest.js";
+import { claimPlaneManifest } from "./manifest.js";
+import { runPlanePreflight } from "./preflight.js";
+import { buildPlaneMemberRoster } from "./member-roster.js";
+import { getPlaneStatus, formatPlaneStatus } from "./status.js";
+import { shutdownPlane, formatPlaneShutdown } from "./shutdown.js";
+import { launchPlaneSupervisor, runPlaneRuntime, } from "./supervisor.js";
+import { createMemberLogDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, createPlaneSpawn, probeTcpPort, registerSignalHandler, resolveHomedir, resolveNodeExecutable, resolvePackageEntrypoint, } from "./defaults.js";
+import { resolveBapiCredentials } from "../credential-store.js";
+import { resolveRequiredStartTicketsRepoName } from "../start-tickets-repo.js";
+/** Upper bound on executor lanes. Guards a typo from forking a fleet. */
+export const PLANE_MAX_EXECUTORS = 32;
+/** Default executor lane count when `--executors` is omitted. */
+export const PLANE_DEFAULT_EXECUTORS = 1;
+/**
+ * Parse everything after the `plane` token.
+ *
+ * Pure by construction: every rejection happens here, before the coordinator
+ * can touch the filesystem, open a socket, resolve a credential, or spawn a
+ * child. A malformed invocation therefore has no side effect at all.
+ */
+export function parsePlaneArgs(argv) {
+    if (argv.length === 0) {
+        return { kind: "error", message: "missing action (expected `up`, `status`, or `down`)" };
+    }
+    if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+        return { kind: "help" };
+    }
+    const action = argv[0];
+    const rest = argv.slice(1);
+    if (action === "status" || action === "down") {
+        if (rest.length > 0) {
+            return {
+                kind: "error",
+                message: `\`plane ${action}\` takes no options (got '${rest[0]}')`,
+            };
+        }
+        return { kind: action };
+    }
+    // Private, and deliberately absent from the usage text and from the
+    // expected-action list in the unknown-action error below: it exists for the
+    // bundled-artifact regression guard, not for operators.
+    if (action === PLANE_ENTRYPOINT_ACTION) {
+        if (rest.length > 0) {
+            return {
+                kind: "error",
+                message: `\`plane ${action}\` takes no options (got '${rest[0]}')`,
+            };
+        }
+        return { kind: "entrypoint" };
+    }
+    if (action !== "up" && action !== PLANE_RUNTIME_ACTION) {
+        return {
+            kind: "error",
+            message: `unknown action '${action}' (expected \`up\`, \`status\`, or \`down\`)`,
+        };
+    }
+    let executors = null;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--executors") {
+            if (executors !== null) {
+                return { kind: "error", message: "--executors may be supplied only once" };
+            }
+            const raw = rest[i + 1];
+            i += 1;
+            if (raw === undefined) {
+                return { kind: "error", message: "--executors requires a value" };
+            }
+            const parsed = parseExecutorCount(raw);
+            if (parsed === null) {
+                return {
+                    kind: "error",
+                    message: `--executors must be a whole number between 1 and ${PLANE_MAX_EXECUTORS} ` +
+                        `(got '${raw}')`,
+                };
+            }
+            executors = parsed;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { kind: "error", message: `unknown option '${arg}' for \`plane ${action}\`` };
+        }
+        return { kind: "error", message: `unexpected argument '${arg}' for \`plane ${action}\`` };
+    }
+    const options = { executors: executors ?? PLANE_DEFAULT_EXECUTORS };
+    return action === "up" ? { kind: "up", options } : { kind: "runtime", options };
+}
+/**
+ * Strict base-10 whole-number parse. Returns `null` for anything that is not an
+ * exact in-range integer — no coercion, no rounding, no exponent notation.
+ * `Number("1e2")` is 100 and `Number("")` is 0, so the textual shape is checked
+ * before the numeric value is trusted.
+ */
+function parseExecutorCount(raw) {
+    if (!/^\d+$/.test(raw))
+        return null;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(value))
+        return null;
+    if (value < 1 || value > PLANE_MAX_EXECUTORS)
+        return null;
+    return value;
+}
+/**
+ * Operator-facing usage. The safety claims here are pinned by a unit test: they
+ * are the contract an operator reads before trusting the supervisor with a run,
+ * so they cannot drift away from the implementation silently.
+ */
+export function getPlaneUsage() {
+    return [
+        "Usage: mcp-server plane <up|status|down> [options]",
+        "",
+        "Brings up (and winds down) the attended conductor plane in one command:",
+        "the Bridge API server, the reconciler worker, and one executor per lane.",
+        "",
+        "Actions:",
+        "  plane up [--executors N]   Preflight, then start the plane. Refuses as a",
+        "                             whole if any spawn-blocking check fails.",
+        "  plane status               Read the manifest and report each member's state.",
+        "  plane down                 Signal the recorded process group, escalating to",
+        "                             SIGKILL, and clear the manifest.",
+        "",
+        "Options:",
+        `  --executors N              Executor lanes to start (default ${PLANE_DEFAULT_EXECUTORS}, max ${PLANE_MAX_EXECUTORS}).`,
+        "  -h, --help                 Show this help.",
+        "",
+        "Behavior you can rely on:",
+        "  * The server runs WITHOUT --reload. Reload is not configurable here, because",
+        "    it drops long-running MCP calls mid-flight.",
+        "  * Executors run from this repository's local build tree",
+        "    (mcp_server/build/index.js) — never npx, never a published package.",
+        "  * A member that exits is reported loudly and is NOT restarted. There is no",
+        "    auto-restart, retry, or backoff: a crash is a finding, not noise.",
+        "  * The dead-man observer is NOT part of the plane. It is started and stopped",
+        "    by you, so its failure domain stays independent of the supervisor's.",
+        `    Start it separately: ${PLANE_OBSERVER_COMMAND}`,
+        "",
+        `Runtime artifacts (manifest + per-member logs) live under ${PLANE_RUNTIME_DIR}/.`,
+    ].join("\n");
+}
+/** The observer reminder printed at the end of a successful startup banner. */
+export function getPlaneObserverReminder() {
+    return [
+        "",
+        "Dead-man observer (independent — not started, listed, or stopped by the plane):",
+        `  ${PLANE_OBSERVER_COMMAND}`,
+        `  with ${PLANE_OBSERVER_CHANNEL_TYPE_ENV} (slack_webhook|generic_webhook) and`,
+        `  ${PLANE_OBSERVER_DESTINATION_ENV} (the NAME of an env var holding the URL).`,
+    ];
+}
+// ---------------------------------------------------------------------------
+// Coordinator
+// ---------------------------------------------------------------------------
+/** Wording every refusal ends with, so "nothing started" is greppable. */
+export const PLANE_NOTHING_STARTED = "no processes were started";
+/**
+ * Public `plane` entrypoint.
+ *
+ * The ordering here IS the all-or-nothing contract: parse, then preflight, and
+ * only then create `.bridge/plane/`, claim the manifest, open logs, or spawn.
+ * Nothing before a clean preflight has a side effect.
+ */
+export async function runPlaneCli(argv, overrides = {}) {
+    const sinks = overrides.sinks ?? {
+        // Bound at the boundary, never inside a plane module: this package also
+        // hosts an MCP stdio server, and shared code that writes to the process's
+        // real stdout would corrupt that transport if it were ever reused there.
+        stdout: (line) => process.stdout.write(`${line}\n`),
+        stderr: (line) => process.stderr.write(`${line}\n`),
+    };
+    try {
+        const parsed = parsePlaneArgs(argv);
+        switch (parsed.kind) {
+            case "help":
+                sinks.stdout(getPlaneUsage());
+                return 0;
+            case "error":
+                sinks.stderr(`Error: ${parsed.message}`);
+                sinks.stderr("");
+                sinks.stderr(getPlaneUsage());
+                return 1;
+            // Each of these is AWAITED, not merely returned. Returning the promise
+            // would hand it to the caller unresolved, so a rejection would escape the
+            // sanitizing catch below and surface as a raw stack — which is exactly the
+            // path most likely to carry a credential out of a resolver or spawn error.
+            case "status":
+                return await runStatusAction(sinks, overrides);
+            case "down":
+                return await runDownAction(sinks, overrides);
+            case "up":
+                return await runUpAction(parsed.options.executors, sinks, overrides);
+            case "runtime":
+                return await runRuntimeAction(parsed.options.executors, overrides);
+            // Dispatched here, ahead of every action that touches the repository, so
+            // the diagnostic answers from an empty directory with no credentials.
+            case "entrypoint":
+                return runEntrypointDiagnosticAction(sinks, overrides);
+        }
+    }
+    catch {
+        // Sanitized by construction: an exception message can carry a credential
+        // that leaked into a resolver error or a spawn failure, so none of it is
+        // rendered — only this fixed line.
+        sinks.stderr("plane failed: an unexpected internal error occurred.");
+        return 1;
+    }
+}
+/**
+ * Report the runtime re-exec target the *executing artifact* selects, and do
+ * nothing else (BAPI-768).
+ *
+ * This is the question the bundled-artifact regression test asks. It runs the
+ * same production resolver preflight uses, so a bundle whose resolution is
+ * broken cannot answer correctly here and pass there. It creates no
+ * `.bridge/plane/`, claims no manifest, opens no log, and spawns nothing —
+ * which is what lets the guard run from an empty temporary directory with no
+ * credentials and no port 8000, and therefore never skip.
+ */
+export function runEntrypointDiagnosticAction(sinks, overrides = {}) {
+    const resolve = overrides.resolveRuntimeEntrypoint ?? (() => resolvePackageEntrypoint());
+    const resolution = resolve();
+    if (!resolution.ok) {
+        sinks.stderr(`plane entrypoint UNRESOLVED: ${PLANE_RUNTIME_ENTRYPOINT_REFUSAL}`);
+        return 1;
+    }
+    sinks.stdout(resolution.entrypoint);
+    return 0;
+}
+async function runStatusAction(sinks, overrides) {
+    const repoRoot = overrides.cwd ?? process.cwd();
+    if (overrides.status) {
+        sinks.stdout(await overrides.status(repoRoot));
+        return 0;
+    }
+    const result = await getPlaneStatus(repoRoot, {
+        fs: createPlaneFsDeps(),
+        proc: createPlaneProcessDeps(),
+    });
+    const text = formatPlaneStatus(result);
+    if (!result.ok) {
+        sinks.stderr(text);
+        return 1;
+    }
+    sinks.stdout(text);
+    return 0;
+}
+async function runDownAction(sinks, overrides) {
+    const repoRoot = overrides.cwd ?? process.cwd();
+    if (overrides.down) {
+        const injected = await overrides.down(repoRoot);
+        (injected.ok ? sinks.stdout : sinks.stderr)(injected.text);
+        return injected.ok ? 0 : 1;
+    }
+    const result = await shutdownPlane(repoRoot, {
+        fs: createPlaneFsDeps(),
+        proc: createPlaneProcessDeps(),
+        clock: createPlaneClock(),
+    });
+    const text = formatPlaneShutdown(result);
+    (result.ok ? sinks.stdout : sinks.stderr)(text);
+    return result.ok ? 0 : 1;
+}
+async function runUpAction(executors, sinks, overrides) {
+    const repoRoot = overrides.cwd ?? process.cwd();
+    const env = overrides.env ?? process.env;
+    const preflight = overrides.preflight
+        ? await overrides.preflight(repoRoot)
+        : await runPlanePreflight(repoRoot, buildPreflightDeps(env));
+    for (const diagnostic of preflight.diagnostics.filter((d) => d.severity === "warning")) {
+        sinks.stdout(formatDiagnostic(diagnostic));
+    }
+    if (!preflight.ok) {
+        sinks.stderr("");
+        sinks.stderr("plane up REFUSED — preflight found blocking problems:");
+        for (const diagnostic of preflight.diagnostics.filter((d) => d.severity === "blocking")) {
+            sinks.stderr(formatDiagnostic(diagnostic));
+        }
+        sinks.stderr("");
+        sinks.stderr(`Fix every item above and retry. ${PLANE_NOTHING_STARTED}.`);
+        return 1;
+    }
+    const planeId = (overrides.newPlaneId ?? randomUUID)();
+    const launch = overrides.launch
+        ? await overrides.launch(preflight, executors)
+        : await launchPlane(preflight, executors, planeId, sinks, env);
+    if (!launch.ok) {
+        for (const line of formatPlaneLaunchFailure(launch))
+            sinks.stderr(line);
+        return 1;
+    }
+    return launch.exitCode;
+}
+/** Stable label so a startup death is greppable in a terminal scrollback. */
+export const PLANE_STARTUP_FAILED = "plane up FAILED — the runtime never came up";
+/**
+ * Render a launch failure with everything an operator needs to act.
+ *
+ * The old rendering was a single `plane up FAILED: <error>` line, which was
+ * accurate only for the spawn-level failures it was written for. A runtime that
+ * dies after spawning has an exit status, a stderr tail, and a trace file, and
+ * omitting them is what turned BAPI-768 into an investigation instead of a
+ * message. Everything here is already redacted and bounded by the supervisor;
+ * this function only lays it out.
+ */
+export function formatPlaneLaunchFailure(launch) {
+    if (!launch.startup) {
+        // No child exit information exists, so none is invented — this is the
+        // pre-existing generic spawn-failure path, preserved verbatim in substance.
+        return [`plane up FAILED: ${launch.error}`];
+    }
+    const { exitCode, signal, stderrExcerpt, tracePath } = launch.startup;
+    const status = signal !== null ? `signal ${signal}` : `exit code ${exitCode ?? "unknown"}`;
+    const lines = [`${PLANE_STARTUP_FAILED}: ${launch.error} (${status}).`, `  trace  ${tracePath}`];
+    if (stderrExcerpt.trim().length > 0) {
+        lines.push("  runtime stderr:");
+        for (const line of stderrExcerpt.split("\n")) {
+            if (line.length > 0)
+                lines.push(`    ${line}`);
+        }
+    }
+    // Not PLANE_NOTHING_STARTED: members may briefly have existed before the
+    // runtime rolled them back, and claiming otherwise would be the same species
+    // of untruth as the banner this ticket removed.
+    lines.push("The plane is not running. Read the trace above, then retry `plane up`.");
+    return lines;
+}
+/** Claim the manifest, print the banner, then run the detached supervisor. */
+async function launchPlane(preflight, executors, planeId, sinks, env) {
+    const fs = createPlaneFsDeps();
+    const clock = createPlaneClock();
+    const context = preflight.context;
+    const nodeExecutable = resolveNodeExecutable();
+    const roster = buildPlaneMemberRoster({
+        context,
+        executors,
+        parentEnv: env,
+        nodeExecutable,
+    });
+    const timestamp = clock.now().toISOString();
+    const claim = await claimPlaneManifest({
+        manifest: {
+            schemaVersion: PLANE_MANIFEST_SCHEMA_VERSION,
+            planeId,
+            repoRoot: context.repoRoot,
+            // Placeholder until the runtime exists; the launcher rewrites both fields
+            // with the detached runtime's pid the moment it has one.
+            supervisorPid: process.pid,
+            supervisorPgid: process.pid,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            members: roster.map((spec) => ({
+                name: spec.name,
+                pid: null,
+                state: "spawning",
+                exitCode: null,
+                exitSignal: null,
+                logPath: relativeLogPathFor(spec.name),
+            })),
+        },
+        fs,
+        proc: createPlaneProcessDeps(),
+    });
+    // No runtime was spawned, so there is no exit status, stderr, or trace to
+    // report — `startup: null` is the honest shape, not a placeholder.
+    if (!claim.ok)
+        return { ok: false, error: claim.message, startup: null };
+    return launchPlaneSupervisor({ context, manifest: claim.manifest, executors }, {
+        fs,
+        clock,
+        spawn: createPlaneSpawn(),
+        sinks,
+        log: createMemberLogDeps(),
+        onSignal: registerSignalHandler,
+        nodeExecutable,
+        // Resolved and validated by preflight, never re-derived here: a second
+        // resolution could disagree with the one the refusal was based on.
+        entrypoint: context.runtimeEntrypoint,
+        parentEnv: env,
+        // The banner is now a consequence of the runtime's readiness handshake
+        // rather than of the launcher reaching the end of its own function. That
+        // is the whole point: `spawn()` succeeding never meant the plane was up.
+        onReady: ({ supervisorPid, supervisorPgid }) => printStartupBanner(sinks, context, roster.length, executors, {
+            supervisorPid,
+            supervisorPgid,
+        }),
+    });
+}
+function printStartupBanner(sinks, context, memberCount, executors, launch) {
+    // Deliberately built from fixed labels plus non-secret facts. No environment
+    // object and no credential value is rendered — the resolved key exists only
+    // in the child environments.
+    sinks.stdout("");
+    sinks.stdout(`Plane up — ${memberCount} members (${executors} executor lane(s))`);
+    sinks.stdout(`  repository   ${context.repoName} (${context.repoRoot})`);
+    sinks.stdout(`  server       ${context.baseUrl} (no --reload)`);
+    sinks.stdout(`  supervisor   pid ${launch.supervisorPid}, process group ${launch.supervisorPgid}`);
+    sinks.stdout(`  logs         ${PLANE_RUNTIME_DIR}/`);
+    sinks.stdout("  crash policy members are NOT restarted; a member exit is reported loudly.");
+    for (const line of getPlaneObserverReminder())
+        sinks.stdout(line);
+    sinks.stdout("");
+}
+/** The private detached-runtime action. Never part of the documented surface. */
+async function runRuntimeAction(executors, overrides) {
+    const repoRoot = overrides.cwd ?? process.cwd();
+    if (overrides.runtime)
+        return overrides.runtime(repoRoot, executors);
+    const env = overrides.env ?? process.env;
+    const planeId = env[PLANE_ID_ENV_VAR];
+    const sinks = {
+        stdout: (line) => process.stdout.write(`${line}\n`),
+        stderr: (line) => process.stderr.write(`${line}\n`),
+    };
+    if (typeof planeId !== "string" || planeId.length === 0) {
+        sinks.stderr(`plane runtime refused: ${PLANE_ID_ENV_VAR} was not provided by the launcher.`);
+        return 1;
+    }
+    const preflight = await runPlanePreflight(repoRoot, buildPreflightDeps(env));
+    if (!preflight.ok) {
+        // The launcher already ran preflight; reaching here means the world changed
+        // between claim and spawn. Refuse rather than start a half-valid plane.
+        sinks.stderr(`plane runtime refused: preflight no longer passes. ${PLANE_NOTHING_STARTED}.`);
+        return 1;
+    }
+    const roster = buildPlaneMemberRoster({
+        context: preflight.context,
+        executors,
+        parentEnv: env,
+        nodeExecutable: resolveNodeExecutable(),
+    });
+    const result = await runPlaneRuntime(repoRoot, roster, {
+        fs: createPlaneFsDeps(),
+        clock: createPlaneClock(),
+        proc: createPlaneProcessDeps(),
+        spawn: createPlaneSpawn(),
+        sinks,
+        log: createMemberLogDeps(),
+        onSignal: registerSignalHandler,
+        probePort: probeTcpPort,
+        selfPid: process.pid,
+        planeId,
+    });
+    return result.exitCode;
+}
+function buildPreflightDeps(env) {
+    return {
+        env,
+        platform: process.platform,
+        homedir: resolveHomedir,
+        fs: createPlaneFsDeps(),
+        clock: createPlaneClock(),
+        proc: createPlaneProcessDeps(),
+        execFile: createPlaneExecFile(),
+        probePort: probeTcpPort,
+        resolveRuntimeEntrypoint: () => resolvePackageEntrypoint(),
+        resolveRepoName: resolveRequiredStartTicketsRepoName,
+        resolveCredentials: resolveBapiCredentials,
+    };
+}
+function formatDiagnostic(diagnostic) {
+    const label = diagnostic.severity === "blocking" ? "BLOCKED" : "WARN   ";
+    return `  ${label} [${diagnostic.check}] ${diagnostic.message}`;
+}