@cursor/july 0.1.101 → 0.1.103

package/src/channels/bitbucket/replay.ts

@@ -0,0 +1,439 @@
+/**
+ * Synthesize Bitbucket webhook payloads from data you can *read* about a
+ * pull request, so `agent-sdk bitbucket replay` can exercise a
+ * `bitbucketChannel()` without admin access to the repository hook and
+ * without a tunnel.
+ *
+ * Payloads are shaped in the dialect of the pull request's host — Cloud
+ * (`pullrequest`, `repository.full_name`) or Data Center (`pullRequest`,
+ * `repository.project.key`, `eventKey`) — so the channel's dialect detection
+ * and the Data Center → Cloud event-key normalizer both run on the local
+ * loop exactly as they do for a real delivery.
+ */
+
+import type { BitbucketApiPullRequest } from "./api.js";
+import { normalizeBitbucketEventKey } from "./events.js";
+import type { BitbucketDialect, BitbucketRepositoryRef } from "./types.js";
+
+/** A parsed pull request reference. */
+export interface BitbucketPrRef {
+  dialect: BitbucketDialect;
+  /** `https://bitbucket.org` or the Data Center origin. */
+  origin: string;
+  repository: BitbucketRepositoryRef;
+  id: number;
+  /** Web URL of the pull request. */
+  url: string;
+  /** `workspace/repo#N` / `PROJECT/repo#N`. */
+  label: string;
+}
+
+/**
+ * Parse a Cloud PR URL (`https://bitbucket.org/<ws>/<repo>/pull-requests/N`),
+ * a Data Center PR URL (`https://<host>/projects/<KEY>/repos/<repo>/pull-requests/N`),
+ * or `workspace/repo#N` (Cloud). Returns undefined otherwise.
+ */
+export function parseBitbucketPrRef(raw: string): BitbucketPrRef | undefined {
+  const text = raw.trim();
+  const dc = text.match(
+    /^(https?:\/\/[^/]+)(?:\/.*?)?\/projects\/([^/]+)\/repos\/([^/]+)\/pull-requests\/(\d+)(?:[/?#].*)?$/i
+  );
+  if (dc !== null) {
+    return build(
+      "data-center",
+      dc[1] as string,
+      dc[2] as string,
+      dc[3] as string,
+      Number(dc[4])
+    );
+  }
+  const cloud = text.match(
+    /^(https?:\/\/[^/]+)\/([^/]+)\/([^/]+)\/pull-requests\/(\d+)(?:[/?#].*)?$/i
+  );
+  if (cloud !== null) {
+    return build(
+      "cloud",
+      cloud[1] as string,
+      cloud[2] as string,
+      cloud[3] as string,
+      Number(cloud[4])
+    );
+  }
+  const hash = text.match(/^([\w.-]+)\/([\w.-]+)#(\d+)$/);
+  if (hash !== null) {
+    return build(
+      "cloud",
+      "https://bitbucket.org",
+      hash[1] as string,
+      hash[2] as string,
+      Number(hash[3])
+    );
+  }
+  return undefined;
+}
+
+function build(
+  dialect: BitbucketDialect,
+  origin: string,
+  owner: string,
+  slug: string,
+  id: number
+): BitbucketPrRef {
+  const fullName = `${owner}/${slug}`;
+  const htmlUrl =
+    dialect === "cloud"
+      ? `${origin}/${fullName}`
+      : `${origin}/projects/${owner}/repos/${slug}`;
+  return {
+    dialect,
+    origin,
+    repository: { dialect, fullName, owner, slug, htmlUrl },
+    id,
+    url: `${htmlUrl}/pull-requests/${id}`,
+    label: `${fullName}#${id}`,
+  };
+}
+
+/** Cloud-vocabulary event keys replay knows how to synthesize. */
+export const BITBUCKET_SYNTHESIZABLE_EVENTS = [
+  "pullrequest:created",
+  "pullrequest:updated",
+  "pullrequest:comment_created",
+  "repo:push",
+] as const;
+
+export type BitbucketSynthesizableEvent =
+  (typeof BITBUCKET_SYNTHESIZABLE_EVENTS)[number];
+
+export function isBitbucketSynthesizableEvent(
+  event: string
+): event is BitbucketSynthesizableEvent {
+  return (BITBUCKET_SYNTHESIZABLE_EVENTS as readonly string[]).includes(event);
+}
+
+export interface SynthesizedBitbucketEvent {
+  /** Cloud-normalized event key (`pullrequest:created`). */
+  eventType: BitbucketSynthesizableEvent;
+  /** `X-Event-Key` header value: Cloud key, or the raw Data Center key. */
+  header: string;
+  payload: Record<string, unknown>;
+}
+
+/** Cloud key → the Data Center `X-Event-Key` that normalizes to it. */
+const DATA_CENTER_HEADER: Readonly<
+  Record<BitbucketSynthesizableEvent, string>
+> = {
+  "pullrequest:created": "pr:opened",
+  "pullrequest:updated": "pr:from_ref_updated",
+  "pullrequest:comment_created": "pr:comment:added",
+  "repo:push": "repo:refs_changed",
+};
+
+const ZERO_SHA = "0000000000000000000000000000000000000000";
+
+interface ReplayActor {
+  id: string;
+  username: string;
+  displayName: string;
+}
+
+const FALLBACK_ACTOR: ReplayActor = {
+  id: "agent-sdk-replay",
+  username: "agent-sdk-replay",
+  displayName: "agent-sdk replay",
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** PR author from the raw REST record (Cloud `author`, DC `author.user`). */
+function actorFromPullRequest(raw: unknown): ReplayActor {
+  const record = asRecord(raw);
+  const author = asRecord(record?.author);
+  const user = asRecord(author?.user) ?? author;
+  if (user === undefined) {
+    return FALLBACK_ACTOR;
+  }
+  const id =
+    str(user.uuid) ??
+    str(user.account_id) ??
+    (typeof user.id === "number" ? String(user.id) : undefined);
+  const username = str(user.nickname) ?? str(user.name) ?? str(user.slug);
+  const displayName = str(user.display_name) ?? str(user.displayName);
+  return {
+    id: id ?? FALLBACK_ACTOR.id,
+    username: username ?? FALLBACK_ACTOR.username,
+    displayName: displayName ?? username ?? FALLBACK_ACTOR.displayName,
+  };
+}
+
+function cloudActor(actor: ReplayActor): Record<string, unknown> {
+  return {
+    type: "user",
+    uuid: actor.id,
+    nickname: actor.username,
+    display_name: actor.displayName,
+  };
+}
+
+function dcActor(actor: ReplayActor): Record<string, unknown> {
+  const numeric = Number(actor.id);
+  return {
+    id: Number.isInteger(numeric) && numeric > 0 ? numeric : 1,
+    name: actor.username,
+    displayName: actor.displayName,
+    slug: actor.username,
+  };
+}
+
+function cloudRepository(
+  repository: BitbucketRepositoryRef
+): Record<string, unknown> {
+  return {
+    type: "repository",
+    full_name: repository.fullName,
+    name: repository.slug,
+    ...(repository.uuid === undefined ? {} : { uuid: repository.uuid }),
+    links: {
+      html: {
+        href:
+          repository.htmlUrl ?? `https://bitbucket.org/${repository.fullName}`,
+      },
+    },
+  };
+}
+
+function dcRepository(
+  repository: BitbucketRepositoryRef
+): Record<string, unknown> {
+  return {
+    slug: repository.slug,
+    ...(repository.id === undefined ? {} : { id: repository.id }),
+    name: repository.slug,
+    project: { key: repository.owner },
+    ...(repository.htmlUrl === undefined
+      ? {}
+      : { links: { self: [{ href: `${repository.htmlUrl}/browse` }] } }),
+  };
+}
+
+function cloudPullRequest(
+  pullRequest: BitbucketApiPullRequest,
+  actor: ReplayActor,
+  url: string
+): Record<string, unknown> {
+  return {
+    id: pullRequest.id,
+    title: pullRequest.title ?? "",
+    description: pullRequest.description ?? "",
+    state: pullRequest.state ?? "OPEN",
+    author: cloudActor(actor),
+    source: {
+      branch: { name: pullRequest.sourceBranch ?? "" },
+      commit: { hash: pullRequest.headSha ?? ZERO_SHA },
+    },
+    destination: {
+      branch: { name: pullRequest.targetBranch ?? "" },
+      commit: { hash: pullRequest.baseSha ?? ZERO_SHA },
+    },
+    links: { html: { href: pullRequest.htmlUrl ?? url } },
+  };
+}
+
+function dcPullRequest(
+  pullRequest: BitbucketApiPullRequest,
+  repository: BitbucketRepositoryRef,
+  actor: ReplayActor,
+  url: string
+): Record<string, unknown> {
+  const repo = dcRepository(repository);
+  return {
+    id: pullRequest.id,
+    title: pullRequest.title ?? "",
+    description: pullRequest.description ?? "",
+    state: pullRequest.state ?? "OPEN",
+    author: { user: dcActor(actor), role: "AUTHOR", approved: false },
+    fromRef: {
+      id: `refs/heads/${pullRequest.sourceBranch ?? ""}`,
+      displayId: pullRequest.sourceBranch ?? "",
+      latestCommit: pullRequest.headSha ?? ZERO_SHA,
+      repository: repo,
+    },
+    toRef: {
+      id: `refs/heads/${pullRequest.targetBranch ?? ""}`,
+      displayId: pullRequest.targetBranch ?? "",
+      latestCommit: pullRequest.baseSha ?? ZERO_SHA,
+      repository: repo,
+    },
+    links: { self: [{ href: pullRequest.htmlUrl ?? url }] },
+  };
+}
+
+/** Build one Bitbucket-shaped payload for `event` in the ref's dialect. */
+export function synthesizeBitbucketEvent(input: {
+  /** Cloud or Data Center event key; DC keys are normalized first. */
+  event: string;
+  ref: BitbucketPrRef;
+  pullRequest: BitbucketApiPullRequest;
+  /** comment body (default `@cursor please take a look`). */
+  comment?: string;
+}): SynthesizedBitbucketEvent | { error: string } {
+  const event = normalizeBitbucketEventKey(input.event);
+  if (!isBitbucketSynthesizableEvent(event)) {
+    return { error: `cannot synthesize ${input.event}` };
+  }
+  const { ref, pullRequest } = input;
+  const actor = actorFromPullRequest(pullRequest.raw);
+  const headSha = pullRequest.headSha ?? ZERO_SHA;
+  const baseSha = pullRequest.baseSha ?? ZERO_SHA;
+  const comment = input.comment ?? "@cursor please take a look";
+  const commentId = Date.now() % 1_000_000_000;
+
+  if (ref.dialect === "cloud") {
+    const base = {
+      repository: cloudRepository(ref.repository),
+      actor: cloudActor(actor),
+    };
+    const pullrequest = cloudPullRequest(pullRequest, actor, ref.url);
+    switch (event) {
+      case "pullrequest:created":
+      case "pullrequest:updated":
+        return {
+          eventType: event,
+          header: event,
+          payload: { ...base, pullrequest },
+        };
+      case "pullrequest:comment_created":
+        return {
+          eventType: event,
+          header: event,
+          payload: {
+            ...base,
+            pullrequest,
+            comment: {
+              id: commentId,
+              content: { raw: comment },
+              user: cloudActor(actor),
+              links: { html: { href: `${ref.url}#comment-${commentId}` } },
+            },
+          },
+        };
+      case "repo:push":
+        return {
+          eventType: event,
+          header: event,
+          payload: {
+            ...base,
+            push: {
+              changes: [
+                {
+                  new: {
+                    type: "branch",
+                    name: pullRequest.sourceBranch ?? "",
+                    target: { hash: headSha },
+                  },
+                  old: {
+                    type: "branch",
+                    name: pullRequest.sourceBranch ?? "",
+                    target: { hash: baseSha },
+                  },
+                },
+              ],
+            },
+          },
+        };
+    }
+  }
+
+  const header = DATA_CENTER_HEADER[event];
+  const base = {
+    eventKey: header,
+    date: new Date().toISOString(),
+    actor: dcActor(actor),
+  };
+  const dcPr = dcPullRequest(pullRequest, ref.repository, actor, ref.url);
+  switch (event) {
+    case "pullrequest:created":
+      return {
+        eventType: event,
+        header,
+        payload: { ...base, pullRequest: dcPr },
+      };
+    case "pullrequest:updated":
+      // `pr:from_ref_updated` carries the previous head; the default dispatch
+      // keys on it to tell a push from a title edit.
+      return {
+        eventType: event,
+        header,
+        payload: { ...base, pullRequest: dcPr, previousFromHash: baseSha },
+      };
+    case "pullrequest:comment_created":
+      return {
+        eventType: event,
+        header,
+        payload: {
+          ...base,
+          pullRequest: dcPr,
+          comment: { id: commentId, text: comment, author: dcActor(actor) },
+        },
+      };
+    case "repo:push":
+      return {
+        eventType: event,
+        header,
+        payload: {
+          ...base,
+          repository: dcRepository(ref.repository),
+          changes: [
+            {
+              ref: {
+                id: `refs/heads/${pullRequest.sourceBranch ?? ""}`,
+                displayId: pullRequest.sourceBranch ?? "",
+                type: "BRANCH",
+              },
+              refId: `refs/heads/${pullRequest.sourceBranch ?? ""}`,
+              fromHash: baseSha,
+              toHash: headSha,
+              type: "UPDATE",
+            },
+          ],
+        },
+      };
+  }
+}
+
+/**
+ * Choose events to replay: explicit list (either dialect's keys), `*` for
+ * every declared, else `pullrequest:created`.
+ */
+export function selectBitbucketReplayEvents(
+  requested: readonly string[] | undefined,
+  declared: readonly string[]
+): { events: BitbucketSynthesizableEvent[]; unsupported: string[] } {
+  const wanted =
+    requested === undefined
+      ? ["pullrequest:created"]
+      : requested.includes("*")
+        ? [...declared]
+        : [...requested];
+  const events: BitbucketSynthesizableEvent[] = [];
+  const unsupported: string[] = [];
+  for (const raw of new Set(wanted)) {
+    const event = normalizeBitbucketEventKey(raw);
+    if (isBitbucketSynthesizableEvent(event)) {
+      if (!events.includes(event)) {
+        events.push(event);
+      }
+    } else {
+      unsupported.push(raw);
+    }
+  }
+  return { events, unsupported };
+}

package/src/channels/bitbucket/state.ts

@@ -0,0 +1,59 @@
+/**
+ * Durable per-session Bitbucket channel state, persisted with the turn so
+ * channel stream-event handlers can rebuild a repo-bound handle without
+ * re-parsing the webhook.
+ */
+
+import type { BitbucketDialect } from "./types.js";
+
+export interface BitbucketChannelState {
+  dialect: BitbucketDialect | null;
+  /** `workspace/repo` (Cloud) or `PROJECT/repo` (Data Center), as delivered. */
+  repoFullName: string;
+  /** Cloud `repository.uuid` (braces included) when known. */
+  repoUuid: string | null;
+  pullRequestId: number | null;
+  /** Source-branch head at dispatch time, when known. */
+  headSha: string | null;
+  /** Comment id that woke the turn (comment events only). */
+  triggeringCommentId: number | null;
+  deliveryId: string | null;
+  /** Cloud-normalized event key. */
+  eventType: string | null;
+}
+
+export function emptyBitbucketChannelState(
+  overrides: Partial<BitbucketChannelState> = {}
+): BitbucketChannelState {
+  return {
+    dialect: null,
+    repoFullName: "",
+    repoUuid: null,
+    pullRequestId: null,
+    headSha: null,
+    triggeringCommentId: null,
+    deliveryId: null,
+    eventType: null,
+    ...overrides,
+  };
+}
+
+export function bitbucketChannelStateForEvent(input: {
+  repository: { dialect: BitbucketDialect; fullName: string; uuid?: string };
+  pullRequestId?: number;
+  headSha?: string;
+  deliveryId?: string;
+  eventType: string;
+  triggeringCommentId?: number;
+}): BitbucketChannelState {
+  return emptyBitbucketChannelState({
+    dialect: input.repository.dialect,
+    repoFullName: input.repository.fullName,
+    repoUuid: input.repository.uuid ?? null,
+    pullRequestId: input.pullRequestId ?? null,
+    headSha: input.headSha ?? null,
+    triggeringCommentId: input.triggeringCommentId ?? null,
+    deliveryId: input.deliveryId ?? null,
+    eventType: input.eventType,
+  });
+}