@cursor/july 0.1.102 → 0.1.103

package/src/internal/cli-bitbucket.ts

@@ -0,0 +1,477 @@
+/**
+ * `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";
+
+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) {
+    process.stderr.write(
+      "no Bitbucket channel found. Author agent/channels/bitbucket.ts 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) {
+    process.stderr.write(
+      "no Bitbucket channel found. Author agent/channels/bitbucket.ts 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;
+}

package/src/internal/cli-convert-automation.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-serve convert-automation <url>` — export a Cursor Automation into
+ * `agent-sdk convert-automation <url>` — export a Cursor Automation into
  * an agentsdk project.
  *
  * Fetches the automation's workflow from the backend export endpoint
@@ -17,13 +17,13 @@
 
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import {
-  type ConvertedMcpConnection,
-  type ConvertWorkflowResult,
-  convertWorkflow,
-  type WorkflowJson,
-} from "./convert-automation/index.js";
+import { convertWorkflow } from "./convert-automation/convert-workflow.js";
 import { slugify } from "./convert-automation/slug.js";
+import type {
+  ConvertedMcpConnection,
+  ConvertWorkflowResult,
+  WorkflowJson,
+} from "./convert-automation/types.js";
 import {
   cursorExternalApiUrl,
   resolveApiKey,

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