@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/github/auth.ts

@@ -1,293 +0,0 @@
-/**
- * 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 }),
-  });
-  try {
-    const result = await auth({
-      type: "installation",
-      installationId: input.installationId,
-    });
-    return result.token;
-  } catch (error) {
-    throw installationTokenMintError(error, {
-      appId,
-      installationId: input.installationId,
-    });
-  }
-}
-
-/**
- * Octokit's bare mint failure ("Not Found - <docs url>") names neither the
- * app nor the installation, which makes a revoked installation or an
- * app/installation credential mismatch undiagnosable from production logs.
- * Rewrap with both ids and, for 404, the two causes that produce it.
- */
-function installationTokenMintError(
-  error: unknown,
-  context: { appId: string; installationId: number },
-): Error {
-  const status =
-    typeof error === "object" &&
-    error !== null &&
-    "status" in error &&
-    typeof (error as { status: unknown }).status === "number"
-      ? (error as { status: number }).status
-      : undefined;
-  const detail = error instanceof Error ? error.message : String(error);
-  const hint =
-    status === 404
-      ? " — the installation does not exist for this app: it was uninstalled or suspended, or the configured app credentials belong to a different GitHub App than the one this installation id refers to"
-      : "";
-  const wrapped = new Error(
-    `githubChannel: failed to mint an installation access token (app ${context.appId}, installation ${context.installationId}): ${detail}${hint}`,
-    error instanceof Error ? { cause: error } : undefined,
-  );
-  if (status !== undefined) {
-    (wrapped as Error & { status?: number }).status = status;
-  }
-  return wrapped;
-}
-
-/**
- * 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;
-  }
-}

package/src/channels/github/binding.ts

@@ -1,233 +0,0 @@
-/**
- * Rebuild GitHub API + thread handles for inbound hooks and stream events.
- */
-
-import type { Octokit } from "@octokit/rest";
-import {
-  callGitHubApi,
-  createGitHubCommitStatus,
-  createGitHubIssueComment,
-  createGitHubOctokit,
-  createGitHubReaction,
-  createGitHubReviewCommentReply,
-  type GitHubApiMethod,
-  type GitHubApiOptions,
-  type GitHubApiResponse,
-  type GitHubJsonObject,
-  type GitHubPostedComment,
-  type GitHubReactionContent,
-} from "./api.js";
-import { createGitHubCheck, type GitHubCheck, type GitHubCheckCreateInput } from "./checks.js";
-import type {
-  GitHubChannelCredentials,
-  GitHubConversationKind,
-  GitHubRepositoryRef,
-} from "./types.js";
-
-/** Hidden marker on outbound GitHub comments so inbound dispatch ignores them. */
-export const GITHUB_OUTBOUND_MARKER = "<!-- agent-serve-github -->";
-
-export function formatGitHubOutboundComment(body: string): string {
-  if (body.includes(GITHUB_OUTBOUND_MARKER)) {
-    return body;
-  }
-  return `${body.trimEnd()}\n\n${GITHUB_OUTBOUND_MARKER}`;
-}
-
-export interface GitHubBindingConfig {
-  api?: GitHubApiOptions;
-  credentials?: GitHubChannelCredentials;
-}
-
-/** Serializable fields needed to rebuild handles. */
-export interface GitHubBindingState {
-  conversationKind: GitHubConversationKind;
-  installationId: number | null;
-  issueNumber: number | null;
-  owner: string;
-  pullRequestNumber: number | null;
-  repo: string;
-  repositoryId: number | null;
-  /**
-   * `repository.html_url` from the delivery. Carries the GitHub Enterprise
-   * Server host; absent on state persisted before this field existed, in
-   * which case handles fall back to `https://github.com`.
-   */
-  repositoryUrl?: string | null;
-  reviewCommentId: number | null;
-  reviewThreadRootCommentId: number | null;
-  triggeringCommentId: number | null;
-}
-
-/** GitHub operations exposed to hooks (`ctx.github`). */
-export interface GitHubHandle {
-  installationId: number | undefined;
-  repository: GitHubRepositoryRef;
-  /**
-   * Authenticated `@octokit/rest` client. Prefer typed `octokit.rest.*`
-   * methods for new code; keep {@link request} / {@link createStatus} for
-   * thin wrappers and host-side tasks.
-   */
-  getOctokit(): Promise<Octokit>;
-  /**
-   * Call an arbitrary GitHub REST path with channel auth (PAT / App /
-   * `gh auth token`). Prefer {@link getOctokit} for typed calls.
-   */
-  request<T = unknown>(input: {
-    body?: GitHubJsonObject;
-    method: GitHubApiMethod;
-    path: string;
-  }): Promise<GitHubApiResponse<T>>;
-  /** Create a commit status on `sha`. */
-  createStatus(input: {
-    sha: string;
-    state: "error" | "failure" | "pending" | "success";
-    context?: string;
-    description?: string;
-    targetUrl?: string;
-  }): Promise<GitHubApiResponse>;
-  /**
-   * Open a CI check run (Checks API) on `sha` and get a handle for updating
-   * and concluding it. Needs `checks:write` — with `cursorAccount`, declare
-   * `githubChannel({ checks: true })` to opt the lease up.
-   */
-  createCheck(
-    input: Omit<GitHubCheckCreateInput, "github" | "owner" | "repo">,
-  ): Promise<GitHubCheck>;
-}
-
-/** Thread-scoped operations for the current conversation (`ctx.thread`). */
-export interface GitHubThread {
-  kind: GitHubConversationKind;
-  /** Post a reply on the issue/PR timeline or review thread. */
-  post(message: string): Promise<GitHubPostedComment>;
-  /**
-   * React to the triggering comment. No-ops when there is no comment to
-   * react to (e.g. a PR-opened delivery).
-   */
-  react(content: GitHubReactionContent): Promise<void>;
-}
-
-export function buildGitHubBinding(input: {
-  config: GitHubBindingConfig;
-  state: GitHubBindingState;
-}): { github: GitHubHandle; thread: GitHubThread } {
-  const { config, state } = input;
-  const repository: GitHubRepositoryRef = {
-    fullName: `${state.owner}/${state.repo}`,
-    url: state.repositoryUrl ?? `https://github.com/${state.owner}/${state.repo}`,
-    owner: state.owner,
-    name: state.repo,
-    ...(state.repositoryId === null ? {} : { id: state.repositoryId }),
-  };
-  const installationId = state.installationId ?? undefined;
-
-  let octokitPromise: Promise<Octokit> | undefined;
-  const getOctokit = (): Promise<Octokit> => {
-    octokitPromise ??= createGitHubOctokit({
-      api: config.api,
-      credentials: config.credentials,
-      installationId,
-    });
-    return octokitPromise;
-  };
-
-  const github: GitHubHandle = {
-    installationId,
-    repository,
-    getOctokit,
-    request(req) {
-      return callGitHubApi({
-        api: config.api,
-        body: req.body,
-        credentials: config.credentials,
-        installationId,
-        method: req.method,
-        path: req.path,
-      });
-    },
-    createStatus(status) {
-      return createGitHubCommitStatus({
-        api: config.api,
-        credentials: config.credentials,
-        installationId,
-        owner: state.owner,
-        repo: state.repo,
-        sha: status.sha,
-        state: status.state,
-        ...(status.context === undefined ? {} : { context: status.context }),
-        ...(status.description === undefined ? {} : { description: status.description }),
-        ...(status.targetUrl === undefined ? {} : { targetUrl: status.targetUrl }),
-      });
-    },
-    createCheck(check) {
-      return createGitHubCheck({
-        ...check,
-        github: { getOctokit },
-        owner: state.owner,
-        repo: state.repo,
-      });
-    },
-  };
-
-  const thread: GitHubThread = {
-    kind: state.conversationKind,
-    post(message) {
-      if (state.conversationKind === "review_thread") {
-        return createGitHubReviewCommentReply({
-          api: config.api,
-          body: message,
-          commentId: requiredNumber(
-            state.reviewThreadRootCommentId ?? state.reviewCommentId,
-            "reviewThreadRootCommentId",
-          ),
-          credentials: config.credentials,
-          installationId,
-          owner: state.owner,
-          pullRequestNumber: requiredNumber(state.pullRequestNumber, "pullRequestNumber"),
-          repo: state.repo,
-        });
-      }
-      return createGitHubIssueComment({
-        api: config.api,
-        body: message,
-        credentials: config.credentials,
-        installationId,
-        issueNumber: requiredNumber(state.issueNumber ?? state.pullRequestNumber, "issueNumber"),
-        owner: state.owner,
-        repo: state.repo,
-      });
-    },
-    async react(content) {
-      const commentId =
-        state.conversationKind === "review_thread"
-          ? state.reviewCommentId
-          : state.triggeringCommentId;
-      if (commentId === null) {
-        return;
-      }
-      await createGitHubReaction({
-        api: config.api,
-        commentId,
-        content,
-        credentials: config.credentials,
-        installationId,
-        owner: state.owner,
-        repo: state.repo,
-        subject:
-          state.conversationKind === "review_thread"
-            ? "pull_request_review_comment"
-            : "issue_comment",
-      });
-    },
-  };
-
-  return { github, thread };
-}
-
-function requiredNumber(value: number | null | undefined, name: string): number {
-  if (typeof value === "number" && Number.isFinite(value)) {
-    return value;
-  }
-  throw new Error(`githubChannel: missing ${name}.`);
-}

package/src/channels/github/checks.ts

@@ -1,145 +0,0 @@
-/**
- * GitHub CI checks (Checks API) — the GitHub {@link CiCheckWriter} behind the
- * shared check lifecycle in `../checks.js`.
- *
- * `createGitHubCheck` opens a merge-box check run on a commit and returns the
- * shared `CiCheck` handle; `resumeGitHubCheck` rebuilds one from a stored
- * check-run id. Works with any client exposing `getOctokit()` (`ctx.github`,
- * `ctx.host.github`), and is also reachable as `ctx.github.createCheck(...)`.
- *
- * Posting checks needs `checks:write`. With `cursorAccount`, declare
- * `githubChannel({ checks: true })` so the hosted lease is minted on the
- * `contents-write` tier; GitHub App / PAT credentials need the equivalent
- * permission. API failures are normalized into `GitHubApiError`.
- */
-
-import type { Octokit } from "@octokit/rest";
-import {
-  type CiCheck,
-  type CiCheckConcludeInput,
-  type CiCheckCreateInput,
-  type CiCheckOutput,
-  type CiCheckRef,
-  type CiCheckUpdateInput,
-  type CiCheckWriter,
-  openCiCheck,
-  resumeCiCheck,
-} from "../checks.js";
-import { wrapOctokitError } from "./api.js";
-
-/** Any client that can hand out an authenticated Octokit. */
-export interface GitHubCheckClient {
-  getOctokit(): Promise<Octokit>;
-}
-
-export type GitHubCheckOutput = CiCheckOutput;
-export type GitHubCheckUpdateInput = CiCheckUpdateInput;
-export type GitHubCheckConcludeInput = CiCheckConcludeInput;
-
-/** A created check run. All methods throw `GitHubApiError` on API failure. */
-export type GitHubCheck = CiCheck & CiCheckRef;
-
-export interface GitHubCheckCreateInput extends CiCheckCreateInput {
-  /** Client used for every API call on the returned handle. */
-  github: GitHubCheckClient;
-  /** Repository owner login, e.g. `"acme"`. */
-  owner: string;
-  /** Repository name, e.g. `"widgets"`. */
-  repo: string;
-}
-
-/**
- * GitHub writer: first write creates the check run (capturing its id), later
- * writes patch it.
- */
-function githubCheckWriter(input: {
-  github: GitHubCheckClient;
-  owner: string;
-  repo: string;
-  name: string;
-  sha?: string;
-  checkRunId?: number;
-}): CiCheckWriter {
-  let checkRunId = input.checkRunId;
-  return async write => {
-    const octokit = await input.github.getOctokit();
-    const base = {
-      owner: input.owner,
-      repo: input.repo,
-      name: input.name,
-      status: write.status,
-      conclusion: write.conclusion,
-      completed_at: write.completedAt,
-      details_url: write.detailsUrl,
-      output: write.output,
-    };
-    if (checkRunId === undefined) {
-      if (input.sha === undefined) {
-        throw new Error("githubChannel: cannot create a check without a sha.");
-      }
-      try {
-        const response = await octokit.rest.checks.create({
-          ...base,
-          head_sha: input.sha,
-          started_at: write.startedAt,
-        });
-        checkRunId = response.data.id;
-        return {
-          id: response.data.id,
-          url: typeof response.data.html_url === "string" ? response.data.html_url : undefined,
-        };
-      } catch (error) {
-        throw wrapOctokitError(error, "POST", `/repos/${input.owner}/${input.repo}/check-runs`);
-      }
-    }
-    try {
-      await octokit.rest.checks.update({ ...base, check_run_id: checkRunId });
-      return undefined;
-    } catch (error) {
-      throw wrapOctokitError(
-        error,
-        "PATCH",
-        `/repos/${input.owner}/${input.repo}/check-runs/${checkRunId}`,
-      );
-    }
-  };
-}
-
-/**
- * Create a CI check run on a commit and return a handle for later updates.
- *
- * ```ts
- * const check = await createGitHubCheck({
- *   github: ctx.github,
- *   owner: ctx.repository.owner,
- *   repo: ctx.repository.name,
- *   name: "Cursor Security Review",
- *   sha: pr.headSha,
- *   detailsUrl: sessionUrl,
- *   output: { title: "Running…", summary: `[View session](${sessionUrl})` },
- * });
- * // …do the work…
- * await check.conclude({ conclusion: "success", output: { … } });
- * ```
- */
-export function createGitHubCheck(input: GitHubCheckCreateInput): Promise<GitHubCheck> {
-  return openCiCheck(githubCheckWriter(input), input);
-}
-
-/**
- * Rebuild a {@link GitHubCheck} handle for an existing check run id (e.g.
- * after a process restart). No API call is made until the first update.
- */
-export function resumeGitHubCheck(input: {
-  github: GitHubCheckClient;
-  owner: string;
-  repo: string;
-  name: string;
-  checkRunId: number;
-  url?: string;
-}): GitHubCheck {
-  return resumeCiCheck(githubCheckWriter(input), {
-    id: input.checkRunId,
-    url: input.url,
-  });
-}