@cursor/bdk 0.2.3 → 0.2.5

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

@@ -1,519 +0,0 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
-import {
-  acknowledgeTask,
-  isTaskDispatch,
-  skipped,
-  turnStarted,
-} from "../../internal/channel-dispatch.js";
-import { continuationSource } from "../../internal/continuation-identity.js";
-import { bindLocalIngressSend } from "../../internal/local-ingress.js";
-import type { AgentCloudOptions, ChannelHandlerArgs, JsonValue } from "../../types.js";
-import type { BitbucketProxyTransport } from "./api.js";
-import {
-  asNonEmptyString,
-  asPositiveInt,
-  asRecord,
-  bitbucketCommentFromPayload,
-  bitbucketPullRequestFromPayload,
-  bitbucketPullRequestRecord,
-  bitbucketPullRequestUrl,
-  bitbucketPushFromPayload,
-  bitbucketRepositoryFromPayload,
-  bitbucketUser,
-  buildBitbucketBinding,
-} from "./binding.js";
-import {
-  defaultBitbucketPullRequestDispatch,
-  defaultBitbucketPullRequestMessage,
-  defaultBitbucketTitle,
-} from "./defaults.js";
-import {
-  BITBUCKET_CHANNEL_KIND,
-  BITBUCKET_PULL_REQUEST_EVENTS,
-  normalizeBitbucketEventKey,
-} from "./events.js";
-import { type BitbucketChannelState, bitbucketChannelStateForEvent } from "./state.js";
-import type {
-  BitbucketChannelOptions,
-  BitbucketDispatch,
-  BitbucketEventContext,
-  BitbucketPullRequestEvent,
-  BitbucketTurnDispatch,
-  BitbucketWebhookDelivery,
-} from "./types.js";
-
-/** `BITBUCKET_WEBHOOK_SECRET` fallback for {@link BitbucketChannelOptions.webhookSecret}. */
-export function envBitbucketWebhookSecret(): string | undefined {
-  const value = process.env.BITBUCKET_WEBHOOK_SECRET?.trim();
-  return value === undefined || value === "" ? undefined : value;
-}
-
-export function resolveBitbucketWebhookSecret(
-  options: Pick<BitbucketChannelOptions, "webhookSecret">,
-): string | undefined {
-  const authored =
-    typeof options.webhookSecret === "function" ? options.webhookSecret() : options.webhookSecret;
-  const trimmed = authored?.trim();
-  return trimmed === undefined || trimmed === "" ? envBitbucketWebhookSecret() : trimmed;
-}
-
-const SIGNATURE_PREFIX = "sha256=";
-
-/** The `X-Hub-Signature` value Bitbucket sends for a raw body. */
-export function signBitbucketWebhookBody(rawBody: string | Buffer, secret: string): string {
-  return `${SIGNATURE_PREFIX}${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
-}
-
-/**
- * Both dialects sign the raw body with HMAC-SHA256 in `X-Hub-Signature`
- * (`sha256=<hex>`, GitHub-shaped). Constant-time compare; a missing or
- * malformed header is a plain `false`.
- */
-export function verifyBitbucketWebhookSignature(
-  rawBody: string | Buffer,
-  signatureHeader: string | null | undefined,
-  secret: string,
-): boolean {
-  if (
-    signatureHeader === null ||
-    signatureHeader === undefined ||
-    !signatureHeader.startsWith(SIGNATURE_PREFIX)
-  ) {
-    return false;
-  }
-  const provided = Buffer.from(signatureHeader, "utf8");
-  const computed = Buffer.from(signBitbucketWebhookBody(rawBody, secret), "utf8");
-  return provided.length === computed.length && timingSafeEqual(provided, computed);
-}
-
-/**
- * Accept a raw Bitbucket payload plus the event key. The key comes from
- * `X-Event-Key` (HTTP) or the hosted envelope; Data Center bodies also carry
- * it as `eventKey`. Data Center keys are normalized to the Cloud vocabulary.
- *
- * The body's `eventKey` is authoritative when present: `X-Hub-Signature`
- * covers the body but not the header, so a captured signed Data Center
- * delivery must not be re-dispatched as a different event by rewriting the
- * header. A header that disagrees with the signed body rejects the delivery.
- *
- * Cloud bodies carry no `eventKey`, but each event family has a signed
- * discriminator object (`comment`, `approval`, `changes_request`, `push`).
- * A header naming a family the body does not match — e.g. a signed
- * `pullrequest:comment_created` body replayed as `pullrequest:created` —
- * is rejected the same way. `created` vs `updated` bodies are shape-identical
- * and cannot be told apart without the key.
- */
-export function parseBitbucketWebhookPayload(
-  payload: unknown,
-  eventKey?: string | null,
-): BitbucketWebhookDelivery | null {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return null;
-  }
-  const fromBody = asNonEmptyString(record.eventKey);
-  const fromHeader = eventKey?.trim() || undefined;
-  if (
-    fromBody !== undefined &&
-    fromHeader !== undefined &&
-    normalizeBitbucketEventKey(fromBody) !== normalizeBitbucketEventKey(fromHeader)
-  ) {
-    return null;
-  }
-  const raw = fromBody ?? fromHeader;
-  if (raw === undefined) {
-    return null;
-  }
-  const eventType = normalizeBitbucketEventKey(raw);
-  if (fromBody === undefined && bitbucketCloudEventFamily(eventType) !== cloudBodyFamily(record)) {
-    return null;
-  }
-  return {
-    eventType,
-    rawEventType: raw,
-    payload: record,
-  };
-}
-
-type BitbucketCloudEventFamily =
-  | "approval"
-  | "changes_request"
-  | "comment"
-  | "other"
-  | "pull_request"
-  | "push";
-
-/** Event family a Cloud key belongs to, by its signed body discriminator. */
-function bitbucketCloudEventFamily(eventType: string): BitbucketCloudEventFamily {
-  if (eventType.startsWith("repo:")) {
-    return eventType === "repo:push" ? "push" : "other";
-  }
-  if (!eventType.startsWith("pullrequest:")) {
-    return "other";
-  }
-  const action = eventType.slice("pullrequest:".length);
-  if (action.startsWith("comment_")) {
-    return "comment";
-  }
-  if (action === "approved" || action === "unapproved") {
-    return "approval";
-  }
-  if (action.startsWith("changes_request_")) {
-    return "changes_request";
-  }
-  return "pull_request";
-}
-
-/** Event family a Cloud body proves by the discriminator object it carries. */
-function cloudBodyFamily(record: Record<string, unknown>): BitbucketCloudEventFamily {
-  if (asRecord(record.comment) !== undefined) {
-    return "comment";
-  }
-  if (asRecord(record.approval) !== undefined) {
-    return "approval";
-  }
-  if (asRecord(record.changes_request) !== undefined) {
-    return "changes_request";
-  }
-  if (asRecord(record.push) !== undefined) {
-    return "push";
-  }
-  return asRecord(record.pullrequest) !== undefined ? "pull_request" : "other";
-}
-
-function configuredRepoAllowlist(
-  options: BitbucketChannelOptions,
-): ReadonlySet<string> | undefined {
-  const repos: string[] = [];
-  if (options.repos !== undefined) {
-    repos.push(...options.repos);
-  }
-  if (typeof options.cursorAccount === "object") {
-    repos.push(...options.cursorAccount.repos);
-  }
-  const normalized = repos
-    .map(repo =>
-      repo
-        .trim()
-        .replace(/^\/+|\/+$/g, "")
-        .toLowerCase(),
-    )
-    .filter(Boolean);
-  return normalized.length === 0 ? undefined : new Set(normalized);
-}
-
-function isPullRequestEvent(eventType: string): boolean {
-  return (BITBUCKET_PULL_REQUEST_EVENTS as readonly string[]).includes(eventType);
-}
-
-export function parseBitbucketEventContext(
-  delivery: BitbucketWebhookDelivery,
-): Omit<BitbucketEventContext, "host" | "artifacts" | "bitbucket" | "send"> | null {
-  const repository = bitbucketRepositoryFromPayload(delivery.payload);
-  if (repository === undefined) {
-    return null;
-  }
-  const pullRequestRecord = bitbucketPullRequestRecord(delivery.payload);
-  const pullRequestId = asPositiveInt(pullRequestRecord?.id);
-  return {
-    deliveryId: delivery.deliveryId,
-    eventType: delivery.eventType,
-    rawEventType: delivery.rawEventType ?? delivery.eventType,
-    repository,
-    ...(pullRequestId === undefined
-      ? {}
-      : {
-          pullRequestId,
-          pullRequestUrl: bitbucketPullRequestUrl(
-            repository,
-            pullRequestId,
-            asNonEmptyString(asRecord(asRecord(pullRequestRecord?.links)?.html)?.href),
-          ),
-        }),
-    payload: delivery.payload,
-    sender: bitbucketUser(delivery.payload.actor),
-  };
-}
-
-function invalidPayload(error: string): Response {
-  return Response.json({ ok: false, error }, { status: 400 });
-}
-
-async function startTurn(input: {
-  options: BitbucketChannelOptions;
-  args: ChannelHandlerArgs;
-  ctx: BitbucketEventContext;
-  message: string;
-  dispatch: BitbucketTurnDispatch;
-  cloud?: AgentCloudOptions;
-  state: BitbucketChannelState;
-}): Promise<Response> {
-  const source = continuationSource(input.options.continuation, "bitbucket");
-  const session = await input.args.send(input.message, {
-    auth: input.dispatch.auth,
-    // v1 agents (omitted continuation resolves to `none/v1`) keep one
-    // engine-minted conversation per pull request; v2 takes the CP stamp.
-    ...(source === "engine" && input.ctx.pullRequestId !== undefined
-      ? {
-          continuationToken: `bitbucket-pr:${input.ctx.repository.fullName.toLowerCase()}#${input.ctx.pullRequestId}`,
-        }
-      : {}),
-    title: input.dispatch.title ?? defaultBitbucketTitle(input.ctx),
-    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
-    state: input.state as unknown as JsonValue,
-    refreshState: input.state as unknown as JsonValue,
-  });
-  return turnStarted(session);
-}
-
-async function resolveCloudOptions(
-  cloud: BitbucketChannelOptions["cloud"],
-  ctx: BitbucketEventContext,
-  pullRequest: BitbucketPullRequestEvent,
-): Promise<AgentCloudOptions | undefined> {
-  if (cloud === undefined || cloud === false) {
-    return undefined;
-  }
-  if (cloud === true) {
-    const url =
-      ctx.repository.htmlUrl ??
-      (ctx.repository.dialect === "cloud"
-        ? `https://bitbucket.org/${ctx.repository.fullName}`
-        : undefined);
-    if (url === undefined) {
-      return undefined;
-    }
-    return {
-      repos: [
-        {
-          url,
-          prUrl: pullRequest.htmlUrl,
-          startingRef: pullRequest.headSha,
-        },
-      ],
-    };
-  }
-  if (typeof cloud === "function") {
-    return await cloud(ctx, pullRequest);
-  }
-  return cloud;
-}
-
-async function applyDispatch(input: {
-  options: BitbucketChannelOptions;
-  args: ChannelHandlerArgs;
-  ctx: BitbucketEventContext;
-  dispatch: BitbucketDispatch | null;
-  extra: Record<string, unknown>;
-  message: string;
-  cloud?: AgentCloudOptions;
-  headSha?: string;
-  triggeringCommentId?: number;
-}): Promise<Response> {
-  if (input.dispatch === null) {
-    return skipped("not_dispatched", input.extra);
-  }
-  if (isTaskDispatch(input.dispatch)) {
-    return acknowledgeTask(input.args, BITBUCKET_CHANNEL_KIND, input.dispatch, input.extra);
-  }
-  const message = [input.dispatch.message ?? input.message, ...(input.dispatch.context ?? [])].join(
-    "\n",
-  );
-  return startTurn({
-    options: input.options,
-    args: input.args,
-    ctx: input.ctx,
-    message,
-    dispatch: input.dispatch,
-    cloud: input.cloud,
-    state: bitbucketChannelStateForEvent({
-      repository: input.ctx.repository,
-      pullRequestId: input.ctx.pullRequestId,
-      headSha: input.headSha,
-      deliveryId: input.ctx.deliveryId,
-      eventType: input.ctx.eventType,
-      triggeringCommentId: input.triggeringCommentId,
-    }),
-  });
-}
-
-/**
- * Run the authored hooks for one Bitbucket delivery and `send()` the turn.
- * Callers own delivery auth: the HTTP route verifies `X-Hub-Signature`;
- * hosted admission arrives verified. The v2 mailbox is stamped upstream
- * (local CP or hosted ingress), never here.
- */
-export async function dispatchBitbucketWebhook(input: {
-  options: BitbucketChannelOptions;
-  delivery: BitbucketWebhookDelivery;
-  args: ChannelHandlerArgs;
-  /** Host-bound SCM-proxy transport (`cursorAccount` + `--cursor-scm-proxy`). */
-  proxy?: () => BitbucketProxyTransport | undefined;
-}): Promise<Response> {
-  const { eventType, payload } = input.delivery;
-  const parsed = parseBitbucketEventContext(input.delivery);
-  if (parsed === null) {
-    return invalidPayload("invalid_bitbucket_payload");
-  }
-  const args = input.args;
-  const ctx: BitbucketEventContext = {
-    ...parsed,
-    bitbucket: buildBitbucketBinding({
-      repository: parsed.repository,
-      proxy: input.proxy?.(),
-      token: input.options.token,
-      apiBaseUrl: input.options.apiBaseUrl,
-    }),
-    host: args.host,
-    artifacts: args.artifacts,
-    send: args.send,
-  };
-  const allowlist = configuredRepoAllowlist(input.options);
-  if (allowlist !== undefined && !allowlist.has(ctx.repository.fullName.toLowerCase())) {
-    return skipped("repo_not_allowed", { repo: ctx.repository.fullName });
-  }
-  const extra = { event: eventType, rawEvent: ctx.rawEventType };
-
-  if (isPullRequestEvent(eventType)) {
-    const action = eventType.slice("pullrequest:".length);
-    const pullRequest = bitbucketPullRequestFromPayload(ctx.repository, payload, action);
-    if (pullRequest === undefined) {
-      return invalidPayload("invalid_bitbucket_pull_request_payload");
-    }
-    const dispatch =
-      input.options.onPullRequest === undefined
-        ? defaultBitbucketPullRequestDispatch(ctx, pullRequest)
-        : await input.options.onPullRequest(ctx, pullRequest);
-    return applyDispatch({
-      options: input.options,
-      args,
-      ctx,
-      dispatch,
-      extra: { ...extra, action },
-      message: defaultBitbucketPullRequestMessage(ctx, pullRequest),
-      cloud: await resolveCloudOptions(input.options.cloud, ctx, pullRequest),
-      headSha: pullRequest.headSha,
-    });
-  }
-
-  switch (eventType) {
-    case "pullrequest:comment_created": {
-      if (input.options.onPullRequestComment === undefined) {
-        return skipped("no_handler", extra);
-      }
-      const comment = bitbucketCommentFromPayload(payload);
-      const pullRequest = bitbucketPullRequestFromPayload(
-        ctx.repository,
-        payload,
-        "comment_created",
-      );
-      if (comment === undefined || pullRequest === undefined) {
-        return invalidPayload("invalid_bitbucket_comment_payload");
-      }
-      const dispatch = await input.options.onPullRequestComment(ctx, comment, pullRequest);
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra,
-        message: `Bitbucket comment on ${ctx.repository.fullName}#${pullRequest.id}`,
-        headSha: pullRequest.headSha,
-        triggeringCommentId: comment.id,
-      });
-    }
-    case "repo:push": {
-      if (input.options.onPush === undefined) {
-        return skipped("no_handler", extra);
-      }
-      const push = bitbucketPushFromPayload(payload);
-      if (push === undefined) {
-        return invalidPayload("invalid_bitbucket_push_payload");
-      }
-      const dispatch = await input.options.onPush(ctx, push);
-      const first = push.changes[0];
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra,
-        message: `Bitbucket push to ${ctx.repository.fullName}${first?.name === undefined ? "" : ` ${first.name}`}`,
-        headSha: first?.after,
-      });
-    }
-    default: {
-      if (input.options.onEvent === undefined) {
-        return skipped("unsupported_event", extra);
-      }
-      const dispatch = await input.options.onEvent(ctx, {
-        eventType,
-        rawEventType: ctx.rawEventType,
-        payload,
-      });
-      return applyDispatch({
-        options: input.options,
-        args,
-        ctx,
-        dispatch,
-        extra,
-        message: `Bitbucket ${eventType} event on ${ctx.repository.fullName}`,
-      });
-    }
-  }
-}
-
-/**
- * HTTP entry for a single agent's Bitbucket channel: `X-Hub-Signature` HMAC
- * when a secret is configured, then {@link dispatchBitbucketWebhook}.
- * Without a secret the route auth owns admission (`serve --dev` admits
- * loopback only; production stays loopback-strict).
- */
-export async function handleBitbucketWebhookRequest(input: {
-  options: BitbucketChannelOptions;
-  request: Request;
-  args: ChannelHandlerArgs;
-  /** When true, skip the HMAC check even if a secret is configured. */
-  skipSignatureVerification?: boolean;
-  proxy?: () => BitbucketProxyTransport | undefined;
-}): Promise<Response> {
-  const bodyText = await input.request.text();
-  const secret = resolveBitbucketWebhookSecret(input.options);
-  if (secret !== undefined && input.skipSignatureVerification !== true) {
-    if (
-      !verifyBitbucketWebhookSignature(
-        bodyText,
-        input.request.headers.get("x-hub-signature"),
-        secret,
-      )
-    ) {
-      return Response.json({ ok: false, error: "invalid_signature" }, { status: 401 });
-    }
-  }
-
-  let payload: unknown;
-  try {
-    payload = JSON.parse(bodyText) as unknown;
-  } catch {
-    return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
-  }
-  const delivery = parseBitbucketWebhookPayload(payload, input.request.headers.get("x-event-key"));
-  if (delivery === null) {
-    return invalidPayload("invalid_bitbucket_payload");
-  }
-  delivery.deliveryId =
-    input.request.headers.get("x-request-uuid") ??
-    input.request.headers.get("x-request-id") ??
-    undefined;
-  return dispatchBitbucketWebhook({
-    options: input.options,
-    delivery,
-    proxy: input.proxy,
-    args: bindLocalIngressSend(input.args, {
-      identity: input.options.continuation,
-      kind: BITBUCKET_CHANNEL_KIND,
-      eventType: delivery.eventType,
-      payload: delivery.payload,
-    }),
-  });
-}

package/src/channels/bitbucket/checks.ts

@@ -1,146 +0,0 @@
-/**
- * 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 }),
-  };
-}