@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/gitlab/replay.ts

@@ -1,328 +0,0 @@
-/**
- * Synthesize GitLab webhook payloads from data you can *read* about a merge
- * request, so `agent-sdk gitlab replay` can exercise a `gitlabChannel()`
- * without Maintainer access to the project hook and without a tunnel.
- *
- * Payloads are shaped to satisfy the channel's parsers (`gitlab-webhook.ts`);
- * `undefined` fields are dropped by `JSON.stringify` before delivery.
- */
-
-/** A parsed merge request reference. */
-export interface GitLabMrRef {
-  /** `https://gitlab.com` or the self-managed origin. */
-  origin: string;
-  /** `group/sub/project` as written (GitLab paths keep their case). */
-  projectPath: string;
-  iid: number;
-  /** `<origin>/<projectPath>/-/merge_requests/<iid>`. */
-  url: string;
-  /** `group/project!N`. */
-  label: string;
-}
-
-/**
- * Parse an MR URL (`https://<host>/<group>/<project>/-/merge_requests/N`) or
- * `group/project!N` (defaults to gitlab.com). Returns undefined otherwise.
- */
-export function parseGitLabMrRef(raw: string): GitLabMrRef | undefined {
-  const text = raw.trim();
-  const url = text.match(/^(https?:\/\/[^/]+)\/(.+?)\/-\/merge_requests\/(\d+)(?:[/?#].*)?$/i);
-  if (url !== null) {
-    return build({
-      origin: url[1] as string,
-      projectPath: url[2] as string,
-      iid: Number(url[3]),
-    });
-  }
-  const bang = text.match(/^([\w.-]+(?:\/[\w.-]+)+)!(\d+)$/);
-  if (bang !== null) {
-    return build({
-      origin: "https://gitlab.com",
-      projectPath: bang[1] as string,
-      iid: Number(bang[2]),
-    });
-  }
-  return undefined;
-}
-
-function build(input: { origin: string; projectPath: string; iid: number }): GitLabMrRef {
-  const { origin, projectPath, iid } = input;
-  const path = projectPath.replace(/^\/+|\/+$/g, "");
-  return {
-    origin,
-    projectPath: path,
-    iid,
-    url: `${origin}/${path}/-/merge_requests/${iid}`,
-    label: `${path}!${iid}`,
-  };
-}
-
-// Minimal shapes read from the REST API (extra fields pass through).
-export interface ReplayGitLabProject {
-  id: number;
-  name?: string;
-  path_with_namespace: string;
-  web_url: string;
-  default_branch?: string;
-  namespace?: { full_path?: string };
-}
-
-export interface ReplayGitLabUser {
-  id: number;
-  username: string;
-  name?: string;
-  avatar_url?: string | null;
-}
-
-export interface ReplayGitLabMergeRequest {
-  id: number;
-  iid: number;
-  title: string;
-  description?: string | null;
-  state: string;
-  draft?: boolean;
-  work_in_progress?: boolean;
-  web_url: string;
-  source_branch: string;
-  target_branch: string;
-  sha?: string | null;
-  author?: ReplayGitLabUser | null;
-  labels?: string[];
-  source_project_id?: number;
-  target_project_id?: number;
-  diff_refs?: {
-    base_sha?: string;
-    head_sha?: string;
-    start_sha?: string;
-  } | null;
-}
-
-/** Latest pipeline on the MR head, when one exists. */
-export interface ReplayGitLabPipeline {
-  id: number;
-  status?: string;
-  sha?: string;
-  ref?: string;
-  source?: string;
-  web_url?: string;
-}
-
-/** Webhook `object_kind`s replay knows how to synthesize. */
-export const GITLAB_SYNTHESIZABLE_EVENTS = ["merge_request", "note", "pipeline", "push"] as const;
-
-export type GitLabSynthesizableEvent = (typeof GITLAB_SYNTHESIZABLE_EVENTS)[number];
-
-export function isGitLabSynthesizableEvent(event: string): event is GitLabSynthesizableEvent {
-  return (GITLAB_SYNTHESIZABLE_EVENTS as readonly string[]).includes(event);
-}
-
-export interface SynthesizedGitLabEvent {
-  eventName: GitLabSynthesizableEvent;
-  /** `object_attributes.action` for merge_request events. */
-  action?: string;
-  /** `X-Gitlab-Event` header value for this object kind. */
-  header: string;
-  payload: Record<string, unknown>;
-}
-
-const EVENT_HEADERS: Readonly<Record<GitLabSynthesizableEvent, string>> = {
-  merge_request: "Merge Request Hook",
-  note: "Note Hook",
-  pipeline: "Pipeline Hook",
-  push: "Push Hook",
-};
-
-const FALLBACK_USER: ReplayGitLabUser = {
-  id: 1,
-  username: "agent-sdk-replay",
-  name: "agent-sdk replay",
-};
-
-function projectPayload(project: ReplayGitLabProject): Record<string, unknown> {
-  return {
-    id: project.id,
-    name: project.name ?? project.path_with_namespace.split("/").at(-1),
-    web_url: project.web_url,
-    namespace: project.namespace?.full_path,
-    path_with_namespace: project.path_with_namespace,
-    default_branch: project.default_branch ?? "main",
-  };
-}
-
-function mergeRequestAttributes(input: {
-  mergeRequest: ReplayGitLabMergeRequest;
-  headSha: string;
-  action?: string;
-  extra?: Record<string, unknown>;
-}): Record<string, unknown> {
-  const { mergeRequest, headSha, action, extra = {} } = input;
-  return {
-    id: mergeRequest.id,
-    iid: mergeRequest.iid,
-    title: mergeRequest.title,
-    description: mergeRequest.description ?? "",
-    state: mergeRequest.state,
-    draft: mergeRequest.draft ?? mergeRequest.work_in_progress ?? false,
-    work_in_progress: mergeRequest.work_in_progress ?? mergeRequest.draft ?? false,
-    source_branch: mergeRequest.source_branch,
-    target_branch: mergeRequest.target_branch,
-    source_project_id: mergeRequest.source_project_id,
-    target_project_id: mergeRequest.target_project_id,
-    author_id: mergeRequest.author?.id,
-    url: mergeRequest.web_url,
-    last_commit: { id: headSha },
-    labels: (mergeRequest.labels ?? []).map(title => ({ title })),
-    ...(action === undefined ? {} : { action }),
-    ...extra,
-  };
-}
-
-/** Build one GitLab-shaped payload for `event`. */
-export function synthesizeGitLabEvent(input: {
-  event: string;
-  project: ReplayGitLabProject;
-  mergeRequest: ReplayGitLabMergeRequest;
-  /** merge_request action (default `open`). */
-  action?: string;
-  /** note body (default `@cursor please take a look`). */
-  comment?: string;
-  /** pipeline status override (default: the latest pipeline's, else `success`). */
-  status?: string;
-  pipeline?: ReplayGitLabPipeline;
-}): SynthesizedGitLabEvent | { error: string } {
-  const { event, project, mergeRequest } = input;
-  if (!isGitLabSynthesizableEvent(event)) {
-    return { error: `cannot synthesize ${event}` };
-  }
-  const user = mergeRequest.author ?? FALLBACK_USER;
-  const headSha =
-    mergeRequest.sha ??
-    mergeRequest.diff_refs?.head_sha ??
-    "0000000000000000000000000000000000000000";
-  const base = {
-    object_kind: event,
-    event_type: event,
-    user: { id: user.id, username: user.username, name: user.name },
-    project: projectPayload(project),
-  };
-
-  switch (event) {
-    case "merge_request": {
-      const action = input.action ?? "open";
-      // `update` with new commits carries `oldrev`; the default dispatch keys
-      // on it, so a synthesized update should look like a push, not an edit.
-      const extra =
-        action === "update" ? { oldrev: mergeRequest.diff_refs?.base_sha ?? headSha } : {};
-      return {
-        eventName: event,
-        action,
-        header: EVENT_HEADERS[event],
-        payload: {
-          ...base,
-          object_attributes: mergeRequestAttributes({
-            mergeRequest,
-            headSha,
-            action,
-            extra,
-          }),
-          labels: (mergeRequest.labels ?? []).map(title => ({ title })),
-        },
-      };
-    }
-    case "note": {
-      const body = input.comment ?? "@cursor please take a look";
-      return {
-        eventName: event,
-        header: EVENT_HEADERS[event],
-        payload: {
-          ...base,
-          project_id: project.id,
-          object_attributes: {
-            id: Date.now() % 1_000_000_000,
-            note: body,
-            noteable_type: "MergeRequest",
-            noteable_id: mergeRequest.id,
-            author_id: user.id,
-            url: `${mergeRequest.web_url}#note_replay`,
-            description: body,
-          },
-          merge_request: mergeRequestAttributes({ mergeRequest, headSha }),
-        },
-      };
-    }
-    case "pipeline": {
-      const pipeline = input.pipeline;
-      return {
-        eventName: event,
-        header: EVENT_HEADERS[event],
-        payload: {
-          object_kind: event,
-          user: base.user,
-          project: base.project,
-          object_attributes: {
-            id: pipeline?.id ?? 1,
-            ref: pipeline?.ref ?? mergeRequest.source_branch,
-            sha: pipeline?.sha ?? headSha,
-            source: pipeline?.source ?? "merge_request_event",
-            status: input.status ?? pipeline?.status ?? "success",
-            url: pipeline?.web_url,
-          },
-          merge_request: {
-            id: mergeRequest.id,
-            iid: mergeRequest.iid,
-            title: mergeRequest.title,
-            source_branch: mergeRequest.source_branch,
-            target_branch: mergeRequest.target_branch,
-            state: mergeRequest.state,
-            url: mergeRequest.web_url,
-          },
-        },
-      };
-    }
-    case "push": {
-      const before = mergeRequest.diff_refs?.base_sha ?? "0000000000000000000000000000000000000000";
-      return {
-        eventName: event,
-        header: EVENT_HEADERS[event],
-        payload: {
-          object_kind: event,
-          event_name: event,
-          before,
-          after: headSha,
-          ref: `refs/heads/${mergeRequest.source_branch}`,
-          checkout_sha: headSha,
-          user_id: user.id,
-          user_username: user.username,
-          user_name: user.name,
-          project_id: project.id,
-          project: base.project,
-          commits: [],
-          total_commits_count: 0,
-        },
-      };
-    }
-  }
-}
-
-/** Choose events to replay: explicit list, `*` for every declared, else merge_request. */
-export function selectGitLabReplayEvents(
-  requested: readonly string[] | undefined,
-  declared: readonly string[],
-): { events: GitLabSynthesizableEvent[]; unsupported: string[] } {
-  const wanted =
-    requested === undefined
-      ? ["merge_request"]
-      : requested.includes("*")
-        ? [...declared]
-        : [...requested];
-  const events: GitLabSynthesizableEvent[] = [];
-  const unsupported: string[] = [];
-  for (const event of new Set(wanted)) {
-    if (isGitLabSynthesizableEvent(event)) {
-      events.push(event);
-    } else {
-      unsupported.push(event);
-    }
-  }
-  return { events, unsupported };
-}

package/src/channels/gitlab/state.ts

@@ -1,55 +0,0 @@
-/**
- * Durable per-session GitLab channel state.
- *
- * Persisted with the turn (same mechanism as `OriginChannelState`) so
- * channel stream-event handlers can rebuild a project-bound handle without
- * re-parsing the webhook.
- */
-
-export interface GitLabChannelState {
-  projectId: number | null;
-  /** `path_with_namespace` as delivered (nested groups keep their slashes). */
-  projectPath: string;
-  mergeRequestIid: number | null;
-  /** Head sha of the merge request at dispatch time, when known. */
-  headSha: string | null;
-  /** Note id that woke the turn (note events only). */
-  triggeringNoteId: number | null;
-  deliveryId: string | null;
-  eventType: string | null;
-}
-
-export function emptyGitLabChannelState(
-  overrides: Partial<GitLabChannelState> = {},
-): GitLabChannelState {
-  return {
-    projectId: null,
-    projectPath: "",
-    mergeRequestIid: null,
-    headSha: null,
-    triggeringNoteId: null,
-    deliveryId: null,
-    eventType: null,
-    ...overrides,
-  };
-}
-
-/** Build the per-turn channel state from a dispatched event's context. */
-export function gitlabChannelStateForEvent(input: {
-  project: { id: number; pathWithNamespace: string };
-  mergeRequestIid?: number;
-  headSha?: string;
-  deliveryId?: string;
-  eventType: string;
-  triggeringNoteId?: number;
-}): GitLabChannelState {
-  return emptyGitLabChannelState({
-    projectId: input.project.id,
-    projectPath: input.project.pathWithNamespace,
-    mergeRequestIid: input.mergeRequestIid ?? null,
-    headSha: input.headSha ?? null,
-    triggeringNoteId: input.triggeringNoteId ?? null,
-    deliveryId: input.deliveryId ?? null,
-    eventType: input.eventType,
-  });
-}

package/src/channels/gitlab/types.ts

@@ -1,247 +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 { GitLabTokenProvider } from "./api.js";
-import type { GitLabHandle } from "./binding.js";
-import type { GitLabChannelState } from "./state.js";
-
-export interface GitLabUser {
-  id: number;
-  username: string;
-  name?: string;
-}
-
-export interface GitLabProjectRef {
-  id: number;
-  /** `path_with_namespace` as delivered, e.g. `acme/platform/widgets`. */
-  pathWithNamespace: string;
-  webUrl: string;
-  defaultBranch?: string;
-}
-
-/** `object_kind: "merge_request"` event, normalized from `object_attributes`. */
-export interface GitLabMergeRequestEvent {
-  /** `open`, `update`, `close`, `reopen`, `approved`, `merge`, … */
-  action?: string;
-  iid: number;
-  id?: number;
-  url: string;
-  title?: string;
-  description?: string | null;
-  state?: string;
-  draft?: boolean;
-  sourceBranch?: string;
-  targetBranch?: string;
-  /** `object_attributes.last_commit.id`. */
-  headSha?: string;
-  /** Set on `update` only when new commits were pushed. */
-  oldrev?: string;
-  authorId?: number;
-  labels?: string[];
-}
-
-export type GitLabNoteableType = "merge_request" | "issue" | "commit" | "snippet";
-
-export interface GitLabNote {
-  id: number;
-  body: string;
-  /** Normalized `object_attributes.noteable_type` (`MergeRequest` → `merge_request`). */
-  noteableType: GitLabNoteableType | string;
-  noteableId?: number;
-  url?: string;
-  author?: GitLabUser;
-  /** `merge_request.iid` for MR notes. */
-  mergeRequestIid?: number;
-}
-
-export interface GitLabPush {
-  ref: string;
-  before?: string;
-  after?: string;
-  checkoutSha?: string;
-  commitCount?: number;
-}
-
-export interface GitLabPipeline {
-  id: number;
-  status?: string;
-  sha?: string;
-  ref?: string;
-  /** `push`, `merge_request_event`, `schedule`, … */
-  source?: string;
-  url?: string;
-  /** `merge_request.iid` when the pipeline belongs to a merge request. */
-  mergeRequestIid?: number;
-}
-
-export interface GitLabEventContext {
-  /** `X-Gitlab-Event-UUID`, when present. */
-  deliveryId?: string;
-  /** GitLab `object_kind` (`merge_request`, `note`, `push`, `pipeline`, …). */
-  eventType: string;
-  project: GitLabProjectRef;
-  mergeRequestIid?: number;
-  mergeRequestUrl?: string;
-  /** Raw parsed payload record, for consumers whose normalization needs more. */
-  payload: Record<string, unknown>;
-  /** `user` on the payload — the actor who triggered the delivery. */
-  sender?: GitLabUser;
-  /**
-   * Project-bound GitLab API (`request`, `setCommitStatus`, `createCheck`).
-   * Routes through the Cursor SCM proxy under `cursorAccount` +
-   * `--cursor-scm-proxy`; otherwise uses {@link GitLabChannelOptions.token} /
-   * `GITLAB_TOKEN` against the project's host.
-   */
-  gitlab: GitLabHandle;
-  /**
-   * 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 GitLabTurnDispatch = {
-  auth: AuthContext;
-  message?: string;
-  title?: string;
-  context?: readonly string[];
-};
-
-/** Bound per-delivery helpers passed to a {@link GitLabTaskDispatch.task}. */
-export interface GitLabTaskArgs {
-  send: SendMessageFn;
-  waitUntil: (promise: Promise<unknown>) => void;
-}
-
-/** Run a host-side handler after the webhook is acknowledged with a 202. */
-export type GitLabTaskDispatch = {
-  task: (args: GitLabTaskArgs) => void | Promise<void>;
-};
-
-export type GitLabDispatch = GitLabTurnDispatch | GitLabTaskDispatch;
-
-export type GitLabDispatchResult = GitLabDispatch | null | Promise<GitLabDispatch | null>;
-
-export type GitLabMergeRequestHook = (
-  ctx: GitLabEventContext,
-  mergeRequest: GitLabMergeRequestEvent,
-) => GitLabDispatchResult;
-
-export type GitLabNoteHook = (ctx: GitLabEventContext, note: GitLabNote) => GitLabDispatchResult;
-
-export type GitLabPushHook = (ctx: GitLabEventContext, push: GitLabPush) => GitLabDispatchResult;
-
-export type GitLabPipelineHook = (
-  ctx: GitLabEventContext,
-  pipeline: GitLabPipeline,
-) => GitLabDispatchResult;
-
-export type GitLabEventHook = (
-  ctx: GitLabEventContext,
-  event: { eventType: string; payload: unknown },
-) => GitLabDispatchResult;
-
-export type GitLabCloudOptionsResolver = (
-  ctx: GitLabEventContext,
-  mergeRequest: GitLabMergeRequestEvent,
-) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
-
-/** One verified GitLab delivery handed to {@link dispatchGitLabWebhook}. */
-export interface GitLabWebhookDelivery {
-  /** `object_kind` (hosted admission passes the envelope's event type). */
-  eventType: string;
-  payload: Record<string, unknown>;
-  deliveryId?: string;
-}
-
-export interface GitLabChannelOptions {
-  /**
-   * Use the signed-in Cursor account for inbound GitLab events delivered by
-   * the Cursor backend. `true` takes project scope from the deployment;
-   * `{ projects }` (`group/project` paths) makes the channel self-contained.
-   */
-  cursorAccount?: boolean | { projects: readonly string[] };
-  /**
-   * Access token (or provider) for direct `ctx.gitlab` calls when not in
-   * proxy mode. Falls back to `GITLAB_TOKEN`.
-   */
-  token?: string | GitLabTokenProvider;
-  /**
-   * REST base for direct `ctx.gitlab` calls. Defaults to
-   * `GITLAB_API_BASE_URL`, else `https://gitlab.com/api/v4`. Self-managed
-   * hosts must set one of these; the payload's `project.web_url` is never
-   * used to pick where the token is sent.
-   */
-  apiBaseUrl?: string;
-  /**
-   * Project hook secret compared against `X-Gitlab-Token` on direct HTTP
-   * deliveries. Falls back to `GITLAB_WEBHOOK_SECRET`. With a secret set the
-   * token compare is the request auth; without one production stays
-   * loopback-strict and `serve --dev` admits unsigned loopback deliveries.
-   */
-  webhookSecret?: string | (() => string | undefined);
-  /**
-   * Optional project allowlist (`group/project`, case-insensitive). Events
-   * from other projects are acked without starting a turn.
-   */
-  projects?: readonly string[];
-  /** Route auth chain; defaults follow {@link webhookSecret}. */
-  auth?: AuthPolicy[];
-  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
-  path?: string;
-  /**
-   * Pin the GitLab `object_kind`s this channel dispatches on (published as
-   * `meta.gitlabWebhookEvents`). 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 merge-request event starts a turn. Return
-   * `{ auth: defaultGitLabAuth(ctx) }` to dispatch, `null` to ignore. Without
-   * this hook the channel dispatches on `open`, `reopen`, and `update` with
-   * new commits (`oldrev` present).
-   */
-  onMergeRequest?: GitLabMergeRequestHook;
-  /**
-   * Opt-in `note` handler. Merge-request notes only by default; widen with
-   * {@link noteables}.
-   */
-  onNote?: GitLabNoteHook;
-  /** Which noteables {@link onNote} receives. Defaults to `["merge_request"]`. */
-  noteables?: readonly GitLabNoteableType[];
-  /** Opt-in `push` handler. No default dispatch. */
-  onPush?: GitLabPushHook;
-  /** Opt-in `pipeline` handler. No default dispatch. */
-  onPipeline?: GitLabPipelineHook;
-  /**
-   * Catch-all for `object_kind`s without a typed hook (`tag_push`, `issue`,
-   * `wiki_page`, …). NOT a fallback: events with a typed hook never reach it.
-   */
-  onEvent?: GitLabEventHook;
-  /**
-   * Per-session cloud options. Pass `true` to attach the project using the
-   * merge request's web URL, or a resolver for custom cloud options.
-   */
-  cloud?: boolean | AgentCloudOptions | GitLabCloudOptionsResolver;
-  /** Channel stream-event handlers. */
-  events?: ChannelEventHandlers<GitLabChannelState>;
-  /** 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/issues/index.ts

@@ -1,9 +0,0 @@
-export { issuesChannel } from "./issues-channel.js";
-export type {
-  IssueCreatedEvent,
-  IssueCreatedEventType,
-  IssueResource,
-  IssueState,
-  IssuesChannelOptions,
-} from "./types.js";
-export { ISSUE_CREATED_EVENT_TYPE } from "./types.js";

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

@@ -1,45 +0,0 @@
-import { z } from "zod";
-import { createFactoryResourceChannel } from "../../internal/factory-resource-channel.js";
-import type { ChannelDefinition } from "../../types.js";
-import {
-  ISSUE_CREATED_EVENT_TYPE,
-  type IssueCreatedEvent,
-  type IssuesChannelOptions,
-} from "./types.js";
-
-const issueResourceSchema = z
-  .object({
-    name: z.string().min(1),
-    title: z.string().min(1),
-    body: z.string().min(1),
-    state: z.enum(["STATE_UNSPECIFIED", "STATE_OPEN", "STATE_CLOSED"]).optional(),
-    createTime: z.string().min(1).optional(),
-    updateTime: z.string().min(1).optional(),
-    path: z.string().optional(),
-    etag: z.string().optional(),
-  })
-  .passthrough();
-
-const issueCreatedEventSchema: z.ZodType<IssueCreatedEvent> = z.object({
-  eventId: z.string().min(1),
-  eventType: z.literal(ISSUE_CREATED_EVENT_TYPE),
-  teamId: z.string().min(1),
-  occurredAtMs: z.number().int().nonnegative(),
-  issue: issueResourceSchema,
-});
-
-const pack = createFactoryResourceChannel({
-  kind: "issues",
-  eventTypes: [ISSUE_CREATED_EVENT_TYPE],
-  eventSchema: issueCreatedEventSchema,
-  replayDescription: "Replay a Factory issue-created event.",
-  invalidError: "invalid issue event",
-});
-
-export function issuesChannel(options: IssuesChannelOptions): ChannelDefinition {
-  return pack.channel(options);
-}
-
-export function getIssuesChannelOptions(definition: object): IssuesChannelOptions | undefined {
-  return pack.getOptions(definition);
-}