@cursor/july 0.1.24 → 0.1.26

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"] };
+}

package/src/channels/github/github-channel.ts

@@ -10,6 +10,7 @@ import {
 import { isDevMode } from "../../internal/dev-mode.js";
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   ChannelDefinition,
   ChannelEventHandlers,
@@ -68,7 +69,7 @@ import type {
  */
 type GitHubParsedContext = Omit<
   GitHubEventContext,
-  "github" | "thread" | "host"
+  "github" | "thread" | "host" | "artifacts"
 >;
 
 const DEFAULT_PULL_REQUEST_ACTIONS: ReadonlySet<string> = new Set([
@@ -737,6 +738,7 @@ async function handlePullRequest(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch =
     input.options.onPullRequest === undefined
@@ -828,6 +830,7 @@ async function handleIssueComment(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
 
   const dispatch =
@@ -918,6 +921,7 @@ async function handleReviewComment(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
 
   const dispatch =
@@ -994,6 +998,7 @@ async function handleIssue(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onIssue(ctx, parsed.issue);
   if (dispatch === null) {
@@ -1053,6 +1058,7 @@ async function handleCheckSuite(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.checkSuite
     );
@@ -1079,6 +1085,7 @@ async function handleCheckSuite(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onCheckSuite(ctx, parsed.checkSuite);
   if (dispatch === null) {
@@ -1143,6 +1150,7 @@ async function handleCheckRun(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.checkRun
     );
@@ -1169,6 +1177,7 @@ async function handleCheckRun(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onCheckRun(ctx, parsed.checkRun);
   if (dispatch === null) {
@@ -1229,6 +1238,7 @@ async function handleWorkflowRun(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.workflowRun
     );
@@ -1255,6 +1265,7 @@ async function handleWorkflowRun(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onWorkflowRun(ctx, parsed.workflowRun);
   if (dispatch === null) {
@@ -1326,6 +1337,7 @@ async function handleStatus(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onStatus(ctx, parsed.status);
   if (dispatch === null) {
@@ -1399,6 +1411,7 @@ async function handleGenericEvent(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onEvent(ctx, parsed.event);
   if (dispatch === null) {
@@ -2224,11 +2237,12 @@ function escapeRegExp(value: string): string {
  */
 function enrichEventContext(input: {
   bindingConfig: GitHubBindingConfig;
-  ctx: Omit<GitHubEventContext, "github" | "thread" | "host"> &
+  ctx: Omit<GitHubEventContext, "github" | "thread" | "host" | "artifacts"> &
     Partial<Pick<GitHubEventContext, "github" | "thread">>;
   bindingState: GitHubBindingState;
   installationId?: number;
   host: HostContext;
+  artifacts: ArtifactsApi;
 }): GitHubEventContext {
   const { github, thread } = buildGitHubBinding({
     config: input.bindingConfig,
@@ -2242,6 +2256,7 @@ function enrichEventContext(input: {
     github,
     thread,
     host: input.host,
+    artifacts: input.artifacts,
   };
 }
 
@@ -2254,6 +2269,7 @@ function enrichCiContext(input: {
   ctx: GitHubParsedContext;
   installationId?: number;
   host: HostContext;
+  artifacts: ArtifactsApi;
 }): GitHubEventContext {
   const binding = githubBindingStateForEvent({
     kind: input.ctx.conversation.kind,
@@ -2269,6 +2285,7 @@ function enrichCiContext(input: {
     bindingState: binding,
     installationId: input.installationId,
     host: input.host,
+    artifacts: input.artifacts,
   });
 }