@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/connect-bitbucket-api.js

@@ -138,7 +138,12 @@ export async function mintBitbucketConnection(deps, repoName) {
     if (!body || !state || !installUrl || typeof ttlSeconds !== "number") {
         return { ok: false, kind: "malformed" };
     }
-    return { ok: true, value: { state, installUrl, ttlSeconds } };
+    // Optional and permissive ON PURPOSE, and only here: absent, null, empty, or any
+    // non-string collapses to null through the same nullable helper the candidate parser
+    // 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 } };
 }
 /** Strictly parse candidates. A candidate missing a usable identity fails the whole list. */
 function parseCandidates(value) {

package/build/connect-bitbucket.js

@@ -36,20 +36,56 @@ import { validateRepoName } from "./bridge-config.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { resolveBapiCredentials, } from "./credential-store.js";
 import { POLL_DEADLINE_MS, confirmBitbucketConnection, mintBitbucketConnection, pollBitbucketConnection, } from "./connect-bitbucket-api.js";
-const USAGE = `Usage: connect-bitbucket [--repo <repo_name>]
+const USAGE = `Usage: connect-bitbucket [--repo <repo_name>] [--workspace <slug>]
 
 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 paste the printed code into its admin
-panel — 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.
+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.
 
 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.
   --help               Show this message.`;
+/**
+ * Bitbucket workspace slugs are NOT Bridge project names, so they do not go through
+ * `validateRepoName`. This mirrors the server's own workspace-slug allowlist: an
+ * alphanumeric first and last character, with dots, underscores, and hyphens allowed in
+ * between, capped at 255 characters.
+ *
+ * The allowlist is what makes substitution safe. A slug that cannot contain `/`, `?`,
+ * `#`, `%`, a space, or a control character cannot reinterpret the template's path
+ * structure once it is substituted — and `encodeURIComponent` at the substitution site
+ * is the second, independent guarantee of the same property.
+ */
+const BITBUCKET_WORKSPACE_SLUG_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+const BITBUCKET_WORKSPACE_SLUG_MAX_LENGTH = 255;
+const WORKSPACE_VALUE_ERROR = "--workspace requires a Bitbucket workspace slug (letters, digits, '.', '_', '-'; " +
+    "e.g. --workspace acme-dev).";
+/** Validate a Bitbucket workspace slug. Never mutates the value beyond trimming. */
+export function validateBitbucketWorkspace(raw) {
+    const value = raw.trim();
+    if (!value)
+        return { ok: false, error: WORKSPACE_VALUE_ERROR };
+    if (value.length > BITBUCKET_WORKSPACE_SLUG_MAX_LENGTH) {
+        return {
+            ok: false,
+            error: `--workspace must be at most ${BITBUCKET_WORKSPACE_SLUG_MAX_LENGTH} characters.`,
+        };
+    }
+    if (!BITBUCKET_WORKSPACE_SLUG_RE.test(value)) {
+        return { ok: false, error: WORKSPACE_VALUE_ERROR };
+    }
+    return { ok: true, value };
+}
 /**
  * Parse argv. Deliberately strict — an unknown flag is an error, not something to
  * ignore. In particular there is NO `--yes` (every bind is confirmed by a human), no
@@ -82,6 +118,25 @@ export function parseConnectBitbucketArgs(argv) {
             out.repo = value;
             continue;
         }
+        if (arg === "--workspace") {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("-")) {
+                return { ok: false, error: WORKSPACE_VALUE_ERROR };
+            }
+            const validated = validateBitbucketWorkspace(value);
+            if (!validated.ok)
+                return { ok: false, error: validated.error };
+            out.workspace = validated.value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--workspace=")) {
+            const validated = validateBitbucketWorkspace(arg.slice("--workspace=".length));
+            if (!validated.ok)
+                return { ok: false, error: validated.error };
+            out.workspace = validated.value;
+            continue;
+        }
         if (arg === "--yes" || arg === "-y") {
             return {
                 ok: false,
@@ -111,22 +166,43 @@ export function parseConnectBitbucketArgs(argv) {
     return { ok: true, value: out };
 }
 /** Echoed single-line prompt on stderr. */
-function defaultPromptLine(promptText) {
+export function defaultPromptLine(promptText) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
         // `rl.close()` emits `close` SYNCHRONOUSLY, so without this guard the close handler
         // would settle the promise empty and discard a real answer. EOF must also resolve
         // rather than deadlock a top-level await.
         let answered = false;
-        rl.on("close", () => {
-            if (!answered)
-                resolve("");
-        });
-        rl.question(promptText, (answer) => {
+        const settleEmpty = () => {
+            if (answered)
+                return;
             answered = true;
+            resolve("");
+        };
+        rl.on("close", settleEmpty);
+        // BAPI-1247: an interrupted prompt (Ctrl-C, a closed input) is a DECLINE, not a
+        // crash. Resolving empty routes it through the ordinary "user said no" path, so the
+        // flow prints its resume guidance instead of surfacing a stack trace that could
+        // carry the install URL.
+        rl.on("SIGINT", () => {
             rl.close();
-            resolve(answer.trim());
+            settleEmpty();
         });
+        rl.on("error", () => {
+            rl.close();
+            settleEmpty();
+        });
+        try {
+            rl.question(promptText, (answer) => {
+                answered = true;
+                rl.close();
+                resolve(answer.trim());
+            });
+        }
+        catch {
+            rl.close();
+            settleEmpty();
+        }
     });
 }
 /**
@@ -245,6 +321,116 @@ const STEPS = [
 function renderStep(deps, index) {
     deps.stderr(`[${index + 1}/${STEPS.length}] ${STEPS[index]}`);
 }
+// ---------------------------------------------------------------------------
+// Redemption guidance (BAPI-1247)
+// ---------------------------------------------------------------------------
+/**
+ * The permanent, deployment-independent way to reach the redemption page. Printed for
+ * EVERY minted code, with or without a link.
+ *
+ * This is the fallback that makes the whole feature safe to configure wrong: a link is
+ * a shortcut, and a shortcut that is missing, stale, or pointed at the wrong deployment
+ * 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"';
+/** The one `{workspace}` token a redemption template may carry. */
+const WORKSPACE_TOKEN = "{workspace}";
+/**
+ * Resolve a server template into a printable link for *workspace*.
+ *
+ * Returns null — silently — for any template this client will not vouch for. The server
+ * validates too, but this is guidance the CLI is about to print as a destination, and
+ * re-checking here means a server change, a proxy rewrite, or an older/newer server can
+ * never talk this command into printing a link it did not verify itself.
+ *
+ * `encodeURIComponent` is applied to a slug that already passed
+ * {@link validateBitbucketWorkspace}, so the substituted value cannot introduce a path
+ * segment, query, or fragment of its own.
+ */
+export function renderBitbucketRedeemLink(template, workspace) {
+    if (typeof template !== "string")
+        return null;
+    const trimmed = template.trim();
+    if (!trimmed)
+        return null;
+    // Control characters, rejected BEFORE parsing — the fourth of the server's four rules,
+    // and the only one `new URL()` cannot stand in for: it strips tab/LF/CR outright and
+    // percent-encodes the rest of the C0 set in the path, so a template carrying terminal
+    // escape bytes parses cleanly and yields a link. That matters because the no-workspace
+    // branch of `renderRedemptionGuidance` prints the template VERBATIM rather than the
+    // normalized URL, so without this the raw escapes would reach stderr.
+    if (/[\u0000-\u001F\u007F]/.test(trimmed))
+        return null;
+    // Exactly one placeholder, and it is the workspace token — the same rule the server
+    // applies, so `{state}`/`{code}`/anything else is refused rather than left literal.
+    const placeholders = trimmed.match(/\{[^{}]*\}/g);
+    if (!placeholders || placeholders.length !== 1 || placeholders[0] !== WORKSPACE_TOKEN) {
+        return null;
+    }
+    // A brace surviving removal of the single legal token means a nested or unbalanced
+    // construct — `{{workspace}}` matches the inner token above but would substitute to a
+    // literal `{acme-dev}` path segment. The server applies this same residue check, and
+    // the two must agree about what a safe template is.
+    const residue = trimmed.replace(WORKSPACE_TOKEN, "");
+    if (residue.includes("{") || residue.includes("}"))
+        return null;
+    const slug = validateBitbucketWorkspace(workspace);
+    if (!slug.ok)
+        return null;
+    const resolved = trimmed.replace(WORKSPACE_TOKEN, encodeURIComponent(slug.value));
+    let parsed;
+    try {
+        parsed = new URL(resolved);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "https:")
+        return null;
+    if (!parsed.hostname)
+        return null;
+    if (parsed.username || parsed.password)
+        return null;
+    return parsed.toString();
+}
+/**
+ * Is *template* structurally usable as printed guidance, even without a workspace?
+ *
+ * Uses the same rules as {@link renderBitbucketRedeemLink} by substituting a throwaway
+ * slug, so the two can never disagree about what counts as a safe template.
+ */
+function isPrintableRedeemTemplate(template) {
+    return renderBitbucketRedeemLink(template, "workspace") !== null;
+}
+/**
+ * Print the redemption destination for the code that is about to be shown.
+ *
+ * Invariant: the textual path is ALWAYS printed. A link, when one can be resolved, sits
+ * beneath it as a shortcut — never in place of it. Three shapes, in descending
+ * helpfulness, none of which is framed as an error:
+ *
+ *  - workspace + safe template → the resolved HTTPS link;
+ *  - safe template, no workspace → the literal template, with what to replace;
+ *  - no usable template → the textual path alone.
+ *
+ * Nothing printed here carries the connection code, the state nonce, or the install URL.
+ */
+function renderRedemptionGuidance(deps, template, workspace) {
+    deps.stderr(`In Bitbucket, go to: ${BITBUCKET_REDEEM_NAVIGATION_PATH}`);
+    if (workspace) {
+        const link = renderBitbucketRedeemLink(template, workspace);
+        // A malformed or unsafe template is dropped in silence: guidance configuration must
+        // never be able to stop, delay, or complicate a connection.
+        if (link)
+            deps.stderr(`  Direct link: ${link}`);
+        return;
+    }
+    if (isPrintableRedeemTemplate(template)) {
+        deps.stderr(`  Direct link: ${template.trim()}`);
+        deps.stderr("  Replace {workspace} with your Bitbucket workspace slug.");
+    }
+}
 /** Display identity for a candidate: prefer the unambiguous workspace/repo slug form. */
 function candidateLabel(c) {
     const slugForm = `${c.workspace_slug}/${c.repository_slug}`;
@@ -270,31 +456,52 @@ const FAILURE_MESSAGES = {
     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.",
 };
-/** The no-connection-made framing, used for every unsuccessful terminal path. */
-function reportNoConnection(deps, detail) {
-    deps.stderr("");
-    deps.stderr("No Bitbucket connection was made.");
-    deps.stderr(detail);
-    return 1;
+/** Only an explicit, case-insensitive `y`/`yes` approves. One definition, used everywhere. */
+function isAffirmative(answer) {
+    const normalized = answer.trim().toLowerCase();
+    return normalized === "y" || normalized === "yes";
 }
 /**
- * Ask which repository to bind. Returns null when the user declined or chose nothing.
- * Never renders a workspace/repository UUID or installation identifier.
+ * Ask a yes/no question. Every non-affirmative outcome — empty input, `n`, unrecognized
+ * text, EOF, an interrupted prompt — is a clean decline. A prompt that throws is a
+ * decline too: the user is trying to get out, not to see an exception.
  */
+async function confirm(deps, question) {
+    try {
+        return isAffirmative(await deps.promptLine(question));
+    }
+    catch {
+        return false;
+    }
+}
+/** The exact command that resumes this attempt. Quoted so a hostile repo name is inert. */
+function resumeCommand(repoName) {
+    return `connect-bitbucket --repo '${repoName}'`;
+}
+/**
+ * The no-connection-made framing, used for every unsuccessful terminal path.
+ *
+ * Always says what to run next: the code that was printed is gone (single-use and
+ * short-lived), so the only useful next step is a fresh run, and saying so is what stops
+ * a user hunting for a code that can no longer work. The expired code itself is never
+ * reprinted.
+ */
+function reportNoConnection(deps, detail, repoName, kind = "failed") {
+    deps.stderr("");
+    deps.stderr("Bitbucket connection was not completed.");
+    deps.stderr(detail);
+    deps.stderr(`To try again: ${resumeCommand(repoName)} (this issues a new code).`);
+    return { kind };
+}
 async function chooseCandidate(deps, candidates) {
     if (candidates.length === 1) {
         const only = candidates[0];
         // Even with one option: show the full identity and require a yes. The user is
         // authorizing a binding, not acknowledging a notice.
-        const answer = (await deps.promptLine(`Connect ${candidateLabel(only)}? [y/N]: `))
-            .trim()
-            .toLowerCase();
-        if (answer !== "y" && answer !== "yes") {
-            deps.stderr("");
-            deps.stderr("No Bitbucket connection was made. Nothing was changed.");
-            return null;
+        if (!(await confirm(deps, `Connect ${candidateLabel(only)}? [y/N]: `))) {
+            return { ok: false, detail: "Nothing was changed." };
         }
-        return only;
+        return { ok: true, value: only };
     }
     deps.stderr("");
     deps.stderr("Your Bitbucket Forge installation includes multiple repositories:");
@@ -303,81 +510,175 @@ async function chooseCandidate(deps, candidates) {
     });
     deps.stderr("");
     // No default: a stray Enter must not bind anything.
-    const answer = (await deps.promptLine(`Choose a repository [1-${candidates.length}]: `)).trim();
+    let answer = "";
+    try {
+        answer = (await deps.promptLine(`Choose a repository [1-${candidates.length}]: `)).trim();
+    }
+    catch {
+        answer = "";
+    }
     const index = Number(answer);
     if (answer.toLowerCase() === "q" ||
         !/^\d+$/.test(answer) ||
         !Number.isInteger(index) ||
         index < 1 ||
         index > candidates.length) {
-        deps.stderr("");
-        deps.stderr("No Bitbucket connection was made. No repository was selected.");
-        return null;
+        return { ok: false, detail: "No repository was selected." };
     }
     const selected = candidates[index - 1];
     deps.stderr(`Selected ${candidateLabel(selected)}.`);
-    return selected;
+    return { ok: true, value: selected };
 }
-export async function runBitbucketConnectionFlow(deps, api, repoName) {
+/**
+ * Run the full connect handshake, with unlimited user-approved code renewals.
+ *
+ * The loop exists because the failure this command actually hits is mundane: a code
+ * lives ~15 minutes, and a user who is mid-way through installing a Forge app can easily
+ * spend longer than that. Before BAPI-1247 that meant "run the whole command again";
+ * now it means one `[y/N]`. Renewal is *always* a fresh mint under the server's own TTL
+ * cap — a code is never extended, resumed, or reprinted.
+ *
+ * Renewal is offered for exactly two outcomes, both read from the typed discriminant
+ * rather than from message text: a server-reported `expired` status, and a client-side
+ * polling `deadline`. Everything else — `invalid`, `no-repositories`, a confirmation
+ * failure, any transport or API failure — stays terminal, because repeating a request
+ * the server already refused cannot help.
+ *
+ * Each iteration's minted value is the ONLY state used for polling and confirmation, so
+ * a renewal can never confirm against a previous code.
+ */
+export async function runBitbucketConnectionFlow(deps, api, repoName, options = {}) {
+    const { workspace, initialMintApproved = false } = options;
     renderStep(deps, 0);
-    const minted = await mintBitbucketConnection(api, repoName);
-    if (!minted.ok) {
-        return reportNoConnection(deps, FAILURE_MESSAGES[minted.kind]);
-    }
-    renderStep(deps, 1);
-    deps.stderr("Opening Bitbucket…");
-    // The URL goes straight from memory to the opener — never through a log line.
-    const opened = await openBitbucketInstallPage(deps, minted.value.installUrl);
-    if (!opened.ok) {
-        return reportNoConnection(deps, opened.error);
-    }
-    // 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).
-    deps.stderr(`Paste this code into the installed app's admin panel: ${minted.value.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)`);
-    const pollDeps = { sleep: deps.sleep, now: deps.now, jitter: deps.jitter };
-    const started = deps.now();
-    const polled = await pollBitbucketConnection(api, pollDeps, repoName, minted.value.state);
-    if (!polled.ok) {
-        return reportNoConnection(deps, FAILURE_MESSAGES[polled.kind]);
-    }
-    const elapsedSec = Math.max(0, Math.round((deps.now() - started) / 1_000));
-    deps.stderr(`Waited ${elapsedSec}s.`);
-    const result = polled.value;
-    if (result.status === "connected") {
-        // Already bound (e.g. a re-run against a finished handshake).
-        deps.stdout(`Connected ${result.repoDisplayName ?? repoName}.`);
-        return 0;
-    }
-    if (result.status !== "staged") {
-        return reportNoConnection(deps, OUTCOME_MESSAGES[result.status] ?? OUTCOME_MESSAGES.invalid);
-    }
-    const candidates = result.candidates;
-    if (candidates.length === 0) {
-        return reportNoConnection(deps, OUTCOME_MESSAGES["no-repositories"]);
+    if (!initialMintApproved) {
+        // A standalone run asks before it mints: minting is a side effect (a live code, a
+        // browser window), so it is opted in to, never assumed.
+        if (!(await confirm(deps, "Create a Bitbucket connection code now? [y/N]: "))) {
+            return reportNoConnection(deps, "No connection code was created.", repoName, "incomplete");
+        }
     }
-    renderStep(deps, 3);
-    const selected = await chooseCandidate(deps, candidates);
-    if (!selected)
-        return 1;
-    renderStep(deps, 4);
-    const confirmed = await confirmBitbucketConnection(api, repoName, minted.value.state, selected.workspace_uuid, selected.repository_uuid);
-    if (!confirmed.ok) {
-        return reportNoConnection(deps, FAILURE_MESSAGES[confirmed.kind]);
+    let browserOpened = false;
+    let expiryCount = 0;
+    for (;;) {
+        const minted = await mintBitbucketConnection(api, repoName);
+        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.
+            return reportNoConnection(deps, FAILURE_MESSAGES[minted.kind], repoName);
+        }
+        // Iteration-local. Nothing outside this block may read a previous code.
+        const connection = minted.value;
+        if (!browserOpened) {
+            renderStep(deps, 1);
+            deps.stderr("Opening Bitbucket…");
+            // The URL goes straight from memory to the opener — never through a log line.
+            const opened = await openBitbucketInstallPage(deps, connection.installUrl);
+            if (!opened.ok) {
+                return reportNoConnection(deps, opened.error, repoName);
+            }
+            // Only the FIRST code opens a browser. On a renewal the install page is already
+            // open (and its URL carries the old, now-dead state), so reopening it would be
+            // 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}`);
+        renderStep(deps, 2);
+        const minutes = Math.floor(POLL_DEADLINE_MS / 60_000);
+        deps.stderr(`Waiting for the Bitbucket Forge app… (up to ~${minutes} minutes)`);
+        const pollDeps = { sleep: deps.sleep, now: deps.now, jitter: deps.jitter };
+        const started = deps.now();
+        const polled = await pollBitbucketConnection(api, pollDeps, repoName, connection.state);
+        // The two renewable outcomes, taken from the typed discriminant.
+        const renewable = (polled.ok && polled.value.status === "expired") || (!polled.ok && polled.kind === "deadline");
+        if (renewable) {
+            expiryCount += 1;
+            deps.stderr("");
+            deps.stderr("That code expired and can no longer be used.");
+            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]: ")) {
+                continue;
+            }
+            return reportNoConnection(deps, polled.ok ? OUTCOME_MESSAGES.expired : FAILURE_MESSAGES.deadline, repoName, "incomplete");
+        }
+        if (!polled.ok) {
+            return reportNoConnection(deps, FAILURE_MESSAGES[polled.kind], repoName);
+        }
+        const elapsedSec = Math.max(0, Math.round((deps.now() - started) / 1_000));
+        deps.stderr(`Waited ${elapsedSec}s.`);
+        const result = polled.value;
+        if (result.status === "connected") {
+            // Already bound (e.g. a re-run against a finished handshake).
+            const displayName = result.repoDisplayName ?? repoName;
+            deps.stdout(`Connected ${displayName}.`);
+            return { kind: "connected", displayName };
+        }
+        if (result.status !== "staged") {
+            return reportNoConnection(deps, OUTCOME_MESSAGES[result.status] ?? OUTCOME_MESSAGES.invalid, repoName);
+        }
+        const candidates = result.candidates;
+        if (candidates.length === 0) {
+            return reportNoConnection(deps, OUTCOME_MESSAGES["no-repositories"], repoName);
+        }
+        renderStep(deps, 3);
+        const selected = await chooseCandidate(deps, candidates);
+        if (!selected.ok) {
+            return reportNoConnection(deps, selected.detail, repoName, "incomplete");
+        }
+        renderStep(deps, 4);
+        const confirmed = await confirmBitbucketConnection(api, repoName, 
+        // This iteration's code only. The server still derives the installation from it;
+        // there is no installation-id or codeless fallback.
+        connection.state, selected.value.workspace_uuid, selected.value.repository_uuid);
+        if (!confirmed.ok) {
+            return reportNoConnection(deps, FAILURE_MESSAGES[confirmed.kind], repoName);
+        }
+        const displayName = confirmed.value.workspaceSlug && confirmed.value.repositorySlug
+            ? `${confirmed.value.workspaceSlug}/${confirmed.value.repositorySlug}`
+            : confirmed.value.repoName;
+        deps.stdout(`Connected ${displayName}.`);
+        return { kind: "connected", displayName };
     }
-    const displayName = confirmed.value.workspaceSlug && confirmed.value.repositorySlug
-        ? `${confirmed.value.workspaceSlug}/${confirmed.value.repositorySlug}`
-        : confirmed.value.repoName;
-    deps.stdout(`Connected ${displayName}.`);
-    return 0;
 }
 // ---------------------------------------------------------------------------
 // Process boundary
 // ---------------------------------------------------------------------------
+/**
+ * Fixed, secret-free wording for each credential-resolution failure (BAPI-1247).
+ *
+ * `cred.error` is deliberately never interpolated. It can carry an absolute filesystem
+ * path, a JSON parser message quoting file contents, or text derived from stored
+ * credential material — none of which belongs in a terminal a user may screenshot or
+ * paste into a bug report. The user does not need the internal detail; they need to know
+ * which of two things to do.
+ */
+const CREDENTIAL_PROBLEM_MESSAGES = {
+    "not-found": "No stored Bridge credentials were found for this project.",
+    "missing-key": "The stored Bridge credentials for this project have no API key.",
+    "read-error": "The stored Bridge credentials could not be read.",
+    "parse-error": "The stored Bridge credentials are not in a readable format.",
+};
+/** Print the credential problem and exactly the two ways out of it. */
+function reportCredentialProblem(deps, kind) {
+    deps.stderr(CREDENTIAL_PROBLEM_MESSAGES[kind] ?? "Bridge credentials for this project are unavailable.");
+    deps.stderr("");
+    deps.stderr("Two ways to fix this:");
+    // Route 1 is the one that also repairs a damaged store, so it goes first.
+    deps.stderr("  1. Run the full Bridge install first — it provisions and stores a key for this project.");
+    // Named, not spelled as an assignment: `VAR=value cmd` is not portable shell, and
+    // telling a PowerShell user to type it would be wrong.
+    deps.stderr("  2. Provide BAPI_API_KEY in the environment this command runs in.");
+}
 /**
  * Entry point. Catches everything and always resolves to a numeric exit code — an
  * unhandled rejection here would surface a stack trace that could contain the install
@@ -419,7 +720,8 @@ export async function runConnectBitbucketCli(argv, injected) {
             stderr: () => { },
         });
         if (!cred.ok) {
-            deps.stderr(cred.error);
+            // Checked BEFORE minting or opening a browser: there is nothing to connect with.
+            reportCredentialProblem(deps, cred.kind);
             return 1;
         }
         const api = {
@@ -427,7 +729,15 @@ export async function runConnectBitbucketCli(argv, injected) {
             baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
             apiKey: cred.credentials.apiKey,
         };
-        return await runBitbucketConnectionFlow(deps, api, repo.value);
+        const result = await runBitbucketConnectionFlow(deps, api, repo.value, {
+            workspace: parsed.value.workspace,
+            // Standalone: nobody has asked yet, so the flow owns the initial confirmation.
+            initialMintApproved: false,
+        });
+        // Only a confirmed connection is a success. `incomplete` (the user stopped) and
+        // `failed` (something broke) are both non-zero — the shell cannot act on the
+        // difference, and the narrative distinction was already printed.
+        return result.kind === "connected" ? 0 : 1;
     }
     catch {
         // Never forward the caught value: it may carry the install URL or the nonce.