@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/start-tickets-prereqs.js

@@ -13,6 +13,7 @@
  * the runtime graph stays acyclic — `start-tickets.ts` imports values FROM here,
  * never the reverse.
  */
+import path from "path";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
@@ -40,6 +41,29 @@ export const TMUX_COMMAND = "tmux";
 export const GIT_FOR_WINDOWS_BASH_HINT = "Install Git for Windows / Git Bash — Worktrunk runs its pre-start / post-start hooks via Git Bash.";
 /** The read-only doctor invocation surfaced from preflight failures and elsewhere. */
 export const START_TICKETS_DOCTOR_COMMAND = "npx -y @bridge_gpt/mcp-server doctor";
+/**
+ * BAPI-527 live-source checkout guard (conductor durable execution).
+ *
+ * `BAPI_CONDUCTOR_LIVE_SOURCE_PATH` — OPTIONAL operator-set path to the checkout
+ * an operator's live dev server (e.g. `uvicorn main:app --reload`) is running
+ * from. When set, unattended conductor/epic/non-mutating start-tickets dispatch
+ * refuses to run if the conductor base repo it would operate on resolves to the
+ * SAME checkout, because cutting worktrees / touching branches under a live
+ * dev-server checkout risks corrupting the operator's working state. No existing
+ * "live dev-server source path" convention was found in the codebase during
+ * discovery, so this local env contract is introduced here. Read only from the
+ * injected `deps.env` (never global `process.env`) so it stays mockable.
+ *
+ * `BAPI_CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH` — explicit escape hatch. When set
+ * to a truthy value (`1`/`true`/`yes`/`on`, case-insensitive) a detected
+ * collision is DOWNGRADED from fatal to a loud warning rather than silently
+ * ignored, so an operator who genuinely wants same-checkout dispatch can opt in
+ * with eyes open.
+ */
+export const CONDUCTOR_LIVE_SOURCE_PATH_ENV = "BAPI_CONDUCTOR_LIVE_SOURCE_PATH";
+export const CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV = "BAPI_CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH";
+/** Stable descriptor id for the live-source checkout guard (used in messages + doctor). */
+export const LIVE_SOURCE_GUARD_ID = "conductor-live-source";
 /** True only for the three first-class supported platforms. */
 export function isSupportedStartTicketsPlatform(platform) {
     return platform === "darwin" || platform === "win32" || platform === "linux";
@@ -254,6 +278,34 @@ function uvDescriptor() {
     return commandDescriptor("uv", "uv", UV_INSTALL_HINTS);
 }
 // ---------------------------------------------------------------------------
+// review-tickets git prerequisite (BAPI-474). review-tickets has its own
+// terminal-launcher-only live preflight (runReviewTicketsPreflight in
+// review-tickets.ts) — separate from getPreflightPrereqDescriptors above,
+// which is start-tickets-specific. Since the parent-fetch-once base pin now
+// requires git for review-tickets too (unless --no-refresh-base is passed),
+// this doctor-only descriptor gives it its own distinctly-labeled,
+// read-only-diagnosable entry rather than relying on the generic start-tickets
+// "git" descriptor, so a user running review-tickets alone can self-diagnose.
+// ---------------------------------------------------------------------------
+const REVIEW_TICKETS_GIT_INSTALL_HINTS = {
+    darwin: `${GIT_INSTALL_HINTS.darwin} (or rerun review-tickets with --no-refresh-base to skip the fetch)`,
+    linux: `${GIT_INSTALL_HINTS.linux} (or rerun review-tickets with --no-refresh-base to skip the fetch)`,
+    win32: `${GIT_INSTALL_HINTS.win32} (or rerun review-tickets with --no-refresh-base to skip the fetch)`,
+};
+function reviewTicketsGitDescriptor() {
+    return {
+        id: "review-tickets-git",
+        label: "git (required by review-tickets base-branch fetch)",
+        installHint: REVIEW_TICKETS_GIT_INSTALL_HINTS,
+        probe: async (deps) => {
+            const found = await isCommandOnPath(deps, "git");
+            return found
+                ? { found: true, detail: "found on PATH" }
+                : { found: false, detail: "review-tickets' parent-fetch-once base pin needs git unless --no-refresh-base is passed" };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
 // regression-check (BAPI-460) doctor-only tool descriptors. These probe the
 // deterministic tooling regression-check relies on (ast-grep, ripgrep,
 // lizard). They are doctor-diagnosable but NOT preflight blockers: a missing
@@ -270,10 +322,11 @@ const LIZARD_INSTALL_HINTS = {
     linux: "uv tool install lizard",
     win32: "uv tool install lizard",
 };
+const RIPGREP_SHELL_FUNCTION_CAVEAT = "a shell function/alias will not satisfy this check — ripgrep must be installed as a real PATH binary.";
 const RIPGREP_INSTALL_HINTS = {
-    darwin: "brew install ripgrep",
-    linux: "Install ripgrep with your distro package manager, e.g. apt install ripgrep",
-    win32: "winget install BurntSushi.ripgrep.MSVC",
+    darwin: `brew install ripgrep (${RIPGREP_SHELL_FUNCTION_CAVEAT})`,
+    linux: `Install ripgrep with your distro package manager, e.g. apt install ripgrep (${RIPGREP_SHELL_FUNCTION_CAVEAT})`,
+    win32: `winget install BurntSushi.ripgrep.MSVC (${RIPGREP_SHELL_FUNCTION_CAVEAT})`,
 };
 /** ast-grep ships two equivalent binary names (`ast-grep` and `sg`); either satisfies the probe. */
 function astGrepDescriptor() {
@@ -383,6 +436,107 @@ export function worktreeMcpReachabilityDescriptor() {
         },
     };
 }
+/**
+ * Conservatively normalize a filesystem path for comparison: trim, drop a
+ * trailing separator, and resolve `.`/`..` segments via `path.resolve`. Symlink
+ * canonicalization is handled UPSTREAM by `git rev-parse --show-toplevel` (which
+ * returns the real, absolute repo root); this in-memory step is the fallback for
+ * a path that is not a git work tree. Never touches the filesystem.
+ */
+export function normalizeCheckoutPath(rawPath) {
+    const trimmed = rawPath.trim();
+    const resolved = path.resolve(trimmed);
+    // Strip a redundant trailing separator (path.resolve already removes most, but
+    // a bare root like "/" must be preserved).
+    return resolved.length > 1 ? resolved.replace(/[\\/]+$/, "") : resolved;
+}
+/**
+ * Resolve the repository ROOT for a path using the authoritative, read-only
+ * `git -C <path> rev-parse --show-toplevel`. Falls back to conservative
+ * in-memory normalization when the target is not a git work tree (or git is
+ * unavailable) so the guard still produces a comparable path. Never mutates.
+ */
+export async function resolveRepoRootPath(deps, targetPath) {
+    const result = await deps.runCommand("git", ["-C", targetPath, "rev-parse", "--show-toplevel"], { cwd: deps.cwd });
+    if (commandSucceeded(result)) {
+        const top = result.stdout.trim();
+        if (top.length > 0)
+            return normalizeCheckoutPath(top);
+    }
+    return normalizeCheckoutPath(targetPath);
+}
+/** True when the override env is set to a recognized truthy value (case-insensitive). */
+export function isLiveSourceDispatchOverrideEnabled(env) {
+    const raw = env[CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV];
+    if (raw === undefined)
+        return false;
+    return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
+}
+/**
+ * Evaluate the live-source guard read-only. Resolves the conductor base repo root
+ * (from `deps.cwd`) and the configured live-source root, then compares them after
+ * conservative normalization. Returns one of three states; never throws, never
+ * mutates.
+ */
+export async function evaluateLiveSourceGuard(deps) {
+    const rawLiveSource = deps.env[CONDUCTOR_LIVE_SOURCE_PATH_ENV];
+    if (!rawLiveSource || rawLiveSource.trim().length === 0) {
+        return {
+            state: "not-configured",
+            detail: `no live dev-server source configured (${CONDUCTOR_LIVE_SOURCE_PATH_ENV} unset) — guard inactive`,
+        };
+    }
+    const baseRepoPath = await resolveRepoRootPath(deps, deps.cwd);
+    const liveSourcePath = await resolveRepoRootPath(deps, rawLiveSource);
+    if (baseRepoPath === liveSourcePath) {
+        return {
+            state: "collision",
+            detail: `COLLISION: the conductor base checkout (${baseRepoPath}) is the SAME checkout as the ` +
+                `configured live dev-server source (${CONDUCTOR_LIVE_SOURCE_PATH_ENV}). Unattended dispatch ` +
+                `would create worktrees / touch branches under a running dev server.`,
+            baseRepoPath,
+            liveSourcePath,
+        };
+    }
+    return {
+        state: "safe",
+        detail: `safe: conductor base checkout (${baseRepoPath}) differs from the configured live ` +
+            `dev-server source (${liveSourcePath})`,
+        baseRepoPath,
+        liveSourcePath,
+    };
+}
+/** Per-OS remediation hint for the live-source guard (secret-free). */
+const LIVE_SOURCE_GUARD_HINT = `Point ${CONDUCTOR_LIVE_SOURCE_PATH_ENV} at your live dev server's checkout ONLY when it ` +
+    `differs from this conductor base checkout, or dispatch the conductor from a separate clone. ` +
+    `To override the guard and dispatch anyway (not recommended), set ` +
+    `${CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV}=1.`;
+const LIVE_SOURCE_GUARD_INSTALL_HINTS = {
+    darwin: LIVE_SOURCE_GUARD_HINT,
+    linux: LIVE_SOURCE_GUARD_HINT,
+    win32: LIVE_SOURCE_GUARD_HINT,
+};
+/**
+ * Doctor-only, strictly read-only descriptor that surfaces the three live-source
+ * guard states through the EXISTING doctor render (found + detail / missing +
+ * install hint):
+ *   - not-configured → `found: true`  (guard inactive, neutral)
+ *   - safe           → `found: true`  (different checkouts, safe)
+ *   - collision      → `found: false` (renders as a flagged problem + override hint)
+ * The runtime path specifics ride in `detail` for programmatic consumers.
+ */
+export function liveSourceGuardDescriptor() {
+    return {
+        id: LIVE_SOURCE_GUARD_ID,
+        label: "Conductor live-source checkout guard",
+        installHint: LIVE_SOURCE_GUARD_INSTALL_HINTS,
+        probe: async (deps) => {
+            const outcome = await evaluateLiveSourceGuard(deps);
+            // Only a collision reads as a problem; not-configured and safe are neutral.
+            return { found: outcome.state !== "collision", detail: outcome.detail };
+        },
+    };
+}
 /**
  * The exact existing live-preflight requirement set per platform, plus the git
  * work-tree custom check appended after the command checks. This is the ONLY
@@ -427,6 +581,8 @@ export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
         astGrepDescriptor(),
         lizardDescriptor(),
         ripgrepDescriptor(),
+        reviewTicketsGitDescriptor(),
+        liveSourceGuardDescriptor(),
     ];
 }
 /**
@@ -467,8 +623,14 @@ export async function probePrerequisite(deps, descriptor) {
  * `runPreflight` behaviour). Iterates the shared preflight descriptors in order
  * and returns on the first missing one. `uv` and the selected agent are NOT
  * enforced here — they are doctor-only. Never throws.
+ *
+ * BAPI-527: when `options.enforceLiveSourceGuard` is set (unattended
+ * conductor/epic/non-mutating dispatch), the live-source checkout guard is
+ * additionally evaluated after the standard loop — a collision is fatal
+ * (`live-source-collision`) unless the override env downgrades it to a returned
+ * `warning`.
  */
-export async function enforcePreflightPrerequisites(deps) {
+export async function enforcePreflightPrerequisites(deps, options = {}) {
     const descriptorsResult = getPreflightPrereqDescriptors(deps.platform, deps.env);
     if (!descriptorsResult.ok) {
         return { ok: false, reason: "unsupported-platform", error: descriptorsResult.error };
@@ -483,5 +645,24 @@ export async function enforcePreflightPrerequisites(deps) {
             return { ok: false, reason: "missing-prerequisite", error };
         }
     }
+    // BAPI-527 live-source checkout guard (unattended dispatch only). Read-only.
+    if (options.enforceLiveSourceGuard) {
+        const guard = await evaluateLiveSourceGuard(deps);
+        if (guard.state === "collision") {
+            const base = `Live-source checkout guard (${LIVE_SOURCE_GUARD_ID}): ${guard.detail}`;
+            if (isLiveSourceDispatchOverrideEnabled(deps.env)) {
+                return {
+                    ok: true,
+                    warning: `${base} Proceeding anyway because ${CONDUCTOR_ALLOW_LIVE_SOURCE_DISPATCH_ENV} is set — ` +
+                        `dispatching under a live dev-server checkout can corrupt the operator's working state.`,
+                };
+            }
+            return {
+                ok: false,
+                reason: "live-source-collision",
+                error: `${base} Refusing unattended dispatch. ${LIVE_SOURCE_GUARD_HINT}`,
+            };
+        }
+    }
     return { ok: true };
 }