@cursor/july 0.1.102 → 0.1.103

package/src/internal/cli-gitlab.ts

@@ -0,0 +1,485 @@
+/**
+ * `agent-sdk gitlab …` — replay a merge request into a local `gitlabChannel()`
+ * and list the discovered GitLab channels.
+ *
+ * There is no `gh webhook forward` analogue for GitLab: project hooks POST to
+ * a public URL, so live forwarding needs a tunnel (see `gitlab forward`,
+ * which prints the recipe rather than running one). Replay covers the local
+ * loop without either: it reads the MR over REST (`GITLAB_TOKEN`) and POSTs
+ * GitLab-shaped payloads with `X-Gitlab-Token` set from `--secret` /
+ * `GITLAB_WEBHOOK_SECRET`.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve as resolvePath } from "node:path";
+import { channelForwardUrl } from "../channels/github/forward.js";
+import {
+  createGitLabClient,
+  gitlabProjectPathSegment,
+} from "../channels/gitlab/api.js";
+import {
+  findGitLabChannelTargets,
+  type GitLabChannelTarget,
+} from "../channels/gitlab/gitlab-channel.js";
+import {
+  GITLAB_SYNTHESIZABLE_EVENTS,
+  parseGitLabMrRef,
+  type ReplayGitLabMergeRequest,
+  type ReplayGitLabPipeline,
+  type ReplayGitLabProject,
+  type SynthesizedGitLabEvent,
+  selectGitLabReplayEvents,
+  synthesizeGitLabEvent,
+} from "../channels/gitlab/replay.js";
+import { resolveAgentMounts } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3000;
+
+export interface GitlabCliOptions {
+  dir: string;
+  slug?: string;
+  channel?: string;
+  host?: string;
+  port?: number;
+  /** Explicit delivery URL (skips URL derivation). */
+  url?: string;
+  /** Comma/space-separated event list, or `*` for the channel's declared set. */
+  events?: string;
+  /** Hook secret sent as `X-Gitlab-Token` (defaults to GITLAB_WEBHOOK_SECRET). */
+  secret?: string;
+  json?: boolean;
+  /** replay: MR URL or `group/project!N`. */
+  mrUrl?: string;
+  /** replay: merge_request action (open, update, close, reopen, approved…). */
+  action?: string;
+  /** replay: pipeline status (success, failed, running…). */
+  conclusion?: string;
+  /** replay: note body. */
+  comment?: string;
+  dryRun?: boolean;
+  out?: string;
+}
+
+const GITLAB_HELP = `${CLI} gitlab — replay GitLab merge-request webhooks into a local agent
+
+Usage:
+  ${CLI} gitlab replay   <mr_url|group/project!N> [--events a,b,c | *]
+                              [--action A] [--conclusion STATUS] [--comment "…"]
+                              [--dir .] [--slug S] [--channel C]
+                              [--host H] [--port N] [--url URL] [--secret S]
+                              [--dry-run] [--out DIR] [--json]
+  ${CLI} gitlab events   [--dir .] [--host H] [--port N] [--json]
+  ${CLI} gitlab forward  [--dir .] [--host H] [--port N]
+
+Commands:
+  replay    Synthesize webhook payloads from a merge request you can *read*
+            (Reporter access is enough) and POST them to the discovered
+            gitlabChannel()s. Reads the MR over the REST API with GITLAB_TOKEN,
+            builds GitLab-shaped payloads for --events (default merge_request;
+            \`*\` = the channel's declared events: ${GITLAB_SYNTHESIZABLE_EVENTS.join(", ")}),
+            and sets X-Gitlab-Token from --secret / GITLAB_WEBHOOK_SECRET.
+            --dry-run prints them; --out writes them as fixtures.
+  events    List discovered GitLab channels and the object_kinds each accepts.
+  forward   Print the project-hook + tunnel recipe for live deliveries. GitLab
+            has no \`gh webhook forward\` analogue: hooks need a reachable URL.
+
+Prerequisites:
+  - GITLAB_TOKEN with read_api on the project (self-managed: also set
+    GITLAB_API_BASE_URL=https://<host>/api/v4, or pass a full MR URL).
+  - The agent already serving (\`${CLI} serve --dir . --dev\`).
+
+See also: docs/guides/gitlab.md
+`;
+
+export async function cmdGitlab(
+  subcommand: string | undefined,
+  options: GitlabCliOptions
+): Promise<number> {
+  switch (subcommand) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(GITLAB_HELP);
+      return subcommand === undefined ? 1 : 0;
+    case "replay":
+      return cmdGitlabReplay(options);
+    case "events":
+      return cmdGitlabEvents(options);
+    case "forward":
+      return cmdGitlabForward(options);
+    default:
+      process.stderr.write(`Unknown gitlab subcommand: ${subcommand}\n`);
+      process.stdout.write(GITLAB_HELP);
+      return 1;
+  }
+}
+
+interface ReplayTarget {
+  slug: string;
+  channelId: string;
+  url: string;
+  events: string[];
+}
+
+async function resolveTargets(
+  options: GitlabCliOptions
+): Promise<ReplayTarget[] | undefined> {
+  const dir = resolvePath(options.dir);
+  const channels = findGitLabChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  let candidates: GitLabChannelTarget[] = channels;
+  if (options.slug !== undefined) {
+    candidates = candidates.filter((c) => c.slug === options.slug);
+  }
+  if (options.channel !== undefined) {
+    candidates = candidates.filter((c) => c.channelId === options.channel);
+  }
+  if (options.url !== undefined && candidates.length > 1) {
+    process.stderr.write(
+      "--url targets a single channel; narrow with --slug/--channel\n"
+    );
+    return undefined;
+  }
+  if (candidates.length === 0 && options.url === undefined) {
+    process.stderr.write(
+      "no GitLab channel found. Author agent/channels/gitlab.ts with gitlabChannel(), or pass --url.\n"
+    );
+    return undefined;
+  }
+  if (options.url !== undefined) {
+    return [
+      {
+        slug: candidates[0]?.slug ?? "",
+        channelId: candidates[0]?.channelId ?? "",
+        url: options.url,
+        events: candidates[0]?.events ?? [],
+      },
+    ];
+  }
+  return candidates.map((c) => ({
+    slug: c.slug,
+    channelId: c.channelId,
+    url: channelForwardUrl({
+      host,
+      port,
+      slug: c.slug,
+      channelId: c.channelId,
+      routePath: c.routePath,
+    }),
+    events: c.events,
+  }));
+}
+
+async function cmdGitlabReplay(options: GitlabCliOptions): Promise<number> {
+  const mrUrl = options.mrUrl;
+  if (mrUrl === undefined || mrUrl === "") {
+    process.stderr.write("gitlab replay needs an MR URL or group/project!N\n");
+    return 1;
+  }
+  const ref = parseGitLabMrRef(mrUrl);
+  if (ref === undefined) {
+    process.stderr.write(`could not parse merge request ref: ${mrUrl}\n`);
+    return 1;
+  }
+  const targets = await resolveTargets(options);
+  if (targets === undefined) {
+    return 1;
+  }
+
+  const requested = parseEventList(options.events);
+  const declared = [...new Set(targets.flatMap((target) => target.events))];
+  const { events, unsupported } = selectGitLabReplayEvents(requested, declared);
+  if (unsupported.length > 0) {
+    process.stderr.write(
+      `[agent-sdk] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
+    );
+  }
+  if (events.length === 0) {
+    process.stderr.write("no synthesizable events selected\n");
+    return 1;
+  }
+
+  // Read the MR — Reporter access is enough.
+  const gitlab = createGitLabClient({
+    apiBaseUrl:
+      process.env.GITLAB_API_BASE_URL?.trim() || `${ref.origin}/api/v4`,
+  });
+  const projectSegment = gitlabProjectPathSegment(ref.projectPath);
+  let project: ReplayGitLabProject;
+  let mergeRequest: ReplayGitLabMergeRequest;
+  try {
+    project = await gitlab.request<ReplayGitLabProject>({
+      method: "GET",
+      path: `/projects/${projectSegment}`,
+    });
+    mergeRequest = await gitlab.request<ReplayGitLabMergeRequest>({
+      method: "GET",
+      path: `/projects/${projectSegment}/merge_requests/${ref.iid}`,
+    });
+  } catch (error) {
+    process.stderr.write(
+      `failed to read ${ref.label} via ${gitlab.apiBaseUrl}: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+  let pipeline: ReplayGitLabPipeline | undefined;
+  if (events.includes("pipeline")) {
+    pipeline = await gitlab
+      .request<ReplayGitLabPipeline[]>({
+        method: "GET",
+        path: `/projects/${projectSegment}/merge_requests/${ref.iid}/pipelines`,
+      })
+      .then((list) => list[0])
+      .catch(() => undefined);
+  }
+
+  const synthesized: SynthesizedGitLabEvent[] = [];
+  for (const event of events) {
+    const result = synthesizeGitLabEvent({
+      event,
+      project,
+      mergeRequest,
+      action: options.action,
+      comment: options.comment,
+      status: options.conclusion,
+      pipeline,
+    });
+    if ("error" in result) {
+      process.stderr.write(`[agent-sdk] skipping ${event}: ${result.error}\n`);
+      continue;
+    }
+    synthesized.push(result);
+  }
+  if (synthesized.length === 0) {
+    process.stderr.write("nothing to replay after synthesis\n");
+    return 1;
+  }
+
+  const secret = options.secret ?? process.env.GITLAB_WEBHOOK_SECRET;
+  process.stderr.write(
+    `[agent-sdk] replaying ${ref.label} (${synthesized
+      .map(eventLabel)
+      .join(
+        ", "
+      )}) → ${targets.length} channel${targets.length === 1 ? "" : "s"}\n`
+  );
+
+  const report: Array<Record<string, unknown>> = [];
+  let anyRejected = false;
+  for (const event of synthesized) {
+    const body = JSON.stringify(event.payload);
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      "x-gitlab-event": event.header,
+      "x-gitlab-event-uuid": randomUUID(),
+    };
+    if (secret !== undefined && secret !== "") {
+      headers["x-gitlab-token"] = secret;
+    }
+    if (options.out !== undefined) {
+      const file = await writeReplayFixture(options.out, event);
+      process.stderr.write(`[agent-sdk] wrote ${file}\n`);
+    }
+    const label = eventLabel(event);
+    if (options.dryRun === true) {
+      report.push({ ...eventReport(event), payload: event.payload });
+      if (options.json !== true) {
+        process.stdout.write(
+          `--- ${label} ---\n${JSON.stringify(event.payload, null, 2)}\n`
+        );
+      }
+      continue;
+    }
+    const deliveries = await deliverReplayEvent(
+      body,
+      headers,
+      event.eventName,
+      targets
+    );
+    if (deliveries.length === 0 || deliveries.some((d) => !d.ok)) {
+      anyRejected = true;
+    }
+    report.push({ ...eventReport(event), deliveries });
+    if (options.json !== true) {
+      const summary =
+        deliveries
+          .map(
+            (d) => `${d.label} ${d.status || "ERR"}${d.ok ? "" : " (rejected)"}`
+          )
+          .join(", ") || "(no matching channel)";
+      process.stderr.write(`[agent-sdk]   ${label} → ${summary}\n`);
+    }
+  }
+
+  if (options.json === true) {
+    process.stdout.write(
+      `${JSON.stringify(
+        { mr: ref.label, dryRun: options.dryRun === true, events: report },
+        null,
+        2
+      )}\n`
+    );
+  }
+  return anyRejected ? 1 : 0;
+}
+
+interface ReplayDelivery {
+  label: string;
+  status: number;
+  ok: boolean;
+  error?: string;
+}
+
+async function deliverReplayEvent(
+  body: string,
+  headers: Record<string, string>,
+  eventName: string,
+  targets: readonly ReplayTarget[]
+): Promise<ReplayDelivery[]> {
+  const recipients = targets.filter(
+    (target) => target.events.length === 0 || target.events.includes(eventName)
+  );
+  return Promise.all(
+    recipients.map(async (target) => {
+      const label =
+        target.slug === ""
+          ? target.channelId
+          : `${target.slug}/${target.channelId}`;
+      try {
+        const response = await fetch(target.url, {
+          method: "POST",
+          headers,
+          body,
+        });
+        await response.text().catch(() => undefined);
+        return { label, status: response.status, ok: response.ok };
+      } catch (error) {
+        return {
+          label,
+          status: 0,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })
+  );
+}
+
+function eventLabel(event: SynthesizedGitLabEvent): string {
+  return event.action === undefined
+    ? event.eventName
+    : `${event.eventName}.${event.action}`;
+}
+
+function eventReport(event: SynthesizedGitLabEvent): Record<string, unknown> {
+  return { event: event.eventName, action: event.action };
+}
+
+async function writeReplayFixture(
+  outDir: string,
+  event: SynthesizedGitLabEvent
+): Promise<string> {
+  const dir = resolvePath(outDir);
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, `gitlab-${eventLabel(event)}.json`);
+  await writeFile(file, `${JSON.stringify(event.payload, null, 2)}\n`);
+  return file;
+}
+
+async function cmdGitlabEvents(options: GitlabCliOptions): Promise<number> {
+  const dir = resolvePath(options.dir);
+  const channels = findGitLabChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  const rows = channels.map((c) => ({
+    slug: c.slug,
+    channelId: c.channelId,
+    url: channelForwardUrl({
+      host,
+      port,
+      slug: c.slug,
+      channelId: c.channelId,
+      routePath: c.routePath,
+    }),
+    events: c.events,
+  }));
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify({ channels: rows }, null, 2)}\n`);
+    return 0;
+  }
+  if (rows.length === 0) {
+    process.stdout.write("no GitLab channels found\n");
+    return 0;
+  }
+  for (const row of rows) {
+    const label =
+      row.slug === "" ? row.channelId : `${row.slug}/${row.channelId}`;
+    process.stdout.write(
+      `${label}\n  ${row.url}\n  ${row.events.join(", ")}\n`
+    );
+  }
+  return 0;
+}
+
+async function cmdGitlabForward(options: GitlabCliOptions): Promise<number> {
+  const dir = resolvePath(options.dir);
+  const channels = findGitLabChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  if (channels.length === 0) {
+    process.stderr.write(
+      "no GitLab channel found. Author agent/channels/gitlab.ts with gitlabChannel().\n"
+    );
+    return 1;
+  }
+  const lines = [
+    "GitLab project hooks deliver to a public URL; there is no local relay.",
+    "To receive live deliveries:",
+    "",
+    `  1. Expose the agent: e.g. \`cloudflared tunnel --url http://${host}:${port}\``,
+    "     (or ngrok / any HTTPS tunnel) and note the public base URL.",
+    "  2. In GitLab → Project → Settings → Webhooks, add one hook per channel:",
+  ];
+  for (const c of channels) {
+    const path = channelForwardUrl({
+      host,
+      port,
+      slug: c.slug,
+      channelId: c.channelId,
+      routePath: c.routePath,
+    }).replace(`http://${host}:${port}`, "<tunnel>");
+    lines.push(`       URL:     ${path}`);
+    lines.push(`       Trigger: ${c.events.join(", ")}`);
+    lines.push(
+      "       Secret token: the value of GITLAB_WEBHOOK_SECRET (or webhookSecret)"
+    );
+  }
+  lines.push(
+    "",
+    `  3. Serve with the secret set so X-Gitlab-Token is verified:`,
+    `     GITLAB_WEBHOOK_SECRET=… ${CLI} serve --dir . --dev`,
+    "",
+    `Without a tunnel, \`${CLI} gitlab replay <mr_url>\` exercises the same channel locally.`,
+    ""
+  );
+  process.stdout.write(lines.join("\n"));
+  return 0;
+}
+
+function parseEventList(value: string | undefined): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const events = value
+    .split(/[\s,]+/)
+    .map((event) => event.trim())
+    .filter(Boolean);
+  return events.length === 0 ? undefined : events;
+}

package/src/internal/cli-mcp.ts

@@ -37,6 +37,7 @@ import {
   resolveProdSlug,
   resolveProdTarget,
 } from "./resolve-prod-target.js";
+import { sleep as defaultSleep } from "./sleep.js";
 
 /** Mount path of the MCP surface relative to an agent base URL. */
 const MCP_PATH = "/v1/mcp";
@@ -163,7 +164,7 @@ export async function cmdMcpServe(options: McpCliOptions): Promise<number> {
   const stdin = options.stdin ?? process.stdin;
   const stdout = options.stdout ?? process.stdout;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const sleep = options.sleep ?? sleepMs;
+  const sleep = options.sleep ?? defaultSleep;
   const pending = new Set<Promise<void>>();
 
   const handleLine = async (line: string): Promise<void> => {
@@ -836,9 +837,3 @@ function describeError(error: unknown): string {
 function defaultErr(text: string): void {
   process.stderr.write(text);
 }
-
-function sleepMs(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}

package/src/internal/cli-slack.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-serve slack …` CLI — doctor, destroy/icon, `create` as a
+ * `agent-sdk slack …` CLI — doctor, destroy/icon, `create` as a
  * dashboard-wizard launcher (`slack-provision-client.ts`), and
  * `init --manual` for Slack CLI / paste-at-api.slack.com manifests.
  */
@@ -39,6 +39,7 @@ import {
   type SlackWizardMintResult,
   type SlackWizardPollResult,
 } from "./slack-provision-client.js";
+import { sleep } from "./sleep.js";
 import { stderrPalette, type TerminalPalette } from "./terminal-style.js";
 
 export interface SlackCliOptions {
@@ -884,7 +885,3 @@ async function fileExists(path: string): Promise<boolean> {
 function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && "code" in error;
 }
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
-}

package/src/internal/continuation-channel.ts

@@ -1,5 +1,7 @@
+import { getBitbucketChannelOptions } from "../channels/bitbucket/bitbucket-channel.js";
 import { getDeploymentsChannelOptions } from "../channels/deployments/deployments-channel.js";
 import { getGitHubChannelOptions } from "../channels/github/github-channel.js";
+import { getGitLabChannelOptions } from "../channels/gitlab/gitlab-channel.js";
 import { getOriginChannelOptions } from "../channels/origin/origin-channel.js";
 import { getSlackChannelOptions } from "../channels/slack/slack-channel.js";
 import type {
@@ -14,6 +16,7 @@ import {
   defaultContinuationSelector,
   handshakeContinuation,
   normalizeIdentity,
+  omittedV2MembershipDowngrade,
 } from "./continuation-identity.js";
 
 type ContinuationChannelOptions = {
@@ -21,10 +24,20 @@ type ContinuationChannelOptions = {
 };
 
 const CONTINUATION_CHANNEL_PACKS: ReadonlyArray<{
-  kind: "github" | "slack" | "origin" | "deployments";
+  kind: "github" | "slack" | "origin" | "gitlab" | "bitbucket" | "deployments";
   getOptions: (definition: object) => ContinuationChannelOptions | undefined;
   usesDeclaredEvents: boolean;
 }> = [
+  {
+    kind: "gitlab",
+    getOptions: getGitLabChannelOptions,
+    usesDeclaredEvents: true,
+  },
+  {
+    kind: "bitbucket",
+    getOptions: getBitbucketChannelOptions,
+    usesDeclaredEvents: true,
+  },
   {
     kind: "github",
     getOptions: getGitHubChannelOptions,
@@ -94,6 +107,72 @@ export function applyAgentContinuationDefaults(project: {
   }
 }
 
+/**
+ * Warn when an omitted `/v2` selector became type `none` because one
+ * declared event sits outside the kind membership. Call before
+ * {@link applyAgentContinuationDefaults} so the omitted field is still
+ * visible. An explicit `*.none/v2` pin stays silent.
+ */
+export function warnOmittedContinuationDowngrades(input: {
+  architecture?: AgentArchitecture;
+  channels: ReadonlyArray<{ id: string; definition: object }>;
+  warn: (id: string, message: string) => void;
+}): void {
+  if (input.architecture !== "v2") {
+    return;
+  }
+  for (const channel of input.channels) {
+    const events = channelDeclaredEventTypes(
+      (channel.definition as ChannelDefinition).meta
+    );
+    for (const pack of CONTINUATION_CHANNEL_PACKS) {
+      const options = pack.getOptions(channel.definition);
+      if (options === undefined) {
+        continue;
+      }
+      if (options.continuation !== undefined) {
+        break;
+      }
+      const downgrade = omittedV2MembershipDowngrade(
+        pack.kind,
+        pack.usesDeclaredEvents ? events : undefined
+      );
+      if (downgrade !== undefined) {
+        input.warn(
+          channel.id,
+          omittedContinuationDowngradeMessage(pack.kind, downgrade)
+        );
+      }
+      break;
+    }
+  }
+}
+
+function omittedContinuationDowngradeMessage(
+  kind: string,
+  downgrade: {
+    selector: ContinuationIdentity;
+    unexpected: readonly string[];
+  }
+): string {
+  const membership =
+    kind === "github"
+      ? "pr"
+      : kind === "origin"
+        ? "origin-pr"
+        : kind === "deployments"
+          ? "deployment"
+          : kind;
+  return (
+    `omitted continuation stamped ${downgrade.selector} because ` +
+    `${downgrade.unexpected.join(", ")} ${
+      downgrade.unexpected.length === 1 ? "is" : "are"
+    } not in the ${membership} membership; every delivery on this ` +
+    `channel starts a fresh session. Pin continuation: "${downgrade.selector}" ` +
+    `if that is intended, or drop the event.`
+  );
+}
+
 function stampOmittedChannelContinuation(
   definition: object,
   version: ContinuationProtocolVersion
@@ -124,6 +203,8 @@ export function channelDeclaredEventTypes(
   return (
     meta?.githubWebhookEvents ??
     meta?.originWebhookEvents ??
+    meta?.gitlabWebhookEvents ??
+    meta?.bitbucketWebhookEvents ??
     meta?.deploymentEventTypes
   );
 }