@bugmole/cli 0.5.0 → 0.6.0

package/src/billing/plan-catalog.ts

@@ -12,6 +12,16 @@ export type UsageKind = "browser_minute" | "device_minute" | "ai_credit";
 export type AiAction = "analysis" | "repair" | "exploration" | "discovery";
 
 export type PlanFeatures = {
+  /** Every plan: no per-seat pricing. */
+  unlimitedUsers: boolean;
+  /** Every plan: runs on your own machines and CI are never counted. */
+  unlimitedLocalRuns: boolean;
+  /** Every plan: Chrome, Firefox, Safari and Edge. */
+  desktopBrowsers: boolean;
+  /** Every plan: emulated iPhone and Android viewports. */
+  emulatedMobile: boolean;
+  /** Every plan: AI explains a failed run (uses AI credits). */
+  aiFailureAnalysis: boolean;
   prChecks: boolean;
   slack: boolean;
   teams: boolean;
@@ -38,12 +48,55 @@ export type PlanDef = {
   aiCredits: number | null;
   parallel: number | null;
   historyDays: number | null;
+  /**
+   * Days without any activity (a run, a task, exploration, a CLI/MCP call or a
+   * dashboard change) before a project is paused; null means never. A paused
+   * project is read-only and doesn't count toward `projects` until someone
+   * activates it again.
+   */
+  inactiveProjectDays: number | null;
+  /**
+   * How far one exploration on Bugmole Cloud goes: pages opened, and clicks
+   * from home. A project's own machine sets its own (BUGMOLE_DISCOVERY_MAX_*).
+   */
+  discovery: { maxPages: number; maxDepth: number };
   /** Cents per unit beyond the allowance; null means usage stops at the allowance. */
   overage: { browserMinuteCents: number | null; creditCents: number | null };
   features: PlanFeatures;
+  /**
+   * What a contract adds beyond the limits and features above, as shown on the
+   * pricing page. Descriptive only: NOT enforced by the registry or read by
+   * feature flags; the contract itself sets them up.
+   */
+  extras: PlanExtras;
 };
 
-const NO_FEATURES: PlanFeatures = {
+/** Descriptive, contract-only plan extras (never enforced; see PlanDef.extras). */
+export type PlanExtras = {
+  dedicatedInfrastructure: boolean;
+  privateDevices: boolean;
+  ownModelAndStorage: boolean;
+  customRetention: boolean;
+  sla: boolean;
+  volumePricing: boolean;
+};
+
+const NO_EXTRAS: PlanExtras = {
+  dedicatedInfrastructure: false,
+  privateDevices: false,
+  ownModelAndStorage: false,
+  customRetention: false,
+  sla: false,
+  volumePricing: false,
+};
+
+/** What every plan, Free included, gets; paid plans add to it. */
+const BASE_FEATURES: PlanFeatures = {
+  unlimitedUsers: true,
+  unlimitedLocalRuns: true,
+  desktopBrowsers: true,
+  emulatedMobile: true,
+  aiFailureAnalysis: true,
   prChecks: false,
   slack: false,
   teams: false,
@@ -68,8 +121,11 @@ export const PLANS: Record<PlanId, PlanDef> = {
     aiCredits: 100,
     parallel: 2,
     historyDays: 7,
+    inactiveProjectDays: 30,
+    discovery: { maxPages: 12, maxDepth: 2 },
     overage: { browserMinuteCents: null, creditCents: null },
-    features: { ...NO_FEATURES },
+    features: { ...BASE_FEATURES },
+    extras: { ...NO_EXTRAS },
   },
   team: {
     id: "team",
@@ -82,8 +138,11 @@ export const PLANS: Record<PlanId, PlanDef> = {
     aiCredits: 1_500,
     parallel: 8,
     historyDays: 30,
+    inactiveProjectDays: null,
+    discovery: { maxPages: 40, maxDepth: 3 },
     overage: { browserMinuteCents: 4, creditCents: 1 },
-    features: { ...NO_FEATURES, prChecks: true, slack: true, teams: true, aiFixes: true },
+    features: { ...BASE_FEATURES, prChecks: true, slack: true, teams: true, aiFixes: true },
+    extras: { ...NO_EXTRAS },
   },
   business: {
     id: "business",
@@ -96,9 +155,11 @@ export const PLANS: Record<PlanId, PlanDef> = {
     aiCredits: 7_500,
     parallel: 25,
     historyDays: 90,
+    inactiveProjectDays: null,
+    discovery: { maxPages: 100, maxDepth: 4 },
     overage: { browserMinuteCents: 3, creditCents: 1 },
     features: {
-      ...NO_FEATURES,
+      ...BASE_FEATURES,
       prChecks: true,
       slack: true,
       teams: true,
@@ -108,6 +169,7 @@ export const PLANS: Record<PlanId, PlanDef> = {
       auditLogExport: true,
       prioritySupport: true,
     },
+    extras: { ...NO_EXTRAS },
   },
   enterprise: {
     id: "enterprise",
@@ -120,8 +182,11 @@ export const PLANS: Record<PlanId, PlanDef> = {
     aiCredits: null,
     parallel: null,
     historyDays: 365,
+    inactiveProjectDays: null,
+    discovery: { maxPages: 250, maxDepth: 5 },
     overage: { browserMinuteCents: 3, creditCents: 1 },
     features: {
+      ...BASE_FEATURES,
       prChecks: true,
       slack: true,
       teams: true,
@@ -133,6 +198,16 @@ export const PLANS: Record<PlanId, PlanDef> = {
       prioritySupport: true,
       selfHostedWorkers: true,
     },
+    // Agreed per contract; additional usage is priced there too, not at the list
+    // rates above (which only apply until a contract sets its own).
+    extras: {
+      dedicatedInfrastructure: true,
+      privateDevices: true,
+      ownModelAndStorage: true,
+      customRetention: true,
+      sla: true,
+      volumePricing: true,
+    },
   },
 };
 
@@ -150,12 +225,12 @@ export const AI_CREDIT_COST: Record<AiAction, number> = {
 export const DEVICE_FARM_CENTS_PER_MIN = 25;
 
 /** Contract-specific adjustments stored with a workspace's plan (Enterprise, trials). */
-export type PlanOverrides = Partial<Pick<PlanDef, "projects" | "cloudMinutes" | "aiCredits" | "parallel" | "historyDays">> & {
+export type PlanOverrides = Partial<Pick<PlanDef, LimitKey>> & {
   features?: Partial<PlanFeatures>;
   overage?: Partial<PlanDef["overage"]>;
 };
 
-export type Entitlements = Omit<PlanDef, "name" | "audience" | "priceMonthlyCents" | "priceYearlyMonthlyCents">;
+export type Entitlements = Omit<PlanDef, "name" | "audience" | "priceMonthlyCents" | "priceYearlyMonthlyCents" | "extras">;
 
 export function isPlanId(value: unknown): value is PlanId {
   return typeof value === "string" && (PLAN_IDS as string[]).includes(value);
@@ -163,7 +238,7 @@ export function isPlanId(value: unknown): value is PlanId {
 
 export function entitlementsFor(plan: PlanId, overrides: PlanOverrides = {}): Entitlements {
   const base = PLANS[plan];
-  const pick = <K extends "projects" | "cloudMinutes" | "aiCredits" | "parallel" | "historyDays">(key: K) =>
+  const pick = <K extends LimitKey>(key: K) =>
     overrides[key] !== undefined ? (overrides[key] as PlanDef[K]) : base[key];
   return {
     id: base.id,
@@ -172,6 +247,8 @@ export function entitlementsFor(plan: PlanId, overrides: PlanOverrides = {}): En
     aiCredits: pick("aiCredits"),
     parallel: pick("parallel"),
     historyDays: pick("historyDays"),
+    inactiveProjectDays: pick("inactiveProjectDays"),
+    discovery: { ...base.discovery },
     overage: { ...base.overage, ...overrides.overage },
     features: { ...base.features, ...overrides.features },
   };
@@ -188,8 +265,8 @@ export function includedQuantity(entitlements: Entitlements, kind: UsageKind): n
 export function overageCents(entitlements: Entitlements, kind: UsageKind): number | null {
   if (kind === "browser_minute") return entitlements.overage.browserMinuteCents;
   if (kind === "ai_credit") return entitlements.overage.creditCents;
-  // Real devices need a paid plan with a subscription; the registry checks that.
-  return entitlements.id === "free" ? null : DEVICE_FARM_CENTS_PER_MIN;
+  // Real devices come with device clouds (Business and up), billed as you go.
+  return entitlements.features.deviceClouds ? DEVICE_FARM_CENTS_PER_MIN : null;
 }
 
 export function formatUsd(cents: number, { minimumFractionDigits }: { minimumFractionDigits?: number } = {}): string {
@@ -197,3 +274,129 @@ export function formatUsd(cents: number, { minimumFractionDigits }: { minimumFra
   const fraction = minimumFractionDigits ?? (Number.isInteger(dollars) ? 0 : 2);
   return `$${dollars.toLocaleString("en-US", { minimumFractionDigits: fraction, maximumFractionDigits: Math.max(fraction, 2) })}`;
 }
+
+// ---------- pricing page ----------
+// The bugmole.com pricing page renders every plan feature, extra and limit from
+// these rows, so a row can't claim something the catalog doesn't grant. A test
+// fails when a catalog key has no row here and isn't in PRICING_UNLISTED.
+
+export type LimitKey = "projects" | "cloudMinutes" | "aiCredits" | "parallel" | "historyDays" | "inactiveProjectDays";
+export type PricingKey =
+  | `features.${keyof PlanFeatures}`
+  | `extras.${keyof PlanExtras}`
+  | `limits.${LimitKey}`
+  | `overage.${UsageKind}`;
+
+export type PricingRow = {
+  key: PricingKey;
+  /** Compare-table row label. */
+  label: string;
+  /** Plan-card bullet, when it differs from the label; for an overage, {value} is the rate. */
+  card?: string;
+  /** Unit after a limit or overage value: " days", " / min", " each". */
+  unit?: string;
+  /** What a limit of null (no limit) reads as; "Custom" when unset. */
+  unlimited?: string;
+};
+
+export const LIMIT_KEYS: LimitKey[] = ["projects", "cloudMinutes", "aiCredits", "parallel", "historyDays", "inactiveProjectDays"];
+
+export const PRICING_ROWS: PricingRow[] = [
+  { key: "features.unlimitedUsers", label: "Unlimited users" },
+  { key: "features.unlimitedLocalRuns", label: "Unlimited local & CI runs" },
+  { key: "features.desktopBrowsers", label: "Chrome, Firefox, Safari & Edge" },
+  { key: "features.emulatedMobile", label: "Emulated iPhone & Android" },
+  { key: "features.aiFailureAnalysis", label: "AI failure analysis" },
+  { key: "limits.projects", label: "Projects" },
+  { key: "limits.cloudMinutes", label: "Cloud minutes / month" },
+  { key: "limits.aiCredits", label: "AI credits / month" },
+  { key: "limits.parallel", label: "Cloud runs at once" },
+  { key: "limits.historyDays", label: "Run history", unit: " days" },
+  { key: "limits.inactiveProjectDays", label: "Projects paused after inactivity", unit: " days", unlimited: "Never" },
+  { key: "overage.browser_minute", label: "Additional cloud minutes", unit: " / min" },
+  { key: "overage.ai_credit", label: "Additional AI credits", unit: " each" },
+  {
+    key: "overage.device_minute",
+    label: "Real-device minutes (Bugmole device cloud)",
+    card: "Real devices on Bugmole's device cloud at {value}, pay as you go",
+    unit: " / min",
+  },
+  { key: "features.prChecks", label: "PR checks" },
+  { key: "features.slack", label: "Slack alerts" },
+  { key: "features.teams", label: "Microsoft Teams alerts" },
+  { key: "features.aiFixes", label: "AI test fixes" },
+  {
+    key: "features.deviceClouds",
+    label: "Device clouds (simulators, emulators, real devices)",
+    card: "iOS simulators, Android emulators & real devices through BrowserStack, Kobiton or AWS Device Farm",
+  },
+  { key: "features.sso", label: "SSO" },
+  { key: "features.auditLogExport", label: "Audit log export" },
+  { key: "features.prioritySupport", label: "Priority support" },
+  { key: "features.scim", label: "SCIM provisioning" },
+  { key: "features.selfHostedWorkers", label: "Self-hosted workers" },
+  { key: "extras.dedicatedInfrastructure", label: "Dedicated infrastructure" },
+  { key: "extras.privateDevices", label: "Private devices" },
+  { key: "extras.ownModelAndStorage", label: "Your own AI model and storage" },
+  { key: "extras.customRetention", label: "Custom retention" },
+  { key: "extras.sla", label: "SLA" },
+  { key: "extras.volumePricing", label: "Volume pricing" },
+];
+
+/**
+ * Catalog keys deliberately left off the pricing page, each with the reason.
+ * Empty today: everything a plan grants is shown.
+ */
+export const PRICING_UNLISTED: Partial<Record<PricingKey, string>> = {};
+
+/** Every key the catalog defines for a plan, in pricing-key form. */
+export function catalogPricingKeys(): PricingKey[] {
+  const plan = PLANS.free;
+  return [
+    ...(Object.keys(plan.features) as Array<keyof PlanFeatures>).map((key) => `features.${key}` as const),
+    ...(Object.keys(plan.extras) as Array<keyof PlanExtras>).map((key) => `extras.${key}` as const),
+    ...LIMIT_KEYS.map((key) => `limits.${key}` as const),
+    ...(["browser_minute", "ai_credit", "device_minute"] as UsageKind[]).map((key) => `overage.${key}` as const),
+  ];
+}
+
+/**
+ * A plan's raw value for a pricing key: a flag, a limit (null: set per
+ * contract) or cents per unit (null: not available). undefined means the key
+ * isn't in the catalog.
+ */
+export function pricingValue(plan: PlanId, key: string): boolean | number | null | undefined {
+  const [group, name] = key.split(".");
+  if (!name || !isPlanId(plan)) return undefined;
+  const def = PLANS[plan];
+  if (group === "features") return Object.hasOwn(def.features, name) ? def.features[name as keyof PlanFeatures] : undefined;
+  if (group === "extras") return Object.hasOwn(def.extras, name) ? def.extras[name as keyof PlanExtras] : undefined;
+  if (group === "limits") return (LIMIT_KEYS as string[]).includes(name) ? entitlementsFor(plan)[name as LimitKey] : undefined;
+  if (group === "overage") {
+    return (["browser_minute", "ai_credit", "device_minute"] as string[]).includes(name)
+      ? overageCents(entitlementsFor(plan), name as UsageKind)
+      : undefined;
+  }
+  return undefined;
+}
+
+/** Whether a plan has a row's feature, extra or overage at all (limits always apply). */
+export function pricingIncluded(plan: PlanId, row: PricingRow): boolean {
+  const value = pricingValue(plan, row.key);
+  if (value === undefined) throw new Error(`Unknown pricing key: ${row.key}`);
+  return value !== false && value !== null;
+}
+
+/** The compare-table cell for a plan: ✓ or — for flags, the value with its unit otherwise. */
+export function pricingCell(plan: PlanId, row: PricingRow): string {
+  const value = pricingValue(plan, row.key);
+  if (value === undefined) throw new Error(`Unknown pricing key: ${row.key}`);
+  if (typeof value === "boolean") return value ? "\u2713" : "\u2014";
+  const custom = PLANS[plan].priceMonthlyCents === null;
+  if (row.key.startsWith("overage.")) {
+    // Contract plans price additional usage in the contract, not at list rates.
+    if (custom) return value === null ? "\u2014" : "Volume pricing";
+    return value === null ? "\u2014" : `${formatUsd(value, { minimumFractionDigits: 2 })}${row.unit ?? ""}`;
+  }
+  return value === null ? (row.unlimited ?? "Custom") : `${value.toLocaleString("en-US")}${row.unit ?? ""}`;
+}

package/src/integrations/jira.ts

@@ -0,0 +1,264 @@
+// A small Jira Cloud REST client (platform API v3) for what the Bugmole
+// integration needs: create and find issues, read transitions, move an
+// issue, comment with @mentions, and edit labels.
+//
+// Authentication is behind JiraAuthProvider so OAuth 2.0 (3LO) can be added
+// without touching the calls. Today there is one provider, an Atlassian API
+// token (Basic auth with the account email). 3LO needs an Atlassian developer
+// app registered at developer.atlassian.com (client id and secret, callback
+// URL, scopes read:jira-work write:jira-work read:jira-user offline_access);
+// its calls go to https://api.atlassian.com/ex/jira/<cloudId> with a Bearer
+// token instead of the site URL.
+//
+// Nothing here logs or returns a credential: errors carry the HTTP status and
+// Jira's own error text, never request headers.
+
+export type JiraFetchEnv = {
+  /** Test seam. */
+  JIRA_FETCH?: typeof fetch;
+};
+
+export class JiraApiError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message);
+  }
+}
+
+/** Supplies the base URL and Authorization header for Jira calls. */
+export interface JiraAuthProvider {
+  readonly kind: "api_token" | "oauth";
+  /** Where REST paths are resolved: the site for API tokens, api.atlassian.com/ex/jira/<cloudId> for 3LO. */
+  readonly apiBase: string;
+  authorization(): Promise<string>;
+}
+
+export class ApiTokenAuth implements JiraAuthProvider {
+  readonly kind = "api_token" as const;
+  readonly apiBase: string;
+  readonly #header: string;
+
+  constructor(siteUrl: string, email: string, token: string) {
+    this.apiBase = siteUrl.replace(/\/+$/, "");
+    const bytes = new TextEncoder().encode(`${email}:${token}`);
+    let binary = "";
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    this.#header = `Basic ${btoa(binary)}`;
+  }
+
+  async authorization(): Promise<string> {
+    return this.#header;
+  }
+
+  /** Never serialize the credential, even by accident. */
+  toJSON() {
+    return { kind: this.kind, apiBase: this.apiBase };
+  }
+}
+
+const SITE = /^https:\/\/[a-z0-9][a-z0-9-]{0,62}\.atlassian\.net$/;
+
+/**
+ * A Jira Cloud site URL, normalized to https://<name>.atlassian.net, or null.
+ * Only Atlassian-hosted sites are accepted, so a connection can't point the
+ * registry's requests at an arbitrary host.
+ */
+export function normalizeJiraSite(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  let text = value.trim().toLowerCase();
+  if (!text) return null;
+  if (!/^https?:\/\//.test(text)) text = `https://${text}`;
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.port) return null;
+  const site = `https://${url.hostname}`;
+  return SITE.test(site) ? site : null;
+}
+
+export const JIRA_PROJECT_KEY = /^[A-Z][A-Z0-9_]{1,9}$/;
+
+// --- Atlassian Document Format ----------------------------------------------------------------
+
+export type AdfNode = { type: string; attrs?: Record<string, unknown>; content?: AdfNode[]; text?: string; marks?: Array<{ type: string; attrs?: Record<string, unknown> }> };
+export type AdfDoc = { type: "doc"; version: 1; content: AdfNode[] };
+
+export const adf = {
+  doc(...content: AdfNode[]): AdfDoc {
+    return { type: "doc", version: 1, content };
+  },
+  paragraph(...content: AdfNode[]): AdfNode {
+    return { type: "paragraph", content };
+  },
+  text(text: string, marks?: AdfNode["marks"]): AdfNode {
+    return marks?.length ? { type: "text", text, marks } : { type: "text", text };
+  },
+  strong(text: string): AdfNode {
+    return { type: "text", text, marks: [{ type: "strong" }] };
+  },
+  link(text: string, href: string): AdfNode {
+    return { type: "text", text, marks: [{ type: "link", attrs: { href } }] };
+  },
+  mention(accountId: string, name?: string): AdfNode {
+    return { type: "mention", attrs: { id: accountId, text: `@${name ?? accountId}` } };
+  },
+  heading(level: number, text: string): AdfNode {
+    return { type: "heading", attrs: { level }, content: [{ type: "text", text }] };
+  },
+  bullets(items: AdfNode[][]): AdfNode {
+    return { type: "bulletList", content: items.map((content) => ({ type: "listItem", content: [{ type: "paragraph", content }] })) };
+  },
+  ordered(items: string[]): AdfNode {
+    return { type: "orderedList", content: items.map((item) => ({ type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: item }] }] })) };
+  },
+};
+
+/** Plain text of a comment body: ADF (API v3) or a wiki-markup string (webhooks, API v2). */
+export function commentText(body: unknown): string {
+  if (typeof body === "string") return body;
+  const parts: string[] = [];
+  const walk = (node: unknown) => {
+    if (!node || typeof node !== "object") return;
+    const value = node as AdfNode;
+    if (value.type === "text" && typeof value.text === "string") parts.push(value.text);
+    if (value.type === "mention" && typeof value.attrs?.text === "string") parts.push(value.attrs.text as string);
+    if (Array.isArray(value.content)) {
+      for (const child of value.content) walk(child);
+      if (value.type === "paragraph") parts.push("\n");
+    }
+  };
+  walk(body);
+  return parts.join(" ").replace(/[ \t]+/g, " ").trim();
+}
+
+/** Account ids mentioned in a comment body: ADF mention nodes, or [~accountid:…] in wiki markup. */
+export function mentionedAccountIds(body: unknown): string[] {
+  const ids = new Set<string>();
+  if (typeof body === "string") {
+    for (const match of body.matchAll(/\[~accountid:([^\]]+)\]/g)) ids.add(match[1]);
+    return [...ids];
+  }
+  const walk = (node: unknown) => {
+    if (!node || typeof node !== "object") return;
+    const value = node as AdfNode;
+    if (value.type === "mention" && typeof value.attrs?.id === "string") ids.add(value.attrs.id as string);
+    if (Array.isArray(value.content)) for (const child of value.content) walk(child);
+  };
+  walk(body);
+  return [...ids];
+}
+
+// --- REST --------------------------------------------------------------------------------------
+
+export type JiraUser = { accountId: string; displayName?: string; emailAddress?: string };
+export type JiraStatus = { name: string; statusCategory?: { key: string; name?: string } };
+export type JiraTransition = { id: string; name: string; to: JiraStatus };
+export type JiraIssue = {
+  id: string;
+  key: string;
+  fields: {
+    summary?: string;
+    status?: JiraStatus;
+    labels?: string[];
+    assignee?: JiraUser | null;
+    reporter?: JiraUser | null;
+  };
+};
+
+export class JiraClient {
+  constructor(private readonly env: JiraFetchEnv, readonly auth: JiraAuthProvider) {}
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const response = await (this.env.JIRA_FETCH ?? fetch)(`${this.auth.apiBase}${path}`, {
+      method,
+      headers: {
+        authorization: await this.auth.authorization(),
+        accept: "application/json",
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new JiraApiError(response.status, `Jira ${method} ${path.split("?")[0]} failed (${response.status}) ${jiraErrorText(text)}`.trim());
+    }
+    if (response.status === 204) return undefined as T;
+    const text = await response.text();
+    return (text ? JSON.parse(text) : undefined) as T;
+  }
+
+  myself(): Promise<JiraUser> {
+    return this.request("GET", "/rest/api/3/myself");
+  }
+
+  project(key: string): Promise<{ id: string; key: string; name: string }> {
+    return this.request("GET", `/rest/api/3/project/${encodeURIComponent(key)}`);
+  }
+
+  createIssue(fields: Record<string, unknown>): Promise<{ id: string; key: string }> {
+    return this.request("POST", "/rest/api/3/issue", { fields });
+  }
+
+  getIssue(key: string, fields = "summary,status,labels,assignee,reporter"): Promise<JiraIssue> {
+    return this.request("GET", `/rest/api/3/issue/${encodeURIComponent(key)}?fields=${encodeURIComponent(fields)}`);
+  }
+
+  editIssue(key: string, body: Record<string, unknown>): Promise<void> {
+    return this.request("PUT", `/rest/api/3/issue/${encodeURIComponent(key)}`, body);
+  }
+
+  /** Issues matching a JQL query (the enhanced search endpoint). */
+  async search(jql: string, fields = "summary,labels"): Promise<JiraIssue[]> {
+    const query = new URLSearchParams({ jql, fields, maxResults: "10" });
+    const result = await this.request<{ issues?: JiraIssue[] }>("GET", `/rest/api/3/search/jql?${query}`);
+    return result?.issues ?? [];
+  }
+
+  async transitions(key: string): Promise<JiraTransition[]> {
+    const result = await this.request<{ transitions?: JiraTransition[] }>("GET", `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`);
+    return result?.transitions ?? [];
+  }
+
+  transition(key: string, transitionId: string): Promise<void> {
+    return this.request("POST", `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`, { transition: { id: transitionId } });
+  }
+
+  comment(key: string, body: AdfDoc): Promise<{ id: string }> {
+    return this.request("POST", `/rest/api/3/issue/${encodeURIComponent(key)}/comment`, { body });
+  }
+
+  labels(key: string, change: { add?: string[]; remove?: string[] }): Promise<void> {
+    const operations = [...(change.add ?? []).map((label) => ({ add: label })), ...(change.remove ?? []).map((label) => ({ remove: label }))];
+    return this.editIssue(key, { update: { labels: operations } });
+  }
+}
+
+function jiraErrorText(text: string): string {
+  try {
+    const parsed = JSON.parse(text) as { errorMessages?: string[]; errors?: Record<string, string> };
+    const messages = [...(parsed.errorMessages ?? []), ...Object.entries(parsed.errors ?? {}).map(([field, message]) => `${field}: ${message}`)];
+    return messages.join("; ").slice(0, 300);
+  } catch {
+    return text.slice(0, 200);
+  }
+}
+
+/** The transition that reaches a status in the Done category; one named "Done" first. */
+export function doneTransition(transitions: JiraTransition[]): JiraTransition | undefined {
+  const done = transitions.filter((transition) => transition.to?.statusCategory?.key === "done");
+  return done.find((transition) => transition.to.name.toLowerCase() === "done") ?? done[0];
+}
+
+/** The transition to a status named Blocked (or itself named Blocked), if the workflow has one. */
+export function blockedTransition(transitions: JiraTransition[]): JiraTransition | undefined {
+  return transitions.find((transition) => transition.to?.name?.toLowerCase() === "blocked")
+    ?? transitions.find((transition) => transition.name.toLowerCase() === "blocked");
+}
+
+/** A transition back to a To Do/In Progress-style status, for a ticket that is retested. */
+export function reopenTransition(transitions: JiraTransition[]): JiraTransition | undefined {
+  const open = transitions.filter((transition) => transition.to?.statusCategory?.key === "indeterminate" || transition.to?.statusCategory?.key === "new");
+  return open.find((transition) => /in progress|in test|testing|retest/i.test(transition.to.name)) ?? open[0];
+}