@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/cli-github.ts

@@ -1,806 +0,0 @@
-/**
- * `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.
- *
- * @see https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing
- */
-
-import { execFile, spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve as resolvePath } from "node:path";
-import { promisify } from "node:util";
-import {
-  buildGitHubForwardArgs,
-  channelForwardUrl,
-  detectGitHubEnvTokenOverride,
-  findGitHubChannelTargets,
-  GITHUB_WEBHOOK_EXTENSION,
-  GITHUB_WEBHOOK_EXTENSION_PIN,
-  type GitHubChannelTarget,
-  type GitHubForwardTarget,
-  ghWebhookExtensionInstallArgs,
-  ghWebhookExtensionPinSatisfied,
-  githubEnvTokenHint,
-  parseGhWebhookExtensionInstalled,
-  parseGhWebhookExtensionVersion,
-  parseRepoFromRemoteUrl,
-  type ResolveGitHubForwardTargetsInput,
-  resolveGitHubForwardTargets,
-  targetLabel,
-  unionForwardEvents,
-} from "../channels/github/forward.js";
-import {
-  parseGitHubPrRef,
-  type ReplayCheck,
-  type ReplayPull,
-  type ReplayRepo,
-  type SynthesizedEvent,
-  selectReplayEvents,
-  signGitHubWebhookBody,
-  synthesizeGitHubEvent,
-} from "../channels/github/replay.js";
-import { resolveAgentMounts } from "./discovery.js";
-import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
-import { projectPath, resolveProjectRoot } from "./project-layout.js";
-import { startFanoutServer } from "./github-fanout.js";
-
-const execFileAsync = promisify(execFile);
-
-const DEFAULT_HOST = "127.0.0.1";
-const DEFAULT_PORT = 3000;
-
-export interface GithubCliOptions {
-  dir: string;
-  /** Select one agent mount by slug. */
-  slug?: string;
-  /** Select one channel id (when an agent has several GitHub channels). */
-  channel?: string;
-  /** Local server host (default 127.0.0.1). */
-  host?: string;
-  /** Local server port (default 3000). */
-  port?: number;
-  /** Explicit forward URL (skips URL derivation). */
-  url?: string;
-  /** Comma/space-separated event override. */
-  events?: string;
-  /** `owner/repo` to forward from. */
-  repo?: string;
-  /** Organization login (org-level hooks). */
-  org?: string;
-  /** Webhook signing secret (defaults to GITHUB_WEBHOOK_SECRET). */
-  secret?: string;
-  /** Install the `cli/gh-webhook` extension if missing. */
-  install?: boolean;
-  json?: boolean;
-  /** replay: PR URL or `owner/repo#N`. */
-  prUrl?: string;
-  /** replay: override the event action (e.g. opened, synchronize). */
-  action?: string;
-  /** replay: CI conclusion for check_run/check_suite/workflow_run. */
-  conclusion?: string;
-  /** replay: commit-status context. */
-  context?: string;
-  /** replay: comment body for issue_comment / review comment. */
-  comment?: string;
-  /** replay: print synthesized payloads instead of POSTing. */
-  dryRun?: boolean;
-  /** replay: write synthesized payloads as fixtures into this dir. */
-  out?: string;
-}
-
-const GITHUB_HELP = `${CLI} github — forward live GitHub webhooks to a local agent
-
-Usage:
-  ${CLI} github forward  [--dir .] [--slug S] [--channel C]
-                              [--repo owner/repo | --org ORG]
-                              [--events a,b,c] [--url URL]
-                              [--host 127.0.0.1] [--port 3000]
-                              [--secret S] [--install]
-  ${CLI} github replay   <pr_url|owner/repo#N> [--events a,b,c | *]
-                              [--action A] [--conclusion C] [--comment "…"]
-                              [--context CTX] [--dir .] [--slug S] [--channel C]
-                              [--host H] [--port N] [--url URL] [--secret S]
-                              [--dry-run] [--out DIR] [--json]
-  ${CLI} github events   [--dir .] [--host H] [--port N] [--json]
-  ${CLI} github doctor   [--install] [--json]
-
-Commands:
-  forward   Run \`gh webhook forward\` for the discovered githubChannel()s.
-            URL + events are derived per channel; the repo is inferred from the
-            git remote when --repo/--org are omitted. When several channels
-            match, one forwarder fans out to all of them (each delivery is
-            re-posted to the channels whose event set matches). Use --slug /
-            --channel to forward to just one.
-  replay    Synthesize webhook payloads from a PR you can *read* (no repo admin,
-            no relay) and POST them to the discovered channel(s). Reads the PR
-            via \`gh api\`, builds GitHub-shaped payloads for --events (default
-            pull_request; \`*\` = the channel's declared events), signs them with
-            --secret / GITHUB_WEBHOOK_SECRET, and fans out like forward.
-            --dry-run prints them; --out writes them as fixtures.
-  events    List discovered GitHub channels and the webhook events each accepts.
-  doctor    Check gh, auth, and the ${GITHUB_WEBHOOK_EXTENSION} extension.
-
-Prerequisites:
-  - gh CLI logged in (\`gh auth login\`).
-  - ${GITHUB_WEBHOOK_EXTENSION} extension (\`${CLI} github doctor --install\`).
-  - The agent already serving (\`${CLI} serve --dir . --dev\`).
-
-Notes:
-  - Set GITHUB_WEBHOOK_SECRET (or pass --secret) so the forwarded deliveries
-    are signed and each channel's signature check passes.
-  - Only one forwarder per repo/org at a time (GitHub limitation) — hence the
-    single-forwarder fan-out rather than one process per channel.
-
-See also: docs/guides/github.md, skills/github/SKILL.md
-`;
-
-export async function cmdGithub(
-  subcommand: string | undefined,
-  options: GithubCliOptions,
-): Promise<number> {
-  switch (subcommand) {
-    case undefined:
-    case "help":
-    case "--help":
-    case "-h":
-      process.stdout.write(GITHUB_HELP);
-      return subcommand === undefined ? 1 : 0;
-    case "forward":
-      return cmdGithubForward(options);
-    case "replay":
-      return cmdGithubReplay(options);
-    case "events":
-      return cmdGithubEvents(options);
-    case "doctor":
-      return cmdGithubDoctor(options);
-    default:
-      process.stderr.write(`Unknown github subcommand: ${subcommand}\n`);
-      process.stdout.write(GITHUB_HELP);
-      return 1;
-  }
-}
-
-async function cmdGithubForward(options: GithubCliOptions): Promise<number> {
-  const dir = resolvePath(options.dir);
-  const channels = findGitHubChannelTargets(await resolveAgentMounts(dir));
-
-  const resolveInput: ResolveGitHubForwardTargetsInput = {
-    targets: channels,
-    slug: options.slug,
-    channel: options.channel,
-    host: options.host ?? DEFAULT_HOST,
-    port: options.port ?? DEFAULT_PORT,
-    authoringPath: projectPath(resolveProjectRoot(dir), "channels/github.ts"),
-    url: options.url,
-    events: parseEventList(options.events),
-  };
-  const resolved = resolveGitHubForwardTargets(resolveInput);
-  if (!resolved.ok) {
-    process.stderr.write(`${resolved.error}\n`);
-    return 1;
-  }
-  const targets = resolved.targets;
-
-  const extension = await ensureWebhookExtension(options.install === true);
-  if (!extension.ok) {
-    process.stderr.write(`${extension.message}\n`);
-    return 1;
-  }
-
-  let repo = options.repo;
-  const org = options.org;
-  if (repo === undefined && org === undefined) {
-    repo = await inferRepo(dir);
-    if (repo === undefined) {
-      process.stderr.write(
-        "could not infer the repository — pass --repo owner/repo (or --org <org>)\n",
-      );
-      return 1;
-    }
-    process.stderr.write(`[agent-sdk] inferred --repo ${repo}\n`);
-  }
-
-  const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
-
-  // `gh webhook forward` targets a single URL, and GitHub allows only one
-  // forwarder per repo/org. To feed several channels at once, run one
-  // forwarder into a local proxy that re-delivers each raw (still-signed)
-  // delivery to every matching channel. A single channel needs no proxy.
-  const fanout = targets.length > 1;
-  const proxy = fanout ? await startFanoutServer(targets) : undefined;
-  const forwardUrl = proxy?.url ?? targets[0].url;
-  const events = fanout ? unionForwardEvents(targets) : targets[0].events;
-
-  const args = buildGitHubForwardArgs({
-    url: forwardUrl,
-    events,
-    repo,
-    org,
-    secret,
-  });
-
-  process.stderr.write(
-    `[agent-sdk] forwarding ${org !== undefined ? `org ${org}` : `repo ${repo}`} to ${targets.length} channel${targets.length === 1 ? "" : "s"}:\n`,
-  );
-  for (const target of targets) {
-    process.stderr.write(
-      `[agent-sdk]   → ${targetLabel(target)}  ${target.url}  (${target.events.join(", ")})\n`,
-    );
-  }
-  if (fanout) {
-    process.stderr.write(
-      `[agent-sdk] fan-out proxy on ${forwardUrl} (union events: ${events.join(", ")})\n`,
-    );
-  }
-  if (secret === undefined || secret === "") {
-    process.stderr.write(
-      "[agent-sdk] no signing secret — deliveries are unsigned. A `serve --dev` github channel accepts them; set GITHUB_WEBHOOK_SECRET on both sides to verify signatures (required for a non-dev target).\n",
-    );
-  }
-  const envToken = detectGitHubEnvTokenOverride();
-  if (envToken !== undefined) {
-    process.stderr.write(`[agent-sdk] warning: ${githubEnvTokenHint(envToken)}\n`);
-  }
-  process.stderr.write(`[agent-sdk] running: gh ${redact(args)}\n`);
-
-  try {
-    return await spawnGh(args);
-  } finally {
-    proxy?.close();
-  }
-}
-
-async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
-  const prUrl = options.prUrl;
-  if (prUrl === undefined || prUrl === "") {
-    process.stderr.write("github replay needs a PR URL or owner/repo#N\n");
-    return 1;
-  }
-  const ref = parseGitHubPrRef(prUrl);
-  if (ref === undefined) {
-    process.stderr.write(`could not parse PR ref: ${prUrl}\n`);
-    return 1;
-  }
-
-  // Which channel(s) to deliver to — reuse forward's discovery + URL builder,
-  // but keep each channel's *declared* events so `--events=*` can expand them.
-  const dir = resolvePath(options.dir);
-  const channels = findGitHubChannelTargets(await resolveAgentMounts(dir));
-  const host = options.host ?? DEFAULT_HOST;
-  const port = options.port ?? DEFAULT_PORT;
-  let candidates = 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 1;
-  }
-  if (candidates.length === 0 && options.url === undefined) {
-    const channelPath = projectPath(resolveProjectRoot(dir), "channels/github.ts");
-    process.stderr.write(
-      `no GitHub channel found. Author ${channelPath} with githubChannel(), or pass --url.\n`,
-    );
-    return 1;
-  }
-  const targets: GitHubForwardTarget[] =
-    options.url === undefined
-      ? 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,
-        }))
-      : [
-          {
-            slug: candidates[0]?.slug ?? "",
-            channelId: candidates[0]?.channelId ?? "",
-            url: options.url,
-            events: candidates[0]?.events ?? [],
-          },
-        ];
-
-  const requested = parseEventList(options.events);
-  const { events: eventsToReplay, unsupported } = selectReplayEvents(
-    requested,
-    unionForwardEvents(targets),
-  );
-  if (unsupported.length > 0) {
-    process.stderr.write(`[agent-sdk] cannot synthesize (skipped): ${unsupported.join(", ")}\n`);
-  }
-  if (eventsToReplay.length === 0) {
-    process.stderr.write("no synthesizable events selected\n");
-    return 1;
-  }
-
-  // Read the PR — pull access is enough (no admin, no relay).
-  let repo: ReplayRepo;
-  let pull: ReplayPull;
-  try {
-    repo = await ghApiJson<ReplayRepo>(`repos/${ref.owner}/${ref.repo}`);
-    pull = await ghApiJson<ReplayPull>(`repos/${ref.owner}/${ref.repo}/pulls/${ref.number}`);
-  } catch (error) {
-    process.stderr.write(
-      `failed to read ${ref.label} via gh api: ${
-        error instanceof Error ? error.message : String(error)
-      }\n`,
-    );
-    return 1;
-  }
-
-  // Best-effort: mirror a real CI check (app slug / conclusion) for CI events.
-  const wantsCi = eventsToReplay.some(event =>
-    ["check_run", "check_suite", "workflow_run", "status"].includes(event),
-  );
-  const check = wantsCi ? await fetchReplayCheck(ref, pull.head.sha) : undefined;
-
-  const synthesized: SynthesizedEvent[] = [];
-  for (const event of eventsToReplay) {
-    const result = synthesizeGitHubEvent({
-      event,
-      repo,
-      pull,
-      action: options.action,
-      conclusion: options.conclusion,
-      context: options.context,
-      comment: options.comment,
-      check,
-    });
-    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.GITHUB_WEBHOOK_SECRET;
-  process.stderr.write(
-    `[agent-sdk] replaying ${ref.label} (${synthesized
-      .map(s => s.eventName)
-      .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 = Buffer.from(JSON.stringify(event.payload));
-    const headers: Record<string, string> = {
-      "content-type": "application/json",
-      "x-github-event": event.eventName,
-      "x-github-delivery": randomUUID(),
-    };
-    if (secret !== undefined && secret !== "") {
-      headers["x-hub-signature-256"] = `sha256=${signGitHubWebhookBody({ secret, body })}`;
-    }
-
-    if (options.out !== undefined) {
-      const file = await writeReplayFixture(options.out, event);
-      process.stderr.write(`[agent-sdk] wrote ${file}\n`);
-    }
-
-    const label = eventLabel(event);
-    if (options.dryRun === true) {
-      report.push({ ...eventReport(event), payload: event.payload });
-      if (options.json !== true) {
-        process.stdout.write(`--- ${label} ---\n${JSON.stringify(event.payload, null, 2)}\n`);
-      }
-      continue;
-    }
-
-    const deliveries = await deliverReplayEvent(body, headers, event.eventName, targets);
-    if (deliveries.length === 0 || deliveries.some(delivery => !delivery.ok)) {
-      anyRejected = true;
-    }
-    report.push({ ...eventReport(event), deliveries });
-    if (options.json !== true) {
-      const summary =
-        deliveries
-          .map(
-            delivery =>
-              `${delivery.label} ${delivery.status || "ERR"}${delivery.ok ? "" : " (rejected)"}`,
-          )
-          .join(", ") || "(no matching channel)";
-      process.stderr.write(`[agent-sdk]   ${label} → ${summary}\n`);
-    }
-  }
-
-  if (options.json === true) {
-    process.stdout.write(
-      `${JSON.stringify(
-        { pr: ref.label, dryRun: options.dryRun === true, events: report },
-        null,
-        2,
-      )}\n`,
-    );
-  }
-  return anyRejected ? 1 : 0;
-}
-
-interface ReplayDelivery {
-  label: string;
-  /** HTTP status from the channel (0 when the request threw). */
-  status: number;
-  ok: boolean;
-  error?: string;
-}
-
-/** POST one synthesized event to every channel whose event set matches. */
-async function deliverReplayEvent(
-  body: Buffer,
-  headers: Record<string, string>,
-  eventName: string,
-  targets: readonly GitHubForwardTarget[],
-): Promise<ReplayDelivery[]> {
-  const recipients = targets.filter(
-    target => target.events.length === 0 || target.events.includes(eventName),
-  );
-  const payload = new Uint8Array(body);
-  // Bounded by the channel count (a handful) — see fanoutDelivery.
-  return Promise.all(
-    recipients.map(async target => {
-      try {
-        const response = await fetch(target.url, {
-          method: "POST",
-          headers,
-          body: payload,
-        });
-        return {
-          label: targetLabel(target),
-          status: response.status,
-          ok: response.ok,
-        };
-      } catch (error) {
-        return {
-          label: targetLabel(target),
-          status: 0,
-          ok: false,
-          error: error instanceof Error ? error.message : String(error),
-        };
-      }
-    }),
-  );
-}
-
-function eventLabel(event: SynthesizedEvent): string {
-  return event.action === undefined ? event.eventName : `${event.eventName}.${event.action}`;
-}
-
-function eventReport(event: SynthesizedEvent): Record<string, unknown> {
-  return { event: event.eventName, action: event.action };
-}
-
-/** GET `gh api <path>` and parse JSON (throws on non-zero exit). */
-async function ghApiJson<T>(path: string): Promise<T> {
-  const { stdout } = await execFileAsync("gh", [
-    "api",
-    path,
-    "-H",
-    "Accept: application/vnd.github+json",
-  ]);
-  return JSON.parse(stdout) as T;
-}
-
-async function fetchReplayCheck(
-  ref: { owner: string; repo: string },
-  sha: string,
-): Promise<ReplayCheck | undefined> {
-  try {
-    const data = await ghApiJson<{
-      check_runs?: Array<{
-        id: number;
-        name?: string;
-        conclusion?: string | null;
-        app?: { slug?: string; name?: string } | null;
-      }>;
-    }>(`repos/${ref.owner}/${ref.repo}/commits/${sha}/check-runs?per_page=100`);
-    const runs = data.check_runs ?? [];
-    const chosen = runs.find(run => run.conclusion === "failure") ?? runs[0];
-    if (chosen === undefined) {
-      return undefined;
-    }
-    return {
-      id: chosen.id,
-      name: chosen.name,
-      conclusion: chosen.conclusion,
-      app: chosen.app,
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-async function writeReplayFixture(outDir: string, event: SynthesizedEvent): Promise<string> {
-  const dir = resolvePath(outDir);
-  await mkdir(dir, { recursive: true });
-  const file = join(dir, `${eventLabel(event)}.json`);
-  await writeFile(file, `${JSON.stringify(event.payload, null, 2)}\n`);
-  return file;
-}
-
-async function cmdGithubEvents(options: GithubCliOptions): Promise<number> {
-  const dir = resolvePath(options.dir);
-  const targets = findGitHubChannelTargets(await resolveAgentMounts(dir));
-  const host = options.host ?? DEFAULT_HOST;
-  const port = options.port ?? DEFAULT_PORT;
-  const urlFor = (t: GitHubChannelTarget): string =>
-    channelForwardUrl({
-      host,
-      port,
-      slug: t.slug,
-      channelId: t.channelId,
-      routePath: t.routePath,
-    });
-
-  if (options.json) {
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          channels: targets.map(t => ({
-            slug: t.slug,
-            channelId: t.channelId,
-            url: urlFor(t),
-            events: t.events,
-          })),
-        },
-        null,
-        2,
-      )}\n`,
-    );
-    return 0;
-  }
-
-  if (targets.length === 0) {
-    const channelPath = projectPath(resolveProjectRoot(dir), "channels/github.ts");
-    process.stdout.write(`no GitHub channels found (author ${channelPath} with githubChannel())\n`);
-    return 0;
-  }
-  for (const t of targets) {
-    const label = t.slug === "" ? t.channelId : `${t.slug}/${t.channelId}`;
-    process.stdout.write(
-      `${label}\n  url:    ${urlFor(t)}\n  events: ${t.events.join(", ") || "none"}\n`,
-    );
-  }
-  return 0;
-}
-
-interface GithubDoctorCheck {
-  id: string;
-  ok: boolean;
-  message: string;
-  /** Non-fatal: surfaced as a warning, not counted toward `doctor: fail`. */
-  warn?: boolean;
-}
-
-async function cmdGithubDoctor(options: GithubCliOptions): Promise<number> {
-  const checks: GithubDoctorCheck[] = [];
-
-  const version = await tryExec({ command: "gh", args: ["--version"] });
-  if (version === undefined) {
-    checks.push({
-      id: "gh",
-      ok: false,
-      message: "gh CLI not found — install from https://cli.github.com",
-    });
-    return reportDoctor(checks, options.json);
-  }
-  checks.push({
-    id: "gh",
-    ok: true,
-    message: version.split("\n")[0]?.trim() ?? "gh present",
-  });
-
-  const auth = await tryExec({ command: "gh", args: ["auth", "status"] });
-  checks.push({
-    id: "auth",
-    ok: auth !== undefined,
-    message: auth !== undefined ? "gh auth status ok" : "not logged in — run `gh auth login`",
-  });
-
-  let extensionList = (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
-  let installed = parseGhWebhookExtensionInstalled(extensionList);
-  let pinOk = installed && ghWebhookExtensionPinSatisfied(extensionList);
-  if ((!installed || !pinOk) && options.install === true) {
-    const install = await tryExec({
-      command: "gh",
-      args: ghWebhookExtensionInstallArgs({ force: installed && !pinOk }),
-    });
-    if (install !== undefined) {
-      extensionList = (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
-      installed = parseGhWebhookExtensionInstalled(extensionList);
-      pinOk = installed && ghWebhookExtensionPinSatisfied(extensionList);
-    } else {
-      installed = false;
-      pinOk = false;
-    }
-    checks.push({
-      id: "install",
-      ok: installed && pinOk,
-      message:
-        installed && pinOk
-          ? `installed ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}`
-          : `failed to install ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}`,
-    });
-  }
-  checks.push({
-    id: "extension",
-    ok: installed && pinOk,
-    message:
-      installed && pinOk
-        ? `${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN} installed`
-        : !installed
-          ? `${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();
-  checks.push(
-    envToken === undefined
-      ? {
-          id: "env_token",
-          ok: true,
-          message: "no GITHUB_TOKEN/GH_TOKEN override (gh uses its own login)",
-        }
-      : {
-          id: "env_token",
-          ok: false,
-          warn: true,
-          message: githubEnvTokenHint(envToken),
-        },
-  );
-
-  return reportDoctor(checks, options.json);
-}
-
-function reportDoctor(checks: GithubDoctorCheck[], json: boolean | undefined): number {
-  // Warnings (e.g. an env-token override) are advisory and do not fail doctor.
-  const ok = checks.every(check => check.ok || check.warn === true);
-  if (json === true) {
-    process.stdout.write(`${JSON.stringify({ ok, checks }, null, 2)}\n`);
-  } else {
-    for (const check of checks) {
-      const marker = check.ok ? "ok" : check.warn === true ? "!!warn" : "!!";
-      process.stdout.write(`${marker}  ${check.id}: ${check.message}\n`);
-    }
-    process.stdout.write(ok ? "doctor: pass\n" : "doctor: fail\n");
-  }
-  return ok ? 0 : 1;
-}
-
-interface ExtensionCheck {
-  ok: boolean;
-  message: string;
-}
-
-async function ensureWebhookExtension(install: boolean): Promise<ExtensionCheck> {
-  if ((await tryExec({ command: "gh", args: ["--version"] })) === undefined) {
-    return {
-      ok: false,
-      message: "gh CLI not found — install from https://cli.github.com, then `gh auth login`",
-    };
-  }
-  const list = (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
-  const installed = parseGhWebhookExtensionInstalled(list);
-  const pinOk = installed && ghWebhookExtensionPinSatisfied(list);
-  if (installed && pinOk) {
-    return { ok: true, message: "" };
-  }
-  if (!install) {
-    return {
-      ok: false,
-      message: !installed
-        ? `${GITHUB_WEBHOOK_EXTENSION} not installed — run \`gh extension install ${GITHUB_WEBHOOK_EXTENSION} --pin ${GITHUB_WEBHOOK_EXTENSION_PIN}\` or re-run with --install`
-        : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(list) ?? "unknown"} (need ${GITHUB_WEBHOOK_EXTENSION_PIN}) — re-run with --install`,
-    };
-  }
-  process.stderr.write(
-    `[agent-sdk] installing ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}…\n`,
-  );
-  if (
-    (await tryExec({
-      command: "gh",
-      args: ghWebhookExtensionInstallArgs({ force: installed && !pinOk }),
-    })) === undefined
-  ) {
-    return {
-      ok: false,
-      message: `failed to install ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}`,
-    };
-  }
-  const listAfter = (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
-  const installedAfter = parseGhWebhookExtensionInstalled(listAfter);
-  const pinOkAfter = installedAfter && ghWebhookExtensionPinSatisfied(listAfter);
-  if (!installedAfter || !pinOkAfter) {
-    return {
-      ok: false,
-      message: !installedAfter
-        ? `${GITHUB_WEBHOOK_EXTENSION} missing after install`
-        : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(listAfter) ?? "unknown"} after install (need ${GITHUB_WEBHOOK_EXTENSION_PIN})`,
-    };
-  }
-  return { ok: true, message: "" };
-}
-
-async function inferRepo(dir: string): Promise<string | undefined> {
-  const viaGh = await tryExec({
-    command: "gh",
-    args: ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
-    cwd: dir,
-  });
-  const trimmed = viaGh?.trim();
-  if (trimmed !== undefined && trimmed !== "") {
-    return trimmed;
-  }
-  const remote = await tryExec({
-    command: "git",
-    args: ["-C", dir, "remote", "get-url", "origin"],
-  });
-  return remote === undefined ? undefined : parseRepoFromRemoteUrl(remote);
-}
-
-/** Run a command, returning stdout on success or undefined on any failure. */
-async function tryExec(options: {
-  command: string;
-  args: string[];
-  cwd?: string;
-}): Promise<string | undefined> {
-  try {
-    const { stdout } = await execFileAsync(options.command, options.args, {
-      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
-    });
-    return stdout;
-  } catch {
-    return undefined;
-  }
-}
-
-function spawnGh(args: string[]): Promise<number> {
-  return new Promise(resolve => {
-    const child = spawn("gh", args, { stdio: "inherit" });
-    const forward = (signal: NodeJS.Signals): void => {
-      if (!child.killed) {
-        child.kill(signal);
-      }
-    };
-    process.on("SIGINT", forward);
-    process.on("SIGTERM", forward);
-    child.on("error", error => {
-      process.stderr.write(`failed to run gh: ${error.message}\n`);
-      resolve(1);
-    });
-    child.on("exit", (code, signal) => {
-      resolve(code ?? (signal === null ? 0 : 130));
-    });
-  });
-}
-
-/** Split a comma/whitespace-separated list; undefined when empty/unset. */
-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;
-}
-
-/** Render the gh argv for logging with the signing secret masked. */
-function redact(args: string[]): string {
-  return args.map(arg => (arg.startsWith("--secret=") ? "--secret=***" : arg)).join(" ");
-}