@impeccable/reviews 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 Sets a repository up for Impeccable for PRs from your terminal. Run it in a checkout of the repository: it signs you in through the browser, then a setup agent reads the checkout, runs what it needs, saves the settings through Impeccable's setup API, asks you only what it cannot find out, opens a test drive pull request for Impeccable to review (and a setup pull request to merge, when the repository needs one) and writes a setup report. A web page mirrors the run as it goes and follows the review.
 
-You need Node 22.19 or newer, git, and the `gh` command signed in to GitHub as someone who can push branches to the repository (the agent opens the pull request as you).
+You need Node 22.19 or newer, git, and the `gh` command signed in to GitHub as someone who can push branches to the repository (the agent opens the pull request as you). On Linux, `bubblewrap`, `socat` and `ripgrep` let the agent's commands run in a sandbox.
 
 ## Run it
 
@@ -23,6 +23,7 @@ Keys: Enter goes on, Esc cancels the intro or the sign-in and skips a question (
 
 | Flag | Default | What it does |
 | --- | --- | --- |
+| `--install-dir <path>` | the folder the command is run in | The folder to set up, a checkout of the repository or a folder inside one, so the command runs from anywhere: `npx @impeccable/reviews --install-dir ~/code/your-repo`. A relative path is taken from the folder the command is run in; `IMPECCABLE_REVIEWS_INSTALL_DIR` does the same when the option is absent. |
 | `--host <origin>` | `https://impeccable.reviews` | Impeccable's address. Plain `http` only for localhost. |
 | `--model <id>` | the model the service hands out (Sonnet 5.5 today) | The model the setup agent runs on, through Impeccable's gateway. |
 | `--effort <level>` | `high` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. |
@@ -31,12 +32,13 @@ Keys: Enter goes on, Esc cancels the intro or the sign-in and skips a question (
 | `--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. |
+| `--no-telemetry` | off | Reports none of the command's steps to Impeccable (see What it reports). `DO_NOT_TRACK=1` does the same. |
 
 ## 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.
+1. **Sign in.** The consent page names this repository, read from the checkout's `origin` remote; you approve, and it 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, 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.
+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 Cloudflare's CLI, cf, 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 reads "waiting for Vercel's preview · 1:05", counting up), 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.
@@ -46,17 +48,33 @@ 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. 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.
+The agent's commands run in an operating-system sandbox, macOS's seatbelt or Linux's bubblewrap, through Anthropic's sandbox runtime (`@anthropic-ai/sandbox-runtime`), which holds even when the repository talks the agent into something:
+
+- **Reads**: what your account reads, but your credential folders: `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.azure`, `~/.config/gcloud`, `~/.kube`, `~/.docker`, `~/.netrc`, `~/.git-credentials`, `~/.config/gh`, and your keychains on macOS.
+- **Writes**: the checkout and its git folder, but never where git takes settings or programs from (its config, hooks, `info`, a `commondir`, the submodules' and the other worktrees' git folders, a `.git` below the checkout's top); the run's scratch folder; and the package managers' caches (npm, pnpm, Yarn, Bun, Corepack, Prisma's engines), but not what `npx` installed in npm's. An install skips the browsers Cypress, Puppeteer and Playwright download, and husky's git hooks.
+- **Network**: only the hosts this setup needs: `--host`; GitHub (`github.com`, `*.github.com`, `*.githubusercontent.com`); the public registries your manifests and lockfiles install from (npm's, Yarn's, PyPI); the registries your own `~/.npmrc` names, never one only the repository names; Google's fonts for a Next.js app and Prisma's engines, when the app uses them; and Vercel's or Netlify's API once you said yes to setting that host up. The debug log names each host it refused.
+
+What acts as you runs outside the sandbox, as a command of its own: `git commit`, `git push`, `gh`, `vercel`, `netlify` and the install of a host's CLI need your sign-ins, keys and keychain, which the sandbox never opens, and run none of the repository's code. Git's hooks are off for them, and for every git the command runs itself, and git is pointed at this checkout's own git folders. A command that joins one of them to another program is refused, and the agent runs them apart; `cd` and git's other commands may come along. What the command fetches there itself, a host's CLI or Cloudflare's `cf` through `npx`, it fetches from a folder of its own, so the repository's `.npmrc` and `node_modules` choose nothing of what runs as you. On macOS the local preview check runs the app's commands in a sandbox of its own: they write only in its throwaway copy, read and reach what the agent's commands do, and serve the app on this machine, where the check requests it. On Linux bubblewrap gives each command a network of its own, which the check could not request, so there the check runs them as before, in its copy with a clean environment.
+
+On macOS the command stops when the sandbox does not start, as inside another tool's sandbox. On Linux it needs `bubblewrap`, `socat` and `ripgrep`: without them, and on other systems, the first screen says once that the commands run without a sandbox, with all your access, as they did before. On Linux bubblewrap takes no pattern in a write rule, so a command there can make a `.git` below the checkout's top; git outside the sandbox never reads it during the run, being pointed at the checkout's own folders.
+
+The fence stays the layer inside the sandbox: it keeps the setup to its own steps and out of `.env` files, and the agent's commands get your environment without the tokens, keys and passwords in it. 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; 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`), 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.
+`netlify --version` and `netlify status`. Once you are signed in to Netlify for the setup: `netlify link` and `netlify sites:create`, 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 deploy (`netlify deploy --build` builds the repository with your Netlify sign-in, and the two never run together), 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).
 
-Refused, never asked, with the reason going back to the agent, which finds another way or leaves the step to you in the report: anything else (`node -e` too), a read outside the checkout (symlinks followed), a read of a `.env` file, a recursive `grep` without `--exclude=.env*`, a push to the default branch, a global install, publishing, a script whose name says it publishes, releases or deploys, a setting such as `PATH`, `EDITOR` or `NODE_OPTIONS` that changes what runs, a `cd` that may not run (after `&&` or `||`, or in a pipe) or goes into a folder that is not there, git patterns that can match a `.env` file, a `git add` of every change or of a folder without `':(exclude,glob)**/.env*'`, a commit message or template read from a `.env` file or from outside the checkout and the scratch folder, package scripts and the tools on the list once the agent has changed a `package.json` or a file they load (a `*.config.*` or `.*rc` file, `tsconfig*.json`, anything under `node_modules`…; after `vite.config.*`, whose preview hosts the setup may correct, the local preview check still runs), and, past 400 tool calls in a run, any but the progress update and the report. `rm -rf`, force pushes, `git reset --hard`, `sudo`, database commands that throw data away (`prisma migrate reset`, `db push --force-reset`, `sequelize db:drop`…), other writes outside the checkout and writes into `.git` never run.
+Refused, never asked, with the reason going back to the agent, which finds another way or leaves the step to you in the report: anything else (`node -e` too), a read outside the checkout (symlinks followed), a read of a `.env` file, a recursive `grep` without `--exclude=.env*`, a push to the default branch, a global install, publishing, a script whose name says it publishes, releases or deploys, a setting such as `PATH`, `EDITOR` or `NODE_OPTIONS` that changes what runs, a `cd` that may not run (after `&&` or `||`, or in a pipe) or goes into a folder that is not there, a command that joins `git commit` or `push`, `gh`, `vercel`, `netlify` or a host CLI's install to another program, git patterns that can match a `.env` file, a `git add` of every change or of a folder without `':(exclude,glob)**/.env*'`, a commit message or template read from a `.env` file or from outside the checkout and the scratch folder, package scripts and the tools on the list once the agent has changed a `package.json` or a file they load (a `*.config.*` or `.*rc` file, `tsconfig*.json`, anything under `node_modules`…; after `vite.config.*`, whose preview hosts the setup may correct, the local preview check still runs), and, past 400 tool calls in a run, any but the progress update and the report. `rm -rf`, force pushes, `git reset --hard`, `sudo`, database commands that throw data away (`prisma migrate reset`, `db push --force-reset`, `sequelize db:drop`…), other writes outside the checkout and writes into a `.git`, the checkout's or one below its top, never run.
+
+## What it reports
+
+So that a setup that stops in the terminal shows where it stopped, the command tells Impeccable about the steps only it sees: that it started, a check that stopped it (Node too old, no git, not a checkout, no `origin` remote, a remote not on GitHub, the sandbox not starting), a sign-in that did not finish (cancelled, timed out, every callback port taken, a different repository approved), and being stopped (Ctrl+C, a signal, a crash, the last update to the web page lost). A stopped run's last update also says why it stopped.
+
+Each report carries the step, how it ended, when, the command's version, Node's major version, your operating system and an id made fresh for the run. Never your code, file names, what you were asked or answered, or any token's value. It never names you: once you sign in, the reports go with the sign-in token, and Impeccable puts them on the account that approved, so steps from before sign-in wait and go with it. A run that never signs in sends its steps with the run's id alone. A report that cannot be sent is dropped and never holds the command up for more than two seconds. `--no-telemetry` or `DO_NOT_TRACK=1` turns all of it off.
 
 ## Tokens
 
@@ -68,4 +86,4 @@ Vercel's bypass secret, which lets reviews open previews behind Vercel's login,
 
 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.
+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. On your yes it creates the token as you through Cloudflare's CLI, cf (run through npx), 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). When cf here is not signed in with Access, your browser opens Cloudflare's sign-in first, for five scopes (`account:read`, `user:read`, `pages:read`, `access.write`, `access-service-token.write`), with a retry when it did not complete. Only where that sign-in cannot create the token (it grants no Access, cf does not run here, or the application runs on policies of its own, which cf has no command for) does the command ask for a Cloudflare API token with two permissions (Access: Apps and Policies, Edit; Access: Service Tokens, Edit), 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/agent.js

@@ -110,8 +110,8 @@ export async function runAgent(opts) {
             model,
             thinkingLevel: opts.effort,
             tools: [...BUILT_IN_TOOLS, ...opts.tools.map((t) => t.name)],
-            // pi's own bash, whose commands run without the person's credentials in their environment.
-            customTools: [defineTool(createBashToolDefinition(cwd, { spawnHook: (spawn) => ({ ...spawn, env: shellEnvironment(spawn.env) }) })), ...opts.tools],
+            // pi's own bash, whose commands run in the sandbox (or as the person, outside it) without the person's credentials in their environment.
+            customTools: [defineTool(createBashToolDefinition(cwd, { operations: opts.bash, spawnHook: (spawn) => ({ ...spawn, env: shellEnvironment(spawn.env) }) })), ...opts.tools],
         });
         return { ...created, services, diagnostics: services.diagnostics };
     };

package/dist/bin.js

@@ -4,8 +4,46 @@
 const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
 if (major < 22 || (major === 22 && minor < 19)) {
     console.error(`impeccable-reviews needs Node 22.19 or newer, and this is Node ${process.versions.node}. Install a newer Node from https://nodejs.org and run it again.`);
+    await reportOldNode(major);
     process.exit(1);
 }
+/**
+ * The one step reported from here (report.ts reports the rest): Node was too
+ * old to run the command. Unnamed, with nothing but the launch, two seconds at
+ * most, and never with --no-telemetry or DO_NOT_TRACK=1. Written for the old
+ * Node it runs on: no imports, and nothing at all where fetch is missing.
+ */
+async function reportOldNode(nodeMajor) {
+    const args = process.argv.slice(2);
+    if (args.includes('--no-telemetry') || /^(1|true|yes)$/i.test(process.env.DO_NOT_TRACK?.trim() ?? ''))
+        return;
+    if (typeof fetch !== 'function' || typeof globalThis.crypto?.randomUUID !== 'function')
+        return;
+    const named = args.find((a) => a.startsWith('--host='))?.slice('--host='.length) ?? (args.includes('--host') ? args[args.indexOf('--host') + 1] : undefined);
+    let host;
+    try {
+        host = new URL(named ?? 'https://impeccable.reviews');
+    }
+    catch {
+        return;
+    }
+    // The same rule as --host itself: plain http only to this machine.
+    if (!(host.protocol === 'https:' || (host.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(host.hostname))))
+        return;
+    let version = 'unknown';
+    try {
+        const { readFileSync } = await import('node:fs');
+        version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    }
+    catch {
+        // The report goes without it.
+    }
+    const body = { launch_id: globalThis.crypto.randomUUID(), version, node_major: nodeMajor, os: process.platform, events: [{ event: 'setup_command_check_failed', outcome: 'node_too_old', at: new Date().toISOString() }] };
+    await Promise.race([
+        fetch(`${host.origin}/app/cli/events`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }).catch(() => undefined),
+        new Promise((resolve) => setTimeout(resolve, 2000).unref()),
+    ]);
+}
 const { main } = await import('./main.js');
 await main(process.argv.slice(2));
 export {};

package/dist/cloudflare-access.js

@@ -1,9 +1,12 @@
 import { setTimeout as sleep } from 'node:timers/promises';
+import { cfFailure, cfStatus } from './cloudflare.js';
 /**
  * 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
+ * The run makes both as the person through cf, Cloudflare's CLI, signed in with the scopes below, and signs cf in, in
+ * the browser, where it lacks them. Where that sign-in cannot make them (it grants no Access, cf does not run here, or
+ * the application runs on policies of its own, which cf has no command to add to), the person gives the run a Cloudflare
+ * API token with two permissions instead, 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.
  */
@@ -13,13 +16,117 @@ 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';
+/**
+ * The OAuth scopes the run's Cloudflare sign-in asks for. Each is named for the API token permission it grants: Access:
+ * Apps and Policies Write and Access: Service Tokens Write, which the token and its policy take; Pages Read, for cf's
+ * list of the preview deployments; and the account and user reads cf finds the accounts with (/accounts, /memberships).
+ */
+export const CF_SCOPES = ['account:read', 'user:read', 'pages:read', 'access.write', 'access-service-token.write'];
+/** Of those, what creating the token and its policy takes: a sign-in without them cannot. */
+const ACCESS_SCOPES = ['account:read', 'access.write', 'access-service-token.write'];
 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}.`);
+/** Why a call failed, in fixed words: the permissions for a 401 or a 403, else the status. Cloudflare's own message never goes on. */
+const refusal = (way, reply, none) => (reply.ok ? none
+    : reply.status === 401 || reply.status === 403 ? `${way.who[0].toUpperCase()}${way.who.slice(1)} cannot do this: it needs Access: Apps and Policies → Edit and Access: Service Tokens → Edit, on the account that holds the Access application.`
+        : reply.status === null ? "Cloudflare's API did not answer." : `Cloudflare's API answered ${reply.status}.`);
+/** Cloudflare's API with the API token the person gave, for this run alone. */
+function withApiToken(key, deps) {
+    return {
+        who: 'the Cloudflare API token',
+        cf: false,
+        call: 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 };
+            }
+        },
+    };
+}
+/** The cf command for each call in an account's Access; a policy of an application's own has none. A delete asks first unless forced, and the run deletes only what it made. */
+const CF_COMMANDS = [
+    [/^GET apps$/, () => ['applications', 'list']],
+    [/^GET policies$/, () => ['policies', 'list']],
+    [/^POST service_tokens$/, () => ['service-tokens', 'create']],
+    [/^POST policies$/, () => ['policies', 'create']],
+    [/^PUT apps\/([\w-]+)$/, (id) => ['applications', 'update', id]],
+    [/^DELETE service_tokens\/([\w-]+)$/, (id) => ['service-tokens', 'delete', id, '--force']],
+    [/^DELETE policies\/([\w-]+)$/, (id) => ['policies', 'delete', id, '--force']],
+];
+/** Cloudflare's API through cf signed in as the person: each call as the cf command that makes it, in the account its path names, which is one of the sign-in's. */
+function throughCf(cf, accounts, signal) {
+    return {
+        who: 'the Cloudflare sign-in',
+        cf: true,
+        call: async (method, path, body, undoing = false) => {
+            const [route = '', query] = path.split('?');
+            const paging = new URLSearchParams(query);
+            if (method === 'GET' && route === '/accounts')
+                return { ok: true, result: paging.get('page') === '1' ? accounts.map((id) => ({ id })) : [] };
+            const at = /^\/accounts\/([0-9a-f]{32})\/access\/(.+)$/.exec(route);
+            const call = `${method} ${at?.[2]}`;
+            const command = CF_COMMANDS.find(([pattern]) => pattern.test(call));
+            if (!at || !command)
+                return { ok: false, status: null };
+            const args = ['zero-trust', 'access', ...command[1](command[0].exec(call)[1] ?? ''),
+                ...(paging.has('page') ? ['--page', paging.get('page'), '--per-page', paging.get('per_page')] : []),
+                ...(body === undefined ? [] : ['--body', JSON.stringify(body)])];
+            try {
+                // cf prints the result as JSON, and a delete nothing.
+                const printed = await cf(args, { account: at[1], ...(undoing ? {} : { signal }) });
+                const start = printed.search(/[[{]/);
+                return { ok: true, result: start < 0 ? null : JSON.parse(printed.slice(start)) };
+            }
+            catch (err) {
+                return { ok: false, status: cfFailure(err) };
+            }
+        },
+    };
+}
+/**
+ * cf signed in with the scopes, as it is or after Cloudflare's sign-in in the browser: one that did not complete offers
+ * a retry, and two failed retries end it. The new sign-in asks for the scopes it held as well, so whatever else the
+ * person uses cf for goes on working.
+ */
+async function reach(deps) {
+    const granted = (s) => s.cli === 'signed-in' && (!s.scopes || ACCESS_SCOPES.every((scope) => s.scopes.includes(scope)));
+    const through = (s) => ({ way: throughCf(deps.cf, s.accounts, deps.signal) });
+    let status = await cfStatus(deps.cf, deps.signal);
+    if (granted(status))
+        return through(status);
+    if (status.cli === 'missing' || status.cli === 'unknown')
+        return { fallback: "Cloudflare's CLI did not run here." };
+    for (let attempt = 0;; attempt++) {
+        deps.status?.("Opening the browser for Cloudflare's login");
+        const scopes = [...new Set([...(status.scopes ?? []).filter((scope) => scope !== 'offline_access'), ...CF_SCOPES])];
+        // The callback on this machine, not the device flow, which asks the person to match a code cf prints where they never see it.
+        const done = await deps.login(['auth', 'login', '--force', '--no-device', '--scopes', ...scopes], { signal: deps.signal }).then(() => true, () => false);
+        deps.signal?.throwIfAborted();
+        const now = await cfStatus(deps.cf, deps.signal);
+        if (granted(now))
+            return through(now);
+        // Signed in anew, and still without Access: Cloudflare gave this sign-in none, which an API token can have.
+        if (done && now.cli === 'signed-in')
+            return { fallback: 'The Cloudflare sign-in gave the run no access to Cloudflare Access.' };
+        if (now.cli === 'signed-in')
+            status = now;
+        if (attempt === 2)
+            return { stopped: 'The Cloudflare sign-in did not complete.' };
+        if (!(await deps.retry()))
+            return { stopped: 'The person skipped the Cloudflare sign-in.' };
+    }
+}
 /** 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);
@@ -40,28 +147,19 @@ function settingsOf(app) {
 /** 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.
+ * As the person, the way they reach Cloudflare's API: the one self-hosted Access application whose destination covers
+ * the address, in the accounts they reach, 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. Through cf, that
+ * application, or a refusal of permissions once what was made is undone, answers a `fallback` for the API token. 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 };
-        }
+async function create(way, deps) {
+    const api = way.call;
+    /** Why it stopped; through cf a 401 or a 403 is the API token's to try, unless something the run made was left behind. */
+    const stop = (reply, none, left = '') => {
+        const why = `${refusal(way, reply, none)}${left}`;
+        return way.cf && !left && !reply.ok && (reply.status === 401 || reply.status === 403) ? { fallback: why } : { reason: why };
     };
     /** 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) => {
@@ -80,7 +178,7 @@ async function create(key, deps) {
     const url = new URL(deps.url);
     const accounts = await every('/accounts', 50);
     if (!accounts.ok)
-        return { reason: refusal(accounts, '') };
+        return stop(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;
@@ -98,7 +196,7 @@ async function create(key, deps) {
     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}.` };
+        return unread ? stop(unread, '') : { reason: `No Access application ${way.who} 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 }] : []));
@@ -106,10 +204,12 @@ async function create(key, deps) {
     if (links.length) {
         const policies = await every(`${base}/policies`, 1000);
         if (!policies.ok)
-            return { reason: refusal(policies, '') };
+            return stop(policies, '');
         const ids = new Set(list(policies.result).map((p) => p.id));
         reusable = links.every((link) => ids.has(link.id));
     }
+    if (!reusable && way.cf)
+        return { fallback: 'The Access application runs on policies of its own, which cf has no command to add to.' };
     const undo = [];
     const rollback = async () => {
         let clean = true;
@@ -117,7 +217,7 @@ async function create(key, deps) {
             clean = (await step()).ok && clean;
         return clean;
     };
-    const fail = async (reply, none) => ({ reason: `${refusal(reply, none)}${(await rollback()) ? '' : LEFT_BEHIND}` });
+    const fail = async (reply, none) => stop(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.
@@ -161,9 +261,9 @@ async function admitted(token, deps) {
 }
 /**
  * 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.
+ * On the person's yes the run creates it and allows it in the application's policy, through cf signed in as them, or
+ * with an API token they give where that sign-in cannot; 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.';
@@ -177,25 +277,33 @@ export async function passCloudflareAccess(deps) {
     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;
+        const reached = await reach(deps);
+        let made = 'way' in reached ? await create(reached.way, deps) : 'stopped' in reached ? { reason: reached.stopped } : reached;
+        let apiToken = false;
+        if ('fallback' in made) {
+            // Where cf's sign-in cannot make the token, an API token the person makes for the run can.
+            const key = (await deps.apiToken())?.trim();
+            if (!key)
+                made = { reason: `${made.fallback} The person skipped the Cloudflare API token that creating the service token then takes.` };
             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}`;
+                deps.remember(key);
+                apiToken = true;
+                made = await create(withApiToken(key, deps), deps);
             }
         }
+        if (!('token' in made))
+            stopped = 'reason' in made ? made.reason : made.fallback;
+        else {
+            const token = made;
+            // 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(token.token, deps).catch(async (err) => {
+                await token.undo();
+                throw err;
+            });
+            if (proof.proven)
+                return keep(token.token, 'created', { application: token.application, ...(token.expires ? { expires: token.expires } : {}), ...(apiToken ? { apiToken: true } : {}) });
+            stopped = `${shut(proof)}${(await token.undo()) ? '' : LEFT_BEHIND}`;
+        }
     }
     // A stopped run asks nothing more.
     deps.signal?.throwIfAborted();