@impeccable/reviews 0.1.3 → 0.1.5

package/dist/playbook/cases/pull-requests.md

@@ -12,7 +12,7 @@ Every run, once the settings are saved. The person merges the setup pull request
    - **Netlify** (netlify-previews, netlify-setup) builds a deploy preview only for a pull request: open the test drive now as a **draft**, step 5's `gh pr create` with `--draft`, which Impeccable leaves unreviewed. impeccable_netlify_previews with `pull` the number it printed waits up to five minutes for the deploy preview, under a status line with its timer. Prove the test drive's page on it, save the method as the case says, then `gh pr ready impeccable/test-drive --repo <owner>/<repo>` marks it ready, which starts the review. Then step 5's recording.
    - **Impeccable's own preview** (static-site): the workflow in the branch builds it on the pull request, and Impeccable's review holds up to eight minutes for that job before it renders, so step 3's proof and the workflow in the branch (from the setup commit) are all this step takes. Then step 5.
 
-   Done when the test drive's page is proven on its preview, and a host's method saved; when nothing proved it, the reference below says how the run goes on.
+   A host's wait that ran out shows its own screen, which opens the host's page where its builds are turned on and waits again on the person's yes. Done when the test drive's page is proven on its preview, and a host's method saved; when nothing proved it, the reference below says how the run goes on.
 5. **Open the test drive and record it**: `gh pr create --repo <owner>/<repo> --head impeccable/test-drive --base <defaultBranch>` with the title "Impeccable test drive (safe to close)" and a body that starts "This pull request only shows Impeccable reviewing a change. Close it when you are done; nothing here needs to be merged." and then names the two pages and lists the flaws planted for the review to find, one line each (a Netlify draft opened this way in step 4, and was marked ready there). Record it right away with impeccable_test_pr, so the web page follows its review; it refuses a draft. Done when impeccable_test_pr answered "Recorded".
 6. **Check the test drive's preview once**, while it is the newest open pull request: impeccable_write to `latest-pull-check` with the app's `appKey`. Done when it answered; this early a 409 `no-preview-running` or a job still starting is expected, and the preview goes under "What is not verified".
 7. **Open the setup pull request**, when there is a setup commit: `git push -u origin impeccable/setup`, then `gh pr create --repo <owner>/<repo> --head impeccable/setup --base <defaultBranch>` with the title "Set up Impeccable previews" and a body that starts "Merge this to keep Impeccable's previews working." and then says what it carries and why, one line each. Record it with impeccable_test_pr: the test drive again, and this one in `setup_pr`. Done when impeccable_test_pr answered "Recorded".
@@ -26,6 +26,6 @@ Every run, once the settings are saved. The person merges the setup pull request
   - **Low-contrast text**: text in a solid light grey, well under 4.5:1 against its background.
   - **A layout transition**: `transition: width 0.3s`, naming the layout property.
   - **Body text at the viewport edge**: a paragraph of more than 40 characters in the main content, without a background, flush with the sides of the viewport.
-- **No preview, no test drive**: when step 4 ends with the preview unproven (the host's build failed or none came within the five minutes, the host's login stayed in front, step 3 failed), open no test drive: mark the Test drive task failed, say under "What is not verified" what was missing and what the person can do, and put their step in `left`. The setup pull request still opens in step 7 when there is a setup commit. A Netlify draft stays open, unrecorded: name it in the report, and put "Mark the test drive #N ready once Netlify builds its preview" in `left`.
+- **No preview, no test drive**: when step 4 ends with the preview unproven (the host's build failed or none came within the five minutes, the host's login stayed in front, step 3 failed), open no test drive: mark the Test drive task failed, say under "What is not verified" what was missing and what the person can do, and put their step in `left`. The setup pull request still opens in step 7 when there is a setup commit. A Netlify draft stays open, unrecorded: name it in the report. Put "Mark the test drive #N ready once Netlify builds its preview" in `left` only where Netlify built no preview; where it built one and the lock stayed in front, preview-protection's step 3 says what the report says instead.
 - **A single-page app**, whose routes live in the browser: the new page is a self-contained HTML file in the folder the build copies as it is (`public/` in Vite), so the output holds it for `entries` and the review counts it as a page added.
 - **A branch name an earlier run took** (checkout or push says so): use `-2`, then `-3`, and name the earlier pull request in the report so the person can close it.

package/dist/playbook/cases/server-previews.md

@@ -8,10 +8,10 @@ The pages need a server from this repository (SSR, API routes, or a backend the
    - **Several apps**: ask once for each app this case applies to, the title naming the app (*"Order desk previews"*).
    - **Asked already for this app in this run**, or a host's setup for it ended without a preview (the sign-in skipped, a step failed): ask nothing, and go on as after a skip.
 2. **Set the host up**: on `vercel`, as the vercel-setup case says, and on `netlify`, as the netlify-setup case says. The pick stands in for that case's "When this applies": its steps run whatever the checkout holds for the host, and even where the host already deploys previews that showed another app or did not answer, since the test drive's own preview, proven on that host, decides. Done when that case's steps are done.
-3. **After a skip**: no preview, no test drive. Save no method and write no workflow for these pages, and open no test drive, as pull-requests' "No preview, no test drive" says. Mark the Preview method and Test drive tasks failed, say under "What was skipped, and why" that the pages need a server and no host deploys previews of them, and put "Turn on your host's pull request previews, then run the setup again" in `left`, naming Vercel, Netlify and Cloudflare in the report. The checkup's entry for this preview then stays in `next`, which counts as done for the playbook's step 5. With several apps this holds for the skipped app alone: the other chosen apps' previews and the test drive go on as monorepo says, and the tasks fail only where no app has a preview. Done when the report says so.
+3. **After a skip**: no preview, no test drive. Save no method and write no workflow for these pages, and open no test drive, as pull-requests' "No preview, no test drive" says. Mark the Preview method and Test drive tasks failed, and say under "What was skipped, and why" that the pages need a server and no host deploys previews of them, naming Vercel, Netlify and Cloudflare as the hosts whose pull request previews Impeccable reviews. The checkup's entry for this preview then stays in `next`, which counts as done for the playbook's step 5. With several apps this holds for the skipped app alone: the other chosen apps' previews and the test drive go on as monorepo says, and the tasks fail only where no app has a preview. Done when the report says so.
 
 ### Reference
 
-- **Already on Impeccable's tunnel**: a repository whose state shows `ci-tunnel` as the preview's method, with its workflow committed, keeps working as it is. Change nothing about that preview: a host the person picks here replaces it once its preview is saved, and after a skip the tunnel stays, which the report says in place of the step for `left`.
+- **Already on Impeccable's tunnel**: a repository whose state shows `ci-tunnel` as the preview's method, with its workflow committed, keeps working as it is. Change nothing about that preview: a host the person picks here replaces it once its preview is saved, and after a skip the tunnel stays, which the report says.
 - **Never save `ci-tunnel`**: impeccable_write refuses it.
 - The sign-in case applies all the same: the accounts serve the host's previews once they come.

package/dist/playbook/cases/vercel-previews.md

@@ -9,6 +9,7 @@ Vercel deploys previews of the pull requests: impeccable_hosted_previews lists a
 
 ### Reference
 
+- **The aim** holds here: the CLI does the work, and the person is asked only what the playbook's aim allows.
 - **Behind Vercel's login** (`gate: "vercel-protection"`): Deployment Protection stands in front of the previews. Get past it as preview-protection says, which proves the preview, and go on with step 2; when nothing got past it, that case says how the run ends.
 - **Another app, or no answer from any of the three**: Vercel's previews do not show this app. Set the preview up as server-previews or static-site says instead, and say under "What is not verified" what the Vercel address answered.
 - **The pull requests**: no setup pull request; the test drive branches from the default branch, and Vercel builds its preview from the push, which pull-requests' step 4 waits for and proves the test drive's page on before the pull request opens. In place of pull-requests' step 3, build the test drive branch once with the install and build Vercel runs (`vercel.json`'s `installCommand` and `buildCommand`, else the package's), as plain commands (`pnpm install`, then `pnpm run build`) and not with impeccable_verify_preview, which is for a preview Impeccable starts itself, so a page that does not build is never pushed.

package/dist/playbook/cases/vercel-setup.md

@@ -10,20 +10,21 @@ The checkout is set up for Vercel (`vercel.json`, `.vercel/project.json`, a `ver
    - **Neither `team` nor `teams`**: the account has no team, and `vercel link --yes` without `--team` links in the person's own scope.
    - **Skip**: set the preview up as server-previews or static-site says, and say under "What was skipped, and why" that Vercel was found and the sign-in was skipped. The steps below do not apply.
 2. **Create the project** (run each Vercel command plain: its answer is short, and a pipe to `tail` is refused): `vercel link --yes --team <the team>` creates the project in that team, named after the folder (or links the one that has that name), and connects the GitHub `origin`; the CLI names no team on its own without a terminal, so the option is given whenever there is a team. Done when it prints the linked project.
-3. **Connect the repository, and lock the project before its first deployment**, with impeccable_vercel_connect: it runs the connection on the linked project, asks the person for Vercel's GitHub app's access when the app cannot reach the repository, and then, on a project with no production deployment, puts Vercel's login in front of every address of the project, its own included. Vercel makes a new project's first deployment Production whatever branch it builds and serves it at the project's own address, and the test drive's push is that first deployment. Done when it answered `connected: true` with `production: "exists"` or `locked: true`; a project connected by the link already is, and it says so.
+3. **Connect the repository, and lock the project before its first deployment**, with impeccable_vercel_connect: it runs the connection on the linked project, asks the person for Vercel's GitHub app's access when the app cannot reach the repository, and then, on a project with no production deployment, puts Vercel's login in front of every address of the project, its own included. Vercel makes a new project's first deployment Production whatever branch it builds and serves it at the project's own address, and the test drive's push is that first deployment. When Vercel refuses the lock, the tool asks the person on one screen to turn it on in the project's settings and waits for it. Done when it answered `connected: true` with `production: "exists"` or `locked: true`; a project connected by the link already is, and it says so.
 4. **Build and push the test drive** (the Test drive task) as pull-requests' steps 2 to 4 say, with the changes vercel-previews' reference gives: from the default branch, no setup pull request, built once with plain commands. Stage its files by name: `vercel link` writes `.vercel/` and a `.env.local` that holds a Vercel token, and may add `.vercel` to `.gitignore`, and none of that goes into the pull request. Its push starts the project's first deployment. Done when `git push -u origin impeccable/test-drive` succeeded.
 5. **Its preview, proven and saved, then its pull request** as pull-requests' step 4 (Vercel) and step 5 say: the wait for the pushed head's deployment, the test drive's page proven on the address it lists (past Vercel's login as preview-protection says), impeccable_write to `preview` as vercel-previews' step 2 says, then the pull request and its recording. The playbook's step 6 then has no pull request left to open: go on with the playbook's step 4. Done when impeccable_test_pr answered "Recorded".
 
 ### Reference
 
+- **The aim** holds here: the CLI does the work, and the person is asked only what the playbook's aim allows.
 - **A step fails before the test drive is pushed** (the sign-in skipped or not completed, the team skipped, the project not created, the repository not connected): the Vercel setup ends there. Set the preview up as server-previews or static-site says, say under "What was skipped, and why" what stopped it, and put the person's step in `left` when there is one, such as "Give Vercel's GitHub app access to the repository", with the `access` page in the report.
 - **A push before step 3** is refused, since a connected project builds every push: run impeccable_vercel_connect first.
-- **`locked: false`** from step 3, with `production` not "exists": push nothing, and set up no other preview either, since the connected project would build that push as its first deployment, public at its own address. Mark the Test drive task failed, say under "What was skipped, and why" what stopped the lock (the answer's `reason`) and how the person locks the project (Vercel Authentication for All Deployments, under the project's Settings → Deployment Protection), and put "Lock the Vercel project, then run the setup again" in `left`.
+- **`locked: false`** from step 3, with `production` not "exists" (the person skipped the tool's screen, or the lock was still off after its retries): push nothing, and set up no other preview either, since the connected project would build that push as its first deployment, public at its own address. Mark the Test drive task failed, and say under "What was skipped, and why" what stopped the lock (the answer's `reason`).
 - **No preview for the pushed test drive**: save no method, set up no other preview and open no pull request, as pull-requests' "No preview, no test drive" says; the project and the connection stay, and the report names them.
-  - **The build failed** (`state` is `failure` or `error`): `vercel deploy --yes` builds this checkout on Vercel and prints why it failed, so the report can name the cause.
-  - **No deployment within five minutes**: the build had not finished, or Vercel builds no push here: the project's Git connection is the thing to check, and "Run the setup again once Vercel builds the repository" goes in `left`.
+  - **The build failed** (`state` is `failure` or `error`): `vercel deploy --yes` builds this checkout on Vercel and prints why it failed. When the cause is in the test drive's own change, correct it, commit, push once more and wait for that build; else the report names the cause.
+  - **No deployment within five minutes**: the wait's own screen opens the project's Git settings and waits again on the person's yes. When they skip it, or none came after its retries, say under "What is not verified" that Vercel built no push here, and that the project's Git connection is the thing to check.
   - **Behind Vercel's login** (`gate: "vercel-protection"`) with nothing getting past it: preview-protection says what the report names.
-- **The first deployment** of a new project is called Production, whatever branch it builds. Locked in step 3, and still so when its deployment is read, it is the test drive's preview: impeccable_hosted_previews lists it, and the proof opens it past Vercel's login as preview-protection says. Unlocked by then, or another project's, the evidence lists no address for it and the proof refuses it: no test drive, as "No preview for the pushed test drive" says, and the report says under "What is not verified" that Vercel serves the test drive's build at the project's own address (`vercel project ls` prints it) without a login until the default branch deploys, with the step from `locked: false` in `left`. A project that deployed production before the run (`production: "exists"`) builds the push as a Preview, and keeps its addresses as they were.
+- **The first deployment** of a new project is called Production, whatever branch it builds. Locked in step 3, and still so when its deployment is read, it is the test drive's preview: impeccable_hosted_previews lists it, and the proof opens it past Vercel's login as preview-protection says. Unlocked by then, or another project's, the evidence lists no address for it and the proof refuses it: no test drive, as "No preview for the pushed test drive" says, and the report says under "What is not verified" that Vercel serves the test drive's build at the project's own address (`vercel project ls` prints it) without a login until the default branch deploys, and that Vercel Authentication for All Deployments, under the project's Settings → Deployment Protection, puts its login back in front. A project that deployed production before the run (`production: "exists"`) builds the push as a Preview, and keeps its addresses as they were.
 - **Behind Vercel's login** (`gate: "vercel-protection"`): a project the CLI creates starts with Vercel Authentication on, and step 3 locks it at every address, so expect it, and go on as the preview-protection case says.
 - **The report** names the Vercel project and its team under "What was configured, and by whom", whichever way the run ended, since it stays in the person's Vercel account, and the CLI's install when there was one, and that the link wrote a `.env.local` with a Vercel token in the checkout. A project locked in step 3 gets this too: Vercel's login stands in front of every address of it, its production one included, until the person chooses Standard Protection under Settings → Deployment Protection, which opens production and keeps the previews behind the login. When the answer's `productionBranch` is not the repository's default branch, say under "Before you merge" that Vercel deploys production from that branch (Settings → Environments → Production → Branch Tracking changes it). The project's environment variables are the person's: when the app needs some (`.env.example`), list their names, never their values, under "Before you merge".
 - **Status lines**: the sign-in, the link, the connection and the lock belong to the Preview method task; from the page on, the Test drive task, so name the test drive in each line about its build, its push, the wait for its preview, the proof and the save (*"Saving the test drive's preview as the method"*). Word Vercel's login as a login, since a line about signing in belongs to the Sign-in task.

package/dist/playbook/github-previews.js

@@ -0,0 +1,101 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const LIMIT = 20;
+const COVERAGE = 'Only the 20 newest GitHub deployments, their latest statuses, and the 20 most recently updated pull requests are checked. A missing match does not prove previews are absent. Empty GitHub deployment history does not prove that a live app or host previews do not exist. A deployment URL does not prove the application rendered.';
+const FAILURE = 'GitHub preview evidence could not be read completely.';
+const STATES = ['error', 'failure', 'inactive', 'in_progress', 'queued', 'pending', 'success'];
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+function sha(value) {
+    return typeof value === 'string' && /^[a-f0-9]{40}$/.test(value);
+}
+function previewUrl(value) {
+    if (typeof value !== 'string' || value.length > 2048 || !/^https:\/\/[^\s\\?#]+$/i.test(value))
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password || url.search || url.hash || /^https:\/\/[^/]*@/i.test(value))
+            return null;
+        return url.href;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read a bounded projection of GitHub evidence; never return response bodies or command errors. */
+export async function readHostedPreviews(owner, repo, dependencies = {}) {
+    if (!/^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(owner)
+        || !/^[a-zA-Z0-9_.-]{1,100}$/.test(repo) || repo === '.' || repo === '..') {
+        return { coverage: COVERAGE, deployments: [], error: FAILURE };
+    }
+    const runGh = dependencies.runGh ?? (async (args) => {
+        const { stdout } = await execFileAsync('gh', args, {
+            encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024, signal: dependencies.signal,
+        });
+        return stdout;
+    });
+    const base = `/repos/${owner}/${repo}`;
+    async function get(route) {
+        if (dependencies.signal?.aborted)
+            throw new Error(FAILURE);
+        const stdout = await runGh(['api', '--hostname', 'github.com', '--method', 'GET', route]);
+        if (dependencies.signal?.aborted)
+            throw new Error(FAILURE);
+        const data = JSON.parse(stdout);
+        if (!Array.isArray(data))
+            throw new Error(FAILURE);
+        return data.slice(0, LIMIT);
+    }
+    try {
+        const [deployments, pulls] = await Promise.all([
+            get(`${base}/deployments?per_page=${LIMIT}`),
+            get(`${base}/pulls?state=all&sort=updated&direction=desc&per_page=${LIMIT}`),
+        ]);
+        let incomplete = false;
+        const evidence = [];
+        for (const entry of deployments) {
+            if (dependencies.signal?.aborted) {
+                incomplete = true;
+                break;
+            }
+            const deployment = record(entry);
+            if (!deployment || !positiveInteger(deployment.id) || !sha(deployment.sha))
+                continue;
+            let latest;
+            try {
+                latest = record((await get(`${base}/deployments/${deployment.id}/statuses?per_page=1`))[0]);
+            }
+            catch {
+                incomplete = true;
+                if (dependencies.signal?.aborted)
+                    break;
+            }
+            const status = STATES.find((state) => state === latest?.state) ?? null;
+            const environment = typeof deployment.environment === 'string' && deployment.environment.length <= 100
+                && !/[\u0000-\u001f\u007f]/.test(deployment.environment) ? deployment.environment : null;
+            const pullRequests = [];
+            for (const item of pulls) {
+                const pull = record(item);
+                if (pull && positiveInteger(pull.number) && (pull.state === 'open' || pull.state === 'closed')
+                    && record(pull.head)?.sha === deployment.sha) {
+                    pullRequests.push({ number: pull.number, state: pull.state });
+                }
+            }
+            evidence.push({ id: deployment.id, sha: deployment.sha, environment, status,
+                previewUrl: status ? previewUrl(latest?.environment_url) : null, pullRequests });
+        }
+        incomplete ||= dependencies.signal?.aborted ?? false;
+        return { coverage: COVERAGE, deployments: evidence,
+            ...(incomplete ? { error: FAILURE } : { emptyDeploymentHistory: deployments.length === 0 }) };
+    }
+    catch {
+        return { coverage: COVERAGE, deployments: [], error: FAILURE };
+    }
+}

package/dist/playbook/netlify-pattern.js

@@ -0,0 +1,24 @@
+/** Keep Netlify's repository-wide pattern tied to successful discovery evidence. */
+export function netlifyPatternError(body, observed) {
+    const pattern = body.previewUrlPattern;
+    if (typeof pattern !== 'string')
+        return null;
+    let netlify = /netlify\.app|<site>/i.test(pattern);
+    try {
+        const hostname = new URL(pattern.replaceAll('{pr}', '1')).hostname;
+        netlify ||= hostname === 'netlify.app' || hostname.endsWith('.netlify.app');
+    }
+    catch { /* The canonical validation below rejects malformed Netlify patterns. */ }
+    if (!netlify)
+        return null;
+    const match = /^https:\/\/deploy-preview-\{pr\}--([a-z0-9](?:[a-z0-9-]*[a-z0-9])?)\.netlify\.app$/.exec(pattern);
+    if (!match || match[1].length > 63)
+        return 'Use a real Netlify site pattern from successful preview evidence; placeholders and malformed patterns are not saved.';
+    if (Object.hasOwn(body, 'appKey'))
+        return 'A Netlify preview URL pattern belongs to the repository; omit appKey.';
+    if (body.intendedMethod !== 'preview-deploy')
+        return 'Save a Netlify pattern with intendedMethod preview-deploy.';
+    if (!observed.has(pattern))
+        return 'Read this repository\'s Netlify previews first and choose a pattern backed by a successful current-head status.';
+    return null;
+}

package/dist/playbook/netlify-previews.js

@@ -0,0 +1,144 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const FAILURE = 'Netlify preview evidence could not be read completely.';
+const COVERAGE = 'Only the 20 most recently updated pull requests, the newest 100 statuses on each exact head SHA, and the 100 most recently updated repository issue comments are checked. Context-derived URLs do not prove the application rendered. Bot comments are historical candidates, not current-head deployment proof. Missing evidence does not prove previews are absent.';
+const SITE = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const CONTEXT = new RegExp(`^netlify/(${SITE})/deploy-preview$`);
+const PREVIEW_HOST = new RegExp(`^deploy-preview-([1-9][0-9]*)--(${SITE})\\.netlify\\.app$`);
+const STATES = ['success', 'pending', 'failure', 'error'];
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : undefined;
+}
+function cleanUrl(value) {
+    if (typeof value !== 'string' || value.length > 2048 || !/^https:\/\/[^\s\\?#@]+$/i.test(value))
+        return;
+    try {
+        const url = new URL(value);
+        if (!url.username && !url.password && !url.port && !url.search && !url.hash)
+            return url;
+    }
+    catch { /* Discard unsafe evidence without returning it. */ }
+}
+function urls(pull, site) {
+    if (`deploy-preview-${pull.number}--${site}`.length > 63)
+        return;
+    return {
+        previewUrl: `https://deploy-preview-${pull.number}--${site}.netlify.app/`,
+        previewUrlPattern: `https://deploy-preview-{pr}--${site}.netlify.app`,
+    };
+}
+function validTarget(value, pull, site) {
+    if (value === null || value === undefined || value === '')
+        return true;
+    const target = cleanUrl(value);
+    if (!target)
+        return false;
+    if (target.hostname === `deploy-preview-${pull.number}--${site}.netlify.app` && target.pathname === '/')
+        return true;
+    return target.hostname === 'app.netlify.com'
+        && new RegExp(`^/(?:sites|projects)/${site}/deploys(?:/[a-zA-Z0-9_-]+)?/?$`).test(target.pathname);
+}
+/** Read a bounded, repository-scoped projection; never expose comments, command errors or credentials. */
+export async function readNetlifyPreviews(owner, repo, dependencies = {}) {
+    const previews = [];
+    if (!/^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(owner)
+        || !/^[a-zA-Z0-9_.-]{1,100}$/.test(repo) || repo === '.' || repo === '..') {
+        return { coverage: COVERAGE, previews, error: FAILURE };
+    }
+    const runGh = dependencies.runGh ?? (async (args) => {
+        const { stdout } = await execFileAsync('gh', args, {
+            encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024, signal: dependencies.signal,
+        });
+        return stdout;
+    });
+    const base = `/repos/${owner}/${repo}`;
+    async function get(route, limit) {
+        if (dependencies.signal?.aborted)
+            throw new Error();
+        const raw = await runGh(['api', '--hostname', 'github.com', '--method', 'GET', route]);
+        if (dependencies.signal?.aborted)
+            throw new Error();
+        const data = JSON.parse(raw);
+        if (!Array.isArray(data))
+            throw new Error();
+        return data.slice(0, limit);
+    }
+    const [pullRead, commentRead] = await Promise.allSettled([
+        get(`${base}/pulls?state=all&sort=updated&direction=desc&per_page=20`, 20),
+        get(`${base}/issues/comments?sort=updated&direction=desc&per_page=100`, 100),
+    ]);
+    if (pullRead.status === 'rejected')
+        return { coverage: COVERAGE, previews, error: FAILURE };
+    let incomplete = false;
+    const warnings = commentRead.status === 'rejected'
+        ? ['Historical Netlify bot comments could not be read. Current-head status evidence is still checked.'] : [];
+    const pulls = new Map();
+    for (const item of pullRead.value) {
+        const pull = record(item);
+        const headSha = record(pull?.head)?.sha;
+        if (!pull || typeof pull.number !== 'number' || !Number.isSafeInteger(pull.number) || pull.number <= 0
+            || (pull.state !== 'open' && pull.state !== 'closed') || typeof headSha !== 'string' || !/^[a-f0-9]{40}$/.test(headSha))
+            continue;
+        const issueUrl = `https://api.github.com${base}/issues/${pull.number}`;
+        if (!pulls.has(issueUrl))
+            pulls.set(issueUrl, { number: pull.number, state: pull.state, headSha });
+    }
+    const seen = new Set();
+    const statusesBySha = new Map();
+    for (const pull of pulls.values()) {
+        if (dependencies.signal?.aborted) {
+            incomplete = true;
+            break;
+        }
+        try {
+            if (!statusesBySha.has(pull.headSha)) {
+                statusesBySha.set(pull.headSha, get(`${base}/commits/${pull.headSha}/statuses?per_page=100`, 100));
+            }
+            for (const item of await statusesBySha.get(pull.headSha)) {
+                const status = record(item);
+                const site = typeof status?.context === 'string' ? CONTEXT.exec(status.context)?.[1] : undefined;
+                if (!site || seen.has(`${pull.number}:${site}`))
+                    continue;
+                // GitHub returns newest first: even an invalid latest entry must hide older success.
+                seen.add(`${pull.number}:${site}`);
+                const state = STATES.find((state) => state === status?.state);
+                const canonical = urls(pull, site);
+                if (!state || !canonical || !validTarget(status?.target_url, pull, site))
+                    continue;
+                previews.push({ pullRequest: pull.number, state: pull.state, headSha: pull.headSha, site,
+                    status: state, ...canonical, source: 'commit-status', matchesHead: true });
+            }
+        }
+        catch {
+            incomplete = true;
+        }
+    }
+    if (!dependencies.signal?.aborted && commentRead.status === 'fulfilled') {
+        for (const item of commentRead.value) {
+            const comment = record(item);
+            const author = record(comment?.user);
+            const pull = typeof comment?.issue_url === 'string' ? pulls.get(comment.issue_url) : undefined;
+            if (!pull || author?.login !== 'netlify[bot]' || author.type !== 'Bot'
+                || typeof comment?.body !== 'string' || comment.body.length > 65_536)
+                continue;
+            for (const match of comment.body.matchAll(/https:\/\/[^\s<>"'()[\]`]+/gi)) {
+                const url = cleanUrl(match[0].replace(/[.,;:]+$/, ''));
+                const parts = url ? PREVIEW_HOST.exec(url.hostname) : null;
+                if (!url || url.pathname !== '/' || !parts || parts[1] !== String(pull.number))
+                    continue;
+                const site = parts[2];
+                const canonical = urls(pull, site);
+                if (!canonical || seen.has(`${pull.number}:${site}`))
+                    continue;
+                seen.add(`${pull.number}:${site}`);
+                previews.push({ pullRequest: pull.number, state: pull.state, headSha: pull.headSha, site,
+                    status: null, ...canonical, source: 'bot-comment', matchesHead: false });
+            }
+        }
+    }
+    if (dependencies.signal?.aborted)
+        incomplete = true;
+    return { coverage: COVERAGE, previews, ...(warnings.length ? { warnings } : {}), ...(incomplete ? { error: FAILURE } : {}) };
+}

package/dist/playbook/probe-preview.js

@@ -0,0 +1,67 @@
+function redirectGate(location, source) {
+    if (!location)
+        return 'redirected';
+    try {
+        const target = new URL(location, source);
+        if (target.protocol !== 'https:')
+            return 'redirected';
+        if (target.origin === 'https://vercel.com' && target.pathname === '/sso-api'
+            && target.searchParams.has('url'))
+            return 'vercel-protection';
+        if ((target.hostname === 'vercel.com' || target.hostname.endsWith('.vercel.com'))
+            && /^\/login(?:\/|$)/.test(target.pathname))
+            return 'vercel-protection';
+        if (target.hostname.endsWith('.cloudflareaccess.com'))
+            return 'cloudflare-access';
+        if (target.origin === source.origin && /^\/(?:login|sign-in|signin)(?:\/|$)/.test(target.pathname)) {
+            return 'app-sign-in';
+        }
+    }
+    catch {
+        // A malformed redirect reveals nothing about preview protection.
+    }
+    return 'redirected';
+}
+/** An unauthenticated HTTP check only: reachable does not prove this is the intended app. */
+export async function probePreview(url, dependencies = {}) {
+    let target;
+    try {
+        target = new URL(url);
+        if (!isPlatformPreview(target)
+            || /[?#\\\s]/.test(url) || !/^https:\/\//i.test(url))
+            throw new Error();
+    }
+    catch {
+        return { status: null, gate: 'unavailable', error: 'invalid-preview-url' };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    const signal = dependencies.signal
+        ? AbortSignal.any([controller.signal, dependencies.signal])
+        : controller.signal;
+    try {
+        signal.throwIfAborted();
+        const response = dependencies.fetch ? await dependencies.fetch(target, {
+            method: 'GET',
+            headers: { accept: 'text/html' },
+            credentials: 'omit',
+            redirect: 'manual',
+            signal,
+        }) : await publicPreviewRequest(target, signal);
+        const status = response.status;
+        const gate = status === 401 && response.headers.get('x-vercel-error') === 'UNAUTHORIZED'
+            ? 'vercel-protection' : status >= 300 && status < 400
+            ? redirectGate(response.headers.get('location'), target)
+            : status >= 200 && status < 300 ? 'reachable' : 'unavailable';
+        // Bodies and redirect details may contain credentials; never read or return them.
+        await response.body?.cancel().catch(() => undefined);
+        return { status, gate };
+    }
+    catch {
+        return { status: null, gate: 'unavailable', error: 'request-failed' };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+import { isPlatformPreview, publicPreviewRequest } from './public-preview-request.js';

package/dist/playbook/protection-secrets.js

@@ -0,0 +1,15 @@
+/** Register credential-shaped write fields before a message can be recorded.
+ * Do not trust the requested path: even a refused or malformed destination must
+ * keep its supplied credentials private. Values remain unchanged in memory.
+ */
+export function protectionWriteSecrets(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return [];
+    const body = input.body;
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return [];
+    return ['value', 'clientId', 'clientSecret']
+        .map((key) => body[key])
+        .filter((value) => typeof value === 'string' && value.length > 0)
+        .sort((a, b) => b.length - a.length);
+}

package/dist/playbook/public-preview-request.js

@@ -0,0 +1,96 @@
+import { lookup } from 'node:dns/promises';
+import { request } from 'node:https';
+import { BlockList, isIP } from 'node:net';
+const blockedV4 = new BlockList();
+for (const [address, prefix] of [
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+    ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+    ['192.88.99.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24],
+    ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
+])
+    blockedV4.addSubnet(address, prefix, 'ipv4');
+const publicV6 = new BlockList();
+publicV6.addSubnet('2000::', 3, 'ipv6');
+const blockedV6 = new BlockList();
+// Conservatively exclude special-purpose, transition and documentation prefixes.
+for (const [address, prefix] of [
+    ['2001::', 23], ['2001:db8::', 32], ['2002::', 16], ['3fff::', 20],
+])
+    blockedV6.addSubnet(address, prefix, 'ipv6');
+export function isPlatformPreview(target) {
+    return target.protocol === 'https:' && !target.username && !target.password && !target.port
+        && !/[?#]/.test(target.href)
+        && /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:vercel|netlify)\.app$/.test(target.hostname);
+}
+function isPublicAddress(value) {
+    if (!value || typeof value.address !== 'string' || value.address.includes('%'))
+        return false;
+    const family = isIP(value.address);
+    if (family !== value.family)
+        return false;
+    if (family === 4)
+        return !blockedV4.check(value.address, 'ipv4');
+    return family === 6 && publicV6.check(value.address, 'ipv6') && !blockedV6.check(value.address, 'ipv6');
+}
+/** Resolve once, validate every answer, then connect only to the pinned public addresses. */
+export async function publicPreviewRequest(target, signal, dependencies = {}) {
+    try {
+        if (!isPlatformPreview(target))
+            throw new Error();
+        signal.throwIfAborted();
+        let abortDns = () => { };
+        const aborted = new Promise((_resolve, reject) => {
+            abortDns = () => reject(new Error());
+            signal.addEventListener('abort', abortDns, { once: true });
+        });
+        const addresses = await Promise.race([
+            (dependencies.lookup ?? lookup)(target.hostname, { all: true, verbatim: true }), aborted,
+        ]).finally(() => signal.removeEventListener('abort', abortDns));
+        signal.throwIfAborted();
+        if (!Array.isArray(addresses) || !addresses.length || !addresses.every(isPublicAddress))
+            throw new Error();
+        const pinned = addresses.map(({ address, family }) => ({ address, family }));
+        return await new Promise((resolve, reject) => {
+            const options = {
+                method: 'GET', headers: { accept: 'text/html' }, signal,
+                agent: false, autoSelectFamily: true, rejectUnauthorized: true,
+                lookup(hostname, options, callback) {
+                    if (hostname !== target.hostname)
+                        return callback(new Error('Preview request failed'), '');
+                    if (options.all)
+                        callback(null, pinned.map((address) => ({ ...address })));
+                    else
+                        callback(null, pinned[0].address, pinned[0].family);
+                },
+            };
+            const req = (dependencies.request ?? request)(target, options, (response) => {
+                response.once('error', () => { });
+                try {
+                    const status = response.statusCode;
+                    const headers = new Headers();
+                    for (const name of ['location', 'x-vercel-error']) {
+                        const value = response.headers[name];
+                        if (typeof value === 'string')
+                            headers.set(name, value);
+                    }
+                    if (!status)
+                        reject(new Error());
+                    else
+                        resolve({ status, headers, body: null });
+                }
+                catch {
+                    reject(new Error());
+                }
+                finally {
+                    response.destroy();
+                }
+            });
+            req.once('error', () => reject(new Error()));
+            req.once('upgrade', (_response, socket) => { socket.destroy(); reject(new Error()); });
+            req.end();
+        });
+    }
+    catch {
+        throw new Error('Preview request failed');
+    }
+}

package/dist/playbook/publication-wait.js

@@ -0,0 +1,46 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+const INTERVAL_MS = 30_000;
+const DEADLINE_MS = 8 * 60_000;
+/** One publication deadline per setup PR, including time spent checking the preview. */
+export function createPublicationWait(dependencies = {}) {
+    const now = dependencies.now ?? (() => performance.now());
+    const pause = dependencies.sleep ?? ((ms, signal) => sleep(ms, undefined, { signal }));
+    const starts = new Map();
+    return {
+        begin(pr) {
+            if (!starts.has(pr))
+                starts.set(pr, now());
+        },
+        remainingMs(pr) {
+            const start = starts.get(pr);
+            return start === undefined ? null : Math.max(0, DEADLINE_MS - (now() - start));
+        },
+        async wait(pr, signal) {
+            const start = starts.get(pr);
+            if (start === undefined)
+                return null;
+            const result = (status) => {
+                const elapsed = Math.max(0, now() - start);
+                return {
+                    status,
+                    waited_seconds: Math.floor(elapsed / 1000),
+                    remaining_seconds: Math.ceil(Math.max(0, DEADLINE_MS - elapsed) / 1000),
+                };
+            };
+            if (signal?.aborted)
+                return result('cancelled');
+            const remaining = DEADLINE_MS - (now() - start);
+            if (remaining <= 0)
+                return result('timed-out');
+            try {
+                await pause(Math.min(INTERVAL_MS, remaining), signal);
+            }
+            catch {
+                return result('cancelled');
+            }
+            if (signal?.aborted)
+                return result('cancelled');
+            return result(now() - start >= DEADLINE_MS ? 'timed-out' : 'retry');
+        },
+    };
+}