@cursor/july 0.1.102 → 0.1.104

package/src/channels/github/state.ts

@@ -37,6 +37,7 @@ export function emptyGitHubChannelState(
     pullRequestNumber: null,
     repo: "",
     repositoryId: null,
+    repositoryUrl: null,
     reviewCommentId: null,
     reviewThreadRootCommentId: null,
     triggeringCommentId: null,
@@ -60,6 +61,8 @@ export function githubBindingStateForEvent(input: {
   repo: string;
   number: number;
   repositoryId?: number;
+  /** `repository.html_url` (GHES host lives here). */
+  repositoryUrl?: string;
   installationId?: number;
   triggeringCommentId?: number;
   reviewCommentId?: number;
@@ -74,6 +77,7 @@ export function githubBindingStateForEvent(input: {
       pullRequestNumber: null,
       repo: input.repo,
       repositoryId: input.repositoryId ?? null,
+      repositoryUrl: input.repositoryUrl ?? null,
       reviewCommentId: null,
       reviewThreadRootCommentId: null,
       triggeringCommentId: input.triggeringCommentId ?? null,
@@ -88,6 +92,7 @@ export function githubBindingStateForEvent(input: {
       pullRequestNumber: input.number,
       repo: input.repo,
       repositoryId: input.repositoryId ?? null,
+      repositoryUrl: input.repositoryUrl ?? null,
       reviewCommentId: input.reviewCommentId ?? null,
       reviewThreadRootCommentId:
         input.reviewThreadRootCommentId ??
@@ -105,6 +110,7 @@ export function githubBindingStateForEvent(input: {
     pullRequestNumber: input.number,
     repo: input.repo,
     repositoryId: input.repositoryId ?? null,
+    repositoryUrl: input.repositoryUrl ?? null,
     reviewCommentId: null,
     reviewThreadRootCommentId: null,
     triggeringCommentId: input.triggeringCommentId ?? null,

package/src/channels/github/types.ts

@@ -1,4 +1,4 @@
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -61,9 +61,6 @@ export interface GitHubChannelCredentials {
   privateKey?: GitHubCredentialValue;
 }
 
-/** @deprecated Prefer {@link GitHubChannelCredentials}. */
-export type GitHubCredentials = GitHubChannelCredentials;
-
 export type GitHubPullRequestAction =
   | "opened"
   | "reopened"
@@ -525,7 +522,7 @@ export interface GitHubChannelOptions {
   /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
   path?: string;
   /**
-   * Webhook events advertised to `agent-serve github forward` (published as
+   * Webhook events advertised to `agent-sdk github forward` (published as
    * `meta.githubWebhookEvents`). Defaults to the set derived from the declared
    * hooks. Set this to pin an exact list — e.g. to include events only handled
    * through {@link onEvent} such as `pull_request_review`.

package/src/channels/gitlab/api.ts

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

@@ -0,0 +1,233 @@
+/**
+ * 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}`;
+}
+
+/** 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();
+}