@cursor/july 0.1.20 → 0.1.21

package/src/channels/github/cursor-account.test.ts

@@ -0,0 +1,204 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createGitHubOctokit } from "./api.js";
+import { resolveCredentialValue } from "./auth.js";
+import {
+  getGithubCursorAccountRuntime,
+  resolveCursorGithubPermissions,
+  resolveCursorGithubProxyUrl,
+} from "./cursor-account.js";
+import { getGitHubChannelOptions, githubChannel } from "./github-channel.js";
+
+describe("githubChannel({ cursorAccount })", () => {
+  it("binds outbound API auth without rewriting authored cursorAccount options", async () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["Acme/Widgets"], permissions: "read" },
+    });
+    const runtime = getGithubCursorAccountRuntime(definition);
+
+    expect(runtime?.options.cursorAccount).toEqual({
+      repos: ["Acme/Widgets"],
+      permissions: "read",
+    });
+    expect(runtime?.scope).toEqual({
+      owner: "acme",
+      repos: ["acme/widgets"],
+      permissions: "read",
+    });
+    expect(() => runtime?.credentials.getToken()).toThrow(/has not been bound/);
+    runtime?.credentials.bind(async () => "ghs_cursor_account");
+    await expect(
+      resolveCredentialValue(
+        getGitHubChannelOptions(definition)?.credentials?.token
+      )
+    ).resolves.toBe("ghs_cursor_account");
+  });
+
+  it("defaults permissions to pr-write on the private scope", () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["acme/widgets"] },
+    });
+    expect(getGithubCursorAccountRuntime(definition)?.scope).toEqual({
+      owner: "acme",
+      repos: ["acme/widgets"],
+      permissions: "pr-write",
+    });
+  });
+
+  it("allows a webhook secret but rejects separate outbound credentials", () => {
+    expect(() =>
+      githubChannel({
+        cursorAccount: true,
+        credentials: { webhookSecret: "signing-secret" },
+      })
+    ).not.toThrow();
+    expect(() =>
+      githubChannel({
+        cursorAccount: true,
+        credentials: { token: "ghp_dedicated" },
+      })
+    ).toThrow(/cannot be combined/);
+    expect(() =>
+      githubChannel({
+        cursorAccount: true,
+        credentials: { appId: 1, privateKey: "pem" },
+      })
+    ).toThrow(/cannot be combined/);
+  });
+
+  it("rejects an empty inline repository scope", () => {
+    expect(() => githubChannel({ cursorAccount: { repos: [] } })).toThrow(
+      /require at least one repository/
+    );
+  });
+
+  it.each([
+    [["acme/widgets", "other/tools"], /must share one owner/],
+    [["https://github.com/acme/widgets"], /expected owner\/repo/],
+    [
+      Array.from({ length: 21 }, (_, index) => `acme/repo-${index}`),
+      /at most 20 repositories/,
+    ],
+  ])("rejects an unsupported repository scope", (repos, error) => {
+    expect(() => githubChannel({ cursorAccount: { repos } })).toThrow(error);
+  });
+
+  it("treats cursorAccount false as disabled", () => {
+    expect(
+      getGithubCursorAccountRuntime(githubChannel({ cursorAccount: false }))
+    ).toBeUndefined();
+  });
+
+  it("accepts contents-write permissions on the private scope", () => {
+    const definition = githubChannel({
+      cursorAccount: {
+        repos: ["acme/widgets"],
+        permissions: "contents-write",
+      },
+    });
+    expect(getGithubCursorAccountRuntime(definition)?.scope?.permissions).toBe(
+      "contents-write"
+    );
+  });
+});
+
+describe("resolveCursorGithubPermissions", () => {
+  it("escalates to the most privileged requested tier", () => {
+    expect(resolveCursorGithubPermissions(["read", "pr-write"])).toBe(
+      "pr-write"
+    );
+    expect(
+      resolveCursorGithubPermissions(["read", "contents-write", "pr-write"])
+    ).toBe("contents-write");
+  });
+});
+
+describe("cursor-account GitHub proxy mode", () => {
+  afterEach(() => {
+    delete process.env.AGENT_SERVE_GITHUB_PROXY_URL;
+  });
+
+  function captureFetch(): {
+    fetchImpl: typeof fetch;
+    requests: { url: string; headers: Headers }[];
+  } {
+    const requests: { url: string; headers: Headers }[] = [];
+    const fetchImpl: typeof fetch = async (input, init) => {
+      requests.push({
+        url: input instanceof Request ? input.url : String(input),
+        headers:
+          input instanceof Request ? input.headers : new Headers(init?.headers),
+      });
+      return Response.json({ id: 1 });
+    };
+    return { fetchImpl, requests };
+  }
+
+  it("resolves the proxy URL from the backend base URL or env override", () => {
+    expect(resolveCursorGithubProxyUrl("https://api.cursor.com")).toBe(
+      "https://api.cursor.com/v0/github-proxy"
+    );
+    process.env.AGENT_SERVE_GITHUB_PROXY_URL =
+      "https://backend.local:8000/v0/github-proxy/";
+    expect(resolveCursorGithubProxyUrl("https://api.cursor.com")).toBe(
+      "https://backend.local:8000/v0/github-proxy"
+    );
+  });
+
+  it("routes channel Octokit calls to the bound proxy with scope headers", async () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["acme/widgets"], permissions: "pr-write" },
+    });
+    const runtime = getGithubCursorAccountRuntime(definition);
+    runtime?.credentials.bind(async () => "crsr_api_key");
+    runtime?.credentials.bindProxyTransport({
+      apiBaseUrl: "https://api.cursor.com/v0/github-proxy",
+      headers: {
+        "x-cursor-github-repos": "acme/widgets",
+        "x-cursor-github-permissions": "pr-write",
+      },
+    });
+
+    const { fetchImpl, requests } = captureFetch();
+    const octokit = await createGitHubOctokit({
+      api: { fetch: fetchImpl },
+      credentials: getGitHubChannelOptions(definition)?.credentials,
+    });
+    await octokit.request("GET /repos/{owner}/{repo}", {
+      owner: "acme",
+      repo: "widgets",
+    });
+
+    expect(requests).toHaveLength(1);
+    const { url, headers } = requests[0]!;
+    expect(url).toBe(
+      "https://api.cursor.com/v0/github-proxy/repos/acme/widgets"
+    );
+    expect(headers.get("authorization")).toBe("Bearer crsr_api_key");
+    expect(headers.get("x-cursor-github-repos")).toBe("acme/widgets");
+    expect(headers.get("x-cursor-github-permissions")).toBe("pr-write");
+  });
+
+  it("keeps raw-token mode when no proxy transport is bound", async () => {
+    const definition = githubChannel({
+      cursorAccount: { repos: ["acme/widgets"] },
+    });
+    getGithubCursorAccountRuntime(definition)?.credentials.bind(
+      async () => "ghs_raw"
+    );
+
+    const { fetchImpl, requests } = captureFetch();
+    const octokit = await createGitHubOctokit({
+      api: { fetch: fetchImpl },
+      credentials: getGitHubChannelOptions(definition)?.credentials,
+    });
+    await octokit.request("GET /repos/{owner}/{repo}", {
+      owner: "acme",
+      repo: "widgets",
+    });
+
+    const { url, headers } = requests[0]!;
+    expect(url).toBe("https://api.github.com/repos/acme/widgets");
+    expect(headers.get("authorization")).toBe("Bearer ghs_raw");
+    expect(headers.get("x-cursor-github-repos")).toBeNull();
+  });
+});

package/src/channels/github/forward.test.ts

@@ -0,0 +1,457 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { setDevMode } from "../../internal/dev-mode.js";
+import type { AgentProject, DiscoveredChannel } from "../../types.js";
+import { deriveGitHubWebhookEvents, GITHUB_CHANNEL_KIND } from "./events.js";
+import {
+  type AgentMountLike,
+  buildGitHubForwardArgs,
+  channelForwardUrl,
+  detectGitHubEnvTokenOverride,
+  findGitHubChannelTargets,
+  GITHUB_WEBHOOK_EXTENSION_PIN,
+  ghWebhookExtensionInstallArgs,
+  ghWebhookExtensionPinSatisfied,
+  parseGhWebhookExtensionInstalled,
+  parseGhWebhookExtensionVersion,
+  parseRepoFromRemoteUrl,
+  resolveGitHubForwardTargets,
+  unionForwardEvents,
+} from "./forward.js";
+import { githubChannel } from "./github-channel.js";
+
+describe("deriveGitHubWebhookEvents", () => {
+  it("returns the base set for a hookless channel", () => {
+    expect(deriveGitHubWebhookEvents({})).toEqual([
+      "pull_request",
+      "issue_comment",
+      "pull_request_review_comment",
+    ]);
+  });
+
+  it("adds an event per declared typed hook", () => {
+    const events = deriveGitHubWebhookEvents({
+      onCheckSuite: () => null,
+      onStatus: () => null,
+    });
+    expect(events).toContain("check_suite");
+    expect(events).toContain("status");
+    expect(events).not.toContain("check_run");
+  });
+
+  it("adds the review catch-all events when onEvent is declared", () => {
+    const events = deriveGitHubWebhookEvents({ onEvent: () => null });
+    expect(events).toContain("pull_request_review");
+    expect(events).toContain("pull_request_review_thread");
+  });
+
+  it("treats webhookEvents as authoritative (deduped)", () => {
+    expect(
+      deriveGitHubWebhookEvents({
+        webhookEvents: ["pull_request", "pull_request", " status "],
+        onCheckRun: () => null,
+      })
+    ).toEqual(["pull_request", "status"]);
+  });
+});
+
+describe("githubChannel meta", () => {
+  it("publishes the github kind and derived events", () => {
+    const channel = githubChannel({ onCheckRun: () => null });
+    expect(channel.meta?.kind).toBe(GITHUB_CHANNEL_KIND);
+    expect(channel.meta?.githubWebhookEvents).toContain("check_run");
+  });
+
+  it("honors an explicit webhookEvents pin", () => {
+    const channel = githubChannel({ webhookEvents: ["pull_request"] });
+    expect(channel.meta?.githubWebhookEvents).toEqual(["pull_request"]);
+  });
+});
+
+describe("githubChannel dev auth default", () => {
+  const savedWebhookSecret = process.env.GITHUB_WEBHOOK_SECRET;
+  beforeEach(() => {
+    delete process.env.GITHUB_WEBHOOK_SECRET;
+  });
+  afterEach(() => {
+    setDevMode(false);
+    if (savedWebhookSecret === undefined) {
+      delete process.env.GITHUB_WEBHOOK_SECRET;
+    } else {
+      process.env.GITHUB_WEBHOOK_SECRET = savedWebhookSecret;
+    }
+  });
+  const forwarded = new Request("http://example.com/hook");
+  const nonLoopback = { requestIp: "203.0.113.4" };
+  const loopback = { requestIp: "127.0.0.1" };
+
+  it("admits loopback deliveries in dev without a secret", async () => {
+    setDevMode(true);
+    const policy = githubChannel().auth?.[0];
+    expect(
+      await policy?.(new Request("http://127.0.0.1/hook"), loopback)
+    ).not.toBeNull();
+  });
+
+  it("admits loopback deliveries carrying gh forwarding headers in dev", async () => {
+    // `gh webhook forward` relays GitHub's edge X-Forwarded-For / X-Real-Ip;
+    // dev auth must admit them from a loopback peer (localDev/localDevStrict
+    // would reject on those headers and break forwarding).
+    setDevMode(true);
+    const policy = githubChannel().auth?.[0];
+    const ghForwarded = new Request("http://127.0.0.1/hook", {
+      headers: {
+        "x-github-event": "pull_request",
+        "x-forwarded-for": "140.82.115.1",
+        "x-real-ip": "140.82.115.1",
+      },
+    });
+    expect(await policy?.(ghForwarded, loopback)).not.toBeNull();
+  });
+
+  it("rejects loopback tunneled traffic with forwarding headers but no GitHub delivery headers in dev", async () => {
+    setDevMode(true);
+    const policy = githubChannel().auth?.[0];
+    const tunneled = new Request("http://127.0.0.1/hook", {
+      headers: {
+        "x-forwarded-for": "203.0.113.4",
+        "x-real-ip": "203.0.113.4",
+      },
+    });
+    expect(await policy?.(tunneled, loopback)).toBeNull();
+  });
+
+  it("rejects non-loopback deliveries in dev without a secret", async () => {
+    setDevMode(true);
+    const policy = githubChannel().auth?.[0];
+    expect(await policy?.(forwarded, nonLoopback)).toBeNull();
+  });
+
+  it("stays loopback-strict outside dev without a secret", async () => {
+    setDevMode(false);
+    const policy = githubChannel().auth?.[0];
+    expect(await policy?.(forwarded, nonLoopback)).toBeNull();
+  });
+
+  it("re-evaluates isDevMode per request on a cached channel definition", async () => {
+    // Channel modules call githubChannel() once at import; flipping --dev
+    // later must still change auth behavior for the same policy closure.
+    setDevMode(false);
+    const policy = githubChannel().auth?.[0];
+    const ghForwarded = new Request("http://127.0.0.1/hook", {
+      headers: {
+        "x-github-event": "pull_request",
+        "x-forwarded-for": "140.82.115.1",
+        "x-real-ip": "140.82.115.1",
+      },
+    });
+    // Outside --dev, localDevStrict rejects proxy-forwarded headers.
+    expect(await policy?.(ghForwarded, loopback)).toBeNull();
+    setDevMode(true);
+    // In --dev, loopbackGitHubDev admits gh webhook forward deliveries.
+    expect(await policy?.(ghForwarded, loopback)).not.toBeNull();
+  });
+});
+
+describe("findGitHubChannelTargets", () => {
+  it("collects github channels across mounts and ignores others", () => {
+    const mounts: AgentMountLike[] = [
+      mount("fsd", [
+        channel("github", githubChannel({ onCheckSuite: () => null })),
+        channel("drive", { __agentServe: "channel", routes: [] }),
+      ]),
+      mount("reviewer", [
+        channel(
+          "github",
+          githubChannel({ webhookEvents: ["pull_request"], path: "/hook" })
+        ),
+      ]),
+    ];
+
+    const targets = findGitHubChannelTargets(mounts);
+    expect(targets).toHaveLength(2);
+    expect(targets[0]).toMatchObject({
+      slug: "fsd",
+      channelId: "github",
+      routePath: "/",
+    });
+    expect(targets[0]?.events).toContain("check_suite");
+    expect(targets[1]).toMatchObject({
+      slug: "reviewer",
+      channelId: "github",
+      routePath: "/hook",
+      events: ["pull_request"],
+    });
+  });
+});
+
+describe("channelForwardUrl", () => {
+  it("omits the slug prefix and the default path", () => {
+    expect(
+      channelForwardUrl({
+        host: "127.0.0.1",
+        port: 3000,
+        slug: "",
+        channelId: "github",
+        routePath: "/",
+      })
+    ).toBe("http://127.0.0.1:3000/v1/channels/github");
+  });
+
+  it("includes the slug and a custom path", () => {
+    expect(
+      channelForwardUrl({
+        host: "localhost",
+        port: 4000,
+        slug: "fsd",
+        channelId: "github",
+        routePath: "/hook",
+      })
+    ).toBe("http://localhost:4000/fsd/v1/channels/github/hook");
+  });
+});
+
+describe("resolveGitHubForwardTargets", () => {
+  const target = {
+    slug: "fsd",
+    channelId: "github",
+    routePath: "/",
+    events: ["pull_request", "check_run"],
+  };
+
+  it("derives the url and events from a single target", () => {
+    const result = resolveGitHubForwardTargets({
+      targets: [target],
+      host: "127.0.0.1",
+      port: 3000,
+    });
+    expect(result).toEqual({
+      ok: true,
+      targets: [
+        {
+          slug: "fsd",
+          channelId: "github",
+          url: "http://127.0.0.1:3000/fsd/v1/channels/github",
+          events: ["pull_request", "check_run"],
+        },
+      ],
+    });
+  });
+
+  it("returns every matching channel for fan-out", () => {
+    const reviewer = {
+      slug: "reviewer",
+      channelId: "github",
+      routePath: "/",
+      events: ["pull_request"],
+    };
+    const result = resolveGitHubForwardTargets({
+      targets: [target, reviewer],
+      host: "127.0.0.1",
+      port: 3000,
+    });
+    expect(result.ok && result.targets.map((t) => t.slug)).toEqual([
+      "fsd",
+      "reviewer",
+    ]);
+    expect(result.ok && unionForwardEvents(result.targets)).toEqual([
+      "pull_request",
+      "check_run",
+    ]);
+  });
+
+  it("applies an explicit event override to all targets", () => {
+    const result = resolveGitHubForwardTargets({
+      targets: [target, { ...target, slug: "reviewer" }],
+      host: "127.0.0.1",
+      port: 3000,
+      events: ["issues"],
+    });
+    expect(result.ok && result.targets.map((t) => t.events)).toEqual([
+      ["issues"],
+      ["issues"],
+    ]);
+  });
+
+  it("narrows by slug and channel", () => {
+    const other = { ...target, slug: "reviewer", channelId: "gh2" };
+    const result = resolveGitHubForwardTargets({
+      targets: [target, other],
+      slug: "reviewer",
+      channel: "gh2",
+      host: "127.0.0.1",
+      port: 3000,
+    });
+    expect(result.ok && result.targets).toHaveLength(1);
+    expect(result.ok && result.targets[0]?.channelId).toBe("gh2");
+  });
+
+  it("uses an explicit url with a single target's events", () => {
+    const result = resolveGitHubForwardTargets({
+      targets: [target],
+      host: "127.0.0.1",
+      port: 3000,
+      url: "https://example.ngrok.app/hook",
+    });
+    expect(result.ok && result.targets[0]?.url).toBe(
+      "https://example.ngrok.app/hook"
+    );
+    expect(result.ok && result.targets[0]?.events).toEqual([
+      "pull_request",
+      "check_run",
+    ]);
+  });
+
+  it("rejects --url when several channels match", () => {
+    const result = resolveGitHubForwardTargets({
+      targets: [target, { ...target, slug: "reviewer" }],
+      host: "127.0.0.1",
+      port: 3000,
+      url: "https://example.ngrok.app/hook",
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it("requires --events for --url when no single target matches", () => {
+    const result = resolveGitHubForwardTargets({
+      targets: [],
+      host: "127.0.0.1",
+      port: 3000,
+      url: "https://example.ngrok.app/hook",
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it("errors when no github channel exists", () => {
+    const result = resolveGitHubForwardTargets({
+      targets: [],
+      host: "127.0.0.1",
+      port: 3000,
+    });
+    expect(result.ok).toBe(false);
+    expect(!result.ok && result.error).toContain("no GitHub channel found");
+  });
+});
+
+describe("buildGitHubForwardArgs", () => {
+  it("builds repo + events + url args", () => {
+    expect(
+      buildGitHubForwardArgs({
+        url: "http://127.0.0.1:3000/v1/channels/github",
+        events: ["pull_request", "issue_comment"],
+        repo: "acme/widgets",
+      })
+    ).toEqual([
+      "webhook",
+      "forward",
+      "--url=http://127.0.0.1:3000/v1/channels/github",
+      "--events=pull_request,issue_comment",
+      "--repo=acme/widgets",
+    ]);
+  });
+
+  it("supports org + secret and dedupes events", () => {
+    const args = buildGitHubForwardArgs({
+      url: "http://127.0.0.1:3000/v1/channels/github",
+      events: ["pull_request", "pull_request"],
+      org: "octo-org",
+      secret: "s3cr3t",
+    });
+    expect(args).toContain("--org=octo-org");
+    expect(args).toContain("--secret=s3cr3t");
+    expect(args).toContain("--events=pull_request");
+  });
+});
+
+describe("parseGhWebhookExtensionInstalled", () => {
+  it("detects the extension in gh extension list output", () => {
+    expect(
+      parseGhWebhookExtensionInstalled("gh webhook\tcli/gh-webhook\tv1.0.0\n")
+    ).toBe(true);
+  });
+
+  it("returns false when absent", () => {
+    expect(parseGhWebhookExtensionInstalled("gh dash\tdlvhdr/gh-dash\n")).toBe(
+      false
+    );
+  });
+});
+
+describe("gh webhook extension pin", () => {
+  const listLine = `gh webhook\tcli/gh-webhook\t${GITHUB_WEBHOOK_EXTENSION_PIN}\n`;
+
+  it("parses the installed version", () => {
+    expect(parseGhWebhookExtensionVersion(listLine)).toBe(
+      GITHUB_WEBHOOK_EXTENSION_PIN
+    );
+  });
+
+  it("reports pin satisfaction", () => {
+    expect(ghWebhookExtensionPinSatisfied(listLine)).toBe(true);
+    expect(
+      ghWebhookExtensionPinSatisfied("gh webhook\tcli/gh-webhook\tv0.1.0\n")
+    ).toBe(false);
+  });
+
+  it("builds pinned install argv", () => {
+    expect(ghWebhookExtensionInstallArgs()).toEqual([
+      "extension",
+      "install",
+      "cli/gh-webhook",
+      "--pin",
+      GITHUB_WEBHOOK_EXTENSION_PIN,
+    ]);
+    expect(ghWebhookExtensionInstallArgs({ force: true })).toContain("--force");
+  });
+});
+
+describe("detectGitHubEnvTokenOverride", () => {
+  it("flags GITHUB_TOKEN, then GH_TOKEN", () => {
+    expect(detectGitHubEnvTokenOverride({ GITHUB_TOKEN: "x" })).toBe(
+      "GITHUB_TOKEN"
+    );
+    expect(detectGitHubEnvTokenOverride({ GH_TOKEN: "x" })).toBe("GH_TOKEN");
+  });
+
+  it("ignores empty/absent tokens", () => {
+    expect(detectGitHubEnvTokenOverride({})).toBeUndefined();
+    expect(
+      detectGitHubEnvTokenOverride({ GITHUB_TOKEN: "", GH_TOKEN: "" })
+    ).toBeUndefined();
+  });
+});
+
+describe("parseRepoFromRemoteUrl", () => {
+  it("parses https, ssh, and git@ remotes", () => {
+    expect(parseRepoFromRemoteUrl("https://github.com/acme/widgets.git")).toBe(
+      "acme/widgets"
+    );
+    expect(parseRepoFromRemoteUrl("git@github.com:acme/widgets.git")).toBe(
+      "acme/widgets"
+    );
+    expect(parseRepoFromRemoteUrl("ssh://git@github.com/acme/widgets")).toBe(
+      "acme/widgets"
+    );
+    expect(parseRepoFromRemoteUrl("https://github.com/acme/widgets/\n")).toBe(
+      "acme/widgets"
+    );
+  });
+
+  it("returns undefined for unrecognized input", () => {
+    expect(parseRepoFromRemoteUrl("")).toBeUndefined();
+    expect(parseRepoFromRemoteUrl("not-a-url")).toBeUndefined();
+  });
+});
+
+function mount(slug: string, channels: DiscoveredChannel[]): AgentMountLike {
+  return {
+    slug,
+    project: { channels } as unknown as AgentProject,
+  };
+}
+
+// Discovery erases the channel's state generic (`mod.default as
+// ChannelDefinition`); mirror that here so githubChannel()'s typed state
+// assigns to DiscoveredChannel.
+function channel(id: string, definition: unknown): DiscoveredChannel {
+  return { id, definition: definition as DiscoveredChannel["definition"] };
+}