@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/bitbucket/binding.ts

@@ -1,417 +0,0 @@
-/**
- * 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}`;
-}
-
-/** Absolute PR URL, or undefined when a Data Center payload has no repo URL. */
-export function bitbucketAbsolutePullRequestUrl(
-  repository: BitbucketRepositoryRef,
-  id: number,
-  explicit?: string,
-): string | undefined {
-  if (explicit !== undefined) {
-    return explicit;
-  }
-  if (repository.dialect === "cloud") {
-    return `https://bitbucket.org/${repository.fullName}/pull-requests/${id}`;
-  }
-  return repository.htmlUrl === undefined
-    ? undefined
-    : `${repository.htmlUrl.replace(/\/+$/, "").replace(/\/browse$/, "")}/pull-requests/${id}`;
-}
-
-/** Whether a Data Center `updated` payload publishes a draft pull request. */
-export function bitbucketDraftMarkedReady(
-  payload: Record<string, unknown>,
-  draft: boolean | undefined,
-): boolean {
-  return payload.previousDraft === true && draft === false;
-}
-
-/**
- * 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

@@ -1,162 +0,0 @@
-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;
-}