@bridge_gpt/mcp-server 0.2.30 → 0.2.32

package/README.md

@@ -31,18 +31,29 @@ npx -y @bridge_gpt/mcp-server@latest install-bridge
 ```
 
 Run bare like that in a terminal and it starts by asking
-**`Do you have a Bridge API key or invite? [Y/n]`**:
-
-- **Yes** (or just press Enter) — the existing-key flow. It asks for your **API key**
-  (generate one on the Bridge API web UI **Security** page) and a **repo name**
-  matching your server-side registration; everything else is derived. A
-  `bapi_inv_…` credential entered here instead of a full API key is automatically
-  detected and redeemed as a **bootstrap invite** — it creates a brand-new project
-  and mints your admin API key rather than looking up an existing repository.
-- **No** — the **self-serve** flow. It asks for an **email**, then a name for your new
-  Bridge project, and creates the workspace and your own admin API key for you. No
-  account, no key, and no invite needed beforehand. Same as passing
-  `--email you@example.com` (see below).
+**`How would you like to connect to Bridge API?`** with three numbered choices:
+
+```
+1. I have a Bridge API key
+2. I have an invite token
+3. I'm new — set me up with just my email
+```
+
+- **1** — the existing-key flow. It asks for your **API key** (generate one on the
+  Bridge API web UI **Security** page) and a **repo name** matching your server-side
+  registration; everything else is derived. A `bapi_inv_…` credential entered here
+  instead of a full API key is automatically detected and redeemed as a **bootstrap
+  invite** — it creates a brand-new project and mints your admin API key rather than
+  looking up an existing repository.
+- **2** — the **bootstrap-invite** flow. It asks for the invite token you were given,
+  with echo suppressed. Same as passing `--invite` (see below).
+- **3** — the **self-serve** flow, and the right answer if you have nothing yet. It
+  asks for an **email**, then a name for your new Bridge project, and creates the
+  workspace and your own admin API key for you. No account, no key, and no invite
+  needed beforehand. Same as passing `--email you@example.com` (see below).
+
+There is **no default**: pressing Enter selects nothing. A blank or invalid answer
+re-prompts once with a hint, then exits with guidance naming all three routes.
 
 That question is asked only for a *bare interactive* run. Passing any flag, setting
 `BAPI_API_KEY`, or running without an interactive terminal skips it and keeps the
@@ -51,11 +62,12 @@ existing deterministic behavior.
 From there `install-bridge` scaffolds the project, writes your editor's MCP config
 with real values, verifies connectivity, persists your API key to the user-scoped
 credential store, and opens a fresh agent session that runs `/install-bridge` to
-derive and apply the remaining config, presents a **capability report** (what you can
-use now and what you'll unlock), and closes by asking whether to index the
-repository. It does **not** automatically run `/learn-repository` or index without
-your consent — both remain available as separate steps. Add `--dry-run` to preview
-every step without writing, pinging, or spawning anything.
+derive and apply the remaining config, presents a concise **capability report**
+("What Bridge can help with"), and recommends `/learn-repository` as your next step.
+It does **not** run `/learn-repository` itself — that stays your next explicit
+invocation. There is **no indexing question**: indexing starts automatically
+server-side once the repository reaches full parse readiness. Add `--dry-run` to
+preview every step without writing, pinging, or spawning anything.
 
 **Were you sent a bootstrap invite?** Then you don't need an API key or the web UI
 at all — run the command your operator gave you:
@@ -148,12 +160,30 @@ shown**.
 The email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a
 **visible** interactive prompt (email is not a secret, so it is echoed as you type —
 unlike the API key and the invite token, which use a hidden prompt). That prompt is
-what answering **no** to `Do you have a Bridge API key or invite? [Y/n]` on a bare run reaches,
-so `install-bridge --email you@example.com` and a bare `install-bridge` + "no" land
-in the same place. The email is still **never written to a log line**. No email
+what **option 3** of the bare-run chooser reaches, so
+`install-bridge --email you@example.com` and a bare `install-bridge` + `3` land in
+the same place. The email is still **never written to a log line**. No email
 verification is performed and no message is sent to the address — it only labels your
 new workspace. `--email` is mutually exclusive with `--api-key` and `--invite`.
 
+##### Self-serve retries resume automatically
+
+A self-serve run that fails part-way through — a network blip on the exchange, a
+failed connectivity check, an interrupted credential write — saves its signup state
+under `bootstrap-pending:<repo>` in the credential store (mode `0600`, fsync'd, the
+same record that already holds your `key_secret`).
+
+**Just re-run the self-serve flow.** It detects that saved attempt, prints
+`resuming your previous signup attempt for <repo>`, and re-drives the *same*
+exchange — it does **not** sign up again, so a retry never creates a second
+workspace. This is why the self-serve record stores the minted invite token: you
+were never shown that token, so nothing else could re-present it.
+
+Do **not** copy, display, or hand-remove that record. If the saved invite has
+genuinely expired, the CLI says so and **asks for confirmation** before discarding
+it and starting fresh — it never discards it silently, because a record whose
+exchange already succeeded is the only trace of a live admin key.
+
 Because this flow *creates* the project, it asks you to **name a new project**
 (`Name your new Bridge project [<inferred>]: `) rather than to match an existing
 server-side registration. The name must be globally unique; if it's taken, you're
@@ -689,12 +719,14 @@ Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for
 
 ### `doctor`
 
-The package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:
+The package also ships a strictly **read-only** `doctor` subcommand — titled **`bridge doctor — read-only diagnostics`** — that diagnoses your whole Bridge install without changing anything:
 
 ```
 npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
 ```
 
+The report always leads with the advisory **`Install status`** section (repo identity, credential resolution, server connectivity, bootstrap-field completeness, integration credentials, indexing state) **before** the `start-tickets` prerequisite diagnostics; the launcher-cache and MCP tool-surface sections follow. `Install status` is read-only GETs only and never affects the exit code.
+
 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.
 
 ### `setup-epic`

package/build/command-assets-doctor.js

@@ -0,0 +1,72 @@
+/**
+ * Read-only worktree Claude command-asset diagnostic (doctor-only, BAPI-664).
+ *
+ * Reports whether the current worktree contains every packaged Claude slash
+ * command under `.claude/commands/`. This probe ONLY reads command paths — it
+ * never writes, creates directories, invokes Git, spawns a process, compares or
+ * reports command file CONTENTS, or leaks raw exceptions. A committed customer
+ * version of a command counts as present regardless of its contents (the command
+ * bundle is fill-only and never refreshed), so the probe checks presence /
+ * readability, not freshness. The sole injected dependencies are `readFile` and
+ * `platform`.
+ */
+import path from "path";
+import { COMMANDS } from "./commands.generated.js";
+/** Stable user-facing relative location shown in every detail string. */
+const COMMAND_DIR_LABEL = ".claude/commands/";
+/** How many missing filenames to list before summarizing the remainder. */
+const MAX_LISTED_MISSING = 5;
+/** The `path` API for the target platform (win32 vs posix). */
+function pathApiForPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/** Render a bounded, deterministic list of missing filenames (generated order). */
+function formatMissing(missing) {
+    if (missing.length <= MAX_LISTED_MISSING) {
+        return missing.join(", ");
+    }
+    const shown = missing.slice(0, MAX_LISTED_MISSING).join(", ");
+    return `${shown} (+${missing.length - MAX_LISTED_MISSING} more)`;
+}
+/**
+ * Probe whether `<worktreeRoot>/.claude/commands/` contains every packaged
+ * command asset. A `readFile` that resolves counts the asset as present (any
+ * contents); a rejection (missing OR unreadable) counts it as absent. Returns
+ * `found: true` only when every packaged command filename is present, otherwise a
+ * `found: false` result with a concise, actionable, secret-free detail that
+ * points the operator back to `start-tickets` (never to manually copying or
+ * committing generated files).
+ */
+export async function probeWorktreeCommandAssets(worktreeRoot, deps) {
+    const filenames = Object.keys(COMMANDS);
+    if (filenames.length === 0) {
+        return {
+            found: false,
+            detail: "Packaged command bundle is empty — reinstall or rebuild the MCP server package.",
+        };
+    }
+    const api = pathApiForPlatform(deps.platform);
+    const commandsDir = api.join(worktreeRoot, ".claude", "commands");
+    const missing = [];
+    for (const filename of filenames) {
+        try {
+            await deps.readFile(api.join(commandsDir, filename));
+        }
+        catch {
+            // Missing OR unreadable — either way the asset is not usable. We never
+            // surface the underlying error (it can carry paths / exception text).
+            missing.push(filename);
+        }
+    }
+    if (missing.length === 0) {
+        return {
+            found: true,
+            detail: `${filenames.length} packaged command assets present under ${COMMAND_DIR_LABEL}`,
+        };
+    }
+    return {
+        found: false,
+        detail: `${missing.length} of ${filenames.length} packaged command assets missing or unreadable under ` +
+            `${COMMAND_DIR_LABEL} (${formatMissing(missing)}). Re-run start-tickets to provision them.`,
+    };
+}

package/build/command-provisioning.js

@@ -0,0 +1,157 @@
+/**
+ * Shared Claude command-asset provisioning (BAPI-664).
+ *
+ * Materializes the FULL packaged command bundle (`COMMANDS` from
+ * `commands.generated.ts`, the single source of truth) into a worktree's
+ * `.claude/commands/` directory so every packaged slash command is runnable from
+ * a freshly created worktree — whether spawned by the interactive `start-tickets`
+ * orchestration or by the headless conductor executor.
+ *
+ * Semantics (locked ticket decisions):
+ *   - FULL bundle: every entry in `COMMANDS` is provisioned.
+ *   - FILL-ONLY: a command file that already exists is treated as a customer asset
+ *     and left byte-for-byte unchanged — its contents are never read-compared or
+ *     refreshed. Only a missing (`ENOENT`) file is created. There is no refresh
+ *     flag.
+ *   - Repository-common exclude: after materialization, `.claude/commands/` is
+ *     added to the worktree's Git `info/exclude` (resolved via Git for linked
+ *     worktrees). `info/exclude` lives in the common Git directory shared by
+ *     sibling worktrees, and an ignore rule never hides an already-tracked file,
+ *     so this common scope is safe.
+ *
+ * All filesystem + command access is dependency-injected so this is unit-testable
+ * with no real I/O. This module NEVER imports `node:fs` / `child_process`, writes
+ * to stdout/stderr, or registers an MCP tool — failures are surfaced structurally
+ * and rendered by the caller's existing orchestration boundary.
+ */
+import path from "path";
+import { COMMANDS } from "./commands.generated.js";
+import { ensureGitInfoExcluded } from "./git-ignore-utils.js";
+/** The exact exclude entry appended for the command directory (POSIX-relative). */
+const COMMAND_DIR_EXCLUDE_ENTRY = ".claude/commands/";
+/** Bounded, secret-free error surfaced when the packaged bundle is empty. */
+const EMPTY_BUNDLE_ERROR = "Command provisioning failed: the packaged command bundle is empty — reinstall or rebuild the MCP server package.";
+/**
+ * Resolve the path API for the target platform. Local (not imported from
+ * `start-tickets.ts`) to avoid a runtime import cycle.
+ */
+export function pathApiForCommandProvisioningPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/** True only for a Node `ENOENT` (missing-file) error. */
+function isEnoentError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+/**
+ * Fill every MISSING packaged command asset into `<worktreeRoot>/.claude/commands/`
+ * without touching any existing customer file, then ensure `.claude/commands/` is
+ * added to the worktree's Git exclude. Returns a structured result; never throws
+ * for an expected filesystem/Git failure, and never leaks raw exception text,
+ * command output, or file contents.
+ */
+export async function provisionCommandsForWorktree(worktreeRoot, deps) {
+    const api = pathApiForCommandProvisioningPlatform(deps.platform);
+    const normalizedRoot = api.isAbsolute(worktreeRoot)
+        ? api.normalize(worktreeRoot)
+        : api.resolve(deps.cwd, worktreeRoot);
+    const commandsDir = api.join(normalizedRoot, ".claude", "commands");
+    const entries = Object.entries(COMMANDS);
+    if (entries.length === 0) {
+        // No runnable slash commands could ever be provisioned — fail loudly rather
+        // than reporting a hollow success.
+        return { ok: false, error: EMPTY_BUNDLE_ERROR };
+    }
+    // Phase 1 — discover which packaged files are absent. A successful read means
+    // the customer already owns that asset; leave it untouched. Only ENOENT counts
+    // as "missing"; any other read failure is a bounded, secret-free error.
+    let fillError = null;
+    const missing = [];
+    for (const [filename, content] of entries) {
+        const target = api.join(commandsDir, filename);
+        try {
+            await deps.readFile(target);
+        }
+        catch (err) {
+            if (isEnoentError(err)) {
+                missing.push([filename, content]);
+            }
+            else {
+                fillError = `Command provisioning failed: could not read existing command asset '${filename}'.`;
+                break;
+            }
+        }
+    }
+    // Phase 2 — create the directory (only when something is missing) and write the
+    // absent files in bundle order using the packaged string unchanged.
+    if (!fillError && missing.length > 0) {
+        try {
+            await deps.mkdir(commandsDir, { recursive: true });
+            for (const [filename, content] of missing) {
+                await deps.writeFile(api.join(commandsDir, filename), content);
+            }
+        }
+        catch {
+            fillError =
+                "Command provisioning failed: could not write one or more packaged command assets.";
+        }
+    }
+    // Phase 3 — ALWAYS attempt exclusion, even after a partial or failed fill, so
+    // partially bootstrapped files are never left visible to Git. The primary fill
+    // failure is preserved if both the fill and the exclusion fail.
+    let excludeError = null;
+    try {
+        await ensureGitInfoExcluded(normalizedRoot, COMMAND_DIR_EXCLUDE_ENTRY, {
+            readFile: deps.readFile,
+            writeFile: deps.writeFile,
+            mkdir: deps.mkdir,
+            runCommand: deps.runCommand,
+            platform: deps.platform,
+        });
+    }
+    catch {
+        excludeError =
+            "Command provisioning failed: could not add '.claude/commands/' to the worktree Git exclude file.";
+    }
+    if (fillError)
+        return { ok: false, error: fillError };
+    if (excludeError)
+        return { ok: false, error: excludeError };
+    return { ok: true };
+}
+/**
+ * Provision command assets for every eligible (`created`, path-bearing) row, in
+ * input order, serially. A non-`created` row or a `created` row without a usable
+ * path is returned unchanged. A per-worktree bootstrap failure marks ONLY that
+ * row `spawn-failed` (with a secret-free `Command provisioning failed: …` error)
+ * so the affected worker is skipped by all later spawn logic while its siblings
+ * proceed. A defensive per-row catch guarantees one unexpected failure cannot
+ * abort later rows or reject the overall call.
+ */
+export async function provisionCommandsForCreatedWorktrees(rows, deps) {
+    const out = [];
+    for (const row of rows) {
+        if (row.status !== "created" || !row.path) {
+            out.push(row);
+            continue;
+        }
+        try {
+            const result = await provisionCommandsForWorktree(row.path, deps);
+            if (result.ok) {
+                out.push(row);
+            }
+            else {
+                out.push({ ...row, status: "spawn-failed", error: result.error });
+            }
+        }
+        catch {
+            out.push({
+                ...row,
+                status: "spawn-failed",
+                error: "Command provisioning failed: an unexpected error occurred while bootstrapping worktree command assets.",
+            });
+        }
+    }
+    return out;
+}