@bridge_gpt/mcp-server 0.2.65 → 0.2.67

package/build/plane/types.js

@@ -52,8 +52,27 @@
  * really a version gap. Reading v1 and v2 stays supported and a manifest without
  * `lifecycle` is interpreted as a fully-up single-phase plane, which is exactly
  * what an older build wrote.
+ *
+ * Bumped to 4 by BAPI-1362, which added the pinned code snapshot
+ * (`snapshotPath` / `snapshotSha`), a per-member `cwd`, the `restarting` member
+ * state, and the member `restartFailure` marker. Same reasoning as 3: an older
+ * binary rejects an unknown top-level key, so a v4 manifest read by a v3 build
+ * would read as a corrupt field rather than as a version gap.
+ *
+ * The version also carries a SAFETY meaning that no other bump has had: a
+ * manifest older than 4 was written by a runtime that has no `plane restart`
+ * handler, and the restart signal's default action terminates a process that
+ * does not handle it. `plane restart` therefore refuses a manifest below
+ * {@link PLANE_RESTART_MIN_SCHEMA_VERSION} before it signals anything.
  */
-export const PLANE_MANIFEST_SCHEMA_VERSION = 3;
+export const PLANE_MANIFEST_SCHEMA_VERSION = 4;
+/**
+ * The first manifest schema version whose runtime handles `plane restart`.
+ *
+ * A runtime that does not register the restart signal is killed by it, so this
+ * is the gate that keeps the CLI from signalling one (BAPI-1362).
+ */
+export const PLANE_RESTART_MIN_SCHEMA_VERSION = 4;
 /**
  * Every schema version this build can READ.
  *
@@ -63,9 +82,35 @@ export const PLANE_MANIFEST_SCHEMA_VERSION = 3;
  * legible, inflicted from the other side. Accepting 1 costs nothing: the two
  * versions differ only in whether `observer` may appear among the members.
  */
-export const PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3];
+export const PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3, 4];
 /** Runtime artifact directory, relative to the repository root. */
 export const PLANE_RUNTIME_DIR = ".bridge/plane";
+/**
+ * Directory of plane-owned detached code snapshots, relative to the repository
+ * root (BAPI-1362). One Git worktree per pinned commit, at
+ * `<PLANE_SNAPSHOTS_DIR>/<full-sha>`. Under {@link PLANE_RUNTIME_DIR}, which is
+ * already ignored by version control.
+ */
+export const PLANE_SNAPSHOTS_DIR = `${PLANE_RUNTIME_DIR}/snapshots`;
+/** Filename of the pending restart request inside {@link PLANE_RUNTIME_DIR}. */
+export const PLANE_RESTART_REQUEST_FILENAME = "restart-request.json";
+/** Filename of the published restart result inside {@link PLANE_RUNTIME_DIR}. */
+export const PLANE_RESTART_RESULT_FILENAME = "restart-result.json";
+/**
+ * Signal the CLI sends the detached runtime to say "a restart request is waiting".
+ *
+ * The signal carries no data; the request itself is a file at a fixed path.
+ * `SIGUSR2`, because `SIGUSR1` is reserved by Node for its inspector and the
+ * termination signals already mean "wind the plane down". It is sent to the
+ * supervisor's own pid only, NEVER to the process group, which would reach every
+ * member.
+ */
+export const PLANE_RESTART_SIGNAL = "SIGUSR2";
+/**
+ * The members `plane restart` may replace. Executor lanes are run-scoped and are
+ * recovered at the run level, so they are deliberately not restartable here.
+ */
+export const PLANE_RESTARTABLE_MEMBERS = ["server", "worker", "observer"];
 /** Manifest filename inside {@link PLANE_RUNTIME_DIR}. */
 export const PLANE_MANIFEST_FILENAME = "plane.json";
 /**
@@ -188,6 +233,13 @@ export function planeCheckSkipped(check, label, detail) {
         outcomes: [{ check, id: check, label, status: "skip", detail }],
     };
 }
+/** Every value {@link PlaneRestartFailureReason} may take, for runtime guards. */
+export const PLANE_RESTART_FAILURE_REASONS = [
+    "stop-incomplete",
+    "spawn",
+    "readiness",
+    "snapshot",
+];
 /**
  * Every value {@link PlaneHeartbeatComponent} may take, for runtime guards.
  *

package/build/plane/worker-exit-code.js

@@ -0,0 +1,2 @@
+/** Matches WORKER_STALE_EXIT_CODE in worker.py. */
+export const WORKER_STALE_EXIT_CODE = 75;

package/build/printed-remedy-commands.js

@@ -0,0 +1,37 @@
+/**
+ * Complete, copy-ready CLI commands that operator-facing messages print as
+ * remedies (BAPI-1376).
+ *
+ * Every command starts with the non-interactive package launcher and names a
+ * subcommand `index.ts` dispatches. A command that carries a placeholder
+ * (`<check-name>`, `<id>`) must be printed with an instruction to replace it.
+ *
+ * Dispatch stays in `index.ts`; this module only names commands. The merge
+ * workflow command is deliberately NOT here: its single definition is the
+ * mirrored contract (`conductor/merge-execution-contract.ts`).
+ */
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+/** The non-interactive launcher every printed command starts with. */
+const LAUNCHER = `npx -y ${MCP_PACKAGE_NAME}`;
+/** The top-level subcommand tokens `index.ts` dispatches that remedies name. */
+export const PRINTED_REMEDY_DISPATCHED_SUBCOMMANDS = [
+    "install",
+    "install-bridge",
+    "doctor",
+    "connect-github",
+];
+/** The guided installer (interactive project setup). */
+export const PRINTED_INSTALL_COMMAND = `${LAUNCHER} install`;
+/** Conductor bootstrap. The parser requires at least one `--required-check`. */
+export const PRINTED_CONDUCTOR_INSTALL_COMMAND = `${LAUNCHER} install conductor --required-check <check-name>`;
+/** Conductor bootstrap that also provisions a repository-wide executor service. */
+export const PRINTED_CONDUCTOR_EXECUTOR_INSTALL_COMMAND = `${LAUNCHER} install conductor --required-check <check-name> --executor-id <id> --repo-wide`;
+/** Read-only readiness diagnostics. */
+export const PRINTED_DOCTOR_COMMAND = `${LAUNCHER} doctor`;
+/** Sessionless GitHub App connection. `--repo` is optional for this command. */
+export const PRINTED_CONNECT_GITHUB_COMMAND = `${LAUNCHER} connect-github`;
+/** Explains the `<check-name>` placeholder; print it beside a conductor command. */
+export const PRINTED_CHECK_NAME_INSTRUCTION = "Replace <check-name> with the exact name of a CI check this repository requires; " +
+    "repeat --required-check for each additional check.";
+/** Explains the `<id>` placeholder of the executor command. */
+export const PRINTED_EXECUTOR_ID_INSTRUCTION = "Replace <id> with a name for the executor service.";

package/build/project-root.js

@@ -16,6 +16,7 @@
  * so this stays trivially testable and swappable.
  */
 import path from "path";
+import { renderDiagnosticValue } from "./diagnostic-text.js";
 /**
  * Whether `cwd` looks like a project root: presence of `.git`, checked through the
  * injected `stat` probe. Any probe failure (absent, or an unexpected I/O error) is
@@ -32,3 +33,101 @@ export async function hasProjectRootMarker(cwd, stat) {
         return false;
     }
 }
+/**
+ * Validate an explicit project root: it must exist, be a directory, and contain
+ * `.git` (a directory, or the `.git` FILE a worktree has) or `.bridge/config`.
+ * An absent path is `missing`; anything else that fails — a file, a folder with
+ * neither marker, or an inaccessible path — is `not-a-project`. Raw filesystem
+ * errors never leave this function.
+ *
+ * Deliberately a SIBLING of {@link hasProjectRootMarker}, which stays `.git`-only
+ * because `install` and `--init` use it and the README pins that wording. A
+ * marker proves only that the path looks like a project, not that it is THIS
+ * project; the stderr source line is how a wrong-but-valid root is noticed.
+ */
+export async function validateExplicitProjectRoot(root, stat) {
+    let info;
+    try {
+        info = await stat(root);
+    }
+    catch (error) {
+        const code = error?.code;
+        return { ok: false, reason: code === "ENOENT" || code === "ENOTDIR" ? "missing" : "not-a-project" };
+    }
+    try {
+        if (!info.isDirectory())
+            return { ok: false, reason: "not-a-project" };
+    }
+    catch {
+        return { ok: false, reason: "not-a-project" };
+    }
+    for (const marker of [path.join(root, ".git"), path.join(root, ".bridge", "config")]) {
+        try {
+            await stat(marker);
+            return { ok: true };
+        }
+        catch {
+            /* try the next marker */
+        }
+    }
+    return { ok: false, reason: "not-a-project" };
+}
+/**
+ * Resolve the project root in the fixed order: a VALID `BAPI_PROJECT_ROOT`,
+ * then MCP `roots/list`, then `CLAUDE_PROJECT_DIR`, then `cwd`. Only the explicit
+ * value is validated — it is the one source written into (possibly committed)
+ * config files, so it is the one that can name another machine's path. The later
+ * sources come from the running host and keep today's behavior. An empty or
+ * whitespace `BAPI_PROJECT_ROOT` is treated as unset.
+ *
+ * Pure apart from the injected seams, so `index.ts` (which cannot be imported in
+ * tests) stays a thin wrapper over this.
+ */
+export async function resolveProjectRoot(options) {
+    let rejectedExplicit;
+    const explicit = (options.env.BAPI_PROJECT_ROOT ?? "").trim();
+    if (explicit.length > 0) {
+        const verdict = await validateExplicitProjectRoot(explicit, options.stat);
+        if (verdict.ok)
+            return { root: explicit, source: "BAPI_PROJECT_ROOT" };
+        rejectedExplicit = { path: explicit, reason: verdict.reason };
+    }
+    const withRejection = (root, source) => rejectedExplicit ? { root, source, rejectedExplicit } : { root, source };
+    let fromRoots = null;
+    try {
+        fromRoots = await options.listRoots();
+    }
+    catch {
+        fromRoots = null;
+    }
+    if (fromRoots && fromRoots.length > 0)
+        return withRejection(fromRoots, "roots/list");
+    const claudeDir = (options.env.CLAUDE_PROJECT_DIR ?? "").trim();
+    if (claudeDir.length > 0)
+        return withRejection(claudeDir, "CLAUDE_PROJECT_DIR");
+    return withRejection(options.cwd(), "cwd");
+}
+/** Resolve `BAPI_DOCS_DIR` (default `docs/tmp`) against the chosen project root. */
+export function resolveDocsDirForRoot(root, env) {
+    return path.resolve(root, env.BAPI_DOCS_DIR ?? "docs/tmp");
+}
+/** Human wording for each closed refusal reason. */
+export const PROJECT_ROOT_REFUSAL_TEXT = {
+    missing: "does not exist",
+    "not-a-project": "is not a project folder (no .git or .bridge/config)",
+};
+/**
+ * The one stderr line the server writes when it first resolves the root, e.g.
+ * `Bridge MCP: project root /home/b/app (from roots/list); BAPI_PROJECT_ROOT
+ * /Users/a/app ignored: does not exist`. Paths are rendered on one line with
+ * control characters escaped.
+ */
+export function formatProjectRootSourceLine(resolved) {
+    let line = `Bridge MCP: project root ${renderDiagnosticValue(resolved.root)} (from ${resolved.source})`;
+    if (resolved.rejectedExplicit) {
+        line +=
+            `; BAPI_PROJECT_ROOT ${renderDiagnosticValue(resolved.rejectedExplicit.path)} ignored: ` +
+                PROJECT_ROOT_REFUSAL_TEXT[resolved.rejectedExplicit.reason];
+    }
+    return line;
+}

package/build/readiness-check.js

@@ -147,7 +147,7 @@ const POSIX_PATH_ROOTS = [
  * Deliberately narrow: it catches the obvious leak (`/Users/...`, `/private/tmp/...`,
  * `C:\\...`) without rejecting the relative, repository-conventional paths
  * remediations legitimately name (`.github/workflows/claude-review.yml`,
- * `docs/claude/epic-implementer-v2-operator-runbook.md`) or the approved setup
+ * `docs/epic-implementer/operator-runbook.md`) or the approved setup
  * URLs (`https://host/setup`) — note the Windows drive alternative requires a
  * word boundary before the letter, so the `s:/` inside `https://` is not a hit.
  */