@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/github/forward.ts

@@ -1,359 +0,0 @@
-/**
- * Planning helpers for `agent-sdk github forward` — turning discovered
- * GitHub channels into a `gh webhook forward` invocation.
- *
- * These are pure functions (no process spawning) so they are unit-testable;
- * the CLI in `internal/cli-github.ts` runs `gh` around them.
- *
- * @see https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing
- */
-
-import { CLI_COMMAND_NAME as CLI } from "../../internal/distribution.js";
-import type { AgentProject } from "../../types.js";
-import { GITHUB_CHANNEL_KIND } from "./events.js";
-
-/** GitHub CLI extension that provides `gh webhook forward`. */
-export const GITHUB_WEBHOOK_EXTENSION = "cli/gh-webhook";
-
-/**
- * Pinned release for {@link GITHUB_WEBHOOK_EXTENSION}. Passed to
- * `gh extension install --pin` so auto-install does not float to arbitrary tags.
- *
- * @see https://github.com/cli/gh-webhook/releases
- */
-export const GITHUB_WEBHOOK_EXTENSION_PIN = "v0.2.0";
-
-/** `gh` argv to install the webhook extension at the pinned release. */
-export function ghWebhookExtensionInstallArgs(options?: { force?: boolean }): string[] {
-  const args = [
-    "extension",
-    "install",
-    GITHUB_WEBHOOK_EXTENSION,
-    "--pin",
-    GITHUB_WEBHOOK_EXTENSION_PIN,
-  ];
-  if (options?.force === true) {
-    args.push("--force");
-  }
-  return args;
-}
-
-/** One discovered GitHub webhook channel on a served agent. */
-export interface GitHubChannelTarget {
-  /** Agent mount slug (`""` for a single-agent server). */
-  slug: string;
-  /** Channel id (filename under `agent/channels/`). */
-  channelId: string;
-  /** Route path under the channel (default `/`). */
-  routePath: string;
-  /** Webhook events this channel is wired to dispatch on. */
-  events: string[];
-}
-
-/** Minimal mount shape shared by `serve` / `resolveAgentMounts`. */
-export interface AgentMountLike {
-  slug: string;
-  project: AgentProject;
-}
-
-/**
- * Collect the GitHub webhook channels across every mounted agent, reading the
- * `meta` a {@link githubChannel} publishes.
- */
-export function findGitHubChannelTargets(
-  mounts: ReadonlyArray<AgentMountLike>,
-): GitHubChannelTarget[] {
-  const targets: GitHubChannelTarget[] = [];
-  for (const { slug, project } of mounts) {
-    for (const channel of project.channels) {
-      const meta = channel.definition.meta;
-      if (meta?.kind !== GITHUB_CHANNEL_KIND) {
-        continue;
-      }
-      const postRoute = (channel.definition.routes ?? []).find(route => route.method === "POST");
-      targets.push({
-        slug,
-        channelId: channel.id,
-        routePath: postRoute?.path ?? "/",
-        events: [...(meta.githubWebhookEvents ?? [])],
-      });
-    }
-  }
-  return targets;
-}
-
-/** Absolute forward URL for a channel target on a local server. */
-export function channelForwardUrl(input: {
-  host: string;
-  port: number;
-  slug: string;
-  channelId: string;
-  routePath: string;
-}): string {
-  const slugPrefix = input.slug === "" ? "" : `/${input.slug}`;
-  const suffix = input.routePath === "/" ? "" : input.routePath;
-  return `http://${input.host}:${input.port}${slugPrefix}/v1/channels/${input.channelId}${suffix}`;
-}
-
-/** A resolved channel to forward deliveries to. */
-export interface GitHubForwardTarget {
-  slug: string;
-  channelId: string;
-  url: string;
-  events: string[];
-}
-
-export interface ResolveGitHubForwardTargetsInput {
-  targets: ReadonlyArray<GitHubChannelTarget>;
-  /** Restrict to one agent mount. */
-  slug?: string;
-  /** Restrict to one channel id. */
-  channel?: string;
-  host: string;
-  port: number;
-  /** Project-relative path where the missing channel should be authored. */
-  authoringPath?: string;
-  /**
-   * Explicit forward URL. Only valid when the selection resolves to a single
-   * channel; skips URL derivation.
-   */
-  url?: string;
-  /** Explicit event list; overrides every selected channel's declared events. */
-  events?: readonly string[];
-}
-
-export type ResolveGitHubForwardTargetsResult =
-  | { ok: true; targets: GitHubForwardTarget[] }
-  | { ok: false; error: string };
-
-/**
- * Resolve every channel a forward should feed, honoring `--slug` / `--channel`
- * selection and `--url` / `--events` overrides. Returns one target for a single
- * match (or an explicit `--url`) and many when several channels match — the CLI
- * fans a single `gh webhook forward` out to all of them.
- */
-export function resolveGitHubForwardTargets(
-  input: ResolveGitHubForwardTargetsInput,
-): ResolveGitHubForwardTargetsResult {
-  let candidates = [...input.targets];
-  if (input.slug !== undefined) {
-    candidates = candidates.filter(t => t.slug === input.slug);
-  }
-  if (input.channel !== undefined) {
-    candidates = candidates.filter(t => t.channelId === input.channel);
-  }
-
-  const overrideEvents = input.events === undefined ? undefined : dedupeEvents(input.events);
-
-  if (input.url !== undefined) {
-    if (candidates.length > 1) {
-      return {
-        ok: false,
-        error: `--url targets a single channel, but the selection matched several — narrow with --slug/--channel:\n${describeTargets(candidates)}`,
-      };
-    }
-    const only = candidates.length === 1 ? candidates[0] : undefined;
-    const events = overrideEvents ?? only?.events;
-    if (events === undefined || events.length === 0) {
-      return {
-        ok: false,
-        error: "pass --events with --url (no single GitHub channel matched to derive them)",
-      };
-    }
-    return {
-      ok: true,
-      targets: [
-        {
-          slug: only?.slug ?? input.slug ?? "",
-          channelId: only?.channelId ?? input.channel ?? "",
-          url: input.url,
-          events,
-        },
-      ],
-    };
-  }
-
-  if (candidates.length === 0) {
-    if (input.targets.length === 0) {
-      return {
-        ok: false,
-        error: `no GitHub channel found. Author ${input.authoringPath ?? "bot/channels/github.ts"} with githubChannel(), or pass --url and --events.`,
-      };
-    }
-    return {
-      ok: false,
-      error: `no GitHub channel matched the given selection.\n${describeTargets(input.targets)}`,
-    };
-  }
-
-  const resolved = candidates
-    .map(target => ({
-      slug: target.slug,
-      channelId: target.channelId,
-      url: channelForwardUrl({
-        host: input.host,
-        port: input.port,
-        slug: target.slug,
-        channelId: target.channelId,
-        routePath: target.routePath,
-      }),
-      events: overrideEvents ?? target.events,
-    }))
-    .filter(target => target.events.length > 0);
-
-  if (resolved.length === 0) {
-    return {
-      ok: false,
-      error:
-        "the selected GitHub channel(s) declare no webhook events; pass --events or set webhookEvents on githubChannel().",
-    };
-  }
-  return { ok: true, targets: resolved };
-}
-
-/** Union of the webhook events across every forward target (deduped). */
-export function unionForwardEvents(targets: ReadonlyArray<GitHubForwardTarget>): string[] {
-  return dedupeEvents(targets.flatMap(target => target.events));
-}
-
-export interface GitHubForwardArgsInput {
-  url: string;
-  events: readonly string[];
-  /** `owner/repo`; mutually exclusive with {@link org}. */
-  repo?: string;
-  /** Organization login for org-level hooks. */
-  org?: string;
-  /** Webhook signing secret so `X-Hub-Signature-256` verifies. */
-  secret?: string;
-  /** Extra args appended verbatim (advanced passthrough). */
-  extraArgs?: readonly string[];
-}
-
-/**
- * Build the argv for `gh <argv>` that runs `gh webhook forward` with the
- * planned URL, events, repo/org, and (optional) signing secret.
- */
-export function buildGitHubForwardArgs(input: GitHubForwardArgsInput): string[] {
-  const args = [
-    "webhook",
-    "forward",
-    `--url=${input.url}`,
-    `--events=${dedupeEvents(input.events).join(",")}`,
-  ];
-  if (input.repo !== undefined && input.repo !== "") {
-    args.push(`--repo=${input.repo}`);
-  }
-  if (input.org !== undefined && input.org !== "") {
-    args.push(`--org=${input.org}`);
-  }
-  if (input.secret !== undefined && input.secret !== "") {
-    args.push(`--secret=${input.secret}`);
-  }
-  if (input.extraArgs !== undefined) {
-    args.push(...input.extraArgs);
-  }
-  return args;
-}
-
-/** True when `gh extension list` output includes the webhook extension. */
-export function parseGhWebhookExtensionInstalled(listOutput: string): boolean {
-  return parseGhWebhookExtensionVersion(listOutput) !== undefined;
-}
-
-/** Version column from `gh extension list` for the webhook extension, if present. */
-export function parseGhWebhookExtensionVersion(listOutput: string): string | undefined {
-  for (const line of listOutput.split("\n")) {
-    if (!line.includes("gh-webhook")) {
-      continue;
-    }
-    const parts = line.split("\t");
-    const repo = parts[1]?.trim() ?? "";
-    if (!repo.includes("gh-webhook")) {
-      continue;
-    }
-    const version = parts[2]?.trim();
-    return version === undefined || version === "" ? undefined : version;
-  }
-  return undefined;
-}
-
-/** Whether the installed webhook extension matches {@link GITHUB_WEBHOOK_EXTENSION_PIN}. */
-export function ghWebhookExtensionPinSatisfied(listOutput: string): boolean {
-  const version = parseGhWebhookExtensionVersion(listOutput);
-  return version === GITHUB_WEBHOOK_EXTENSION_PIN;
-}
-
-/**
- * `gh webhook forward` authenticates its relay session
- * (`webhook-forwarder.github.com`) with the GitHub CLI's *own* OAuth login. A
- * `GITHUB_TOKEN` / `GH_TOKEN` env override is used for REST calls (so hook
- * creation succeeds) but is rejected by the relay — every delivery then fails
- * with HTTP 401. Detect such an override so the CLI can warn.
- *
- * Returns the offending env var name, or undefined when none is set.
- */
-export function detectGitHubEnvTokenOverride(
-  env: Record<string, string | undefined> = process.env,
-): string | undefined {
-  if (env.GITHUB_TOKEN !== undefined && env.GITHUB_TOKEN !== "") {
-    return "GITHUB_TOKEN";
-  }
-  if (env.GH_TOKEN !== undefined && env.GH_TOKEN !== "") {
-    return "GH_TOKEN";
-  }
-  return undefined;
-}
-
-/** Guidance shown when {@link detectGitHubEnvTokenOverride} finds an override. */
-export function githubEnvTokenHint(varName: string): string {
-  return `${varName} is set — gh webhook forward authenticates its relay with the GitHub CLI's own login, so an env token usually causes HTTP 401. Blank it for the command (e.g. \`GITHUB_TOKEN= GH_TOKEN= ${CLI} github forward …\`) or \`unset GITHUB_TOKEN GH_TOKEN\`.`;
-}
-
-/**
- * Extract `owner/repo` from a git remote URL (https, `git@`, or `ssh://`).
- * Returns undefined for unrecognized shapes.
- */
-export function parseRepoFromRemoteUrl(remote: string): string | undefined {
-  let url = remote.trim();
-  if (url === "") {
-    return undefined;
-  }
-  if (url.startsWith("git@")) {
-    url = `https://${url.slice("git@".length).replace(":", "/")}`;
-  } else if (url.startsWith("ssh://git@")) {
-    url = `https://${url.slice("ssh://git@".length)}`;
-  } else if (!/^https?:\/\//i.test(url)) {
-    return undefined;
-  }
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return undefined;
-  }
-  const segments = parsed.pathname
-    .replace(/^\/+/, "")
-    .replace(/\.git$/i, "")
-    .replace(/\/+$/, "")
-    .split("/");
-  const [owner, repo] = segments;
-  if (owner === undefined || owner === "" || repo === undefined || repo === "") {
-    return undefined;
-  }
-  return `${owner}/${repo}`;
-}
-
-/** `slug/channelId`, or just `channelId` for a single-agent (unslugged) mount. */
-export function targetLabel(target: { slug: string; channelId: string }): string {
-  return target.slug === "" ? target.channelId : `${target.slug}/${target.channelId}`;
-}
-
-function dedupeEvents(events: readonly string[]): string[] {
-  return [...new Set(events.map(event => event.trim()).filter(Boolean))];
-}
-
-function describeTargets(targets: ReadonlyArray<GitHubChannelTarget>): string {
-  return targets
-    .map(t => `  - ${targetLabel(t)} (events: ${t.events.join(", ") || "none"})`)
-    .join("\n");
-}