sailfork / t3code-github / .repos/ alchemy-effect/ packages/ pkg/ src/ Registry/ GitHub.ts

import * as crypto from "node:crypto";
import * as Github from "@distilled.cloud/github";
import * as Actions from "@distilled.cloud/github/actions";
import * as Apps from "@distilled.cloud/github/apps";
import * as Checks from "@distilled.cloud/github/checks";
import * as Issues from "@distilled.cloud/github/issues";
import * as Pulls from "@distilled.cloud/github/pulls";
import * as Arr from "effect/Array";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as DateTime from "effect/DateTime";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import { Base64Url } from "effect/encoding";
import * as HttpClient from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import { COMMENT_MARKER, RegistryConfig } from "./Bindings.ts";
import * as KVCache from "./KVCache.ts";

export class CryptoError extends Data.TaggedError("CryptoError")<{ readonly message: string }> {}

export class AppNotInstalled extends Data.TaggedError("AppNotInstalled")<{
  readonly repo: string;
}> {
  override get message() {
    return `The GitHub App is not installed on ${this.repo}`;
  }
}

/** Import an RSA private key PEM (PKCS#1 or PKCS#8) for RS256 signing. */
export const importPrivateKey = (pem: string) =>
  Effect.try({
    try: () => crypto.createPrivateKey({ key: pem }),
    catch: (cause) =>
      new CryptoError({
        message: `invalid private key: ${cause instanceof Error ? cause.message : String(cause)}`,
      }),
  });

/** Sign a compact RS256 JWT, used to authenticate as the GitHub App. */
export const signJwt = (claims: Record<string, unknown>, key: crypto.KeyObject) =>
  Effect.try({
    try: () => {
      const header = Base64Url.encode(JSON.stringify({ alg: "RS256", typ: "JWT" }));
      const payload = Base64Url.encode(JSON.stringify(claims));
      const input = `${header}.${payload}`;
      const signature = crypto.sign("sha256", Buffer.from(input), key);
      return `${input}.${Base64Url.encode(new Uint8Array(signature))}`;
    },
    catch: (cause) =>
      new CryptoError({
        message: `signing failed: ${cause instanceof Error ? cause.message : String(cause)}`,
      }),
  });

/**
 * Install commands per package, grouped. A group marked `collapsed`
 * renders as a closed `<details>` block so a long list of secondary
 * packages stays out of the way.
 */
export const renderInstalls = (
  packages: ReadonlyArray<{ name: string; group: string; url: string }>,
  groups: ReadonlyArray<{ name: string; collapsed: boolean }>,
) => {
  const collapsed = new Set(groups.filter((g) => g.collapsed).map((g) => g.name));
  // One code block per package so each command has its own copy button, in
  // the order the manifest lists them, which is the order they were given
  // to `pkg pack`. Blank lines around the markdown inside `<details>` are
  // what make GitHub render it.
  return Object.entries(Arr.groupBy(packages, (pkg) => pkg.group))
    .flatMap(([group, members]) => {
      const installs = members.flatMap(({ url }) => ["```sh", `pnpm install ${url}`, "```", ""]);
      return collapsed.has(group)
        ? [
            "<details>",
            `<summary><b>${group}</b> (${members.length})</summary>`,
            "",
            ...installs,
            "</details>",
            "",
          ]
        : [`### ${group}`, "", ...installs];
    })
    .join("\n");
};

/**
 * GitHub's `<relative-time>` element, rendered as a live relative time in
 * comments, with a plain UTC fallback like `Sep 7, 2026 at 2:42 PM UTC`.
 */
const relativeTime = (millis: number) => {
  const date = DateTime.makeUnsafe(millis);
  const label = DateTime.formatUtc(date, {
    locale: "en-US",
    dateStyle: "medium",
    timeStyle: "short",
  });
  return `<relative-time datetime="${DateTime.formatIso(date)}">${label} UTC</relative-time>`;
};

export const renderComment = (
  packages: ReadonlyArray<{ name: string; group: string; url: string }>,
  groups: ReadonlyArray<{ name: string; collapsed: boolean }>,
  times: { readonly publishedAt: number; readonly expiresAt: number },
) =>
  [
    COMMENT_MARKER,
    "",
    "Install the packages built from this commit:",
    "",
    renderInstalls(packages, groups),
    `Published ${relativeTime(times.publishedAt)}. Expires ${relativeTime(times.expiresAt)}, extended while this pull request is open.`,
  ].join("\n");

/** Render any GitHub operation failure for logs and error responses. */
export const describe = (error: {
  readonly _tag: string;
  readonly message?: string | undefined;
}) => (error.message ? `${error._tag}: ${error.message}` : error._tag);

const USER_AGENT = "alchemy-pkg";

const split = (repo: string) => {
  const [owner, name] = repo.split("/");
  return { owner: owner ?? "", repo: name ?? "" };
};

/**
 * Installation tokens are refreshed two minutes before GitHub expires them:
 * one for clock skew, one for the minute KV's edge cache may keep serving an
 * expired entry.
 */
const TOKEN_MARGIN = Duration.minutes(2);

/**
 * The registry's GitHub App: every operation runs as the App's installation
 * on the repository in question. Installation tokens live in the KV cache,
 * so one mint per repository serves every isolate for about an hour.
 */
const make = Effect.gen(function* () {
  const config = yield* RegistryConfig;
  const http = yield* HttpClient.HttpClient;

  /** Run a distilled GitHub operation as the given bearer token. */
  const as = <A, E, R>(token: string, operation: Effect.Effect<A, E, R>) =>
    operation.pipe(
      Effect.provideService(
        Github.Credentials,
        Effect.succeed({
          token: Redacted.make(token),
          apiBaseUrl: config.github.apiUrl,
          userAgent: USER_AGENT,
        }),
      ),
      Effect.provideService(HttpClient.HttpClient, http),
    );

  // The credentials are read here, when a token is minted, never during the
  // Worker's Init: `Registry.ts` binds them explicitly, so plan time never
  // resolves them. Importing the key is a sub-millisecond step next to the
  // two GitHub calls a mint makes, so nothing is kept between mints.
  const appJwt = Effect.gen(function* () {
    const pem = yield* config.github.privateKey;
    const key = yield* pem.pipe(Redacted.value, importPrivateKey);
    const now = Math.floor((yield* Clock.currentTimeMillis) / 1000);
    return yield* signJwt({ iat: now - 60, exp: now + 540, iss: yield* config.github.appId }, key);
  });

  // Failures are not kept: the next call retries the mint.
  const tokens = KVCache.make(
    (repo: string) => `token:${repo}`,
    Schema.String,
    (repo) =>
      Effect.gen(function* () {
        const jwt = yield* appJwt;
        const installation = yield* as(jwt, Apps.getRepoInstallation(split(repo))).pipe(
          Effect.catchTag("NotFound", () => new AppNotInstalled({ repo })),
        );
        const access = yield* as(
          jwt,
          Apps.createInstallationAccessToken({ installation_id: installation.id }),
        );
        const now = yield* Clock.currentTimeMillis;
        return {
          value: access.token,
          ttl: Duration.subtract(
            Duration.millis(Math.max(0, Date.parse(access.expires_at) - now)),
            TOKEN_MARGIN,
          ),
        };
      }),
  );

  /** A GitHub operation run as the App's installation on `repo`. */
  const asInstallation = <A, E, R>(repo: string, operation: Effect.Effect<A, E, R>) =>
    Effect.flatMap(tokens(repo), (token) => as(token, operation));

  return {
    getRun: (repo: string, runId: number) =>
      asInstallation(repo, Actions.getWorkflowRun({ ...split(repo), run_id: runId })),

    /**
     * Artifacts named `name` uploaded to a run so far, including by jobs
     * still in progress.
     */
    listRunArtifacts: (repo: string, runId: number, name: string) =>
      asInstallation(
        repo,
        Actions.listWorkflowRunArtifacts({ ...split(repo), run_id: runId, name, per_page: 100 }),
      ).pipe(Effect.map((page) => page.artifacts)),

    /**
     * Open pull requests against `repo` whose head is `sha` in `headRepo`, the
     * repository the commit was pushed to. Commit-associated PR lookups can
     * return no results for forks, so discover candidates by owner and branch.
     */
    pullRequestsForCommit: (repo: string, headRepo: string, headBranch: string, sha: string) =>
      asInstallation(
        repo,
        Pulls.list({
          ...split(repo),
          head: `${split(headRepo).owner}:${headBranch}`,
          state: "open",
          per_page: 100,
        }),
      ).pipe(
        Effect.map((pulls) =>
          pulls.filter(
            (pr) =>
              pr.head.sha === sha &&
              pr.head.ref === headBranch &&
              pr.head.repo?.full_name === headRepo &&
              pr.base.repo.full_name === repo,
          ),
        ),
      ),

    getPullRequest: (repo: string, number: number) =>
      asInstallation(repo, Pulls.get({ ...split(repo), pull_number: number })),

    /**
     * Publish a completed check run on `headSha`. GitHub shows the newest run
     * per name and App, so re-publishing the same commit simply supersedes it.
     */
    createCheckRun: (
      repo: string,
      input: {
        readonly headSha: string;
        readonly name: string;
        readonly title: string;
        readonly summary: string;
        readonly detailsUrl: string;
      },
    ) =>
      Effect.flatMap(DateTime.now, (now) =>
        asInstallation(
          repo,
          Checks.create({
            ...split(repo),
            name: input.name,
            head_sha: input.headSha,
            status: "completed",
            conclusion: "success",
            completed_at: DateTime.formatIso(now),
            details_url: input.detailsUrl,
            output: { title: input.title, summary: input.summary },
          }),
        ),
      ),

    /**
     * Create or update the comment on `issue` whose body starts with
     * `marker`, looking through the first five pages of comments.
     */
    upsertComment: (repo: string, issue: number, marker: string, body: string) =>
      Effect.gen(function* () {
        const comments = Stream.paginate(1, (page) =>
          asInstallation(
            repo,
            Issues.listComments({ ...split(repo), issue_number: issue, per_page: 100, page }),
          ).pipe(
            Effect.map((comments) => [
              comments,
              comments.length < 100 || page >= 5 ? Option.none() : Option.some(page + 1),
            ]),
          ),
        );
        const existing = yield* comments.pipe(
          Stream.filter((comment) => comment.body?.startsWith(marker) === true),
          Stream.take(1),
          Stream.runCollect,
          Effect.map(Arr.head),
        );
        yield* Option.match(existing, {
          onNone: () =>
            asInstallation(
              repo,
              Issues.createComment({ ...split(repo), issue_number: issue, body }),
            ),
          onSome: (comment) =>
            asInstallation(
              repo,
              Issues.updateComment({ ...split(repo), comment_id: comment.id, body }),
            ),
        });
      }),
  };
});

export class GitHubApp extends Context.Service<GitHubApp, Effect.Success<typeof make>>()(
  "@alchemy.run/pkg/GitHubApp",
) {}

export const GitHubAppLive = Layer.effect(GitHubApp, make);