@cursor/july 0.1.101 → 0.1.103

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

@@ -0,0 +1,114 @@
+/**
+ * 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,93 @@
+/**
+ * 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,44 @@
+/** {@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,176 @@
+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;
+}