@cursor/july 0.1.102 → 0.1.104

package/src/channels/bitbucket/api.ts

@@ -0,0 +1,623 @@
+/**
+ * Bitbucket REST client for the Bitbucket channel — the `createGitLabClient`
+ * analogue, with one `BitbucketApi` facade implemented twice: Cloud 2.0
+ * (`https://api.bitbucket.org/2.0/repositories/{workspace}/{slug}/…`) and
+ * Data Center 1.0 (`<host>/rest/api/1.0/projects/{KEY}/repos/{slug}/…`).
+ * The dialect comes from the delivery payload shape, never a round trip.
+ *
+ * Two transports:
+ *
+ * - **Direct**: `Authorization: Bearer` with a repository / workspace /
+ *   HTTP access token from options or `BITBUCKET_TOKEN`. The base defaults
+ *   to `BITBUCKET_API_BASE_URL`, else api.bitbucket.org (Cloud). Data Center
+ *   deploys must configure one; `ctx.bitbucket` never derives the host from
+ *   the webhook payload — only the replay CLI passes a user-supplied repo URL.
+ * - **Proxy** (`--cursor-scm-proxy` with `cursorAccount`): the backend
+ *   forwarder at `/v0/bitbucket-proxy`. Calls carry the Cursor API key as
+ *   the bearer plus `x-cursor-bitbucket-repos` naming the repo the call is
+ *   scoped to; the backend swaps in the tenant's Bitbucket credential and
+ *   picks the upstream (Cloud 2.0 or the DC host's 1.0) per tenant.
+ */
+
+import type { BitbucketDialect, BitbucketRepositoryRef } from "./types.js";
+
+export const DEFAULT_BITBUCKET_CLOUD_API_BASE_URL =
+  "https://api.bitbucket.org/2.0";
+
+/** Header the SCM proxy reads to scope a Bitbucket call to one repo. */
+export const CURSOR_BITBUCKET_REPOS_HEADER = "x-cursor-bitbucket-repos";
+
+export type BitbucketApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+
+/** Normalized Bitbucket REST failure — the `GitLabApiError` analogue. */
+export class BitbucketApiError extends Error {
+  readonly body: unknown;
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+
+  constructor(input: {
+    body: unknown;
+    method: string;
+    path: string;
+    status: number;
+  }) {
+    super(
+      `Bitbucket ${input.method} ${input.path} failed with HTTP ${input.status}.`
+    );
+    this.name = "BitbucketApiError";
+    this.body = input.body;
+    this.method = input.method;
+    this.path = input.path;
+    this.status = input.status;
+  }
+}
+
+export type BitbucketTokenProvider = () => Promise<string> | string;
+
+/** Backend SCM-proxy transport bound by the serve host in proxy mode. */
+export interface BitbucketProxyTransport {
+  /** `/v0/bitbucket-proxy` base, see `resolveCursorBitbucketProxyUrl`. */
+  apiBaseUrl: string;
+  /** Cursor API key sent as the bearer; the proxy swaps in the Bitbucket token. */
+  getApiKey: () => Promise<string>;
+  /** Static headers added to every call (repo scope when declared). */
+  headers?: Readonly<Record<string, string>>;
+}
+
+export interface BitbucketClientOptions {
+  /**
+   * REST base, e.g. `https://bitbucket.example.com/rest/api/1.0`. Falls back
+   * to `BITBUCKET_API_BASE_URL`.
+   */
+  apiBaseUrl?: string;
+  /** Access token or provider for direct calls. Falls back to `BITBUCKET_TOKEN`. */
+  token?: string | BitbucketTokenProvider;
+  /** Route through the Cursor SCM proxy instead of calling Bitbucket directly. */
+  proxy?: BitbucketProxyTransport;
+  /**
+   * Repo (`workspace/slug` or `PROJECT/slug`) every call is scoped to.
+   * Proxy mode sends it as `x-cursor-bitbucket-repos` when no static header
+   * names one.
+   */
+  repo?: string;
+  /** Injectable fetch for tests. */
+  fetch?: typeof fetch;
+}
+
+export interface BitbucketRequestInput {
+  method: BitbucketApiMethod;
+  /** Path under the API base, e.g. `/repositories/acme/widgets/pullrequests/7`. */
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  /**
+   * `Accept` header. `application/json` (default) parses the body; anything
+   * else (`text/plain` for diffs and raw files) returns the body text.
+   */
+  accept?: string;
+}
+
+/** Minimal authenticated Bitbucket REST client. */
+export interface BitbucketClient {
+  readonly apiBaseUrl: string;
+  /** Call a Bitbucket REST path. Throws {@link BitbucketApiError} on non-2xx. */
+  request<T = unknown>(input: BitbucketRequestInput): Promise<T>;
+}
+
+function envValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+
+/** `BITBUCKET_TOKEN` when set. */
+export function envBitbucketToken(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  return envValue(env.BITBUCKET_TOKEN);
+}
+
+/**
+ * REST base for direct calls: `BITBUCKET_API_BASE_URL`, else api.bitbucket.org
+ * 2.0 for Cloud, else `/rest/api/1.0` on `repoHtmlUrl`'s origin. Callers must
+ * only pass a `repoHtmlUrl` the operator supplied (the replay CLI), never one
+ * read from a delivery payload.
+ */
+export function bitbucketApiBaseUrl(input: {
+  dialect: BitbucketDialect;
+  repoHtmlUrl?: string;
+  env?: NodeJS.ProcessEnv;
+}): string | undefined {
+  const fromEnv = envValue((input.env ?? process.env).BITBUCKET_API_BASE_URL);
+  if (fromEnv !== undefined) {
+    return fromEnv.replace(/\/+$/, "");
+  }
+  if (input.dialect === "cloud") {
+    return DEFAULT_BITBUCKET_CLOUD_API_BASE_URL;
+  }
+  if (input.repoHtmlUrl !== undefined) {
+    try {
+      return `${new URL(input.repoHtmlUrl).origin}/rest/api/1.0`;
+    } catch {
+      // no usable host
+    }
+  }
+  return undefined;
+}
+
+function buildQuery(query: BitbucketRequestInput["query"]): string {
+  if (query === undefined) {
+    return "";
+  }
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) {
+      params.set(key, String(value));
+    }
+  }
+  const encoded = params.toString();
+  return encoded === "" ? "" : `?${encoded}`;
+}
+
+export function createBitbucketClient(
+  options: BitbucketClientOptions = {}
+): BitbucketClient {
+  const fetchImpl = options.fetch ?? fetch;
+  const apiBaseUrl =
+    options.proxy?.apiBaseUrl ??
+    options.apiBaseUrl ??
+    envValue(process.env.BITBUCKET_API_BASE_URL);
+  if (apiBaseUrl === undefined || apiBaseUrl.trim() === "") {
+    throw new Error(
+      "bitbucketChannel: no Bitbucket API base URL (pass apiBaseUrl, set BITBUCKET_API_BASE_URL, or serve with --cursor-scm-proxy and cursorAccount)."
+    );
+  }
+  const base = apiBaseUrl.replace(/\/+$/, "");
+  const repo = options.repo?.trim().replace(/^\/+|\/+$/g, "");
+
+  const authHeaders = async (): Promise<Record<string, string>> => {
+    if (options.proxy !== undefined) {
+      const headers: Record<string, string> = {
+        authorization: `Bearer ${await options.proxy.getApiKey()}`,
+        ...options.proxy.headers,
+      };
+      if (
+        (headers[CURSOR_BITBUCKET_REPOS_HEADER] ?? "").trim() === "" &&
+        repo !== undefined &&
+        repo !== ""
+      ) {
+        headers[CURSOR_BITBUCKET_REPOS_HEADER] = repo.toLowerCase();
+      }
+      return headers;
+    }
+    const token =
+      typeof options.token === "function"
+        ? await options.token()
+        : (options.token ?? envBitbucketToken());
+    if (token === undefined || token === "") {
+      throw new Error(
+        "bitbucketChannel: no Bitbucket credential available (pass token, set BITBUCKET_TOKEN, or serve with --cursor-scm-proxy and cursorAccount)."
+      );
+    }
+    return { authorization: `Bearer ${token}` };
+  };
+
+  return {
+    apiBaseUrl: base,
+    async request<T = unknown>(input: BitbucketRequestInput): Promise<T> {
+      const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
+      const accept = input.accept ?? "application/json";
+      const response = await fetchImpl(
+        `${base}${path}${buildQuery(input.query)}`,
+        {
+          method: input.method,
+          headers: {
+            ...(await authHeaders()),
+            accept,
+            ...(input.body === undefined
+              ? {}
+              : { "content-type": "application/json" }),
+          },
+          body:
+            input.body === undefined ? undefined : JSON.stringify(input.body),
+        }
+      );
+      const text = await response.text();
+      let parsed: unknown = text;
+      if (accept === "application/json") {
+        try {
+          parsed = text === "" ? undefined : JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+      }
+      if (!response.ok) {
+        throw new BitbucketApiError({
+          body: parsed,
+          method: input.method,
+          path,
+          status: response.status,
+        });
+      }
+      return parsed as T;
+    },
+  };
+}
+
+// --- BitbucketApi facade -----------------------------------------------------
+
+/** Build-status states shared by both dialects (DC `STOPPED` → `CANCELLED`). */
+export type BitbucketBuildStatusState =
+  | "INPROGRESS"
+  | "SUCCESSFUL"
+  | "FAILED"
+  | "STOPPED";
+
+export interface BitbucketBuildStatusInput {
+  sha: string;
+  /** Stable key per status row (`cursor/security-review`). */
+  key: string;
+  state: BitbucketBuildStatusState;
+  /** Display name; defaults to {@link key}. */
+  name?: string;
+  /** "Details" link. Both dialects require one; falls back to the repo URL. */
+  url?: string;
+  description?: string;
+}
+
+export interface BitbucketPullRequestCommentInput {
+  body: string;
+  /**
+   * Anchor the comment to a file line. Cloud posts `inline`; Data Center
+   * posts an `anchor` on the destination side. Omit for a top-level comment.
+   */
+  inline?: { path: string; line?: number };
+}
+
+/** Comment as returned by either dialect, minimally normalized. */
+export interface BitbucketApiComment {
+  id: number;
+  body: string;
+  authorId?: string;
+  path?: string;
+  line?: number;
+  raw: unknown;
+}
+
+/** Pull request as returned by either dialect, minimally normalized. */
+export interface BitbucketApiPullRequest {
+  id: number;
+  title?: string;
+  description?: string;
+  state?: string;
+  sourceBranch?: string;
+  targetBranch?: string;
+  headSha?: string;
+  baseSha?: string;
+  htmlUrl?: string;
+  raw: unknown;
+}
+
+/**
+ * The handful of operations review products need, implemented once per
+ * dialect. `ctx.bitbucket.api` is the repo-bound instance.
+ */
+export interface BitbucketApi {
+  readonly dialect: BitbucketDialect;
+  readonly repository: BitbucketRepositoryRef;
+  getPullRequest(id: number): Promise<BitbucketApiPullRequest>;
+  /** Unified diff of the pull request (`text/plain`). */
+  getPullRequestDiff(id: number): Promise<string>;
+  listPullRequestComments(id: number): Promise<BitbucketApiComment[]>;
+  postPullRequestComment(
+    id: number,
+    input: BitbucketPullRequestCommentInput
+  ): Promise<BitbucketApiComment>;
+  setBuildStatus(input: BitbucketBuildStatusInput): Promise<unknown>;
+  /** Raw file contents at `ref` (branch, tag, or SHA). */
+  getFileAtRef(path: string, ref: string): Promise<string>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function encodePath(path: string): string {
+  return path
+    .split("/")
+    .filter((segment) => segment !== "")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+function fallbackUrl(repository: BitbucketRepositoryRef): string {
+  return (
+    repository.htmlUrl ??
+    (repository.dialect === "cloud"
+      ? `https://bitbucket.org/${repository.fullName}`
+      : "https://cursor.com")
+  );
+}
+
+/** `/repositories/{workspace}/{slug}` — Bitbucket Cloud 2.0. */
+export function bitbucketCloudRepoPath(repository: {
+  owner: string;
+  slug: string;
+}): string {
+  return `/repositories/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.slug)}`;
+}
+
+/** `/projects/{KEY}/repos/{slug}` — Bitbucket Data Center 1.0. */
+export function bitbucketDataCenterRepoPath(repository: {
+  owner: string;
+  slug: string;
+}): string {
+  return `/projects/${encodeURIComponent(repository.owner)}/repos/${encodeURIComponent(repository.slug)}`;
+}
+
+export function cloudBitbucketApi(
+  client: BitbucketClient,
+  repository: BitbucketRepositoryRef
+): BitbucketApi {
+  const repo = bitbucketCloudRepoPath(repository);
+  const mapComment = (raw: unknown): BitbucketApiComment => {
+    const record = asRecord(raw) ?? {};
+    const inline = asRecord(record.inline);
+    return {
+      id: num(record.id) ?? 0,
+      body: str(asRecord(record.content)?.raw) ?? "",
+      authorId: str(asRecord(record.user)?.uuid),
+      path: str(inline?.path),
+      line: num(inline?.to) ?? num(inline?.from),
+      raw,
+    };
+  };
+  return {
+    dialect: "cloud",
+    repository,
+    async getPullRequest(id) {
+      const raw = await client.request<Record<string, unknown>>({
+        method: "GET",
+        path: `${repo}/pullrequests/${id}`,
+      });
+      const source = asRecord(raw.source);
+      const destination = asRecord(raw.destination);
+      return {
+        id: num(raw.id) ?? id,
+        title: str(raw.title),
+        description: str(raw.description),
+        state: str(raw.state),
+        sourceBranch: str(asRecord(source?.branch)?.name),
+        targetBranch: str(asRecord(destination?.branch)?.name),
+        headSha: str(asRecord(source?.commit)?.hash),
+        baseSha: str(asRecord(destination?.commit)?.hash),
+        htmlUrl: str(asRecord(asRecord(raw.links)?.html)?.href),
+        raw,
+      };
+    },
+    getPullRequestDiff: (id) =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/pullrequests/${id}/diff`,
+        accept: "text/plain",
+      }),
+    async listPullRequestComments(id) {
+      const comments: BitbucketApiComment[] = [];
+      let page: string | undefined = `${repo}/pullrequests/${id}/comments`;
+      let query: Record<string, string | number> | undefined = { pagelen: 100 };
+      while (page !== undefined) {
+        const raw: Record<string, unknown> = await client.request({
+          method: "GET",
+          path: page,
+          query,
+        });
+        for (const value of Array.isArray(raw.values) ? raw.values : []) {
+          comments.push(mapComment(value));
+        }
+        const next = str(raw.next);
+        if (next === undefined) {
+          break;
+        }
+        // `next` is absolute; re-root it under the client base so the proxy
+        // (which only forwards paths) keeps working.
+        const nextUrl = new URL(next);
+        const baseUrl = new URL(`${client.apiBaseUrl}/`);
+        page = nextUrl.pathname.startsWith(baseUrl.pathname)
+          ? nextUrl.pathname.slice(baseUrl.pathname.length - 1)
+          : nextUrl.pathname;
+        query = Object.fromEntries(nextUrl.searchParams.entries());
+      }
+      return comments;
+    },
+    async postPullRequestComment(id, input) {
+      const raw = await client.request({
+        method: "POST",
+        path: `${repo}/pullrequests/${id}/comments`,
+        body: {
+          content: { raw: input.body },
+          ...(input.inline === undefined
+            ? {}
+            : {
+                inline: {
+                  path: input.inline.path,
+                  ...(input.inline.line === undefined
+                    ? {}
+                    : { to: input.inline.line }),
+                },
+              }),
+        },
+      });
+      return mapComment(raw);
+    },
+    setBuildStatus: (input) =>
+      client.request({
+        method: "POST",
+        path: `${repo}/commit/${encodeURIComponent(input.sha)}/statuses/build`,
+        body: {
+          key: input.key,
+          state: input.state,
+          name: input.name ?? input.key,
+          url: input.url ?? fallbackUrl(repository),
+          ...(input.description === undefined
+            ? {}
+            : { description: input.description }),
+        },
+      }),
+    getFileAtRef: (path, ref) =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/src/${encodeURIComponent(ref)}/${encodePath(path)}`,
+        accept: "text/plain",
+      }),
+  };
+}
+
+export function dcBitbucketApi(
+  client: BitbucketClient,
+  repository: BitbucketRepositoryRef
+): BitbucketApi {
+  const repo = bitbucketDataCenterRepoPath(repository);
+  const mapComment = (raw: unknown): BitbucketApiComment => {
+    const record = asRecord(raw) ?? {};
+    const anchor = asRecord(record.anchor);
+    const authorId = num(asRecord(record.author)?.id);
+    return {
+      id: num(record.id) ?? 0,
+      body: str(record.text) ?? "",
+      authorId: authorId === undefined ? undefined : String(authorId),
+      path: str(anchor?.path),
+      line: num(anchor?.line),
+      raw,
+    };
+  };
+  return {
+    dialect: "data-center",
+    repository,
+    async getPullRequest(id) {
+      const raw = await client.request<Record<string, unknown>>({
+        method: "GET",
+        path: `${repo}/pull-requests/${id}`,
+      });
+      const fromRef = asRecord(raw.fromRef);
+      const toRef = asRecord(raw.toRef);
+      const self = asRecord(raw.links)?.self;
+      return {
+        id: num(raw.id) ?? id,
+        title: str(raw.title),
+        description: str(raw.description),
+        state: str(raw.state),
+        sourceBranch: str(fromRef?.displayId),
+        targetBranch: str(toRef?.displayId),
+        headSha: str(fromRef?.latestCommit),
+        baseSha: str(toRef?.latestCommit),
+        htmlUrl: Array.isArray(self) ? str(asRecord(self[0])?.href) : undefined,
+        raw,
+      };
+    },
+    // `/pull-requests/{id}.diff` streams the raw unified diff; the sibling
+    // `/pull-requests/{id}/diff` route returns a JSON `RestDiff` instead.
+    getPullRequestDiff: (id) =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/pull-requests/${id}.diff`,
+        accept: "text/plain",
+      }),
+    async listPullRequestComments(id) {
+      const comments: BitbucketApiComment[] = [];
+      let start = 0;
+      for (;;) {
+        const raw = await client.request<Record<string, unknown>>({
+          method: "GET",
+          path: `${repo}/pull-requests/${id}/activities`,
+          query: { limit: 100, start },
+        });
+        for (const value of Array.isArray(raw.values) ? raw.values : []) {
+          const activity = asRecord(value);
+          if (
+            activity?.action === "COMMENTED" &&
+            activity.comment !== undefined
+          ) {
+            comments.push(mapComment(activity.comment));
+          }
+        }
+        const nextStart = num(raw.nextPageStart);
+        if (raw.isLastPage !== false || nextStart === undefined) {
+          break;
+        }
+        start = nextStart;
+      }
+      return comments;
+    },
+    async postPullRequestComment(id, input) {
+      const raw = await client.request({
+        method: "POST",
+        path: `${repo}/pull-requests/${id}/comments`,
+        body: {
+          text: input.body,
+          ...(input.inline === undefined
+            ? {}
+            : {
+                anchor: {
+                  path: input.inline.path,
+                  diffType: "EFFECTIVE",
+                  ...(input.inline.line === undefined
+                    ? { fileType: "TO" }
+                    : {
+                        line: input.inline.line,
+                        lineType: "CONTEXT",
+                        fileType: "TO",
+                      }),
+                },
+              }),
+        },
+      });
+      return mapComment(raw);
+    },
+    // Repository-scoped build status (DC 7.14+), which lives under
+    // `rest/api/1.0` so the proxy's single upstream base reaches it; the
+    // older `rest/build-status/1.0/commits/{sha}` sits outside that base.
+    setBuildStatus: (input) =>
+      client.request({
+        method: "POST",
+        path: `${repo}/commits/${encodeURIComponent(input.sha)}/builds`,
+        body: {
+          key: input.key,
+          state: input.state === "STOPPED" ? "CANCELLED" : input.state,
+          name: input.name ?? input.key,
+          url: input.url ?? fallbackUrl(repository),
+          ...(input.description === undefined
+            ? {}
+            : { description: input.description }),
+        },
+      }),
+    getFileAtRef: (path, ref) =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/raw/${encodePath(path)}`,
+        query: { at: ref },
+        accept: "text/plain",
+      }),
+  };
+}
+
+/** Pick the dialect implementation for `repository.dialect`. */
+export function createBitbucketApi(
+  client: BitbucketClient,
+  repository: BitbucketRepositoryRef
+): BitbucketApi {
+  return repository.dialect === "cloud"
+    ? cloudBitbucketApi(client, repository)
+    : dcBitbucketApi(client, repository);
+}