The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as crypto from "node:crypto"; |
| 2 | import * as Github from "@distilled.cloud/github"; |
| 3 | import * as Actions from "@distilled.cloud/github/actions"; |
| 4 | import * as Apps from "@distilled.cloud/github/apps"; |
| 5 | import * as Checks from "@distilled.cloud/github/checks"; |
| 6 | import * as Issues from "@distilled.cloud/github/issues"; |
| 7 | import * as Pulls from "@distilled.cloud/github/pulls"; |
| 8 | import * as Arr from "effect/Array"; |
| 9 | import * as Clock from "effect/Clock"; |
| 10 | import * as Context from "effect/Context"; |
| 11 | import * as Data from "effect/Data"; |
| 12 | import * as DateTime from "effect/DateTime"; |
| 13 | import * as Duration from "effect/Duration"; |
| 14 | import * as Effect from "effect/Effect"; |
| 15 | import { Base64Url } from "effect/encoding"; |
| 16 | import * as HttpClient from "effect/http/HttpClient"; |
| 17 | import * as Layer from "effect/Layer"; |
| 18 | import * as Option from "effect/Option"; |
| 19 | import * as Redacted from "effect/Redacted"; |
| 20 | import * as Schema from "effect/Schema"; |
| 21 | import * as Stream from "effect/Stream"; |
| 22 | import { COMMENT_MARKER, RegistryConfig } from "./Bindings.ts"; |
| 23 | import * as KVCache from "./KVCache.ts"; |
| 24 | |
| 25 | export class CryptoError extends Data.TaggedError("CryptoError")<{ readonly message: string }> {} |
| 26 | |
| 27 | export class AppNotInstalled extends Data.TaggedError("AppNotInstalled")<{ |
| 28 | readonly repo: string; |
| 29 | }> { |
| 30 | override get message() { |
| 31 | return `The GitHub App is not installed on ${this.repo}`; |
| 32 | } |
| 33 | } |
| 34 | |
| 35 | /** Import an RSA private key PEM (PKCS#1 or PKCS#8) for RS256 signing. */ |
| 36 | export const importPrivateKey = (pem: string) => |
| 37 | Effect.try({ |
| 38 | try: () => crypto.createPrivateKey({ key: pem }), |
| 39 | catch: (cause) => |
| 40 | new CryptoError({ |
| 41 | message: `invalid private key: ${cause instanceof Error ? cause.message : String(cause)}`, |
| 42 | }), |
| 43 | }); |
| 44 | |
| 45 | /** Sign a compact RS256 JWT, used to authenticate as the GitHub App. */ |
| 46 | export const signJwt = (claims: Record<string, unknown>, key: crypto.KeyObject) => |
| 47 | Effect.try({ |
| 48 | try: () => { |
| 49 | const header = Base64Url.encode(JSON.stringify({ alg: "RS256", typ: "JWT" })); |
| 50 | const payload = Base64Url.encode(JSON.stringify(claims)); |
| 51 | const input = `${header}.${payload}`; |
| 52 | const signature = crypto.sign("sha256", Buffer.from(input), key); |
| 53 | return `${input}.${Base64Url.encode(new Uint8Array(signature))}`; |
| 54 | }, |
| 55 | catch: (cause) => |
| 56 | new CryptoError({ |
| 57 | message: `signing failed: ${cause instanceof Error ? cause.message : String(cause)}`, |
| 58 | }), |
| 59 | }); |
| 60 | |
| 61 | /** |
| 62 | * Install commands per package, grouped. A group marked `collapsed` |
| 63 | * renders as a closed `<details>` block so a long list of secondary |
| 64 | * packages stays out of the way. |
| 65 | */ |
| 66 | export const renderInstalls = ( |
| 67 | packages: ReadonlyArray<{ name: string; group: string; url: string }>, |
| 68 | groups: ReadonlyArray<{ name: string; collapsed: boolean }>, |
| 69 | ) => { |
| 70 | const collapsed = new Set(groups.filter((g) => g.collapsed).map((g) => g.name)); |
| 71 | // One code block per package so each command has its own copy button, in |
| 72 | // the order the manifest lists them, which is the order they were given |
| 73 | // to `pkg pack`. Blank lines around the markdown inside `<details>` are |
| 74 | // what make GitHub render it. |
| 75 | return Object.entries(Arr.groupBy(packages, (pkg) => pkg.group)) |
| 76 | .flatMap(([group, members]) => { |
| 77 | const installs = members.flatMap(({ url }) => ["```sh", `pnpm install ${url}`, "```", ""]); |
| 78 | return collapsed.has(group) |
| 79 | ? [ |
| 80 | "<details>", |
| 81 | `<summary><b>${group}</b> (${members.length})</summary>`, |
| 82 | "", |
| 83 | ...installs, |
| 84 | "</details>", |
| 85 | "", |
| 86 | ] |
| 87 | : [`### ${group}`, "", ...installs]; |
| 88 | }) |
| 89 | .join("\n"); |
| 90 | }; |
| 91 | |
| 92 | /** |
| 93 | * GitHub's `<relative-time>` element, rendered as a live relative time in |
| 94 | * comments, with a plain UTC fallback like `Sep 7, 2026 at 2:42 PM UTC`. |
| 95 | */ |
| 96 | const relativeTime = (millis: number) => { |
| 97 | const date = DateTime.makeUnsafe(millis); |
| 98 | const label = DateTime.formatUtc(date, { |
| 99 | locale: "en-US", |
| 100 | dateStyle: "medium", |
| 101 | timeStyle: "short", |
| 102 | }); |
| 103 | return `<relative-time datetime="${DateTime.formatIso(date)}">${label} UTC</relative-time>`; |
| 104 | }; |
| 105 | |
| 106 | export const renderComment = ( |
| 107 | packages: ReadonlyArray<{ name: string; group: string; url: string }>, |
| 108 | groups: ReadonlyArray<{ name: string; collapsed: boolean }>, |
| 109 | times: { readonly publishedAt: number; readonly expiresAt: number }, |
| 110 | ) => |
| 111 | [ |
| 112 | COMMENT_MARKER, |
| 113 | "", |
| 114 | "Install the packages built from this commit:", |
| 115 | "", |
| 116 | renderInstalls(packages, groups), |
| 117 | `Published ${relativeTime(times.publishedAt)}. Expires ${relativeTime(times.expiresAt)}, extended while this pull request is open.`, |
| 118 | ].join("\n"); |
| 119 | |
| 120 | /** Render any GitHub operation failure for logs and error responses. */ |
| 121 | export const describe = (error: { |
| 122 | readonly _tag: string; |
| 123 | readonly message?: string | undefined; |
| 124 | }) => (error.message ? `${error._tag}: ${error.message}` : error._tag); |
| 125 | |
| 126 | const USER_AGENT = "alchemy-pkg"; |
| 127 | |
| 128 | const split = (repo: string) => { |
| 129 | const [owner, name] = repo.split("/"); |
| 130 | return { owner: owner ?? "", repo: name ?? "" }; |
| 131 | }; |
| 132 | |
| 133 | /** |
| 134 | * Installation tokens are refreshed two minutes before GitHub expires them: |
| 135 | * one for clock skew, one for the minute KV's edge cache may keep serving an |
| 136 | * expired entry. |
| 137 | */ |
| 138 | const TOKEN_MARGIN = Duration.minutes(2); |
| 139 | |
| 140 | /** |
| 141 | * The registry's GitHub App: every operation runs as the App's installation |
| 142 | * on the repository in question. Installation tokens live in the KV cache, |
| 143 | * so one mint per repository serves every isolate for about an hour. |
| 144 | */ |
| 145 | const make = Effect.gen(function* () { |
| 146 | const config = yield* RegistryConfig; |
| 147 | const http = yield* HttpClient.HttpClient; |
| 148 | |
| 149 | /** Run a distilled GitHub operation as the given bearer token. */ |
| 150 | const as = <A, E, R>(token: string, operation: Effect.Effect<A, E, R>) => |
| 151 | operation.pipe( |
| 152 | Effect.provideService( |
| 153 | Github.Credentials, |
| 154 | Effect.succeed({ |
| 155 | token: Redacted.make(token), |
| 156 | apiBaseUrl: config.github.apiUrl, |
| 157 | userAgent: USER_AGENT, |
| 158 | }), |
| 159 | ), |
| 160 | Effect.provideService(HttpClient.HttpClient, http), |
| 161 | ); |
| 162 | |
| 163 | // The credentials are read here, when a token is minted, never during the |
| 164 | // Worker's Init: `Registry.ts` binds them explicitly, so plan time never |
| 165 | // resolves them. Importing the key is a sub-millisecond step next to the |
| 166 | // two GitHub calls a mint makes, so nothing is kept between mints. |
| 167 | const appJwt = Effect.gen(function* () { |
| 168 | const pem = yield* config.github.privateKey; |
| 169 | const key = yield* pem.pipe(Redacted.value, importPrivateKey); |
| 170 | const now = Math.floor((yield* Clock.currentTimeMillis) / 1000); |
| 171 | return yield* signJwt({ iat: now - 60, exp: now + 540, iss: yield* config.github.appId }, key); |
| 172 | }); |
| 173 | |
| 174 | // Failures are not kept: the next call retries the mint. |
| 175 | const tokens = KVCache.make( |
| 176 | (repo: string) => `token:${repo}`, |
| 177 | Schema.String, |
| 178 | (repo) => |
| 179 | Effect.gen(function* () { |
| 180 | const jwt = yield* appJwt; |
| 181 | const installation = yield* as(jwt, Apps.getRepoInstallation(split(repo))).pipe( |
| 182 | Effect.catchTag("NotFound", () => new AppNotInstalled({ repo })), |
| 183 | ); |
| 184 | const access = yield* as( |
| 185 | jwt, |
| 186 | Apps.createInstallationAccessToken({ installation_id: installation.id }), |
| 187 | ); |
| 188 | const now = yield* Clock.currentTimeMillis; |
| 189 | return { |
| 190 | value: access.token, |
| 191 | ttl: Duration.subtract( |
| 192 | Duration.millis(Math.max(0, Date.parse(access.expires_at) - now)), |
| 193 | TOKEN_MARGIN, |
| 194 | ), |
| 195 | }; |
| 196 | }), |
| 197 | ); |
| 198 | |
| 199 | /** A GitHub operation run as the App's installation on `repo`. */ |
| 200 | const asInstallation = <A, E, R>(repo: string, operation: Effect.Effect<A, E, R>) => |
| 201 | Effect.flatMap(tokens(repo), (token) => as(token, operation)); |
| 202 | |
| 203 | return { |
| 204 | getRun: (repo: string, runId: number) => |
| 205 | asInstallation(repo, Actions.getWorkflowRun({ ...split(repo), run_id: runId })), |
| 206 | |
| 207 | /** |
| 208 | * Artifacts named `name` uploaded to a run so far, including by jobs |
| 209 | * still in progress. |
| 210 | */ |
| 211 | listRunArtifacts: (repo: string, runId: number, name: string) => |
| 212 | asInstallation( |
| 213 | repo, |
| 214 | Actions.listWorkflowRunArtifacts({ ...split(repo), run_id: runId, name, per_page: 100 }), |
| 215 | ).pipe(Effect.map((page) => page.artifacts)), |
| 216 | |
| 217 | /** |
| 218 | * Open pull requests against `repo` whose head is `sha` in `headRepo`, the |
| 219 | * repository the commit was pushed to. Commit-associated PR lookups can |
| 220 | * return no results for forks, so discover candidates by owner and branch. |
| 221 | */ |
| 222 | pullRequestsForCommit: (repo: string, headRepo: string, headBranch: string, sha: string) => |
| 223 | asInstallation( |
| 224 | repo, |
| 225 | Pulls.list({ |
| 226 | ...split(repo), |
| 227 | head: `${split(headRepo).owner}:${headBranch}`, |
| 228 | state: "open", |
| 229 | per_page: 100, |
| 230 | }), |
| 231 | ).pipe( |
| 232 | Effect.map((pulls) => |
| 233 | pulls.filter( |
| 234 | (pr) => |
| 235 | pr.head.sha === sha && |
| 236 | pr.head.ref === headBranch && |
| 237 | pr.head.repo?.full_name === headRepo && |
| 238 | pr.base.repo.full_name === repo, |
| 239 | ), |
| 240 | ), |
| 241 | ), |
| 242 | |
| 243 | getPullRequest: (repo: string, number: number) => |
| 244 | asInstallation(repo, Pulls.get({ ...split(repo), pull_number: number })), |
| 245 | |
| 246 | /** |
| 247 | * Publish a completed check run on `headSha`. GitHub shows the newest run |
| 248 | * per name and App, so re-publishing the same commit simply supersedes it. |
| 249 | */ |
| 250 | createCheckRun: ( |
| 251 | repo: string, |
| 252 | input: { |
| 253 | readonly headSha: string; |
| 254 | readonly name: string; |
| 255 | readonly title: string; |
| 256 | readonly summary: string; |
| 257 | readonly detailsUrl: string; |
| 258 | }, |
| 259 | ) => |
| 260 | Effect.flatMap(DateTime.now, (now) => |
| 261 | asInstallation( |
| 262 | repo, |
| 263 | Checks.create({ |
| 264 | ...split(repo), |
| 265 | name: input.name, |
| 266 | head_sha: input.headSha, |
| 267 | status: "completed", |
| 268 | conclusion: "success", |
| 269 | completed_at: DateTime.formatIso(now), |
| 270 | details_url: input.detailsUrl, |
| 271 | output: { title: input.title, summary: input.summary }, |
| 272 | }), |
| 273 | ), |
| 274 | ), |
| 275 | |
| 276 | /** |
| 277 | * Create or update the comment on `issue` whose body starts with |
| 278 | * `marker`, looking through the first five pages of comments. |
| 279 | */ |
| 280 | upsertComment: (repo: string, issue: number, marker: string, body: string) => |
| 281 | Effect.gen(function* () { |
| 282 | const comments = Stream.paginate(1, (page) => |
| 283 | asInstallation( |
| 284 | repo, |
| 285 | Issues.listComments({ ...split(repo), issue_number: issue, per_page: 100, page }), |
| 286 | ).pipe( |
| 287 | Effect.map((comments) => [ |
| 288 | comments, |
| 289 | comments.length < 100 || page >= 5 ? Option.none() : Option.some(page + 1), |
| 290 | ]), |
| 291 | ), |
| 292 | ); |
| 293 | const existing = yield* comments.pipe( |
| 294 | Stream.filter((comment) => comment.body?.startsWith(marker) === true), |
| 295 | Stream.take(1), |
| 296 | Stream.runCollect, |
| 297 | Effect.map(Arr.head), |
| 298 | ); |
| 299 | yield* Option.match(existing, { |
| 300 | onNone: () => |
| 301 | asInstallation( |
| 302 | repo, |
| 303 | Issues.createComment({ ...split(repo), issue_number: issue, body }), |
| 304 | ), |
| 305 | onSome: (comment) => |
| 306 | asInstallation( |
| 307 | repo, |
| 308 | Issues.updateComment({ ...split(repo), comment_id: comment.id, body }), |
| 309 | ), |
| 310 | }); |
| 311 | }), |
| 312 | }; |
| 313 | }); |
| 314 | |
| 315 | export class GitHubApp extends Context.Service<GitHubApp, Effect.Success<typeof make>>()( |
| 316 | "@alchemy.run/pkg/GitHubApp", |
| 317 | ) {} |
| 318 | |
| 319 | export const GitHubAppLive = Layer.effect(GitHubApp, make); |