@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/cli-bitbucket.ts

@@ -1,438 +0,0 @@
-/**
- * `agent-sdk bitbucket …` — replay a pull request into a local
- * `bitbucketChannel()` and list the discovered Bitbucket channels.
- *
- * Like GitLab, Bitbucket repository hooks POST to a public URL, so live
- * forwarding needs a tunnel (`bitbucket forward` prints the recipe). Replay
- * covers the local loop without one: it reads the PR over REST
- * (`BITBUCKET_TOKEN`) in the host's dialect and POSTs Bitbucket-shaped
- * payloads with `X-Hub-Signature` computed from `--secret` /
- * `BITBUCKET_WEBHOOK_SECRET`.
- */
-
-import { randomUUID } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve as resolvePath } from "node:path";
-import {
-  type BitbucketApiPullRequest,
-  bitbucketApiBaseUrl,
-  createBitbucketApi,
-  createBitbucketClient,
-} from "../channels/bitbucket/api.js";
-import {
-  type BitbucketChannelTarget,
-  findBitbucketChannelTargets,
-} from "../channels/bitbucket/bitbucket-channel.js";
-import { signBitbucketWebhookBody } from "../channels/bitbucket/bitbucket-webhook.js";
-import {
-  BITBUCKET_SYNTHESIZABLE_EVENTS,
-  parseBitbucketPrRef,
-  type SynthesizedBitbucketEvent,
-  selectBitbucketReplayEvents,
-  synthesizeBitbucketEvent,
-} from "../channels/bitbucket/replay.js";
-import { channelForwardUrl } from "../channels/github/forward.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 BitbucketCliOptions {
-  dir: string;
-  slug?: string;
-  channel?: string;
-  host?: string;
-  port?: number;
-  /** Explicit delivery URL (skips URL derivation). */
-  url?: string;
-  /** Comma/space-separated event keys (either dialect), or `*` for the declared set. */
-  events?: string;
-  /** Hook secret used to sign `X-Hub-Signature` (defaults to BITBUCKET_WEBHOOK_SECRET). */
-  secret?: string;
-  json?: boolean;
-  /** replay: PR URL (Cloud or Data Center) or `workspace/repo#N`. */
-  prUrl?: string;
-  /** replay: comment body. */
-  comment?: string;
-  dryRun?: boolean;
-  out?: string;
-}
-
-const BITBUCKET_HELP = `${CLI} bitbucket — replay Bitbucket pull-request webhooks into a local agent
-
-Usage:
-  ${CLI} bitbucket replay   <pr_url|workspace/repo#N> [--events a,b,c | *]
-                                 [--comment "…"] [--dir .] [--slug S] [--channel C]
-                                 [--host H] [--port N] [--url URL] [--secret S]
-                                 [--dry-run] [--out DIR] [--json]
-  ${CLI} bitbucket events   [--dir .] [--host H] [--port N] [--json]
-  ${CLI} bitbucket forward  [--dir .] [--host H] [--port N]
-
-Commands:
-  replay    Synthesize webhook payloads from a pull request you can *read* and
-            POST them to the discovered bitbucketChannel()s. Reads the PR over
-            the REST API with BITBUCKET_TOKEN in the host's dialect (Cloud 2.0
-            for bitbucket.org, Data Center 1.0 for a /projects/…/repos/… URL),
-            builds payloads in that dialect for --events (default
-            pullrequest:created; \`*\` = the channel's declared events; Data
-            Center keys such as pr:opened are accepted:
-            ${BITBUCKET_SYNTHESIZABLE_EVENTS.join(", ")}),
-            and signs X-Hub-Signature from --secret / BITBUCKET_WEBHOOK_SECRET.
-            --dry-run prints them; --out writes them as fixtures.
-  events    List discovered Bitbucket channels and the event keys each accepts.
-  forward   Print the repository-hook + tunnel recipe for live deliveries.
-
-Prerequisites:
-  - BITBUCKET_TOKEN with pull request read access (Data Center: an HTTP
-    access token; or set BITBUCKET_API_BASE_URL to the REST base).
-  - The agent already serving (\`${CLI} serve --dir . --dev\`).
-`;
-
-export async function cmdBitbucket(
-  subcommand: string | undefined,
-  options: BitbucketCliOptions,
-): Promise<number> {
-  switch (subcommand) {
-    case undefined:
-    case "help":
-    case "--help":
-    case "-h":
-      process.stdout.write(BITBUCKET_HELP);
-      return subcommand === undefined ? 1 : 0;
-    case "replay":
-      return cmdBitbucketReplay(options);
-    case "events":
-      return cmdBitbucketEvents(options);
-    case "forward":
-      return cmdBitbucketForward(options);
-    default:
-      process.stderr.write(`Unknown bitbucket subcommand: ${subcommand}\n`);
-      process.stdout.write(BITBUCKET_HELP);
-      return 1;
-  }
-}
-
-interface ReplayTarget {
-  slug: string;
-  channelId: string;
-  url: string;
-  events: string[];
-}
-
-async function resolveTargets(options: BitbucketCliOptions): Promise<ReplayTarget[] | undefined> {
-  const dir = resolvePath(options.dir);
-  const channels = findBitbucketChannelTargets(await resolveAgentMounts(dir));
-  const host = options.host ?? DEFAULT_HOST;
-  const port = options.port ?? DEFAULT_PORT;
-  let candidates: BitbucketChannelTarget[] = 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/bitbucket.ts");
-    process.stderr.write(
-      `no Bitbucket channel found. Author ${channelPath} with bitbucketChannel(), 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 cmdBitbucketReplay(options: BitbucketCliOptions): Promise<number> {
-  const prUrl = options.prUrl;
-  if (prUrl === undefined || prUrl === "") {
-    process.stderr.write("bitbucket replay needs a PR URL or workspace/repo#N\n");
-    return 1;
-  }
-  const ref = parseBitbucketPrRef(prUrl);
-  if (ref === undefined) {
-    process.stderr.write(`could not parse pull request ref: ${prUrl}\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 } = selectBitbucketReplayEvents(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 PR in the host's dialect — read access is enough.
-  const apiBaseUrl = bitbucketApiBaseUrl({
-    dialect: ref.dialect,
-    repoHtmlUrl: ref.repository.htmlUrl,
-  });
-  let pullRequest: BitbucketApiPullRequest;
-  try {
-    const client = createBitbucketClient({ apiBaseUrl });
-    pullRequest = await createBitbucketApi(client, ref.repository).getPullRequest(ref.id);
-  } catch (error) {
-    process.stderr.write(
-      `failed to read ${ref.label} via ${apiBaseUrl ?? "(no API base)"}: ${
-        error instanceof Error ? error.message : String(error)
-      }\n`,
-    );
-    return 1;
-  }
-
-  const synthesized: SynthesizedBitbucketEvent[] = [];
-  for (const event of events) {
-    const result = synthesizeBitbucketEvent({
-      event,
-      ref,
-      pullRequest,
-      comment: options.comment,
-    });
-    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.BITBUCKET_WEBHOOK_SECRET;
-  process.stderr.write(
-    `[agent-sdk] replaying ${ref.label} (${ref.dialect}; ${synthesized
-      .map(event => event.eventType)
-      .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-event-key": event.header,
-      "x-request-uuid": randomUUID(),
-    };
-    if (secret !== undefined && secret !== "") {
-      headers["x-hub-signature"] = signBitbucketWebhookBody(body, secret);
-    }
-    if (options.out !== undefined) {
-      const file = await writeReplayFixture(options.out, event);
-      process.stderr.write(`[agent-sdk] wrote ${file}\n`);
-    }
-    if (options.dryRun === true) {
-      report.push({ ...eventReport(event), payload: event.payload });
-      if (options.json !== true) {
-        process.stdout.write(
-          `--- ${event.header} ---\n${JSON.stringify(event.payload, null, 2)}\n`,
-        );
-      }
-      continue;
-    }
-    const deliveries = await deliverReplayEvent(body, headers, event.eventType, 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]   ${event.header} → ${summary}\n`);
-    }
-  }
-
-  if (options.json === true) {
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          pr: ref.label,
-          dialect: ref.dialect,
-          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>,
-  eventType: string,
-  targets: readonly ReplayTarget[],
-): Promise<ReplayDelivery[]> {
-  const recipients = targets.filter(
-    target => target.events.length === 0 || target.events.includes(eventType),
-  );
-  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 eventReport(event: SynthesizedBitbucketEvent): Record<string, unknown> {
-  return { event: event.eventType, header: event.header };
-}
-
-async function writeReplayFixture(
-  outDir: string,
-  event: SynthesizedBitbucketEvent,
-): Promise<string> {
-  const dir = resolvePath(outDir);
-  await mkdir(dir, { recursive: true });
-  const file = join(dir, `bitbucket-${event.header.replace(/[^\w.-]+/g, "-")}.json`);
-  await writeFile(file, `${JSON.stringify(event.payload, null, 2)}\n`);
-  return file;
-}
-
-async function cmdBitbucketEvents(options: BitbucketCliOptions): Promise<number> {
-  const dir = resolvePath(options.dir);
-  const channels = findBitbucketChannelTargets(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 Bitbucket 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 cmdBitbucketForward(options: BitbucketCliOptions): Promise<number> {
-  const dir = resolvePath(options.dir);
-  const channels = findBitbucketChannelTargets(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/bitbucket.ts");
-    process.stderr.write(
-      `no Bitbucket channel found. Author ${channelPath} with bitbucketChannel().\n`,
-    );
-    return 1;
-  }
-  const lines = [
-    "Bitbucket repository 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 Bitbucket → Repository settings → Webhooks, add one hook per channel",
-    "     (Cloud triggers use the keys below; Data Center shows the pr:* names):",
-  ];
-  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(`       Triggers: ${c.events.join(", ")}`);
-    lines.push("       Secret:   the value of BITBUCKET_WEBHOOK_SECRET (or webhookSecret)");
-  }
-  lines.push(
-    "",
-    "  3. Serve with the secret set so X-Hub-Signature is verified:",
-    `     BITBUCKET_WEBHOOK_SECRET=… ${CLI} serve --dir . --dev`,
-    "",
-    `Without a tunnel, \`${CLI} bitbucket replay <pr_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;
-}