@cursor/july 0.1.102 → 0.1.103

package/src/channels/bitbucket/binding.ts

@@ -0,0 +1,414 @@
+/**
+ * Repository / pull-request binding parsed from a Bitbucket webhook payload,
+ * normalized across the two dialects.
+ *
+ * Cloud: top-level `repository` (`full_name`, `uuid`, `links.html.href`),
+ * `pullrequest` (`source.branch.name`, `source.commit.hash`, `links.html`),
+ * `comment.content.raw`, `push.changes[].new.target.hash`.
+ *
+ * Data Center: `pullRequest` (`fromRef.displayId`, `fromRef.latestCommit`,
+ * repo under `toRef.repository` as `project.key` + `slug`), `comment.text`,
+ * top-level `changes[].toHash` on `repo:refs_changed`, and `previousFromHash`
+ * on `pr:from_ref_updated`.
+ */
+
+import {
+  type BitbucketApi,
+  type BitbucketBuildStatusInput,
+  type BitbucketClient,
+  type BitbucketProxyTransport,
+  type BitbucketRequestInput,
+  type BitbucketTokenProvider,
+  bitbucketApiBaseUrl,
+  createBitbucketApi,
+  createBitbucketClient,
+} from "./api.js";
+import {
+  type BitbucketCheck,
+  type BitbucketCheckCreateInput,
+  createBitbucketCheck,
+} from "./checks.js";
+import type {
+  BitbucketDialect,
+  BitbucketPullRequestComment,
+  BitbucketPullRequestEvent,
+  BitbucketPush,
+  BitbucketRepositoryRef,
+  BitbucketUser,
+} from "./types.js";
+
+/** Bitbucket operations exposed to hooks (`ctx.bitbucket`), bound to the repo. */
+export interface BitbucketHandle {
+  repository: BitbucketRepositoryRef;
+  /** Dialect-specific REST facade (PR, diff, comments, build status, files). */
+  readonly api: BitbucketApi;
+  /** Call a raw REST path under the dialect's base. Throws `BitbucketApiError`. */
+  request<T = unknown>(input: BitbucketRequestInput): Promise<T>;
+  /** Post a build status on the bound repo. */
+  setBuildStatus(input: BitbucketBuildStatusInput): Promise<unknown>;
+  /** Open a build status through the shared check lifecycle. */
+  createCheck(
+    input: Omit<BitbucketCheckCreateInput, "bitbucket">
+  ): Promise<BitbucketCheck>;
+}
+
+/**
+ * Build `ctx.bitbucket` for one delivery. Lazy: no credential is resolved
+ * until the first call, so channels without outbound Bitbucket access still
+ * dispatch. Proxy mode (`cursorAccount` + `--cursor-scm-proxy`) wins when
+ * the host bound a transport; otherwise direct access with `token` /
+ * `BITBUCKET_TOKEN` against the dialect's API base.
+ */
+export function buildBitbucketBinding(input: {
+  repository: BitbucketRepositoryRef;
+  proxy?: BitbucketProxyTransport;
+  token?: string | BitbucketTokenProvider;
+  apiBaseUrl?: string;
+  fetch?: typeof fetch;
+}): BitbucketHandle {
+  let client: BitbucketClient | undefined;
+  let api: BitbucketApi | undefined;
+  const getClient = (): BitbucketClient => {
+    client ??= createBitbucketClient({
+      proxy: input.proxy,
+      token: input.token,
+      // Never derive the credentialed host from the delivery's repository
+      // link: a signed-but-forged payload must not choose where the token
+      // goes. Data Center deploys set BITBUCKET_API_BASE_URL / apiBaseUrl.
+      apiBaseUrl:
+        input.apiBaseUrl ??
+        bitbucketApiBaseUrl({ dialect: input.repository.dialect }),
+      repo: input.repository.fullName,
+      fetch: input.fetch,
+    });
+    return client;
+  };
+  const getApi = (): BitbucketApi => {
+    api ??= createBitbucketApi(getClient(), input.repository);
+    return api;
+  };
+  return {
+    repository: input.repository,
+    get api() {
+      return getApi();
+    },
+    request: (request) => getClient().request(request),
+    setBuildStatus: (status) => getApi().setBuildStatus(status),
+    createCheck: (check) =>
+      createBitbucketCheck({ ...check, bitbucket: getApi() }),
+  };
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+export function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== ""
+    ? value.trim()
+    : undefined;
+}
+
+export function asPositiveInt(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string" && /^[1-9]\d*$/.test(value)) {
+    return Number(value);
+  }
+  return undefined;
+}
+
+function asBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+/** Data Center `links.self[0].href`; Cloud `links.html.href`. */
+function linkHref(links: unknown): string | undefined {
+  const record = asRecord(links);
+  const html = asNonEmptyString(asRecord(record?.html)?.href);
+  if (html !== undefined) {
+    return html;
+  }
+  const self = record?.self;
+  if (Array.isArray(self)) {
+    return asNonEmptyString(asRecord(self[0])?.href);
+  }
+  return asNonEmptyString(asRecord(self)?.href);
+}
+
+/** The pull-request record under either dialect's key. */
+export function bitbucketPullRequestRecord(
+  payload: Record<string, unknown>
+): Record<string, unknown> | undefined {
+  return asRecord(payload.pullrequest) ?? asRecord(payload.pullRequest);
+}
+
+/**
+ * Cloud bodies carry `pullrequest` / `repository.full_name`; Data Center
+ * bodies carry `pullRequest` / `repository.project.key`. Unknown shapes
+ * default to Cloud, the dialect the hosted ingress normalizes toward.
+ */
+export function bitbucketDialectOf(
+  payload: Record<string, unknown>
+): BitbucketDialect {
+  if (
+    asRecord(payload.pullRequest) !== undefined ||
+    asNonEmptyString(payload.eventKey) !== undefined ||
+    asRecord(asRecord(payload.repository)?.project) !== undefined
+  ) {
+    return "data-center";
+  }
+  return "cloud";
+}
+
+function repositoryFromRecord(
+  dialect: BitbucketDialect,
+  repository: Record<string, unknown> | undefined
+): BitbucketRepositoryRef | undefined {
+  if (repository === undefined) {
+    return undefined;
+  }
+  const htmlUrl = linkHref(repository.links);
+  const fullName = asNonEmptyString(repository.full_name);
+  if (fullName !== undefined) {
+    const [owner, ...rest] = fullName.split("/");
+    if (owner === undefined || rest.length === 0) {
+      return undefined;
+    }
+    const uuid = asNonEmptyString(repository.uuid);
+    return {
+      dialect,
+      fullName,
+      owner,
+      slug: rest.join("/"),
+      ...(uuid === undefined ? {} : { uuid }),
+      ...(htmlUrl === undefined ? {} : { htmlUrl }),
+    };
+  }
+  const projectKey = asNonEmptyString(asRecord(repository.project)?.key);
+  const slug = asNonEmptyString(repository.slug);
+  if (projectKey === undefined || slug === undefined) {
+    return undefined;
+  }
+  const id = asPositiveInt(repository.id);
+  return {
+    dialect,
+    fullName: `${projectKey}/${slug}`,
+    owner: projectKey,
+    slug,
+    ...(id === undefined ? {} : { id }),
+    ...(htmlUrl === undefined ? {} : { htmlUrl }),
+  };
+}
+
+/**
+ * Repository the delivery is about. Top-level `repository` (Cloud always;
+ * DC on `repo:*`), else the DC pull request's `toRef.repository`.
+ */
+export function bitbucketRepositoryFromPayload(
+  payload: Record<string, unknown>
+): BitbucketRepositoryRef | undefined {
+  const dialect = bitbucketDialectOf(payload);
+  return (
+    repositoryFromRecord(dialect, asRecord(payload.repository)) ??
+    repositoryFromRecord(
+      dialect,
+      asRecord(asRecord(bitbucketPullRequestRecord(payload)?.toRef)?.repository)
+    )
+  );
+}
+
+/** Cloud `{uuid, display_name, nickname}` or DC `{id, name, displayName}`. */
+export function bitbucketUser(value: unknown): BitbucketUser | undefined {
+  const record = asRecord(value);
+  if (record === undefined) {
+    return undefined;
+  }
+  // DC wraps PR authors as `{ user: {...}, role, approved }`.
+  const user = asRecord(record.user) ?? record;
+  const id =
+    asNonEmptyString(user.uuid) ??
+    asNonEmptyString(user.account_id) ??
+    (asPositiveInt(user.id) === undefined
+      ? undefined
+      : String(asPositiveInt(user.id)));
+  if (id === undefined) {
+    return undefined;
+  }
+  const displayName =
+    asNonEmptyString(user.display_name) ?? asNonEmptyString(user.displayName);
+  const username =
+    asNonEmptyString(user.nickname) ?? asNonEmptyString(user.name);
+  return {
+    id,
+    ...(displayName === undefined ? {} : { displayName }),
+    ...(username === undefined ? {} : { username }),
+  };
+}
+
+export function bitbucketPullRequestUrl(
+  repository: BitbucketRepositoryRef,
+  id: number,
+  explicit?: string
+): string {
+  if (explicit !== undefined) {
+    return explicit;
+  }
+  if (repository.dialect === "cloud") {
+    return `${repository.htmlUrl ?? `https://bitbucket.org/${repository.fullName}`}/pull-requests/${id}`;
+  }
+  return repository.htmlUrl === undefined
+    ? `projects/${repository.owner}/repos/${repository.slug}/pull-requests/${id}`
+    : `${repository.htmlUrl.replace(/\/browse\/?$/, "")}/pull-requests/${id}`;
+}
+
+/**
+ * Normalize the pull request from either dialect. `action` is the suffix of
+ * the Cloud-normalized event key (`pullrequest:created` → `created`).
+ */
+export function bitbucketPullRequestFromPayload(
+  repository: BitbucketRepositoryRef,
+  payload: Record<string, unknown>,
+  action: string
+): BitbucketPullRequestEvent | undefined {
+  const record = bitbucketPullRequestRecord(payload);
+  const id = asPositiveInt(record?.id);
+  if (record === undefined || id === undefined) {
+    return undefined;
+  }
+  const description =
+    record.description === null
+      ? null
+      : typeof record.description === "string"
+        ? record.description
+        : undefined;
+  const source = asRecord(record.source);
+  const destination = asRecord(record.destination);
+  const fromRef = asRecord(record.fromRef);
+  const toRef = asRecord(record.toRef);
+  const sourceBranch =
+    asNonEmptyString(asRecord(source?.branch)?.name) ??
+    asNonEmptyString(fromRef?.displayId);
+  const targetBranch =
+    asNonEmptyString(asRecord(destination?.branch)?.name) ??
+    asNonEmptyString(toRef?.displayId);
+  const headSha =
+    asNonEmptyString(asRecord(source?.commit)?.hash) ??
+    asNonEmptyString(fromRef?.latestCommit);
+  const previousHeadSha = asNonEmptyString(payload.previousFromHash);
+  const author = bitbucketUser(record.author);
+  const title = asNonEmptyString(record.title);
+  const state = asNonEmptyString(record.state);
+  const draft = asBoolean(record.draft);
+  return {
+    action,
+    id,
+    ...(title === undefined ? {} : { title }),
+    ...(description === undefined ? {} : { description }),
+    ...(state === undefined ? {} : { state }),
+    ...(draft === undefined ? {} : { draft }),
+    ...(sourceBranch === undefined ? {} : { sourceBranch }),
+    ...(targetBranch === undefined ? {} : { targetBranch }),
+    ...(headSha === undefined ? {} : { headSha }),
+    ...(previousHeadSha === undefined ? {} : { previousHeadSha }),
+    ...(author === undefined ? {} : { author }),
+    htmlUrl: bitbucketPullRequestUrl(repository, id, linkHref(record.links)),
+  };
+}
+
+/** Cloud `comment.content.raw` / DC `comment.text`. */
+export function bitbucketCommentFromPayload(
+  payload: Record<string, unknown>
+): BitbucketPullRequestComment | undefined {
+  const comment = asRecord(payload.comment);
+  const id = asPositiveInt(comment?.id);
+  const body =
+    typeof asRecord(comment?.content)?.raw === "string"
+      ? (asRecord(comment?.content)?.raw as string)
+      : typeof comment?.text === "string"
+        ? comment.text
+        : undefined;
+  if (comment === undefined || id === undefined || body === undefined) {
+    return undefined;
+  }
+  const author = bitbucketUser(comment.user ?? comment.author);
+  const htmlUrl = linkHref(comment.links);
+  const inlineRecord = asRecord(comment.inline);
+  const inline =
+    inlineRecord === undefined
+      ? undefined
+      : {
+          ...(asNonEmptyString(inlineRecord.path) === undefined
+            ? {}
+            : { path: asNonEmptyString(inlineRecord.path) }),
+          ...(typeof inlineRecord.to === "number"
+            ? { to: inlineRecord.to }
+            : {}),
+          ...(typeof inlineRecord.from === "number"
+            ? { from: inlineRecord.from }
+            : {}),
+        };
+  return {
+    id,
+    body,
+    ...(author === undefined ? {} : { author }),
+    ...(htmlUrl === undefined ? {} : { htmlUrl }),
+    ...(inline === undefined ? {} : { inline }),
+  };
+}
+
+/** Cloud `push.changes[]` (`new`/`old` targets) or DC `changes[]` (`toHash`/`fromHash`). */
+export function bitbucketPushFromPayload(
+  payload: Record<string, unknown>
+): BitbucketPush | undefined {
+  const cloudChanges = asRecord(payload.push)?.changes;
+  const changes = Array.isArray(cloudChanges)
+    ? cloudChanges
+    : Array.isArray(payload.changes)
+      ? payload.changes
+      : undefined;
+  if (changes === undefined) {
+    return undefined;
+  }
+  return {
+    changes: changes.flatMap((entry) => {
+      const change = asRecord(entry);
+      if (change === undefined) {
+        return [];
+      }
+      const next = asRecord(change.new);
+      const previous = asRecord(change.old);
+      const ref = asRecord(change.ref);
+      const name =
+        asNonEmptyString(next?.name) ??
+        asNonEmptyString(previous?.name) ??
+        asNonEmptyString(ref?.displayId);
+      const refId =
+        asNonEmptyString(change.refId) ??
+        asNonEmptyString(ref?.id) ??
+        (name === undefined ? undefined : `refs/heads/${name}`);
+      const type =
+        asNonEmptyString(next?.type) ??
+        asNonEmptyString(previous?.type) ??
+        asNonEmptyString(ref?.type)?.toLowerCase();
+      const before =
+        asNonEmptyString(asRecord(previous?.target)?.hash) ??
+        asNonEmptyString(change.fromHash);
+      const after =
+        asNonEmptyString(asRecord(next?.target)?.hash) ??
+        asNonEmptyString(change.toHash);
+      return [
+        {
+          ...(refId === undefined ? {} : { ref: refId }),
+          ...(name === undefined ? {} : { name }),
+          ...(before === undefined ? {} : { before }),
+          ...(after === undefined ? {} : { after }),
+          ...(type === undefined ? {} : { type }),
+        },
+      ];
+    }),
+  };
+}

package/src/channels/bitbucket/bitbucket-channel.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import {
+  allowAll,
+  defineChannel,
+  localDevStrict,
+  loopbackOnly,
+  POST,
+} from "../../channels.js";
+import { withPropagatingBackgroundErrors } from "../../internal/channel-dispatch.js";
+import { normalizeIdentity } from "../../internal/continuation-identity.js";
+import { isDevMode } from "../../internal/dev-mode.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import type { ChannelDefinition } from "../../types.js";
+import {
+  dispatchBitbucketWebhook,
+  handleBitbucketWebhookRequest,
+  parseBitbucketWebhookPayload,
+  resolveBitbucketWebhookSecret,
+} from "./bitbucket-webhook.js";
+import {
+  createPendingCursorBitbucketCredentials,
+  parseCursorBitbucketRepoScope,
+  registerBitbucketCursorAccountRuntime,
+} from "./cursor-account.js";
+import {
+  BITBUCKET_CHANNEL_KIND,
+  deriveBitbucketWebhookEvents,
+} from "./events.js";
+import {
+  type BitbucketChannelState,
+  emptyBitbucketChannelState,
+} from "./state.js";
+import type { BitbucketChannelOptions } from "./types.js";
+
+const bitbucketChannelOptionsByDefinition = new WeakMap<
+  object,
+  BitbucketChannelOptions
+>();
+
+export function getBitbucketChannelOptions(
+  definition: object
+): BitbucketChannelOptions | undefined {
+  return bitbucketChannelOptionsByDefinition.get(definition);
+}
+
+export function bitbucketChannel(
+  options: BitbucketChannelOptions = {}
+): ChannelDefinition<BitbucketChannelState> {
+  const routePath = options.path ?? "/";
+  // With a hook secret the `X-Hub-Signature` HMAC is the request auth
+  // (allowAll), matching GitHub HMAC + webhookSecret. Without one, prod stays
+  // loopback-strict; `--dev` admits loopback only. `isDevMode()` and the
+  // secret are read per request: channel modules construct at import time.
+  const auth = options.auth ?? [
+    (request, info) =>
+      (resolveBitbucketWebhookSecret(options) !== undefined
+        ? allowAll()
+        : isDevMode()
+          ? loopbackOnly()
+          : localDevStrict())(request, info),
+  ];
+
+  const channelOptions: BitbucketChannelOptions = { ...options };
+  if (channelOptions.continuation !== undefined) {
+    channelOptions.continuation = normalizeIdentity(
+      channelOptions.continuation,
+      BITBUCKET_CHANNEL_KIND
+    );
+  }
+  // `cursorAccount` routes `ctx.bitbucket` through the SCM proxy once the
+  // serve host binds the Cursor API key + transport (`--cursor-scm-proxy`).
+  const cursorAccount =
+    options.cursorAccount === undefined || options.cursorAccount === false
+      ? undefined
+      : {
+          credentials: createPendingCursorBitbucketCredentials(),
+          scope:
+            typeof options.cursorAccount === "object"
+              ? parseCursorBitbucketRepoScope(options.cursorAccount.repos)
+              : undefined,
+        };
+  const proxy = () => cursorAccount?.credentials.getProxyTransport();
+
+  const definition = defineChannel<BitbucketChannelState>({
+    auth,
+    state: emptyBitbucketChannelState(),
+    events: options.events ?? {},
+    onStart: options.onStart,
+    onStop: options.onStop,
+    meta: {
+      kind: BITBUCKET_CHANNEL_KIND,
+      bitbucketWebhookEvents: deriveBitbucketWebhookEvents(channelOptions),
+    },
+    routes: [
+      POST(routePath, {
+        bodySchema: z.unknown(),
+        description: "Bitbucket webhook ingress",
+        handler: async (request, args) =>
+          handleBitbucketWebhookRequest({
+            options: channelOptions,
+            request,
+            args,
+            proxy,
+          }),
+      }),
+    ],
+  });
+  bitbucketChannelOptionsByDefinition.set(definition, channelOptions);
+  if (cursorAccount !== undefined) {
+    registerBitbucketCursorAccountRuntime(definition, {
+      options: channelOptions,
+      ...cursorAccount,
+    });
+  }
+  attachHostedAdmissionAdapter(definition, {
+    kind: BITBUCKET_CHANNEL_KIND,
+    prepareArgs: withPropagatingBackgroundErrors,
+    dispatch: async ({ eventType, payload, deliveryId, args }) => {
+      const delivery = parseBitbucketWebhookPayload(payload, eventType);
+      if (delivery === null) {
+        return Response.json(
+          { ok: false, error: "invalid_bitbucket_payload" },
+          { status: 400 }
+        );
+      }
+      delivery.deliveryId = deliveryId;
+      return dispatchBitbucketWebhook({
+        options: channelOptions,
+        delivery,
+        args,
+        proxy,
+      });
+    },
+  });
+  return definition;
+}
+
+/** Minimal mount shape shared by `serve` / the `bitbucket` CLI. */
+export interface BitbucketAgentMountLike {
+  slug: string;
+  project: {
+    channels: Array<{
+      id: string;
+      definition: {
+        meta?: { kind?: string; bitbucketWebhookEvents?: readonly string[] };
+        routes?: ReadonlyArray<{ method: string; path: string }>;
+      };
+    }>;
+  };
+}
+
+export interface BitbucketChannelTarget {
+  slug: string;
+  channelId: string;
+  /** Route path under the channel (default `/`). */
+  routePath: string;
+  events: string[];
+}
+
+export function findBitbucketChannelTargets(
+  mounts: ReadonlyArray<BitbucketAgentMountLike>
+): BitbucketChannelTarget[] {
+  const targets: BitbucketChannelTarget[] = [];
+  for (const { slug, project } of mounts) {
+    for (const channel of project.channels) {
+      const meta = channel.definition.meta;
+      if (meta?.kind !== BITBUCKET_CHANNEL_KIND) {
+        continue;
+      }
+      const postRoute = (channel.definition.routes ?? []).find(
+        (route) => route.method === "POST"
+      );
+      targets.push({
+        slug,
+        channelId: channel.id,
+        routePath: postRoute?.path ?? "/",
+        events: [...(meta.bitbucketWebhookEvents ?? [])],
+      });
+    }
+  }
+  return targets;
+}