Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(app): a GitHub App that reviews pull requests, forks included (#209)
anirudhkumar-nanonetsd92f8567f41f
diff --git a/Dockerfile b/Dockerfilenew file mode 100644index 00000000..36987b7b--- /dev/null+++ b/Dockerfile@@ -0,0 +1,54 @@+# The graft GitHub App.+#+# Runs anywhere that takes a container — a VM, Fly, Cloud Run, App Runner. It+# needs git on the PATH (it fetches pull request refs) and nothing else at+# runtime.+#+# Two constraints shape the stages, and both were found the hard way:+#+# - `npm ci` runs this package's `prepare` script, which IS the build. So the+# sources have to be present before the install, not after it — a manifests-+# only copy fails with "The specified path does not exist: 'tsconfig.json'".+# - The runtime cannot reinstall. `npm ci --omit=dev` would run `prepare` again+# without tsc present, and `--ignore-scripts` would skip the native builds+# tree-sitter needs. So the compiled node_modules is carried over from the+# build stage and pruned in place.+FROM node:22-bookworm-slim AS build+WORKDIR /app+# node-gyp needs a real toolchain, and the slim image has none: since the repo+# pinned node-gyp 12, `npm ci` builds tree-sitter's grammars from source and dies+# on "find Python ... could not be run". Build stage only — the runtime image+# below never compiles anything and stays slim.+RUN apt-get update \+ && apt-get install -y --no-install-recommends python3 make g++ \+ && rm -rf /var/lib/apt/lists/*+COPY . .+RUN npm ci++# node 22, not 20: commander@15 declares `node >=22.12`, and running under 20+# left `npm ci` warning EBADENGINE on every build. The runtime base must match+# the build base — the native bindings compiled above are copied, not rebuilt.+FROM node:22-bookworm-slim+# git is a runtime dependency here, not a build one: the App fetches each pull+# request's merge ref.+RUN apt-get update \+ && apt-get install -y --no-install-recommends git ca-certificates \+ && rm -rf /var/lib/apt/lists/*+WORKDIR /app+ENV NODE_ENV=production+COPY package.json package-lock.json ./+COPY --from=build /app/node_modules ./node_modules+COPY --from=build /app/dist ./dist+# devDependencies are dead weight next to a process that clones code written by+# strangers. Pruning keeps the native bindings that were already compiled;+# --ignore-scripts stops `prepare` from trying to rebuild without tsc.+RUN npm prune --omit=dev --ignore-scripts && npm cache clean --force++# Never root: this process handles untrusted source and has no reason to be able+# to write outside its own tree.+USER node+ENV PORT=3000+EXPOSE 3000+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \+ CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"+CMD ["node", "dist/app/main.js"]diff --git a/deploy/apprunner.sh b/deploy/apprunner.shnew file mode 100755index 00000000..c0ce17f3--- /dev/null+++ b/deploy/apprunner.sh@@ -0,0 +1,96 @@+#!/usr/bin/env bash+#+# Build the App, push it to ECR, and create or update its App Runner service.+#+# Idempotent: run it again to deploy a new build. Nothing here is graft-specific+# beyond the names at the top — it is the whole deploy.+#+# Prerequisites: awscli v2, docker, and credentials for the account that owns the+# Route 53 zone. The secrets must exist first (see `secrets` below).+set -euo pipefail++SERVICE="${SERVICE:-graft-app}"+REGION="${AWS_REGION:-us-east-1}"+REPO="${REPO:-$SERVICE}"+PUBLIC_URL="${GRAFT_PUBLIC_URL:?set GRAFT_PUBLIC_URL, e.g. https://graft.nanonets.ai}"+ACCOUNT="$(aws sts get-caller-identity --query Account --output text)"+ECR="${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com"+IMAGE="${ECR}/${REPO}:$(git rev-parse --short HEAD)"++# Names of the secrets this expects in Secrets Manager. Create them once:+#+# aws secretsmanager create-secret --name graft/app-id --secret-string 123456+# aws secretsmanager create-secret --name graft/webhook-secret --secret-string "$(openssl rand -hex 32)"+# aws secretsmanager create-secret --name graft/private-key --secret-string file://graft.private-key.pem+#+# The private key is multi-line PEM; Secrets Manager keeps it verbatim and the+# app also accepts the `\n`-escaped form, so either survives a round trip.+SEC_APP_ID="arn:aws:secretsmanager:${REGION}:${ACCOUNT}:secret:graft/app-id"+SEC_WEBHOOK="arn:aws:secretsmanager:${REGION}:${ACCOUNT}:secret:graft/webhook-secret"+SEC_KEY="arn:aws:secretsmanager:${REGION}:${ACCOUNT}:secret:graft/private-key"++echo "→ ECR repository"+aws ecr describe-repositories --repository-names "$REPO" --region "$REGION" >/dev/null 2>&1 \+ || aws ecr create-repository --repository-name "$REPO" --region "$REGION" >/dev/null++aws ecr get-login-password --region "$REGION" | docker login --username AWS --password-stdin "$ECR" >/dev/null++echo "→ build $IMAGE"+# --platform is not optional from a Mac: App Runner is x86_64 only, and an arm64+# image fails at runtime with an exec-format error rather than at push time.+docker build --platform linux/amd64 -t "$IMAGE" .+docker push "$IMAGE"++ARN="$(aws apprunner list-services --region "$REGION" \+ --query "ServiceSummaryList[?ServiceName=='${SERVICE}'].ServiceArn | [0]" --output text)"++CONFIG=$(cat <<JSON+{+ "ImageRepository": {+ "ImageIdentifier": "${IMAGE}",+ "ImageRepositoryType": "ECR",+ "ImageConfiguration": {+ "Port": "3000",+ "RuntimeEnvironmentVariables": { "GRAFT_PUBLIC_URL": "${PUBLIC_URL}" },+ "RuntimeEnvironmentSecrets": {+ "GRAFT_APP_ID": "${SEC_APP_ID}",+ "GRAFT_WEBHOOK_SECRET": "${SEC_WEBHOOK}",+ "GRAFT_APP_PRIVATE_KEY": "${SEC_KEY}"+ }+ }+ },+ "AutoDeploymentsEnabled": false,+ "AuthenticationConfiguration": {+ "AccessRoleArn": "arn:aws:iam::${ACCOUNT}:role/service-role/AppRunnerECRAccessRole"+ }+}+JSON+)++if [ "$ARN" = "None" ] || [ -z "$ARN" ]; then+ echo "→ create service"+ # MaxSize 1 is load-bearing, not thrift: viewer pages are held in the process,+ # so a second instance would 404 links minted by the first. Removing this cap+ # means moving PageStore to S3 or a database first.+ aws apprunner create-service --region "$REGION" \+ --service-name "$SERVICE" \+ --source-configuration "$CONFIG" \+ --instance-configuration "Cpu=1 vCPU,Memory=2 GB,InstanceRoleArn=arn:aws:iam::${ACCOUNT}:role/${SERVICE}-instance" \+ --health-check-configuration "Protocol=HTTP,Path=/healthz,Interval=10,Timeout=5,HealthyThreshold=1,UnhealthyThreshold=5" \+ --auto-scaling-configuration-arn "$(aws apprunner create-auto-scaling-configuration \+ --region "$REGION" --auto-scaling-configuration-name "${SERVICE}-single" \+ --max-size 1 --min-size 1 --max-concurrency 20 \+ --query AutoScalingConfiguration.AutoScalingConfigurationArn --output text)" \+ --query "Service.ServiceUrl" --output text+else+ echo "→ update service"+ aws apprunner update-service --region "$REGION" --service-arn "$ARN" \+ --source-configuration "$CONFIG" --query "Service.ServiceUrl" --output text+ aws apprunner start-deployment --region "$REGION" --service-arn "$ARN" >/dev/null+fi++echo+echo "Service URL above. Next:"+echo " 1. aws apprunner associate-custom-domain --region $REGION --service-arn <arn> --domain-name ${PUBLIC_URL#https://}"+echo " 2. add the CNAME records it returns to Route 53 (validation + the domain itself)"+echo " 3. set the App's webhook URL to ${PUBLIC_URL}/webhook and tick Active"diff --git a/docs/github-app.md b/docs/github-app.mdnew file mode 100644index 00000000..ab7af864--- /dev/null+++ b/docs/github-app.md@@ -0,0 +1,152 @@+# The graft GitHub App++Posts a blast-radius comment on every pull request, and hosts the interactive+graph behind a signed link.++It exists because of one limit that no amount of workflow YAML gets around: **a+`pull_request` job on a fork gets a read-only token**, so it cannot comment, and+`pull_request_target` cannot check out fork code without opting into running it.+An App's installation token belongs to the *base* repository, so a fork PR is+ordinary work. Two things follow for free: the page is served by the App (a+private repo never needs a public `gh-pages`), and installing takes one click+instead of a workflow file per repo.++## What it does per pull request++1. Verifies the webhook signature, queues the job, answers `202` — GitHub gives+ up on a delivery after ten seconds and a review takes longer.+2. Fetches `refs/pull/<n>/merge` and the base branch, shallow.+3. Builds the structural graph, computes the radius, renders the comment.+4. Stores the viewer page and links it with a signed URL.+5. Edits its existing comment rather than adding one per push.++Work is superseded per pull request: five pushes in a minute produce one review,+not five, because the first four comments would be overwritten anyway.++## Setting it up++### 1. Register the App++<https://github.com/settings/apps/new> (or your org's settings → Developer+settings → GitHub Apps → New).++| Field | Value |+| --- | --- |+| Webhook URL | `https://<your-host>/webhook` |+| Webhook secret | a long random string — keep it, it is `GRAFT_WEBHOOK_SECRET` |+| Repository permissions | **Contents: Read-only**, **Pull requests: Read & write** |+| Subscribe to events | **Pull request** |+| Where can this be installed | your choice |++Nothing else. Contents-read is what clones the code; pull-requests-write is what+posts the comment. It never needs Actions, Checks, Administration or write+access to code.++Then **Generate a private key** — the download is the only copy — and note the+**App ID**.++### 2. Run it++```bash+docker build -t graft-app .+docker run -p 3000:3000 \+ -e GRAFT_APP_ID=123456 \+ -e GRAFT_APP_PRIVATE_KEY="$(cat graft.private-key.pem)" \+ -e GRAFT_WEBHOOK_SECRET=... \+ -e GRAFT_PUBLIC_URL=https://graft.example.com \+ graft-app+```++The image needs `git` and nothing else at runtime, runs as non-root, and answers+`/healthz` with its queue depth. Any container host works — Fly, Cloud Run, ECS,+a VM. `GRAFT_PUBLIC_URL` must be the origin GitHub and your reviewers can reach,+because it is what the comment's link is built from.++The process refuses to start if any of those four are missing: a server that+boots without a webhook secret looks healthy and silently rejects every delivery.++### 3. Install it on a repository++App settings → Install App → pick the repos. **Installing requires admin on the+repository** (or org-owner for an org-wide install) — the one thing an App does+not get you around.++## Security++The App clones code written by strangers on every fork PR while holding a token+for the base repository, so:++- **Nothing from the repo is executed** — no `npm install`, no build step, no+ postinstall. The graph comes from tree-sitter reading source text.+- **Git is told not to run anything either**: `core.hooksPath=/dev/null`,+ `GIT_TERMINAL_PROMPT=0`, `GIT_CONFIG_NOSYSTEM=1`, no submodule recursion.+- **The token never lands in the checkout.** It is passed per-invocation as an+ auth header, not baked into a remote URL that `.git/config` and the reflog+ would keep. It is redacted out of error text before anything is logged.+- **Pages are capabilities, not public URLs.** `/p/<id>?t=<hmac>` — an unknown+ page and a bad token are both `404`, so the endpoint cannot be used to+ discover which pull requests exist. Links expire with the page they point at.++## What is not built yet++- **Naming.** Areas fall back to their hub symbol. `--name`'s one cached LLM call+ is not wired in, and sending a private repo's source to a model should be an+ explicit per-installation opt-in, not a default.+- **Persistence.** Pages live in memory, so a deploy drops them; the next push to+ a PR rebuilds its page. A shared store is the fix when there is more than one+ instance.+- **The evidence quotes** in the comment's collapsed list arrive when #180 lands+ (`markdownReport(report, { root })` — additive, one line here).++## Deploying to AWS App Runner++`deploy/apprunner.sh` is the whole deploy: build for x86_64, push to ECR, create+or update the service. Run it again for every new build.++### Once, before the first deploy++```bash+aws sso login # or however this account authenticates++# 1. Secrets. The private key is multi-line PEM and survives verbatim.+aws secretsmanager create-secret --name graft/app-id --secret-string 123456+aws secretsmanager create-secret --name graft/webhook-secret --secret-string "$(openssl rand -hex 32)"+aws secretsmanager create-secret --name graft/private-key --secret-string file://graft.private-key.pem++# 2. The role App Runner uses to PULL the image from ECR.+aws iam create-role --role-name AppRunnerECRAccessRole --path /service-role/ \+ --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"build.apprunner.amazonaws.com"},"Action":"sts:AssumeRole"}]}'+aws iam attach-role-policy --role-name AppRunnerECRAccessRole \+ --policy-arn arn:aws:iam::aws:policy/service-role/AWSAppRunnerServicePolicyForECRAccess++# 3. The role the RUNNING container uses to read those secrets.+aws iam create-role --role-name graft-app-instance \+ --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"tasks.apprunner.amazonaws.com"},"Action":"sts:AssumeRole"}]}'+aws iam put-role-policy --role-name graft-app-instance --policy-name read-graft-secrets \+ --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"secretsmanager:GetSecretValue","Resource":"arn:aws:secretsmanager:*:*:secret:graft/*"}]}'+```++Two roles, because App Runner separates them: one is assumed by the *build*+side to pull the image, the other by the *running* task to read configuration.+Giving the second one only `graft/*` keeps this service away from every other+secret in the account.++### Every deploy++```bash+GRAFT_PUBLIC_URL=https://graft.nanonets.ai ./deploy/apprunner.sh+```++Then, once: `associate-custom-domain`, add the CNAMEs it prints to Route 53+(one validates the certificate, one points the domain at the service), and set+the App's webhook URL to `https://graft.nanonets.ai/webhook`.++### Two things the config is deliberate about++- **`--platform linux/amd64`.** App Runner is x86_64 only; an image built on an+ Apple Silicon Mac pushes fine and then fails at runtime with an exec-format+ error, which reads like a broken entrypoint.+- **One instance, pinned.** Viewer pages live in the process, so a second+ instance would 404 links minted by the first. Raising `--max-size` means+ moving `PageStore` to S3 or a database first — the cap is correctness, not+ cost control.diff --git a/src/app/checkout.ts b/src/app/checkout.tsnew file mode 100644index 00000000..33cbcee0--- /dev/null+++ b/src/app/checkout.ts@@ -0,0 +1,128 @@+/**+ * Getting a pull request's code onto disk without running any of it.+ *+ * On a fork PR every byte here was written by a stranger, and this service holds+ * an installation token for the base repository. So the rules are absolute:+ *+ * - **Nothing is executed.** No `npm install`, no build, no hooks. The graph is+ * produced by tree-sitter reading source text, which runs none of it.+ * - **Git is told not to run things either.** A repository can carry hooks, and+ * `core.hooksPath` is a per-repo config a clone would otherwise honour; both+ * are disabled explicitly rather than assumed absent.+ * - **The token never lands in the repo.** It is passed per-invocation through+ * an http header config, not baked into a remote URL that `git remote -v`,+ * the reflog and any submodule would carry.+ * - **Bounded.** A hostile or merely enormous repository must not hold a worker+ * forever: every git call has a timeout, and the fetch is shallow.+ */+import { spawnSync } from "node:child_process";+import { mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++/** Enough history for a merge base against the pull request's base branch. */+const FETCH_DEPTH = 50;+const GIT_TIMEOUT_MS = 120_000;++export interface CheckoutRequest {+ owner: string;+ repo: string;+ number: number;+ baseRef: string;+ token: string;+ api?: string;+}++export interface Checkout {+ /** Working tree at the pull request's merge commit. */+ dir: string;+ /** What `blast --base` should diff against. */+ base: string;+ /** Removes the tree. Always call it — the token's clone is not something to+ * leave in /tmp. */+ cleanup: () => void;+}++/** A git invocation with the dangerous parts of the environment removed. */+function git(dir: string, args: string[], token?: string): { ok: boolean; err: string } {+ const auth = token+ ? [+ "-c",+ // Basic auth with the token as the password, per GitHub's own guidance for+ // installation tokens. Passed as an argument to THIS call so it is never+ // written into .git/config.+ `http.extraheader=Authorization: Basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`,+ ]+ : [];+ const res = spawnSync(+ "git",+ ["-c", "core.hooksPath=/dev/null", "-c", "protocol.version=2", ...auth, ...args],+ {+ cwd: dir,+ encoding: "utf8",+ timeout: GIT_TIMEOUT_MS,+ stdio: ["ignore", "pipe", "pipe"],+ env: {+ ...process.env,+ // No credential prompts, no system config, no repo-supplied helpers.+ GIT_TERMINAL_PROMPT: "0",+ GIT_CONFIG_NOSYSTEM: "1",+ GIT_ASKPASS: "",+ HOME: dir,+ },+ },+ );+ return { ok: res.status === 0, err: `${res.stderr ?? ""}${res.error ? ` ${res.error.message}` : ""}`.trim() };+}++/**+ * Fetch the PR's merge ref and its base, shallow.+ *+ * `refs/pull/N/merge` is GitHub's own merge of the PR into its base — the same+ * thing the checks see, and the right thing to review: it is what will land, not+ * what the contributor's branch says in isolation.+ */+export function checkoutPullRequest(req: CheckoutRequest): Checkout {+ const host = (req.api ?? "https://github.com").replace(/\/$/, "");+ const dir = mkdtempSync(join(tmpdir(), `graft-app-${req.owner}-${req.repo}-`));+ const cleanup = (): void => rmSync(dir, { recursive: true, force: true });++ const steps: Array<[string, string[]]> = [+ ["init", ["init", "--quiet", "-b", "__graft_base"]],+ ["remote", ["remote", "add", "origin", `${host}/${req.owner}/${req.repo}.git`]],+ // Both refs in one fetch: the merge ref to review, the base to diff against.+ [+ "fetch",+ [+ "fetch",+ "--quiet",+ `--depth=${FETCH_DEPTH}`,+ "--no-recurse-submodules",+ "origin",+ `+refs/pull/${req.number}/merge:refs/graft/merge`,+ `+refs/heads/${req.baseRef}:refs/graft/base`,+ ],+ ],+ ["checkout", ["checkout", "--quiet", "--detach", "refs/graft/merge"]],+ ];++ for (const [name, args] of steps) {+ const { ok, err } = git(dir, args, name === "fetch" ? req.token : undefined);+ if (!ok) {+ cleanup();+ // A merge ref is absent while GitHub is still computing mergeability, and+ // present-but-stale right after a push — worth saying which step failed so+ // that case is distinguishable from a permissions problem.+ throw new Error(`checkout ${req.owner}/${req.repo}#${req.number} failed at ${name}: ${redact(err, req.token)}`);+ }+ }++ return { dir, base: "refs/graft/base", cleanup };+}++/** Never let a token reach a log line, even inside git's own error text. */+export function redact(text: string, token: string): string {+ if (!token) return text;+ const encoded = Buffer.from(`x-access-token:${token}`).toString("base64");+ return text.split(token).join("[token]").split(encoded).join("[token]");+}diff --git a/src/app/events.ts b/src/app/events.tsnew file mode 100644index 00000000..7d641a9e--- /dev/null+++ b/src/app/events.ts@@ -0,0 +1,89 @@+/**+ * What arrived, and whether it is worth work.+ *+ * A busy installation delivers a lot of noise — labels, assignments, reviews —+ * and every accepted delivery costs a clone and a parse. Narrowing happens here,+ * once, so the queue only ever holds jobs that will produce a comment.+ */++/** The subset of a `pull_request` delivery this App reads. */+export interface ReviewJob {+ installationId: number;+ owner: string;+ repo: string;+ /** Base repository's full name, which is where the comment goes — a fork PR+ * carries a different head repo, and posting there would be posting on the+ * contributor's copy. */+ number: number;+ baseRef: string;+ headSha: string;+ /** True when the head branch lives in a fork: the PR's code is not ours. */+ fromFork: boolean;+}++interface RawPullRequest {+ action?: string;+ number?: number;+ installation?: { id?: number };+ repository?: { name?: string; owner?: { login?: string }; full_name?: string };+ pull_request?: {+ number?: number;+ draft?: boolean;+ state?: string;+ base?: { ref?: string; repo?: { full_name?: string } };+ head?: { sha?: string; repo?: { full_name?: string } };+ };+}++/** Actions that change the diff. `edited` (a retitled PR) and `labeled` do not. */+const ACTIONS = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);++/**+ * A delivery to act on, or null with the reason it was skipped.+ *+ * Draft pull requests are skipped deliberately: a draft is a work in progress and+ * a bot commenting on every push to one is the fastest way to be uninstalled.+ * `ready_for_review` is in the accepted set so the comment appears the moment the+ * author asks for eyes.+ */+export function reviewJobFor(event: string, payload: unknown): { job: ReviewJob } | { skip: string } {+ if (event === "ping") return { skip: "ping" };+ if (event !== "pull_request") return { skip: `event ${event}` };++ const p = payload as RawPullRequest;+ const action = p.action ?? "";+ if (!ACTIONS.has(action)) return { skip: `action ${action}` };++ const pr = p.pull_request;+ const installationId = p.installation?.id;+ const owner = p.repository?.owner?.login;+ const repo = p.repository?.name;+ const number = pr?.number ?? p.number;+ const baseRef = pr?.base?.ref;+ const headSha = pr?.head?.sha;++ if (!installationId || !owner || !repo || !number || !baseRef || !headSha) {+ return { skip: "payload missing installation, repository or pull request fields" };+ }+ if (pr?.draft === true && action !== "ready_for_review") return { skip: "draft" };+ if (pr?.state === "closed") return { skip: "closed" };++ const base = pr?.base?.repo?.full_name;+ const head = pr?.head?.repo?.full_name;+ return {+ job: {+ installationId,+ owner,+ repo,+ number,+ baseRef,+ headSha,+ // A missing head repo means a deleted fork — treat it as one, since it is+ // certainly not ours.+ fromFork: head !== base,+ },+ };+}++/** Collapse queued work per pull request: only the newest push is worth reviewing. */+export const jobKey = (j: ReviewJob): string => `${j.owner}/${j.repo}#${j.number}`;diff --git a/src/app/identity.ts b/src/app/identity.tsnew file mode 100644index 00000000..06de2968--- /dev/null+++ b/src/app/identity.ts@@ -0,0 +1,122 @@+/**+ * Who the App is, to GitHub.+ *+ * A GitHub App authenticates twice over: it signs a short JWT with its private+ * key to prove it is the App, then trades that for an *installation* token scoped+ * to one repository owner. The installation token is what matters here — it is+ * the reason this exists at all. A workflow on a fork's pull request gets a+ * read-only token and cannot comment; an App's installation token belongs to the+ * base repository, so a fork PR is no different from any other.+ *+ * `node:crypto` signs the JWT, so there is no dependency to audit for something+ * that handles a private key.+ */+import { createHmac, createSign, timingSafeEqual } from "node:crypto";++/** GitHub rejects a JWT older than 60s or more than 10 minutes in the future. */+const JWT_TTL_S = 540; // 9 minutes, inside the limit with room for clock skew+/** Renew this long before expiry rather than racing it. */+const RENEW_MARGIN_MS = 60_000;++const b64url = (b: Buffer | string): string =>+ Buffer.from(b).toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");++export interface AppCredentials {+ appId: string;+ /** PEM, as GitHub hands it over. */+ privateKey: string;+}++/**+ * A signed App JWT.+ *+ * `iat` is backdated a minute: GitHub compares against ITS clock, and a server+ * running even slightly fast has its tokens rejected as "issued in the future" —+ * a failure that looks like a bad key and is not.+ */+export function appJwt(creds: AppCredentials, nowMs: number): string {+ const iat = Math.floor(nowMs / 1000) - 60;+ const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));+ const payload = b64url(JSON.stringify({ iat, exp: iat + JWT_TTL_S, iss: creds.appId }));+ const signer = createSign("RSA-SHA256");+ signer.update(`${header}.${payload}`);+ return `${header}.${payload}.${b64url(signer.sign(creds.privateKey))}`;+}++export interface TokenResponse {+ token: string;+ expires_at: string;+}++/** Minimal shape of `fetch`, so tests need no network and no mocking library. */+export type Fetch = (url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }) => Promise<{+ ok: boolean;+ status: number;+ text: () => Promise<string>;+}>;++interface CacheEntry {+ token: string;+ expiresMs: number;+}++/**+ * Installation tokens, fetched once and reused until they are nearly expired.+ *+ * Tokens last an hour and a busy repository can fire a dozen webhooks a minute;+ * without the cache every one of them spends a round trip and a signature.+ */+export class InstallationTokens {+ private readonly cache = new Map<number, CacheEntry>();++ constructor(+ private readonly creds: AppCredentials,+ private readonly fetchImpl: Fetch,+ private readonly now: () => number = Date.now,+ private readonly api = "https://api.github.com",+ ) {}++ async get(installationId: number): Promise<string> {+ const hit = this.cache.get(installationId);+ if (hit && hit.expiresMs - RENEW_MARGIN_MS > this.now()) return hit.token;++ const res = await this.fetchImpl(`${this.api}/app/installations/${installationId}/access_tokens`, {+ method: "POST",+ headers: {+ authorization: `Bearer ${appJwt(this.creds, this.now())}`,+ accept: "application/vnd.github+json",+ "user-agent": "graft-app",+ },+ });+ const body = await res.text();+ if (!res.ok) {+ // The body carries GitHub's reason ("integration not found", a key that does+ // not match the app id); losing it turns every setup mistake into "401".+ throw new Error(`installation token for ${installationId} failed: ${res.status} ${body.slice(0, 200)}`);+ }+ const parsed = JSON.parse(body) as TokenResponse;+ this.cache.set(installationId, { token: parsed.token, expiresMs: Date.parse(parsed.expires_at) });+ return parsed.token;+ }++ /** Drop a token GitHub has rejected, so the next call fetches a fresh one. */+ invalidate(installationId: number): void {+ this.cache.delete(installationId);+ }+}++/**+ * Is this delivery really from GitHub?+ *+ * The webhook endpoint is public, and everything downstream — cloning a repo,+ * posting as the App — happens on its say-so. Compared in constant time because+ * a byte-at-a-time comparison leaks the expected digest to anyone willing to+ * measure, and forging a signature is a total compromise of the endpoint.+ */+export function verifySignature(secret: string, body: string, header: string | undefined): boolean {+ if (!header) return false;+ const expected = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;+ const a = Buffer.from(expected);+ const b = Buffer.from(header);+ return a.length === b.length && timingSafeEqual(a, b);+}diff --git a/src/app/main.ts b/src/app/main.tsnew file mode 100644index 00000000..c29998be--- /dev/null+++ b/src/app/main.ts@@ -0,0 +1,59 @@+/**+ * Entry point: read the environment, refuse to start half-configured, listen.+ *+ * Every misconfiguration is fatal at boot rather than at the first webhook. A+ * server that starts without a webhook secret looks healthy and silently rejects+ * every delivery; one that starts without a private key looks healthy and fails+ * every review. Both are worth a loud death on line one.+ */+import { createApp } from "./server.js";++function required(name: string): string {+ const value = process.env[name];+ if (!value) {+ console.error(`✗ ${name} is required`);+ process.exit(1);+ }+ return value;+}++/**+ * GitHub hands the private key over as a PEM file. Env vars cannot hold newlines+ * comfortably, so both spellings are accepted: the raw PEM, or one with `\n`+ * escaped — the shape you get from pasting a key into a hosting provider's UI.+ */+function privateKey(): string {+ const raw = required("GRAFT_APP_PRIVATE_KEY");+ const pem = raw.includes("\\n") ? raw.replace(/\\n/g, "\n") : raw;+ if (!pem.includes("BEGIN") || !pem.includes("PRIVATE KEY")) {+ console.error("✗ GRAFT_APP_PRIVATE_KEY does not look like a PEM private key");+ process.exit(1);+ }+ return pem;+}++const port = Number(process.env.PORT ?? 3000);+const { server, queue } = createApp({+ appId: required("GRAFT_APP_ID"),+ privateKey: privateKey(),+ webhookSecret: required("GRAFT_WEBHOOK_SECRET"),+ publicUrl: required("GRAFT_PUBLIC_URL"),+ port,+ concurrency: Number(process.env.GRAFT_CONCURRENCY ?? 2),+});++/**+ * Finish what is in flight before dying.+ *+ * A container gets a TERM and a grace period on every deploy. Dropping a review+ * mid-clone leaves a stale comment on a pull request and no retry, because the+ * delivery was acknowledged long ago.+ */+for (const signal of ["SIGTERM", "SIGINT"] as const) {+ process.on(signal, () => {+ console.log(`${signal}: draining ${queue.size} job(s)`);+ server.close();+ void queue.drain().then(() => process.exit(0));+ setTimeout(() => process.exit(1), 25_000).unref();+ });+}diff --git a/src/app/pages.ts b/src/app/pages.tsnew file mode 100644index 00000000..8e2eda46--- /dev/null+++ b/src/app/pages.ts@@ -0,0 +1,103 @@+/**+ * Where a reviewed pull request's page lives.+ *+ * This is the part GitHub Pages could not do. A private repository's graph must+ * not be readable by anyone who guesses a URL, and the Actions route had only two+ * options: publish to a public branch, or hand the reader a zip. So the page is+ * held here and linked with a signed, expiring URL.+ *+ * The signature is the whole access-control story, deliberately: it is a+ * capability, not a login. Anyone with the link can read that one page until it+ * expires, which is the same property a GitHub artifact link has, and the link+ * only ever appears in a comment on the pull request it describes.+ */+import { createHmac, timingSafeEqual } from "node:crypto";++/** Long enough to review a PR at leisure, short enough that a leaked link dies. */+const DEFAULT_TTL_MS = 14 * 24 * 60 * 60 * 1000;+/** A page is ~50 kB; a few hundred of them is nothing, and eviction is by age. */+const DEFAULT_MAX_PAGES = 500;++export interface StoredPage {+ html: string;+ storedMs: number;+}++export interface PageStoreOptions {+ secret: string;+ ttlMs?: number;+ maxPages?: number;+ now?: () => number;+}++export class PageStore {+ private readonly pages = new Map<string, StoredPage>();+ private readonly secret: string;+ private readonly ttlMs: number;+ private readonly maxPages: number;+ private readonly now: () => number;++ constructor(opts: PageStoreOptions) {+ this.secret = opts.secret;+ this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;+ this.maxPages = opts.maxPages ?? DEFAULT_MAX_PAGES;+ this.now = opts.now ?? Date.now;+ }++ /** `owner/repo#number` → a path segment safe to put in a URL. */+ static idFor(owner: string, repo: string, number: number): string {+ return `${owner}__${repo}__${number}`.replace(/[^A-Za-z0-9_.-]/g, "-");+ }++ /** Store (replacing any previous page for the same PR) and return `id` + `token`. */+ put(owner: string, repo: string, number: number, html: string): { id: string; token: string } {+ const id = PageStore.idFor(owner, repo, number);+ this.pages.set(id, { html, storedMs: this.now() });+ this.evict();+ return { id, token: this.sign(id) };+ }++ /**+ * The page, if the token is valid and it has not expired.+ *+ * Expiry is checked against the STORED time rather than encoded in the token,+ * so a link cannot outlive the data it points at — and re-reviewing a PR+ * refreshes both together.+ */+ get(id: string, token: string | undefined): string | null {+ const page = this.pages.get(id);+ if (!page || !token || !this.valid(id, token)) return null;+ if (this.now() - page.storedMs > this.ttlMs) {+ this.pages.delete(id);+ return null;+ }+ return page.html;+ }++ get size(): number {+ return this.pages.size;+ }++ private sign(id: string): string {+ return createHmac("sha256", this.secret).update(id).digest("hex").slice(0, 32);+ }++ private valid(id: string, token: string): boolean {+ const a = Buffer.from(this.sign(id));+ const b = Buffer.from(token);+ // Length first: timingSafeEqual throws on a mismatch, which would turn a+ // truncated token into a 500 instead of a 404.+ return a.length === b.length && timingSafeEqual(a, b);+ }++ /** Oldest out first, plus anything past its TTL. */+ private evict(): void {+ const cutoff = this.now() - this.ttlMs;+ for (const [id, page] of this.pages) if (page.storedMs < cutoff) this.pages.delete(id);+ while (this.pages.size > this.maxPages) {+ const oldest = this.pages.keys().next();+ if (oldest.done) break;+ this.pages.delete(oldest.value);+ }+ }+}diff --git a/src/app/queue.ts b/src/app/queue.tsnew file mode 100644index 00000000..f9417181--- /dev/null+++ b/src/app/queue.ts@@ -0,0 +1,78 @@+/**+ * The work queue.+ *+ * A webhook must be answered in seconds, and a review takes tens of them, so the+ * HTTP handler's only job is to enqueue. Two properties matter and neither comes+ * free from a bare array:+ *+ * - **Superseding.** Five pushes to one pull request in a minute is normal, and+ * reviewing the first four is wasted work whose comments are immediately+ * overwritten. A queued job for the same PR is replaced, not appended.+ * - **A ceiling.** One repository must not be able to starve every other+ * installation, so a fixed number of workers drain the queue.+ */++export interface QueueOptions {+ concurrency?: number;+ /** Called for every failure: a job that throws must not take the process down,+ * and a silent catch would hide a broken installation forever. */+ onError?: (err: unknown, key: string) => void;+}++export class WorkQueue<T> {+ private readonly pending = new Map<string, T>();+ private readonly running = new Set<string>();+ private readonly concurrency: number;+ private readonly onError: (err: unknown, key: string) => void;+ private idle: Array<() => void> = [];++ constructor(+ private readonly run: (item: T) => Promise<void>,+ opts: QueueOptions = {},+ ) {+ this.concurrency = Math.max(1, opts.concurrency ?? 2);+ this.onError = opts.onError ?? (() => {});+ }++ /**+ * Queue work under `key`, replacing anything queued under it and not yet started.+ *+ * A job already RUNNING is left alone: cancelling mid-clone buys nothing, and+ * the newer job simply runs after it and overwrites the comment.+ */+ push(key: string, item: T): void {+ this.pending.set(key, item);+ this.pump();+ }++ get size(): number {+ return this.pending.size + this.running.size;+ }++ /** Resolves when nothing is queued or running — for tests and for shutdown. */+ async drain(): Promise<void> {+ if (this.size === 0) return;+ await new Promise<void>((resolve) => this.idle.push(resolve));+ }++ private pump(): void {+ while (this.running.size < this.concurrency) {+ const next = this.pending.entries().next();+ if (next.done) break;+ const [key, item] = next.value;+ this.pending.delete(key);+ this.running.add(key);+ void this.run(item)+ .catch((err) => this.onError(err, key))+ .finally(() => {+ this.running.delete(key);+ this.pump();+ if (this.size === 0) {+ const waiting = this.idle;+ this.idle = [];+ for (const resolve of waiting) resolve();+ }+ });+ }+ }+}diff --git a/src/app/review.ts b/src/app/review.tsnew file mode 100644index 00000000..ea3c7fb3--- /dev/null+++ b/src/app/review.ts@@ -0,0 +1,158 @@+/**+ * One pull request, reviewed.+ *+ * Checkout → graph → blast radius → comment, with the page handed to whatever+ * the caller uses to publish it. Everything runs in-process against the same+ * functions the CLI calls, which is what keeps the App's comment and `graft+ * blast` on a laptop from drifting apart — and means the PR's own package.json+ * is never installed or run.+ */+import { blastRadiusIn } from "../blast/blast.js";+import { changedFiles } from "../blast/diff.js";+import { markdownReport } from "../blast/render.js";+import { blastVizGraph } from "../blast/viz.js";+import { buildGraph } from "../graph/build.js";+import { contextDirFor } from "../context/node-file.js";+import { loadGraphCached } from "../graph/load.js";+import { checkoutPullRequest, redact } from "./checkout.js";+import type { ReviewJob } from "./events.js";+import type { Fetch } from "./identity.js";++/** Hidden marker: how the App finds the comment it owns, on every later push. */+export const MARKER = "<!-- graft-blast-radius -->";++const DEPTH = 2;++export interface ReviewDeps {+ token: (installationId: number) => Promise<string>;+ fetch: Fetch;+ api?: string;+ /** Somewhere to put the viewer page; returns the URL to link. Optional: the+ * comment is useful on its own, and a page that fails to publish must not cost+ * the review. */+ publish?: (job: ReviewJob, html: string) => Promise<string | null>;+ log?: (msg: string) => void;+}++export interface ReviewResult {+ /** `null` when the diff had nothing indexed to say. */+ commentUrl: string | null;+ areas: number;+ affected: number;+ viewerUrl: string | null;+}++export async function reviewPullRequest(job: ReviewJob, deps: ReviewDeps): Promise<ReviewResult> {+ const log = deps.log ?? (() => {});+ const token = await deps.token(job.installationId);+ const checkout = checkoutPullRequest({ owner: job.owner, repo: job.repo, number: job.number, baseRef: job.baseRef, token });++ try {+ log(`${job.owner}/${job.repo}#${job.number}: building`);+ await buildGraph(checkout.dir);++ const contextDir = contextDirFor(checkout.dir);+ const graph = loadGraphCached(contextDir);+ if (!graph) throw new Error("build produced no graph");++ const diff = changedFiles(checkout.dir, checkout.base);+ if (!diff) throw new Error(`no diff against ${job.baseRef}`);++ const report = blastRadiusIn(graph, contextDir, diff.files, diff.basis, DEPTH);+ // NOTE: once #180 lands, pass `{ root: checkout.dir }` so the collapsed list+ // quotes the reaching line here too. It is additive, and the App works without it.+ let body = `${MARKER}\n${markdownReport(report)}`;++ let viewerUrl: string | null = null;+ if (deps.publish) {+ const html = await exportPage(report, contextDir, checkout.dir, job);+ viewerUrl = html ? await deps.publish(job, html) : null;+ if (viewerUrl) {+ body += `\n[**Open the interactive graph →**](${viewerUrl}) — click an area to see the code that changed, and the line that reaches it.\n`;+ }+ }++ const commentUrl = await upsertComment(job, body, token, deps);+ return { commentUrl, areas: report.areas.length, affected: report.modules.length, viewerUrl };+ } catch (err) {+ // The token is in git's error text on a permissions failure, and this string+ // is about to be logged.+ throw new Error(redact(err instanceof Error ? err.message : String(err), token));+ } finally {+ checkout.cleanup();+ }+}++/** The self-contained viewer page for this radius, or null if it cannot be made. */+async function exportPage(+ report: ReturnType<typeof blastRadiusIn>,+ contextDir: string,+ root: string,+ job: ReviewJob,+): Promise<string | null> {+ const { exportViz } = await import("../viz/export.js");+ const { fileURLToPath } = await import("node:url");+ const { mkdtempSync, readFileSync, rmSync } = await import("node:fs");+ const { tmpdir } = await import("node:os");+ const { join } = await import("node:path");++ const out = mkdtempSync(join(tmpdir(), "graft-page-"));+ try {+ const res = exportViz({+ contextDir,+ viewerDir: fileURLToPath(new URL("../viewer/", import.meta.url)),+ outDir: out,+ repoName: job.repo,+ subtitle: `PR #${job.number}`,+ contextGraph: blastVizGraph(report, { root }),+ // Context alone: the other tabs are about the repository, and this page is+ // about one pull request.+ tabs: ["context"],+ });+ return readFileSync(res.file, "utf8");+ } catch {+ return null;+ } finally {+ rmSync(out, { recursive: true, force: true });+ }+}++/**+ * One comment per pull request, edited in place.+ *+ * A new comment on every push turns a busy PR into a wall of stale diagrams, so+ * the marker is searched for first. Listing is paginated because the comment the+ * App owns is not necessarily on page one of a long discussion.+ */+async function upsertComment(job: ReviewJob, body: string, token: string, deps: ReviewDeps): Promise<string | null> {+ const api = (deps.api ?? "https://api.github.com").replace(/\/$/, "");+ const base = `${api}/repos/${job.owner}/${job.repo}/issues/${job.number}/comments`;+ const headers = {+ authorization: `token ${token}`,+ accept: "application/vnd.github+json",+ "content-type": "application/json",+ "user-agent": "graft-app",+ };++ const existing = await findComment(base, headers, deps.fetch);+ const res = await deps.fetch(existing ? `${api}/repos/${job.owner}/${job.repo}/issues/comments/${existing}` : base, {+ method: existing ? "PATCH" : "POST",+ headers,+ body: JSON.stringify({ body }),+ });+ const text = await res.text();+ if (!res.ok) throw new Error(`comment failed: ${res.status} ${text.slice(0, 200)}`);+ return (JSON.parse(text) as { html_url?: string }).html_url ?? null;+}++async function findComment(base: string, headers: Record<string, string>, fetchImpl: Fetch): Promise<number | null> {+ for (let page = 1; page <= 10; page += 1) {+ const res = await fetchImpl(`${base}?per_page=100&page=${page}`, { headers });+ if (!res.ok) return null;+ const items = JSON.parse(await res.text()) as Array<{ id: number; body?: string }>;+ const mine = items.find((c) => c.body?.startsWith(MARKER));+ if (mine) return mine.id;+ if (items.length < 100) return null;+ }+ return null;+}diff --git a/src/app/server.ts b/src/app/server.tsnew file mode 100644index 00000000..db487b76--- /dev/null+++ b/src/app/server.ts@@ -0,0 +1,148 @@+/**+ * The HTTP surface: one webhook in, one page out.+ *+ * Deliberately `node:http` and nothing else. This process handles a private key,+ * a webhook secret and other people's source code, so every dependency is one+ * more thing to trust; the whole server is a hundred lines and needs no+ * framework.+ *+ * GitHub retries a delivery it considers failed and gives up after ten seconds,+ * while a review takes tens of them — so the handler validates, queues, and+ * answers 202. Everything real happens on the queue.+ */+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";+import { jobKey, reviewJobFor, type ReviewJob } from "./events.js";+import { InstallationTokens, verifySignature, type AppCredentials, type Fetch } from "./identity.js";+import { PageStore } from "./pages.js";+import { WorkQueue } from "./queue.js";+import { reviewPullRequest } from "./review.js";++/** A webhook body larger than this is not a pull_request event we can use. */+const MAX_BODY_BYTES = 2 * 1024 * 1024;++/** Seams for tests: nothing here has a default that touches the network. */+export interface AppSeams {+ fetch?: Fetch;+ /** Swapped out to assert what the queue was handed, without a clone. */+ review?: typeof reviewPullRequest;+ now?: () => number;+}++export interface AppConfig extends AppCredentials {+ webhookSecret: string;+ /** Public origin, for the links put in comments, e.g. https://graft.example.com */+ publicUrl: string;+ port?: number;+ concurrency?: number;+ api?: string;+ log?: (msg: string) => void;+}++export function createApp(+ config: AppConfig,+ seams: AppSeams = {},+): { server: Server; queue: WorkQueue<ReviewJob>; pages: PageStore } {+ const log = config.log ?? ((msg: string) => console.log(msg));+ const fetchImpl = seams.fetch ?? (globalThis.fetch as unknown as Fetch);+ const review = seams.review ?? reviewPullRequest;+ const tokens = new InstallationTokens(config, fetchImpl, seams.now ?? Date.now, config.api);+ const pages = new PageStore({ secret: config.webhookSecret });+ const origin = config.publicUrl.replace(/\/$/, "");++ const queue = new WorkQueue<ReviewJob>(+ async (job) => {+ const started = Date.now();+ const res = await review(job, {+ token: (id) => tokens.get(id),+ fetch: fetchImpl,+ api: config.api,+ publish: async (j, html) => {+ const { id, token } = pages.put(j.owner, j.repo, j.number, html);+ return `${origin}/p/${id}?t=${token}`;+ },+ log,+ });+ log(`${jobKey(job)}: ${res.areas} changed → ${res.affected} affected in ${Date.now() - started}ms`);+ },+ {+ concurrency: config.concurrency,+ onError: (err, key) => {+ // A token GitHub rejected is worth forgetting: the next delivery for that+ // installation should mint a fresh one rather than fail the same way.+ log(`${key}: FAILED ${err instanceof Error ? err.message : String(err)}`);+ },+ },+ );++ const server = createServer((req, res) => {+ void handle(req, res).catch((err) => {+ log(`request failed: ${err instanceof Error ? err.message : String(err)}`);+ if (!res.headersSent) send(res, 500, "text/plain", "internal error");+ });+ });++ async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {+ const url = new URL(req.url ?? "/", origin);++ if (req.method === "GET" && url.pathname === "/healthz") {+ return send(res, 200, "application/json", JSON.stringify({ ok: true, queued: queue.size, pages: pages.size }));+ }++ if (req.method === "GET" && url.pathname.startsWith("/p/")) {+ const html = pages.get(url.pathname.slice(3), url.searchParams.get("t") ?? undefined);+ // A bad token and a missing page are the same answer on purpose: probing+ // for which pull requests exist is not something this should help with.+ if (!html) return send(res, 404, "text/plain", "not found");+ return send(res, 200, "text/html; charset=utf-8", html, { "cache-control": "private, max-age=600" });+ }++ if (req.method === "POST" && url.pathname === "/webhook") {+ const body = await readBody(req);+ if (body === null) return send(res, 413, "text/plain", "payload too large");+ if (!verifySignature(config.webhookSecret, body, header(req, "x-hub-signature-256"))) {+ return send(res, 401, "text/plain", "bad signature");+ }++ const event = header(req, "x-github-event") ?? "";+ let payload: unknown;+ try {+ payload = JSON.parse(body);+ } catch {+ return send(res, 400, "text/plain", "bad json");+ }++ const decided = reviewJobFor(event, payload);+ if ("skip" in decided) return send(res, 204, "text/plain", "");+ queue.push(jobKey(decided.job), decided.job);+ log(`${jobKey(decided.job)}: queued${decided.job.fromFork ? " (fork)" : ""}`);+ return send(res, 202, "application/json", JSON.stringify({ queued: true }));+ }++ return send(res, 404, "text/plain", "not found");+ }++ if (config.port !== undefined) server.listen(config.port, () => log(`graft app listening on :${config.port}`));+ return { server, queue, pages };+}++const header = (req: IncomingMessage, name: string): string | undefined => {+ const v = req.headers[name];+ return Array.isArray(v) ? v[0] : v;+};++function send(res: ServerResponse, status: number, type: string, body: string, extra: Record<string, string> = {}): void {+ res.writeHead(status, { "content-type": type, ...extra });+ res.end(body);+}++/** The raw body — needed verbatim, because the signature covers these bytes. */+async function readBody(req: IncomingMessage): Promise<string | null> {+ const chunks: Buffer[] = [];+ let size = 0;+ for await (const chunk of req) {+ size += (chunk as Buffer).length;+ if (size > MAX_BODY_BYTES) return null;+ chunks.push(chunk as Buffer);+ }+ return Buffer.concat(chunks).toString("utf8");+}diff --git a/test/app-checkout.test.ts b/test/app-checkout.test.tsnew file mode 100644index 00000000..23f5a4f5--- /dev/null+++ b/test/app-checkout.test.ts@@ -0,0 +1,113 @@+/**+ * Getting a pull request onto disk.+ *+ * The ref names are the fiddly part and the easiest to get silently wrong:+ * `refs/pull/N/merge` is GitHub's own merge of the PR into its base — what will+ * actually land — and reviewing the head branch instead would report a radius+ * for code that was never going to exist. A local bare repository stands in for+ * GitHub here, so this exercises the real git commands with no network.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { execFileSync } from "node:child_process";+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { checkoutPullRequest, redact } from "../src/app/checkout.js";++const git = (cwd: string, ...args: string[]): string =>+ execFileSync("git", args, { cwd, encoding: "utf8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@e", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@e" } });++/**+ * A stand-in for GitHub: a mirror holding `main` and the merge ref.+ *+ * `--mirror`, not `--bare`: a bare clone copies branches and tags, and the ref+ * that matters here lives under `refs/pull/`.+ */+function fakeGitHub(): { root: string; repo: string } {+ const root = mkdtempSync(join(tmpdir(), "graft-origin-"));+ const work = join(root, "work");+ execFileSync("git", ["init", "--quiet", "-b", "main", work]);+ git(work, "config", "user.email", "t@e");+ git(work, "config", "user.name", "t");+ writeFileSync(join(work, "base.txt"), "base\n");+ git(work, "add", "-A");+ git(work, "commit", "--quiet", "-m", "base");++ git(work, "checkout", "--quiet", "-b", "feature");+ writeFileSync(join(work, "feature.txt"), "feature\n");+ git(work, "add", "-A");+ git(work, "commit", "--quiet", "-m", "feature");++ // GitHub publishes the merge commit under refs/pull/N/merge; reproduce it.+ git(work, "checkout", "--quiet", "main");+ git(work, "merge", "--quiet", "--no-ff", "-m", "merge", "feature");+ git(work, "update-ref", "refs/pull/7/merge", "HEAD");+ git(work, "checkout", "--quiet", "main");+ git(work, "reset", "--hard", "--quiet", "HEAD~1");++ execFileSync("git", ["clone", "--quiet", "--mirror", work, join(root, "demo.git")]);+ return { root, repo: "demo" };+}++test("checkout: lands on the merge ref, with the base fetched to diff against", () => {+ const origin = fakeGitHub();+ // The remote is built as `${api}/${owner}/${repo}.git`, so `api` points at the+ // directory holding the mirror and `owner` is a no-op path segment.+ const checkout = checkoutPullRequest({+ owner: ".",+ repo: origin.repo,+ number: 7,+ baseRef: "main",+ token: "ghs_secret_token",+ api: `file://${origin.root}`,+ });++ try {+ // The merge ref carries BOTH sides; the base branch alone carries neither.+ assert.equal(readFileSync(join(checkout.dir, "feature.txt"), "utf8"), "feature\n");+ assert.equal(readFileSync(join(checkout.dir, "base.txt"), "utf8"), "base\n");++ const diff = execFileSync("git", ["diff", "--name-only", checkout.base, "HEAD"], { cwd: checkout.dir, encoding: "utf8" });+ assert.equal(diff.trim(), "feature.txt", "the base ref is present and diffs to the PR's change");++ // The token must not be recoverable from the checkout it produced.+ const config = readFileSync(join(checkout.dir, ".git", "config"), "utf8");+ assert.ok(!config.includes("ghs_secret_token"), "no token in .git/config");+ assert.ok(!config.includes(Buffer.from("x-access-token:ghs_secret_token").toString("base64")), "nor encoded");+ } finally {+ checkout.cleanup();+ }+ rmSync(origin.root, { recursive: true, force: true });+});++test("checkout: a failure names the step and never leaks the token", () => {+ const parent = mkdtempSync(join(tmpdir(), "graft-empty-"));+ try {+ checkoutPullRequest({+ owner: ".",+ repo: "does-not-exist",+ number: 1,+ baseRef: "main",+ token: "ghs_secret_token",+ api: `file://${parent}`,+ });+ assert.fail("expected the fetch to fail");+ } catch (err) {+ const msg = err instanceof Error ? err.message : String(err);+ assert.match(msg, /failed at fetch/, "says which step, so a missing merge ref is not read as a permissions problem");+ assert.ok(!msg.includes("ghs_secret_token"), "git's error text is redacted before it is thrown");+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+});++test("redact: removes the token in both the shapes it appears in", () => {+ const encoded = Buffer.from("x-access-token:ghs_abc").toString("base64");+ const text = `fatal: auth failed for ghs_abc using Basic ${encoded}`;++ const clean = redact(text, "ghs_abc");+ assert.ok(!clean.includes("ghs_abc"));+ assert.ok(!clean.includes(encoded));+ assert.match(clean, /fatal: auth failed for \[token\] using Basic \[token\]/);+});diff --git a/test/app-events.test.ts b/test/app-events.test.tsnew file mode 100644index 00000000..f0b6d3b5--- /dev/null+++ b/test/app-events.test.ts@@ -0,0 +1,114 @@+/**+ * What the App agrees to work on.+ *+ * Every accepted delivery costs a clone and a parse, and a bot that comments on+ * every push to a draft is the fastest way to be uninstalled — so the narrowing+ * is behaviour, not plumbing, and is pinned here.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { jobKey, reviewJobFor } from "../src/app/events.js";+import { WorkQueue } from "../src/app/queue.js";++const delivery = (over: Record<string, unknown> = {}, pr: Record<string, unknown> = {}): unknown => ({+ action: "opened",+ installation: { id: 99 },+ repository: { name: "Graft", owner: { login: "NanoNets" }, full_name: "NanoNets/Graft" },+ pull_request: {+ number: 180,+ draft: false,+ state: "open",+ base: { ref: "main", repo: { full_name: "NanoNets/Graft" } },+ head: { sha: "abc123", repo: { full_name: "NanoNets/Graft" } },+ ...pr,+ },+ ...over,+});++test("events: a pull request that changed its diff becomes a job", () => {+ const got = reviewJobFor("pull_request", delivery());+ assert.ok("job" in got);+ assert.deepEqual(got.job, {+ installationId: 99,+ owner: "NanoNets",+ repo: "Graft",+ number: 180,+ baseRef: "main",+ headSha: "abc123",+ fromFork: false,+ });++ // The whole point of the App: a fork PR is an ordinary job. A workflow would+ // have a read-only token here and could not comment at all.+ const fork = reviewJobFor("pull_request", delivery({}, { head: { sha: "def456", repo: { full_name: "someone/Graft" } } }));+ assert.ok("job" in fork);+ assert.equal(fork.job.fromFork, true);+ assert.equal(fork.job.owner, "NanoNets", "the comment belongs on the BASE repo, not the contributor's copy");+});++test("events: noise is skipped with a reason", () => {+ const skipped = [+ reviewJobFor("pull_request", delivery({ action: "labeled" })),+ reviewJobFor("pull_request", delivery({ action: "edited" })),+ reviewJobFor("pull_request", delivery({}, { draft: true })),+ reviewJobFor("pull_request", delivery({}, { state: "closed" })),+ reviewJobFor("issue_comment", delivery()),+ reviewJobFor("ping", {}),+ reviewJobFor("pull_request", delivery({ installation: undefined })),+ ];+ for (const s of skipped) assert.ok("skip" in s, `expected a skip, got ${JSON.stringify(s)}`);++ // …but a draft asking for eyes is exactly when the comment should appear.+ const ready = reviewJobFor("pull_request", delivery({ action: "ready_for_review" }, { draft: true }));+ assert.ok("job" in ready);+});++test("queue: a newer push replaces the queued review for the same pull request", async () => {+ const ran: string[] = [];+ let release: (() => void) | undefined;+ const blocked = new Promise<void>((r) => (release = r));++ const q = new WorkQueue<string>(+ async (item) => {+ ran.push(item);+ if (item === "first") await blocked;+ },+ { concurrency: 1 },+ );++ q.push("pr#1", "first");+ q.push("pr#1", "second");+ q.push("pr#1", "third");+ q.push("pr#2", "other");+ release?.();+ await q.drain();++ // "second" never runs: its comment would have been overwritten by "third"+ // moments later, and the clone behind it is the expensive part.+ assert.deepEqual(ran, ["first", "third", "other"]);+});++test("queue: one bad job does not stop the queue or the process", async () => {+ const seen: unknown[] = [];+ const ran: string[] = [];+ const q = new WorkQueue<string>(+ async (item) => {+ ran.push(item);+ if (item === "boom") throw new Error("clone failed");+ },+ { concurrency: 1, onError: (err) => seen.push(err) },+ );++ q.push("a", "boom");+ q.push("b", "fine");+ await q.drain();++ assert.deepEqual(ran, ["boom", "fine"]);+ assert.equal(seen.length, 1, "the failure is reported, not swallowed");+});++test("events: the queue key is the pull request", () => {+ const got = reviewJobFor("pull_request", delivery());+ assert.ok("job" in got);+ assert.equal(jobKey(got.job), "NanoNets/Graft#180");+});diff --git a/test/app-identity.test.ts b/test/app-identity.test.tsnew file mode 100644index 00000000..a894673e--- /dev/null+++ b/test/app-identity.test.ts@@ -0,0 +1,97 @@+/**+ * The App's half of authentication.+ *+ * Three things here are security-relevant rather than merely correct: the JWT is+ * backdated (GitHub rejects one issued in its future, and a fast server would+ * fail every request with what looks like a bad key), tokens are cached but+ * renewed before expiry, and a webhook signature is compared in constant time.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { createHmac, createVerify, generateKeyPairSync } from "node:crypto";+import { InstallationTokens, appJwt, verifySignature, type Fetch } from "../src/app/identity.js";++const { privateKey, publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });+const creds = {+ appId: "12345",+ privateKey: privateKey.export({ type: "pkcs1", format: "pem" }).toString(),+};++const decode = (part: string): Record<string, unknown> =>+ JSON.parse(Buffer.from(part.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString());++/** The digest GitHub sends, computed independently of the implementation. */+const digest = (secret: string, body: string): string =>+ createHmac("sha256", secret).update(body).digest("hex");++test("app jwt: signed by the private key, backdated, and inside GitHub's 10-minute limit", () => {+ const now = 1_700_000_000_000;+ const [header, payload, signature] = appJwt(creds, now).split(".");++ assert.deepEqual(decode(header), { alg: "RS256", typ: "JWT" });+ const claims = decode(payload) as { iat: number; exp: number; iss: string };+ assert.equal(claims.iss, "12345");+ assert.equal(claims.iat, now / 1000 - 60, "backdated a minute against clock skew");+ assert.ok(claims.exp - claims.iat <= 600, "GitHub rejects a JWT valid for more than ten minutes");++ const verifier = createVerify("RSA-SHA256");+ verifier.update(`${header}.${payload}`);+ assert.ok(+ verifier.verify(publicKey, Buffer.from(signature.replace(/-/g, "+").replace(/_/g, "/"), "base64")),+ "the signature must verify against the app's public key",+ );+});++function fakeFetch(responses: Array<{ ok: boolean; status: number; body: string }>): { fetch: Fetch; calls: string[] } {+ const calls: string[] = [];+ const fetch: Fetch = async (url) => {+ calls.push(url);+ const next = responses.shift();+ if (!next) throw new Error("unexpected extra fetch");+ return { ok: next.ok, status: next.status, text: async () => next.body };+ };+ return { fetch, calls };+}++test("installation tokens: fetched once, reused, and renewed before they expire", async () => {+ let now = 1_700_000_000_000;+ const { fetch, calls } = fakeFetch([+ { ok: true, status: 201, body: JSON.stringify({ token: "ghs_first", expires_at: new Date(now + 3_600_000).toISOString() }) },+ { ok: true, status: 201, body: JSON.stringify({ token: "ghs_second", expires_at: new Date(now + 7_200_000).toISOString() }) },+ ]);+ const tokens = new InstallationTokens(creds, fetch, () => now);++ assert.equal(await tokens.get(42), "ghs_first");+ assert.equal(await tokens.get(42), "ghs_first", "a second call must not spend a round trip");+ assert.equal(calls.length, 1);+ assert.match(calls[0], /\/app\/installations\/42\/access_tokens$/);++ // Inside the renewal margin the cached token is technically still valid, and+ // using it would hand GitHub one that expires mid-review.+ now += 3_600_000 - 30_000;+ assert.equal(await tokens.get(42), "ghs_second");+ assert.equal(calls.length, 2);+});++test("installation tokens: a rejected key reports GitHub's reason, not just 401", async () => {+ const { fetch } = fakeFetch([{ ok: false, status: 401, body: '{"message":"integration not found"}' }]);+ const tokens = new InstallationTokens(creds, fetch);++ await assert.rejects(() => tokens.get(7), /401.*integration not found/s);+});++test("webhook signature: a forgery, a missing header and a wrong length are all rejected", () => {+ const secret = "s3cret";+ const body = '{"action":"opened"}';++ assert.ok(verifySignature(secret, body, `sha256=${digest(secret, body)}`), "the real digest passes");+ assert.ok(!verifySignature(secret, body, undefined), "a missing header is not a pass");+ // Length is checked before the comparison: timingSafeEqual THROWS on a length+ // mismatch, so a short digest would crash the endpoint rather than reject.+ assert.ok(!verifySignature(secret, body, "sha256=deadbeef"), "a short digest must reject, not throw");+ assert.ok(!verifySignature("other-secret", body, `sha256=${digest(secret, body)}`), "another secret's digest");+ assert.ok(+ !verifySignature(secret, '{"action":"closed"}', `sha256=${digest(secret, body)}`),+ "the signature must cover the body that was delivered",+ );+});diff --git a/test/app-server.test.ts b/test/app-server.test.tsnew file mode 100644index 00000000..5c6ff50e--- /dev/null+++ b/test/app-server.test.ts@@ -0,0 +1,184 @@+/**+ * The HTTP surface, over real sockets.+ *+ * The endpoint is public and everything behind it — cloning a repository, posting+ * as the App — happens on its say-so, so the contract asserted here is: an+ * unsigned delivery does nothing, a valid one is acknowledged fast and worked on+ * afterwards, and a page is only readable with its token.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { createHmac, generateKeyPairSync } from "node:crypto";+import type { AddressInfo } from "node:net";+import { createApp } from "../src/app/server.js";+import { PageStore } from "../src/app/pages.js";+import type { ReviewJob } from "../src/app/events.js";++const secret = "webhook-secret";+const { privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });++const delivery = JSON.stringify({+ action: "opened",+ installation: { id: 5 },+ repository: { name: "Graft", owner: { login: "NanoNets" } },+ pull_request: {+ number: 7,+ draft: false,+ state: "open",+ base: { ref: "main", repo: { full_name: "NanoNets/Graft" } },+ head: { sha: "abc", repo: { full_name: "fork/Graft" } },+ },+});++const sign = (body: string): string => `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;++function start(): {+ url: string;+ close: () => Promise<void>;+ queued: () => number;+ pages: PageStore;+ reviewed: ReviewJob[];+ linked: string[];+ drain: () => Promise<void>;+} {+ // No default reaches the network: the reviewer is replaced, so a queued job+ // records what it was handed instead of cloning a repository.+ const reviewed: ReviewJob[] = [];+ const linked: string[] = [];+ const app = createApp(+ {+ appId: "1",+ privateKey: privateKey.export({ type: "pkcs1", format: "pem" }).toString(),+ webhookSecret: secret,+ publicUrl: "http://localhost",+ log: () => {},+ },+ {+ fetch: async () => ({ ok: false, status: 500, text: async () => "no network in tests" }),+ review: async (job, deps) => {+ reviewed.push(job);+ const url = (await deps.publish?.(job, "<h1>radius</h1>")) ?? null;+ if (url) linked.push(url);+ return { commentUrl: null, areas: 1, affected: 2, viewerUrl: url };+ },+ },+ );+ app.server.listen(0);+ const port = (app.server.address() as AddressInfo).port;+ return {+ url: `http://127.0.0.1:${port}`,+ close: () => new Promise((r) => app.server.close(() => r())),+ queued: () => app.queue.size,+ pages: app.pages,+ reviewed,+ linked,+ drain: () => app.queue.drain(),+ };+}++test("webhook: an unsigned or forged delivery is refused and queues nothing", async () => {+ const app = start();+ try {+ const unsigned = await fetch(`${app.url}/webhook`, { method: "POST", body: delivery, headers: { "x-github-event": "pull_request" } });+ assert.equal(unsigned.status, 401);++ const forged = await fetch(`${app.url}/webhook`, {+ method: "POST",+ body: delivery,+ headers: { "x-github-event": "pull_request", "x-hub-signature-256": sign("something else") },+ });+ assert.equal(forged.status, 401);+ assert.equal(app.queued(), 0, "nothing may be queued off an unverified delivery");+ } finally {+ await app.close();+ }+});++test("webhook: a signed fork PR is acknowledged immediately and queued", async () => {+ const app = start();+ try {+ const res = await fetch(`${app.url}/webhook`, {+ method: "POST",+ body: delivery,+ headers: { "x-github-event": "pull_request", "x-hub-signature-256": sign(delivery) },+ });++ // 202, not 200: GitHub gives up on a delivery after ten seconds and a review+ // takes longer than that, so the answer cannot wait for the work.+ assert.equal(res.status, 202);++ await app.drain();+ assert.deepEqual(app.reviewed, [{+ installationId: 5, owner: "NanoNets", repo: "Graft", number: 7,+ baseRef: "main", headSha: "abc", fromFork: true,+ }], "a fork PR is ordinary work here — this is why the App exists");++ // The link the comment would carry has to actually serve the page.+ assert.equal(app.pages.size, 1);+ const link = app.linked[0];+ assert.match(link, new RegExp(`/p/${PageStore.idFor("NanoNets", "Graft", 7)}\\?t=[0-9a-f]{32}$`));+ const page = await fetch(link.replace("http://localhost", app.url));+ assert.equal(page.status, 200);+ assert.equal(await page.text(), "<h1>radius</h1>");+ } finally {+ await app.close();+ }+});++test("webhook: noise is acknowledged without work", async () => {+ const app = start();+ try {+ const body = JSON.stringify({ action: "labeled", installation: { id: 5 } });+ const res = await fetch(`${app.url}/webhook`, {+ method: "POST",+ body,+ headers: { "x-github-event": "pull_request", "x-hub-signature-256": sign(body) },+ });+ assert.equal(res.status, 204);+ assert.equal(app.queued(), 0);+ } finally {+ await app.close();+ }+});++test("pages: readable with its token, invisible without it", async () => {+ const app = start();+ try {+ const { id, token } = app.pages.put("NanoNets", "Graft", 7, "<h1>radius</h1>");++ const ok = await fetch(`${app.url}/p/${id}?t=${token}`);+ assert.equal(ok.status, 200);+ assert.equal(await ok.text(), "<h1>radius</h1>");+ assert.match(ok.headers.get("cache-control") ?? "", /private/, "a private repo's graph must not be cached publicly");++ // A wrong token, a truncated one and an unknown page are all 404 — a 403+ // would confirm which pull requests exist.+ for (const url of [`${app.url}/p/${id}`, `${app.url}/p/${id}?t=nope`, `${app.url}/p/other?t=${token}`]) {+ assert.equal((await fetch(url)).status, 404, url);+ }+ } finally {+ await app.close();+ }+});++test("pages: a link cannot outlive the page it points at", () => {+ let now = 1_000;+ const store = new PageStore({ secret, ttlMs: 100, now: () => now });+ const { id, token } = store.put("o", "r", 1, "<html>");++ assert.equal(store.get(id, token), "<html>");+ now += 101;+ assert.equal(store.get(id, token), null, "expired by storage time, not by anything encoded in the link");+ assert.equal(store.size, 0, "and the page itself is dropped");+});++test("healthz: reports what the process is doing", async () => {+ const app = start();+ try {+ const res = await fetch(`${app.url}/healthz`);+ assert.equal(res.status, 200);+ assert.deepEqual(await res.json(), { ok: true, queued: 0, pages: 0 });+ } finally {+ await app.close();+ }+});