@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/connect-bitbucket-api.js

@@ -87,6 +87,25 @@ function asString(value) {
 function asNullableString(value) {
     return typeof value === "string" && value.length > 0 ? value : null;
 }
+/** Same unambiguous alphabet the server draws its codes and check values from. */
+const APPROVAL_CHECK_RE = /^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{4,8}$/;
+/**
+ * Decide the mint's mode defensively (BAPI-1401). Approval mode needs BOTH an explicit
+ * `approval_mode: "approve"` and a well-formed check value; any other combination is
+ * code mode, so a partial or unexpected response can never strand the user without the
+ * code they would need.
+ */
+function parseApprovalMode(body) {
+    const check = typeof body.approval_check === "string" ? body.approval_check.trim() : "";
+    if (body.approval_mode === "approve" && APPROVAL_CHECK_RE.test(check)) {
+        return { approvalMode: "approve", approvalCheck: check };
+    }
+    return { approvalMode: "code", approvalCheck: null };
+}
+/** Parse the optional, additive `reason` on a status body. Unknown → null. */
+function parseStatusReason(value) {
+    return value === "declined" ? "declined" : null;
+}
 // ---------------------------------------------------------------------------
 // Retry-After
 // ---------------------------------------------------------------------------
@@ -121,13 +140,23 @@ export function parseRetryAfterMs(header, remainingMs, nowMs) {
 // ---------------------------------------------------------------------------
 // Endpoints
 // ---------------------------------------------------------------------------
-/** Mint a CLI-origin connection code and its Forge install-page URL. */
-export async function mintBitbucketConnection(deps, repoName) {
-    const res = await postJson(deps, "/setup/bitbucket/cli/connection-code", {
-        repo_name: repoName,
-    });
+/**
+ * Mint a CLI-origin connection code and its Forge install-page URL.
+ *
+ * BAPI-1401: when `workspaceSlug` is given, it is sent as the request's workspace claim,
+ * asking the server for an approval-mode connection request. Without it the request body
+ * is exactly the legacy shape. Either way the response decides the mode.
+ */
+export async function mintBitbucketConnection(deps, repoName, workspaceSlug) {
+    const payload = { repo_name: repoName };
+    if (workspaceSlug)
+        payload.workspace_slug = workspaceSlug;
+    const res = await postJson(deps, "/setup/bitbucket/cli/connection-code", payload);
     if (!res.ok)
         return res;
+    if (res.value.status === 429) {
+        return { ok: false, kind: "too-many-pending" };
+    }
     if (res.value.status !== 200) {
         return { ok: false, kind: classifyStatus(res.value.status) };
     }
@@ -143,7 +172,11 @@ export async function mintBitbucketConnection(deps, repoName) {
     // uses. Required-field strictness above is untouched — an optional field must not
     // become a new way for a server change to fail a mint.
     const redeemUrlTemplate = asNullableString(body.redeem_url_template);
-    return { ok: true, value: { state, installUrl, ttlSeconds, redeemUrlTemplate } };
+    const { approvalMode, approvalCheck } = parseApprovalMode(body);
+    return {
+        ok: true,
+        value: { state, installUrl, ttlSeconds, redeemUrlTemplate, approvalMode, approvalCheck },
+    };
 }
 /** Strictly parse candidates. A candidate missing a usable identity fails the whole list. */
 function parseCandidates(value) {
@@ -198,6 +231,7 @@ export async function fetchBitbucketConnectionStatus(deps, repoName, state, nowM
             status: status,
             candidates,
             repoDisplayName: asNullableString(body.repo_display_name),
+            reason: parseStatusReason(body.reason),
             // A single read has no deadline of its own to clamp against; the poller applies
             // its own bound. POLL_DEADLINE_MS is the widest a caller could honor.
             retryAfterMs: parseRetryAfterMs(res.value.retryAfter, POLL_DEADLINE_MS, nowMs),
@@ -348,6 +382,7 @@ export async function pollBitbucketConnection(deps, poll, repoName, state) {
                         status: typed,
                         candidates,
                         repoDisplayName: asNullableString(body.repo_display_name),
+                        reason: parseStatusReason(body.reason),
                         retryAfterMs: null,
                     },
                 };

package/build/connect-bitbucket.js

@@ -5,20 +5,28 @@
  * The whole point of this command is that it needs no Bridge web session: a user who has
  * a Bridge API key can connect Bitbucket without ever opening the setup UI. The flow is
  *
- *   mint → browser (install the Forge app on Bitbucket, paste the printed code into its
- *   admin panel) → poll → pick a repository → confirm
+ *   mint → browser (install the Forge app on Bitbucket, then approve the request on the
+ *   app's workspace settings page) → poll → pick a repository → confirm
  *
  * and the browser half authenticates to *Bitbucket*, not to Bridge. Bridge never asks
  * for, accepts, echoes, or transports a Bitbucket credential. The only thing crossing
  * between the browser and this process is a Bridge-issued state nonce, held in memory.
  *
+ * BAPI-1401 — two modes. **Approval mode** (the default when a Bitbucket workspace is
+ * known from `--workspace` or this project's git remote, and the server supports it):
+ * the mint is a connection request listed on that workspace's Forge settings page, and a
+ * workspace admin clicks Approve on the card showing the check value printed here. No
+ * code is printed. **Code mode** (`--use-code`, no workspace, or an older server): the
+ * legacy flow — the printed code is pasted into the same settings page.
+ *
  * Two properties are load-bearing and easy to erode:
  *
  * 1. **The nonce and install URL are never printed to output the CLI narrates around.**
  *    The URL carries the state as a query parameter, so putting it in a log line or an
  *    error message would paste a live credential-equivalent into the user's scrollback.
- *    The printed code shown to the user for pasting into Bitbucket's own admin panel is
- *    the one deliberate exception — see `runBitbucketConnectionFlow` below.
+ *    In code mode the printed code shown to the user for pasting into Bitbucket's own
+ *    settings page is the one deliberate exception — see `runBitbucketConnectionFlow`
+ *    below. In approval mode it is never printed.
  * 2. **Nothing binds without an explicit human choice.** Even a single-repository
  *    installation is confirmed by hand — the server stages candidates and this command
  *    asks. There is deliberately no `--yes`.
@@ -35,25 +43,30 @@ import { DEFAULT_BAPI_BASE_URL } from "./install-bridge.js";
 import { validateRepoName } from "./bridge-config.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { resolveBapiCredentials, } from "./credential-store.js";
+import { defaultGitRemoteRunner, resolveBitbucketWorkspace, } from "./bitbucket-workspace-remote.js";
 import { POLL_DEADLINE_MS, confirmBitbucketConnection, mintBitbucketConnection, pollBitbucketConnection, } from "./connect-bitbucket-api.js";
-const USAGE = `Usage: connect-bitbucket [--repo <repo_name>] [--workspace <slug>]
+const USAGE = `Usage: connect-bitbucket [--repo <repo_name>] [--workspace <slug>] [--use-code]
 
 Connect a Bitbucket repository to a Bridge project from your terminal.
 
-Opens the Bitbucket Forge app's install page in your browser and prints a
-connection code. Install the app, then redeem the code in Bitbucket under
-Workspace settings → Apps → "Connect Bitbucket to Bridge API" — that is how you
-authenticate to Bitbucket; Bridge never asks for a Bitbucket token or app
-password. Once the app reports the code back, this command asks which single
-repository to connect.
+Opens the Bitbucket Forge app's install page in your browser. Install the app,
+then in Bitbucket open Workspace settings → Forge Apps → "Connect Bitbucket to
+Bridge API" and click Approve on the request this command started (it prints a
+short check value so you can tell it apart). That is how you authenticate to
+Bitbucket; Bridge never asks for a Bitbucket token or app password. Once the
+app reports back, this command asks which single repository to connect.
+
+Without a known workspace, or with --use-code, it prints a connection code to
+paste on that same page instead.
 
 Options:
   --repo <repo_name>   Bridge project to connect (inferred from this directory
                        when omitted; you will be asked to confirm).
-  --workspace <slug>   Bitbucket workspace slug. Prints a direct link to that
-                       workspace's settings page for the app. The connection
-                       code still has to be pasted there by hand — the link only
-                       saves you finding the page.
+  --workspace <slug>   Bitbucket workspace slug. Inferred from this project's
+                       origin git remote when omitted. Lists the request on that
+                       workspace's settings page and prints a direct link to it.
+  --use-code           Print a connection code to paste instead of approving a
+                       request.
   --help               Show this message.`;
 /**
  * Bitbucket workspace slugs are NOT Bridge project names, so they do not go through
@@ -94,7 +107,7 @@ export function validateBitbucketWorkspace(raw) {
  * resolve only through the shared credential-store seam).
  */
 export function parseConnectBitbucketArgs(argv) {
-    const out = { help: false };
+    const out = { useCode: false, help: false };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--help" || arg === "-h") {
@@ -137,6 +150,10 @@ export function parseConnectBitbucketArgs(argv) {
             out.workspace = validated.value;
             continue;
         }
+        if (arg === "--use-code") {
+            out.useCode = true;
+            continue;
+        }
         if (arg === "--yes" || arg === "-y") {
             return {
                 ok: false,
@@ -255,6 +272,7 @@ export function createDefaultConnectBitbucketDeps() {
         openBrowser: (url) => defaultOpenBrowser(process.platform, url),
         stdout: (message) => process.stdout.write(`${message}\n`),
         stderr: (message) => process.stderr.write(`${message}\n`),
+        runGit: defaultGitRemoteRunner,
     };
 }
 /**
@@ -313,7 +331,7 @@ export async function openBitbucketInstallPage(deps, installUrl) {
 // ---------------------------------------------------------------------------
 const STEPS = [
     "Connect Bitbucket",
-    "Complete Bitbucket Forge install in browser",
+    "Install the Bitbucket Forge app and connect it in Bitbucket",
     "Verify connection",
     "Choose repository",
     "Confirm connection",
@@ -333,7 +351,7 @@ function renderStep(deps, index) {
  * must never leave the user with nothing. The words are the app's own Bitbucket
  * navigation, so they stay correct without any Bridge-side configuration at all.
  */
-export const BITBUCKET_REDEEM_NAVIGATION_PATH = 'Workspace settings → Apps → "Connect Bitbucket to Bridge API"';
+export const BITBUCKET_REDEEM_NAVIGATION_PATH = 'Workspace settings → Forge Apps → "Connect Bitbucket to Bridge API"';
 /** The one `{workspace}` token a redemption template may carry. */
 const WORKSPACE_TOKEN = "{workspace}";
 /**
@@ -431,6 +449,24 @@ function renderRedemptionGuidance(deps, template, workspace) {
         deps.stderr("  Replace {workspace} with your Bitbucket workspace slug.");
     }
 }
+/**
+ * Print what to do in approval mode (BAPI-1401): install, then Approve the request that
+ * shows this run's check value. The code is never printed. `firstRequest` is false on a
+ * renewal, where the browser is already open and only the new request's check changes.
+ */
+function renderApprovalGuidance(deps, repoName, approvalCheck, template, workspace, firstRequest) {
+    if (firstRequest) {
+        deps.stderr("Step 1: install the app in the browser window that just opened.");
+    }
+    else {
+        deps.stderr("A new request was created. The app install page is already open in your browser.");
+    }
+    deps.stderr(`Step 2: in Bitbucket, go to ${BITBUCKET_REDEEM_NAVIGATION_PATH} and click Approve on ` +
+        `the request for ${repoName} showing check ${approvalCheck}.`);
+    const link = renderBitbucketRedeemLink(template, workspace);
+    if (link)
+        deps.stderr(`  Direct link: ${link}`);
+}
 /** Display identity for a candidate: prefer the unambiguous workspace/repo slug form. */
 function candidateLabel(c) {
     const slugForm = `${c.workspace_slug}/${c.repository_slug}`;
@@ -443,6 +479,8 @@ function candidateLabel(c) {
 const OUTCOME_MESSAGES = {
     expired: "The connection request expired before the Forge app reported back. Run connect-bitbucket again.",
     invalid: "This connection request is no longer valid. Run connect-bitbucket again.",
+    // BAPI-1401: an `invalid` status that carries reason "declined".
+    declined: "The connection request was declined in Bitbucket. Run connect-bitbucket again to start a new request.",
     "no-repositories": "The Bitbucket Forge app installation did not include any repositories Bridge can " +
         "access. Re-run connect-bitbucket and grant access to at least one repository.",
 };
@@ -453,9 +491,13 @@ const FAILURE_MESSAGES = {
     "not-found": "Bridge does not recognize this project. Check --repo matches your Bridge project name.",
     server: "Bridge API returned an error. Run connect-bitbucket again shortly.",
     malformed: "Bridge API returned an unexpected response. Run connect-bitbucket again shortly.",
-    deadline: "Timed out waiting for the Bitbucket Forge app. If you completed the install and pasted " +
-        "the code, run connect-bitbucket again to pick up the connection.",
+    deadline: "Timed out waiting for the Bitbucket Forge app. If you installed the app and approved " +
+        "the request (or pasted the code), run connect-bitbucket again to pick up the connection.",
+    "too-many-pending": "Too many Bitbucket connection requests are waiting. Approve or decline them in " +
+        "Bitbucket, or wait up to 15 minutes for them to expire, then run connect-bitbucket again.",
 };
+/** BAPI-1401: offered after the first approval-mode expiry or deadline. */
+const USE_CODE_FALLBACK_HINT = "Can't see the request? Re-run with --use-code";
 /** Only an explicit, case-insensitive `y`/`yes` approves. One definition, used everywhere. */
 function isAffirmative(answer) {
     const normalized = answer.trim().toLowerCase();
@@ -548,7 +590,7 @@ async function chooseCandidate(deps, candidates) {
  * a renewal can never confirm against a previous code.
  */
 export async function runBitbucketConnectionFlow(deps, api, repoName, options = {}) {
-    const { workspace, initialMintApproved = false } = options;
+    const { workspace, useCode = false, initialMintApproved = false } = options;
     renderStep(deps, 0);
     if (!initialMintApproved) {
         // A standalone run asks before it mints: minting is a side effect (a live code, a
@@ -559,8 +601,11 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
     }
     let browserOpened = false;
     let expiryCount = 0;
+    let useCodeHintShown = false;
     for (;;) {
-        const minted = await mintBitbucketConnection(api, repoName);
+        // BAPI-1401: the workspace is sent as an approval-mode claim unless the user asked
+        // for the code flow. The server's response, not this request, decides the mode.
+        const minted = await mintBitbucketConnection(api, repoName, useCode ? undefined : workspace);
         if (!minted.ok) {
             // Includes a renewal mint: a failed fresh mint is terminal and resumable, never
             // silently retried. An automatic retry here would spend codes the user cannot see.
@@ -568,6 +613,13 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
         }
         // Iteration-local. Nothing outside this block may read a previous code.
         const connection = minted.value;
+        // Approval mode needs a workspace to have been claimed; a server that answers
+        // "approve" to a claimless mint is treated as code mode rather than trusted.
+        const approval = connection.approvalMode === "approve" &&
+            connection.approvalCheck !== null &&
+            !useCode &&
+            workspace !== undefined;
+        const firstRequest = !browserOpened;
         if (!browserOpened) {
             renderStep(deps, 1);
             deps.stderr("Opening Bitbucket…");
@@ -581,13 +633,20 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
             // both noise and a stale destination.
             browserOpened = true;
         }
-        renderRedemptionGuidance(deps, connection.redeemUrlTemplate, workspace);
-        // The code itself is not a bearer credential the way the URL's state parameter is
-        // treated elsewhere in this flow — it must be visible so the user can paste it into
-        // the installed Forge app's admin panel, which is how redemption actually happens for
-        // a Forge app (there is no GitHub-style browser redirect back to Bridge). This is
-        // the single statement in the command that prints a code, and it runs once per mint.
-        deps.stderr(`Paste this code there: ${connection.state}`);
+        if (approval) {
+            // BAPI-1401: nothing to paste. `connection.state` stays in memory, used only for
+            // polling and confirmation below.
+            renderApprovalGuidance(deps, repoName, connection.approvalCheck, connection.redeemUrlTemplate, workspace, firstRequest);
+        }
+        else {
+            renderRedemptionGuidance(deps, connection.redeemUrlTemplate, workspace);
+            // The code itself is not a bearer credential the way the URL's state parameter is
+            // treated elsewhere in this flow — it must be visible so the user can paste it into
+            // the installed Forge app's settings page, which is how redemption happens in code
+            // mode (there is no GitHub-style browser redirect back to Bridge). This is the
+            // single statement in the command that prints a code, and it runs once per mint.
+            deps.stderr(`Paste this code there: ${connection.state}`);
+        }
         renderStep(deps, 2);
         const minutes = Math.floor(POLL_DEADLINE_MS / 60_000);
         deps.stderr(`Waiting for the Bitbucket Forge app… (up to ~${minutes} minutes)`);
@@ -599,14 +658,23 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
         if (renewable) {
             expiryCount += 1;
             deps.stderr("");
-            deps.stderr("That code expired and can no longer be used.");
+            deps.stderr(approval
+                ? "That request expired and can no longer be approved."
+                : "That code expired and can no longer be used.");
+            if (approval && !useCodeHintShown) {
+                deps.stderr(USE_CODE_FALLBACK_HINT);
+                useCodeHintShown = true;
+            }
             if (expiryCount > 1) {
                 // Said only after it has happened more than once — by then the likely cause is
                 // not slowness but a wrong page or an app that was never installed.
                 deps.stderr("If this keeps happening, check that the Forge app is installed and that you " +
                     "have the right workspace's settings page open.");
             }
-            if (await confirm(deps, "Issue a fresh code and keep waiting? [y/N]: ")) {
+            const renewQuestion = approval
+                ? "Create a fresh request and keep waiting? [y/N]: "
+                : "Issue a fresh code and keep waiting? [y/N]: ";
+            if (await confirm(deps, renewQuestion)) {
                 continue;
             }
             return reportNoConnection(deps, polled.ok ? OUTCOME_MESSAGES.expired : FAILURE_MESSAGES.deadline, repoName, "incomplete");
@@ -624,7 +692,8 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
             return { kind: "connected", displayName };
         }
         if (result.status !== "staged") {
-            return reportNoConnection(deps, OUTCOME_MESSAGES[result.status] ?? OUTCOME_MESSAGES.invalid, repoName);
+            const outcomeKey = result.status === "invalid" && result.reason === "declined" ? "declined" : result.status;
+            return reportNoConnection(deps, OUTCOME_MESSAGES[outcomeKey] ?? OUTCOME_MESSAGES.invalid, repoName);
         }
         const candidates = result.candidates;
         if (candidates.length === 0) {
@@ -729,8 +798,12 @@ export async function runConnectBitbucketCli(argv, injected) {
             baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
             apiKey: cred.credentials.apiKey,
         };
+        // BAPI-1401: explicit --workspace, else the origin remote. Inferred even with
+        // --use-code, where it still resolves the printed settings-page link.
+        const workspace = await resolveBitbucketWorkspace(parsed.value.workspace, deps.cwd, deps.runGit, deps.stderr);
         const result = await runBitbucketConnectionFlow(deps, api, repo.value, {
-            workspace: parsed.value.workspace,
+            workspace,
+            useCode: parsed.value.useCode,
             // Standalone: nobody has asked yet, so the flow owns the initial confirmation.
             initialMintApproved: false,
         });

package/build/connect-github-api.js

@@ -331,15 +331,21 @@ export async function revokeGithubHandoff(deps, repoName, state) {
     }
     return { ok: true, value: status };
 }
+/** A server-supplied ticket prefix is a short alphanumeric key, never free text. */
+const TICKET_PREFIX_SHAPE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
+function parseTicketPrefix(body) {
+    const raw = asRecord(body)?.ticket_prefix;
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return TICKET_PREFIX_SHAPE.test(trimmed) ? trimmed : undefined;
+}
 /**
- * Read whether GitHub is already configured for a project.
- *
- * Uses the existing authenticated install-manifest/capability surface — read-only, and
- * unrelated to any in-flight connection attempt. `unavailable` is a real answer and is
- * deliberately distinct from `unconfigured`: callers must be able to skip rather than
- * fabricate "not configured" from a probe that simply failed.
+ * Read the install manifest once and report GitHub's configured state and the
+ * optional ticket prefix. Same request, same deadline, and same GitHub parsing as
+ * {@link fetchGithubConfigurationState}, which delegates here.
  */
-export async function fetchGithubConfigurationState(deps, repoName) {
+export async function fetchGithubConfigurationDetails(deps, repoName) {
     let resp;
     try {
         resp = await deps.fetch(`${deps.baseUrl}/jira/config/install-manifest?repo_name=${encodeURIComponent(repoName)}`, {
@@ -348,31 +354,44 @@ export async function fetchGithubConfigurationState(deps, repoName) {
         });
     }
     catch {
-        return "unavailable";
+        return { state: "unavailable" };
     }
     if (resp.status !== 200)
-        return "unavailable";
+        return { state: "unavailable" };
     let body;
     try {
         body = await resp.json();
     }
     catch {
-        return "unavailable";
+        return { state: "unavailable" };
     }
+    const ticketPrefix = parseTicketPrefix(body);
+    const withPrefix = (state) => ticketPrefix === undefined ? { state } : { state, ticketPrefix };
     const integrations = asRecord(body)?.integrations;
     if (!Array.isArray(integrations))
-        return "unavailable";
+        return withPrefix("unavailable");
     for (const raw of integrations) {
         const rec = asRecord(raw);
         if (rec?.id !== "github_app")
             continue;
         if (typeof rec.is_configured !== "boolean")
-            return "unavailable";
-        return rec.is_configured ? "configured" : "unconfigured";
+            return withPrefix("unavailable");
+        return withPrefix(rec.is_configured ? "configured" : "unconfigured");
     }
     // The checklist is provider-scoped: GitHub is legitimately absent for a Bitbucket
     // project. Absent is not "unconfigured" — there is nothing here to connect.
-    return "unavailable";
+    return withPrefix("unavailable");
+}
+/**
+ * Read whether GitHub is already configured for a project.
+ *
+ * Uses the existing authenticated install-manifest/capability surface — read-only, and
+ * unrelated to any in-flight connection attempt. `unavailable` is a real answer and is
+ * deliberately distinct from `unconfigured`: callers must be able to skip rather than
+ * fabricate "not configured" from a probe that simply failed.
+ */
+export async function fetchGithubConfigurationState(deps, repoName) {
+    return (await fetchGithubConfigurationDetails(deps, repoName)).state;
 }
 /**
  * Slightly longer than the server's 15-minute code TTL, so an expiry is reported by the