@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/bitbucket/types.ts

@@ -1,261 +0,0 @@
-import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
-import type {
-  AgentCloudOptions,
-  ArtifactsApi,
-  AuthContext,
-  AuthPolicy,
-  ChannelEventHandlers,
-  ChannelStartArgs,
-  HostContext,
-  SendMessageFn,
-} from "../../types.js";
-import type { BitbucketTokenProvider } from "./api.js";
-import type { BitbucketHandle } from "./binding.js";
-import type { BitbucketChannelState } from "./state.js";
-
-/**
- * Which Bitbucket sent the payload. Cloud bodies carry `pullrequest` and
- * `repository.uuid`; Data Center bodies carry `pullRequest` and
- * `repository.project.key`.
- */
-export type BitbucketDialect = "cloud" | "data-center";
-
-export interface BitbucketUser {
-  /** Cloud `uuid` (braces included) or Data Center numeric `id`. */
-  id: string;
-  displayName?: string;
-  /** Cloud `nickname` / Data Center `name`. */
-  username?: string;
-}
-
-export interface BitbucketRepositoryRef {
-  dialect: BitbucketDialect;
-  /**
-   * `workspace/repo` (Cloud) or `PROJECT/repo` (Data Center), as delivered.
-   * Continuation keys lowercase it; consumers should too when comparing.
-   */
-  fullName: string;
-  /** Workspace slug (Cloud) or project key (Data Center). */
-  owner: string;
-  slug: string;
-  /** Cloud `repository.uuid` (braces included). */
-  uuid?: string;
-  /** Data Center numeric repository id. */
-  id?: number;
-  /** Web URL when the payload carries one. */
-  htmlUrl?: string;
-}
-
-/** A pull request normalized from either dialect. */
-export interface BitbucketPullRequestEvent {
-  /**
-   * Cloud-normalized action: `created`, `updated`, `approved`, `unapproved`,
-   * `changes_request_created`, `fulfilled`, `rejected`.
-   */
-  action: string;
-  id: number;
-  title?: string;
-  description?: string | null;
-  /** `OPEN`, `MERGED`, `DECLINED`, `SUPERSEDED`. */
-  state?: string;
-  draft?: boolean;
-  sourceBranch?: string;
-  targetBranch?: string;
-  /** Source-branch head: Cloud `source.commit.hash` / DC `fromRef.latestCommit`. */
-  headSha?: string;
-  /** DC `previousFromHash` on `pr:from_ref_updated` — new commits were pushed. */
-  previousHeadSha?: string;
-  author?: BitbucketUser;
-  htmlUrl?: string;
-}
-
-export interface BitbucketPullRequestComment {
-  id: number;
-  body: string;
-  author?: BitbucketUser;
-  htmlUrl?: string;
-  /** Cloud `comment.inline` when the comment is anchored to a file. */
-  inline?: { path?: string; to?: number; from?: number };
-}
-
-export interface BitbucketPushChange {
-  ref?: string;
-  /** Branch / tag name. */
-  name?: string;
-  before?: string;
-  after?: string;
-  type?: string;
-}
-
-export interface BitbucketPush {
-  changes: BitbucketPushChange[];
-}
-
-export interface BitbucketEventContext {
-  /** `X-Request-UUID` (Cloud) / `X-Request-Id` (DC), when present. */
-  deliveryId?: string;
-  /** Cloud-normalized event key (`pullrequest:created`, `repo:push`, …). */
-  eventType: string;
-  /** Raw `X-Event-Key` as delivered (DC keys before normalization). */
-  rawEventType: string;
-  repository: BitbucketRepositoryRef;
-  pullRequestId?: number;
-  pullRequestUrl?: string;
-  /** Raw parsed payload record, for consumers whose normalization needs more. */
-  payload: Record<string, unknown>;
-  /** `actor` on the payload — who triggered the delivery. */
-  sender?: BitbucketUser;
-  /**
-   * Repo-bound Bitbucket API (`api`, `request`, `setBuildStatus`,
-   * `createCheck`) in the delivery's dialect. Routes through the Cursor SCM
-   * proxy under `cursorAccount` + `--cursor-scm-proxy`; otherwise uses
-   * {@link BitbucketChannelOptions.token} / `BITBUCKET_TOKEN` against the
-   * dialect's API base.
-   */
-  bitbucket: BitbucketHandle;
-  /**
-   * Channel `send`. Set on every delivery path (HTTP webhook, hosted
-   * admission) so a hook can start a turn itself instead of returning
-   * `{ auth, message }` or a deferred `{ task }`.
-   */
-  send?: SendMessageFn;
-  host: HostContext;
-  artifacts: ArtifactsApi;
-}
-
-export type BitbucketTurnDispatch = {
-  auth: AuthContext;
-  message?: string;
-  title?: string;
-  context?: readonly string[];
-};
-
-/** Bound per-delivery helpers passed to a {@link BitbucketTaskDispatch.task}. */
-export interface BitbucketTaskArgs {
-  send: SendMessageFn;
-  waitUntil: (promise: Promise<unknown>) => void;
-}
-
-/** Run a host-side handler after the webhook is acknowledged with a 202. */
-export type BitbucketTaskDispatch = {
-  task: (args: BitbucketTaskArgs) => void | Promise<void>;
-};
-
-export type BitbucketDispatch = BitbucketTurnDispatch | BitbucketTaskDispatch;
-
-export type BitbucketDispatchResult = BitbucketDispatch | null | Promise<BitbucketDispatch | null>;
-
-export type BitbucketPullRequestHook = (
-  ctx: BitbucketEventContext,
-  pullRequest: BitbucketPullRequestEvent,
-) => BitbucketDispatchResult;
-
-export type BitbucketPullRequestCommentHook = (
-  ctx: BitbucketEventContext,
-  comment: BitbucketPullRequestComment,
-  pullRequest: BitbucketPullRequestEvent,
-) => BitbucketDispatchResult;
-
-export type BitbucketPushHook = (
-  ctx: BitbucketEventContext,
-  push: BitbucketPush,
-) => BitbucketDispatchResult;
-
-export type BitbucketEventHook = (
-  ctx: BitbucketEventContext,
-  event: { eventType: string; rawEventType: string; payload: unknown },
-) => BitbucketDispatchResult;
-
-export type BitbucketCloudOptionsResolver = (
-  ctx: BitbucketEventContext,
-  pullRequest: BitbucketPullRequestEvent,
-) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
-
-/** One verified Bitbucket delivery handed to {@link dispatchBitbucketWebhook}. */
-export interface BitbucketWebhookDelivery {
-  /** Cloud-normalized event key (hosted admission passes the envelope's). */
-  eventType: string;
-  /** `X-Event-Key` as delivered. Defaults to {@link eventType}. */
-  rawEventType?: string;
-  payload: Record<string, unknown>;
-  deliveryId?: string;
-}
-
-export interface BitbucketChannelOptions {
-  /**
-   * Use the signed-in Cursor account for inbound Bitbucket events delivered
-   * by the Cursor backend. `true` takes repo scope from the deployment;
-   * `{ repos }` (`workspace/repo` or `PROJECT/repo`) makes the channel
-   * self-contained.
-   */
-  cursorAccount?: boolean | { repos: readonly string[] };
-  /**
-   * Access token (or provider) for direct `ctx.bitbucket` calls when not in
-   * proxy mode. Sent as `Authorization: Bearer`. Falls back to
-   * `BITBUCKET_TOKEN`.
-   */
-  token?: string | BitbucketTokenProvider;
-  /**
-   * REST base for direct `ctx.bitbucket` calls. Defaults to
-   * `BITBUCKET_API_BASE_URL`, else api.bitbucket.org 2.0 (Cloud). Data
-   * Center deploys must set one of these; the payload's repository link is
-   * never used to pick where the token is sent.
-   */
-  apiBaseUrl?: string;
-  /**
-   * Webhook secret for direct HTTP deliveries: `X-Hub-Signature`
-   * `sha256=<hmac>` over the raw body (both dialects). Falls back to
-   * `BITBUCKET_WEBHOOK_SECRET`. With a secret set the HMAC is the request
-   * auth; without one production stays loopback-strict and `serve --dev`
-   * admits unsigned loopback deliveries.
-   */
-  webhookSecret?: string | (() => string | undefined);
-  /**
-   * Optional repo allowlist (`workspace/repo` / `PROJECT/repo`,
-   * case-insensitive). Events from other repos are acked without a turn.
-   */
-  repos?: readonly string[];
-  /** Route auth chain; defaults follow {@link webhookSecret}. */
-  auth?: AuthPolicy[];
-  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
-  path?: string;
-  /**
-   * Pin the event keys this channel dispatches on (Cloud vocabulary; DC keys
-   * are normalized). Published as `meta.bitbucketWebhookEvents`. Defaults to
-   * the set derived from hooks.
-   */
-  webhookEvents?: readonly string[];
-  /**
-   * Continuation selector. Omit this to inherit the agent architecture's
-   * default. Set it explicitly only when migrating persisted identities.
-   */
-  continuation?: ContinuationIdentity;
-  /**
-   * Decide whether an inbound pull-request event starts a turn. Return
-   * `{ auth: defaultBitbucketAuth(ctx) }` to dispatch, `null` to ignore.
-   * Without this hook the channel dispatches on `created` and on `updated`
-   * that pushed commits (Data Center `previousFromHash` differs from the
-   * head; Cloud `pullrequest:updated` carries no diff and is not dispatched).
-   */
-  onPullRequest?: BitbucketPullRequestHook;
-  /** Opt-in `pullrequest:comment_created` handler. */
-  onPullRequestComment?: BitbucketPullRequestCommentHook;
-  /** Opt-in `repo:push` handler. No default dispatch. */
-  onPush?: BitbucketPushHook;
-  /**
-   * Catch-all for event keys without a typed hook (`repo:fork`,
-   * `issue:created`, …). NOT a fallback: typed events never reach it.
-   */
-  onEvent?: BitbucketEventHook;
-  /**
-   * Per-session cloud options. Pass `true` to attach the repo using the
-   * pull request's web URL, or a resolver for custom cloud options.
-   */
-  cloud?: boolean | AgentCloudOptions | BitbucketCloudOptionsResolver;
-  /** Channel stream-event handlers. */
-  events?: ChannelEventHandlers<BitbucketChannelState>;
-  /** Called once when the server mounts this channel. */
-  onStart?: (args: ChannelStartArgs) => void | Promise<void>;
-  /** Called when the server shuts down. */
-  onStop?: () => void | Promise<void>;
-}

package/src/channels/change-monitors/change-monitors-channel.ts

@@ -1,63 +0,0 @@
-import { z } from "zod";
-import { createFactoryResourceChannel } from "../../internal/factory-resource-channel.js";
-import type { ChannelDefinition } from "../../types.js";
-import {
-  CHECKPOINT_CREATED_EVENT_TYPE,
-  type ChangeMonitorsChannelOptions,
-  type CheckpointCreatedEvent,
-} from "./types.js";
-
-const checkpointResourceSchema = z
-  .object({
-    name: z.string().min(1),
-    deployment: z.string().min(1),
-    runKey: z.string().min(1),
-    evidenceSummary: z.string().min(1),
-    planRevision: z.string().optional(),
-    createTime: z.string().min(1).optional(),
-    description: z.string().optional(),
-    clear: z.object({}).passthrough().optional(),
-    issues: z
-      .object({ title: z.string().min(1) })
-      .passthrough()
-      .optional(),
-    inconclusive: z.object({}).passthrough().optional(),
-    deferred: z
-      .object({ reason: z.string().min(1) })
-      .passthrough()
-      .optional(),
-  })
-  .passthrough()
-  .refine(
-    checkpoint =>
-      [checkpoint.clear, checkpoint.issues, checkpoint.inconclusive, checkpoint.deferred].filter(
-        arm => arm !== undefined,
-      ).length === 1,
-    { message: "checkpoint must have exactly one result arm" },
-  );
-
-const checkpointCreatedEventSchema: z.ZodType<CheckpointCreatedEvent> = z.object({
-  eventId: z.string().min(1),
-  eventType: z.literal(CHECKPOINT_CREATED_EVENT_TYPE),
-  teamId: z.string().min(1),
-  occurredAtMs: z.number().int().nonnegative(),
-  checkpoint: checkpointResourceSchema,
-});
-
-const pack = createFactoryResourceChannel({
-  kind: "change_monitors",
-  eventTypes: [CHECKPOINT_CREATED_EVENT_TYPE],
-  eventSchema: checkpointCreatedEventSchema,
-  replayDescription: "Replay a Change Monitor checkpoint-created event.",
-  invalidError: "invalid change-monitor checkpoint event",
-});
-
-export function changeMonitorsChannel(options: ChangeMonitorsChannelOptions): ChannelDefinition {
-  return pack.channel(options);
-}
-
-export function getChangeMonitorsChannelOptions(
-  definition: object,
-): ChangeMonitorsChannelOptions | undefined {
-  return pack.getOptions(definition);
-}

package/src/channels/change-monitors/index.ts

@@ -1,8 +0,0 @@
-export { changeMonitorsChannel } from "./change-monitors-channel.js";
-export type {
-  ChangeMonitorsChannelOptions,
-  CheckpointCreatedEvent,
-  CheckpointCreatedEventType,
-  CheckpointResource,
-} from "./types.js";
-export { CHECKPOINT_CREATED_EVENT_TYPE } from "./types.js";

package/src/channels/change-monitors/types.ts

@@ -1,42 +0,0 @@
-import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
-import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
-
-export const CHECKPOINT_CREATED_EVENT_TYPE = "checkpoint.created" as const;
-
-export type CheckpointCreatedEventType = typeof CHECKPOINT_CREATED_EVENT_TYPE;
-
-/**
- * Factory Checkpoint JSON (camelCase proto JSON). Exactly one result arm is
- * set: `clear`, `issues`, `inconclusive`, or `deferred`. The channel does not pre-filter.
- */
-export type CheckpointResource = {
-  name: string;
-  deployment: string;
-  runKey: string;
-  evidenceSummary: string;
-  planRevision?: string;
-  createTime?: string;
-  description?: string;
-  clear?: Record<string, unknown>;
-  issues?: { title: string };
-  inconclusive?: Record<string, unknown>;
-  deferred?: { reason: string };
-};
-
-/** Factory `checkpoint.created` for every Change Monitor Checkpoint create. */
-export type CheckpointCreatedEvent = {
-  eventId: string;
-  eventType: CheckpointCreatedEventType;
-  teamId: string;
-  occurredAtMs: number;
-  checkpoint: CheckpointResource;
-};
-
-export type ChangeMonitorsChannelOptions = {
-  onEvent: (event: CheckpointCreatedEvent, args: ChannelHandlerArgs) => Promise<unknown> | unknown;
-  continuation?: ContinuationIdentity;
-  path?: string;
-  auth?: ChannelDefinition["auth"];
-  onStart?: ChannelDefinition["onStart"];
-  onStop?: ChannelDefinition["onStop"];
-};

package/src/channels/checks.ts

@@ -1,185 +0,0 @@
-/**
- * CI checks, shared across SCMs.
- *
- * The check lifecycle lives here once: `openCiCheck` opens a run (defaults
- * `in_progress`, stamps `startedAt`), the returned {@link CiCheck} handle
- * patches it (`update`) and completes it (`conclude`, stamps `completedAt`),
- * and `resumeCiCheck` rebuilds a handle after a restart. Each SCM plugs in
- * with one {@link CiCheckWriter} — a function that persists a single desired
- * check state on its API (GitHub Checks API create/patch, Origin's keyed
- * upsert, …) and owns any transport state such as a server-assigned run id.
- *
- * Agent code should usually stay one level higher, on {@link CiChecksClient}:
- * both `ctx.github` and `ctx.origin` satisfy it, so a check reporter written
- * once works on either forge:
- *
- * ```ts
- * async function reportCheck(checks: CiChecksClient, sha: string) {
- *   const check = await checks.createCheck({ name: "My Agent", sha });
- *   // …do the work…
- *   await check.conclude({
- *     conclusion: "success",
- *     output: { title: "Done", summary: "All good." },
- *   });
- * }
- * ```
- *
- * {@link CiCheckConclusion} is the common subset every SCM accepts; an SCM
- * with extras widens it through the generic parameter (e.g. Origin's
- * `CiCheck<CiCheckConclusion | "stale">`).
- */
-
-/** Output shown on the check page. */
-export interface CiCheckOutput {
-  /** Heading on the check page. */
-  title: string;
-  /** Markdown body (supports links, e.g. `[View session](…)`). */
-  summary: string;
-  /** Optional detailed markdown body. */
-  text?: string;
-}
-
-export type CiCheckStatus = "queued" | "in_progress" | "completed";
-
-/** Final results accepted by every SCM. */
-export type CiCheckConclusion =
-  | "action_required"
-  | "cancelled"
-  | "failure"
-  | "neutral"
-  | "skipped"
-  | "success"
-  | "timed_out";
-
-export interface CiCheckUpdateInput<TConclusion extends string = CiCheckConclusion> {
-  status?: CiCheckStatus;
-  conclusion?: TConclusion;
-  detailsUrl?: string;
-  output?: CiCheckOutput;
-}
-
-export interface CiCheckConcludeInput<TConclusion extends string = CiCheckConclusion> {
-  /** Final result shown in the merge box. */
-  conclusion: TConclusion;
-  detailsUrl?: string;
-  output?: CiCheckOutput;
-}
-
-/** SCM-side reference to a check run, when the SCM reports one. */
-export interface CiCheckRef {
-  /** Server-assigned run id (GitHub check-run number, Origin `cr_…`). */
-  id?: number | string;
-  /** Web URL of the check run page. */
-  url?: string;
-}
-
-/** A created check run, whichever SCM it lives on. */
-export interface CiCheck<TConclusion extends string = CiCheckConclusion> {
-  /** Patch status / output / details link while the check is running. */
-  update(input: CiCheckUpdateInput<TConclusion>): Promise<void>;
-  /** Complete the check with a conclusion (stamps `completedAt`). */
-  conclude(input: CiCheckConcludeInput<TConclusion>): Promise<void>;
-}
-
-export interface CiCheckCreateInput {
-  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
-  name: string;
-  /** Commit the check attaches to (usually the PR head SHA). */
-  sha: string;
-  /**
-   * Check suite the check files under, on forges that have one. Origin
-   * renders every check as `suite / check` and groups the checks tab by
-   * suite, so name it after the posting app (GitHub groups an app's checks
-   * under the app); without it the suite mirrors the check name. GitHub,
-   * GitLab and Bitbucket have no app-named suite and ignore it.
-   */
-  suite?: { name?: string };
-  /** Initial status. Defaults to `"in_progress"`. */
-  status?: "queued" | "in_progress";
-  /** "Details" link on the check, e.g. the agent session run URL. */
-  detailsUrl?: string;
-  /** Title + markdown summary shown on the check page. */
-  output?: CiCheckOutput;
-}
-
-/**
- * Anything that can open a CI check on its bound repository — `ctx.github`,
- * `ctx.origin`, or the `bindOriginChecks` adapter.
- */
-export interface CiChecksClient<TConclusion extends string = CiCheckConclusion> {
-  createCheck(input: CiCheckCreateInput): Promise<CiCheck<TConclusion>>;
-}
-
-/** One desired check state for a writer to persist. */
-export interface CiCheckWrite<
-  TConclusion extends string = CiCheckConclusion,
-> extends CiCheckUpdateInput<TConclusion> {
-  startedAt?: string;
-  completedAt?: string;
-}
-
-/**
- * The per-SCM extension point: persist one {@link CiCheckWrite} on the SCM
- * (create-then-patch, keyed upsert, …). Bound to a repo + check identity at
- * construction; owns transport state (e.g. the created run id) across calls.
- * May return a {@link CiCheckRef} to expose on the handle.
- */
-export type CiCheckWriter<TConclusion extends string = CiCheckConclusion> = (
-  write: CiCheckWrite<TConclusion>,
-) => Promise<CiCheckRef | undefined>;
-
-/**
- * Open a check run through `writer` and return a handle for later updates.
- * SCM modules wrap this (`createGitHubCheck`, `createOriginCheck`); channels
- * expose it repo-bound as `ctx.github.createCheck` / `ctx.origin.createCheck`.
- */
-export async function openCiCheck<TConclusion extends string = CiCheckConclusion>(
-  writer: CiCheckWriter<TConclusion>,
-  input?: Pick<CiCheckCreateInput, "status" | "detailsUrl" | "output">,
-): Promise<CiCheck<TConclusion> & CiCheckRef> {
-  const ref = await writer({
-    status: input?.status ?? "in_progress",
-    startedAt: new Date().toISOString(),
-    detailsUrl: input?.detailsUrl,
-    output: input?.output,
-  });
-  return resumeCiCheck(writer, ref);
-}
-
-/**
- * Rebuild a {@link CiCheck} handle around an existing run (e.g. after a
- * process restart). No write happens until the first update.
- */
-export function resumeCiCheck<TConclusion extends string = CiCheckConclusion>(
-  writer: CiCheckWriter<TConclusion>,
-  ref?: CiCheckRef,
-): CiCheck<TConclusion> & CiCheckRef {
-  let id = ref?.id;
-  let url = ref?.url;
-  const write = async (write: CiCheckWrite<TConclusion>): Promise<void> => {
-    const next = await writer(write);
-    id = next?.id ?? id;
-    url = next?.url ?? url;
-  };
-  return {
-    get id() {
-      return id;
-    },
-    get url() {
-      return url;
-    },
-    update: update =>
-      write({
-        ...update,
-        completedAt: update.status === "completed" ? new Date().toISOString() : undefined,
-      }),
-    conclude: conclude =>
-      write({
-        status: "completed",
-        conclusion: conclude.conclusion,
-        completedAt: new Date().toISOString(),
-        detailsUrl: conclude.detailsUrl,
-        output: conclude.output,
-      }),
-  };
-}