@cursor/july 0.1.1

package/dist/channels/github/forward.js

@@ -0,0 +1,271 @@
+/**
+ * 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 { 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) {
+    const args = [
+        "extension",
+        "install",
+        GITHUB_WEBHOOK_EXTENSION,
+        "--pin",
+        GITHUB_WEBHOOK_EXTENSION_PIN,
+    ];
+    if ((options === null || options === void 0 ? void 0 : options.force) === true) {
+        args.push("--force");
+    }
+    return args;
+}
+/**
+ * Collect the GitHub webhook channels across every mounted agent, reading the
+ * `meta` a {@link githubChannel} publishes.
+ */
+export function findGitHubChannelTargets(mounts) {
+    var _a, _b, _c;
+    const targets = [];
+    for (const { slug, project } of mounts) {
+        for (const channel of project.channels) {
+            const meta = channel.definition.meta;
+            if ((meta === null || meta === void 0 ? void 0 : meta.kind) !== GITHUB_CHANNEL_KIND) {
+                continue;
+            }
+            const postRoute = ((_a = channel.definition.routes) !== null && _a !== void 0 ? _a : []).find((route) => route.method === "POST");
+            targets.push({
+                slug,
+                channelId: channel.id,
+                routePath: (_b = postRoute === null || postRoute === void 0 ? void 0 : postRoute.path) !== null && _b !== void 0 ? _b : "/",
+                events: [...((_c = meta.githubWebhookEvents) !== null && _c !== void 0 ? _c : [])],
+            });
+        }
+    }
+    return targets;
+}
+/** Absolute forward URL for a channel target on a local server. */
+export function channelForwardUrl(input) {
+    const slugPrefix = input.slug === "" ? "" : `/${input.slug}`;
+    const suffix = input.routePath === "/" ? "" : input.routePath;
+    return `http://${input.host}:${input.port}${slugPrefix}/v1/channels/${input.channelId}${suffix}`;
+}
+/**
+ * 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) {
+    var _a, _b, _c, _d;
+    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 !== null && overrideEvents !== void 0 ? overrideEvents : only === null || only === void 0 ? void 0 : 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: (_b = (_a = only === null || only === void 0 ? void 0 : only.slug) !== null && _a !== void 0 ? _a : input.slug) !== null && _b !== void 0 ? _b : "",
+                    channelId: (_d = (_c = only === null || only === void 0 ? void 0 : only.channelId) !== null && _c !== void 0 ? _c : input.channel) !== null && _d !== void 0 ? _d : "",
+                    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 !== null && overrideEvents !== void 0 ? 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) {
+    return dedupeEvents(targets.flatMap((target) => target.events));
+}
+/**
+ * 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) {
+    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) {
+    return parseGhWebhookExtensionVersion(listOutput) !== undefined;
+}
+/** Version column from `gh extension list` for the webhook extension, if present. */
+export function parseGhWebhookExtensionVersion(listOutput) {
+    var _a, _b;
+    var _c;
+    for (const line of listOutput.split("\n")) {
+        if (!line.includes("gh-webhook")) {
+            continue;
+        }
+        const parts = line.split("\t");
+        const repo = (_c = (_a = parts[1]) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _c !== void 0 ? _c : "";
+        if (!repo.includes("gh-webhook")) {
+            continue;
+        }
+        const version = (_b = parts[2]) === null || _b === void 0 ? void 0 : _b.trim();
+        return version === undefined || version === "" ? undefined : version;
+    }
+    return undefined;
+}
+/** Whether the installed webhook extension matches {@link GITHUB_WEBHOOK_EXTENSION_PIN}. */
+export function ghWebhookExtensionPinSatisfied(listOutput) {
+    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 = process.env) {
+    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) {
+    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) {
+    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;
+    try {
+        parsed = new URL(url);
+    }
+    catch (_a) {
+        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) {
+    return target.slug === ""
+        ? target.channelId
+        : `${target.slug}/${target.channelId}`;
+}
+function dedupeEvents(events) {
+    return [...new Set(events.map((event) => event.trim()).filter(Boolean))];
+}
+function describeTargets(targets) {
+    return targets
+        .map((t) => `  - ${targetLabel(t)} (events: ${t.events.join(", ") || "none"})`)
+        .join("\n");
+}

package/dist/channels/github/github-channel.d.ts

@@ -0,0 +1,127 @@
+import type { AuthContext, ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
+import { type GitHubChannelState } from "./state.js";
+import type { GitHubChannelOptions, GitHubComment, GitHubCredentialValue, GitHubEventContext, GitHubPullRequestEvent, GitHubTurnDispatch, GitHubUser } from "./types.js";
+/**
+ * Inbound context as produced by the payload parsers, before the GitHub API +
+ * thread handles are attached. {@link enrichEventContext} adds `github`,
+ * `thread`, and `host` to make a full {@link GitHubEventContext} for hooks.
+ */
+type GitHubParsedContext = Omit<GitHubEventContext, "github" | "thread" | "host">;
+/**
+ * Derive the turn's auth from the actor that triggered the delivery — the
+ * standard `{ auth: defaultGitHubAuth(ctx) }` dispatch from an inbound hook.
+ */
+export declare function defaultGitHubAuth(ctx: GitHubParsedContext): AuthContext;
+export declare function githubContinuationKey(ctx: GitHubParsedContext): string;
+/** @deprecated Prefer {@link githubContinuationKey}. */
+export declare function githubPullRequestContinuationKey(ctx: GitHubParsedContext): string;
+export declare function defaultGitHubTitle(ctx: GitHubParsedContext): string;
+/** @deprecated Prefer {@link defaultGitHubTitle}. */
+export declare function defaultGitHubPullRequestTitle(ctx: GitHubParsedContext): string;
+export declare function defaultGitHubPullRequestMessage(ctx: GitHubParsedContext, pullRequest: GitHubPullRequestEvent): string;
+/**
+ * Default dispatch gate when no `onPullRequest` hook is declared: the common
+ * review triggers start a turn as the delivery's actor.
+ *
+ * Eve has no default for `onPullRequest` (opt-in only). Agent-serve keeps this
+ * gate for backward compatibility with existing demos.
+ */
+export declare function defaultGitHubPullRequestDispatch(ctx: GitHubParsedContext, pullRequest: GitHubPullRequestEvent): GitHubTurnDispatch | null;
+/**
+ * Default comment hook (Eve-compatible): dispatch only when the comment
+ * `@mention`s {@link botName}.
+ */
+export declare function defaultOnComment(ctx: GitHubParsedContext, comment: GitHubComment, options: {
+    botName?: string;
+}): GitHubTurnDispatch | null;
+export declare function shouldDispatchGitHubComment(args: {
+    body: string;
+    author?: GitHubUser;
+    botName?: string;
+}): boolean;
+export declare function extractGitHubCommentTrigger(args: {
+    body: string;
+    botName?: string;
+}): {
+    message: string;
+} | undefined;
+export declare function parseGitHubPullRequestEvent(args: {
+    payload: unknown;
+    deliveryId?: string;
+}): {
+    ctx: GitHubParsedContext;
+    pullRequest: GitHubPullRequestEvent;
+} | null;
+export declare function verifyGitHubWebhookSignature(args: {
+    body: string;
+    signatureHeader: string | null;
+    secret: GitHubCredentialValue | undefined;
+}): Promise<"verified" | "missing_secret" | "missing_signature" | "mismatch">;
+/**
+ * GitHub webhook channel (Eve-compatible dispatch surface). Point a GitHub App
+ * or repository webhook at `/<agent>/v1/channels/github` and declare inbound
+ * hooks:
+ *
+ * ```ts
+ * import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+ *
+ * export default githubChannel({
+ *   botName: "my-agent",
+ *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+ *   // Replaces the @mention gate. Prefer typed Octokit via getOctokit().
+ *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
+ *   onPullRequest: (ctx, pr) =>
+ *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+ *   onStatus: (ctx, status) =>
+ *     status.state === "failure"
+ *       ? {
+ *           task: async () => {
+ *             const octokit = await ctx.github.getOctokit();
+ *             await octokit.rest.repos.createCommitStatus({
+ *               owner: ctx.repository.owner,
+ *               repo: ctx.repository.name,
+ *               sha: status.sha,
+ *               state: "pending",
+ *               context: "agent/triage",
+ *             });
+ *           },
+ *         }
+ *       : null,
+ *   onEvent: (ctx, event) =>
+ *     event.eventName === "label" ? { auth: defaultGitHubAuth(ctx) } : null,
+ * });
+ * ```
+ */
+/**
+ * Core GitHub webhook dispatch used by {@link githubChannel} routes and by
+ * {@link handleAgentServeTrigger} fan-out. Signature verification is the
+ * caller's responsibility (HTTP route verifies; internal fan-out skips).
+ */
+export declare function dispatchGitHubWebhook(input: {
+    options: GitHubChannelOptions;
+    eventName: string | null;
+    payload: unknown;
+    deliveryId?: string;
+    args: ChannelHandlerArgs;
+}): Promise<Response>;
+/**
+ * HTTP entry for a single agent's GitHub channel: optional HMAC verify, then
+ * {@link dispatchGitHubWebhook}.
+ */
+export declare function handleGitHubWebhookRequest(input: {
+    options: GitHubChannelOptions;
+    request: Request;
+    args: ChannelHandlerArgs;
+    /** When true, skip HMAC even if a webhook secret is configured. */
+    skipSignatureVerification?: boolean;
+}): Promise<Response>;
+/**
+ * Recover the {@link GitHubChannelOptions} used to build a channel definition,
+ * if it was created via {@link githubChannel}.
+ */
+export declare function getGitHubChannelOptions(definition: object): GitHubChannelOptions | undefined;
+export declare function githubChannel(options?: GitHubChannelOptions): ChannelDefinition<GitHubChannelState>;
+/** Match GitHub App bot actors (`slug` config vs `slug[bot]` login). */
+export declare function isGitHubAppBotAuthor(author: GitHubUser | undefined, botName: string | undefined): boolean;
+export {};
+//# sourceMappingURL=github-channel.d.ts.map

package/dist/channels/github/github-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/github/github-channel.ts"],"names":[],"mappings":"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"}