@cursor/july 0.1.1

package/src/channels/github/forward.ts

@@ -0,0 +1,381 @@
+/**
+ * Planning helpers for `agent-serve 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 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;
+  /**
+   * 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 agent/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= agent-serve 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");
+}