@pilatos/bitbucket-cli 1.8.2 → 1.8.4

package/dist/index.js

@@ -14337,6 +14337,12 @@ var applyOptions = (object, options = {}) => {
   const colorLevel = stdoutColor ? stdoutColor.level : 0;
   object.level = options.level === undefined ? colorLevel : options.level;
 };
+
+class Chalk {
+  constructor(options) {
+    return chalkFactory(options);
+  }
+}
 var chalkFactory = (options) => {
   const chalk = (...strings) => strings.join(" ");
   applyOptions(chalk, options);
@@ -21341,6 +21347,288 @@ class CloneCommand extends BaseCommand {
   }
 }
 
+// src/services/response-parsers.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function getString(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function getNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function getIterable(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (typeof value !== "object" || value === null) {
+    return;
+  }
+  const iterableCandidate = value;
+  const iterator2 = iterableCandidate[Symbol.iterator];
+  return typeof iterator2 === "function" ? value : undefined;
+}
+function getValuesIterable(data) {
+  if (isRecord(data) && "values" in data) {
+    return getIterable(data.values);
+  }
+  return getIterable(data);
+}
+function mapPaginatedValues(data, mapValue) {
+  const iterableValues = getValuesIterable(data);
+  const values = [];
+  if (iterableValues) {
+    for (const value of iterableValues) {
+      const mappedValue = mapValue(value);
+      if (mappedValue !== undefined) {
+        values.push(mappedValue);
+      }
+    }
+  }
+  const next = isRecord(data) ? getString(data.next) : undefined;
+  return {
+    values,
+    next
+  };
+}
+function getCommitFilePath(file) {
+  if (!isRecord(file)) {
+    return;
+  }
+  const path = file.path;
+  return typeof path === "string" && path.length > 0 ? path : undefined;
+}
+function parseDiffstatFile(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  return {
+    path: getCommitFilePath(value.new) ?? getCommitFilePath(value.old) ?? "unknown",
+    additions: getNumber(value.lines_added) ?? 0,
+    deletions: getNumber(value.lines_removed) ?? 0
+  };
+}
+function parseActivityUser(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const displayName = getString(value.display_name);
+  const username = getString(value.username);
+  const nickname = getString(value.nickname);
+  if (!displayName && !username && !nickname) {
+    return;
+  }
+  return {
+    display_name: displayName,
+    username,
+    nickname
+  };
+}
+function parseActivityHash(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const hash = getString(value.hash);
+  return hash ? { hash } : undefined;
+}
+function parseActivityComment(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const id = getNumber(value.id);
+  const raw = getRawContent(value.content);
+  const user = parseActivityUser(value.user);
+  const author = parseActivityUser(value.author);
+  const createdOn = getString(value.created_on);
+  if (id === undefined && raw === undefined && !user && !author && !createdOn) {
+    return;
+  }
+  return {
+    id,
+    content: raw === undefined ? undefined : { raw },
+    user,
+    author,
+    created_on: createdOn
+  };
+}
+function parseApproval(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const user = parseActivityUser(value.user);
+  const date = getString(value.date);
+  if (!user && !date) {
+    return;
+  }
+  return { user, date };
+}
+function parseChangesRequested(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const user = parseActivityUser(value.user);
+  const reason = getString(value.reason);
+  const date = getString(value.date);
+  if (!user && !reason && !date) {
+    return;
+  }
+  return {
+    user,
+    reason,
+    date
+  };
+}
+function parseMerge(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const user = parseActivityUser(value.user);
+  const date = getString(value.date);
+  const commit = parseActivityHash(value.commit);
+  if (!user && !date && !commit) {
+    return;
+  }
+  return {
+    user,
+    date,
+    commit
+  };
+}
+function parseDecline(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const user = parseActivityUser(value.user);
+  const date = getString(value.date);
+  if (!user && !date) {
+    return;
+  }
+  return { user, date };
+}
+function parseCommit(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const date = getString(value.date);
+  const hash = getString(value.hash);
+  const author = isRecord(value.author) ? {
+    user: parseActivityUser(value.author.user)
+  } : undefined;
+  if (!date && !hash && !author?.user) {
+    return;
+  }
+  return {
+    date,
+    hash,
+    author
+  };
+}
+function parseUpdate(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const author = parseActivityUser(value.author);
+  const date = getString(value.date);
+  const title = getString(value.title);
+  const description = getString(value.description);
+  const state = getString(value.state);
+  if (!author && !date && !title && !description && !state) {
+    return;
+  }
+  return {
+    author,
+    date,
+    title,
+    description,
+    state
+  };
+}
+function parseActivity(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  return {
+    type: getString(value.type),
+    comment: parseActivityComment(value.comment),
+    approval: parseApproval(value.approval),
+    changes_requested: parseChangesRequested(value.changes_requested),
+    merge: parseMerge(value.merge),
+    decline: parseDecline(value.decline),
+    commit: parseCommit(value.commit),
+    update: parseUpdate(value.update),
+    user: parseActivityUser(value.user)
+  };
+}
+function getLinkHref(links, key) {
+  if (!isRecord(links)) {
+    return;
+  }
+  const link = links[key];
+  if (!isRecord(link)) {
+    return;
+  }
+  return getString(link.href);
+}
+function getCloneLinks(links) {
+  if (!isRecord(links)) {
+    return [];
+  }
+  const cloneLinks = getIterable(links.clone);
+  if (!cloneLinks) {
+    return [];
+  }
+  const parsedLinks = [];
+  for (const cloneLink of cloneLinks) {
+    if (!isRecord(cloneLink)) {
+      continue;
+    }
+    const name = getString(cloneLink.name);
+    const href = getString(cloneLink.href);
+    if (name && href) {
+      parsedLinks.push({ name, href });
+    }
+  }
+  return parsedLinks;
+}
+function getBranchName(endpoint) {
+  if (!isRecord(endpoint)) {
+    return;
+  }
+  const branch = endpoint.branch;
+  if (!isRecord(branch)) {
+    return;
+  }
+  const name = branch.name;
+  return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+function getUserDisplayName(user) {
+  if (!isRecord(user)) {
+    return;
+  }
+  const nickname = getString(user.nickname);
+  if (nickname && nickname.length > 0) {
+    return nickname;
+  }
+  const displayName = getString(user.display_name);
+  if (displayName && displayName.length > 0) {
+    return displayName;
+  }
+  const username = getString(user.username);
+  return username && username.length > 0 ? username : undefined;
+}
+function getRawContent(content) {
+  if (!isRecord(content)) {
+    return;
+  }
+  return getString(content.raw);
+}
+function parseDiffstatFiles(data) {
+  return Array.from(mapPaginatedValues(data, parseDiffstatFile).values ?? []);
+}
+function parsePullrequestActivitiesPage(data) {
+  return mapPaginatedValues(data, parseActivity);
+}
+
 // src/commands/repo/create.command.ts
 class CreateRepoCommand extends BaseCommand {
   repositoriesApi;
@@ -21379,8 +21667,9 @@ class CreateRepoCommand extends BaseCommand {
       return;
     }
     this.output.success(`Created repository ${repo.full_name}`);
-    this.output.text(`  ${this.output.dim("URL:")} ${repo.links?.html?.href}`);
-    const sshClone = Array.from(repo.links?.clone ?? []).find((c) => c.name === "ssh");
+    const repoUrl = getLinkHref(repo.links, "html") ?? "";
+    this.output.text(`  ${this.output.dim("URL:")} ${repoUrl}`);
+    const sshClone = getCloneLinks(repo.links).find((cloneLink) => cloneLink.name === "ssh");
     if (sshClone?.href) {
       this.output.text(`  ${this.output.dim("Clone:")} git clone ${sshClone.href}`);
     }
@@ -21553,8 +21842,9 @@ class ViewRepoCommand extends BaseCommand {
     this.output.text(`  ${this.output.dim("Created:")} ${this.output.formatDate(repo.created_on ?? "")}`);
     this.output.text(`  ${this.output.dim("Updated:")} ${this.output.formatDate(repo.updated_on ?? "")}`);
     this.output.text("");
-    this.output.text(`  ${this.output.dim("URL:")} ${repo.links?.html?.href}`);
-    const sshClone = Array.from(repo.links?.clone ?? []).find((c) => c.name === "ssh");
+    const repoUrl = getLinkHref(repo.links, "html") ?? "";
+    this.output.text(`  ${this.output.dim("URL:")} ${repoUrl}`);
+    const sshClone = getCloneLinks(repo.links).find((cloneLink) => cloneLink.name === "ssh");
     if (sshClone?.href) {
       this.output.text(`  ${this.output.dim("SSH:")} ${sshClone.href}`);
     }
@@ -22143,7 +22433,7 @@ class CheckoutPRCommand extends BaseCommand {
       pullRequestId: prId
     });
     const pr = prResponse.data;
-    const branchName = pr.source?.branch?.name;
+    const branchName = getBranchName(pr.source);
     const localBranchName = `pr-${prId}`;
     if (!branchName) {
       throw new BBError({
@@ -22233,8 +22523,7 @@ class DiffPRCommand extends BaseCommand {
           return response.data;
         },
         shouldInclude: (pullRequest) => {
-          const source = pullRequest.source;
-          return source?.branch?.name === currentBranch;
+          return getBranchName(pullRequest.source) === currentBranch;
         }
       });
       const pr = matches[0];
@@ -22318,8 +22607,7 @@ class DiffPRCommand extends BaseCommand {
       repoSlug,
       pullRequestId: prId
     });
-    const links = prResponse.data.links;
-    const htmlUrl = links?.html?.href;
+    const htmlUrl = getLinkHref(prResponse.data.links, "html");
     if (htmlUrl) {
       const normalizedHtmlUrl = htmlUrl.replace(/\/$/, "");
       return `${normalizedHtmlUrl}/diff`;
@@ -22332,15 +22620,7 @@ class DiffPRCommand extends BaseCommand {
       repoSlug,
       pullRequestId: prId
     });
-    const diffstat = diffstatResponse.data;
-    const files = Array.from(diffstat.values ?? []).map((file) => {
-      const path = file.new?.path || file.old?.path || "unknown";
-      return {
-        path,
-        additions: file.lines_added ?? 0,
-        deletions: file.lines_removed ?? 0
-      };
-    });
+    const files = parseDiffstatFiles(diffstatResponse.data);
     const totalAdditions = files.reduce((sum, f) => sum + f.additions, 0);
     const totalDeletions = files.reduce((sum, f) => sum + f.deletions, 0);
     const filesChanged = files.length;
@@ -22378,8 +22658,7 @@ class DiffPRCommand extends BaseCommand {
       repoSlug,
       pullRequestId: prId
     });
-    const diffstat = diffstatResponse.data;
-    const fileNames = Array.from(diffstat.values ?? []).map((file) => file.new?.path || file.old?.path || "unknown");
+    const fileNames = parseDiffstatFiles(diffstatResponse.data).map((file) => file.path);
     if (useJson) {
       return fileNames;
     }
@@ -22459,7 +22738,7 @@ class ActivityPRCommand extends BaseCommand {
         }, {
           params: { page, pagelen }
         });
-        return response.data;
+        return parsePullrequestActivitiesPage(response.data);
       },
       shouldInclude: (activity) => {
         if (filterTypes.length === 0) {
@@ -22468,7 +22747,6 @@ class ActivityPRCommand extends BaseCommand {
         return filterTypes.includes(this.getActivityType(activity));
       }
     });
-    const typedActivities = activities;
     if (context.globalOptions.json) {
       this.output.json({
         workspace: repoContext.workspace,
@@ -22477,12 +22755,12 @@ class ActivityPRCommand extends BaseCommand {
         filters: {
           types: filterTypes
         },
-        count: typedActivities.length,
-        activities: typedActivities
+        count: activities.length,
+        activities
       });
       return;
     }
-    if (typedActivities.length === 0) {
+    if (activities.length === 0) {
       if (filterTypes.length > 0) {
         this.output.info("No activity entries matched the requested filter");
       } else {
@@ -22490,7 +22768,7 @@ class ActivityPRCommand extends BaseCommand {
       }
       return;
     }
-    const rows = typedActivities.map((activity) => {
+    const rows = activities.map((activity) => {
       const activityType = this.getActivityType(activity);
       return [
         activityType.toUpperCase(),
@@ -22533,10 +22811,7 @@ class ActivityPRCommand extends BaseCommand {
   }
   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;
-    if (!user) {
-      return "Unknown";
-    }
-    return user.display_name || user.username || "Unknown";
+    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;
@@ -22548,7 +22823,7 @@ class ActivityPRCommand extends BaseCommand {
   buildActivityDetails(activity, type) {
     switch (type) {
       case "comment": {
-        const content = activity.comment?.content?.raw ?? "";
+        const content = getRawContent(activity.comment?.content) ?? "";
         const id = activity.comment?.id ? `#${activity.comment.id}` : "";
         const snippet = this.truncate(content, 80);
         return [id, snippet].filter(Boolean).join(" ");
@@ -22728,10 +23003,10 @@ class ListCommentsPRCommand extends BaseCommand {
       return;
     }
     const rows = values.map((comment) => {
-      const content = comment.content?.raw ?? "";
+      const content = getRawContent(comment.content) ?? "";
       return [
         comment.id?.toString() ?? "",
-        comment.user?.nickname ?? comment.user?.display_name ?? "Unknown",
+        getUserDisplayName(comment.user) ?? "Unknown",
         comment.deleted ? "[deleted]" : options.truncate === false ? content : content.slice(0, 60) + (content.length > 60 ? "..." : ""),
         this.output.formatDate(comment.created_on ?? "")
       ];
@@ -23539,6 +23814,51 @@ function bootstrap(options = {}) {
   return container;
 }
 
+// src/help-text.ts
+function createHelpTextBuilder(noColor) {
+  const passthrough = (t) => t;
+  const chalk2 = new Chalk({ level: noColor ? 0 : 1 });
+  const c = noColor ? { bold: passthrough, dim: passthrough, cyan: passthrough } : { bold: chalk2.bold, dim: chalk2.dim, cyan: chalk2.cyan };
+  return function buildHelpText(config) {
+    const sections = [];
+    if (config.examples?.length) {
+      sections.push(c.bold("Examples:"));
+      for (const example of config.examples) {
+        sections.push(`  ${c.dim("$")} ${example}`);
+      }
+    }
+    if (config.validValues) {
+      for (const [label, values] of Object.entries(config.validValues)) {
+        if (sections.length)
+          sections.push("");
+        sections.push(c.bold(`${label}:`));
+        sections.push(`  ${c.cyan(values.join(", "))}`);
+      }
+    }
+    if (config.defaults) {
+      if (sections.length)
+        sections.push("");
+      sections.push(c.bold("Defaults:"));
+      for (const [key, value] of Object.entries(config.defaults)) {
+        sections.push(`  ${c.bold(`--${key}`)}  ${c.cyan(value)}`);
+      }
+    }
+    if (config.envVars) {
+      if (sections.length)
+        sections.push("");
+      sections.push(c.bold("Environment variables:"));
+      const maxLen = Math.max(...Object.keys(config.envVars).map((k) => k.length));
+      for (const [name, desc] of Object.entries(config.envVars)) {
+        sections.push(`  ${c.bold(name.padEnd(maxLen + 2))}${c.dim(desc)}`);
+      }
+    }
+    return `
+` + sections.join(`
+`) + `
+`;
+  };
+}
+
 // src/cli.ts
 import tabtab3 from "tabtab";
 var require3 = createRequire2(import.meta.url);
@@ -23593,6 +23913,7 @@ function resolveNoColorSetting(argv, env2) {
   return hasNoColorEnv;
 }
 var noColor = resolveNoColorSetting(process.argv, process.env);
+var buildHelpText = createHelpTextBuilder(noColor);
 var container = bootstrap({ noColor });
 function createContext(program2) {
   const opts = program2.opts();
@@ -23622,7 +23943,15 @@ function withGlobalOptions(options, context) {
   };
 }
 var cli = new Command;
-cli.name("bb").description("A command-line interface for Bitbucket Cloud").version(pkg2.version).option("--json", "Output as JSON").option("--no-color", "Disable color output").option("-w, --workspace <workspace>", "Specify workspace").option("-r, --repo <repo>", "Specify repository").action(async () => {
+cli.name("bb").description("A command-line interface for Bitbucket Cloud").version(pkg2.version).option("--json", "Output as JSON").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'"
+  }
+})).action(async () => {
   cli.outputHelp();
   const versionService = container.resolve(ServiceTokens.VersionService);
   const output = container.resolve(ServiceTokens.OutputService);
@@ -23639,116 +23968,255 @@ cli.name("bb").description("A command-line interface for Bitbucket Cloud").versi
   } catch {}
 });
 var authCmd = new Command("auth").description("Authenticate with Bitbucket");
-authCmd.command("login").description("Authenticate with Bitbucket using an API token").option("-u, --username <username>", "Bitbucket username").option("-p, --password <password>", "Bitbucket API token").action(async (options) => {
+authCmd.command("login").description("Authenticate with Bitbucket using an API token").option("-u, --username <username>", "Bitbucket username").option("-p, --password <password>", "Bitbucket API token").addHelpText("after", buildHelpText({
+  examples: [
+    "bb auth login -u myuser -p mytoken",
+    "BB_USERNAME=myuser BB_API_TOKEN=mytoken bb auth login"
+  ],
+  envVars: {
+    BB_USERNAME: "Used when --username is not provided",
+    BB_API_TOKEN: "Used when --password is not provided"
+  }
+})).action(async (options) => {
   await runCommand(ServiceTokens.LoginCommand, options, cli);
 });
-authCmd.command("logout").description("Log out of Bitbucket").action(async () => {
+authCmd.command("logout").description("Log out of Bitbucket").addHelpText("after", buildHelpText({ examples: ["bb auth logout"] })).action(async () => {
   await runCommand(ServiceTokens.LogoutCommand, undefined, cli);
 });
-authCmd.command("status").description("Show authentication status").action(async () => {
+authCmd.command("status").description("Show authentication status").addHelpText("after", buildHelpText({
+  examples: ["bb auth status", "bb auth status --json"]
+})).action(async () => {
   await runCommand(ServiceTokens.StatusCommand, undefined, cli);
 });
-authCmd.command("token").description("Print the current access token").action(async () => {
+authCmd.command("token").description("Print the current access token").addHelpText("after", buildHelpText({
+  examples: ["bb auth token", "bb auth token | pbcopy"]
+})).action(async () => {
   await runCommand(ServiceTokens.TokenCommand, undefined, cli);
 });
 cli.addCommand(authCmd);
 var repoCmd = new Command("repo").description("Manage repositories");
-repoCmd.command("clone <repository>").description("Clone a Bitbucket repository").option("-d, --directory <dir>", "Directory to clone into").action(async (repository, options) => {
+repoCmd.command("clone <repository>").description("Clone a Bitbucket repository").option("-d, --directory <dir>", "Directory to clone into").addHelpText("after", buildHelpText({
+  examples: [
+    "bb repo clone workspace/repo-name",
+    "bb repo clone workspace/repo-name -d my-directory"
+  ]
+})).action(async (repository, options) => {
   await runCommand(ServiceTokens.CloneCommand, { repository, ...options }, cli);
 });
-repoCmd.command("create <name>").description("Create a new repository").option("-d, --description <description>", "Repository description").option("--private", "Create a private repository (default)").option("--public", "Create a public repository").option("-p, --project <project>", "Project key").action(async (name, options) => {
+repoCmd.command("create <name>").description("Create a new repository").option("-d, --description <description>", "Repository description").option("--private", "Create a private repository (default)").option("--public", "Create a public repository").option("-p, --project <project>", "Project key").addHelpText("after", buildHelpText({
+  examples: [
+    "bb repo create my-repo",
+    "bb repo create my-repo --public -p PROJ",
+    'bb repo create my-repo -d "My new repository"'
+  ],
+  defaults: { private: "true (visibility is private unless --public)" }
+})).action(async (name, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.CreateRepoCommand, withGlobalOptions({ name, ...options }, context), cli, context);
 });
-repoCmd.command("list").description("List repositories").option("--limit <number>", "Maximum number of repositories to list", "25").action(async (options) => {
+repoCmd.command("list").description("List repositories").option("--limit <number>", "Maximum number of repositories to list", "25").addHelpText("after", buildHelpText({
+  examples: [
+    "bb repo list",
+    "bb repo list --limit 50",
+    "bb repo list --json"
+  ],
+  defaults: { limit: "25" }
+})).action(async (options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListReposCommand, withGlobalOptions(options, context), cli, context);
 });
-repoCmd.command("view [repository]").description("View repository details").action(async (repository, options) => {
+repoCmd.command("view [repository]").description("View repository details").addHelpText("after", buildHelpText({
+  examples: [
+    "bb repo view",
+    "bb repo view workspace/repo-name",
+    "bb repo view workspace/repo-name --json"
+  ]
+})).action(async (repository, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ViewRepoCommand, withGlobalOptions({ repository, ...options }, context), cli, context);
 });
-repoCmd.command("delete <repository>").description("Delete a repository").option("-y, --yes", "Skip confirmation prompt").action(async (repository, options) => {
+repoCmd.command("delete <repository>").description("Delete a repository").option("-y, --yes", "Skip confirmation prompt").addHelpText("after", buildHelpText({
+  examples: [
+    "bb repo delete workspace/repo-name",
+    "bb repo delete workspace/repo-name --yes"
+  ]
+})).action(async (repository, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteRepoCommand, withGlobalOptions({ repository, ...options }, context), cli, context);
 });
 cli.addCommand(repoCmd);
 var prCmd = new Command("pr").description("Manage pull requests");
-prCmd.command("create").description("Create a pull request").option("-t, --title <title>", "Pull request title").option("-b, --body <body>", "Pull request description").option("-s, --source <branch>", "Source branch (default: current branch)").option("-d, --destination <branch>", "Destination branch (default: main)").option("--close-source-branch", "Close source branch after merge").option("--draft", "Create the pull request as draft").action(async (options) => {
+prCmd.command("create").description("Create a pull request").option("-t, --title <title>", "Pull request title").option("-b, --body <body>", "Pull request description").option("-s, --source <branch>", "Source branch (default: current branch)").option("-d, --destination <branch>", "Destination branch (default: main)").option("--close-source-branch", "Close source branch after merge").option("--draft", "Create the pull request as draft").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr create -t "My PR" -b "Description"',
+    'bb pr create -t "My PR" --draft',
+    'bb pr create -t "My PR" -s feature -d develop',
+    'bb pr create -t "My PR" --close-source-branch'
+  ],
+  defaults: {
+    source: "current git branch",
+    destination: "main"
+  }
+})).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 (OPEN, MERGED, DECLINED, SUPERSEDED)", "OPEN").option("--limit <number>", "Maximum number of PRs to list", "25").action(async (options) => {
+prCmd.command("list").description("List pull requests").option("-s, --state <state>", "Filter by state (OPEN, MERGED, DECLINED, SUPERSEDED)", "OPEN").option("--limit <number>", "Maximum number of PRs to list", "25").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr list",
+    "bb pr list -s MERGED --limit 10",
+    "bb pr list --json"
+  ],
+  validValues: {
+    "Valid states": ["OPEN", "MERGED", "DECLINED", "SUPERSEDED"]
+  },
+  defaults: { state: "OPEN", limit: "25" }
+})).action(async (options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListPRsCommand, withGlobalOptions(options, context), cli, context);
 });
-prCmd.command("view <id>").description("View pull request details").action(async (id, options) => {
+prCmd.command("view <id>").description("View pull request details").addHelpText("after", buildHelpText({
+  examples: ["bb pr view 42", "bb pr view 42 --json"]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ViewPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("activity <id>").description("Show pull request activity log").option("--limit <number>", "Maximum number of activity entries", "25").option("--type <types>", "Filter activity by type (comma-separated)").action(async (id, options) => {
+prCmd.command("activity <id>").description("Show pull request activity log").option("--limit <number>", "Maximum number of activity entries", "25").option("--type <types>", "Filter activity by type (comma-separated)").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr activity 42",
+    "bb pr activity 42 --type comment,approval",
+    "bb pr activity 42 --limit 10 --json"
+  ],
+  validValues: {
+    "Valid activity types (comma-separated)": [
+      "comment",
+      "approval",
+      "changes_requested",
+      "merge",
+      "decline",
+      "commit",
+      "update"
+    ]
+  },
+  defaults: { limit: "25" }
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ActivityPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("checks <id>").description("Show CI/CD checks and build status for a pull request").option("--json", "Output as JSON").action(async (id, options) => {
+prCmd.command("checks <id>").description("Show CI/CD checks and build status for a pull request").option("--json", "Output as JSON").addHelpText("after", buildHelpText({
+  examples: ["bb pr checks 42", "bb pr checks 42 --json"]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ChecksPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("edit [id]").description("Edit a pull request").option("-t, --title <title>", "New pull request title").option("-b, --body <body>", "New pull request description").option("-F, --body-file <file>", "Read description from file").action(async (id, options) => {
+prCmd.command("edit [id]").description("Edit a pull request").option("-t, --title <title>", "New pull request title").option("-b, --body <body>", "New pull request description").option("-F, --body-file <file>", "Read description from file").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr edit 42 -t "New title"',
+    'bb pr edit 42 -b "Updated description"',
+    "bb pr edit 42 -F description.md",
+    "bb pr edit"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.EditPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("merge <id>").description("Merge a pull request").option("-m, --message <message>", "Merge commit message").option("--close-source-branch", "Delete the source branch after merging").option("--strategy <strategy>", "Merge strategy (merge_commit, squash, fast_forward)").action(async (id, options) => {
+prCmd.command("merge <id>").description("Merge a pull request").option("-m, --message <message>", "Merge commit message").option("--close-source-branch", "Delete the source branch after merging").option("--strategy <strategy>", "Merge strategy").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr merge 42",
+    "bb pr merge 42 --strategy squash --close-source-branch",
+    'bb pr merge 42 -m "Merge feature X"'
+  ],
+  validValues: {
+    "Valid merge strategies": [
+      "merge_commit",
+      "squash",
+      "fast_forward",
+      "squash_fast_forward",
+      "rebase_fast_forward",
+      "rebase_merge"
+    ]
+  }
+})).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").action(async (id, options) => {
+prCmd.command("approve <id>").description("Approve a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr approve 42"] })).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").action(async (id, options) => {
+prCmd.command("decline <id>").description("Decline a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr decline 42"] })).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").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"] })).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").action(async (id, options) => {
+prCmd.command("checkout <id>").description("Checkout a pull request locally").addHelpText("after", buildHelpText({ examples: ["bb pr checkout 42"] })).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.CheckoutPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("diff [id]").description("View pull request diff").option("--color <when>", "Colorize output (auto, always, never)", "auto").option("--name-only", "Show only names of changed files").option("--stat", "Show diffstat").option("--web", "Open diff in web browser").action(async (id, options) => {
+prCmd.command("diff [id]").description("View pull request diff").option("--color <when>", "Colorize output", "auto").option("--name-only", "Show only names of changed files").option("--stat", "Show diffstat").option("--web", "Open diff in web browser").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr diff 42",
+    "bb pr diff 42 --stat",
+    "bb pr diff 42 --name-only",
+    "bb pr diff --web",
+    "bb pr diff 42 --color always"
+  ],
+  validValues: {
+    "Valid --color values": ["auto", "always", "never"]
+  },
+  defaults: { color: "auto" }
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DiffPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
 var prCommentsCmd = new Command("comments").description("Manage pull request comments");
-prCommentsCmd.command("list <id>").description("List comments on a pull request").option("--limit <number>", "Maximum number of comments (default: 25)").option("--no-truncate", "Show full comment content without truncation").action(async (id, options) => {
+prCommentsCmd.command("list <id>").description("List comments on a pull request").option("--limit <number>", "Maximum number of comments (default: 25)").option("--no-truncate", "Show full comment content without truncation").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr comments list 42",
+    "bb pr comments list 42 --no-truncate",
+    "bb pr comments list 42 --limit 50 --json"
+  ],
+  defaults: { limit: "25" }
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListCommentsPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCommentsCmd.command("add <id> <message>").description("Add a comment to a pull request").option("--file <path>", "File path in the diff for inline comment").option("--line-to <number>", "Line number in the new file version").option("--line-from <number>", "Line number in the old file version").action(async (id, message, options) => {
+prCommentsCmd.command("add <id> <message>").description("Add a comment to a pull request").option("--file <path>", "File path in the diff for inline comment").option("--line-to <number>", "Line number in the new file version").option("--line-from <number>", "Line number in the old file version").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr comments add 42 "LGTM"',
+    'bb pr comments add 42 "Fix this" --file src/main.ts --line-to 10'
+  ]
+})).action(async (id, message, options) => {
   const context = createContext(cli);
   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").action(async (prId, commentId, message, options) => {
+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"']
+})).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").action(async (prId, commentId, options) => {
+prCommentsCmd.command("delete <pr-id> <comment-id>").description("Delete a comment on a pull request").addHelpText("after", buildHelpText({
+  examples: ["bb pr comments delete 42 12345"]
+})).action(async (prId, commentId, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteCommentPRCommand, withGlobalOptions({ prId, commentId }, context), cli, context);
 });
 var prReviewersCmd = new Command("reviewers").description("Manage pull request reviewers");
-prReviewersCmd.command("list <id>").description("List reviewers on a pull request").action(async (id, options) => {
+prReviewersCmd.command("list <id>").description("List reviewers on a pull request").addHelpText("after", buildHelpText({
+  examples: ["bb pr reviewers list 42", "bb pr reviewers list 42 --json"]
+})).action(async (id, options) => {
   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").action(async (id, username, options) => {
+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) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.AddReviewerPRCommand, withGlobalOptions({ id, username, ...options }, context), cli, context);
 });
-prReviewersCmd.command("remove <id> <username>").description("Remove a reviewer from a pull request").action(async (id, username, options) => {
+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) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.RemoveReviewerPRCommand, withGlobalOptions({ id, username, ...options }, context), cli, context);
 });
@@ -23756,21 +24224,46 @@ cli.addCommand(prCmd);
 prCmd.addCommand(prCommentsCmd);
 prCmd.addCommand(prReviewersCmd);
 var configCmd = new Command("config").description("Manage configuration");
-configCmd.command("get <key>").description("Get a configuration value").action(async (key) => {
+configCmd.command("get <key>").description("Get a configuration value").addHelpText("after", buildHelpText({
+  examples: ["bb config get defaultWorkspace"],
+  validValues: {
+    "Readable config keys": [
+      "username",
+      "defaultWorkspace",
+      "skipVersionCheck",
+      "versionCheckInterval"
+    ]
+  }
+})).action(async (key) => {
   await runCommand(ServiceTokens.GetConfigCommand, { key }, cli);
 });
-configCmd.command("set <key> <value>").description("Set a configuration value").action(async (key, value) => {
+configCmd.command("set <key> <value>").description("Set a configuration value").addHelpText("after", buildHelpText({
+  examples: [
+    "bb config set defaultWorkspace my-workspace",
+    "bb config set skipVersionCheck true",
+    "bb config set versionCheckInterval 86400"
+  ],
+  validValues: {
+    "Settable config keys": [
+      "defaultWorkspace (string)",
+      "skipVersionCheck (true/false)",
+      "versionCheckInterval (positive integer, seconds)"
+    ]
+  }
+})).action(async (key, value) => {
   await runCommand(ServiceTokens.SetConfigCommand, { key, value }, cli);
 });
-configCmd.command("list").description("List all configuration values").action(async () => {
+configCmd.command("list").description("List all configuration values").addHelpText("after", buildHelpText({
+  examples: ["bb config list", "bb config list --json"]
+})).action(async () => {
   await runCommand(ServiceTokens.ListConfigCommand, undefined, cli);
 });
 cli.addCommand(configCmd);
 var completionCmd = new Command("completion").description("Shell completion utilities");
-completionCmd.command("install").description("Install shell completions for bash, zsh, or fish").action(async () => {
+completionCmd.command("install").description("Install shell completions for bash, zsh, or fish").addHelpText("after", buildHelpText({ examples: ["bb completion install"] })).action(async () => {
   await runCommand(ServiceTokens.InstallCompletionCommand, undefined, cli);
 });
-completionCmd.command("uninstall").description("Uninstall shell completions").action(async () => {
+completionCmd.command("uninstall").description("Uninstall shell completions").addHelpText("after", buildHelpText({ examples: ["bb completion uninstall"] })).action(async () => {
   await runCommand(ServiceTokens.UninstallCompletionCommand, undefined, cli);
 });
 cli.addCommand(completionCmd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilatos/bitbucket-cli",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "A command-line interface for Bitbucket Cloud",
   "author": "",
   "license": "MIT",