@juangadm/pre-post 1.3.0 → 1.5.0

package/README.md

@@ -1,330 +1,85 @@
 # pre-post
 
-Before/after screenshots for pull requests. One command detects the routes your branch
-changed, captures each one before and after, uploads the images to GitHub, and puts them at
-the top of the PR description where a reviewer can judge them at a glance.
+**See the change before you read the diff.**
 
-It works out both sides itself, cheapest option first:
-
-| | Pre (the baseline) | Post (this branch) |
-|---|---|---|
-| 1 | `--before` | `--after` |
-| 2 | `before` in `.pre-post.json` | the preview deployment for this commit |
-| 3 | the production deployment for the base commit | a local dev server |
-| 4 | whatever is on production now | |
-| 5 | the base commit, served locally | |
-
-Rows 2 to 4 need no dev environment at all, which is the point: a preview deployment and a
-production URL are enough for anyone who can open the PR. Deployments come from the GitHub
-Deployments API, so Vercel, Cloudflare Pages, Netlify and Render all work with no extra
-token and nothing to configure; a host that records only a commit status is read from the
-deployment bot's own PR comment instead. Row 4 covers repositories that do not deploy every
-push to their default branch, so nothing is deployed at the fork point — it prints which
-commit Pre actually came from rather than implying the base.
-
-pre-post never guesses a baseline. If no deployment can be found it says so and tells you
-the one flag that fixes it, because a baseline that is quietly the wrong site reads as 100%
-changed on every route and looks exactly like a real result.
-
-The last baseline needs no network at all: it checks the base commit into a throwaway
-worktree and boots its dev script. That keeps pre-post working inside a sandboxed agent
-container, a CI job, or behind an egress allowlist — and it compares against exactly what
-the branch forked from, rendered in the same browser as the Post side.
-
-> Originally forked from [before-and-after](https://github.com/vercel-labs/before-and-after) by James Clements / Vercel Labs.
+pre-post puts before/after screenshots of every page your branch touched at the top of the
+pull request. One command finds the changed routes, captures Pre and Post, highlights what
+moved, and updates the PR description. No setup, no pasting images.
 
 ```
 $ npx -y @juangadm/pre-post@latest pr
 
 Routes (nextjs-app, 41ms): /, /pricing
-  /                           medium src/app/page.tsx imports src/components/ui/button.tsx (2 hops)
-  /pricing                    medium src/app/pricing/page.tsx imports src/components/ui/button.tsx (2 hops)
-Capturing 8 screenshots (2 route(s) × 2 viewport(s)) ...
-  changed  /pricing @ mobile (1.42%, 1811ms)
+Capturing 4 screenshots (2 route(s) × 1 viewport(s)) ...
   changed  /pricing @ desktop (0.64%, 2036ms)
-  same     / @ mobile (0.00%, 1990ms)
   same     / @ desktop (0.00%, 2211ms)
-Publishing 10 image(s) to acme/web@pre-post-assets ...
 Updated PR description: https://github.com/acme/web/pull/42
-pre-post · PR #42 · 2 route(s) · 2 viewport(s) · 6.8s
-  /         desktop  no change
-  /         mobile   no change
-  /pricing  desktop  0.64% changed
-  /pricing  mobile   1.4% changed
-Comment: https://github.com/acme/web/pull/42
 ```
 
-## How it works
-
-1. **Routes.** Diffs the branch against the merge base with `main` — fetching that branch
-   first when the checkout does not have it, which is the normal shape in CI and in the
-   web/sandbox editors. When no shared history can be established it stops with one
-   sentence rather than reporting an empty diff, and `--base <ref>` names the commit
-   directly. Then it follows the import
-   graph: a change to `components/ui/button.tsx` marks every page that imports it. Next.js
-   App Router and Pages Router, Vite apps (React Router, file-based `src/pages`), and a
-   generic fallback. Monorepos are handled by picking the app that owns the changed files.
-2. **Capture.** Playwright + Chromium headless shell. The page's own clock is held
-   still while it loads and then run forward by a fixed budget, so a page that animates
-   on a timer is photographed at the same frame on both sides however fast each host
-   answered. Reduced motion, animations finished, caret hidden, fonts and images settled,
-   layout stable, lazy content primed. 2x device scale, full page (capped at 2400 CSS
-   px), desktop (add mobile with `-r`).
-   All routes and viewports run concurrently.
-3. **Diff.** Pure-JS pixel comparison in worker threads. Reports the percentage changed,
-   the bounding box, and a tight crop of the changed region. A route counts as changed when
-   the painted difference covers at least `minChangedArea` CSS pixels² (default 100, roughly
-   a third of a 16px icon) or at least `threshold` of the canvas — the first rule is what
-   decides on a page, the second on a small image.
-4. **Layout shift.** A padding change near the top of a page moves everything below it, and
-   pixel diffing counts every moved pixel as changed: a change a designer would call
-   "slightly roomier" reads as most of the page repainted, and the crop is suppressed just
-   when it would be most useful. So the two sides are checked for a single vertical offset
-   first — how far the content moved, and from which row. When one is found, Pre is re-spaced
-   into Post's layout and the two are compared there: the crop comes from that pair, and the
-   comment says `Content shifted down 48px` instead of quoting a percentage. Rows Post gained
-   are left as background rather than skipped, so content inserted above the shift — the
-   banner that caused it — still reads as new rather than as nothing. The offset is only
-   accepted when it accounts for most of the difference across the rows both sides share.
-   The raw numbers are left alone: a move is a visual change, and reporting less of one would
-   hide it. Reflow, where content moves both across and down, has no single offset to find,
-   so it is reported the way it always was.
-5. **Publish.** Images go to a `pre-post-assets` branch in the same repository via the GitHub
-   API, as one commit per run. Nothing is committed to the PR branch, no CI is triggered,
-   and the blob URLs render on private repos — a screenshot is visible to exactly whoever
-   can see the repository. `pre-post prune` removes images for PRs closed more than 90 days
-   ago, but note that it commits a deletion rather than rewriting history: the older commits
-   still hold the blobs, so a link handed out earlier keeps working. Treat anything captured
-   as permanent, and think twice before pointing pre-post at a preview holding real data.
-   See [Screenshot storage](#screenshot-storage) for how fast the branch grows.
-6. **Describe.** The images go in a delimited block at the top of the PR description,
-   replaced in place on every run and leaving your own text untouched. Changed routes show
-   a Pre/Post crop with the full page collapsed underneath; unchanged routes fold into a
-   single line. A pure layout shift — nothing changed once the move is undone — has no
-   region to crop, so it shows the full pages directly under the `Content shifted down 40px.
-   Nothing else changed.` line, with no collapsed section repeating them. If the PR cannot be edited — a fork, a read-only token — it falls back to
-   one sticky comment.
+## Get started
 
-## Install
+Pick one. None of them installs anything permanently.
 
-Two ways. Neither installs anything permanently.
-
-### Claude Code — easiest
+**In Claude Code**: install the skill once, then say `/pre-post` after a UI change.
 
 ```bash
 npx skills add juangadm/pre-post -y
 ```
 
-Then say `/pre-post` after a UI change. Install once, never type a flag. No npm
-knowledge needed.
-
-### Terminal
+**In a terminal**: run it on a branch with an open PR.
 
 ```bash
 npx -y @juangadm/pre-post@latest pr
 ```
 
-Run it on a branch with an open PR. No install step.
+**On every PR, automatically**: add the [GitHub Action](https://github.com/juangadm/pre-post/blob/main/docs/github-action.md). No tokens or
+secrets needed.
 
-### Both need
+### You'll need
 
-| | |
-|---|---|
-| **Node 20+** | The one hard requirement. Check with `node --version`. |
-| **A GitHub token** | `gh auth login`, or set `GH_TOKEN`. Needs write access — it publishes images and edits the PR. |
-| **An open PR** | Where the images go. Without one, pre-post prints the markdown to paste. |
+- **Node 20+**
+- **A GitHub token** with write access: `gh auth login`, or set `GH_TOKEN`
+- **An open PR**: without one, pre-post prints the markdown for you to paste
 
-First run also pulls a Chromium headless shell (~80 MB), then reuses it. Stuck? Run
+The first run downloads a small browser (~80 MB). Stuck? Run
 `npx -y @juangadm/pre-post@latest doctor`.
 
-### GitHub Action: every PR, no tokens
-
-For a team, or for work done in cloud agent sessions: GitHub runs pre-post on each push to a
-PR and posts with the job's own token. Nobody sets up anything per person, and there are no
-secrets to add. Add `.github/workflows/pre-post.yml`:
-
-```yaml
-name: pre-post
-on: pull_request
-permissions: { contents: write, pull-requests: write }
-concurrency: { group: 'pre-post-${{ github.event.pull_request.number }}', cancel-in-progress: true }
-jobs:
-  pre-post:
-    if: github.event.pull_request.head.repo.full_name == github.repository
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { ref: '${{ github.event.pull_request.head.sha }}', fetch-depth: 0 }
-      - uses: juangadm/pre-post@v1
-```
-
-The runner builds the base commit and the PR's commit and serves both, the same way pre-post
-does on a laptop with nothing deployed. No preview deployment is involved, so Vercel's
-Deployment Protection never gets in the way.
-
-- **Your app must start with its dev script without secrets.** If it needs environment
-  variables, give them to the job with `env:`.
-- **pnpm or yarn** comes from the `packageManager` field in package.json. Without one, set
-  it up before the pre-post step (e.g. `pnpm/action-setup`), as any other job would.
-- **Fork PRs are skipped:** their token cannot write, so there is nowhere to post.
-- **Flags** go in `with: { args: '--responsive' }`.
-- **The run's images**, including `sheet.png`, are kept as a workflow artifact even when
-  posting fails.
-- **Pinned:** `@v1` runs the pre-post version released with that tag, never whatever npm
-  calls `latest`.
-
-## Usage
+## Everyday commands
 
 ```bash
-pre-post pr                                  # everything, on the current branch's PR
-pre-post pr --before https://acme.com        # pin the baseline (saved to .pre-post.json)
-pre-post pr --no-local-baseline              # never build the base commit locally
-pre-post pr --routes /pricing,/docs          # explicit routes
-pre-post pr --viewports desktop,1440x900     # custom viewports
-pre-post pr --dry-run                        # capture + diff locally, post nothing
-pre-post pr --json                           # machine-readable output
-
-pre-post https://acme.com http://localhost:3000 --routes /pricing   # ad-hoc comparison
-pre-post before.png after.png                # diff two images
-pre-post detect                              # which routes does this branch touch?
-pre-post login https://staging.acme.com      # sign in once; the session is reused
-pre-post prune --days 90                     # clean up the assets branch
-pre-post doctor                              # browser, token, dev server, config
-```
-
-When something needs a human, the CLI exits with code 3 and one sentence saying what to do
-(log in, start the dev server, pass `--before`). Re-running picks up where it left off.
-
-Exit codes, so a script or an agent can branch on them:
-
-| code | meaning |
-|---|---|
-| 0 | done; for `doctor`, `pre-post pr` can run |
-| 1 | the run failed — every capture errored, or an unexpected error; for `doctor`, a required check failed |
-| 2 | the arguments could not be parsed |
-| 3 | something needs a human; the message says what |
-
-`doctor` marks a check **FAIL** only when `pre-post pr` has no way to proceed without it —
-the browser, a GitHub token, and being inside a git repository. Everything else prints as
-**note**: no dev server running, or no `--before` saved, narrows *which* strategy a run
-picks rather than stopping it, so those never change the exit code.
-
-Results go into a delimited block at the top of the PR description, which re-runs replace in
-place, leaving your own text untouched. If the PR cannot be edited — a fork, a read-only
-token — it falls back to a single sticky comment.
-
-## Screenshot storage
-
-Every real run adds one commit to the `pre-post-assets` branch holding that run's images —
-roughly 100–200 KB for a small PR, and again on every re-run. As a rough guide, 20 PRs a
-week at 3 runs each is about 9 MB a week, or ~450 MB a year.
-
-Two things to know before that adds up:
-
-- **`prune` tidies the branch; it does not shrink the repository.** It commits a deletion,
-  so the images stay in history and every link already posted in a PR keeps working. The
-  repository's size only ever grows.
-- **A plain `git clone` downloads every branch**, screenshots included. Teammates who never
-  look at them can skip the branch in an existing clone (git 2.29+):
-
-  ```bash
-  git config --add remote.origin.fetch '^refs/heads/pre-post-assets'
-  ```
-
-A weekly prune keeps the branch's own listing short. As a scheduled workflow:
-
-```yaml
-# .github/workflows/pre-post-prune.yml
-on:
-  schedule: [{ cron: '17 6 * * 1' }]   # Mondays
-  workflow_dispatch:
-permissions: { contents: write, pull-requests: read }
-jobs:
-  prune:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npx -y @juangadm/pre-post@latest prune --days 90
-        env: { GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}' }
+pre-post pr                              # screenshot this branch's PR
+pre-post pr --routes /pricing,/docs      # only these pages
+pre-post pr -r                           # desktop and mobile
+pre-post pr --before https://acme.com    # set the "before" site (remembered)
+pre-post pr --dry-run                    # try it without posting
+pre-post login https://staging.acme.com  # sign in once for protected sites
+pre-post doctor                          # check your setup
 ```
 
-It removes folders for PRs closed more than 90 days ago, and runs made before a PR was
-opened once they are that old. Actually reclaiming the space means rewriting the branch's
-history, which also breaks the images in those older PRs — so it is left as your call.
-
-## Configuration
-
-Optional `.pre-post.json` in the repo root:
+If pre-post needs something from you, it stops with one sentence saying exactly what.
 
-```json
-{
-  "before": "https://acme.com",
-  "routes": ["/"],
-  "samples": { "/blog/[slug]": "/blog/hello-world" },
-  "viewports": ["desktop"],
-  "fullPage": true,
-  "maxHeight": 2400,
-  "scale": 2,
-  "threshold": 0.001,
-  "minChangedArea": 100,
-  "maxRoutes": 6,
-  "ignore": ["apps/docs"],
-  "headers": {},
-  "assetsBranch": "pre-post-assets",
-  "baselineSetup": "pnpm run build:packages"
-}
-```
-
-`baselineSetup` runs in the app directory between the install and the dev server when the
-baseline is built from source. Use it for whatever the app needs before it can boot — a
-workspace build, a codegen step. In a turborepo it is inferred: `turbo run build
---filter=<app>^...`, which builds the packages the app imports and leaves the app to the
-dev server. Setting it turns the guess off.
+## How it decides what "before" is
 
-A command that fails stops the run with one instruction, rather than quietly comparing
-against something else.
+Post (your branch) is the PR's preview deployment, or a local dev server. Pre is the
+production site your branch forked from. When nothing is deployed, pre-post builds the base
+commit itself, so it works in CI and in sandboxes too. It never guesses: if it can't find a
+trustworthy baseline, it tells you which flag to pass.
 
-Env files copied into the baseline's worktree get their origin variables rewritten to the
-port the baseline actually listens on, before the setup step runs so a build cannot bake in
-the old one. Without this an auth-gated app rejects its own callbacks and every capture is a
-loading skeleton. The names rewritten are the ones that can only mean the app's own address
-— `BETTER_AUTH_URL`, `NEXTAUTH_URL`, `AUTH_URL`, `APP_URL`, `SITE_URL`, `CANONICAL_URL` and
-their `_ORIGIN`/`_BASE_URL` forms, with a `NEXT_PUBLIC_` / `VITE_` / `PUBLIC_` prefix
-optional. Generic names are left alone: `BASE_URL`, `SERVER_URL` and `PUBLIC_URL` are as
-often a backend on another port or a path prefix, and `DATABASE_URL` is never an origin.
+Screenshots are stored on a `pre-post-assets` branch in your own repo, so only people who can
+see the repo can see them. Nothing is committed to your PR branch.
 
-Environment:
+## Learn more
 
-| Variable | Purpose |
+| | |
 |---|---|
-| `PRE_POST_GH_TOKEN` | GitHub token read before the two below. Use it where a hosted environment sets `GH_TOKEN` itself |
-| `GH_TOKEN` / `GITHUB_TOKEN` | GitHub token (default: `gh auth token`) |
-| `VERCEL_AUTOMATION_BYPASS_SECRET` | Bypass Vercel Deployment Protection on preview and production URLs |
-| `PRE_POST_CONCURRENCY` | Parallel pages (default 6) |
-| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | Use a specific Chromium binary |
-| `GH_REPO` | `owner/repo` when the remote URL cannot be parsed |
-
-## Library
-
-```ts
-import { runPr, captureScreenshot, diffImages, detectRoutesForRepo } from '@juangadm/pre-post';
-```
-
-## Development
-
-```bash
-pnpm install
-pnpm build
-pnpm test:unit
-TEST_BROWSER=true pnpm test        # needs a Chromium; npx playwright-core install chromium-headless-shell
-```
-
-pnpm and npm cannot share a `node_modules`. pnpm builds a symlinked tree that npm
-cannot read, so `npm install` over it fails with `Cannot read properties of null
-(reading 'edgesOut')`, which names none of that. Run `rm -rf node_modules
-site/node_modules` before switching either way. npm also installs the CLI only —
-`site/` is a pnpm workspace member, so use pnpm to work on the site.
+| [How it works](https://github.com/juangadm/pre-post/blob/main/docs/how-it-works.md) | How Pre and Post are chosen, capture, diffing, layout shifts |
+| [GitHub Action](https://github.com/juangadm/pre-post/blob/main/docs/github-action.md) | Run on every PR with no per-person setup |
+| [Video: Moments](https://github.com/juangadm/pre-post/blob/main/docs/video.md) | Record interactions (menus, hovers, transitions) as synced Pre \| Post clips |
+| [Reference](https://github.com/juangadm/pre-post/blob/main/docs/reference.md) | All commands, exit codes, `.pre-post.json`, environment variables |
+| [Screenshot storage](https://github.com/juangadm/pre-post/blob/main/docs/storage.md) | How much space it uses and how to prune it |
+| [Contributing](https://github.com/juangadm/pre-post/blob/main/CONTRIBUTING.md) | Build and test locally |
 
-## License
+## Credits
 
-MIT
+Forked from [before-and-after](https://github.com/vercel-labs/before-and-after) by James
+Clements / Vercel Labs. MIT licensed.

package/dist/attach.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Put clips where GitHub will play them.
+ *
+ * A video plays inline in a PR only from GitHub's own attachment storage
+ * (`github.com/user-attachments/assets/…`); a file on the assets branch is a
+ * download link at best. Since 2026-09-01 `gh` uploads there with `--attach`
+ * (gh 2.99+, a person's login or a classic PAT — the Actions GITHUB_TOKEN is
+ * refused), rewriting a local reference in the text it posts into the
+ * attachment URL.
+ *
+ * The description itself is written by the same code as always, so the clips
+ * are uploaded on their own first: a temporary comment carries them up, their
+ * URLs are read back, and the comment is deleted — the flow vercel-labs'
+ * before-and-after settled on. Anything that goes wrong leaves the caller to
+ * fall back to the assets branch. The cost: PR subscribers are notified of a
+ * comment that is gone by the time they look. Passing `--attach` to the
+ * description edit itself would avoid it, but the sticky-comment fallback
+ * would still need this flow.
+ */
+import { GitHub } from './github.js';
+import { MomentOutcome } from './types.js';
+/** The first gh release whose `--attach` works on PRs and comments. */
+export declare const MIN_GH_FOR_ATTACH: readonly [2, 99, 0];
+export declare const UPDATE_GH_HINT = "Update GitHub CLI to 2.99 or newer (https://cli.github.com, or `brew upgrade gh`) to play videos inline in the PR.";
+/** `gh version 2.101.0 (2026-09-20)` → [2, 101, 0]. */
+export declare function parseGhVersion(output: string): number[] | null;
+export declare function atLeast(version: number[], min: readonly number[]): boolean;
+/** Whether this machine's gh can attach video, and if not the sentence that fixes it. */
+export declare function ghAttachSupport(): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The attachment URLs in a comment body, in the order they appear. */
+export declare function attachmentUrls(body: string): string[];
+/**
+ * Upload `files` (all in one folder) as PR attachments. Returns file → URL.
+ * Throws when any of them does not come back as an attachment.
+ */
+export declare function uploadAttachments(gh: GitHub, ownerRepo: string, prNumber: number, files: string[], token?: string): Promise<Map<string, string>>;
+export interface AttachOptions {
+    gh: GitHub;
+    ownerRepo: string;
+    /** No PR yet means nowhere to attach to. */
+    pr?: number;
+    token?: string;
+    log?: (msg: string) => void;
+}
+/**
+ * Attach recorded clips to the PR where possible, marking each one inline.
+ * Returns the clips left for the assets branch, and the one sentence that
+ * would make them play when there are any.
+ */
+export declare function attachClips(clips: MomentOutcome[], opts: AttachOptions): Promise<{
+    linked: MomentOutcome[];
+    hint?: string;
+}>;
+//# sourceMappingURL=attach.d.ts.map

package/dist/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,qBAAsB,CAAC;AAErD,eAAO,MAAM,cAAc,uHAAuH,CAAC;AAKnJ,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAG9D;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK1E;AAED,yFAAyF;AACzF,wBAAgB,eAAe,IAAI;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQ9E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAErD;AAmBD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA4B9B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBlI"}

package/dist/attach.js

@@ -0,0 +1,137 @@
+/**
+ * Put clips where GitHub will play them.
+ *
+ * A video plays inline in a PR only from GitHub's own attachment storage
+ * (`github.com/user-attachments/assets/…`); a file on the assets branch is a
+ * download link at best. Since 2026-09-01 `gh` uploads there with `--attach`
+ * (gh 2.99+, a person's login or a classic PAT — the Actions GITHUB_TOKEN is
+ * refused), rewriting a local reference in the text it posts into the
+ * attachment URL.
+ *
+ * The description itself is written by the same code as always, so the clips
+ * are uploaded on their own first: a temporary comment carries them up, their
+ * URLs are read back, and the comment is deleted — the flow vercel-labs'
+ * before-and-after settled on. Anything that goes wrong leaves the caller to
+ * fall back to the assets branch. The cost: PR subscribers are notified of a
+ * comment that is gone by the time they look. Passing `--attach` to the
+ * description edit itself would avoid it, but the sticky-comment fallback
+ * would still need this flow.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawn, spawnSync } from 'child_process';
+/** The first gh release whose `--attach` works on PRs and comments. */
+export const MIN_GH_FOR_ATTACH = [2, 99, 0];
+export const UPDATE_GH_HINT = 'Update GitHub CLI to 2.99 or newer (https://cli.github.com, or `brew upgrade gh`) to play videos inline in the PR.';
+const ATTACHMENT_URL = /https:\/\/github\.com\/user-attachments\/assets\/[\w-]+/g;
+const UPLOAD_MARKER = '<!-- pre-post:upload (temporary; deleted once the clips are uploaded) -->';
+/** `gh version 2.101.0 (2026-09-20)` → [2, 101, 0]. */
+export function parseGhVersion(output) {
+    const m = /gh version (\d+)\.(\d+)\.(\d+)/.exec(output);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+export function atLeast(version, min) {
+    for (let i = 0; i < min.length; i++) {
+        if ((version[i] ?? 0) !== min[i])
+            return (version[i] ?? 0) > min[i];
+    }
+    return true;
+}
+/** Whether this machine's gh can attach video, and if not the sentence that fixes it. */
+export function ghAttachSupport() {
+    const probe = spawnSync('gh', ['--version'], { encoding: 'utf-8' });
+    if (probe.error || probe.status !== 0) {
+        return { ok: false, reason: 'Install GitHub CLI 2.99 or newer (https://cli.github.com) to play videos inline in the PR.' };
+    }
+    const version = parseGhVersion(probe.stdout);
+    if (!version || !atLeast(version, MIN_GH_FOR_ATTACH))
+        return { ok: false, reason: UPDATE_GH_HINT };
+    return { ok: true };
+}
+/** The attachment URLs in a comment body, in the order they appear. */
+export function attachmentUrls(body) {
+    return body.match(ATTACHMENT_URL) ?? [];
+}
+function runGh(args, cwd, token) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('gh', args, {
+            cwd,
+            // The token pre-post already uses, so gh acts as the same identity.
+            env: token ? { ...process.env, GH_TOKEN: token } : process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', d => { out += d; });
+        child.stderr.on('data', d => { err += d; });
+        child.on('error', reject);
+        child.on('close', code => code === 0 ? resolve(out) : reject(new Error(err.trim().split('\n').pop() || `gh exited ${code}`)));
+    });
+}
+/**
+ * Upload `files` (all in one folder) as PR attachments. Returns file → URL.
+ * Throws when any of them does not come back as an attachment.
+ */
+export async function uploadAttachments(gh, ownerRepo, prNumber, files, token) {
+    if (!files.length)
+        return new Map();
+    const dir = path.dirname(files[0]);
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'pre-post-upload-'));
+    const bodyFile = path.join(scratch, 'body.md');
+    // `--attach` rewrites references to the files it is given, resolved from
+    // gh's working directory, so both use the same relative spelling.
+    const refs = files.map(f => `./${path.basename(f)}`);
+    fs.writeFileSync(bodyFile, [UPLOAD_MARKER, '', ...refs.map(r => `![clip](${r})`), ''].join('\n'));
+    try {
+        const out = await runGh([
+            'pr', 'comment', String(prNumber), '--repo', ownerRepo, '--body-file', bodyFile,
+            ...refs.flatMap(r => ['--attach', r]),
+        ], dir, token);
+        const id = /#issuecomment-(\d+)/.exec(out)?.[1];
+        if (!id)
+            throw new Error('gh did not say which comment it posted');
+        const comment = await gh.request('GET', `/repos/${ownerRepo}/issues/comments/${id}`);
+        const urls = attachmentUrls(comment.body ?? '');
+        if (urls.length !== files.length) {
+            // Kept, not deleted: the comment is the only place the uploads are listed.
+            throw new Error(`expected ${files.length} attachment(s), GitHub returned ${urls.length}`);
+        }
+        // The attachment outlives the comment that carried it up.
+        await gh.request('DELETE', `/repos/${ownerRepo}/issues/comments/${id}`).catch(() => undefined);
+        return new Map(files.map((f, i) => [f, urls[i]]));
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Attach recorded clips to the PR where possible, marking each one inline.
+ * Returns the clips left for the assets branch, and the one sentence that
+ * would make them play when there are any.
+ */
+export async function attachClips(clips, opts) {
+    const log = opts.log ?? (() => undefined);
+    if (!opts.pr)
+        return { linked: clips, hint: 'Open the PR and re-run to play the videos inline.' };
+    const support = ghAttachSupport();
+    if (!support.ok) {
+        log(`Videos will be linked, not inline: ${support.reason}`);
+        return { linked: clips, hint: support.reason };
+    }
+    try {
+        const urls = await uploadAttachments(opts.gh, opts.ownerRepo, opts.pr, clips.map(m => m.file), opts.token);
+        for (const m of clips) {
+            m.videoUrl = urls.get(m.file);
+            m.inline = true;
+        }
+        log(`Attached ${clips.length} video(s) to PR #${opts.pr}.`);
+        return { linked: [] };
+    }
+    catch (err) {
+        const hint = `GitHub did not take the videos as attachments (${err instanceof Error ? err.message : err}); they are linked instead. Inline video needs gh signed in as a person or with a classic token, not the Actions GITHUB_TOKEN.`;
+        log(hint);
+        return { linked: clips, hint };
+    }
+}
+//# sourceMappingURL=attach.js.map

package/dist/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"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"}

package/dist/baseline.d.ts

@@ -11,13 +11,24 @@
  * The cost is time: a checkout, an install and a dev-server boot. So callers
  * reach for it after a reachable deployment, not before one.
  */
+import { ChildProcess } from 'child_process';
 import { NeedsHumanError } from './errors.js';
 import { Stopwatch } from './timings.js';
 export interface LocalBaseline {
     url: string;
     /** Stop the dev server and delete the worktree. Safe to call twice. */
     stop: () => Promise<void>;
+    /** Everything the dev server printed, so a failure can be explained with its own words. */
+    logFile?: string;
 }
+/**
+ * Where a dev server's output goes: a file per server, never the terminal.
+ *
+ * It used to go nowhere (`stdio: 'ignore'`), so when a server answered 500
+ * there was no way to say why. A file rather than a pipe: the server is
+ * detached and must not stall when this process stops reading.
+ */
+export declare function serverLogFile(side: 'pre' | 'post', port: number): string;
 interface PackageManager {
     bin: string;
     install: string[];
@@ -172,7 +183,7 @@ export declare function installDeps(pm: PackageManager, cwd: string, timeoutMs:
 /**
  * The install failed and nothing else can rescue this run.
  *
- * Its own error rather than a quiet null, for the reason docs/portability.md
+ * Its own error rather than a quiet null, for the reason docs/internal/portability.md
  * §1 gives about base resolution: a run that compared nothing must not exit
  * clean. A null here fell through to "no baseline", and on a repository with a
  * configured production URL it fell through to comparing against that instead
@@ -257,6 +268,20 @@ export declare function reusableInstall(repoRoot: string, sha: string): Promise<
  * removed so the normal install starts from a clean tree.
  */
 export declare function reuseInstall(repoRoot: string, worktree: string, dirs: string[]): Promise<boolean>;
+/** How long a dev server gets to exit on SIGTERM before it is killed. */
+export declare const SERVER_STOP_TIMEOUT_MS = 5000;
+/**
+ * SIGTERM the server's process group, wait for it to exit, then make sure.
+ *
+ * The wait is on the child itself — the package manager, which exits once the
+ * server under it has — because Node reaps it, so its exit is a fact. Asking
+ * the group with signal 0 was not: in a container whose PID 1 does not reap,
+ * dead members linger as zombies that still answer, and every stop waited out
+ * the full timeout. Once the child is gone, or `timeoutMs` has passed, the
+ * whole group is SIGKILLed, so nothing it started is left writing into a
+ * worktree about to be removed.
+ */
+export declare function stopGroup(child: ChildProcess, timeoutMs?: number): Promise<void>;
 export interface BaselineOptions {
     repoRoot: string;
     /** Commit to serve. Omit to serve the working tree as it stands. */