@cursor/bdk 0.2.1

package/src/channels/gitlab/checks.ts

@@ -0,0 +1,228 @@
+/**
+ * GitLab commit statuses — the GitLab {@link CiCheckWriter} behind the shared
+ * check lifecycle in `../checks.js`.
+ *
+ * GitLab has no Checks API; the merge-request widget shows **commit
+ * statuses** (`POST /projects/:id/statuses/:sha`, one row per `name`). The
+ * writer maps the shared status / conclusion pair onto GitLab's state set
+ * and re-posts the full desired state on every write, so `resumeGitLabCheck`
+ * needs only `(project, sha, name)` to rebuild a handle after a restart.
+ *
+ * Posting needs a token with `api` scope (Developer role or above); through
+ * the SCM proxy that is the tenant's project / host credential.
+ */
+
+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 GitLabApiMethod, gitlabProjectPathSegment } from "./api.js";
+
+/** Any client that can call the GitLab REST API. */
+export interface GitLabCheckClient {
+  request<T = unknown>(input: {
+    method: GitLabApiMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<T>;
+}
+
+/** GitLab commit status `state` values. */
+export type GitLabCommitStatusState = "pending" | "running" | "success" | "failed" | "canceled";
+
+export interface GitLabCommitStatusInput {
+  /** Numeric project id or `group/project` path. */
+  project: number | string;
+  sha: string;
+  state: GitLabCommitStatusState;
+  /** Status name shown in the MR widget, e.g. `cursor/security-review`. */
+  name: string;
+  /** "Details" link. */
+  targetUrl?: string;
+  /** Short description (GitLab truncates long values). */
+  description?: string;
+  /** Attach the status to a specific pipeline instead of the latest one. */
+  pipelineId?: number;
+}
+
+/** Response subset of `POST /projects/:id/statuses/:sha`. */
+export interface GitLabCommitStatus {
+  id?: number;
+  status?: string;
+  target_url?: string | null;
+  [key: string]: unknown;
+}
+
+const DESCRIPTION_MAX_CHARS = 255;
+
+/** Post one commit status. Throws `GitLabApiError` on API failure. */
+export async function setGitLabCommitStatus(
+  gitlab: GitLabCheckClient,
+  input: GitLabCommitStatusInput,
+): Promise<GitLabCommitStatus> {
+  return await gitlab.request<GitLabCommitStatus>({
+    method: "POST",
+    path: `/projects/${gitlabProjectPathSegment(input.project)}/statuses/${encodeURIComponent(input.sha)}`,
+    body: {
+      state: input.state,
+      name: input.name,
+      ...(input.targetUrl === undefined ? {} : { target_url: input.targetUrl }),
+      ...(input.description === undefined
+        ? {}
+        : { description: input.description.slice(0, DESCRIPTION_MAX_CHARS) }),
+      ...(input.pipelineId === undefined ? {} : { pipeline_id: input.pipelineId }),
+    },
+  });
+}
+
+/** Shared check status / conclusion → GitLab commit status state. */
+export function gitlabCommitStatusState(input: {
+  status: CiCheckStatus;
+  conclusion?: CiCheckConclusion;
+}): GitLabCommitStatusState {
+  if (input.status === "queued") {
+    return "pending";
+  }
+  if (input.status === "in_progress") {
+    return "running";
+  }
+  switch (input.conclusion) {
+    case "success":
+    case "neutral":
+    case "skipped":
+      return "success";
+    case "cancelled":
+      return "canceled";
+    case "failure":
+    case "action_required":
+    case "timed_out":
+    case undefined:
+      return "failed";
+  }
+}
+
+export type GitLabCheckOutput = CiCheckOutput;
+export type GitLabCheckUpdateInput = CiCheckUpdateInput;
+export type GitLabCheckConcludeInput = CiCheckConcludeInput;
+
+/** A created commit status. All methods throw `GitLabApiError` on failure. */
+export type GitLabCheck = CiCheck & CiCheckRef;
+
+export interface GitLabCheckIdentityInput {
+  /** Client used for every API call on the returned handle. */
+  gitlab: GitLabCheckClient;
+  /** Numeric project id or `group/project` path. */
+  project: number | string;
+  /** Status name shown in the MR widget, e.g. `"cursor/security-review"`. */
+  name: string;
+  /** Commit the status attaches to (usually the MR head SHA). */
+  sha: string;
+  /** Pin the status to one pipeline. */
+  pipelineId?: number;
+}
+
+export interface GitLabCheckCreateInput extends GitLabCheckIdentityInput, CiCheckCreateInput {}
+
+/**
+ * GitLab writer: every write re-posts the status row for `(sha, name)`, and
+ * a commit status has no partial update, so the writer carries the last
+ * status, details link, and title forward when a write omits them.
+ */
+function gitlabCheckWriter(
+  input: GitLabCheckIdentityInput & {
+    status?: CiCheckStatus;
+    url?: string;
+    title?: string;
+  },
+): CiCheckWriter {
+  let lastStatus: CiCheckStatus = input.status ?? "in_progress";
+  let lastUrl: string | undefined = input.url;
+  let lastTitle: string | undefined = input.title;
+  return async write => {
+    const status = write.status ?? (write.conclusion === undefined ? lastStatus : "completed");
+    lastStatus = status;
+    lastUrl = write.detailsUrl ?? lastUrl;
+    lastTitle = write.output?.title ?? lastTitle;
+    const posted = await setGitLabCommitStatus(input.gitlab, {
+      project: input.project,
+      sha: input.sha,
+      name: input.name,
+      state: gitlabCommitStatusState({ status, conclusion: write.conclusion }),
+      targetUrl: lastUrl,
+      description: lastTitle,
+      pipelineId: input.pipelineId,
+    });
+    return {
+      ...(typeof posted?.id === "number" ? { id: posted.id } : {}),
+      ...(typeof posted?.target_url === "string" ? { url: posted.target_url } : {}),
+    };
+  };
+}
+
+/**
+ * Open a commit status on `sha` and return a handle for later updates.
+ *
+ * ```ts
+ * const check = await createGitLabCheck({
+ *   gitlab: ctx.gitlab,
+ *   project: ctx.project.id,
+ *   name: "cursor/security-review",
+ *   sha: mergeRequest.headSha,
+ *   detailsUrl: sessionUrl,
+ *   output: { title: "Running…", summary: "" },
+ * });
+ * await check.conclude({ conclusion: "success", output: { title: "Clean", summary: "" } });
+ * ```
+ */
+export function createGitLabCheck(input: GitLabCheckCreateInput): Promise<GitLabCheck> {
+  return openCiCheck(gitlabCheckWriter(input), input);
+}
+
+/**
+ * Rebuild a {@link GitLabCheck} handle for an existing status row from its
+ * identity. No API call is made until the first update.
+ */
+export function resumeGitLabCheck(
+  input: GitLabCheckIdentityInput & {
+    /** Last known status; defaults to `"in_progress"`. */
+    status?: CiCheckStatus;
+    /** Last known details link, kept on writes that omit `detailsUrl`. */
+    url?: string;
+    /** Last known title, kept on writes that omit `output`. */
+    title?: string;
+    id?: number;
+  },
+): GitLabCheck {
+  return resumeCiCheck(
+    gitlabCheckWriter(input),
+    input.id === undefined ? undefined : { id: input.id },
+  );
+}
+
+/**
+ * Project-bound checks adapter satisfying the shared {@link CiChecksClient}
+ * contract for forge-agnostic check code.
+ */
+export function bindGitLabChecks(input: {
+  gitlab: GitLabCheckClient;
+  project: number | string;
+}): CiChecksClient {
+  return {
+    createCheck: check =>
+      createGitLabCheck({
+        ...check,
+        gitlab: input.gitlab,
+        project: input.project,
+      }),
+  };
+}

package/src/channels/gitlab/cursor-account.ts

@@ -0,0 +1,105 @@
+/**
+ * Cursor-account mode for GitLab channels.
+ *
+ * `gitlabChannel({ cursorAccount })` declares that outbound GitLab calls run
+ * through the Cursor SCM proxy (`/v0/gitlab-proxy`) with the tenant's
+ * credential swapped in server-side. The serve host binds the Cursor API key
+ * and the proxy transport at startup when `--cursor-scm-proxy` is set; until
+ * then `ctx.gitlab` falls back to direct `GITLAB_TOKEN` access.
+ */
+
+import { resolveCursorScmProxyUrl } from "../github/cursor-account.js";
+import type { GitLabProxyTransport } from "./api.js";
+import type { GitLabChannelOptions } from "./types.js";
+
+export const CURSOR_GITLAB_MAX_PROJECTS = 20;
+/** `group/project`, with nested groups (`group/sub/project`). */
+const CURSOR_GITLAB_PROJECT_PATTERN = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+$/;
+
+export interface CursorGitLabProjectScope {
+  /** Lowercased `group/project` paths. */
+  projects: readonly string[];
+}
+
+/** Host-bound credential: Cursor API key + proxy transport, bound at serve. */
+export interface PendingCursorGitLabCredentials {
+  bind(getApiKey: () => Promise<string>): void;
+  bindProxyTransport(transport: Omit<GitLabProxyTransport, "getApiKey">): void;
+  /** The full proxy transport once both halves are bound. */
+  getProxyTransport(): GitLabProxyTransport | undefined;
+}
+
+export interface GitLabCursorAccountRuntime {
+  /** Authored channel options (not rewritten). */
+  options: GitLabChannelOptions;
+  credentials: PendingCursorGitLabCredentials;
+  scope: CursorGitLabProjectScope | undefined;
+}
+
+const runtimeByDefinition = new WeakMap<object, GitLabCursorAccountRuntime>();
+
+export function parseCursorGitLabProjectScope(values: readonly string[]): CursorGitLabProjectScope {
+  const projects = [
+    ...new Set(
+      values
+        .map(project =>
+          project
+            .trim()
+            .replace(/^\/+|\/+$/g, "")
+            .toLowerCase(),
+        )
+        .filter(Boolean),
+    ),
+  ];
+  if (projects.length === 0) {
+    throw new Error("gitlabChannel({ cursorAccount }) requires at least one project.");
+  }
+  if (projects.length > CURSOR_GITLAB_MAX_PROJECTS) {
+    throw new Error(
+      `gitlabChannel({ cursorAccount }) supports at most ${CURSOR_GITLAB_MAX_PROJECTS} projects.`,
+    );
+  }
+  for (const project of projects) {
+    if (!CURSOR_GITLAB_PROJECT_PATTERN.test(project) || project.includes("..")) {
+      throw new Error(`Invalid GitLab project "${project}"; expected group/project.`);
+    }
+  }
+  return { projects };
+}
+
+export function createPendingCursorGitLabCredentials(): PendingCursorGitLabCredentials {
+  let getApiKey: (() => Promise<string>) | undefined;
+  let transport: Omit<GitLabProxyTransport, "getApiKey"> | undefined;
+  return {
+    bind(next) {
+      getApiKey = next;
+    },
+    bindProxyTransport(next) {
+      transport = next;
+    },
+    getProxyTransport() {
+      if (getApiKey === undefined || transport === undefined) {
+        return undefined;
+      }
+      return { ...transport, getApiKey };
+    },
+  };
+}
+
+/** GitLab-proxy base URL (`/v0/gitlab-proxy`, `AGENT_SERVE_GITLAB_PROXY_URL`). */
+export function resolveCursorGitLabProxyUrl(backendBaseUrl: string): string {
+  return resolveCursorScmProxyUrl("gitlab", backendBaseUrl);
+}
+
+export function registerGitLabCursorAccountRuntime(
+  definition: object,
+  runtime: GitLabCursorAccountRuntime,
+): void {
+  runtimeByDefinition.set(definition, runtime);
+}
+
+export function getGitLabCursorAccountRuntime(
+  definition: object,
+): GitLabCursorAccountRuntime | undefined {
+  return runtimeByDefinition.get(definition);
+}

package/src/channels/gitlab/defaults.ts

@@ -0,0 +1,80 @@
+/**
+ * Default dispatch decisions for the GitLab channel: turn auth derived from
+ * the delivery's actor, the title / message a turn starts with, and which
+ * merge-request actions dispatch when no `onMergeRequest` hook is declared.
+ */
+
+import type { AuthContext } from "../../types.js";
+import type { GitLabEventContext, GitLabMergeRequestEvent, GitLabTurnDispatch } from "./types.js";
+
+type DispatchContext = Omit<GitLabEventContext, "host" | "artifacts" | "gitlab" | "send">;
+
+/**
+ * Derive the turn's auth from the actor that triggered the delivery — the
+ * standard `{ auth: defaultGitLabAuth(ctx) }` dispatch from an inbound hook.
+ * The subscriber's Cursor identity is not the turn principal (same pattern
+ * as `defaultGitHubAuth` / `defaultOriginAuth`).
+ */
+export function defaultGitLabAuth(ctx: DispatchContext): AuthContext {
+  const sender = ctx.sender;
+  const host = new URL(ctx.project.webUrl).host;
+  return {
+    authenticator: "gitlab-webhook",
+    principalId: sender === undefined ? "gitlab" : String(sender.id),
+    principalType: "user",
+    attributes: {
+      conversation_kind: ctx.mergeRequestIid === undefined ? ctx.eventType : "merge_request",
+      project: ctx.project.pathWithNamespace,
+      project_id: String(ctx.project.id),
+      ...(ctx.deliveryId === undefined ? {} : { delivery_id: ctx.deliveryId }),
+      ...(sender === undefined ? {} : { subject: String(sender.id), username: sender.username }),
+      issuer: `gitlab:${host}`,
+    },
+  };
+}
+
+export function defaultGitLabTitle(
+  ctx: Pick<GitLabEventContext, "project" | "mergeRequestIid" | "eventType">,
+): string {
+  return ctx.mergeRequestIid === undefined
+    ? `GitLab ${ctx.project.pathWithNamespace} ${ctx.eventType}`
+    : `GitLab ${ctx.project.pathWithNamespace}!${ctx.mergeRequestIid}`;
+}
+
+export function defaultGitLabMergeRequestMessage(
+  ctx: DispatchContext,
+  mergeRequest: GitLabMergeRequestEvent,
+): string {
+  const head =
+    mergeRequest.sourceBranch !== undefined && mergeRequest.headSha !== undefined
+      ? `Head: ${mergeRequest.sourceBranch} (${mergeRequest.headSha})`
+      : undefined;
+  return [
+    `GitLab merge request trigger: ${ctx.project.pathWithNamespace}!${mergeRequest.iid}`,
+    `Action: ${mergeRequest.action ?? "unknown"}`,
+    `URL: ${mergeRequest.url}`,
+    ...(mergeRequest.title === undefined ? [] : [`Title: ${mergeRequest.title}`]),
+    ...(head === undefined ? [] : [head]),
+    "Handle this merge request event.",
+  ].join("\n");
+}
+
+/**
+ * Default gate when no `onMergeRequest` hook is declared: a new or reopened
+ * merge request, or an `update` that pushed commits (`oldrev` present —
+ * title / label edits carry no `oldrev`), starts a turn as the actor.
+ */
+export function defaultGitLabMergeRequestDispatch(
+  ctx: DispatchContext,
+  mergeRequest: GitLabMergeRequestEvent,
+): GitLabTurnDispatch | null {
+  const action = mergeRequest.action;
+  const dispatches =
+    action === "open" ||
+    action === "reopen" ||
+    (action === "update" && mergeRequest.oldrev !== undefined);
+  if (!dispatches) {
+    return null;
+  }
+  return { auth: defaultGitLabAuth(ctx) };
+}

package/src/channels/gitlab/events.ts

@@ -0,0 +1,37 @@
+/** {@link ChannelMeta.kind} value used by {@link gitlabChannel}. */
+export const GITLAB_CHANNEL_KIND = "gitlab";
+
+/**
+ * GitLab `object_kind` values (the `X-Gitlab-Event` payload discriminator)
+ * each authored hook subscribes to. `merge_request` is always declared: it
+ * is the default dispatch when no `onMergeRequest` hook exists.
+ */
+const HOOK_EVENTS: ReadonlyArray<readonly [hook: string, objectKind: string]> = [
+  ["onMergeRequest", "merge_request"],
+  ["onNote", "note"],
+  ["onPush", "push"],
+  ["onPipeline", "pipeline"],
+  ["onTagPush", "tag_push"],
+];
+
+export interface GitLabWebhookEventOptions {
+  webhookEvents?: readonly string[];
+  onMergeRequest?: unknown;
+  onNote?: unknown;
+  onPush?: unknown;
+  onPipeline?: unknown;
+  onTagPush?: unknown;
+}
+
+export function deriveGitLabWebhookEvents(options: GitLabWebhookEventOptions): string[] {
+  if (options.webhookEvents !== undefined) {
+    return [...new Set(options.webhookEvents.map(event => event.trim()).filter(Boolean))];
+  }
+  const events = ["merge_request"];
+  for (const [hook, objectKind] of HOOK_EVENTS) {
+    if ((options as Record<string, unknown>)[hook] !== undefined) {
+      events.push(objectKind);
+    }
+  }
+  return [...new Set(events)];
+}

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

@@ -0,0 +1,160 @@
+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 {
+  createPendingCursorGitLabCredentials,
+  parseCursorGitLabProjectScope,
+  registerGitLabCursorAccountRuntime,
+} from "./cursor-account.js";
+import { deriveGitLabWebhookEvents, GITLAB_CHANNEL_KIND } from "./events.js";
+import {
+  dispatchGitLabWebhook,
+  handleGitLabWebhookRequest,
+  parseGitLabWebhookPayload,
+  resolveGitLabWebhookSecret,
+} from "./gitlab-webhook.js";
+import { emptyGitLabChannelState, type GitLabChannelState } from "./state.js";
+import type { GitLabChannelOptions } from "./types.js";
+
+const gitlabChannelOptionsByDefinition = new WeakMap<object, GitLabChannelOptions>();
+
+export function getGitLabChannelOptions(definition: object): GitLabChannelOptions | undefined {
+  return gitlabChannelOptionsByDefinition.get(definition);
+}
+
+export function gitlabChannel(
+  options: GitLabChannelOptions = {},
+): ChannelDefinition<GitLabChannelState> {
+  const routePath = options.path ?? "/";
+  // With a hook secret the `X-Gitlab-Token` compare 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) =>
+      (resolveGitLabWebhookSecret(options) !== undefined
+        ? allowAll()
+        : isDevMode()
+          ? loopbackOnly()
+          : localDevStrict())(request, info),
+  ];
+
+  const channelOptions: GitLabChannelOptions = { ...options };
+  if (channelOptions.continuation !== undefined) {
+    channelOptions.continuation = normalizeIdentity(
+      channelOptions.continuation,
+      GITLAB_CHANNEL_KIND,
+    );
+  }
+  // `cursorAccount` routes `ctx.gitlab` 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: createPendingCursorGitLabCredentials(),
+          scope:
+            typeof options.cursorAccount === "object"
+              ? parseCursorGitLabProjectScope(options.cursorAccount.projects)
+              : undefined,
+        };
+  const proxy = () => cursorAccount?.credentials.getProxyTransport();
+
+  const definition = defineChannel<GitLabChannelState>({
+    auth,
+    state: emptyGitLabChannelState(),
+    events: options.events ?? {},
+    onStart: options.onStart,
+    onStop: options.onStop,
+    meta: {
+      kind: GITLAB_CHANNEL_KIND,
+      gitlabWebhookEvents: deriveGitLabWebhookEvents(channelOptions),
+    },
+    routes: [
+      POST(routePath, {
+        bodySchema: z.unknown(),
+        description: "GitLab webhook ingress",
+        handler: async (request, args) =>
+          handleGitLabWebhookRequest({
+            options: channelOptions,
+            request,
+            args,
+            proxy,
+          }),
+      }),
+    ],
+  });
+  gitlabChannelOptionsByDefinition.set(definition, channelOptions);
+  if (cursorAccount !== undefined) {
+    registerGitLabCursorAccountRuntime(definition, {
+      options: channelOptions,
+      ...cursorAccount,
+    });
+  }
+  attachHostedAdmissionAdapter(definition, {
+    kind: GITLAB_CHANNEL_KIND,
+    prepareArgs: withPropagatingBackgroundErrors,
+    dispatch: async ({ eventType, payload, deliveryId, args }) => {
+      const delivery = parseGitLabWebhookPayload(payload, eventType);
+      if (delivery === null) {
+        return Response.json({ ok: false, error: "invalid_gitlab_payload" }, { status: 400 });
+      }
+      delivery.deliveryId = deliveryId;
+      return dispatchGitLabWebhook({
+        options: channelOptions,
+        delivery,
+        args,
+        proxy,
+      });
+    },
+  });
+  return definition;
+}
+
+/** Minimal mount shape shared by `serve` / the `gitlab` CLI. */
+export interface GitLabAgentMountLike {
+  slug: string;
+  project: {
+    channels: Array<{
+      id: string;
+      definition: {
+        meta?: { kind?: string; gitlabWebhookEvents?: readonly string[] };
+        routes?: ReadonlyArray<{ method: string; path: string }>;
+      };
+    }>;
+  };
+}
+
+export interface GitLabChannelTarget {
+  slug: string;
+  channelId: string;
+  /** Route path under the channel (default `/`). */
+  routePath: string;
+  events: string[];
+}
+
+export function findGitLabChannelTargets(
+  mounts: ReadonlyArray<GitLabAgentMountLike>,
+): GitLabChannelTarget[] {
+  const targets: GitLabChannelTarget[] = [];
+  for (const { slug, project } of mounts) {
+    for (const channel of project.channels) {
+      const meta = channel.definition.meta;
+      if (meta?.kind !== GITLAB_CHANNEL_KIND) {
+        continue;
+      }
+      const postRoute = (channel.definition.routes ?? []).find(route => route.method === "POST");
+      targets.push({
+        slug,
+        channelId: channel.id,
+        routePath: postRoute?.path ?? "/",
+        events: [...(meta.gitlabWebhookEvents ?? [])],
+      });
+    }
+  }
+  return targets;
+}