@bridge_gpt/mcp-server 0.1.14 → 0.1.17

package/README.md

@@ -33,6 +33,49 @@ This runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version s
 
 The MCP server also checks for updates automatically on startup. If a newer version is available, you'll see a notice in your editor's MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.
 
+### CLI subcommand: `start-tickets`
+
+Beyond `--init` / `--upgrade`, the package ships a `start-tickets` subcommand that spawns one Worktrunk worktree + selected-agent session per Jira ticket. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`. It is part of the **existing `bridge-api-mcp-server` bin** — not a separate binary — so it travels with the package to every consumer. It also backs the `/start-tickets` slash command.
+
+```
+npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
+| `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
+| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
+| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
+| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
+| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
+| `--max-parallel N` | `3` | Max worktrees created concurrently |
+| `-h`, `--help` | — | Show usage |
+
+Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent's `'/implement-ticket <KEY>'` — `claude '/implement-ticket <KEY>'` by default, or `cursor-agent '/implement-ticket <KEY>'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:
+
+```
+npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
+```
+
+**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
+
+- **macOS** — opens a Terminal.app or iTerm tab via `osascript`.
+- **Windows** — creates worktrees with **`git-wt`** (Worktrunk's winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.
+- **Linux** — creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.
+
+Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` — Worktrunk's `pre-start` hook runs `uv`, but live preflight does not check it — and the selected agent's command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).
+
+### CLI subcommand: `doctor`
+
+The package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:
+
+```
+npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
+```
+
+It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
+
 ### 2. Generate an API Key
 
 1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project's **Security** page
@@ -195,12 +238,47 @@ Commands are slash commands you invoke from your AI assistant's chat. Most orche
 | `/review-ticket PROJ-123` | Two-round ticket quality review with critiques from multiple LLM providers |
 | `/run-tests` | Run the full test suite, triage failures, and classify issues as test bugs vs. implementation bugs |
 | `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |
+| `/start-tickets KEY [KEY ...]` | Spawn one Worktrunk worktree + selected-agent session per ticket via the packaged `start-tickets` CLI (Claude Code by default, `--agent cursor-agent` for Cursor; macOS Terminal/iTerm, Windows Terminal/PowerShell, or Linux tmux) |
 | `/teach-bridge` | Update a Bridge API configuration field via natural-language instructions |
 | `/update-ticket PROJ-123` | Fetch clarifying questions and critique, then rewrite the ticket description and push to Jira |
 | `/write-ticket` | Draft a new Jira ticket from a prompt and upload it |
 
 > Commands are designed for Claude Code. Other editors may support slash commands differently — check your editor's documentation for how to invoke prompt files.
 
+## Smoke testing
+
+The package ships a canonical, **opt-in** in-host smoke-test runbook at
+`smoke-test/SMOKE-TEST.md`. An AI agent running inside your host (Claude Code,
+Cursor, Codex, Windsurf, or VS Code/Copilot) executes it to verify that the MCP
+server actually works end-to-end *inside that host* — it calls the real tools and
+records a PASS/FAIL verdict for each one in a markdown report.
+
+- `smoke-test/SMOKE-TEST.md` **ships with the npm package** and is the
+  **canonical** source of truth for the smoke test.
+- The smoke test **adds no MCP tool** and **does not change the registered
+  tool surface** (the server still registers its existing 51 tools).
+- It is **opt-in**: default `--init` **does not scaffold `/smoke-test-mcp`**, so
+  consumer command palettes are not polluted.
+
+### Running it
+
+You have two options:
+
+1. **Copy the opt-in command manually.** Copy the packaged command stub into your
+   host's command directory, then invoke `/smoke-test-mcp`:
+
+   ```bash
+   # Claude Code
+   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .claude/commands/smoke-test-mcp.md
+   # Cursor
+   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .cursor/commands/smoke-test-mcp.md
+   ```
+
+2. **Open the runbook directly.** Alternatively, open
+   `smoke-test/SMOKE-TEST.md` and ask the host agent to execute it.
+
+Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`.
+
 ## Available Tools
 
 MCP tools are the low-level primitives Bridge exposes to your AI assistant. You don't call them directly — ask your AI assistant to perform the task you need, or compose them into a custom pipeline.
@@ -350,3 +428,5 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_PROJECT_ROOT` | No | _(auto-set by --init)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution |
 | `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |
 | `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |
+| `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
+| `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |

package/build/agent-launchers/claude.js

@@ -0,0 +1,85 @@
+/**
+ * The v1 `claude` agent launcher (BAPI-327).
+ *
+ * Resolves the `claude` binary against the *baked schedule-time PATH* (not the
+ * ambient process default), builds the locked
+ * `/full-automation --scheduled-at <T> --idea-file <abs> [--auto-approve]`
+ * prompt, and emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
+ * working-directory flag, so the cwd is always set by the scheduler unit — this
+ * adapter must never add a cwd argument to the invocation.
+ */
+import { pathApiForPlatform } from "../scheduler-backends/types.js";
+import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
+/**
+ * Resolve a bare command to an absolute path using the platform PATH-probe,
+ * forcing the baked PATH so the schedule resolves the same binary the user had
+ * at creation time. On Windows both `PATH` and `Path` are overridden (Node and
+ * `where.exe` disagree on casing). Returns the first non-empty *absolute* path
+ * from stdout, or `null` when the probe fails or yields only relative paths.
+ */
+export async function resolveCommandOnPath(command, envPath, deps) {
+    const pathApi = pathApiForPlatform(deps.platform);
+    const probe = deps.platform === "win32" ? "where.exe" : "which";
+    const env = { ...deps.env, PATH: envPath };
+    if (deps.platform === "win32") {
+        // Windows env var lookup is case-insensitive but Node preserves the literal
+        // key; override both casings so neither the probe nor child sees a stale one.
+        env.Path = envPath;
+    }
+    const result = await deps.runCommand(probe, [command], { env });
+    if (result.exitCode !== 0)
+        return null;
+    const candidate = result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    if (!candidate)
+        return null;
+    if (!pathApi.isAbsolute(candidate))
+        return null;
+    return pathApi.normalize(candidate);
+}
+/**
+ * Quote the idea-file path so it survives as a single `/full-automation`
+ * argument even when it contains spaces or markup-significant characters
+ * (`&`, `<`, `>`, …) that would otherwise be split or mangled when the slash
+ * command is parsed. Only an embedded double quote needs escaping; the same
+ * absolute path is additionally baked into `BRIDGE_GPT_IDEA_FILE` by every
+ * backend as a robust environment fallback.
+ */
+export function quoteIdeaFileForPrompt(ideaFile) {
+    return `"${ideaFile.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Build the exact full-automation prompt. `--auto-approve` is appended by
+ * default; it is omitted only when the caller selected `--no-auto-approve`.
+ */
+export function buildClaudePrompt(input) {
+    const base = `/full-automation --scheduled-at ${input.runAtIso} ` +
+        `--idea-file ${quoteIdeaFileForPrompt(input.ideaFile)}`;
+    return input.autoApprove ? `${base} --auto-approve` : base;
+}
+const CLAUDE_CAPABILITY = {
+    name: "claude",
+    command: "claude",
+    supportsCwdFlag: false,
+    promptFlag: "-p",
+};
+/** Create the v1 Claude agent launcher. */
+export function createClaudeLauncher() {
+    return {
+        capability: CLAUDE_CAPABILITY,
+        resolveBinary(envPath, deps) {
+            return resolveCommandOnPath("claude", envPath, deps);
+        },
+        buildInvocation(exe, input) {
+            const prompt = buildClaudePrompt(input);
+            // No working-directory flag: cwd is owned by the scheduler unit.
+            return { exe, args: [CLAUDE_CAPABILITY.promptFlag, prompt], prompt };
+        },
+        formatInvocationLine(invocation, platform) {
+            const quote = platform === "win32" ? windowsCmdQuote : posixShellQuote;
+            return [invocation.exe, ...invocation.args].map((part) => quote(part)).join(" ");
+        },
+    };
+}

package/build/agent-launchers/index.js

@@ -0,0 +1,17 @@
+/**
+ * Agent-launcher registry (BAPI-327). v1 ships only `claude`; the lookup returns
+ * `null` for every other name so the CLI can reject unsupported agents with a
+ * clear message rather than silently falling back.
+ */
+import { createClaudeLauncher } from "./claude.js";
+export { createClaudeLauncher } from "./claude.js";
+const CLAUDE_LAUNCHER = createClaudeLauncher();
+/** Return the launcher for a name, or `null` when unsupported in v1. */
+export function getAgentLauncher(name) {
+    return name === "claude" ? CLAUDE_LAUNCHER : null;
+}
+/** Comma-separated list of valid agent-launcher names (just `claude` in v1). */
+export function formatValidAgentLauncherNames() {
+    const names = ["claude"];
+    return names.join(", ");
+}

package/build/agent-launchers/types.js

@@ -0,0 +1 @@
+export {};

package/build/agent-registry.js

@@ -0,0 +1,68 @@
+/**
+ * agent-registry — the single source of truth for the agents the packaged
+ * `start-tickets` CLI (and the read-only `doctor` subcommand) know how to launch.
+ *
+ * BAPI-305 replaced the former module-level `AGENT_COMMAND = "claude"` swap point
+ * in `start-tickets.ts` with this registry so the agent name -> command mapping
+ * lives in exactly one place. New agents are added by extending `AGENT_REGISTRY`;
+ * no other production module hard-codes an agent command.
+ *
+ * The module is intentionally dependency-free (it imports nothing from
+ * `start-tickets.ts` / `start-tickets-prereqs.ts` / `doctor.ts`) so every other
+ * module can import it without risking a circular dependency.
+ */
+/**
+ * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
+ * with exactly `claude` (default) and `cursor-agent`. `as const satisfies` keeps
+ * the literal keys (so `AgentName` is a precise union) while type-checking each
+ * value against `AgentSpec`.
+ */
+export const AGENT_REGISTRY = {
+    claude: {
+        name: "claude",
+        command: "claude",
+        promptArgStyle: "positional",
+        installHint: {
+            darwin: "npm install -g @anthropic-ai/claude-code",
+            linux: "npm install -g @anthropic-ai/claude-code",
+            win32: "npm install -g @anthropic-ai/claude-code",
+        },
+        authNote: "Claude Code authenticates interactively on first run — follow its login/auth prompt if asked.",
+    },
+    "cursor-agent": {
+        name: "cursor-agent",
+        command: "cursor-agent",
+        promptArgStyle: "positional",
+        installHint: {
+            darwin: "curl https://cursor.com/install -fsSL | bash",
+            linux: "curl https://cursor.com/install -fsSL | bash",
+            win32: "irm 'https://cursor.com/install?win32=true' | iex",
+        },
+        authNote: "Run cursor-agent login to authenticate; doctor checks PATH presence only, not login state.",
+    },
+};
+/** The default agent used when `--agent` is omitted. */
+export const DEFAULT_AGENT_NAME = "claude";
+/** Registry keys in deterministic (insertion) order. */
+export function listAgentNames() {
+    return Object.keys(AGENT_REGISTRY);
+}
+/** Type guard: true only for a registered agent name. */
+export function isAgentName(value) {
+    return listAgentNames().includes(value);
+}
+/**
+ * Resolve an agent name to its spec. An omitted name defaults to
+ * `DEFAULT_AGENT_NAME`; any unknown name (including `""` and wrong-case) returns
+ * `null` so callers can surface a validation error listing the valid names.
+ */
+export function resolveAgentSpec(name) {
+    const resolved = name ?? DEFAULT_AGENT_NAME;
+    if (!isAgentName(resolved))
+        return null;
+    return AGENT_REGISTRY[resolved];
+}
+/** Comma-delimited valid agent names for CLI validation errors (`claude, cursor-agent`). */
+export function formatValidAgentNames() {
+    return listAgentNames().join(", ");
+}