@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/gitlab/checks.ts

@@ -1,228 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/** {@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

@@ -1,160 +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 {
-  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;
-}