@impeccable/reviews 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Renaissance Geek, Inc. All rights reserved.
+
+This software is proprietary. You may install and run it only to set up and
+use Impeccable (https://impeccable.reviews), subject to Impeccable's Terms of
+Service at https://impeccable.reviews/terms. You may not copy, modify,
+distribute, sublicense, or reverse engineer it, except as those terms or
+applicable law allow.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL RENAISSANCE
+GEEK, INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -29,13 +29,14 @@ Keys: Enter goes on, Esc cancels the intro or the sign-in and skips a question (
 | `--yes` | off | Runs the allowlisted commands without asking, which they already do; anything off the list is still refused. |
 | `--debug` | off | Writes a debug log and a transcript of the run (`transcript-<run>.md`, with its raw events in `transcript-<run>.jsonl`) to the temp folder, tokens removed, and prints where they are. |
 | `--transcript <path>` | the temp folder | Writes the transcript there instead: a folder, or a `.md` file with the `.jsonl` beside it. |
+| `--scan-report` | off | Writes what the fence's content checks found (`scan-report-<run>.json`: each match's check, where it was, the tool and what it did, never the text, with counts per check) beside the transcript, and prints where it is. |
 | `--frames <dir>` | off | Writes each screen into the folder as it changes (`NNN-<state>.ansi` with its styling, `NNN-<state>.txt`, and `index.json`), for the eval. |
 
 ## What happens
 
 1. **Sign in.** The consent page (pick the organization and this repository) answers a small server on the first free port of 8239, 8238, 8240, 8237, 8236 and 8235, with PKCE and a state check, then sends the browser on to the run's web page. On a remote shell, press P and paste the address the browser ends on.
 2. **A web front end?** Impeccable reviews web front ends, mobile web included. A checkout with none (a React Native, Expo or Flutter app without a web target, or a service with no page, template, stylesheet or web framework) ends here: the terminal and the web page say "Impeccable reviews web front ends, and this repository does not have one. Nothing was set up.", and it exits 2. When the checkout cannot tell, Impeccable's own scan decides. A checkout with a web front end that the scan skipped stops the same way, with the setup page, where the person chooses Add anyway before running it again.
-3. **Set up.** On a run with its own capped model token (model calls go through Impeccable's gateway, so this machine holds no model key), the agent reads the checkout, runs the build, saves settings through the setup API, and asks you in a dialog only what it cannot find out. It never asks you to run a command: what it cannot run goes into the report, with the command. When Vercel or Netlify already deploys previews of your pull requests, it opens the newest one (Netlify's it finds on GitHub, and through the Netlify CLI when you are signed in to it on this machine, read only), and once that page is your app it takes the host's previews as they are, with no question and no setup pull request. When the repository is set up for Vercel or Netlify but that host has never previewed it, it asks you for one thing, to sign in to the host, and only when its CLI on this machine is signed out: one screen, Sign in or Skip, the login in your browser on Enter, and a retry when it did not complete (two failed retries count as a skip). Then it does the rest itself. On Vercel it creates the project with `vercel link` in the team the CLI's current scope names (asking which, only when you have several and none is current), connects the repository, pushes the test drive and waits up to five minutes for Vercel's build of it (the task in progress carries the timer, "1:05 of 5:00"), proves that preview, takes Vercel's previews as they are and only then opens the test drive's pull request, so its review renders; a new project starts with Vercel Authentication on, which the run gets past with a bypass secret on your yes. On Netlify it creates the site in your Netlify team (asking which, only when you have several), connects the repository through Netlify's site settings and Netlify's GitHub app, so pull requests get deploy previews, pushes the test drive and opens it as a draft, which Impeccable leaves unreviewed, waits for its deploy preview, proves it, takes Netlify's previews as they are and marks the draft ready. When the host's GitHub app cannot reach the repository, one more screen opens the app's page on GitHub for you to give it access, and the run waits. On skip it builds Impeccable's own previews as usual.
+3. **Set up.** On a run with its own capped model token (model calls go through Impeccable's gateway, so this machine holds no model key), the agent reads the checkout, runs the build, saves settings through the setup API, and asks you in a dialog only what it cannot find out. It never asks you to run a command: what it cannot run goes into the report, with the command. When Vercel, Netlify or Cloudflare Pages already deploys previews of your pull requests, it opens the newest one (Netlify's it finds on GitHub, and through the Netlify CLI when you are signed in to it on this machine, read only; Cloudflare's in the check run and the comment Cloudflare's GitHub app posts, and through wrangler when you are signed in to it here, read only), and once that page is your app it takes the host's previews as they are, with no question and no setup pull request. When the repository is set up for Vercel or Netlify but that host has never previewed it, it asks you for one thing, to sign in to the host, and only when its CLI on this machine is signed out: one screen, Sign in or Skip, the login in your browser on Enter, and a retry when it did not complete (two failed retries count as a skip). Then it does the rest itself. On Vercel it creates the project with `vercel link` in the team the CLI's current scope names (asking which, only when you have several and none is current), connects the repository, puts Vercel's login in front of every address of the new project before pushing anything (Vercel makes a new project's first deployment production, whatever branch it builds, and would serve the test drive at the project's own address otherwise; the report says how to open production once your default branch is live), pushes the test drive and waits up to five minutes for Vercel's build of it (the task in progress carries the timer, "1:05 of 5:00"), proves that preview, takes Vercel's previews as they are and only then opens the test drive's pull request, so its review renders; a new project starts with Vercel Authentication on, which the run gets past with a bypass secret on your yes. On Netlify it creates the site in your Netlify team (asking which, only when you have several), connects the repository through Netlify's site settings and Netlify's GitHub app, so pull requests get deploy previews, pushes the test drive and opens it as a draft, which Impeccable leaves unreviewed, waits for its deploy preview, proves it, takes Netlify's previews as they are and marks the draft ready. When the host's GitHub app cannot reach the repository, one more screen opens the app's page on GitHub for you to give it access, and the run waits. On skip it builds Impeccable's own previews as usual.
 4. **Two pull requests,** opened as you with `gh`, even when something is left for a person, which goes into the report, both into the default branch and in this order:
    - the test drive, safe to close (`impeccable/test-drive`, "Impeccable test drive (safe to close)"), always: a few real style or layout changes on a page the preview renders, on top of the setup commit when there is one, so it carries the workflow, whose job builds the preview on the pull request while Impeccable's review waits for it. Its pull request opens only once its preview is proven: the host's build of the pushed branch, or the local proof of Impeccable's own preview. No preview, no test drive: the run then says why in the report and what you can do, and still opens the setup pull request when the repository needs one;
    - the setup pull request, to merge (`impeccable/setup`, "Set up Impeccable previews"), only when the repository needs a change to keep previews working: the preview workflow, any fix the build needed.
@@ -45,13 +46,13 @@ The sign-in's setup token lasts an hour. A run that goes longer asks you to sign
 
 ## What the agent may run
 
-The fence keeps the setup to its own steps and out of `.env` files; it is not a sandbox: the repository's scripts and builds run as you, with your files and your `gh` and git sign-ins, as they would for a developer, but without the tokens, keys and passwords in your environment.
+The fence keeps the setup to its own steps and out of `.env` files; it is not a sandbox: the repository's scripts and builds run as you, with your files and your `gh` and git sign-ins, as they would for a developer, but without the tokens, keys and passwords in your environment. It also reads what goes past it: text shaped like a secret (a cloud or GitHub key, a private key, a token) in a file the agent writes, a setting, a commit, a pull request or a message to you is refused, a command that names a credential file (`~/.ssh`, `.aws/credentials`, `.netrc`, `.env`) is refused, and what the agent reads gets a line saying it is data when it carries text shaped like instructions; the debug log and `--scan-report` list each match.
 
 Without asking: `git status|diff|log|show|add|commit|checkout -b|push -u origin <branch>`, `gh pr create|view` and `gh pr ready` for the test drive's branch by name (a Netlify draft, marked ready once its preview is proven), `npm|pnpm|yarn|bun install|ci`, the scripts of the package.json where the command runs (`npm run`, `pnpm run`, `bun run`, `yarn <script>`), `npx`, `pnpm exec`, `yarn` and `bunx` for `tsc`, `eslint`, `prettier`, `next`, `vite`, `astro`, `nuxt`, `prisma`, `playwright`, `drizzle-kit`, `sequelize` and `knex`, and `ls`, `cat`, `head`, `grep` and `find` inside the checkout (by relative or absolute path) and the run's scratch folder. A package manager or tool runner may have `KEY=value` settings in front; any of these may start with a `cd` into a folder of the checkout and be chained with `&&`, `||`, `;` or `|` to others on the list.
 
-`vercel whoami` and `vercel --version`. Once you are signed in to Vercel for the setup: `vercel link --yes`, `vercel project add|ls`, `vercel git connect` and `vercel deploy` for a preview, on the project named after the folder and in the one team the sign-in settled on (the CLI's current scope, your only team, or the one you pick when it asks): no other `--scope`, `--team` or `--project`, and a global install of the Vercel CLI itself when it is missing (`npm install -g vercel`, or your package manager's global add). The sign-in (`vercel login`) is the run's own tool, never the agent's command. Never a production deploy, a project's removal, its environment variables or protection settings (`vercel project protection`, `api` and `curl` print a project's bypass secrets, so the agent's shell never runs them), or a token on the command line.
+`vercel whoami` and `vercel --version`. Once you are signed in to Vercel for the setup: `vercel link --yes`, `vercel project add|ls`, `vercel git connect` and `vercel deploy` for a preview, on the project named after the folder and in the one team the sign-in settled on (the CLI's current scope, your only team, or the one you pick when it asks): no other `--scope`, `--team` or `--project`, and a global install of the Vercel CLI itself when it is missing (`npm install -g vercel`, or your package manager's global add). The sign-in (`vercel login`) is the run's own tool, never the agent's command. Never a production deploy, a project's removal, its environment variables or protection settings (`vercel project protection`, `api` and `curl` print a project's bypass secrets, so the agent's shell never runs them; the lock before a new project's first deployment and the bypass secret are the run's own tools), or a token on the command line.
 
-`netlify --version` and `netlify status`. Once you are signed in to Netlify for the setup: `netlify link`, `netlify sites:create` and `netlify deploy` for a deploy preview (`--build --context deploy-preview`), in your own current Netlify team, or with `--account-slug` for the one team you picked when the run asked, and a global install of the Netlify CLI itself when it is missing (`npm install -g netlify-cli`, or your package manager's global add). The sign-in (`netlify login`) and the repository's connection (the site's settings, through Netlify's API) are the run's own tools, never the agent's commands; `netlify init` never runs. Never a production deploy, a site's removal, its environment variables, or a token on the command line.
+`netlify --version` and `netlify status`. Once you are signed in to Netlify for the setup: `netlify link`, `netlify sites:create` and `netlify deploy` for a deploy preview (`--build --context deploy-preview`), in your own current Netlify team, or with `--account-slug` for the one team you picked when the run asked, and a global install of the Netlify CLI itself when it is missing (`npm install -g netlify-cli`, or your package manager's global add). The sign-in (`netlify login`), the repository's connection (the site's settings, through Netlify's API) and the site's password (`netlify api` prints a site's settings, the password among them) are the run's own tools, never the agent's commands; `netlify init` never runs. Never a production deploy, a site's removal, its environment variables, or a token on the command line.
 
 Scratch output, such as the log of a server the agent starts, goes to a folder in the OS temp directory, never into the checkout; a `>` redirect into that run's folder is the one write outside the checkout that runs, and the agent reads what it wrote there back (the path with its symlinks resolved).
 
@@ -65,4 +66,6 @@ A test account's password, typed hidden on the account's screen (after a screen
 
 Vercel's bypass secret, which lets reviews open previews behind Vercel's login, is handled the same way. When Vercel's login stands in front of a preview, the command asks you once, on one screen, whether to create a bypass secret for Impeccable, and on your yes creates it as you through the Vercel CLI, labelled "Impeccable reviews" (`vercel api` for Vercel's protection-bypass route; an older CLI's `vercel project protection enable --protection-bypass`), then reads it back from the project's settings. A project that already holds a secret with that label gives it without a question. When the CLI is signed out, this folder is not linked, or your role cannot make one, a screen names the settings page and takes the secret you type, hidden. It opens the preview with the secret first and saves it, with the setting that sends it in the `x-vercel-protection-bypass` header, only once the page shows your app. The agent never holds it: the secret goes from the command's own process to Vercel and to Impeccable's setting, and the debug log and the transcript remove it. Vercel documents this as Protection Bypass for Automation, which every plan includes; you revoke it in the project's Settings, Deployment Protection.
 
-Working on the CLI itself (a local build, the smoke test, the evals): [docs/development.md](docs/development.md).
+Netlify's site password (Password Protection on Pro and Enterprise plans; "Project visibility: Password" on a credit-based Pro plan) is handled the same way. When a Netlify deploy preview asks for it, the command reads the site's settings through the Netlify CLI, signed in as you. For a password Netlify gives back, it asks you once, on one screen, whether to store the site password for Impeccable, and on your yes reads it from the site as you. When Netlify does not give the password back, the CLI is signed out or the site is in none of your teams, a screen takes the password you type, hidden (the run never sets one itself: the Netlify CLI takes a new password only on its command line, where any process could read it). It opens the preview with the password first, as basic credentials in the `Authorization` header (Netlify's password page asks for a password alone, so the credentials carry no username), and saves it, with the setting that sends that header, only once the page shows your app; a password that opens the preview on Netlify's own form but not in the header is reported, not saved, since reviews can send only a header. A site behind Netlify's team login (a private site, or team login protection) has no way in for tools: the run reports it and takes no method. The agent never holds the password: it goes from the command's own process to Netlify and to Impeccable's setting, and the debug log and the transcript remove it.
+
+A Cloudflare Access service token, which lets reviews open Pages previews behind Access, is handled the same way. When Access stands in front of a preview, the command asks you once, on one screen, whether to create a service token for Impeccable, and on your yes asks for a Cloudflare API token with two permissions (Access: Apps and Policies, Edit; Access: Service Tokens, Edit), since wrangler's sign-in has no scope for Access. With it the command creates the token as you, named "Impeccable reviews", and allows it in a Service Auth policy of the Access application in front of the preview (a reusable policy added to the application's list, or a policy of its own where it has its own); the API token is used for that run only and stored nowhere. On a skip, or where that cannot be done, a screen takes a client id and secret you paste, the secret hidden. It opens the preview with the token in the `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers first and saves it, with the setting that sends them, only once the page shows your app; a token it made that opens nothing is deleted, with its policy. The agent never holds either, and the debug log and the transcript remove both. You revoke it in Zero Trust, Access controls, Service credentials, Service Tokens.

package/dist/cloudflare-access.js

@@ -0,0 +1,213 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+/**
+ * Getting past Cloudflare Access the way Cloudflare documents it for tools: a service token, a client id and a client
+ * secret sent in two headers, which a Service Auth policy of the Access application in front of the previews allows.
+ * wrangler's sign-in cannot reach Access (its OAuth scopes hold none for Zero Trust), so the person gives the run a
+ * Cloudflare API token with two permissions, used in the command's own process for this run and kept nowhere. The person
+ * consents once, on the tool's screen, before anything is made; a token opens the locked address before anything saves
+ * it; neither it nor the API token goes back to the model.
+ */
+/** The headers Access reads a service token from. */
+export const ACCESS_ID_HEADER = 'CF-Access-Client-Id';
+export const ACCESS_SECRET_HEADER = 'CF-Access-Client-Secret';
+/** The name the token and its policy carry in Zero Trust, so the person knows whose they are and can revoke them. */
+export const TOKEN_NAME = 'Impeccable reviews';
+const API = 'https://api.cloudflare.com/client/v4';
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined);
+const list = (value) => (Array.isArray(value) ? value.map(record).filter((item) => item !== undefined) : []);
+/** An id Cloudflare gave, safe in a path: an account's 32 hex digits, or a UUID. */
+const uid = (value) => typeof value === 'string' && /^[0-9a-f-]{8,64}$/i.test(value);
+const PERMISSIONS = 'The Cloudflare API token cannot do this: it needs Access: Apps and Policies → Edit and Access: Service Tokens → Edit, on the account that holds the Access application.';
+/** Why a call failed, in fixed words: the token's permissions for a 401 or a 403, else the status. Cloudflare's own message never goes on. */
+const refusal = (reply, none) => (reply.ok ? none : reply.status === 401 || reply.status === 403 ? PERMISSIONS : reply.status === null ? "Cloudflare's API did not answer." : `Cloudflare's API answered ${reply.status}.`);
+/** Where an application sends Access's login: its domain, its self-hosted domains and its public destinations, each a host with an optional path. */
+function destinations(app) {
+    const uris = list(app.destinations).filter((d) => d.type === undefined || d.type === 'public').map((d) => d.uri);
+    return [app.domain, ...(Array.isArray(app.self_hosted_domains) ? app.self_hosted_domains : []), ...uris].filter((d) => typeof d === 'string' && d.length > 0);
+}
+/** Whether a destination covers the address: its host, where `*` stands for any part of a name, and its path, when it has one, the address's path or a folder above it. */
+function covers(destination, url) {
+    const [host = '', ...rest] = destination.trim().toLowerCase().replace(/^https?:\/\//, '').split('/');
+    const path = rest.join('/').replace(/\/+$/, '');
+    const pattern = (text, any) => text.split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join(any);
+    return new RegExp(`^${pattern(host, '[a-z0-9.-]*')}$`).test(url.hostname) && (!path || new RegExp(`^/${pattern(path, '.*')}(?:/|$)`).test(url.pathname));
+}
+/** An application's settings as its PUT takes them back: without what Cloudflare sets itself, its policies (sent as links), and the older name for its destinations. */
+function settingsOf(app) {
+    const own = ['id', 'uid', 'aud', 'created_at', 'updated_at', 'policies', ...('destinations' in app ? ['self_hosted_domains'] : [])];
+    return Object.fromEntries(Object.entries(app).filter(([key]) => !own.includes(key)));
+}
+/** What undoing answers when Cloudflare refused a step of it: the person removes the rest. */
+const LEFT_BEHIND = ` Some of what the run made could not be taken back: delete the service token and the policy named "${TOKEN_NAME}" in Zero Trust.`;
+/**
+ * With the person's API token: the one self-hosted Access application whose destination covers the address, in the
+ * accounts the token reaches, then the service token, then a Service Auth policy that allows it on that application. An
+ * application on reusable policies (every one the dashboard makes now) gets a reusable policy added to its list; one on
+ * policies of its own gets one of those, since the two never mix on one application. What this made is undone, last
+ * first, when a later step fails, or on `undo`, even once the run is stopped.
+ */
+async function create(key, deps) {
+    /** One call; `undoing` runs on after the run is stopped, since what it takes back would otherwise stay. */
+    const api = async (method, path, body, undoing = false) => {
+        try {
+            const res = await (deps.fetch ?? fetch)(`${API}${path}`, {
+                method,
+                headers: { authorization: `Bearer ${key}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: AbortSignal.any([AbortSignal.timeout(30_000), ...(deps.signal && !undoing ? [deps.signal] : [])]),
+            });
+            const data = record(await res.json().catch(() => undefined));
+            return res.ok && data?.success === true ? { ok: true, result: data.result } : { ok: false, status: res.status };
+        }
+        catch {
+            return { ok: false, status: null };
+        }
+    };
+    /** Every page of a list, as many as it takes: a page shorter than a full one is the last. */
+    const every = async (path, per) => {
+        const items = [];
+        for (let page = 1; page <= 20; page++) {
+            const reply = await api('GET', `${path}?per_page=${per}&page=${page}`);
+            if (!reply.ok)
+                return reply;
+            const batch = Array.isArray(reply.result) ? reply.result : [];
+            items.push(...batch);
+            if (batch.length < per)
+                break;
+        }
+        return { ok: true, result: items };
+    };
+    const url = new URL(deps.url);
+    const accounts = await every('/accounts', 50);
+    if (!accounts.ok)
+        return { reason: refusal(accounts, '') };
+    // Every account's applications, so two that cover the address, in one account or two, are never settled by the order they came in.
+    const found = [];
+    let unread;
+    for (const account of list(accounts.result)) {
+        if (!uid(account.id))
+            continue;
+        const apps = await every(`/accounts/${account.id}/access/apps`, 1000);
+        if (!apps.ok)
+            unread = apps;
+        else
+            for (const app of list(apps.result))
+                if (app.type === 'self_hosted' && uid(app.id) && destinations(app).some((d) => covers(d, url)))
+                    found.push({ account: account.id, app });
+    }
+    if (found.length > 1)
+        return { reason: `${found.length} Access applications cover ${url.host}, so which one's policy should allow the token is not clear.` };
+    if (!found.length)
+        return { reason: unread ? refusal(unread, '') : `No Access application the API token reaches covers ${url.host}.` };
+    const { account, app } = found[0];
+    const base = `/accounts/${account}/access`;
+    const links = list(app.policies).flatMap((p, i) => (uid(p.id) ? [{ id: p.id, precedence: typeof p.precedence === 'number' ? p.precedence : i + 1 }] : []));
+    let reusable = true;
+    if (links.length) {
+        const policies = await every(`${base}/policies`, 1000);
+        if (!policies.ok)
+            return { reason: refusal(policies, '') };
+        const ids = new Set(list(policies.result).map((p) => p.id));
+        reusable = links.every((link) => ids.has(link.id));
+    }
+    const undo = [];
+    const rollback = async () => {
+        let clean = true;
+        for (const step of undo.splice(0).reverse())
+            clean = (await step()).ok && clean;
+        return clean;
+    };
+    const fail = async (reply, none) => ({ reason: `${refusal(reply, none)}${(await rollback()) ? '' : LEFT_BEHIND}` });
+    const made = await api('POST', `${base}/service_tokens`, { name: TOKEN_NAME });
+    const token = record(made.ok ? made.result : undefined);
+    // The secret is shown this once: the log and the transcript learn it before anything else happens.
+    for (const part of [token?.client_secret, token?.client_id])
+        if (typeof part === 'string' && part)
+            deps.remember(part);
+    if (!uid(token?.id) || typeof token.client_id !== 'string' || typeof token.client_secret !== 'string')
+        return fail(made, 'Cloudflare answered no service token.');
+    undo.push(() => api('DELETE', `${base}/service_tokens/${token.id}`, undefined, true));
+    const rule = { name: TOKEN_NAME, decision: 'non_identity', include: [{ service_token: { token_id: token.id } }] };
+    const precedence = Math.max(0, ...links.map((link) => link.precedence)) + 1;
+    const policy = await api('POST', reusable ? `${base}/policies` : `${base}/apps/${app.id}/policies`, reusable ? rule : { ...rule, precedence });
+    const policyId = record(policy.ok ? policy.result : undefined)?.id;
+    if (!uid(policyId))
+        return fail(policy, 'Cloudflare answered no policy.');
+    if (reusable) {
+        undo.push(() => api('DELETE', `${base}/policies/${policyId}`, undefined, true));
+        const settings = settingsOf(app);
+        const linked = await api('PUT', `${base}/apps/${app.id}`, { ...settings, policies: [...links, { id: policyId, precedence }] });
+        if (!linked.ok)
+            return fail(linked, '');
+        undo.push(() => api('PUT', `${base}/apps/${app.id}`, { ...settings, policies: links }, true));
+    }
+    else
+        undo.push(() => api('DELETE', `${base}/apps/${app.id}/policies/${policyId}`, undefined, true));
+    return {
+        token: { id: token.client_id, secret: token.client_secret },
+        application: typeof app.name === 'string' && app.name ? app.name : url.host,
+        ...(typeof token.expires_at === 'string' ? { expires: token.expires_at } : {}),
+        undo: rollback,
+    };
+}
+/** The proof with the token, again while Access's login still stands in front, until Access applies a new policy or the wait runs out. */
+async function admitted(token, deps) {
+    const wait = deps.wait ?? { totalMs: 15_000, everyMs: 3_000 };
+    let proof = await deps.prove(token);
+    for (const end = Date.now() + wait.totalMs; !proof.proven && proof.gate === 'cloudflare-access' && Date.now() < end; proof = await deps.prove(token)) {
+        await sleep(wait.everyMs, undefined, { signal: deps.signal });
+    }
+    return proof;
+}
+/**
+ * Gets a service token in place for the address Cloudflare Access stands in front of, and saves only one that opens it.
+ * On the person's yes and with their API token, the run creates it and allows it in the application's policy; on a skip,
+ * or when that cannot be done or the token does not open the address (and what was made is undone), the person may paste
+ * one they made.
+ */
+export async function passCloudflareAccess(deps) {
+    const shut = (proof) => proof.reason ?? 'The address did not open with the service token.';
+    /** A token that opened the address, saved for reviews. */
+    const keep = async (token, how, made = {}) => {
+        const failed = await deps.save(token);
+        return { status: failed ? 'save-failed' : 'saved', token: how, ...made, ...(failed ? { reason: failed } : {}), value: token };
+    };
+    /** Why the run's own way ended without a token that opens the address, for the paste screen's skip. */
+    let stopped;
+    if (!(await deps.consent()))
+        stopped = 'The person skipped creating a service token.';
+    else {
+        const key = (await deps.apiToken())?.trim();
+        if (!key)
+            stopped = 'The person skipped the Cloudflare API token that creating the service token takes.';
+        else {
+            deps.remember(key);
+            const made = await create(key, deps);
+            if ('reason' in made)
+                stopped = made.reason;
+            else {
+                // A token that opens nothing is no use to anyone, nor is one a stopped run leaves behind: it and its policy go.
+                const proof = await admitted(made.token, deps).catch(async (err) => {
+                    await made.undo();
+                    throw err;
+                });
+                if (proof.proven)
+                    return keep(made.token, 'created', { application: made.application, ...(made.expires ? { expires: made.expires } : {}) });
+                stopped = `${shut(proof)}${(await made.undo()) ? '' : LEFT_BEHIND}`;
+            }
+        }
+    }
+    // A stopped run asks nothing more.
+    deps.signal?.throwIfAborted();
+    const typed = await deps.paste();
+    if (!typed)
+        return { status: 'skipped', reason: stopped };
+    const token = { id: typed.id?.trim() ?? '', secret: typed.secret?.trim() ?? '' };
+    for (const part of [token.secret, token.id])
+        if (part)
+            deps.remember(part);
+    if (![token.id, token.secret].every((part) => /^[\x21-\x7e]{8,512}$/.test(part)))
+        return { status: 'refused', reason: 'What was typed is not a service token: a client id and a client secret, each one line.' };
+    const proof = await admitted(token, deps);
+    return proof.proven ? keep(token, 'typed') : { status: 'refused', reason: shut(proof) };
+}

package/dist/cloudflare.js

@@ -0,0 +1,249 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { commandRunner } from './netlify.js';
+/**
+ * Cloudflare Pages: the preview deployments this repository's pull requests
+ * get, from GitHub's record and from wrangler on this machine when it is
+ * signed in (read only), and whether wrangler is signed in. Cloudflare's
+ * GitHub app records no deployment and no commit status: its record is a
+ * check run on each commit it built and a comment on the pull request, both
+ * naming the deployment's address (https://<id>.<project>.pages.dev) and the
+ * branch's alias (https://<branch>.<project>.pages.dev), which follows the
+ * branch's latest build. Nothing here reads a token, and nothing comes back
+ * beyond the fields below.
+ */
+/** How many pull requests, the most recently updated, the evidence reads. */
+const NEWEST = 10;
+const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+/** A Pages deployment's address, or a branch's alias: one label, then the project, under pages.dev. */
+export const PAGES_ADDRESS = new RegExp(`^https://(${LABEL})\\.(${LABEL})\\.pages\\.dev$`);
+const LINKS = new RegExp(`https://${LABEL}\\.${LABEL}\\.pages\\.dev`, 'g');
+/** Cloudflare's GitHub app, by the slug its check runs carry and the login its comments carry; the earlier Pages-only app posted the same. */
+const APPS = new Set(['cloudflare-workers-and-pages', 'cloudflare-pages']);
+const isApp = (login) => typeof login === 'string' && APPS.has(login.replace(/\[bot\]$/, ''));
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined);
+const positive = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+const list = (value) => (Array.isArray(value) ? value.map(record).filter((item) => item !== undefined) : []);
+const sha = (value) => typeof value === 'string' && /^[0-9a-f]{40}$/.test(value);
+/** A branch name GitHub can be asked about: the characters git allows, no `..`, and neither a slash nor a dot at the end. */
+const branchName = (value) => /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(value) && !value.includes('..') && !value.endsWith('/') && !value.endsWith('.');
+/** A branch, as GitHub names it in a check run's summary or a wrangler row: git's characters, and not too long to be one. */
+const branchOf = (value) => (typeof value === 'string' && branchName(value) ? value : undefined);
+/** The project a Pages address belongs to; null for any other address. */
+export function pagesProject(url) {
+    return PAGES_ADDRESS.exec(url)?.[2] ?? null;
+}
+/** The deployment's address and the branch's alias, as the app's table names them, else the first two Pages links in order; a page mentions each once. */
+function addresses(html) {
+    const row = (label) => new RegExp(`${label}:</strong>[\\s\\S]{0,200}?href='(https://[^']+)'`).exec(html)?.[1];
+    const fits = (value) => (value && PAGES_ADDRESS.test(value) ? value : undefined);
+    const links = [...new Set(html.match(LINKS) ?? [])];
+    return { url: fits(row('Preview URL')) ?? links[0], alias: fits(row('Branch Preview URL')) ?? (links[1] !== links[0] ? links[1] : undefined) };
+}
+/** What a check run's conclusion, or the words the app's table says, tell of the build. */
+const stateOf = (value) => (typeof value !== 'string' ? 'building' : /succe/i.test(value) ? 'success' : /fail|timed_out|error/i.test(value) ? 'failure' : /cancel/i.test(value) ? 'canceled' : 'building');
+/**
+ * GitHub's record: the Cloudflare check run on each head (or, with `only`, that pull request's; with `branch`, the
+ * pushed branch's head alone, before its pull request exists), and the app's comment on each pull request when it
+ * describes the head. `failed` when a read did not answer.
+ */
+async function fromGitHub(owner, repo, gh, only, branch) {
+    const base = `/repos/${owner}/${repo}`;
+    const get = async (route) => JSON.parse(await gh(['api', '--hostname', 'github.com', '--method', 'GET', route]));
+    let failed = false;
+    const read = async (what, none) => what.catch(() => ((failed = true), none));
+    const when = (value) => (typeof value === 'string' && Number.isFinite(Date.parse(value)) ? Date.parse(value) : 0);
+    const heads = [];
+    if (branch !== undefined) {
+        const ref = record(await read(get(`${base}/branches/${encodeURIComponent(branch)}`), null));
+        const head = record(ref?.commit)?.sha;
+        if (ref?.name === branch && sha(head))
+            heads.push({ branch, sha: head, at: 0 });
+    }
+    else {
+        const pulls = await read(only ? get(`${base}/pulls/${only}`).then((one) => [one]) : get(`${base}/pulls?state=all&sort=updated&direction=desc&per_page=${NEWEST}`), []);
+        for (const pull of list(pulls)) {
+            const head = record(pull.head);
+            if (positive(pull.number) && (!only || pull.number === only) && sha(head?.sha))
+                heads.push({ number: pull.number, branch: branchOf(head?.ref), sha: head.sha, at: when(pull.updated_at) });
+        }
+    }
+    const found = [];
+    // Cloudflare posts its check run once the build ended, so a head with none is still building, or was never built.
+    const runs = await Promise.all(heads.map((head) => read(get(`${base}/commits/${head.sha}/check-runs?per_page=100`), null)));
+    runs.forEach((result, i) => {
+        const head = heads[i];
+        for (const run of list(record(result)?.check_runs)) {
+            if (!isApp(record(run.app)?.slug))
+                continue;
+            const { url, alias } = addresses(String(record(run.output)?.summary ?? ''));
+            if (!url)
+                continue;
+            found.push({ ...(head.number ? { pullRequest: head.number } : {}), ...(head.branch ? { branch: head.branch } : {}), sha: head.sha, url, ...(alias ? { alias } : {}), state: run.status === 'completed' ? stateOf(run.conclusion) : 'building', from: 'check run', at: when(run.completed_at) || head.at });
+            break;
+        }
+    });
+    if (branch === undefined) {
+        const comments = await read(get(`${base}/issues/comments?sort=updated&direction=desc&per_page=100`), []);
+        for (const comment of list(comments)) {
+            const issue = typeof comment.issue_url === 'string' ? Number(/\/issues\/([1-9]\d*)$/.exec(comment.issue_url)?.[1]) : NaN;
+            const head = heads.find((h) => h.number === issue);
+            if (!head || !isApp(record(comment.user)?.login) || typeof comment.body !== 'string')
+                continue;
+            // The app edits its one comment as the pull request moves on: it describes the head when the commit it names is the head's.
+            const commit = /Latest commit:<\/strong>[\s\S]{0,80}?<code>([0-9a-f]{7,40})<\/code>/.exec(comment.body)?.[1];
+            if (!commit || !head.sha.startsWith(commit))
+                continue;
+            const { url, alias } = addresses(comment.body);
+            if (!url || found.some((p) => p.pullRequest === issue && p.url === url))
+                continue;
+            found.push({ pullRequest: issue, ...(head.branch ? { branch: head.branch } : {}), sha: head.sha, url, ...(alias ? { alias } : {}), state: stateOf(/Status:<\/strong>[\s\S]{0,120}?<\/td>/.exec(comment.body)?.[0]), from: 'bot comment', at: when(comment.updated_at) || head.at });
+        }
+    }
+    return { previews: found, heads, failed };
+}
+/** The Pages project the checkout's wrangler config names: only a config with a Pages output directory is a Pages project's, since a Worker's config names a Worker. */
+export async function configuredProject(cwd) {
+    const name = (value) => (typeof value === 'string' && new RegExp(`^${LABEL}$`).test(value) ? value : undefined);
+    try {
+        const toml = await readFile(join(cwd, 'wrangler.toml'), 'utf8');
+        if (/^\s*pages_build_output_dir\s*=/m.test(toml))
+            return name(/^\s*name\s*=\s*"([^"\n]+)"/m.exec(toml)?.[1]);
+    }
+    catch {
+        // No TOML config: the JSON ones next.
+    }
+    for (const file of ['wrangler.json', 'wrangler.jsonc']) {
+        try {
+            // A jsonc config may carry comments, on their own lines or after a value, and trailing commas.
+            const config = record(JSON.parse(plainJson(await readFile(join(cwd, file), 'utf8'))));
+            if (typeof config?.pages_build_output_dir === 'string')
+                return name(config.name);
+        }
+        catch {
+            // Not there, or not readable as JSON.
+        }
+    }
+    return undefined;
+}
+/** JSON with comments as JSON: line and block comments outside strings go, and so does a comma before a closing bracket. */
+export function plainJson(text) {
+    let out = '';
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"') {
+            // A string, its escapes kept, so a // inside it stays.
+            let j = i + 1;
+            for (; j < text.length && text[j] !== '"'; j++)
+                if (text[j] === '\\')
+                    j++;
+            out += text.slice(i, j + 1);
+            i = j;
+        }
+        else if (c === '/' && text[i + 1] === '/') {
+            const end = text.indexOf('\n', i);
+            i = end < 0 ? text.length : end - 1;
+        }
+        else if (c === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end < 0 ? text.length : end + 1;
+        }
+        else
+            out += c;
+    }
+    return out.replace(/,(\s*[}\]])/g, '$1');
+}
+/** What `wrangler whoami --json` printed, as JSON: the same object signed out, with `loggedIn` false, whatever it exited with. */
+const whoamiOf = (printed) => {
+    const text = String(printed ?? '');
+    return record(JSON.parse(text.slice(text.indexOf('{'), text.lastIndexOf('}') + 1)));
+};
+/** `wrangler whoami --json`: whether wrangler is signed in. */
+export async function wranglerStatus(npx) {
+    let status;
+    try {
+        status = whoamiOf(await npx(['--yes', 'wrangler', 'whoami', '--json']));
+    }
+    catch (err) {
+        if (err.missing)
+            return 'missing';
+        try {
+            status = whoamiOf(err.stdout);
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    return status?.loggedIn === true ? 'signed-in' : status?.loggedIn === false ? 'signed-out' : 'unknown';
+}
+/**
+ * What wrangler lists of the project's preview deployments when it is signed in: `pages deployment list --json` prints
+ * one row a deployment, with the branch, the commit's first seven characters, the address and the status (a date once
+ * the build succeeded, else the stage's word).
+ */
+async function fromWrangler(project, npx) {
+    const cli = await wranglerStatus(npx);
+    if (cli !== 'signed-in' || !project)
+        return { cli, rows: [], failed: cli === 'unknown' };
+    try {
+        const printed = await npx(['--yes', 'wrangler', 'pages', 'deployment', 'list', '--project-name', project, '--environment', 'preview', '--json']);
+        const rows = list(JSON.parse(printed.slice(printed.indexOf('['), printed.lastIndexOf(']') + 1))).flatMap((row, at) => {
+            const url = typeof row.Deployment === 'string' && PAGES_ADDRESS.test(row.Deployment) ? row.Deployment : undefined;
+            if (!url || !/^preview$/i.test(String(row.Environment)))
+                return [];
+            const status = String(row.Status ?? '');
+            const state = /^(idle|active|queued|building)$/i.test(status) ? 'building' : /^fail/i.test(status) ? 'failure' : /^cancel/i.test(status) ? 'canceled' : 'success';
+            const commit = typeof row.Source === 'string' && /^[0-9a-f]{7,40}$/.test(row.Source) ? row.Source : undefined;
+            return [{ ...(branchOf(row.Branch) ? { branch: row.Branch } : {}), ...(commit ? { sha: commit } : {}), url, state, from: 'wrangler', at: -at }];
+        });
+        return { cli, rows, failed: false };
+    }
+    catch {
+        return { cli, rows: [], failed: true };
+    }
+}
+/**
+ * Whether this repository's pull requests get Cloudflare Pages previews: the newest, as GitHub and wrangler have them;
+ * with `pull`, that pull request's only; with `branch`, the pushed branch's head's only, before its pull request exists.
+ */
+export async function readCloudflarePreviews(owner, repo, cwd, deps = {}) {
+    const unread = () => ({ previews: [], cli: 'missing', error: "Cloudflare's previews could not be read.", unread: ['GitHub'] });
+    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 unread();
+    if (deps.branch !== undefined && !branchName(deps.branch))
+        return unread();
+    const github = await fromGitHub(owner, repo, deps.gh ?? commandRunner('gh', cwd, { signal: deps.signal }), deps.pull, deps.branch);
+    const project = github.previews.map((p) => pagesProject(p.url)).find(Boolean) ?? (await configuredProject(cwd));
+    // wrangler installs itself through npx on a machine without it, which takes a while the first time.
+    const wrangler = await fromWrangler(project, deps.npx ?? commandRunner('npx', cwd, { signal: deps.signal, timeoutMs: 120_000 }));
+    // A row is the head's when its commit is the head's; the pull request's heads say which. A wait for a pushed branch takes its head's rows alone.
+    const head = (row) => github.heads.find((h) => row.sha && h.sha.startsWith(row.sha) && (deps.branch === undefined || h.branch === deps.branch));
+    const rows = wrangler.rows.flatMap((row) => {
+        const of = head(row);
+        if (deps.branch !== undefined && !of)
+            return [];
+        if (deps.pull !== undefined && of?.number !== deps.pull)
+            return [];
+        return [of ? { ...row, ...(of.number ? { pullRequest: of.number } : {}), branch: of.branch ?? row.branch, sha: of.sha, at: of.at } : row];
+    });
+    // Of the same build, the check run outranks wrangler's row, and both the app's comment; each address once.
+    const rank = (p) => (p.from === 'check run' ? 0 : p.from === 'wrangler' ? 1 : 2);
+    const previews = [];
+    for (const p of [...github.previews, ...rows].sort((a, b) => rank(a) - rank(b))) {
+        const twin = previews.find((q) => q.url === p.url && (q.pullRequest ?? q.branch) === (p.pullRequest ?? p.branch));
+        if (!twin)
+            previews.push(p);
+        else if (!twin.alias && p.alias)
+            twin.alias = p.alias;
+    }
+    // The most recently updated pull request's first; a branch with no pull request among them last, as wrangler lists it.
+    previews.sort((a, b) => (b.pullRequest ? 1 : 0) - (a.pullRequest ? 1 : 0) || b.at - a.at);
+    return {
+        ...(project ? { project } : {}),
+        previews: previews.slice(0, deps.branch !== undefined ? previews.length : NEWEST).map(({ at, ...preview }) => preview),
+        cli: wrangler.cli,
+        ...(github.failed || wrangler.failed
+            ? { error: "Some of Cloudflare's previews could not be read: what is missing is unknown, not absent.", unread: [...(github.failed ? ['GitHub'] : []), ...(wrangler.failed ? ['wrangler'] : [])] }
+            : {}),
+    };
+}