@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/gitlab/api.ts

@@ -1,329 +0,0 @@
-/**
- * GitLab REST v4 client for the GitLab channel — the `createGitHubOctokit`
- * / `createOriginClient` analogue.
- *
- * Two transports:
- *
- * - **Direct**: `PRIVATE-TOKEN` against `https://<host>/api/v4` with a
- *   project / group / personal access token from options or `GITLAB_TOKEN`.
- *   The host defaults to `GITLAB_API_BASE_URL`, else gitlab.com. `ctx.gitlab`
- *   never derives it from the webhook payload; only the replay CLI passes a
- *   user-supplied `projectWebUrl`.
- * - **Proxy** (`--cursor-scm-proxy` with `cursorAccount`): the backend
- *   forwarder at `/v0/gitlab-proxy`. Calls carry the Cursor API key as the
- *   bearer plus `x-cursor-gitlab-projects` naming the project the call is
- *   scoped to; the backend swaps in the tenant's GitLab credential.
- *
- * Deliberately fetch-based rather than `@gitbeaker/rest`: the pack needs a
- * handful of endpoints and one header hook, not a full SDK dependency.
- */
-
-export const DEFAULT_GITLAB_API_BASE_URL = "https://gitlab.com/api/v4";
-
-/** Header the SCM proxy reads to scope a GitLab call to one project. */
-export const CURSOR_GITLAB_PROJECTS_HEADER = "x-cursor-gitlab-projects";
-
-export type GitLabApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
-
-/** Normalized GitLab REST failure — the `GitHubApiError` analogue. */
-export class GitLabApiError extends Error {
-  readonly body: unknown;
-  readonly method: string;
-  readonly path: string;
-  readonly status: number;
-
-  constructor(input: { body: unknown; method: string; path: string; status: number }) {
-    super(`GitLab ${input.method} ${input.path} failed with HTTP ${input.status}.`);
-    this.name = "GitLabApiError";
-    this.body = input.body;
-    this.method = input.method;
-    this.path = input.path;
-    this.status = input.status;
-  }
-}
-
-export type GitLabTokenProvider = () => Promise<string> | string;
-
-/** Backend SCM-proxy transport bound by the serve host in proxy mode. */
-export interface GitLabProxyTransport {
-  /** `/v0/gitlab-proxy` base, see `resolveCursorGitLabProxyUrl`. */
-  apiBaseUrl: string;
-  /** Cursor API key sent as the bearer; the proxy swaps in the GitLab token. */
-  getApiKey: () => Promise<string>;
-  /** Static headers added to every call (project scope when declared). */
-  headers?: Readonly<Record<string, string>>;
-}
-
-export interface GitLabClientOptions {
-  /** REST base, e.g. `https://gitlab.example.com/api/v4`. */
-  apiBaseUrl?: string;
-  /** Access token or provider for direct calls. Falls back to `GITLAB_TOKEN`. */
-  token?: string | GitLabTokenProvider;
-  /** Route through the Cursor SCM proxy instead of calling GitLab directly. */
-  proxy?: GitLabProxyTransport;
-  /**
-   * Project (`group/project`) every call is scoped to. Proxy mode sends it
-   * as `x-cursor-gitlab-projects` when no static header names one.
-   */
-  project?: string;
-  /** Injectable fetch for tests. */
-  fetch?: typeof fetch;
-}
-
-export interface GitLabRequestInput {
-  method: GitLabApiMethod;
-  /** Path under the API base, e.g. `/projects/42/statuses/<sha>`. */
-  path: string;
-  query?: Record<string, string | number | boolean | undefined>;
-  body?: unknown;
-}
-
-/** Minimal authenticated GitLab REST client. */
-export interface GitLabClient {
-  readonly apiBaseUrl: string;
-  /** Call a GitLab v4 path. Throws {@link GitLabApiError} on non-2xx. */
-  request<T = unknown>(input: GitLabRequestInput): Promise<T>;
-}
-
-export interface GitLabApiMergeRequest {
-  iid: number;
-  title?: string;
-  description?: string;
-  state?: string;
-  draft?: boolean;
-  webUrl?: string;
-  headSha?: string;
-  sourceBranch?: string;
-  targetBranch?: string;
-  authorUsername?: string;
-  baseSha?: string;
-  changedFilesCount?: number;
-}
-
-export interface GitLabApiMergeRequestDiff {
-  oldPath: string;
-  newPath: string;
-  patch?: string;
-  status: "added" | "modified" | "removed" | "renamed";
-}
-
-/** Project-bound merge-request reads shared by GitLab agents. */
-export interface GitLabApi {
-  getMergeRequest(iid: number): Promise<GitLabApiMergeRequest>;
-  getMergeBaseSha(base: string, headSha: string): Promise<string | undefined>;
-  listMergeRequestDiffs(iid: number): Promise<GitLabApiMergeRequestDiff[]>;
-}
-
-function envValue(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
-}
-
-/** `GITLAB_TOKEN` when set. */
-export function envGitLabToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
-  return envValue(env.GITLAB_TOKEN);
-}
-
-/**
- * REST base for direct calls: `GITLAB_API_BASE_URL`, else `/api/v4` on the
- * given project web URL's origin (self-managed hosts), else gitlab.com.
- */
-export function gitlabApiBaseUrl(input?: {
-  projectWebUrl?: string;
-  env?: NodeJS.ProcessEnv;
-}): string {
-  const fromEnv = envValue((input?.env ?? process.env).GITLAB_API_BASE_URL);
-  if (fromEnv !== undefined) {
-    return fromEnv.replace(/\/+$/, "");
-  }
-  if (input?.projectWebUrl !== undefined) {
-    try {
-      return `${new URL(input.projectWebUrl).origin}/api/v4`;
-    } catch {
-      // fall through to the default host
-    }
-  }
-  return DEFAULT_GITLAB_API_BASE_URL;
-}
-
-/**
- * GitLab's `:id` path segment accepts a numeric id or a URL-encoded
- * `group/project` path.
- */
-export function gitlabProjectPathSegment(project: number | string): string {
-  return typeof project === "number"
-    ? String(project)
-    : encodeURIComponent(project.replace(/^\/+|\/+$/g, ""));
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-function nonEmptyString(value: unknown): string | undefined {
-  return typeof value === "string" && value !== "" ? value : undefined;
-}
-
-const GITLAB_DIFFS_PER_PAGE = 100;
-
-export function createGitLabApi(
-  client: Pick<GitLabClient, "request">,
-  project: number | string,
-): GitLabApi {
-  const projectPath = `/projects/${gitlabProjectPathSegment(project)}`;
-  return {
-    async getMergeRequest(iid) {
-      const raw = await client.request<Record<string, unknown>>({
-        method: "GET",
-        path: `${projectPath}/merge_requests/${iid}`,
-      });
-      const diffRefs = asRecord(raw.diff_refs);
-      const changesCount = nonEmptyString(raw.changes_count);
-      return {
-        iid: (raw.iid as number | null | undefined) ?? iid,
-        title: raw.title as string | undefined,
-        description: raw.description === null ? undefined : (raw.description as string | undefined),
-        state: raw.state as string | undefined,
-        draft:
-          typeof raw.draft === "boolean"
-            ? raw.draft
-            : typeof raw.work_in_progress === "boolean"
-              ? raw.work_in_progress
-              : undefined,
-        webUrl: raw.web_url as string | undefined,
-        headSha:
-          (raw.sha as string | null | undefined) ?? (diffRefs?.head_sha as string | undefined),
-        sourceBranch: raw.source_branch as string | undefined,
-        targetBranch: raw.target_branch as string | undefined,
-        authorUsername: asRecord(raw.author)?.username as string | undefined,
-        baseSha: nonEmptyString(diffRefs?.base_sha),
-        changedFilesCount:
-          changesCount !== undefined && /^\d+$/.test(changesCount)
-            ? Number(changesCount)
-            : undefined,
-      };
-    },
-    async getMergeBaseSha(base, headSha) {
-      const data = await client.request<{ id?: string }>({
-        method: "GET",
-        path: `${projectPath}/repository/merge_base?refs[]=${encodeURIComponent(base)}&refs[]=${encodeURIComponent(headSha)}`,
-      });
-      return nonEmptyString(data.id);
-    },
-    async listMergeRequestDiffs(iid) {
-      const files: GitLabApiMergeRequestDiff[] = [];
-      for (let page = 1; ; page += 1) {
-        const diffs = await client.request<Record<string, unknown>[]>({
-          method: "GET",
-          path: `${projectPath}/merge_requests/${iid}/diffs`,
-          query: { page, per_page: GITLAB_DIFFS_PER_PAGE },
-        });
-        for (const diff of diffs) {
-          const status =
-            diff.new_file === true
-              ? "added"
-              : diff.deleted_file === true
-                ? "removed"
-                : diff.renamed_file === true
-                  ? "renamed"
-                  : "modified";
-          const rawPatch = typeof diff.diff === "string" ? diff.diff : undefined;
-          files.push({
-            oldPath: diff.old_path as string,
-            newPath: diff.new_path as string,
-            status,
-            patch: rawPatch?.replace(/\n$/, ""),
-          });
-        }
-        if (diffs.length < GITLAB_DIFFS_PER_PAGE) {
-          return files;
-        }
-      }
-    },
-  };
-}
-
-function buildQuery(query: GitLabRequestInput["query"]): string {
-  if (query === undefined) {
-    return "";
-  }
-  const params = new URLSearchParams();
-  for (const [key, value] of Object.entries(query)) {
-    if (value !== undefined) {
-      params.set(key, String(value));
-    }
-  }
-  const encoded = params.toString();
-  return encoded === "" ? "" : `?${encoded}`;
-}
-
-export function createGitLabClient(options: GitLabClientOptions = {}): GitLabClient {
-  const fetchImpl = options.fetch ?? fetch;
-  const apiBaseUrl = (
-    options.proxy?.apiBaseUrl ??
-    options.apiBaseUrl ??
-    gitlabApiBaseUrl()
-  ).replace(/\/+$/, "");
-  const project = options.project?.trim().replace(/^\/+|\/+$/g, "");
-
-  const authHeaders = async (): Promise<Record<string, string>> => {
-    if (options.proxy !== undefined) {
-      const headers: Record<string, string> = {
-        authorization: `Bearer ${await options.proxy.getApiKey()}`,
-        ...options.proxy.headers,
-      };
-      if (
-        (headers[CURSOR_GITLAB_PROJECTS_HEADER] ?? "").trim() === "" &&
-        project !== undefined &&
-        project !== ""
-      ) {
-        headers[CURSOR_GITLAB_PROJECTS_HEADER] = project.toLowerCase();
-      }
-      return headers;
-    }
-    const token =
-      typeof options.token === "function"
-        ? await options.token()
-        : (options.token ?? envGitLabToken());
-    if (token === undefined || token === "") {
-      throw new Error(
-        "gitlabChannel: no GitLab credential available (pass token, set GITLAB_TOKEN, or serve with --cursor-scm-proxy and cursorAccount).",
-      );
-    }
-    return { "private-token": token };
-  };
-
-  return {
-    apiBaseUrl,
-    async request<T = unknown>(input: GitLabRequestInput): Promise<T> {
-      const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
-      const response = await fetchImpl(`${apiBaseUrl}${path}${buildQuery(input.query)}`, {
-        method: input.method,
-        headers: {
-          ...(await authHeaders()),
-          accept: "application/json",
-          ...(input.body === undefined ? {} : { "content-type": "application/json" }),
-        },
-        body: input.body === undefined ? undefined : JSON.stringify(input.body),
-      });
-      const text = await response.text();
-      let parsed: unknown;
-      try {
-        parsed = text === "" ? undefined : JSON.parse(text);
-      } catch {
-        parsed = text;
-      }
-      if (!response.ok) {
-        throw new GitLabApiError({
-          body: parsed,
-          method: input.method,
-          path,
-          status: response.status,
-        });
-      }
-      return parsed as T;
-    },
-  };
-}

package/src/channels/gitlab/binding.ts

@@ -1,231 +0,0 @@
-/**
- * Project / merge-request binding parsed from a GitLab webhook payload.
- *
- * Every GitLab hook payload carries `project` (`id`, `path_with_namespace`,
- * `web_url`); the merge request lives under `object_attributes` for
- * `merge_request` events and under `merge_request` for `note` / `pipeline`.
- */
-
-import {
-  createGitLabClient,
-  type GitLabClient,
-  type GitLabProxyTransport,
-  type GitLabRequestInput,
-  type GitLabTokenProvider,
-  gitlabApiBaseUrl,
-} from "./api.js";
-import {
-  createGitLabCheck,
-  type GitLabCheck,
-  type GitLabCheckCreateInput,
-  type GitLabCommitStatus,
-  type GitLabCommitStatusInput,
-  setGitLabCommitStatus,
-} from "./checks.js";
-import type {
-  GitLabMergeRequestEvent,
-  GitLabNoteableType,
-  GitLabProjectRef,
-  GitLabUser,
-} from "./types.js";
-
-/** GitLab operations exposed to hooks (`ctx.gitlab`), bound to the project. */
-export interface GitLabHandle {
-  project: GitLabProjectRef;
-  /** Call a GitLab v4 path. Throws `GitLabApiError` on API failure. */
-  request<T = unknown>(input: GitLabRequestInput): Promise<T>;
-  /** Post a commit status on the bound project. */
-  setCommitStatus(input: Omit<GitLabCommitStatusInput, "project">): Promise<GitLabCommitStatus>;
-  /** Open a commit status through the shared check lifecycle. */
-  createCheck(input: Omit<GitLabCheckCreateInput, "gitlab" | "project">): Promise<GitLabCheck>;
-}
-
-/**
- * Build `ctx.gitlab` for one delivery. Lazy: no credential is resolved until
- * the first call, so channels without outbound GitLab access still dispatch.
- * Proxy mode (`cursorAccount` + `--cursor-scm-proxy`) wins when the host
- * bound a transport; otherwise direct access with `token` / `GITLAB_TOKEN`.
- *
- * Nothing credentialed is derived from the payload: the API base comes from
- * `apiBaseUrl` / `GITLAB_API_BASE_URL` (else gitlab.com), never from the
- * delivery's `project.web_url`, so a forged hook cannot redirect the token to
- * another host. Writes address the project by `path_with_namespace` — the
- * same field the `projects` allowlist admits on — rather than by the
- * independently forgeable numeric `project.id`.
- */
-export function buildGitLabBinding(input: {
-  project: GitLabProjectRef;
-  proxy?: GitLabProxyTransport;
-  token?: string | GitLabTokenProvider;
-  apiBaseUrl?: string;
-  fetch?: typeof fetch;
-}): GitLabHandle {
-  let client: GitLabClient | undefined;
-  const getClient = (): GitLabClient => {
-    client ??= createGitLabClient({
-      proxy: input.proxy,
-      token: input.token,
-      apiBaseUrl: input.apiBaseUrl ?? gitlabApiBaseUrl(),
-      project: input.project.pathWithNamespace,
-      fetch: input.fetch,
-    });
-    return client;
-  };
-  return {
-    project: input.project,
-    request: request => getClient().request(request),
-    setCommitStatus: status =>
-      setGitLabCommitStatus(getClient(), {
-        ...status,
-        project: input.project.pathWithNamespace,
-      }),
-    createCheck: check =>
-      createGitLabCheck({
-        ...check,
-        gitlab: getClient(),
-        project: input.project.pathWithNamespace,
-      }),
-  };
-}
-
-export function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-export function asNonEmptyString(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
-}
-
-export function asPositiveInt(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
-    return value;
-  }
-  if (typeof value === "string" && /^[1-9]\d*$/.test(value)) {
-    return Number(value);
-  }
-  return undefined;
-}
-
-export function asBoolean(value: unknown): boolean | undefined {
-  return typeof value === "boolean" ? value : undefined;
-}
-
-export function gitlabProjectFromPayload(
-  payload: Record<string, unknown>,
-): GitLabProjectRef | undefined {
-  const project = asRecord(payload.project);
-  const id = asPositiveInt(project?.id) ?? asPositiveInt(payload.project_id);
-  const pathWithNamespace = asNonEmptyString(project?.path_with_namespace);
-  if (id === undefined || pathWithNamespace === undefined) {
-    return undefined;
-  }
-  const webUrl = asNonEmptyString(project?.web_url) ?? `https://gitlab.com/${pathWithNamespace}`;
-  const defaultBranch = asNonEmptyString(project?.default_branch);
-  return {
-    id,
-    pathWithNamespace,
-    webUrl,
-    ...(defaultBranch === undefined ? {} : { defaultBranch }),
-  };
-}
-
-export function gitlabUser(value: unknown): GitLabUser | undefined {
-  const record = asRecord(value);
-  const id = asPositiveInt(record?.id);
-  const username = asNonEmptyString(record?.username);
-  if (id === undefined || username === undefined) {
-    return undefined;
-  }
-  const name = asNonEmptyString(record?.name);
-  return name === undefined ? { id, username } : { id, username, name };
-}
-
-/**
- * The actor of a delivery. Most hooks nest it under `user`; `push` and
- * `tag_push` flatten it to top-level `user_id` / `user_username` /
- * `user_name` instead.
- */
-export function gitlabSender(payload: Record<string, unknown>): GitLabUser | undefined {
-  return (
-    gitlabUser(payload.user) ??
-    gitlabUser({
-      id: payload.user_id,
-      username: payload.user_username,
-      name: payload.user_name,
-    })
-  );
-}
-
-export function gitlabMergeRequestUrl(
-  project: GitLabProjectRef,
-  iid: number,
-  explicit?: string,
-): string {
-  return explicit ?? `${project.webUrl}/-/merge_requests/${iid}`;
-}
-
-/**
- * Whether an `update` payload marks a draft merge request ready. GitLab uses
- * either `changes.draft` or the legacy `changes.work_in_progress` shape.
- */
-export function gitlabDraftMarkedReady(payload: Record<string, unknown>): boolean {
-  const changes = asRecord(payload.changes);
-  const draft = asRecord(changes?.draft ?? changes?.work_in_progress);
-  return draft?.current === false && draft.previous !== false;
-}
-
-/** Normalize a merge-request record (`object_attributes` or `merge_request`). */
-export function gitlabMergeRequestFromRecord(
-  project: GitLabProjectRef,
-  record: Record<string, unknown> | undefined,
-): GitLabMergeRequestEvent | undefined {
-  const iid = asPositiveInt(record?.iid);
-  if (record === undefined || iid === undefined) {
-    return undefined;
-  }
-  const labels = Array.isArray(record.labels)
-    ? record.labels
-        .map(label => asNonEmptyString(asRecord(label)?.title))
-        .filter((title): title is string => title !== undefined)
-    : undefined;
-  const description =
-    record.description === null
-      ? null
-      : typeof record.description === "string"
-        ? record.description
-        : undefined;
-  return {
-    action: asNonEmptyString(record.action),
-    iid,
-    id: asPositiveInt(record.id),
-    url: gitlabMergeRequestUrl(project, iid, asNonEmptyString(record.url)),
-    title: asNonEmptyString(record.title),
-    description,
-    state: asNonEmptyString(record.state),
-    draft: asBoolean(record.draft) ?? asBoolean(record.work_in_progress),
-    sourceBranch: asNonEmptyString(record.source_branch),
-    targetBranch: asNonEmptyString(record.target_branch),
-    headSha: asNonEmptyString(asRecord(record.last_commit)?.id),
-    oldrev: asNonEmptyString(record.oldrev),
-    authorId: asPositiveInt(record.author_id),
-    ...(labels === undefined ? {} : { labels }),
-  };
-}
-
-const NOTEABLE_TYPES: Readonly<Record<string, GitLabNoteableType>> = {
-  MergeRequest: "merge_request",
-  Issue: "issue",
-  Commit: "commit",
-  Snippet: "snippet",
-};
-
-/** `noteable_type: "MergeRequest"` → `merge_request`; unknown values pass through. */
-export function normalizeGitLabNoteableType(value: unknown): string | undefined {
-  const raw = asNonEmptyString(value);
-  if (raw === undefined) {
-    return undefined;
-  }
-  return NOTEABLE_TYPES[raw] ?? raw.toLowerCase();
-}