@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/cli-gitlab.ts

@@ -1,452 +0,0 @@
-/**
- * `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";
-import { projectPath, resolveProjectRoot } from "./project-layout.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) {
-    const channelPath = projectPath(resolveProjectRoot(dir), "channels/gitlab.ts");
-    process.stderr.write(
-      `no GitLab channel found. Author ${channelPath} 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) {
-    const channelPath = projectPath(resolveProjectRoot(dir), "channels/gitlab.ts");
-    process.stderr.write(`no GitLab channel found. Author ${channelPath} 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;
-}