@cursor/july 0.1.102 → 0.1.104

package/src/channels/bitbucket/checks.ts

@@ -0,0 +1,154 @@
+/**
+ * Bitbucket build statuses — the Bitbucket {@link CiCheckWriter} behind the
+ * shared check lifecycle in `../checks.js`.
+ *
+ * Bitbucket has no Checks API; the PR page shows **build statuses** keyed
+ * by `(commit, key)`. Cloud: `POST /repositories/{ws}/{slug}/commit/{sha}/
+ * statuses/build`; Data Center: `POST /projects/{KEY}/repos/{slug}/commits/
+ * {sha}/builds`. The writer maps the shared status / conclusion pair onto
+ * Bitbucket's state set and re-posts the full desired state on every write,
+ * so `resumeBitbucketCheck` needs only `(sha, key)` to rebuild a handle.
+ */
+
+import {
+  type CiCheck,
+  type CiCheckConcludeInput,
+  type CiCheckConclusion,
+  type CiCheckCreateInput,
+  type CiCheckOutput,
+  type CiCheckRef,
+  type CiCheckStatus,
+  type CiChecksClient,
+  type CiCheckUpdateInput,
+  type CiCheckWriter,
+  openCiCheck,
+  resumeCiCheck,
+} from "../checks.js";
+import type { BitbucketApi, BitbucketBuildStatusState } from "./api.js";
+
+/** Anything that can post a Bitbucket build status. */
+export type BitbucketCheckClient = Pick<BitbucketApi, "setBuildStatus">;
+
+/** Shared check status / conclusion → Bitbucket build-status state. */
+export function bitbucketBuildStatusState(input: {
+  status: CiCheckStatus;
+  conclusion?: CiCheckConclusion;
+}): BitbucketBuildStatusState {
+  if (input.status === "queued" || input.status === "in_progress") {
+    return "INPROGRESS";
+  }
+  switch (input.conclusion) {
+    case "success":
+    case "neutral":
+    case "skipped":
+      return "SUCCESSFUL";
+    case "cancelled":
+      return "STOPPED";
+    case "failure":
+    case "action_required":
+    case "timed_out":
+    case undefined:
+      return "FAILED";
+  }
+}
+
+export type BitbucketCheckOutput = CiCheckOutput;
+export type BitbucketCheckUpdateInput = CiCheckUpdateInput;
+export type BitbucketCheckConcludeInput = CiCheckConcludeInput;
+
+/** A created build status. All methods throw `BitbucketApiError` on failure. */
+export type BitbucketCheck = CiCheck & CiCheckRef;
+
+export interface BitbucketCheckIdentityInput {
+  /** Client used for every API call on the returned handle. */
+  bitbucket: BitbucketCheckClient;
+  /** Status key shown on the PR, e.g. `"cursor/security-review"`. */
+  name: string;
+  /** Commit the status attaches to (usually the PR head SHA). */
+  sha: string;
+}
+
+export interface BitbucketCheckCreateInput
+  extends BitbucketCheckIdentityInput,
+    CiCheckCreateInput {}
+
+/**
+ * Bitbucket writer: every write re-posts the status row for `(sha, key)`.
+ * Tracks the last written status so an output-only update keeps the state.
+ * Build statuses have no server id or page URL of their own.
+ */
+function bitbucketCheckWriter(
+  input: BitbucketCheckIdentityInput & { status?: CiCheckStatus; url?: string }
+): CiCheckWriter {
+  let lastStatus: CiCheckStatus = input.status ?? "in_progress";
+  let lastUrl: string | undefined = input.url;
+  return async (write) => {
+    const status =
+      write.status ??
+      (write.conclusion === undefined ? lastStatus : "completed");
+    lastStatus = status;
+    lastUrl = write.detailsUrl ?? lastUrl;
+    await input.bitbucket.setBuildStatus({
+      sha: input.sha,
+      key: input.name,
+      name: write.output?.title ?? input.name,
+      state: bitbucketBuildStatusState({
+        status,
+        conclusion: write.conclusion,
+      }),
+      url: lastUrl,
+      description: write.output?.summary,
+    });
+    return lastUrl === undefined ? undefined : { url: lastUrl };
+  };
+}
+
+/**
+ * Open a build status on `sha` and return a handle for later updates.
+ *
+ * ```ts
+ * const check = await createBitbucketCheck({
+ *   bitbucket: ctx.bitbucket.api,
+ *   name: "cursor/security-review",
+ *   sha: pullRequest.headSha,
+ *   detailsUrl: sessionUrl,
+ *   output: { title: "Running…", summary: "" },
+ * });
+ * await check.conclude({ conclusion: "success", output: { title: "Clean", summary: "" } });
+ * ```
+ */
+export function createBitbucketCheck(
+  input: BitbucketCheckCreateInput
+): Promise<BitbucketCheck> {
+  return openCiCheck(bitbucketCheckWriter(input), input);
+}
+
+/**
+ * Rebuild a {@link BitbucketCheck} handle for an existing status row from
+ * its identity. No API call is made until the first update.
+ */
+export function resumeBitbucketCheck(
+  input: BitbucketCheckIdentityInput & {
+    /** Last known status; defaults to `"in_progress"`. */
+    status?: CiCheckStatus;
+    url?: string;
+  }
+): BitbucketCheck {
+  return resumeCiCheck(
+    bitbucketCheckWriter(input),
+    input.url === undefined ? undefined : { url: input.url }
+  );
+}
+
+/**
+ * Repo-bound checks adapter satisfying the shared {@link CiChecksClient}
+ * contract for forge-agnostic check code.
+ */
+export function bindBitbucketChecks(input: {
+  bitbucket: BitbucketCheckClient;
+}): CiChecksClient {
+  return {
+    createCheck: (check) =>
+      createBitbucketCheck({ ...check, bitbucket: input.bitbucket }),
+  };
+}

package/src/channels/bitbucket/cursor-account.ts

@@ -0,0 +1,117 @@
+/**
+ * Cursor-account mode for Bitbucket channels.
+ *
+ * `bitbucketChannel({ cursorAccount })` declares that outbound Bitbucket
+ * calls run through the Cursor SCM proxy (`/v0/bitbucket-proxy`) with the
+ * tenant's credential swapped in server-side. The serve host binds the
+ * Cursor API key and the proxy transport at startup when
+ * `--cursor-scm-proxy` is set; until then `ctx.bitbucket` falls back to
+ * direct `BITBUCKET_TOKEN` access.
+ */
+
+import { resolveCursorScmProxyUrl } from "../github/cursor-account.js";
+import type { BitbucketProxyTransport } from "./api.js";
+import type { BitbucketChannelOptions } from "./types.js";
+
+export const CURSOR_BITBUCKET_MAX_REPOS = 20;
+/** `workspace/slug` (Cloud) or `PROJECT/slug` (Data Center). */
+const CURSOR_BITBUCKET_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+export interface CursorBitbucketRepoScope {
+  /** Lowercased `owner/slug` repos. */
+  repos: readonly string[];
+}
+
+/** Host-bound credential: Cursor API key + proxy transport, bound at serve. */
+export interface PendingCursorBitbucketCredentials {
+  bind(getApiKey: () => Promise<string>): void;
+  bindProxyTransport(
+    transport: Omit<BitbucketProxyTransport, "getApiKey">
+  ): void;
+  /** The full proxy transport once both halves are bound. */
+  getProxyTransport(): BitbucketProxyTransport | undefined;
+}
+
+export interface BitbucketCursorAccountRuntime {
+  /** Authored channel options (not rewritten). */
+  options: BitbucketChannelOptions;
+  credentials: PendingCursorBitbucketCredentials;
+  scope: CursorBitbucketRepoScope | undefined;
+}
+
+const runtimeByDefinition = new WeakMap<
+  object,
+  BitbucketCursorAccountRuntime
+>();
+
+export function parseCursorBitbucketRepoScope(
+  values: readonly string[]
+): CursorBitbucketRepoScope {
+  const repos = [
+    ...new Set(
+      values
+        .map((repo) =>
+          repo
+            .trim()
+            .replace(/^\/+|\/+$/g, "")
+            .toLowerCase()
+        )
+        .filter(Boolean)
+    ),
+  ];
+  if (repos.length === 0) {
+    throw new Error(
+      "bitbucketChannel({ cursorAccount }) requires at least one repo."
+    );
+  }
+  if (repos.length > CURSOR_BITBUCKET_MAX_REPOS) {
+    throw new Error(
+      `bitbucketChannel({ cursorAccount }) supports at most ${CURSOR_BITBUCKET_MAX_REPOS} repos.`
+    );
+  }
+  for (const repo of repos) {
+    if (!CURSOR_BITBUCKET_REPO_PATTERN.test(repo) || repo.includes("..")) {
+      throw new Error(
+        `Invalid Bitbucket repo "${repo}"; expected workspace/repo or PROJECT/repo.`
+      );
+    }
+  }
+  return { repos };
+}
+
+export function createPendingCursorBitbucketCredentials(): PendingCursorBitbucketCredentials {
+  let getApiKey: (() => Promise<string>) | undefined;
+  let transport: Omit<BitbucketProxyTransport, "getApiKey"> | undefined;
+  return {
+    bind(next) {
+      getApiKey = next;
+    },
+    bindProxyTransport(next) {
+      transport = next;
+    },
+    getProxyTransport() {
+      if (getApiKey === undefined || transport === undefined) {
+        return undefined;
+      }
+      return { ...transport, getApiKey };
+    },
+  };
+}
+
+/** Bitbucket-proxy base URL (`/v0/bitbucket-proxy`, `AGENT_SERVE_BITBUCKET_PROXY_URL`). */
+export function resolveCursorBitbucketProxyUrl(backendBaseUrl: string): string {
+  return resolveCursorScmProxyUrl("bitbucket", backendBaseUrl);
+}
+
+export function registerBitbucketCursorAccountRuntime(
+  definition: object,
+  runtime: BitbucketCursorAccountRuntime
+): void {
+  runtimeByDefinition.set(definition, runtime);
+}
+
+export function getBitbucketCursorAccountRuntime(
+  definition: object
+): BitbucketCursorAccountRuntime | undefined {
+  return runtimeByDefinition.get(definition);
+}

package/src/channels/bitbucket/defaults.ts

@@ -0,0 +1,110 @@
+/**
+ * Default dispatch decisions for the Bitbucket channel: turn auth derived
+ * from the delivery's actor, the title / message a turn starts with, and
+ * which pull-request events dispatch when no `onPullRequest` hook exists.
+ */
+
+import type { AuthContext } from "../../types.js";
+import type {
+  BitbucketEventContext,
+  BitbucketPullRequestEvent,
+  BitbucketTurnDispatch,
+} from "./types.js";
+
+type DispatchContext = Omit<
+  BitbucketEventContext,
+  "host" | "artifacts" | "bitbucket" | "send"
+>;
+
+function issuerHost(ctx: DispatchContext): string {
+  if (ctx.repository.htmlUrl !== undefined) {
+    try {
+      return new URL(ctx.repository.htmlUrl).host;
+    } catch {
+      // fall through to the dialect default
+    }
+  }
+  return ctx.repository.dialect === "cloud"
+    ? "bitbucket.org"
+    : "bitbucket-data-center";
+}
+
+/**
+ * Derive the turn's auth from the actor that triggered the delivery — the
+ * standard `{ auth: defaultBitbucketAuth(ctx) }` dispatch from an inbound
+ * hook. The subscriber's Cursor identity is not the turn principal (same
+ * pattern as `defaultGitHubAuth` / `defaultGitLabAuth`).
+ */
+export function defaultBitbucketAuth(ctx: DispatchContext): AuthContext {
+  const sender = ctx.sender;
+  return {
+    authenticator: "bitbucket-webhook",
+    principalId: sender === undefined ? "bitbucket" : sender.id,
+    principalType: "user",
+    attributes: {
+      conversation_kind:
+        ctx.pullRequestId === undefined ? ctx.eventType : "pull_request",
+      repo: ctx.repository.fullName,
+      dialect: ctx.repository.dialect,
+      ...(ctx.deliveryId === undefined ? {} : { delivery_id: ctx.deliveryId }),
+      ...(sender === undefined
+        ? {}
+        : {
+            subject: sender.id,
+            ...(sender.username === undefined
+              ? {}
+              : { username: sender.username }),
+          }),
+      issuer: `bitbucket:${issuerHost(ctx)}`,
+    },
+  };
+}
+
+export function defaultBitbucketTitle(
+  ctx: Pick<BitbucketEventContext, "repository" | "pullRequestId" | "eventType">
+): string {
+  return ctx.pullRequestId === undefined
+    ? `Bitbucket ${ctx.repository.fullName} ${ctx.eventType}`
+    : `Bitbucket ${ctx.repository.fullName}#${ctx.pullRequestId}`;
+}
+
+export function defaultBitbucketPullRequestMessage(
+  ctx: DispatchContext,
+  pullRequest: BitbucketPullRequestEvent
+): string {
+  const head =
+    pullRequest.sourceBranch !== undefined && pullRequest.headSha !== undefined
+      ? `Head: ${pullRequest.sourceBranch} (${pullRequest.headSha})`
+      : undefined;
+  return [
+    `Bitbucket pull request trigger: ${ctx.repository.fullName}#${pullRequest.id}`,
+    `Action: ${pullRequest.action}`,
+    ...(pullRequest.htmlUrl === undefined
+      ? []
+      : [`URL: ${pullRequest.htmlUrl}`]),
+    ...(pullRequest.title === undefined ? [] : [`Title: ${pullRequest.title}`]),
+    ...(head === undefined ? [] : [head]),
+    "Handle this pull request event.",
+  ].join("\n");
+}
+
+/**
+ * Default gate when no `onPullRequest` hook is declared: a new pull request,
+ * or an `updated` that pushed commits (Data Center `pr:from_ref_updated`
+ * carries `previousFromHash`; Cloud `pullrequest:updated` has no diff, so
+ * only a changed head dispatches), starts a turn as the actor.
+ */
+export function defaultBitbucketPullRequestDispatch(
+  ctx: DispatchContext,
+  pullRequest: BitbucketPullRequestEvent
+): BitbucketTurnDispatch | null {
+  const dispatches =
+    pullRequest.action === "created" ||
+    (pullRequest.action === "updated" &&
+      pullRequest.previousHeadSha !== undefined &&
+      pullRequest.previousHeadSha !== pullRequest.headSha);
+  if (!dispatches) {
+    return null;
+  }
+  return { auth: defaultBitbucketAuth(ctx) };
+}

package/src/channels/bitbucket/events.ts

@@ -0,0 +1,84 @@
+/** {@link ChannelMeta.kind} value used by {@link bitbucketChannel}. */
+export const BITBUCKET_CHANNEL_KIND = "bitbucket";
+
+/**
+ * Data Center `X-Event-Key`s → the Cloud vocabulary the channel dispatches
+ * on. Pure copy of the backend ingress normalizer so local HTTP deliveries
+ * (which arrive raw) and hosted admission (already normalized) agree.
+ */
+export const BITBUCKET_DATA_CENTER_EVENT_KEYS: Readonly<
+  Record<string, string>
+> = {
+  "pr:opened": "pullrequest:created",
+  "pr:modified": "pullrequest:updated",
+  "pr:from_ref_updated": "pullrequest:updated",
+  "pr:merged": "pullrequest:fulfilled",
+  "pr:declined": "pullrequest:rejected",
+  "pr:comment:added": "pullrequest:comment_created",
+  "pr:reviewer:approved": "pullrequest:approved",
+  "pr:reviewer:needs_work": "pullrequest:changes_request_created",
+  "repo:refs_changed": "repo:push",
+};
+
+/** `pr:opened` → `pullrequest:created`; Cloud keys pass through unchanged. */
+export function normalizeBitbucketEventKey(eventKey: string): string {
+  const trimmed = eventKey.trim();
+  return BITBUCKET_DATA_CENTER_EVENT_KEYS[trimmed] ?? trimmed;
+}
+
+/** Cloud pull-request event keys, grouped by the hook that receives them. */
+export const BITBUCKET_PULL_REQUEST_EVENTS = [
+  "pullrequest:created",
+  "pullrequest:updated",
+  "pullrequest:approved",
+  "pullrequest:unapproved",
+  "pullrequest:changes_request_created",
+  "pullrequest:fulfilled",
+  "pullrequest:rejected",
+] as const;
+
+export const BITBUCKET_COMMENT_EVENTS = [
+  "pullrequest:comment_created",
+] as const;
+export const BITBUCKET_PUSH_EVENTS = ["repo:push"] as const;
+
+/**
+ * `pullrequest:created` / `:updated` are always declared: they are the
+ * default dispatch when no `onPullRequest` hook exists. Other hooks add
+ * their event keys.
+ */
+const HOOK_EVENTS: ReadonlyArray<
+  readonly [hook: string, events: readonly string[]]
+> = [
+  ["onPullRequest", BITBUCKET_PULL_REQUEST_EVENTS],
+  ["onPullRequestComment", BITBUCKET_COMMENT_EVENTS],
+  ["onPush", BITBUCKET_PUSH_EVENTS],
+];
+
+export interface BitbucketWebhookEventOptions {
+  webhookEvents?: readonly string[];
+  onPullRequest?: unknown;
+  onPullRequestComment?: unknown;
+  onPush?: unknown;
+}
+
+export function deriveBitbucketWebhookEvents(
+  options: BitbucketWebhookEventOptions
+): string[] {
+  if (options.webhookEvents !== undefined) {
+    return [
+      ...new Set(
+        options.webhookEvents
+          .map((event) => normalizeBitbucketEventKey(event))
+          .filter(Boolean)
+      ),
+    ];
+  }
+  const events: string[] = ["pullrequest:created", "pullrequest:updated"];
+  for (const [hook, hookEvents] of HOOK_EVENTS) {
+    if ((options as Record<string, unknown>)[hook] !== undefined) {
+      events.push(...hookEvents);
+    }
+  }
+  return [...new Set(events)];
+}

package/src/channels/bitbucket/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Bitbucket webhook channel pack for agent-serve (Cloud and Data Center).
+ *
+ * ```ts
+ * import { bitbucketChannel, defaultBitbucketAuth } from "@cursor/july/channels/bitbucket";
+ *
+ * export default bitbucketChannel({
+ *   webhookSecret: () => process.env.BITBUCKET_WEBHOOK_SECRET,
+ *   onPullRequest: (ctx) => ({ auth: defaultBitbucketAuth(ctx) }),
+ *   onPullRequestComment: (ctx) => ({ auth: defaultBitbucketAuth(ctx) }),
+ * });
+ * ```
+ *
+ * Direct webhook mode verifies the hook's `X-Hub-Signature` (`sha256=` HMAC
+ * over the raw body) against {@link BitbucketChannelOptions.webhookSecret}
+ * (or `BITBUCKET_WEBHOOK_SECRET`). Data Center `X-Event-Key`s (`pr:opened`)
+ * are normalized to the Cloud vocabulary (`pullrequest:created`) before
+ * hooks run, and payload fields from either dialect land on one shape.
+ * Hosted deployments receive deliveries the Cursor backend already verified
+ * and normalized. The turn principal is `bitbucket-webhook` plus the
+ * Bitbucket actor — not the Cursor subscriber.
+ */
+
+export * from "./api.js";
+export {
+  type BitbucketHandle,
+  bitbucketCommentFromPayload,
+  bitbucketDialectOf,
+  bitbucketPullRequestFromPayload,
+  bitbucketPullRequestUrl,
+  bitbucketPushFromPayload,
+  bitbucketRepositoryFromPayload,
+  bitbucketUser,
+  buildBitbucketBinding,
+} from "./binding.js";
+export * from "./bitbucket-channel.js";
+export * from "./bitbucket-webhook.js";
+export * from "./checks.js";
+export {
+  CURSOR_BITBUCKET_MAX_REPOS,
+  type CursorBitbucketRepoScope,
+  parseCursorBitbucketRepoScope,
+  resolveCursorBitbucketProxyUrl,
+} from "./cursor-account.js";
+export * from "./defaults.js";
+export * from "./events.js";
+export * from "./replay.js";
+export * from "./state.js";
+export * from "./types.js";