@cursor/july 0.1.101 → 0.1.103

package/src/internal/cli-cursor.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-serve login | logout | whoami` — the Cursor account CLI.
+ * `agent-sdk login | logout | whoami` — the Cursor account CLI.
  *
  * `login` runs the same PKCE browser flow as `cursor-agent`, then uses the
  * short-lived session exactly once to mint a named, dashboard-revocable
@@ -28,6 +28,7 @@ import {
   startBrowserLogin,
   writeStoredCredentials,
 } from "./cursor/credentials.js";
+import { describeError } from "./describe-error.js";
 import { CLI_COMMAND_NAME } from "./distribution.js";
 import { openBrowser } from "./open-browser.js";
 import { stderrPalette, stdoutPalette } from "./terminal-style.js";
@@ -288,7 +289,3 @@ function describeLoginPollFailure(
       ].join("\n");
   }
 }
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/internal/cli-deploy.ts

@@ -47,6 +47,7 @@ import {
   validateDeploymentSlug,
 } from "./deploy-client.js";
 import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
+import { describeError } from "./describe-error.js";
 import {
   type ChildAgentDir,
   formatDiagnostics,
@@ -62,6 +63,7 @@ import {
   validateSettableSecretName,
 } from "./hosting.js";
 import { deployProgressLabel, sanitizeCustomerError } from "./logs-client.js";
+import { sleep } from "./sleep.js";
 import { stderrPalette } from "./terminal-style.js";
 
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
@@ -2210,11 +2212,3 @@ function renderTable(header: string[], rows: string[][]): string {
       .trimEnd();
   return [renderRow(header), ...rows.map(renderRow)].join("\n");
 }
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
-}

package/src/internal/cli-github.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-serve github …` CLI — forward live GitHub webhooks to a locally
+ * `agent-sdk github …` CLI — forward live GitHub webhooks to a locally
  * served agent via the `cli/gh-webhook` extension, plus a doctor and an
  * events lister.
  *
@@ -674,8 +674,8 @@ async function cmdGithubDoctor(options: GithubCliOptions): Promise<number> {
       installed && pinOk
         ? `${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN} installed`
         : !installed
-          ? `${GITHUB_WEBHOOK_EXTENSION} missing — run \`agent-serve github doctor --install\``
-          : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(extensionList) ?? "unknown"} (need ${GITHUB_WEBHOOK_EXTENSION_PIN}) — run \`agent-serve github doctor --install\``,
+          ? `${GITHUB_WEBHOOK_EXTENSION} missing — run \`${CLI} github doctor --install\``
+          : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(extensionList) ?? "unknown"} (need ${GITHUB_WEBHOOK_EXTENSION_PIN}) — run \`${CLI} github doctor --install\``,
   });
 
   const envToken = detectGitHubEnvTokenOverride();

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));
-}