@bridge_gpt/mcp-server 0.2.28 → 0.2.29

package/build/install-bridge.js

@@ -57,10 +57,23 @@
  * repository prompt asks for a new project name rather than an existing
  * registration (see `RepoNamePromptMode`).
  *
- * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the two exceptions to "this command
- * consumes a key, it does not create one". With `--invite` (or `BAPI_INVITE`) there is no
- * API key yet, so the pre-flight ping of Step 2 CANNOT be made: the exchange is
- * what mints the key, and it REPLACES that ping. The order becomes:
+ * ORDINARY-ENTRY INVITE RECLASSIFICATION (BAPI-661) — the have-key branch's own
+ * credential input (`--api-key`, `BAPI_API_KEY`, or its hidden prompt) is
+ * CREDENTIAL-AGNOSTIC: it accepts a full API key OR a bootstrap-invite token,
+ * because a user handed only an invite has no way to know it belongs in a
+ * different flag. `classifyEnteredCredential` inspects the resolved value
+ * immediately after input resolution (before repository-name resolution); a
+ * `bapi_inv_…` value flips the branch's `bootstrapInviteMode`/`inviteToken` and
+ * the run falls into the SAME bootstrap-invite protocol described below, verbatim.
+ * Explicit `--invite`/`BAPI_INVITE` and `--email`/`BAPI_SIGNUP_EMAIL` are never
+ * reclassified — they are already unambiguous and remain authoritative.
+ *
+ * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the exceptions to "this command
+ * consumes a key, it does not create one" (the ordinary-entry reclassification
+ * above is the other). With `--invite` (or `BAPI_INVITE`, or a reclassified
+ * ordinary-entry value) there is no API key yet, so the pre-flight ping of Step 2
+ * CANNOT be made: the exchange is what mints the key, and it REPLACES that ping.
+ * The order becomes:
  *
  *   resolve bootstrap-invite token (no-echo prompt by DEFAULT — the delivered
  *   one-liner is secret-free) → resolve repo name → scaffold → generate
@@ -185,11 +198,15 @@ export function getInstallBridgeUsage() {
         "an interactive terminal keeps the existing deterministic behavior and no prompt.",
         "",
         "Inputs (the only two irreducible ones):",
-        "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
-        "                    then an interactive (no-echo) prompt. Generate one in the",
-        "                    Bridge API web UI Security page — this command consumes a",
-        "                    key, it does not create one (--email and --invite are the",
-        "                    exceptions: they CREATE the project and its first admin key).",
+        "  --api-key <key>   Bridge API key OR bootstrap invite. Falls back to the",
+        "                    BAPI_API_KEY env var, then an interactive (no-echo) prompt.",
+        "                    Generate a key in the Bridge API web UI Security page — this",
+        "                    command consumes a key, it does not create one. A value",
+        "                    detected as a bootstrap invite (bapi_inv_…), from any of the",
+        "                    three sources above, is instead redeemed to CREATE a new",
+        "                    project and its first admin key — the same as --invite —",
+        "                    so it skips repository lookup entirely (--email and --invite",
+        "                    remain the explicit, preferred entry points for a new project).",
         "                    NEVER printed or logged.",
         "  --repo <name>     Repository name. --repo and BAPI_REPO_NAME still take",
         "                    priority and short-circuit before any network call. When",
@@ -710,8 +727,16 @@ export function createDefaultInstallBridgeDeps() {
     };
 }
 /**
- * Resolve the API key: `--api-key` → `BAPI_API_KEY` env → interactive no-echo
- * prompt. Fails (secret-free) when none is available and stdin is non-interactive.
+ * Resolve the ordinary credential entry: `--api-key` → `BAPI_API_KEY` env →
+ * interactive no-echo prompt. Fails (secret-free) when none is available and
+ * stdin is non-interactive.
+ *
+ * Despite the name, this is CREDENTIAL-AGNOSTIC (BAPI-661): the returned value may
+ * be a full Bridge API key or a bootstrap-invite token (`bapi_inv_…`) — the caller
+ * classifies it with {@link classifyEnteredCredential} immediately after this
+ * resolves and routes an invite into the existing redemption workflow. This
+ * function itself performs no classification; it only resolves which raw string
+ * was entered.
  */
 export async function resolveApiKey(options, deps) {
     if (typeof options.apiKey === "string" && options.apiKey.trim().length > 0) {
@@ -722,16 +747,20 @@ export async function resolveApiKey(options, deps) {
         return { ok: true, value: fromEnv.trim() };
     }
     if (deps.isTTY && deps.promptSecret) {
-        const entered = (await deps.promptSecret("Bridge API key (input hidden): ")).trim();
+        const entered = (await deps.promptSecret("Bridge API key or invite (input hidden): ")).trim();
         if (entered.length > 0) {
             return { ok: true, value: entered };
         }
-        return { ok: false, error: "No API key entered." };
+        return {
+            ok: false,
+            error: "No Bridge API key or invite entered. Pass --api-key, set the BAPI_API_KEY environment " +
+                "variable, or try the hidden prompt again.",
+        };
     }
     return {
         ok: false,
-        error: "An API key is required. Pass --api-key or set the BAPI_API_KEY environment variable " +
-            "(no interactive terminal is available to prompt for it).",
+        error: "A Bridge API key or invite is required. Pass --api-key or set the BAPI_API_KEY " +
+            "environment variable (no interactive terminal is available to prompt for it).",
     };
 }
 /**
@@ -836,8 +865,8 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
         return { kind: "need-key", method: "self-serve" };
     return { kind: "have-key" };
 }
-/** The exact visible text of the bare-TTY onboarding selector (BAPI-626). */
-export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key? [Y/n] ";
+/** The exact visible text of the bare-TTY onboarding selector (BAPI-626, BAPI-661). */
+export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key or invite? [Y/n] ";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
  *
@@ -1000,7 +1029,8 @@ export function promptMultiSelectViaReadline(promptText, options, defaults, inpu
                 const mark = selected.has(opt.id) ? "[x]" : "[ ]";
                 output.write(`  ${idx + 1}. ${mark} ${opt.label}\n`);
             });
-            output.write("Type numbers to toggle, e.g. 1,3 — then Enter. Enter with ≥1 selected accepts.\n");
+            output.write("Type numbers to toggle, e.g. 1,3 — then Enter.\n");
+            output.write("Press Enter on an empty line to confirm — re-typing a number un-selects it.\n");
             output.write("Enter numbers to toggle (comma-separated), or press Enter to accept: ");
         };
         const rl = readline.createInterface({ input, output });
@@ -1195,20 +1225,41 @@ export async function chooseInstallBridgeLaunchAgent(agents, deps) {
  *    completes.
  *
  * Condition-specific warning prefixes are added by the caller, never inside here.
+ *
+ * `toolLabels` (BAPI-661) names the actually-selected platform(s) in the
+ * `"configured"` message so "open it in an AI coding tool" becomes "open it in
+ * GitHub Copilot (VS Code)" when that is what was selected — an empty array (the
+ * explicit empty-selection call site, or any caller with nothing to name) falls
+ * back to the prior generic "an AI coding tool" wording unchanged.
  */
-export function buildManualInstallBridgeContinuation(kind) {
+export function buildManualInstallBridgeContinuation(kind, toolLabels) {
     if (kind === "empty-selection") {
         return [
             "No AI coding tools were configured, so nothing was set up for this project.",
             "Re-run install-bridge and select at least one tool to configure it.",
         ].join("\n");
     }
+    const toolPhrase = formatToolLabelPhrase(toolLabels);
     return [
-        "To finish configuring this project, open it in an AI coding tool that has the",
+        `To finish configuring this project, open it in ${toolPhrase} that has the`,
         "Bridge MCP server configured and run /install-bridge.",
         "Until the project is configured, your Bridge MCP tools stay limited.",
     ].join("\n");
 }
+/**
+ * Format 0, 1, or many tool labels into a readable phrase for the continuation
+ * message. Empty falls back to the generic "an AI coding tool"; one label is used
+ * bare; two or more join with a serial (Oxford) comma and "and".
+ */
+function formatToolLabelPhrase(labels) {
+    if (labels.length === 0)
+        return "an AI coding tool";
+    if (labels.length === 1)
+        return labels[0];
+    if (labels.length === 2)
+        return `${labels[0]} and ${labels[1]}`;
+    return `${labels.slice(0, -1).join(", ")}, and ${labels[labels.length - 1]}`;
+}
 /** The exact consent-prompt prefix, shared with tests so the copy cannot drift. */
 export const INSTALL_BRIDGE_LAUNCH_CONSENT_PROMPT_PREFIX = "Bridge can configure and set up this project for you automatically. Open a ";
 /**
@@ -1287,6 +1338,17 @@ function hostConfigTargetsForPlatforms(platforms) {
         .filter((t) => t.scope === "project" && t.format === "json")
         .map((t) => ({ relPath: t.relPath, topLevelKey: t.topLevelKey }));
 }
+/**
+ * Derive the human-facing labels for a set of selected platforms, in registry
+ * (`HOST_PLATFORM_ORDER`) order rather than the caller's input order, so a
+ * continuation message names selected tools deterministically (BAPI-661).
+ * Deduplicates by platform ID and reads every label from `MCP_HOST_TARGETS` —
+ * never a second, hand-maintained label map.
+ */
+export function labelsForPlatforms(platforms) {
+    const set = new Set(platforms);
+    return HOST_PLATFORM_ORDER.filter((id) => set.has(id)).map((id) => MCP_HOST_TARGETS[id].label);
+}
 /** Resolve which project-local host configs to write, mirroring runInit detection. */
 async function resolveHostConfigTargets(deps) {
     const targets = [
@@ -1447,9 +1509,19 @@ export function buildPingUrl(baseUrl, repoName) {
     return url.toString();
 }
 /**
- * Verify connectivity. Distinguishes a rejected key (401/403) from an unknown
- * repo / not-found (404) where the response allows. The key is sent in the
- * `X-API-Key` header and NEVER appears in any returned message.
+ * Fixed, secret-free fallback for an HTTP 403 whose body carries no usable
+ * `detail` (absent, malformed, unreadable, or a non-string `detail`). Deliberately
+ * does NOT claim the key is invalid or expired — a 403 means the credential was
+ * understood but denied access, which is a different (and often more actionable)
+ * failure than an invalid/expired key.
+ */
+const CONNECTIVITY_ACCESS_DENIED_FALLBACK = "The Bridge API denied access to this repository (HTTP 403). Verify the repo_name and that this " +
+    "credential is authorized for it.";
+/**
+ * Verify connectivity. Distinguishes a rejected/expired credential (401) from a
+ * repository-specific access denial (403, BAPI-661) from an unknown repo /
+ * not-found (404) where the response allows. The key is sent in the `X-API-Key`
+ * header and NEVER appears in any returned message.
  */
 export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
     const url = buildPingUrl(baseUrl, repoName);
@@ -1474,7 +1546,7 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
     }
     if (resp.ok)
         return { ok: true };
-    if (resp.status === 401 || resp.status === 403) {
+    if (resp.status === 401) {
         return {
             ok: false,
             message: `The Bridge API rejected the credential (HTTP ${resp.status}). The API key may be invalid or expired ` +
@@ -1482,6 +1554,27 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
                 "permission error.)",
         };
     }
+    if (resp.status === 403) {
+        // BAPI-661: a 403 means the credential was understood but access to THIS repo
+        // was denied — the server's `detail` (e.g. "repository '<name>' is not
+        // registered; verify the repo_name") is a safe, specific, non-secret message
+        // that is far more actionable than the blanket invalid-key diagnosis 401 uses.
+        // Only a nonblank string `detail` is ever surfaced; any other shape (missing
+        // body, invalid JSON, a non-string/blank detail, or a body-read exception)
+        // collapses to the fixed fallback so nothing unvalidated ever reaches the user.
+        let detail;
+        try {
+            const body = (await resp.json());
+            detail = body?.detail;
+        }
+        catch {
+            return { ok: false, message: CONNECTIVITY_ACCESS_DENIED_FALLBACK };
+        }
+        if (typeof detail === "string" && detail.trim().length > 0) {
+            return { ok: false, message: detail.trim() };
+        }
+        return { ok: false, message: CONNECTIVITY_ACCESS_DENIED_FALLBACK };
+    }
     if (resp.status === 404) {
         return {
             ok: false,
@@ -1651,6 +1744,21 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
  * treated as a `failed` mint rather than fed into the redemption path.
  */
 export const BOOTSTRAP_INVITE_TOKEN_PREFIX = "bapi_inv_";
+/**
+ * Classify a value entered through the ORDINARY credential input (`--api-key`,
+ * `BAPI_API_KEY`, or the have-key hidden prompt) as a bootstrap-invite token or a
+ * full API key (BAPI-661). This lets a user who was handed an invite but reaches
+ * for the ordinary key input still get redeemed correctly, instead of the invite
+ * being sent as an (invalid) API key to repository resolution / connectivity.
+ *
+ * Pure and total: trims first, then does a case-sensitive prefix check against
+ * {@link BOOTSTRAP_INVITE_TOKEN_PREFIX}. Blank and every non-matching value is
+ * `"api-key"` — the existing resolvers already reject a blank value, so this
+ * function does not need to special-case it. Never logs or returns the value.
+ */
+export function classifyEnteredCredential(value) {
+    return value.trim().startsWith(BOOTSTRAP_INVITE_TOKEN_PREFIX) ? "invite" : "api-key";
+}
 /** The self-serve mint endpoint: `<base>/setup/bootstrap/self-serve`. No query string — ever. */
 export function buildSelfServeMintUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve`;
@@ -1996,8 +2104,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const branch = branchResult.branch;
-    const bootstrapInviteMode = branch.kind === "need-key";
-    const selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
+    // Mutable (BAPI-661): an ordinary have-key credential that classifies as a
+    // bootstrap invite (see the have-key arm below) flips `bootstrapInviteMode` to
+    // true AFTER branch selection, before repository-name resolution — everything
+    // downstream that branches on these two flags then follows the existing
+    // bootstrap-invite protocol automatically. Explicit `--invite`/`BAPI_INVITE` and
+    // `--email`/`BAPI_SIGNUP_EMAIL` never pass through this reclassification.
+    let bootstrapInviteMode = branch.kind === "need-key";
+    let selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
     // ---- Resolve inputs (may prompt when interactive) ----
     // Resolve the credential/entry input first so a fully-empty non-interactive
     // invocation fails with the (more relevant) missing-input message before the repo
@@ -2030,7 +2144,20 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             errorLog(`Error: ${keyResult.error}`);
             return 1;
         }
-        apiKey = keyResult.value;
+        // BAPI-661: an invite pasted into the ordinary credential input (flag, env, or
+        // hidden prompt) is redeemed like an explicit --invite, not sent as an API key
+        // to repository resolution / connectivity. Reclassifying BEFORE that
+        // resolution is what lets the rest of the function reuse the existing
+        // bootstrap-invite protocol verbatim.
+        if (classifyEnteredCredential(keyResult.value) === "invite") {
+            inviteToken = keyResult.value.trim();
+            apiKey = "";
+            bootstrapInviteMode = true;
+            selfServeSignupMode = false;
+        }
+        else {
+            apiKey = keyResult.value;
+        }
     }
     // baseUrl is resolved BEFORE repository input because the have-key branch needs
     // it for the server-resolution request.
@@ -2077,7 +2204,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             else {
                 // Feature-detect + degrade: 404 (old server), 409 (unresolved/ambiguous/
                 // client-scoped), and network/other errors all fall back to the existing
-                // local resolution WITHOUT a cause-specific message or leaked detail.
+                // local resolution — WITHOUT a cause-specific message or leaked detail, but
+                // (BAPI-661) WITH a visible signal that the fallback is happening, so a
+                // guessed name is never confirmed silently as if it had been verified.
+                log("Couldn't auto-resolve your repo from the key; falling back to a guessed name — confirm " +
+                    "it matches the setup UI.");
                 const repoResult = await resolveRepoName(options, deps, "existing-registration");
                 if (!repoResult.ok) {
                     errorLog(`Error: ${repoResult.error}`);
@@ -2159,7 +2290,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // Return BEFORE any config/credential write, materialization, prewarm, or spawn, so a
     // bare `--tools=` (or an EOF-resolved picker) cleanly does nothing but guide a re-run.
     if (planLaunch.kind === "manual" && planLaunch.reason === "empty-selection") {
-        log(buildManualInstallBridgeContinuation("empty-selection"));
+        // Explicit empty selection: no labels to name, so the generic fallback is
+        // intentional here — pass [] rather than `labelsForPlatforms(selectedPlatforms)`.
+        log(buildManualInstallBridgeContinuation("empty-selection", []));
         return 0;
     }
     // ---- Finalize the launch agent for spawn-capable decisions ----
@@ -2609,7 +2742,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 // deterministic setup is complete, so this is a non-fatal warning (exit 0), with
                 // the same shared continuation so the remediation is consistent.
                 errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}).`);
-                log(buildManualInstallBridgeContinuation("configured"));
+                log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
                 return 0;
             }
             log("");
@@ -2623,13 +2756,13 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             return 0;
         }
         // Declined (or non-TTY suppression): the deterministic setup is complete and durable.
-        log(buildManualInstallBridgeContinuation("configured"));
+        log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
         return 0;
     }
     // No launchable session (a no-launchable selection, or a non-TTY / declined chooser):
     // finalAgentName is null, so nothing was materialized. The configured hosts are
     // durable — print the shared continuation + limited-tools note (never the
     // empty-selection variant, which already returned above).
-    log(buildManualInstallBridgeContinuation("configured"));
+    log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
     return 0;
 }