@pilatos/bitbucket-cli 1.14.0 → 1.16.0

package/dist/index.js

@@ -17440,6 +17440,8 @@ var ServiceTokens = {
   AddDefaultReviewerCommand: "AddDefaultReviewerCommand",
   RemoveDefaultReviewerCommand: "RemoveDefaultReviewerCommand",
   DefaultReviewerService: "DefaultReviewerService",
+  UrlBuilderService: "UrlBuilderService",
+  BrowseCommand: "BrowseCommand",
   CreatePRCommand: "CreatePRCommand",
   ListPRsCommand: "ListPRsCommand",
   ViewPRCommand: "ViewPRCommand",
@@ -17483,6 +17485,7 @@ var ServiceTokens = {
 // src/services/config.service.ts
 import { posix, win32 } from "path";
 import { homedir } from "os";
+import { randomUUID } from "crypto";
 
 // src/types/errors.ts
 class BBError extends Error {
@@ -17531,6 +17534,12 @@ class APIError extends BBError {
     }
   }
 }
+function rethrowWithNotFoundContext(error, notFoundMessage) {
+  if (error instanceof APIError && error.statusCode === 404) {
+    throw new APIError(notFoundMessage, 404, error.response, error.context);
+  }
+  throw error;
+}
 
 class GitError extends BBError {
   command;
@@ -17548,13 +17557,19 @@ class GitError extends BBError {
 }
 
 // src/services/config.service.ts
+var CONFIG_FILE_MODE = 384;
+var CONFIG_DIR_MODE = 448;
+var INSECURE_MODE_MASK = 63;
+
 class ConfigService {
   configDir;
   configFile;
+  platform;
   configCache = null;
   constructor(configDir, options = {}) {
     const platform = options.platform ?? process.platform;
     const joinPath = platform === "win32" ? win32.join : posix.join;
+    this.platform = platform;
     this.configDir = configDir ?? this.resolveDefaultConfigDir({ ...options, platform });
     this.configFile = joinPath(this.configDir, "config.json");
   }
@@ -17575,7 +17590,10 @@ class ConfigService {
   async ensureConfigDir() {
     try {
       const fs = await import("fs/promises");
-      await fs.mkdir(this.configDir, { recursive: true });
+      await fs.mkdir(this.configDir, {
+        recursive: true,
+        mode: CONFIG_DIR_MODE
+      });
     } catch (error) {
       throw new BBError({
         code: 4002 /* CONFIG_WRITE_FAILED */,
@@ -17584,12 +17602,36 @@ class ConfigService {
       });
     }
   }
+  async verifyPermissions(path, expectedMode, kind) {
+    if (this.platform === "win32")
+      return;
+    const fs = await import("fs/promises");
+    let stats;
+    try {
+      stats = await fs.stat(path);
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return;
+      throw error;
+    }
+    const mode = stats.mode & 511;
+    if (mode & INSECURE_MODE_MASK) {
+      const actual = mode.toString(8).padStart(3, "0");
+      const expected = expectedMode.toString(8).padStart(3, "0");
+      throw new BBError({
+        code: 4001 /* CONFIG_READ_FAILED */,
+        message: `Config ${kind} has insecure permissions (${actual}); expected ${expected}. Run: chmod ${expected} ${path}`
+      });
+    }
+  }
   async getConfig() {
     if (this.configCache) {
       return this.configCache;
     }
     try {
       const fs = await import("fs/promises");
+      await this.verifyPermissions(this.configDir, CONFIG_DIR_MODE, "directory");
+      await this.verifyPermissions(this.configFile, CONFIG_FILE_MODE, "file");
       const data = await fs.readFile(this.configFile, "utf-8");
       this.configCache = JSON.parse(data);
       return this.configCache;
@@ -17598,6 +17640,9 @@ class ConfigService {
         this.configCache = {};
         return this.configCache;
       }
+      if (error instanceof BBError) {
+        throw error;
+      }
       throw new BBError({
         code: 4001 /* CONFIG_READ_FAILED */,
         message: `Failed to read config file: ${this.configFile}`,
@@ -17607,13 +17652,20 @@ class ConfigService {
   }
   async setConfig(config) {
     await this.ensureConfigDir();
+    const fs = await import("fs/promises");
+    const body = JSON.stringify(config, null, 2);
+    const tmpFile = `${this.configFile}.${randomUUID()}.tmp`;
     try {
-      const fs = await import("fs/promises");
-      await fs.writeFile(this.configFile, JSON.stringify(config, null, 2), {
-        mode: 384
+      await fs.writeFile(tmpFile, body, {
+        mode: CONFIG_FILE_MODE,
+        flag: "wx"
       });
+      await fs.rename(tmpFile, this.configFile);
       this.configCache = config;
     } catch (error) {
+      try {
+        await fs.unlink(tmpFile);
+      } catch {}
       throw new BBError({
         code: 4002 /* CONFIG_WRITE_FAILED */,
         message: `Failed to write config file: ${this.configFile}`,
@@ -17627,7 +17679,7 @@ class ConfigService {
     if (!username || !apiToken) {
       throw new BBError({
         code: 1001 /* AUTH_REQUIRED */,
-        message: "Authentication required. Run 'bb auth login' to authenticate."
+        message: "Authentication required. Run 'bb auth login' or set BB_USERNAME and BB_API_TOKEN."
       });
     }
     return { username, apiToken };
@@ -17674,7 +17726,7 @@ class ConfigService {
     if (!oauthAccessToken || !oauthRefreshToken || !oauthExpiresAt) {
       throw new BBError({
         code: 1001 /* AUTH_REQUIRED */,
-        message: "OAuth authentication required. Run 'bb auth login' to authenticate."
+        message: "OAuth authentication required. Run 'bb auth login' or set BB_USERNAME and BB_API_TOKEN."
       });
     }
     return {
@@ -17773,6 +17825,9 @@ class GitService {
   async getCurrentBranch() {
     return this.execOrError(["rev-parse", "--abbrev-ref", "HEAD"]);
   }
+  async getCurrentCommit() {
+    return this.execOrError(["rev-parse", "HEAD"]);
+  }
   async getRemoteUrl(remote = "origin") {
     const result = await this.exec(["remote", "get-url", remote]);
     if (result.exitCode !== 0) {
@@ -17797,14 +17852,14 @@ class ContextService {
     this.configService = configService;
   }
   parseRemoteUrl(url) {
-    const sshMatch = /git@bitbucket\.org:([^/]+)\/([^.]+)(?:\.git)?/.exec(url);
+    const sshMatch = /^git@bitbucket\.org:([^/\s]+)\/([^/\s.]+)(?:\.git)?$/.exec(url);
     if (sshMatch) {
       return {
         workspace: sshMatch[1],
         repoSlug: sshMatch[2]
       };
     }
-    const httpsMatch = /https?:\/\/(?:[^@]+@)?bitbucket\.org\/([^/]+)\/([^/.]+)(?:\.git)?/.exec(url);
+    const httpsMatch = /^https?:\/\/(?:[^@\s]+@)?bitbucket\.org\/([^/\s]+)\/([^/\s.]+)(?:\.git)?$/.exec(url);
     if (httpsMatch) {
       return {
         workspace: httpsMatch[1],
@@ -17814,29 +17869,48 @@ class ContextService {
     return null;
   }
   async getRepoContextFromGit() {
+    const result = await this.inspectGitRepoContext();
+    return result.context;
+  }
+  async inspectGitRepoContext() {
     const isRepo = await this.gitService.isRepository();
     if (!isRepo) {
-      return null;
+      return { context: null, reason: "not_a_git_repo", remoteUrl: null };
     }
+    let remoteUrl;
     try {
-      const remoteUrl = await this.gitService.getRemoteUrl();
-      return this.parseRemoteUrl(remoteUrl);
+      remoteUrl = await this.gitService.getRemoteUrl();
     } catch {
-      return null;
+      return { context: null, reason: "no_remote", remoteUrl: null };
+    }
+    const context = this.parseRemoteUrl(remoteUrl);
+    if (!context) {
+      return { context: null, reason: "remote_not_bitbucket", remoteUrl };
     }
+    return { context, reason: null, remoteUrl };
   }
   async getRepoContext(options) {
+    const result = await this.resolveRepoContext(options);
+    return result.context;
+  }
+  async resolveRepoContext(options) {
     if (options.workspace && options.repo) {
       return {
-        workspace: options.workspace,
-        repoSlug: options.repo
+        context: { workspace: options.workspace, repoSlug: options.repo },
+        reason: null,
+        remoteUrl: null
       };
     }
-    const gitContext = await this.getRepoContextFromGit();
+    const gitResult = await this.inspectGitRepoContext();
+    const gitContext = gitResult.context;
     if (options.workspace && gitContext) {
       return {
-        workspace: options.workspace,
-        repoSlug: gitContext.repoSlug
+        context: {
+          workspace: options.workspace,
+          repoSlug: gitContext.repoSlug
+        },
+        reason: null,
+        remoteUrl: gitResult.remoteUrl
       };
     }
     if (options.repo) {
@@ -17844,22 +17918,40 @@ class ContextService {
       const workspace = gitContext?.workspace || config.defaultWorkspace;
       if (workspace) {
         return {
-          workspace,
-          repoSlug: options.repo
+          context: { workspace, repoSlug: options.repo },
+          reason: null,
+          remoteUrl: gitResult.remoteUrl
         };
       }
     }
-    return gitContext;
+    return gitResult;
   }
   async requireRepoContext(options) {
-    const context = await this.getRepoContext(options);
-    if (!context) {
+    const result = await this.resolveRepoContext(options);
+    if (!result.context) {
       throw new BBError({
         code: 6001 /* CONTEXT_REPO_NOT_FOUND */,
-        message: "Could not determine repository. Use --workspace and --repo options, " + "or run this command from within a Bitbucket repository."
+        message: this.buildRepoNotFoundMessage(result.reason, result.remoteUrl),
+        context: {
+          reason: result.reason ?? "unknown",
+          ...result.remoteUrl ? { remoteUrl: result.remoteUrl } : {}
+        }
       });
     }
-    return context;
+    return result.context;
+  }
+  buildRepoNotFoundMessage(reason, remoteUrl) {
+    const fallback = "Use --workspace and --repo options, or run this command from within a Bitbucket repository.";
+    switch (reason) {
+      case "not_a_git_repo":
+        return `Not in a git repository. ${fallback}`;
+      case "no_remote":
+        return `Git repository has no remote configured. Add a Bitbucket remote with \`git remote add origin <url>\`, or ${fallback.charAt(0).toLowerCase()}${fallback.slice(1)}`;
+      case "remote_not_bitbucket":
+        return `Remote ${remoteUrl ? `'${remoteUrl}' ` : ""}is not a Bitbucket URL. ${fallback}`;
+      default:
+        return `Could not determine repository. ${fallback}`;
+    }
   }
   async requireWorkspace(explicit) {
     if (explicit && explicit.length > 0) {
@@ -18397,6 +18489,10 @@ function deepGet(source, path) {
 }
 
 // src/services/output.service.ts
+var CONTROL_CHARS = /(\x1b\[[0-9;?]*m)|\x1b\[[0-9;?]*[A-Za-ln-z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x9B\x9D]/g;
+function stripControl(value) {
+  return value.replace(CONTROL_CHARS, (_match, sgr) => sgr ?? "");
+}
 var WRAPPER_ARRAY_KEYS = [
   "pullRequests",
   "repositories",
@@ -18442,36 +18538,38 @@ class OutputService {
     if (rows.length === 0) {
       return;
     }
-    const widths = headers.map((header, index) => {
-      const maxRowWidth = Math.max(...rows.map((row) => (row[index] || "").length));
+    const sanitizedHeaders = headers.map(stripControl);
+    const sanitizedRows = rows.map((row) => row.map((cell) => stripControl(cell || "")));
+    const widths = sanitizedHeaders.map((header, index) => {
+      const maxRowWidth = Math.max(...sanitizedRows.map((row) => (row[index] || "").length));
       return Math.max(header.length, maxRowWidth);
     });
-    const headerRow = headers.map((header, index) => header.padEnd(widths[index])).join("  ");
+    const headerRow = sanitizedHeaders.map((header, index) => header.padEnd(widths[index])).join("  ");
     console.log(this.format(headerRow, source_default.bold));
     console.log(widths.map((width) => "-".repeat(width)).join("  "));
-    for (const row of rows) {
-      const formattedRow = row.map((cell, index) => (cell || "").padEnd(widths[index])).join("  ");
+    for (const row of sanitizedRows) {
+      const formattedRow = row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
       console.log(formattedRow);
     }
   }
   success(message) {
     const symbol = this.format("\u2713", source_default.green);
-    console.log(`${symbol} ${message}`);
+    console.log(`${symbol} ${stripControl(message)}`);
   }
   error(message) {
     const symbol = this.format("\u2717", source_default.red);
-    console.error(`${symbol} ${message}`);
+    console.error(`${symbol} ${stripControl(message)}`);
   }
   warning(message) {
     const symbol = this.format("\u26A0", source_default.yellow);
-    console.warn(`${symbol} ${message}`);
+    console.warn(`${symbol} ${stripControl(message)}`);
   }
   info(message) {
     const symbol = this.format("\u2139", source_default.blue);
-    console.log(`${symbol} ${message}`);
+    console.log(`${symbol} ${stripControl(message)}`);
   }
   text(message) {
-    console.log(message);
+    console.log(stripControl(message));
   }
   formatDate(date) {
     const d = typeof date === "string" ? new Date(date) : date;
@@ -22485,6 +22583,17 @@ function getRetryDelay(error, attempt) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function redactRequestUrl(requestUrl, baseUrl) {
+  const raw = requestUrl ?? "";
+  try {
+    const parsed = new URL(raw, baseUrl);
+    const query = parsed.search ? "?[redacted]" : "";
+    return `${parsed.origin}${parsed.pathname}${query}`;
+  } catch {
+    const queryIdx = raw.indexOf("?");
+    return queryIdx === -1 ? raw : `${raw.slice(0, queryIdx)}?[redacted]`;
+  }
+}
 function createApiClient(credentialStore, oauthService) {
   const instance = axios_default.create({
     baseURL: BASE_URL,
@@ -22495,7 +22604,7 @@ function createApiClient(credentialStore, oauthService) {
   });
   instance.interceptors.request.use(async (config) => {
     if (process.env.DEBUG === "true") {
-      console.debug(`[HTTP] ${config.method?.toUpperCase()} ${config.url}`);
+      console.debug(`[HTTP] ${config.method?.toUpperCase()} ${redactRequestUrl(config.url, config.baseURL)}`);
     }
     const authMethod = await credentialStore.getAuthMethod();
     if (authMethod === "oauth" && oauthService) {
@@ -22558,11 +22667,17 @@ function createApiClient(credentialStore, oauthService) {
     if (error.response) {
       const { status, data } = error.response;
       const message = extractErrorMessage(data) || error.message;
-      throw new APIError(message, status, data);
+      const method = error.config?.method?.toUpperCase();
+      const url2 = error.config?.url;
+      throw new APIError(message, status, data, {
+        status,
+        ...method ? { method } : {},
+        ...url2 ? { url: url2 } : {}
+      });
     } else if (error.request) {
       throw new BBError({
         code: 7001 /* NETWORK_ERROR */,
-        message: "Network error: Unable to reach Bitbucket API",
+        message: "Network error: Unable to reach Bitbucket API. Run with DEBUG=true for details. If you're behind a proxy or using a custom CA, check your environment.",
         cause: error
       });
     } else {
@@ -22592,13 +22707,15 @@ function extractErrorMessage(data) {
 }
 // src/services/oauth.service.ts
 import { createServer } from "http";
-import { randomBytes } from "crypto";
+import { createHash, randomBytes } from "crypto";
 var BITBUCKET_AUTHORIZE_URL = "https://bitbucket.org/site/oauth2/authorize";
 var BITBUCKET_TOKEN_URL = "https://bitbucket.org/site/oauth2/access_token";
+var CALLBACK_HOST = "127.0.0.1";
 var CALLBACK_PORT = 19872;
 var CALLBACK_PATH = "/callback";
 var CALLBACK_URL = `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
 var AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 1e4;
 var DEFAULT_CLIENT_ID = "ErUBvNmdYtfVHgW6J4";
 var DEFAULT_CLIENT_SECRET = "QnrWypuKXv7YvU7WJwQRza2n2QfHCEw5";
 var OAUTH_SCOPES = [
@@ -22609,7 +22726,36 @@ var OAUTH_SCOPES = [
   "pullrequest:write"
 ].join(" ");
 function generateState() {
-  return randomBytes(16).toString("hex");
+  return randomBytes(32).toString("hex");
+}
+function base64UrlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generatePkcePair() {
+  const verifier = base64UrlEncode(randomBytes(32));
+  const challenge = base64UrlEncode(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+var OAUTH_ERROR_DESCRIPTION_MAX_LENGTH = 200;
+function extractOAuthErrorDescription(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("error_description" in parsed)) {
+    return;
+  }
+  const description = parsed.error_description;
+  if (typeof description !== "string") {
+    return;
+  }
+  const sanitized = description.replace(/\s+/g, " ").trim();
+  if (sanitized.length === 0) {
+    return;
+  }
+  return sanitized.length > OAUTH_ERROR_DESCRIPTION_MAX_LENGTH ? `${sanitized.slice(0, OAUTH_ERROR_DESCRIPTION_MAX_LENGTH)}\u2026` : sanitized;
 }
 
 class OAuthService {
@@ -22622,9 +22768,10 @@ class OAuthService {
   async authorize(clientId, clientSecret) {
     const resolvedClientId = clientId ?? await this.getClientId();
     const state = generateState();
-    const authUrl = this.buildAuthUrl(resolvedClientId, state);
+    const { verifier, challenge } = generatePkcePair();
+    const authUrl = this.buildAuthUrl(resolvedClientId, state, challenge);
     const { code } = await this.waitForCallback(authUrl, state);
-    const tokenResponse = await this.exchangeCode(code, resolvedClientId, clientSecret);
+    const tokenResponse = await this.exchangeCode(code, resolvedClientId, verifier, clientSecret);
     const expiresAt = Math.floor(Date.now() / 1000) + tokenResponse.expires_in;
     await this.credentialStore.setOAuthCredentials({
       accessToken: tokenResponse.access_token,
@@ -22654,14 +22801,17 @@ class OAuthService {
         "Content-Type": "application/x-www-form-urlencoded",
         Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
       },
-      body: params.toString()
+      body: params.toString(),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
     });
     if (!response.ok) {
       const errorBody = await response.text();
+      const description = extractOAuthErrorDescription(errorBody);
+      const baseMessage = `Failed to refresh OAuth token. Run 'bb auth login' to re-authenticate.`;
       throw new BBError({
         code: 1003 /* AUTH_EXPIRED */,
-        message: `Failed to refresh OAuth token. Run 'bb auth login' to re-authenticate.`,
-        context: { status: response.status, body: errorBody }
+        message: description ? `${baseMessage} (${description})` : baseMessage,
+        context: { status: response.status }
       });
     }
     const tokenResponse = await response.json();
@@ -22674,22 +22824,29 @@ class OAuthService {
     return tokenResponse.access_token;
   }
   async revokeToken() {
-    try {
-      const credentials = await this.credentialStore.getOAuthCredentials();
-      const clientId = await this.getClientId();
-      const clientSecret = await this.getClientSecret();
-      const params = new URLSearchParams({
-        token: credentials.accessToken
-      });
-      await fetch("https://bitbucket.org/site/oauth2/revoke", {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/x-www-form-urlencoded",
-          Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
-        },
-        body: params.toString()
+    const credentials = await this.credentialStore.getOAuthCredentials();
+    const clientId = await this.getClientId();
+    const clientSecret = await this.getClientSecret();
+    const params = new URLSearchParams({
+      token: credentials.accessToken
+    });
+    const response = await fetch("https://bitbucket.org/site/oauth2/revoke", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
+      },
+      body: params.toString(),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      throw new BBError({
+        code: 7001 /* NETWORK_ERROR */,
+        message: `Failed to revoke OAuth token (HTTP ${response.status}).`,
+        context: { status: response.status, body: errorBody }
       });
-    } catch {}
+    }
   }
   async getValidAccessToken() {
     const isExpired = await this.credentialStore.isOAuthTokenExpired();
@@ -22707,13 +22864,15 @@ class OAuthService {
     const customSecret = await this.configService.getValue("oauthClientSecret");
     return customSecret ?? DEFAULT_CLIENT_SECRET;
   }
-  buildAuthUrl(clientId, state) {
+  buildAuthUrl(clientId, state, codeChallenge) {
     const params = new URLSearchParams({
       client_id: clientId,
       response_type: "code",
       redirect_uri: CALLBACK_URL,
       scope: OAUTH_SCOPES,
-      state
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
     });
     return `${BITBUCKET_AUTHORIZE_URL}?${params.toString()}`;
   }
@@ -22783,7 +22942,7 @@ class OAuthService {
           }));
         }
       });
-      server.listen(CALLBACK_PORT, async () => {
+      server.listen(CALLBACK_PORT, CALLBACK_HOST, async () => {
         try {
           const open2 = (await Promise.resolve().then(() => (init_open(), exports_open))).default;
           await open2(authUrl);
@@ -22794,12 +22953,13 @@ ${authUrl}
       });
     });
   }
-  async exchangeCode(code, clientId, clientSecretOverride) {
+  async exchangeCode(code, clientId, codeVerifier, clientSecretOverride) {
     const clientSecret = clientSecretOverride ?? await this.getClientSecret();
     const params = new URLSearchParams({
       grant_type: "authorization_code",
       code,
-      redirect_uri: CALLBACK_URL
+      redirect_uri: CALLBACK_URL,
+      code_verifier: codeVerifier
     });
     const response = await fetch(BITBUCKET_TOKEN_URL, {
       method: "POST",
@@ -22807,21 +22967,25 @@ ${authUrl}
         "Content-Type": "application/x-www-form-urlencoded",
         Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
       },
-      body: params.toString()
+      body: params.toString(),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
     });
     if (!response.ok) {
       const errorBody = await response.text();
+      const description = extractOAuthErrorDescription(errorBody);
+      const baseMessage = `Failed to exchange authorization code. Please try again.`;
       throw new BBError({
         code: 1002 /* AUTH_INVALID */,
-        message: `Failed to exchange authorization code. Please try again.`,
-        context: { status: response.status, body: errorBody }
+        message: description ? `${baseMessage} (${description})` : baseMessage,
+        context: { status: response.status }
       });
     }
     return await response.json();
   }
   async fetchUserInfo(accessToken) {
     const response = await fetch("https://api.bitbucket.org/2.0/user", {
-      headers: { Authorization: `Bearer ${accessToken}` }
+      headers: { Authorization: `Bearer ${accessToken}` },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
     });
     if (!response.ok) {
       throw new BBError({
@@ -23217,6 +23381,67 @@ function accountToEntry(account) {
     nickname: asUser.nickname
   };
 }
+// src/services/url-builder.service.ts
+var BITBUCKET_WEB_BASE = "https://bitbucket.org";
+function encodePathSegments(path3) {
+  return path3.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
+
+class UrlBuilderService {
+  base;
+  constructor(base = BITBUCKET_WEB_BASE) {
+    this.base = base.replace(/\/+$/, "");
+  }
+  repo(ctx) {
+    return this.repoBase(ctx);
+  }
+  src(ctx, branch, path3, line) {
+    const encodedBranch = encodeURIComponent(branch);
+    const trimmedPath = path3?.replace(/^\/+/, "").replace(/\/+$/, "") ?? "";
+    const pathPart = trimmedPath ? `/${encodePathSegments(trimmedPath)}` : "/";
+    const lineFragment = typeof line === "number" && Number.isFinite(line) && line > 0 ? `#lines-${line}` : "";
+    return `${this.repoBase(ctx)}/src/${encodedBranch}${pathPart}${lineFragment}`;
+  }
+  branchList(ctx) {
+    return `${this.repoBase(ctx)}/branches/`;
+  }
+  commit(ctx, sha) {
+    return `${this.repoBase(ctx)}/commits/${encodeURIComponent(sha)}`;
+  }
+  commitList(ctx) {
+    return `${this.repoBase(ctx)}/commits/`;
+  }
+  pullRequest(ctx, id) {
+    return `${this.repoBase(ctx)}/pull-requests/${id}`;
+  }
+  pullRequestList(ctx) {
+    return `${this.repoBase(ctx)}/pull-requests/`;
+  }
+  pipelinesHome(ctx) {
+    return `${this.repoBase(ctx)}/pipelines`;
+  }
+  pipelineRun(ctx, idOrUuid) {
+    return `${this.repoBase(ctx)}/pipelines/results/${encodeURIComponent(idOrUuid)}`;
+  }
+  downloads(ctx) {
+    return `${this.repoBase(ctx)}/downloads/`;
+  }
+  issue(ctx, id) {
+    return `${this.repoBase(ctx)}/issues/${id}`;
+  }
+  issueList(ctx) {
+    return `${this.repoBase(ctx)}/issues`;
+  }
+  wiki(ctx) {
+    return `${this.repoBase(ctx)}/wiki`;
+  }
+  settings(ctx) {
+    return `${this.repoBase(ctx)}/admin`;
+  }
+  repoBase(ctx) {
+    return `${this.base}/${encodeURIComponent(ctx.workspace)}/${encodeURIComponent(ctx.repoSlug)}`;
+  }
+}
 // src/bootstrap.ts
 import { createRequire } from "module";
 
@@ -27005,13 +27230,32 @@ class BaseCommand {
   }
   requireOption(value, name, message) {
     if (value === undefined || value === null || value === "") {
+      const baseMessage = message || `Option --${name} is required`;
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: message || `Option --${name} is required`
+        message: this.appendHelpHint(baseMessage)
       });
     }
     return value;
   }
+  appendHelpHint(message) {
+    const commandPath = this.getCommandPath();
+    const target = commandPath ? `bb ${commandPath} --help` : "bb --help";
+    return `${message} Run \`${target}\` for usage.`;
+  }
+  getCommandPath() {
+    const argv = process.argv.slice(2);
+    const tokens = [];
+    for (const arg of argv) {
+      if (arg.startsWith("-"))
+        break;
+      tokens.push(arg);
+    }
+    if (tokens.length >= 2) {
+      return `${tokens[0]} ${tokens[1]}`;
+    }
+    return tokens.join(" ");
+  }
   parseIntOption(value, name) {
     const parsed = Number.parseInt(value, 10);
     if (Number.isNaN(parsed)) {
@@ -27112,12 +27356,33 @@ class LoginCommand extends BaseCommand {
       this.output.success(`Logged in as ${user.display_name} (${user.username})`);
     } catch (error) {
       await this.credentialStore.clearCredentials();
-      throw new BBError({
-        code: 1002 /* AUTH_INVALID */,
-        message: `Authentication failed: ${error instanceof Error ? error.message : String(error)}`
-      });
+      throw this.wrapLoginError(error);
     }
   }
+  wrapLoginError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (error instanceof APIError) {
+      if (error.statusCode === 401 || error.statusCode === 403) {
+        return new BBError({
+          code: 1002 /* AUTH_INVALID */,
+          message: `Invalid username or token: ${detail}. Verify your Bitbucket username and that the API token is current and has the required scopes.`,
+          cause: error
+        });
+      }
+      if (error.statusCode === 429) {
+        return new BBError({
+          code: 2004 /* API_RATE_LIMITED */,
+          message: `Bitbucket API rate-limited: ${detail}. Wait a moment and try again.`,
+          cause: error
+        });
+      }
+    }
+    return new BBError({
+      code: 1002 /* AUTH_INVALID */,
+      message: `Authentication failed: ${detail}`,
+      cause: error instanceof Error ? error : undefined
+    });
+  }
 }
 
 // src/commands/auth/logout.command.ts
@@ -27133,16 +27398,28 @@ class LogoutCommand extends BaseCommand {
   }
   async execute(_options, context) {
     const authMethod = await this.credentialStore.getAuthMethod();
+    let revokeFailed = false;
     if (authMethod === "oauth") {
-      await this.oauthService.revokeToken();
+      try {
+        await this.oauthService.revokeToken();
+      } catch {
+        revokeFailed = true;
+      }
       await this.credentialStore.clearOAuthCredentials();
     } else {
       await this.credentialStore.clearCredentials();
     }
     if (context.globalOptions.json) {
-      await this.output.json({ authenticated: false, success: true });
+      await this.output.json({
+        authenticated: false,
+        success: true,
+        revokeFailed: revokeFailed || undefined
+      });
       return;
     }
+    if (revokeFailed) {
+      this.output.warning("Token revocation failed; the access token may still be valid at Bitbucket. Consider revoking it manually.");
+    }
     this.output.success("Logged out of Bitbucket");
   }
 }
@@ -27252,7 +27529,7 @@ class TokenCommand extends BaseCommand {
     if (!credentials.username || !credentials.apiToken) {
       throw new BBError({
         code: 1001 /* AUTH_REQUIRED */,
-        message: "Not authenticated. Run 'bb auth login' first."
+        message: "Not authenticated. Run 'bb auth login' or set BB_USERNAME and BB_API_TOKEN."
       });
     }
     const token = Buffer.from(`${credentials.username}:${credentials.apiToken}`).toString("base64");
@@ -27729,7 +28006,7 @@ class ViewRepoCommand extends BaseCommand {
     const response = await this.repositoriesApi.repositoriesWorkspaceRepoSlugGet({
       workspace: repoContext.workspace,
       repoSlug: repoContext.repoSlug
-    });
+    }).catch((error) => rethrowWithNotFoundContext(error, `Repository ${repoContext.workspace}/${repoContext.repoSlug} not found.`));
     const repo = response.data;
     if (context.globalOptions.json) {
       await this.output.json(repo);
@@ -27952,7 +28229,7 @@ class CreatePRCommand extends BaseCommand {
     if (!options.title) {
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: "Pull request title is required. Use --title option."
+        message: this.appendHelpHint("Pull request title is required. Use --title option.")
       });
     }
     const repoContext = await this.contextService.requireRepoContext({
@@ -28175,7 +28452,7 @@ class ViewPRCommand extends BaseCommand {
       workspace: repoContext.workspace,
       repoSlug: repoContext.repoSlug,
       pullRequestId: prId
-    });
+    }).catch((error) => rethrowWithNotFoundContext(error, `Pull request #${prId} not found in ${repoContext.workspace}/${repoContext.repoSlug}.`));
     const pr = response.data;
     if (context.globalOptions.json) {
       await this.output.json(pr);
@@ -28337,8 +28614,9 @@ class EditPRCommand extends BaseCommand {
       try {
         body = fs7.readFileSync(options.bodyFile, "utf-8");
       } catch (err) {
+        const isNotFound = err instanceof Error && err.code === "ENOENT";
         throw new BBError({
-          code: 9999 /* UNKNOWN */,
+          code: isNotFound ? 5003 /* FILE_NOT_FOUND */ : 9999 /* UNKNOWN */,
           message: `Failed to read file '${options.bodyFile}': ${err instanceof Error ? err.message : "Unknown error"}`,
           cause: err instanceof Error ? err : undefined,
           context: { bodyFile: options.bodyFile }
@@ -28608,10 +28886,6 @@ class CheckoutPRCommand extends BaseCommand {
 }
 
 // src/commands/pr/diff.command.ts
-import { exec } from "child_process";
-import { promisify as promisify7 } from "util";
-var execAsync = promisify7(exec);
-
 class DiffPRCommand extends BaseCommand {
   pullrequestsApi;
   contextService;
@@ -28722,16 +28996,8 @@ class DiffPRCommand extends BaseCommand {
   }
   async openInBrowser(url2) {
     this.output.info(`Opening ${url2} in your browser...`);
-    const platform2 = process.platform;
-    let command;
-    if (platform2 === "darwin") {
-      command = `open "${url2}"`;
-    } else if (platform2 === "win32") {
-      command = `start "" "${url2}"`;
-    } else {
-      command = `xdg-open "${url2}"`;
-    }
-    await execAsync(command);
+    const open2 = (await Promise.resolve().then(() => (init_open(), exports_open))).default;
+    await open2(url2);
   }
   async getWebDiffUrl(workspace, repoSlug, prId) {
     const prResponse = await this.pullrequestsApi.repositoriesWorkspaceRepoSlugPullrequestsPullRequestIdGet({
@@ -28961,11 +29227,11 @@ class ActivityPRCommand extends BaseCommand {
     return activity.type ? activity.type.toLowerCase() : "activity";
   }
   getActorName(activity) {
-    const user = activity.comment?.user ?? activity.comment?.author ?? activity.approval?.user ?? activity.update?.author ?? activity.changes_requested?.user ?? activity.merge?.user ?? activity.decline?.user ?? activity.commit?.author?.user ?? activity.user;
+    const user = activity.comment?.user ?? activity.comment?.author ?? activity.approval?.user ?? activity.changes_requested?.user ?? activity.merge?.user ?? activity.decline?.user ?? activity.commit?.author?.user ?? activity.update?.author ?? activity.user;
     return getUserDisplayName(user) ?? "Unknown";
   }
   formatActivityDate(activity) {
-    const date = activity.comment?.created_on ?? activity.approval?.date ?? activity.update?.date ?? activity.changes_requested?.date ?? activity.merge?.date ?? activity.decline?.date ?? activity.commit?.date;
+    const date = activity.comment?.created_on ?? activity.approval?.date ?? activity.changes_requested?.date ?? activity.merge?.date ?? activity.decline?.date ?? activity.commit?.date ?? activity.update?.date;
     if (!date) {
       return "-";
     }
@@ -29034,16 +29300,23 @@ class CommentPRCommand extends BaseCommand {
     this.contextService = contextService;
   }
   async execute(options, context) {
+    const validModesNote = "Valid modes: (1) general comment (no flags); (2) file-level comment (--file + --line-to or --line-from); (3) inline comment with line range (--file + --line-from + --line-to).";
     if ((options.lineTo || options.lineFrom) && !options.file) {
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: "--file is required when using --line-to or --line-from"
+        message: this.appendHelpHint(`--file is required when using --line-to or --line-from. ${validModesNote}`),
+        context: {
+          validModes: ["general", "file", "inline"]
+        }
       });
     }
     if (options.file && !options.lineTo && !options.lineFrom) {
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: "At least one of --line-to or --line-from is required when using --file"
+        message: this.appendHelpHint(`At least one of --line-to or --line-from is required when using --file. ${validModesNote}`),
+        context: {
+          validModes: ["general", "file", "inline"]
+        }
       });
     }
     if (options.lineTo) {
@@ -29575,13 +29848,13 @@ class ViewSnippetCommand extends BaseCommand {
     const response = await this.snippetsApi.snippetsWorkspaceEncodedIdGet({
       workspace,
       encodedId: options.id
-    });
+    }).catch((error) => rethrowWithNotFoundContext(error, `Snippet ${options.id} not found in workspace ${workspace}.`));
     const snippet = response.data;
     const fileNames = this.extractFileNames(snippet);
     if (options.file !== undefined) {
       if (!fileNames.includes(options.file)) {
         throw new BBError({
-          code: 5002 /* VALIDATION_INVALID */,
+          code: 5003 /* FILE_NOT_FOUND */,
           message: `File not found in snippet: ${options.file}`,
           context: { file: options.file, available: fileNames }
         });
@@ -29689,7 +29962,7 @@ class CreateSnippetCommand extends BaseCommand {
     for (const filePath of options.file) {
       if (!fs8.existsSync(filePath)) {
         throw new BBError({
-          code: 5002 /* VALIDATION_INVALID */,
+          code: 5003 /* FILE_NOT_FOUND */,
           message: `File not found: ${filePath}`,
           context: { file: filePath }
         });
@@ -29748,7 +30021,7 @@ class EditSnippetCommand extends BaseCommand {
       for (const filePath of options.file) {
         if (!fs9.existsSync(filePath)) {
           throw new BBError({
-            code: 5002 /* VALIDATION_INVALID */,
+            code: 5003 /* FILE_NOT_FOUND */,
             message: `File not found: ${filePath}`,
             context: { file: filePath }
           });
@@ -30052,7 +30325,7 @@ class GetConfigCommand extends BaseCommand {
     if (GetConfigCommand.HIDDEN_KEYS.includes(key)) {
       throw new BBError({
         code: 4003 /* CONFIG_INVALID_KEY */,
-        message: `Cannot display '${key}' - use 'bb auth token' to get authentication credentials`,
+        message: `Cannot display '${key}' - it is part of your authentication credentials, not config. ` + `Use 'bb auth token' to retrieve credentials, or run 'bb config list' to see readable keys.`,
         context: { key }
       });
     }
@@ -30164,9 +30437,11 @@ class ListConfigCommand extends BaseCommand {
     ]);
     if (rows.length === 0) {
       this.output.text("No configuration set");
-      return;
+    } else {
+      this.output.table(["KEY", "VALUE"], rows);
     }
-    this.output.table(["KEY", "VALUE"], rows);
+    this.output.text("");
+    this.output.text(this.output.dim(`Settable keys: ${SETTABLE_CONFIG_KEYS.join(", ")}. Run 'bb config set --help' for details.`));
   }
 }
 
@@ -30199,7 +30474,7 @@ class InstallCompletionCommand extends BaseCommand {
       this.output.text("Restart your shell or source your profile to enable completions.");
     } catch (error) {
       throw new BBError({
-        code: 9999 /* UNKNOWN */,
+        code: 9001 /* COMPLETION_INSTALL_FAILED */,
         message: `Failed to install completions: ${error}`,
         cause: error instanceof Error ? error : undefined
       });
@@ -30234,7 +30509,7 @@ class UninstallCompletionCommand extends BaseCommand {
       this.output.success("Shell completions uninstalled successfully!");
     } catch (error) {
       throw new BBError({
-        code: 9999 /* UNKNOWN */,
+        code: 9002 /* COMPLETION_UNINSTALL_FAILED */,
         message: `Failed to uninstall completions: ${error}`,
         cause: error instanceof Error ? error : undefined
       });
@@ -30242,6 +30517,193 @@ class UninstallCompletionCommand extends BaseCommand {
   }
 }
 
+// src/commands/browse.command.ts
+var SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+var PR_NUMBER_PATTERN = /^\d+$/;
+var PATH_LINE_PATTERN = /^(.+):(\d+)$/;
+
+class BrowseCommand extends BaseCommand {
+  contextService;
+  gitService;
+  urlBuilder;
+  name = "browse";
+  description = "Open a Bitbucket page (repo, file, PR, commit, etc.) in your browser";
+  constructor(contextService, gitService, urlBuilder, output) {
+    super(output);
+    this.contextService = contextService;
+    this.gitService = gitService;
+    this.urlBuilder = urlBuilder;
+  }
+  async execute(options, context) {
+    const repoContext = await this.contextService.requireRepoContext({
+      ...context.globalOptions,
+      ...options
+    });
+    this.validateFlagCombination(options);
+    const url2 = await this.resolveUrl(options, repoContext);
+    const useJson = Boolean(context.globalOptions.json);
+    const printOnly = options.browser === false;
+    if (useJson) {
+      await this.output.json({ url: url2 });
+      return { url: url2, opened: false };
+    }
+    if (printOnly) {
+      this.output.text(url2);
+      return { url: url2, opened: false };
+    }
+    await this.openInBrowser(url2);
+    return { url: url2, opened: true };
+  }
+  async resolveUrl(options, ctx) {
+    if (options.pr !== undefined) {
+      return this.urlBuilder.pullRequest(ctx, this.parsePositiveInt(options.pr, "pr"));
+    }
+    if (options.prs || options.pullRequests) {
+      return this.urlBuilder.pullRequestList(ctx);
+    }
+    if (options.branches) {
+      return this.urlBuilder.branchList(ctx);
+    }
+    if (options.commits) {
+      return this.urlBuilder.commitList(ctx);
+    }
+    if (options.commit !== undefined) {
+      const sha = typeof options.commit === "string" && options.commit.length > 0 ? options.commit : await this.gitService.getCurrentCommit();
+      return this.urlBuilder.commit(ctx, sha);
+    }
+    if (options.pipelines) {
+      return this.urlBuilder.pipelinesHome(ctx);
+    }
+    if (options.pipeline !== undefined) {
+      const value = options.pipeline.trim();
+      if (value.length === 0) {
+        throw new BBError({
+          code: 5002 /* VALIDATION_INVALID */,
+          message: this.appendHelpHint("--pipeline requires a run id or uuid.")
+        });
+      }
+      return this.urlBuilder.pipelineRun(ctx, value);
+    }
+    if (options.downloads) {
+      return this.urlBuilder.downloads(ctx);
+    }
+    if (options.issue !== undefined) {
+      return this.urlBuilder.issue(ctx, this.parsePositiveInt(options.issue, "issue"));
+    }
+    if (options.issues) {
+      return this.urlBuilder.issueList(ctx);
+    }
+    if (options.wiki) {
+      return this.urlBuilder.wiki(ctx);
+    }
+    if (options.settings) {
+      return this.urlBuilder.settings(ctx);
+    }
+    const target = options.target?.trim();
+    if (target && target.length > 0) {
+      if (PR_NUMBER_PATTERN.test(target)) {
+        return this.urlBuilder.pullRequest(ctx, Number.parseInt(target, 10));
+      }
+      if (SHA_PATTERN.test(target)) {
+        return this.urlBuilder.commit(ctx, target);
+      }
+      const { path: path3, line } = this.parsePathWithLine(target);
+      const branch = await this.resolveBranch(options.branch);
+      return this.urlBuilder.src(ctx, branch, path3, line);
+    }
+    if (options.branch) {
+      return this.urlBuilder.src(ctx, options.branch);
+    }
+    return this.urlBuilder.repo(ctx);
+  }
+  validateFlagCombination(options) {
+    const setFlags = [];
+    if (options.pr !== undefined)
+      setFlags.push("--pr");
+    if (options.prs) {
+      setFlags.push("--prs");
+    } else if (options.pullRequests) {
+      setFlags.push("--pull-requests");
+    }
+    if (options.branches)
+      setFlags.push("--branches");
+    if (options.commit !== undefined)
+      setFlags.push("--commit");
+    if (options.commits)
+      setFlags.push("--commits");
+    if (options.pipelines)
+      setFlags.push("--pipelines");
+    if (options.pipeline !== undefined)
+      setFlags.push("--pipeline");
+    if (options.downloads)
+      setFlags.push("--downloads");
+    if (options.issue !== undefined)
+      setFlags.push("--issue");
+    if (options.issues)
+      setFlags.push("--issues");
+    if (options.wiki)
+      setFlags.push("--wiki");
+    if (options.settings)
+      setFlags.push("--settings");
+    if (setFlags.length > 1) {
+      throw new BBError({
+        code: 5002 /* VALIDATION_INVALID */,
+        message: this.appendHelpHint(`Cannot combine ${setFlags.join(" and ")}; pick one resource.`)
+      });
+    }
+    const hasResourceFlag = setFlags.length === 1;
+    const hasTarget = !!options.target?.trim();
+    if (hasResourceFlag && hasTarget) {
+      throw new BBError({
+        code: 5002 /* VALIDATION_INVALID */,
+        message: this.appendHelpHint(`Cannot use a positional target with ${setFlags[0]}.`)
+      });
+    }
+    if (hasResourceFlag && options.branch) {
+      throw new BBError({
+        code: 5002 /* VALIDATION_INVALID */,
+        message: this.appendHelpHint(`Cannot combine --branch with ${setFlags[0]}.`)
+      });
+    }
+  }
+  parsePathWithLine(target) {
+    const match = PATH_LINE_PATTERN.exec(target);
+    if (match) {
+      const line = Number.parseInt(match[2], 10);
+      if (Number.isFinite(line) && line > 0) {
+        return { path: match[1], line };
+      }
+    }
+    return { path: target };
+  }
+  async resolveBranch(explicit) {
+    if (explicit && explicit.length > 0) {
+      return explicit;
+    }
+    try {
+      return await this.gitService.getCurrentBranch();
+    } catch {
+      return "HEAD";
+    }
+  }
+  parsePositiveInt(value, name) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0 || String(parsed) !== value.trim()) {
+      throw new BBError({
+        code: 5002 /* VALIDATION_INVALID */,
+        message: this.appendHelpHint(`--${name} must be a positive integer.`),
+        context: { [name]: value }
+      });
+    }
+    return parsed;
+  }
+  async openInBrowser(url2) {
+    this.output.info(`Opening ${url2} in your browser...`);
+    const open2 = (await Promise.resolve().then(() => (init_open(), exports_open))).default;
+    await open2(url2);
+  }
+}
+
 // src/bootstrap.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -30288,6 +30750,7 @@ function bootstrap(options = {}) {
   });
   registerCommand(container, ServiceTokens.SnippetFilesService, SnippetFilesService, [ServiceTokens.SnippetsAxios]);
   registerCommand(container, ServiceTokens.DefaultReviewerService, DefaultReviewerService, [ServiceTokens.PullrequestsApi]);
+  container.register(ServiceTokens.UrlBuilderService, () => new UrlBuilderService);
   registerCommand(container, ServiceTokens.LoginCommand, LoginCommand, [
     ServiceTokens.CredentialStore,
     ServiceTokens.UsersApi,
@@ -30522,6 +30985,12 @@ function bootstrap(options = {}) {
     ServiceTokens.OutputService
   ]);
   registerCommand(container, ServiceTokens.ListConfigCommand, ListConfigCommand, [ServiceTokens.ConfigService, ServiceTokens.OutputService]);
+  registerCommand(container, ServiceTokens.BrowseCommand, BrowseCommand, [
+    ServiceTokens.ContextService,
+    ServiceTokens.GitService,
+    ServiceTokens.UrlBuilderService,
+    ServiceTokens.OutputService
+  ]);
   registerCommand(container, ServiceTokens.InstallCompletionCommand, InstallCompletionCommand, [ServiceTokens.OutputService]);
   registerCommand(container, ServiceTokens.UninstallCompletionCommand, UninstallCompletionCommand, [ServiceTokens.OutputService]);
   container.register(ServiceTokens.VersionService, () => {
@@ -30569,6 +31038,15 @@ function createHelpTextBuilder(noColor) {
         sections.push(`  ${c.bold(name.padEnd(maxLen + 2))}${c.dim(desc)}`);
       }
     }
+    if (config.seeAlso?.length) {
+      if (sections.length)
+        sections.push("");
+      sections.push(c.bold("See also:"));
+      const maxLen = Math.max(...config.seeAlso.map((e) => e.label.length));
+      for (const { label, url: url2 } of config.seeAlso) {
+        sections.push(`  ${c.bold(label.padEnd(maxLen + 2))}${c.cyan(url2)}`);
+      }
+    }
     return `
 ` + sections.join(`
 `) + `
@@ -30602,6 +31080,7 @@ var ROOT_COMPLETIONS = [
   "repo",
   "pr",
   "snippet",
+  "browse",
   "config",
   "completion",
   "--help",
@@ -30754,14 +31233,28 @@ function withGlobalOptions(options, context) {
   };
 }
 var cli = new Command;
-cli.name("bb").description("A command-line interface for Bitbucket Cloud").version(pkg2.version).option("--json [fields]", "Output as JSON; optionally project to a comma-separated field list (e.g. number,title,author.display_name)").option("--jq <expression>", "Filter the JSON output through a jq expression (requires --json)").option("--no-color", "Disable color output").option("-w, --workspace <workspace>", "Specify workspace").option("-r, --repo <repo>", "Specify repository").addHelpText("after", buildHelpText({
+cli.name("bb").description("A command-line interface for Bitbucket Cloud").version(pkg2.version).option("--json [fields]", "Output as JSON; optionally project to a comma-separated field list (e.g. number,title,author.display_name)").option("--jq <expression>", `Filter the JSON output through a jq expression \u2014 runs in-process via embedded jq, requires --json (e.g. '.pullRequests[] | select(.state == "OPEN") | .title')`).option("--no-color", "Disable color output").option("-w, --workspace <workspace>", "Specify workspace").option("-r, --repo <repo>", "Specify repository").addHelpText("after", buildHelpText({
   envVars: {
     BB_USERNAME: "Bitbucket username (fallback for auth login)",
     BB_API_TOKEN: "Bitbucket API token (fallback for auth login)",
     NO_COLOR: "Disable color output when set",
     FORCE_COLOR: "Force color output when set (and not '0')",
     DEBUG: "Enable HTTP debug logging when 'true'"
-  }
+  },
+  seeAlso: [
+    {
+      label: "Quick Start",
+      url: "https://bitbucket-cli.paulvanderlei.com/getting-started/quickstart/"
+    },
+    {
+      label: "Scripting",
+      url: "https://bitbucket-cli.paulvanderlei.com/guides/scripting/"
+    },
+    {
+      label: "Changelog",
+      url: "https://bitbucket-cli.paulvanderlei.com/help/changelog/"
+    }
+  ]
 })).action(async () => {
   cli.outputHelp();
   const versionService = container.resolve(ServiceTokens.VersionService);
@@ -30777,9 +31270,23 @@ cli.name("bb").description("A command-line interface for Bitbucket Cloud").versi
       output.text("\u2500".repeat(50));
     }
   } catch {}
+  try {
+    const configService = container.resolve(ServiceTokens.ConfigService);
+    const config = await configService.getConfig();
+    const hasBasicAuth = Boolean(config.username && config.apiToken);
+    const hasOAuth = Boolean(config.oauthAccessToken && config.oauthRefreshToken);
+    if (!hasBasicAuth && !hasOAuth) {
+      output.text("");
+      output.text(`Tip: Run '${output.highlight("bb auth login")}' to get started.`);
+    }
+  } catch {}
 });
 var authCmd = new Command("auth").description("Authenticate with Bitbucket");
-authCmd.command("login").description("Authenticate with Bitbucket (OAuth or API token)").option("-u, --username <username>", "Bitbucket username (implies API token auth)").option("-p, --password <password>", "Bitbucket API token (implies API token auth)").option("--app-password", "Use API token authentication instead of OAuth").option("--client-id <clientId>", "Custom OAuth consumer client ID").option("--client-secret <clientSecret>", "Custom OAuth consumer client secret").addHelpText("after", buildHelpText({
+authCmd.command("login").description("Authenticate with Bitbucket (OAuth or API token)").option("-u, --username <username>", "Bitbucket username (implies API token auth)").option("-p, --password <password>", "Bitbucket API token (implies API token auth)").option("--app-password", "Use API token authentication (instead of OAuth). App passwords are deprecated; use API tokens.").option("--client-id <clientId>", "Custom OAuth consumer client ID").option("--client-secret <clientSecret>", "Custom OAuth consumer client secret").addHelpText("before", `
+Default: OAuth (browser-based, recommended).
+` + `For CI/CD: API token via --app-password or BB_API_TOKEN env var.
+` + `Note: Bitbucket app passwords are deprecated; use OAuth or an API token.
+`).addHelpText("after", buildHelpText({
   examples: [
     "bb auth login",
     "bb auth login --app-password -u myuser -p mytoken",
@@ -30793,7 +31300,9 @@ authCmd.command("login").description("Authenticate with Bitbucket (OAuth or API
 })).action(async (options) => {
   await runCommand(ServiceTokens.LoginCommand, options, cli);
 });
-authCmd.command("logout").description("Log out of Bitbucket").addHelpText("after", buildHelpText({ examples: ["bb auth logout"] })).action(async () => {
+authCmd.command("logout").description("Log out of Bitbucket").addHelpText("after", buildHelpText({
+  examples: ["bb auth logout", "bb auth logout --json"]
+})).action(async () => {
   await runCommand(ServiceTokens.LogoutCommand, undefined, cli);
 });
 authCmd.command("status").description("Show authentication status").addHelpText("after", buildHelpText({
@@ -30901,12 +31410,22 @@ prCmd.command("create").description("Create a pull request").option("-t, --title
     source: "current git branch",
     destination: "main",
     "default-reviewers": "false (override with --default-reviewers or config key prCreateIncludeDefaultReviewers)"
-  }
+  },
+  seeAlso: [
+    {
+      label: "Repository Context",
+      url: "https://bitbucket-cli.paulvanderlei.com/guides/repository-context/"
+    },
+    {
+      label: "Default reviewers",
+      url: "https://bitbucket-cli.paulvanderlei.com/commands/repo/#bb-repo-default-reviewers"
+    }
+  ]
 })).action(async (options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.CreatePRCommand, withGlobalOptions(options, context), cli, context);
 });
-prCmd.command("list").description("List pull requests").option("-s, --state <state>", `Filter by state (${PR_STATES.join(", ")})`, "OPEN").option("--limit <number>", "Maximum number of PRs to list", "25").option("--mine", "Show only PRs where you are a reviewer").addHelpText("after", buildHelpText({
+prCmd.command("list").description("List pull requests").option("-s, --state <state>", `Filter by state (${PR_STATES.join(", ")})`, "OPEN").option("--limit <number>", "Maximum number of PRs to list", "25").option("--mine", "Show only PRs where you are a reviewer (not authored by you)").addHelpText("after", buildHelpText({
   examples: [
     "bb pr list",
     "bb pr list -s MERGED --limit 10",
@@ -30916,7 +31435,17 @@ prCmd.command("list").description("List pull requests").option("-s, --state <sta
   validValues: {
     "Valid states": [...PR_STATES]
   },
-  defaults: { state: "OPEN", limit: "25" }
+  defaults: { state: "OPEN", limit: "25" },
+  seeAlso: [
+    {
+      label: "Scripting & Automation",
+      url: "https://bitbucket-cli.paulvanderlei.com/guides/scripting/"
+    },
+    {
+      label: "JSON Output",
+      url: "https://bitbucket-cli.paulvanderlei.com/reference/json-output/"
+    }
+  ]
 })).action(async (options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListPRsCommand, withGlobalOptions(options, context), cli, context);
@@ -30981,24 +31510,50 @@ prCmd.command("merge <id>").description("Merge a pull request").option("-m, --me
       "rebase_fast_forward",
       "rebase_merge"
     ]
+  },
+  defaults: {
+    strategy: "the repository's configured merge strategy (typically merge_commit)"
   }
 })).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.MergePRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("approve <id>").description("Approve a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr approve 42"] })).action(async (id, options) => {
+prCmd.command("approve <id>").description("Approve a pull request").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr approve 42",
+    "bb pr approve 42 --json",
+    "bb pr approve 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ApprovePRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("decline <id>").description("Decline a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr decline 42"] })).action(async (id, options) => {
+prCmd.command("decline <id>").description("Decline a pull request").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr decline 42",
+    "bb pr decline 42 --json",
+    "bb pr decline 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeclinePRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("ready <id>").description("Mark a draft pull request as ready for review").addHelpText("after", buildHelpText({ examples: ["bb pr ready 42"] })).action(async (id, options) => {
+prCmd.command("ready <id>").description("Mark a draft pull request as ready for review").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr ready 42",
+    "bb pr ready 42 --json",
+    "bb pr ready 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ReadyPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("checkout <id>").description("Checkout a pull request locally").addHelpText("after", buildHelpText({ examples: ["bb pr checkout 42"] })).action(async (id, options) => {
+prCmd.command("checkout <id>").description("Checkout a pull request locally").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr checkout 42",
+    "bb pr checkout 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.CheckoutPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
@@ -31040,13 +31595,19 @@ prCommentsCmd.command("add <id> <message>").description("Add a comment to a pull
   await runCommand(ServiceTokens.CommentPRCommand, withGlobalOptions({ id, message, ...options }, context), cli, context);
 });
 prCommentsCmd.command("edit <pr-id> <comment-id> <message>").description("Edit a comment on a pull request").addHelpText("after", buildHelpText({
-  examples: ['bb pr comments edit 42 12345 "Updated comment"']
+  examples: [
+    'bb pr comments edit 42 12345 "Updated comment"',
+    'bb pr comments edit 42 12345 "Updated comment" --json'
+  ]
 })).action(async (prId, commentId, message, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.EditCommentPRCommand, withGlobalOptions({ prId, commentId, message }, context), cli, context);
 });
 prCommentsCmd.command("delete <pr-id> <comment-id>").description("Delete a comment on a pull request").option("-y, --yes", "Skip confirmation prompt").addHelpText("after", buildHelpText({
-  examples: ["bb pr comments delete 42 12345 --yes"]
+  examples: [
+    "bb pr comments delete 42 12345",
+    "bb pr comments delete 42 12345 --yes"
+  ]
 })).action(async (prId, commentId, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteCommentPRCommand, withGlobalOptions({ prId, commentId, ...options }, context), cli, context);
@@ -31058,13 +31619,23 @@ prReviewersCmd.command("list <id>").description("List reviewers on a pull reques
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListReviewersPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prReviewersCmd.command("add <id> <username>").description("Add a reviewer to a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr reviewers add 42 jdoe"] })).action(async (id, username, options) => {
+prReviewersCmd.command("add <id> <user>").description("Add a reviewer to a pull request (user is an account ID or {uuid})").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr reviewers add 42 "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"',
+    'bb pr reviewers add 42 "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"'
+  ]
+})).action(async (id, user, options) => {
   const context = createContext(cli);
-  await runCommand(ServiceTokens.AddReviewerPRCommand, withGlobalOptions({ id, username, ...options }, context), cli, context);
+  await runCommand(ServiceTokens.AddReviewerPRCommand, withGlobalOptions({ id, username: user, ...options }, context), cli, context);
 });
-prReviewersCmd.command("remove <id> <username>").description("Remove a reviewer from a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr reviewers remove 42 jdoe"] })).action(async (id, username, options) => {
+prReviewersCmd.command("remove <id> <user>").description("Remove a reviewer from a pull request (user is an account ID or {uuid})").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr reviewers remove 42 "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"',
+    'bb pr reviewers remove 42 "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"'
+  ]
+})).action(async (id, user, options) => {
   const context = createContext(cli);
-  await runCommand(ServiceTokens.RemoveReviewerPRCommand, withGlobalOptions({ id, username, ...options }, context), cli, context);
+  await runCommand(ServiceTokens.RemoveReviewerPRCommand, withGlobalOptions({ id, username: user, ...options }, context), cli, context);
 });
 cli.addCommand(prCmd);
 prCmd.addCommand(prCommentsCmd);
@@ -31095,7 +31666,7 @@ snippetCmd.command("view <id>").description("View snippet details").option("-f,
   const context = createContext(cli);
   await runCommand(ServiceTokens.ViewSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCmd.command("create").description("Create a new snippet").option("-t, --title <title>", "Snippet title").option("-f, --file <path...>", "File(s) to include").option("--private", "Create a private snippet (default)").option("--public", "Create a public snippet").addHelpText("after", buildHelpText({
+snippetCmd.command("create").description("Create a new snippet").option("-t, --title <title>", "Snippet title").option("-f, --file <path...>", "File(s) to include (variadic; pass multiple paths or repeat the flag)").option("--private", "Create a private snippet (default)").option("--public", "Create a public snippet").addHelpText("after", buildHelpText({
   examples: [
     'bb snippet create -t "My snippet" -f file.txt',
     'bb snippet create -t "Config files" -f config.yml -f setup.sh --public'
@@ -31105,7 +31676,7 @@ snippetCmd.command("create").description("Create a new snippet").option("-t, --t
   const context = createContext(cli);
   await runCommand(ServiceTokens.CreateSnippetCommand, withGlobalOptions(options, context), cli, context);
 });
-snippetCmd.command("edit <id>").description("Edit a snippet").option("-t, --title <title>", "New snippet title").option("--private", "Make snippet private").option("--public", "Make snippet public").option("-f, --file <path...>", "Replace/add file(s) (sends multipart update)").addHelpText("after", buildHelpText({
+snippetCmd.command("edit <id>").description("Edit a snippet").option("-t, --title <title>", "New snippet title").option("--private", "Make snippet private").option("--public", "Make snippet public").option("-f, --file <path...>", "Replace/add file(s) (variadic; pass multiple paths or repeat the flag; sends multipart update)").addHelpText("after", buildHelpText({
   examples: [
     'bb snippet edit kypj -t "New title"',
     "bb snippet edit kypj --public",
@@ -31121,11 +31692,18 @@ snippetCmd.command("delete <id>").description("Delete a snippet").option("-y, --
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCmd.command("watch <id>").description("Watch a snippet").addHelpText("after", buildHelpText({ examples: ["bb snippet watch kypj"] })).action(async (id, options) => {
+snippetCmd.command("watch <id>").description("Watch a snippet").addHelpText("after", buildHelpText({
+  examples: ["bb snippet watch kypj", "bb snippet watch kypj -w my-team"]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.WatchSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCmd.command("unwatch <id>").description("Stop watching a snippet").addHelpText("after", buildHelpText({ examples: ["bb snippet unwatch kypj"] })).action(async (id, options) => {
+snippetCmd.command("unwatch <id>").description("Stop watching a snippet").addHelpText("after", buildHelpText({
+  examples: [
+    "bb snippet unwatch kypj",
+    "bb snippet unwatch kypj -w my-team"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.UnwatchSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
@@ -31140,26 +31718,57 @@ snippetCommentsCmd.command("list <id>").description("List comments on a snippet"
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListSnippetCommentsCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCommentsCmd.command("add <id>").description("Add a comment to a snippet").option("-m, --message <text>", "Comment message").addHelpText("after", buildHelpText({
-  examples: ['bb snippet comments add kypj -m "Great snippet!"']
-})).action(async (id, options) => {
+snippetCommentsCmd.command("add <id> [message]").description("Add a comment to a snippet (message is required)").option("-m, --message <text>", "Comment message (alternative to the positional [message] argument; one of the two is required)").addHelpText("after", buildHelpText({
+  examples: [
+    'bb snippet comments add kypj "Great snippet!"',
+    'bb snippet comments add kypj -m "Great snippet!"',
+    'bb snippet comments add kypj "Great snippet!" --json'
+  ]
+})).action(async (id, message, options) => {
   const context = createContext(cli);
-  await runCommand(ServiceTokens.AddSnippetCommentCommand, withGlobalOptions({ id, ...options }, context), cli, context);
+  const resolvedMessage = message ?? options.message;
+  await runCommand(ServiceTokens.AddSnippetCommentCommand, withGlobalOptions({ id, ...options, message: resolvedMessage }, context), cli, context);
 });
 snippetCommentsCmd.command("edit <snippet-id> <comment-id> <message>").description("Edit a comment on a snippet").addHelpText("after", buildHelpText({
-  examples: ['bb snippet comments edit kypj 123 "Updated comment"']
+  examples: [
+    'bb snippet comments edit kypj 123 "Updated comment"',
+    'bb snippet comments edit kypj 123 "Updated comment" --json'
+  ]
 })).action(async (snippetId, commentId, message, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.EditSnippetCommentCommand, withGlobalOptions({ snippetId, commentId, message }, context), cli, context);
 });
 snippetCommentsCmd.command("delete <snippet-id> <comment-id>").description("Delete a comment on a snippet").option("-y, --yes", "Skip confirmation prompt").addHelpText("after", buildHelpText({
-  examples: ["bb snippet comments delete kypj 123 --yes"]
+  examples: [
+    "bb snippet comments delete kypj 123",
+    "bb snippet comments delete kypj 123 --yes"
+  ]
 })).action(async (snippetId, commentId, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteSnippetCommentCommand, withGlobalOptions({ snippetId, commentId, ...options }, context), cli, context);
 });
 snippetCmd.addCommand(snippetCommentsCmd);
 cli.addCommand(snippetCmd);
+cli.command("browse [target]").description("Open a Bitbucket page (repo home, file, PR, commit, etc.) in your browser").option("--pr <id>", "Open a specific pull request").option("--prs", "Open the pull-requests list").option("--pull-requests", "Alias for --prs").option("--branch <name>", "Open the branch source tree (or, with <target>, that path on the branch)").option("--branches", "Open the branches list").option("--commit [sha]", "Open a specific commit (defaults to HEAD when no SHA is given)").option("--commits", "Open the commits list").option("--pipelines", "Open the pipelines page").option("--pipeline <id>", "Open a specific pipeline run").option("--downloads", "Open the downloads page").option("--issue <id>", "Open a specific issue").option("--issues", "Open the issue tracker").option("--wiki", "Open the wiki").option("--settings", "Open repository settings").option("-n, --no-browser", "Print the URL to stdout instead of opening it").addHelpText("after", buildHelpText({
+  examples: [
+    "bb browse",
+    "bb browse src/cli.ts",
+    "bb browse src/cli.ts:42",
+    "bb browse --branch release/2.0 src/cli.ts",
+    "bb browse 217",
+    "bb browse --pr 217",
+    "bb browse --prs",
+    "bb browse abc1234",
+    "bb browse --commit",
+    "bb browse --pipelines",
+    "bb browse --settings",
+    "bb browse --pr 217 --no-browser",
+    "bb browse --pr 217 --json url"
+  ]
+})).action(async (target, options) => {
+  const context = createContext(cli);
+  await runCommand(ServiceTokens.BrowseCommand, withGlobalOptions({ target, ...options }, context), cli, context);
+});
 var configCmd = new Command("config").description("Manage configuration");
 configCmd.command("get <key>").description("Get a configuration value").addHelpText("after", buildHelpText({
   examples: ["bb config get defaultWorkspace"],
@@ -31168,7 +31777,8 @@ configCmd.command("get <key>").description("Get a configuration value").addHelpT
       "username",
       "defaultWorkspace",
       "skipVersionCheck",
-      "versionCheckInterval"
+      "versionCheckInterval",
+      "prCreateIncludeDefaultReviewers"
     ]
   }
 })).action(async (key) => {
@@ -31184,9 +31794,16 @@ configCmd.command("set <key> <value>").description("Set a configuration value").
     "Settable config keys": [
       "defaultWorkspace (string)",
       "skipVersionCheck (true/false)",
-      "versionCheckInterval (positive integer, seconds)"
+      "versionCheckInterval (positive integer, seconds)",
+      "prCreateIncludeDefaultReviewers (true/false)"
     ]
-  }
+  },
+  seeAlso: [
+    {
+      label: "Configuration File",
+      url: "https://bitbucket-cli.paulvanderlei.com/reference/configuration/"
+    }
+  ]
 })).action(async (key, value) => {
   await runCommand(ServiceTokens.SetConfigCommand, { key, value }, cli);
 });
@@ -31197,10 +31814,20 @@ configCmd.command("list").description("List all configuration values").addHelpTe
 });
 cli.addCommand(configCmd);
 var completionCmd = new Command("completion").description("Shell completion utilities");
-completionCmd.command("install").description("Install shell completions for bash, zsh, or fish").addHelpText("after", buildHelpText({ examples: ["bb completion install"] })).action(async () => {
+completionCmd.command("install").description("Install shell completions for bash, zsh, or fish").addHelpText("after", buildHelpText({
+  examples: ["bb completion install", "bb completion install --json"],
+  validValues: {
+    "Supported shells": ["bash", "zsh", "fish"]
+  }
+})).action(async () => {
   await runCommand(ServiceTokens.InstallCompletionCommand, undefined, cli);
 });
-completionCmd.command("uninstall").description("Uninstall shell completions").addHelpText("after", buildHelpText({ examples: ["bb completion uninstall"] })).action(async () => {
+completionCmd.command("uninstall").description("Uninstall shell completions").addHelpText("after", buildHelpText({
+  examples: ["bb completion uninstall", "bb completion uninstall --json"],
+  validValues: {
+    "Supported shells": ["bash", "zsh", "fish"]
+  }
+})).action(async () => {
   await runCommand(ServiceTokens.UninstallCompletionCommand, undefined, cli);
 });
 cli.addCommand(completionCmd);