@alchemy.run/pkg 0.0.0-placeholder → 2.0.0-beta.79

package/src/Registry/Bindings.ts

@@ -0,0 +1,134 @@
+import * as Cloudflare from "alchemy/Cloudflare";
+import type * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import type * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+
+/**
+ * What the registry Worker binds: its three resources, the settings binding
+ * that carries the policy into the isolate, and the credential bindings.
+ * Shared by `Registry.ts` (which declares the Worker) and the runtime
+ * modules in this folder.
+ */
+
+/**
+ * Registry policy. The `Type` side is what the Worker runs against
+ * (`Duration`, `ByteSize`); the `Encoded` side is plain JSON, which is how
+ * the policy crosses into the isolate as a Worker binding.
+ */
+export const Policy = Schema.Struct({
+  /**
+   * Repositories allowed to publish, as `owner/name`. A publication may
+   * contain any package; every package gets the commit, short commit,
+   * `branch:` and `pr:` tags of the run that produced it.
+   */
+  repos: Schema.Array(Schema.String),
+  /**
+   * How long a publication lives: from the push for branch publications,
+   * from close or merge for pull request publications. Publishing the same
+   * content again refreshes the clock.
+   */
+  ttl: Schema.DurationFromMillis,
+  /** Upper bound on a single tarball. Absent means unlimited. */
+  maxPackageSize: Schema.optionalKey(Schema.ByteSizeFromNumber),
+});
+export type Policy = typeof Policy.Type;
+
+/**
+ * Everything the Worker needs that is plain data. Encoded into the
+ * {@link SETTINGS_ENV} binding at deploy time and decoded back inside the
+ * isolate, so the deploy-time and runtime views of the registry are the
+ * same value by construction.
+ */
+export const Settings = Schema.Struct({
+  policy: Policy,
+  /**
+   * Hostname to package scope. Requests on an aliased host resolve an
+   * unscoped name under that scope, so `pkg.distilled.cloud/core/<sha>`
+   * serves `@distilled.cloud/core`.
+   */
+  aliases: Schema.Record(Schema.String, Schema.String),
+  /** Cron expression for the expiry sweep. */
+  cron: Schema.String,
+  github: Schema.Struct({
+    apiUrl: Schema.String,
+  }),
+});
+export type Settings = typeof Settings.Type;
+
+/**
+ * Worker props the registry forwards verbatim. `main`, `env`, and `crons`
+ * are owned by the registry itself.
+ */
+export type WorkerOverrides = Omit<
+  Cloudflare.WorkerProps,
+  "main" | "env" | "crons"
+>;
+
+export interface GitHubCredentials {
+  /** The App id. Read from the deploy environment, bound to the Worker. */
+  readonly appId: Config.Config<string>;
+  /** The App's private key PEM. Bound to the Worker as a secret. */
+  readonly privateKey: Config.Config<Redacted.Redacted<string>>;
+}
+
+/**
+ * The resolved registry configuration, provided to the Worker's Init phase.
+ * At plan time it is the value `PkgRegistry(id, options)` built from the
+ * caller's options; inside the isolate it is rebuilt from the Worker's
+ * bindings (see `RegistryConfigFromEnv` in `Registry.ts`). Either way the
+ * handler code sees one shape.
+ */
+export class RegistryConfig extends Context.Service<
+  RegistryConfig,
+  Settings & {
+    readonly worker: WorkerOverrides;
+    readonly github: Settings["github"] & GitHubCredentials;
+  }
+>()("@alchemy.run/pkg/RegistryConfig") {}
+
+/** Worker `json` binding carrying the encoded {@link Settings}. */
+export const SETTINGS_ENV = "PKG_SETTINGS";
+
+/** Worker env var the GitHub App id is bound under. */
+export const APP_ID_ENV = "PKG_GITHUB_APP_ID";
+
+/** Worker secret the GitHub App private key PEM is bound under. */
+export const PRIVATE_KEY_ENV = "PKG_GITHUB_APP_PRIVATE_KEY";
+
+export const DEFAULT_TTL = Duration.weeks(1);
+export const DEFAULT_CRON = "0 * * * *";
+export const DEFAULT_API_URL = "https://api.github.com";
+
+/** Marker that identifies the sticky install comment. */
+export const COMMENT_MARKER = "<!-- pkg-preview-comment -->";
+
+/** Uploaded tarballs no tag points at are deleted once older than this. */
+export const ORPHAN_GRACE = Duration.hours(24);
+
+/** Tags tied to pull requests are re-checked when due within this window. */
+export const SWEEP_LOOKAHEAD = Duration.hours(2);
+
+/** Content-addressed tarballs, keyed `<encoded name>/<sha256>.tgz`. */
+export const Bucket = Cloudflare.R2.Bucket("Bucket", { forceDestroy: true });
+
+export const tarballKey = (name: string, sha256: string) =>
+  `${encodeURIComponent(name)}/${sha256}.tgz`;
+
+// The migrations ship inside this package. `import.meta.url` is a file URL
+// during plan/deploy and absent or opaque inside the isolate, where the
+// resource declaration is only evaluated for its binding.
+const migrations =
+  typeof import.meta.url === "string" && import.meta.url.startsWith("file:")
+    ? decodeURIComponent(new URL("../../migrations", import.meta.url).pathname)
+    : undefined;
+
+/** Publications, tags, and tarball bookkeeping. */
+export const Database = Cloudflare.D1.Database("Database", { migrations });
+
+/**
+ * Resolved runs and installation tokens, shared by every isolate of the
+ * Worker. Everything in it is re-derivable from GitHub; see `KVCache.ts`.
+ */
+export const Cache = Cloudflare.KV.Namespace("Cache");

package/src/Registry/GitHub.ts

@@ -0,0 +1,365 @@
+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 Repos from "@distilled.cloud/github/repos";
+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 * as Encoding from "effect/Encoding";
+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 * as HttpClient from "effect/unstable/http/HttpClient";
+import * as crypto from "node:crypto";
+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}` }),
+  });
+
+/** 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 = Encoding.encodeBase64Url(
+        JSON.stringify({ alg: "RS256", typ: "JWT" }),
+      );
+      const payload = Encoding.encodeBase64Url(JSON.stringify(claims));
+      const input = `${header}.${payload}`;
+      const signature = crypto.sign("sha256", Buffer.from(input), key);
+      return `${input}.${Encoding.encodeBase64Url(new Uint8Array(signature))}`;
+    },
+    catch: (cause) => new CryptoError({ message: `signing failed: ${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* importPrivateKey(Redacted.value(pem));
+    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)),
+
+    /**
+     * Pull requests against `repo` whose head is `sha` in `headRepo`, the
+     * repository the commit was pushed to.
+     */
+    pullRequestsForCommit: (repo: string, headRepo: string, sha: string) =>
+      asInstallation(
+        repo,
+        Repos.listPullRequestsAssociatedWithCommit({
+          ...split(repo),
+          commit_sha: sha,
+          per_page: 100,
+        }),
+      ).pipe(
+        Effect.map((pulls) =>
+          pulls.filter(
+            (pr) =>
+              pr.head.sha === sha &&
+              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);