@cursor/july 0.1.102 → 0.1.104

package/src/channels/gitlab/replay.ts

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

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

@@ -0,0 +1,263 @@
+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. Omitted inherits {@link AgentConfig.architecture}:
+   * engine-minted per-MR continuation unless the agent set
+   * `architecture: "v2"` (then `gitlab.mr/v2`, or `gitlab.none/v2` when a
+   * non-MR event is declared). Override with `"gitlab.none/v2"` for one-shot
+   * events.
+   */
+  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

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