@cursor/july 0.1.1

package/src/channels/github/api.ts

@@ -0,0 +1,374 @@
+/**
+ * GitHub REST helpers backed by `@octokit/rest`.
+ *
+ * Channel hooks should prefer `ctx.github` / `ctx.thread`. Use
+ * {@link createGitHubOctokit} (or `ctx.github.getOctokit()`) when you need
+ * typed Octokit methods directly.
+ */
+
+import { createAppAuth } from "@octokit/auth-app";
+import { Octokit } from "@octokit/rest";
+import {
+  type GitHubAuthApiOptions,
+  hasGitHubAppCredentials,
+  resolveCredentialValue,
+  resolveGitHubAccessToken,
+  resolveGitHubAppId,
+  resolveGitHubInstallationId,
+  resolveGitHubPrivateKey,
+} from "./auth.js";
+import type { GitHubChannelCredentials } from "./types.js";
+
+export type GitHubJsonObject = Record<string, unknown>;
+export type GitHubApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+
+export interface GitHubApiOptions extends GitHubAuthApiOptions {}
+
+export interface GitHubApiResponse<T = unknown> {
+  body: T;
+  ok: boolean;
+  status: number;
+}
+
+export class GitHubApiError extends Error {
+  readonly body: unknown;
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+
+  constructor(input: {
+    body: unknown;
+    method: string;
+    path: string;
+    status: number;
+  }) {
+    super(
+      `GitHub ${input.method} ${input.path} failed with HTTP ${input.status}.`
+    );
+    this.name = "GitHubApiError";
+    this.body = input.body;
+    this.method = input.method;
+    this.path = input.path;
+    this.status = input.status;
+  }
+}
+
+export interface GitHubPostedComment {
+  htmlUrl: string | undefined;
+  id: number;
+  raw: unknown;
+  url: string | undefined;
+}
+
+export type GitHubReactionContent =
+  | "+1"
+  | "-1"
+  | "confused"
+  | "eyes"
+  | "heart"
+  | "hooray"
+  | "laugh"
+  | "rocket";
+
+interface GitHubResourceInput {
+  api?: GitHubApiOptions;
+  credentials?: GitHubChannelCredentials;
+  installationId?: number;
+  owner: string;
+  repo: string;
+}
+
+/**
+ * Build an authenticated Octokit client.
+ *
+ * Prefer explicit bearer tokens, then GitHub App installation auth (when App
+ * credentials + an installation id are available), then local PAT /
+ * `gh auth token`. App auth uses `@octokit/auth-app` so Octokit refreshes
+ * installation tokens itself.
+ */
+export async function createGitHubOctokit(input: {
+  api?: GitHubApiOptions;
+  credentials?: GitHubChannelCredentials;
+  installationId?: number;
+}): Promise<Octokit> {
+  const requestOptions =
+    input.api?.fetch === undefined ? undefined : { fetch: input.api.fetch };
+  const baseUrl = input.api?.apiBaseUrl;
+
+  const explicit =
+    (await resolveCredentialValue(input.credentials?.token)) ??
+    (await resolveCredentialValue(input.credentials?.installationToken));
+  if (explicit !== undefined) {
+    return new Octokit({
+      auth: explicit,
+      ...(baseUrl === undefined ? {} : { baseUrl }),
+      ...(requestOptions === undefined ? {} : { request: requestOptions }),
+    });
+  }
+
+  const installationId = await resolveGitHubInstallationId(
+    input.installationId
+  );
+  if (
+    installationId !== undefined &&
+    (await hasGitHubAppCredentials(input.credentials))
+  ) {
+    const appId = await resolveGitHubAppId(input.credentials?.appId);
+    const privateKey = await resolveGitHubPrivateKey(
+      input.credentials?.privateKey
+    );
+    return new Octokit({
+      authStrategy: createAppAuth,
+      auth: {
+        appId,
+        privateKey,
+        installationId,
+      },
+      ...(baseUrl === undefined ? {} : { baseUrl }),
+      ...(requestOptions === undefined ? {} : { request: requestOptions }),
+    });
+  }
+
+  // Local testing: ambient PAT / `gh auth token` when App creds are unset.
+  const token = await resolveGitHubAccessToken(input);
+  return new Octokit({
+    auth: token,
+    ...(baseUrl === undefined ? {} : { baseUrl }),
+    ...(requestOptions === undefined ? {} : { request: requestOptions }),
+  });
+}
+
+/**
+ * Call a GitHub REST path with channel auth. Prefer typed Octokit methods via
+ * {@link createGitHubOctokit} / `ctx.github.getOctokit()` when possible.
+ */
+export async function callGitHubApi<T = unknown>(input: {
+  api?: GitHubApiOptions;
+  body?: GitHubJsonObject;
+  credentials?: GitHubChannelCredentials;
+  installationId?: number;
+  method: GitHubApiMethod;
+  path: string;
+  options?: { auth?: boolean; headers?: Readonly<Record<string, string>> };
+}): Promise<GitHubApiResponse<T>> {
+  if (input.options?.auth === false) {
+    const octokit = new Octokit({
+      ...(input.api?.apiBaseUrl === undefined
+        ? {}
+        : { baseUrl: input.api.apiBaseUrl }),
+      ...(input.api?.fetch === undefined
+        ? {}
+        : { request: { fetch: input.api.fetch } }),
+    });
+    return requestWithOctokit(octokit, input);
+  }
+
+  const octokit = await createGitHubOctokit({
+    api: input.api,
+    credentials: input.credentials,
+    installationId: input.installationId,
+  });
+  return requestWithOctokit(octokit, input);
+}
+
+async function requestWithOctokit<T>(
+  octokit: Octokit,
+  input: {
+    body?: GitHubJsonObject;
+    method: GitHubApiMethod;
+    path: string;
+    options?: { headers?: Readonly<Record<string, string>> };
+  }
+): Promise<GitHubApiResponse<T>> {
+  try {
+    const route = `${input.method} ${normalizeRequestPath(input.path)}`;
+    const response = await octokit.request(route, {
+      ...(input.body ?? {}),
+      ...(input.options?.headers === undefined
+        ? {}
+        : { headers: input.options.headers }),
+    });
+    return {
+      body: response.data as T,
+      ok: true,
+      status: response.status,
+    };
+  } catch (error) {
+    if (isOctokitRequestError(error)) {
+      throw new GitHubApiError({
+        body: error.response?.data,
+        method: input.method,
+        path: input.path,
+        status: error.status,
+      });
+    }
+    throw error;
+  }
+}
+
+/** Create an issue or PR timeline comment. */
+export async function createGitHubIssueComment(
+  input: GitHubResourceInput & { body: string; issueNumber: number }
+): Promise<GitHubPostedComment> {
+  const octokit = await createGitHubOctokit(input);
+  try {
+    const response = await octokit.rest.issues.createComment({
+      owner: input.owner,
+      repo: input.repo,
+      issue_number: input.issueNumber,
+      body: input.body,
+    });
+    return toPostedComment(response.data);
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/issues/${input.issueNumber}/comments`
+    );
+  }
+}
+
+/** Reply to an inline pull-request review comment thread. */
+export async function createGitHubReviewCommentReply(
+  input: GitHubResourceInput & {
+    body: string;
+    commentId: number;
+    pullRequestNumber: number;
+  }
+): Promise<GitHubPostedComment> {
+  const octokit = await createGitHubOctokit(input);
+  try {
+    const response = await octokit.rest.pulls.createReplyForReviewComment({
+      owner: input.owner,
+      repo: input.repo,
+      pull_number: input.pullRequestNumber,
+      comment_id: input.commentId,
+      body: input.body,
+    });
+    return toPostedComment(response.data);
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/pulls/${input.pullRequestNumber}/comments/${input.commentId}/replies`
+    );
+  }
+}
+
+/** Create a reaction on an issue or review comment. */
+export async function createGitHubReaction(
+  input: GitHubResourceInput & {
+    commentId: number;
+    content: GitHubReactionContent;
+    subject: "issue_comment" | "pull_request_review_comment";
+  }
+): Promise<GitHubApiResponse> {
+  const octokit = await createGitHubOctokit(input);
+  try {
+    const response =
+      input.subject === "issue_comment"
+        ? await octokit.rest.reactions.createForIssueComment({
+            owner: input.owner,
+            repo: input.repo,
+            comment_id: input.commentId,
+            content: input.content,
+          })
+        : await octokit.rest.reactions.createForPullRequestReviewComment({
+            owner: input.owner,
+            repo: input.repo,
+            comment_id: input.commentId,
+            content: input.content,
+          });
+    return {
+      body: response.data,
+      ok: true,
+      status: response.status,
+    };
+  } catch (error) {
+    const segment =
+      input.subject === "issue_comment" ? "issues/comments" : "pulls/comments";
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/${segment}/${input.commentId}/reactions`
+    );
+  }
+}
+
+/** Create a commit status (legacy `statuses` API). */
+export async function createGitHubCommitStatus(
+  input: GitHubResourceInput & {
+    sha: string;
+    state: "error" | "failure" | "pending" | "success";
+    context?: string;
+    description?: string;
+    targetUrl?: string;
+  }
+): Promise<GitHubApiResponse> {
+  const octokit = await createGitHubOctokit(input);
+  try {
+    const response = await octokit.rest.repos.createCommitStatus({
+      owner: input.owner,
+      repo: input.repo,
+      sha: input.sha,
+      state: input.state,
+      ...(input.context === undefined ? {} : { context: input.context }),
+      ...(input.description === undefined
+        ? {}
+        : { description: input.description }),
+      ...(input.targetUrl === undefined ? {} : { target_url: input.targetUrl }),
+    });
+    return {
+      body: response.data,
+      ok: true,
+      status: response.status,
+    };
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/statuses/${input.sha}`
+    );
+  }
+}
+
+function toPostedComment(raw: {
+  html_url?: string;
+  id?: number;
+  url?: string;
+}): GitHubPostedComment {
+  return {
+    htmlUrl: typeof raw.html_url === "string" ? raw.html_url : undefined,
+    id: typeof raw.id === "number" ? raw.id : 0,
+    raw,
+    url: typeof raw.url === "string" ? raw.url : undefined,
+  };
+}
+
+function normalizeRequestPath(path: string): string {
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+function isOctokitRequestError(error: unknown): error is {
+  status: number;
+  response?: { data?: unknown };
+} {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    typeof (error as { status: unknown }).status === "number"
+  );
+}
+
+function wrapOctokitError(error: unknown, method: string, path: string): Error {
+  if (isOctokitRequestError(error)) {
+    return new GitHubApiError({
+      body: error.response?.data,
+      method,
+      path,
+      status: error.status,
+    });
+  }
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/channels/github/auth.ts

@@ -0,0 +1,275 @@
+/**
+ * GitHub API token resolution for the channel pack.
+ *
+ * Resolution order for authenticated REST calls:
+ * 1. `credentials.token` / `credentials.installationToken` (explicit)
+ * 2. GitHub App JWT → installation access token (when App creds + installation
+ *    id are available — webhook `installation.id` or `GITHUB_APP_INSTALLATION_ID`)
+ * 3. `GITHUB_TOKEN` / `GH_TOKEN` env (local PAT / fine-grained token)
+ * 4. `gh auth token` (local CLI session)
+ *
+ * Production should set App credentials and omit ambient PATs. Local testing
+ * can keep using a PAT or `gh auth login` when App creds are unset.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createAppAuth } from "@octokit/auth-app";
+import type {
+  GitHubChannelCredentials,
+  GitHubCredentialValue,
+} from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface GitHubAuthApiOptions {
+  apiBaseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+let ghAuthTokenCache: { token: string; expiresAtMs: number } | null = null;
+const GH_AUTH_CACHE_MS = 5 * 60_000;
+
+/** Refresh exported `GH_TOKEN` before installation tokens expire (~60m). */
+const GH_CLI_TOKEN_REFRESH_MS = 50 * 60_000;
+let ghCliTokenRefreshTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Resolve a credential value (literal or lazy). */
+export async function resolveCredentialValue(
+  value: GitHubCredentialValue | undefined
+): Promise<string | undefined> {
+  if (value === undefined) {
+    return undefined;
+  }
+  const resolved = typeof value === "function" ? await value() : value;
+  if (typeof resolved !== "string") {
+    return undefined;
+  }
+  const trimmed = resolved.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** True when App id + private key are configured (credentials or env). */
+export async function hasGitHubAppCredentials(
+  credentials?: GitHubChannelCredentials
+): Promise<boolean> {
+  try {
+    await resolveGitHubAppId(credentials?.appId);
+    await resolveGitHubPrivateKey(credentials?.privateKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve an installation id from the call site, then
+ * `GITHUB_APP_INSTALLATION_ID` (host / non-webhook GitHub calls).
+ */
+export async function resolveGitHubInstallationId(
+  installationId?: number
+): Promise<number | undefined> {
+  if (
+    installationId !== undefined &&
+    Number.isInteger(installationId) &&
+    installationId > 0
+  ) {
+    return installationId;
+  }
+  const fromEnv = await resolveCredentialValue(
+    process.env.GITHUB_APP_INSTALLATION_ID
+  );
+  if (fromEnv === undefined) {
+    return undefined;
+  }
+  if (!/^[1-9][0-9]*$/u.test(fromEnv)) {
+    return undefined;
+  }
+  return Number(fromEnv);
+}
+
+/**
+ * Resolve a bearer token for GitHub REST calls. Prefer explicit credentials,
+ * then App installation tokens when configured, then local PAT / `gh auth`.
+ */
+export async function resolveGitHubAccessToken(input: {
+  api?: GitHubAuthApiOptions;
+  credentials?: GitHubChannelCredentials;
+  installationId?: number;
+}): Promise<string> {
+  const explicit =
+    (await resolveCredentialValue(input.credentials?.token)) ??
+    (await resolveCredentialValue(input.credentials?.installationToken));
+  if (explicit !== undefined) {
+    return explicit;
+  }
+
+  const installationId = await resolveGitHubInstallationId(
+    input.installationId
+  );
+  if (
+    installationId !== undefined &&
+    (await hasGitHubAppCredentials(input.credentials))
+  ) {
+    return createGitHubInstallationToken({
+      api: input.api,
+      appId: input.credentials?.appId,
+      installationId,
+      privateKey: input.credentials?.privateKey,
+    });
+  }
+
+  const fromEnv =
+    (await resolveCredentialValue(process.env.GITHUB_TOKEN)) ??
+    (await resolveCredentialValue(process.env.GH_TOKEN));
+  if (fromEnv !== undefined) {
+    return fromEnv;
+  }
+
+  const fromGh = await tryResolveGhAuthToken();
+  if (fromGh !== undefined) {
+    return fromGh;
+  }
+
+  throw new Error(
+    "githubChannel: no GitHub token available (set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + installation id, or GITHUB_TOKEN / GH_TOKEN, or run `gh auth login`)."
+  );
+}
+
+/** Soft resolve — returns undefined instead of throwing. */
+export async function tryResolveGitHubAccessToken(input: {
+  api?: GitHubAuthApiOptions;
+  credentials?: GitHubChannelCredentials;
+  installationId?: number;
+}): Promise<string | undefined> {
+  try {
+    return await resolveGitHubAccessToken(input);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read `gh auth token` when the CLI is logged in. Cached briefly. */
+export async function tryResolveGhAuthToken(): Promise<string | undefined> {
+  if (ghAuthTokenCache !== null && Date.now() < ghAuthTokenCache.expiresAtMs) {
+    return ghAuthTokenCache.token;
+  }
+  try {
+    const { stdout } = await execFileAsync("gh", ["auth", "token"], {
+      timeout: 5_000,
+      env: process.env,
+    });
+    const token = stdout.trim();
+    if (token === "") {
+      return undefined;
+    }
+    ghAuthTokenCache = {
+      token,
+      expiresAtMs: Date.now() + GH_AUTH_CACHE_MS,
+    };
+    return token;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function resolveGitHubAppId(
+  appId?: GitHubCredentialValue | number
+): Promise<string> {
+  const source =
+    appId ??
+    (process.env.GITHUB_APP_ID !== undefined && process.env.GITHUB_APP_ID !== ""
+      ? process.env.GITHUB_APP_ID
+      : undefined);
+  if (source === undefined) {
+    throw new Error("githubChannel: GITHUB_APP_ID is required.");
+  }
+  if (typeof source === "number") {
+    return String(source);
+  }
+  const value = await resolveCredentialValue(source);
+  if (value === undefined) {
+    throw new Error("githubChannel: GITHUB_APP_ID is required.");
+  }
+  return value;
+}
+
+export async function resolveGitHubPrivateKey(
+  privateKey?: GitHubCredentialValue
+): Promise<string> {
+  const source =
+    privateKey ??
+    (process.env.GITHUB_APP_PRIVATE_KEY !== undefined &&
+    process.env.GITHUB_APP_PRIVATE_KEY !== ""
+      ? process.env.GITHUB_APP_PRIVATE_KEY
+      : undefined);
+  if (source === undefined) {
+    throw new Error("githubChannel: GITHUB_APP_PRIVATE_KEY is required.");
+  }
+  const value = await resolveCredentialValue(source);
+  if (value === undefined) {
+    throw new Error("githubChannel: GITHUB_APP_PRIVATE_KEY is required.");
+  }
+  return value.replace(/\\n/gu, "\n");
+}
+
+/**
+ * Mint an installation access token via `@octokit/auth-app`.
+ * Prefer {@link createGitHubOctokit} for normal API work — this is for
+ * callers that only need the raw token string.
+ */
+export async function createGitHubInstallationToken(input: {
+  api?: GitHubAuthApiOptions;
+  appId?: GitHubCredentialValue | number;
+  installationId: number;
+  privateKey?: GitHubCredentialValue;
+}): Promise<string> {
+  const appId = await resolveGitHubAppId(input.appId);
+  const privateKey = await resolveGitHubPrivateKey(input.privateKey);
+  // Prefer createGitHubOctokit for API work — this path only mints a raw
+  // token. Custom fetch belongs on the Octokit client, not createAppAuth
+  // (StrategyOptions.request expects a full RequestInterface).
+  const auth = createAppAuth({
+    appId,
+    privateKey,
+    ...(input.api?.apiBaseUrl === undefined
+      ? {}
+      : { baseUrl: input.api.apiBaseUrl }),
+  });
+  const result = await auth({
+    type: "installation",
+    installationId: input.installationId,
+  });
+  return result.token;
+}
+
+/**
+ * Export the resolved host GitHub token as `process.env.GH_TOKEN` so
+ * subprocesses that shell out to `gh` work on App-credential hosts (corp
+ * agent-serve). Intended for serve warmup when auth source is `app`.
+ * Returns whether `GH_TOKEN` was written; refreshes on an interval.
+ */
+export async function ensureGhCliTokenEnv(): Promise<boolean> {
+  const token = await tryResolveGitHubAccessToken({});
+  if (token === undefined) {
+    return false;
+  }
+  process.env.GH_TOKEN = token;
+  if (ghCliTokenRefreshTimer === null) {
+    const timer = setInterval(() => {
+      void ensureGhCliTokenEnv();
+    }, GH_CLI_TOKEN_REFRESH_MS);
+    timer.unref?.();
+    ghCliTokenRefreshTimer = timer;
+  }
+  return true;
+}
+
+/** Clears in-memory caches. Intended for tests. */
+export function clearGitHubAuthCaches(): void {
+  ghAuthTokenCache = null;
+  if (ghCliTokenRefreshTimer !== null) {
+    clearInterval(ghCliTokenRefreshTimer);
+    ghCliTokenRefreshTimer = null;
+  }
+}