@bridge_gpt/mcp-server 0.1.14 → 0.1.17

package/build/start-tickets-prereqs.js

@@ -0,0 +1,346 @@
+/**
+ * start-tickets-prereqs — the single, shared source of per-OS prerequisite
+ * knowledge for the packaged `start-tickets` automation (BAPI-305).
+ *
+ * Both consumers read from the SAME descriptor set so they can never drift:
+ *   - `runPreflight` (in start-tickets.ts) ENFORCES the preflight descriptors
+ *     fail-fast before a real run (behaviour unchanged from BAPI-302/303).
+ *   - the read-only `doctor` subcommand RENDERS the doctor descriptors
+ *     (preflight set + `uv` + the selected agent) without failing fast.
+ *
+ * Dependency direction: this module imports only TYPES from `start-tickets.ts`
+ * (erased at compile time) and the `AgentSpec` type from `agent-registry.ts`, so
+ * the runtime graph stays acyclic — `start-tickets.ts` imports values FROM here,
+ * never the reverse.
+ */
+// ---------------------------------------------------------------------------
+// Constants (moved here from start-tickets.ts so both consumers share them)
+// ---------------------------------------------------------------------------
+/**
+ * Environment variable that overrides the Worktrunk binary name for nonstandard
+ * installs. Read from the injected `deps.env` (never the global `process.env`)
+ * so the override stays fully mockable in unit tests. Its value may be a bare
+ * command name or an absolute path. Uses the project-wide `BAPI_` prefix.
+ */
+export const WORKTRUNK_BINARY_OVERRIDE_ENV = "BAPI_WORKTRUNK_BIN";
+/** Windows Terminal launcher (distinct from the Worktrunk `git-wt` binary). */
+export const WINDOWS_TERMINAL_COMMAND = "wt.exe";
+/** PowerShell executables tried, in order, for the Windows fallback / launcher. */
+export const WINDOWS_POWERSHELL_CANDIDATES = ["powershell.exe", "powershell"];
+/** Default Worktrunk binary on Windows (winget alias avoids the wt.exe clash). */
+export const DEFAULT_WINDOWS_WORKTRUNK_BINARY = "git-wt";
+/** Default Worktrunk binary on macOS / Linux. */
+export const DEFAULT_POSIX_WORKTRUNK_BINARY = "wt";
+/** tmux binary used for Linux spawning. */
+export const TMUX_COMMAND = "tmux";
+/** Actionable hint emitted when Git Bash is missing on Windows. */
+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";
+/** True only for the three first-class supported platforms. */
+export function isSupportedStartTicketsPlatform(platform) {
+    return platform === "darwin" || platform === "win32" || platform === "linux";
+}
+/** Message shown when spawning is attempted on an unsupported platform. */
+export function unsupportedPlatformMessage(platform) {
+    return (`start-tickets does not support this platform: '${platform}' is unsupported. ` +
+        "Supported platforms are darwin, win32, and linux. " +
+        "Use --dry-run to preview the intended commands on any OS.");
+}
+// ---------------------------------------------------------------------------
+// Worktrunk binary resolution + command probing (moved from start-tickets.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the Worktrunk binary name for a platform. A trimmed, non-empty
+ * `BAPI_WORKTRUNK_BIN` override wins; otherwise `git-wt` on Windows and `wt`
+ * elsewhere (including a non-throwing `wt` fallback for dry-run-only callers on
+ * unsupported platforms).
+ */
+export function resolveWorktrunkBinary(platform, env) {
+    const override = env[WORKTRUNK_BINARY_OVERRIDE_ENV];
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    if (platform === "win32")
+        return DEFAULT_WINDOWS_WORKTRUNK_BINARY;
+    return DEFAULT_POSIX_WORKTRUNK_BINARY;
+}
+/** True when a command result has exit code 0. */
+export function commandSucceeded(result) {
+    return result.exitCode === 0;
+}
+/** The platform-correct PATH probe: `where` on Windows, `which` elsewhere. */
+export function getCommandProbe(tool, platform) {
+    if (platform === "win32")
+        return { file: "where", args: [tool] };
+    return { file: "which", args: [tool] };
+}
+/** True when `tool` is resolvable on PATH using the platform-correct probe. */
+export async function isCommandOnPath(deps, tool) {
+    const probe = getCommandProbe(tool, deps.platform);
+    const result = await deps.runCommand(probe.file, probe.args);
+    return commandSucceeded(result);
+}
+/** Return the first candidate command found on PATH, or null. Stops on first hit. */
+export async function resolveFirstCommandOnPath(deps, candidates) {
+    for (const candidate of candidates) {
+        if (await isCommandOnPath(deps, candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Windows-only usability probe for Git Bash. Uses a list-based `bash --version`
+ * rather than a bare `where bash` because Git for Windows commonly omits bash.exe
+ * from PATH while still shipping a usable bash.
+ */
+export async function requireBashUsable(deps) {
+    const result = await deps.runCommand("bash", ["--version"]);
+    if (commandSucceeded(result))
+        return { ok: true };
+    return {
+        ok: false,
+        error: `bash is required on Windows but could not be run. ${GIT_FOR_WINDOWS_BASH_HINT}`,
+    };
+}
+/** Append the read-only doctor hint to a preflight failure message. */
+export function appendDoctorHint(error) {
+    return `${error} Hint: Run ${START_TICKETS_DOCTOR_COMMAND} for a read-only start-tickets diagnostics report.`;
+}
+function hintForPlatform(hints, platform) {
+    if (platform === "win32")
+        return hints.win32;
+    if (platform === "linux")
+        return hints.linux;
+    return hints.darwin;
+}
+const WORKTRUNK_INSTALL_HINTS = {
+    darwin: "brew install worktrunk",
+    // Worktrunk installs as the git-wt winget alias on Windows.
+    win32: "Install Worktrunk via winget; it installs as the git-wt alias on Windows.",
+    // No universal one-line installer on Linux — point at the docs (link-only).
+    linux: "See the Worktrunk documentation for Linux install instructions: https://worktrunk.dev",
+};
+const GIT_INSTALL_HINTS = {
+    darwin: "xcode-select --install (or brew install git)",
+    linux: "Install git with your distro package manager, e.g. apt install git",
+    win32: "Install Git for Windows: https://git-scm.com/download/win",
+};
+const OSASCRIPT_INSTALL_HINTS = {
+    darwin: "osascript ships with macOS; if it is missing, repair your macOS command line tools.",
+    linux: "osascript is macOS-only.",
+    win32: "osascript is macOS-only.",
+};
+const TMUX_INSTALL_HINTS = {
+    darwin: "brew install tmux",
+    linux: "Install tmux with your distro package manager, e.g. apt install tmux",
+    win32: "tmux is used only on Linux.",
+};
+const GIT_BASH_INSTALL_HINTS = {
+    darwin: GIT_FOR_WINDOWS_BASH_HINT,
+    linux: GIT_FOR_WINDOWS_BASH_HINT,
+    win32: GIT_FOR_WINDOWS_BASH_HINT,
+};
+const WINDOWS_LAUNCHER_INSTALL_HINTS = {
+    darwin: "Windows Terminal / PowerShell are used only on Windows.",
+    linux: "Windows Terminal / PowerShell are used only on Windows.",
+    win32: "Install Windows Terminal (winget install Microsoft.WindowsTerminal) or ensure powershell.exe is on PATH.",
+};
+const GIT_WORK_TREE_INSTALL_HINTS = {
+    darwin: "Run start-tickets from inside a git repository work tree.",
+    linux: "Run start-tickets from inside a git repository work tree.",
+    win32: "Run start-tickets from inside a git repository work tree.",
+};
+const UV_INSTALL_HINTS = {
+    darwin: "brew install uv",
+    linux: "curl -LsSf https://astral.sh/uv/install.sh | sh",
+    win32: 'powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"',
+};
+function commandDescriptor(tool, label, installHint) {
+    return {
+        id: tool,
+        label,
+        installHint,
+        preflightError: `Required command not found on PATH: ${tool}.`,
+        probe: async (deps) => {
+            const found = await isCommandOnPath(deps, tool);
+            return found ? { found: true, detail: "found on PATH" } : { found: false };
+        },
+    };
+}
+function worktrunkDescriptor(binary) {
+    return {
+        id: "worktrunk",
+        label: `Worktrunk (${binary})`,
+        installHint: WORKTRUNK_INSTALL_HINTS,
+        preflightError: `Required command not found on PATH: ${binary}.`,
+        probe: async (deps) => {
+            const found = await isCommandOnPath(deps, binary);
+            // The resolved binary is shown via the label (`Worktrunk (<binary>)`); the
+            // detail stays generic so preflight enforcement uses `preflightError`.
+            return found ? { found: true, detail: "found on PATH" } : { found: false };
+        },
+    };
+}
+function gitBashDescriptor() {
+    return {
+        id: "git-bash",
+        label: "Git Bash (bash)",
+        installHint: GIT_BASH_INSTALL_HINTS,
+        probe: async (deps) => {
+            const result = await requireBashUsable(deps);
+            return result.ok ? { found: true, detail: "bash --version ok" } : { found: false, detail: result.error };
+        },
+    };
+}
+function windowsLauncherDescriptor() {
+    const candidates = [WINDOWS_TERMINAL_COMMAND, ...WINDOWS_POWERSHELL_CANDIDATES];
+    return {
+        id: "windows-launcher",
+        label: "Windows Terminal or PowerShell",
+        installHint: WINDOWS_LAUNCHER_INSTALL_HINTS,
+        preflightError: "Windows Terminal (wt.exe) or PowerShell is required to open a tab. " +
+            "Install Windows Terminal or ensure powershell.exe is on PATH.",
+        probe: async (deps) => {
+            const found = await resolveFirstCommandOnPath(deps, candidates);
+            return found ? { found: true, detail: found } : { found: false };
+        },
+    };
+}
+function gitWorkTreeDescriptor() {
+    return {
+        id: "git-work-tree",
+        label: "git work tree",
+        installHint: GIT_WORK_TREE_INSTALL_HINTS,
+        probe: async (deps) => {
+            const revParse = await deps.runCommand("git", ["rev-parse", "--is-inside-work-tree"], {
+                cwd: deps.cwd,
+            });
+            if (!commandSucceeded(revParse)) {
+                return {
+                    found: false,
+                    detail: "start-tickets must be run inside a git repository (git rev-parse --is-inside-work-tree failed).",
+                };
+            }
+            if (revParse.stdout.trim() !== "true") {
+                return {
+                    found: false,
+                    detail: "start-tickets must be run inside a git work tree (git rev-parse --is-inside-work-tree did not report 'true').",
+                };
+            }
+            return { found: true, detail: "inside a git work tree" };
+        },
+    };
+}
+function agentDescriptor(agent) {
+    return {
+        id: agent.command,
+        label: agent.name,
+        installHint: agent.installHint,
+        authNote: agent.authNote,
+        preflightError: `Required command not found on PATH: ${agent.command}.`,
+        probe: async (deps) => {
+            const found = await isCommandOnPath(deps, agent.command);
+            return found ? { found: true, detail: "found on PATH" } : { found: false };
+        },
+    };
+}
+function uvDescriptor() {
+    return commandDescriptor("uv", "uv", UV_INSTALL_HINTS);
+}
+/**
+ * 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
+ * place the per-OS preflight knowledge lives; `runPreflight` enforces it and
+ * `doctor` renders it (via `getDoctorPrereqDescriptors`). Returns a structured
+ * unsupported-platform error for non-darwin/win32/linux.
+ */
+export function getPreflightPrereqDescriptors(platform, env) {
+    if (!isSupportedStartTicketsPlatform(platform)) {
+        return { ok: false, error: unsupportedPlatformMessage(platform) };
+    }
+    const worktrunkBinary = resolveWorktrunkBinary(platform, env);
+    const descriptors = [worktrunkDescriptor(worktrunkBinary)];
+    descriptors.push(commandDescriptor("git", "git", GIT_INSTALL_HINTS));
+    if (platform === "darwin") {
+        descriptors.push(commandDescriptor("osascript", "osascript", OSASCRIPT_INSTALL_HINTS));
+    }
+    else if (platform === "win32") {
+        descriptors.push(gitBashDescriptor());
+        descriptors.push(windowsLauncherDescriptor());
+    }
+    else {
+        descriptors.push(commandDescriptor(TMUX_COMMAND, TMUX_COMMAND, TMUX_INSTALL_HINTS));
+    }
+    // Git work-tree check shares the same descriptor source so runPreflight and
+    // doctor never drift on it.
+    descriptors.push(gitWorkTreeDescriptor());
+    return { ok: true, descriptors };
+}
+/**
+ * Doctor-only prerequisites: `uv` (a real gap — Worktrunk's pre-start hook runs
+ * `uv`, but live preflight does not check it) and the selected agent command.
+ * These are intentionally kept out of `runPreflight` so live behaviour stays
+ * additive (BAPI-302/303 regression-safe).
+ */
+export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
+    return [uvDescriptor(), agentDescriptor(agent)];
+}
+/**
+ * The doctor's full descriptor set: the preflight descriptors (verbatim) plus
+ * the doctor-only `uv` and selected-agent descriptors. The preflight prefix is
+ * byte-for-byte the same as `getPreflightPrereqDescriptors`, which a drift-guard
+ * test asserts.
+ */
+export function getDoctorPrereqDescriptors(platform, env, agent) {
+    const preflight = getPreflightPrereqDescriptors(platform, env);
+    if (!preflight.ok)
+        return preflight;
+    return {
+        ok: true,
+        descriptors: [...preflight.descriptors, ...getDoctorOnlyPrereqDescriptors(platform, env, agent)],
+    };
+}
+/** Probe one descriptor without throwing, resolving its platform-specific hint. */
+export async function probePrerequisite(deps, descriptor) {
+    let outcome;
+    try {
+        outcome = await descriptor.probe(deps);
+    }
+    catch (err) {
+        outcome = { found: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+    return {
+        id: descriptor.id,
+        label: descriptor.label,
+        found: outcome.found,
+        detail: outcome.detail,
+        installHint: hintForPlatform(descriptor.installHint, deps.platform),
+        authNote: descriptor.authNote,
+    };
+}
+/**
+ * Enforce the preflight descriptors fail-fast (matching the existing
+ * `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.
+ */
+export async function enforcePreflightPrerequisites(deps) {
+    const descriptorsResult = getPreflightPrereqDescriptors(deps.platform, deps.env);
+    if (!descriptorsResult.ok) {
+        return { ok: false, reason: "unsupported-platform", error: descriptorsResult.error };
+    }
+    for (const descriptor of descriptorsResult.descriptors) {
+        const probed = await probePrerequisite(deps, descriptor);
+        if (!probed.found) {
+            // Command-style descriptors carry their message in `preflightError`; the
+            // custom Git Bash / git-work-tree checks carry a specific message in
+            // `detail`. Prefer the descriptor's own error, then the probe detail.
+            const error = descriptor.preflightError ?? probed.detail ?? `Missing prerequisite: ${descriptor.label}.`;
+            return { ok: false, reason: "missing-prerequisite", error };
+        }
+    }
+    return { ok: true };
+}