@impeccable/reviews 0.1.8 → 0.1.9

package/README.md

@@ -24,7 +24,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. |
-| `--app <key>` | asked | On a repository with several apps, sets up that one app, by its key (such as `storefront`), without asking which. Without it, every run asks, with the apps that are on already picked. |
+| `--app <key>` | asked | On a repository with several apps, sets up that one app, by its key (such as `storefront`): one confirm screen names it instead of the list of apps, and only that app is touched. Without it, every run asks, with the apps that are on already picked. |
 | `--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`. |

package/dist/host-questions.js

@@ -234,6 +234,16 @@ export const APPS_QUESTION = {
 };
 /** The apps question's hint when the command was started below the repository's top: `where` is an app's folder ("Tally Board's folder") or the folder itself. */
 export const startedIn = (where) => `You started in ${where}. Impeccable sets up from the top of the repository.`;
+/** The apps question when the command was started for one app (`--app`): no list, one confirm screen naming that app, and the list behind Skip for someone who wants another app (#286). */
+export const namedAppQuestion = (app) => ({
+    id: APPS_QUESTION.id,
+    kind: 'confirm',
+    title: APPS_QUESTION.title,
+    hint: `You're setting up ${app.name} (${app.folder || '/'}); the other apps stay as they are.`,
+    prompt: `Set up ${app.name}?`,
+    confirmLabel: `Set up ${app.name}`,
+    skipLabel: 'Pick other apps',
+});
 /** The ids whose screens the tool puts up itself, when it needs the person, and takes down: the web page follows those, not the model's call. */
 export const TOOL_SHOWN = new Set(['netlify-setup', 'vercel-setup', APPS_QUESTION.id]);
 /** A question as the person reads it: the fixed words for a host's id, else the model's own. */

package/dist/main.js

@@ -16,7 +16,7 @@ import { scanRecorder } from './scan.js';
 import { createReporter, reportingOff } from './report.js';
 import { createSessionSync, pageStatus, plainReport, syncExtension } from './sync.js';
 import { checkPushAccess, readPushAccess } from './push-access.js';
-import { createTools, ownPullRequest, resultLine } from './tools.js';
+import { appsSummary, createTools, ownPullRequest, resultLine } from './tools.js';
 import { transcriptPaths } from './transcript.js';
 import { askPerson } from './ui/bridge.js';
 import { atExit, closeScreens, helpMark, onScreenExit, recordFrames, showIntro, showOutro, showPullRequest, showRun, showSignIn } from './ui/screens.js';
@@ -235,14 +235,17 @@ export async function main(argv) {
                 const saved = await settle(liveSync.flush(), 5000);
                 const { testPr } = report;
                 const setupPr = shownSetupPr(report.setupPr);
+                // On a repository with several apps, "You're all set up" means every app this run picked is: one left unproven is named, with its one step (#286).
+                const apps = appsSummary(report.apps ?? []);
+                const allSetUp = Boolean(testPr) && !apps.notReady.length;
                 // One pull request a screen, each opened in the browser and put on the clipboard as its screen appears: the test drive, then the setup pull request.
                 const hand = { open: openBrowser, copy: copyText };
                 if (testPr && setupPr)
                     await showPullRequest(testPr.url, hand);
                 await showOutro({
-                    outcome: testPr ? 'done' : 'partial',
-                    title: testPr ? "You're all set up" : 'Settings saved',
-                    result: resultLine({ ...report, setupPr }),
+                    outcome: allSetUp ? 'done' : 'partial',
+                    title: allSetUp ? "You're all set up" : apps.notReady.length ? `${apps.notReady.join(' and ')} ${apps.notReady.length === 1 ? 'is' : 'are'} not set up` : 'Settings saved',
+                    result: [resultLine({ ...report, setupPr }), apps.line].filter(Boolean).join(' '),
                     link: (setupPr ?? testPr)?.url,
                     links: [
                         ...(testPr ? [{ label: 'Test drive, watch the review there', url: testPr.url }] : []),
@@ -250,7 +253,7 @@ export async function main(argv) {
                         ...(setupPr ? [{ label: testPr ? 'Setup pull request, merge this' : 'Setup pull request', url: setupPr.url }] : []),
                         { label: 'Web page', url: page },
                     ],
-                    todo: report.left,
+                    todo: [...apps.todo, ...report.left],
                     warnings: [...removed, ...(saved && !saved.ok ? [`The web page missed the last update (${saved.error}), so it may lag behind this.`] : [])],
                 }, hand);
                 // The web page has the report; when it missed it, the report stays here instead.

package/dist/playbook/cases/monorepo.md

@@ -5,14 +5,14 @@ The state's repository has an `apps` item: the scan proposed several apps, folde
 ### Steps
 
 1. **Confirm the proposal** as it stands, while the item's status is `needs-you`: impeccable_write to `apps` with the `confirm` action the item's instructions give. Its answer lists every app of the repository, on and off, with its `key`, `name`, `pathPrefixes` and `enabled`; the one the scan switched on is the repository's default. An item that is `done` or `skipped` was answered before (on the setup page, or by an earlier run): no confirm, and step 2 all the same. Done when it answered `apps`, or the item was answered before.
-2. **Ask which apps this run sets up**, on every run, with impeccable_ask: `id: "apps"`, `kind: "multi"`, and the `prompt` *"Which apps should get Impeccable previews?"*. The tool words the question and lists the state's apps (the repository's own, `main`, only where the Worker kept it as a product of its own), each picked as it is on, or every one after this run's confirm. Mark the Apps task in progress first. Every write and host tool for an app is refused until it is answered. Done when it answered `values`, `named` (the command was started for that one app with `--app`, so no screen showed), or a skip, whose `on` lists the apps that are on: the ones this run sets up.
+2. **Ask which apps this run sets up**, on every run, with impeccable_ask: `id: "apps"`, `kind: "multi"`, and the `prompt` *"Which apps should get Impeccable previews?"*. The tool words the question and lists the state's apps (the repository's own, `main`, only where the Worker kept it as a product of its own), each picked as it is on, or every one after this run's confirm. Mark the Apps task in progress first. Every write and host tool for an app is refused until it is answered. Done when it answered `values`, `named` (the command was started for that one app with `--app`, from its card on the dashboard: the tool showed one confirm screen naming that app instead of the list, and the list all the same when the person asked for other apps there), or a skip, whose `on` lists the apps that are on: the ones this run sets up. After `named`, that app is the one this run sets up: every host read, key, proof, method and check is its own, and no other app is mentioned past that screen.
 3. **Write the picks**, one action a call as the item's instructions give them: `enable` each chosen app that is off, then `disable` each app that is on and was not chosen. The last app that is on cannot be switched off (409), which is why the enables come first. **After `named`**, `enable` that app when it is off, and switch no other off. **After Skip**, write nothing more: the apps that are on stay on. Done when the last answer's `apps` show `enabled` true for every chosen app and false for the rest (after `named`, true for that app), or, after Skip, nothing was written.
 4. **Read the state again** with impeccable_state. Done when the preview item's `apps` names each chosen app's `directory`, `build` and `method` (none yet for an app not set up), and `perApp` its status.
-5. **Set each chosen app up**, one after the other, as the playbook's steps 3 and 4 say for that app alone, `appKey` on every write and check (`preview`, `test-accounts`, `latest-pull-check`, `connection-check`): its method by the case that applies to it (server-previews when its pages need a server, static-site when they do not, a host's case when the host deploys that app as a project of its own, proven on that app's own address: impeccable_hosted_previews, impeccable_netlify_previews and impeccable_cloudflare_previews take its `appKey` and list only the previews of the project or site that builds its folder, so another app's address, project or key never stands in for it; their `unmatched` says why none can be told, and that app goes as server-previews or static-site says, with the reason under "What is not verified"), and its own sign-in when the scan item's `accessByApp` says it has one, each account question's title naming the app (*"Order desk admin account"*). Done when every chosen app's method is saved, or its preview skipped as server-previews says, and its sign-in saved or skipped, and no other app got a write, a build or a question.
-6. **The pull requests** as pull-requests says, once for the repository: the setup commit takes the state's one workflow `file` (a job for each chosen static site whose preview Impeccable builds) once every chosen app's method and build settings are saved, or its preview skipped as server-previews says; the test drive adds its page to every chosen app with a preview (an app whose preview was skipped gets none, and goes under "What was skipped, and why"), in that app's own framework and linked from that app's own public page, so one review renders each of them on its own preview; that case's step 3 proves each chosen app with the input that proved it; its step 6 checks once, with the `appKey` of the first chosen app with a preview, and the other apps' previews go under "What is not verified". Done when pull-requests' steps are done.
+5. **Set each chosen app up**, one after the other, as the playbook's steps 3 and 4 say for that app alone, `appKey` on every write and check (`preview`, `test-accounts`, `latest-pull-check`, `connection-check`): its method by the case that applies to it (server-previews when its pages need a server, static-site when they do not, a host's case when the host deploys that app as a project of its own, proven on that app's own address: impeccable_hosted_previews, impeccable_netlify_previews and impeccable_cloudflare_previews take its `appKey` and list only the previews of the project or site that builds its folder, so another app's address, project or key never stands in for it; their `unmatched` says why none can be told, and that app goes as server-previews or static-site says, with the reason under "What is not verified"), and its own sign-in when the scan item's `accessByApp` says it has one, each account question's title naming the app (*"Order desk admin account"*). **The lock in front of each app's previews is that app's own**: when its proof answers a `gate`, preview-protection's steps run for that app, with its `appKey`, before any other app's step (the tools refuse the next app's reads and writes until its key tool was called), and the key goes to that app's own project or site; a key saved for one app says nothing about another's, and the state's `keySaved` speaks for one app at most. Done when every chosen app's method is saved, or its preview skipped as server-previews says, and its sign-in saved or skipped, and no other app got a write, a build or a question.
+6. **The pull requests** as pull-requests says, once for the repository: the setup commit takes the state's one workflow `file` (a job for each chosen static site whose preview Impeccable builds) once every chosen app's method and build settings are saved, or its preview skipped as server-previews says; the test drive adds its page to every chosen app with a preview (an app whose preview was skipped gets none, and goes under "What was skipped, and why"), in that app's own framework and linked from that app's own public page, so one review renders each of them on its own preview; that case's step 3 proves each chosen app with the input that proved it; its step 4 proves the test drive's page on each chosen app's own preview, with that app's key where its lock stands in front; its step 6 checks each chosen app with a preview, with its `appKey`, one call each. Done when pull-requests' steps are done.
    - **A chosen app whose preview was skipped** (server-previews): it stays on, with no method, no job in the workflow and no test drive page. It holds nothing back: the other apps' setup commit, test drive and checks go on as above, and its checkup entry left in `next` counts as done for the playbook's step 5. The report says, on its line and under "What was skipped, and why", that it gets no preview until its host deploys them.
    - **A host previews some chosen apps and Impeccable builds the others**: a host's case speaks for its own app. The setup commit carries the workflow for the others and the test drive branches from it, and pull-requests' step 4 goes each app's way: the host's app proven on the host's build, the others by the workflow. The repository goes without a workflow and a setup pull request only where a host previews every chosen app.
-7. **Report per app**: under "What was configured, and by whom", one line per app the question offered: on or off and why (picked, unticked, named with `--app`, on already after a skip), its method, its sign-in, what was verified; an app left out is under "What was skipped, and why" as well, with the setup page as where it is turned on. Done when every app is on one line.
+7. **Report per app**: under "What was configured, and by whom", one line per app the question offered: on or off and why (picked, unticked, named with `--app`, on already after a skip), its method, its sign-in, what was verified; an app left out is under "What was skipped, and why" as well, with the setup page as where it is turned on. impeccable_report adds a section of its own, "Each app, as this run left it", from what the run saved and proved, and the last screen says "You're all set up" only when every chosen app is: an app whose preview met a lock with no key saved, or got no method, is named there with its one step, so the report's lines say the same. Done when every app is on one line.
 
 ### Reference
 

package/dist/playbook/cases/preview-protection.md

@@ -20,7 +20,7 @@ impeccable_prove_preview answered a `gate`: the host's own lock stands in front
 
 - **The report** names, under "What was configured, and by whom", the Vercel project that holds the secret named "Impeccable reviews" (`project`), whether this run created it, found it there or the person typed it, and where it is revoked: the project's Settings → Deployment Protection → Protection Bypass for Automation; or the Netlify site (`site`) whose password is stored, whether this run read it from the site or the person typed it, and where it is changed: the site's Project configuration → General → Visitor access; or, with `opened`, the Netlify site made public, by this run on the person's yes or by the person on Netlify's page (`madePublic`), so anyone with its address opens it, and where it is made private again: the same Visitor access; or the service token named "Impeccable reviews", whether this run created it or the person typed it, the Access application whose policy allows it (`application`), when a created one runs out (`expires`), and where it is revoked: Zero Trust → Access controls → Service credentials → Service Tokens; with `apiToken`, the Cloudflare API token the person made for the run is theirs to delete (dash.cloudflare.com/profile/api-tokens). Revoking, regenerating or changing it stops reviews until a new one is saved on the setup page.
 - **The tool does the writes**: the key as Impeccable's credential for the lock, and the setting that sends it in the host's header (`x-vercel-protection-bypass`, `Authorization`, or `CF-Access-Client-Id` and `CF-Access-Client-Secret`), both through the setup API, so impeccable_write refuses those two. The state's `preview-protection` item words the same calls, and shows `keySaved` once they are done.
-- **A key saved before** (the item shows `keySaved` and a `check` that `passed`): the lock was handled by an earlier run or the person. Run step 2's check and go on; call the tool only when that check fails.
+- **A key saved before** (the item shows `keySaved` and a `check` that `passed`): the lock was handled by an earlier run or the person. Run step 2's check and go on; call the tool only when that check fails. On a repository with several apps, the item's `keySaved` speaks for one app at most: an app whose own proof answered a `gate` gets step 1 with its `appKey`, whatever another app's key did, and its step 2 check is its own.
 - **The key is never yours**: it goes from the command's own process to the host and to Impeccable, and into no message, status line, file, command or report. `vercel project protection`, `vercel api`, `vercel curl` and `netlify api` print it, and the fence refuses them.
 - **The app's own sign-in** is another card: a preview opened past the lock proves nothing about it.
 - **Status lines** belong to the Preview method task. Word Vercel's login and Cloudflare Access as a login, and Netlify's lock as a password.

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

@@ -2,6 +2,8 @@
 
 Vercel deploys previews of the pull requests: impeccable_hosted_previews lists a successful Preview deployment that Vercel made (`vercel: true`) of a pull request, with its address. The checkout often shows it too (`vercel.json`, `.vercel/project.json`, a `vercel` dependency), but GitHub's record decides. Vercel builds and serves every preview, so these steps replace the playbook's step 3, and the repository needs no workflow and no setup pull request.
 
+It applies as well **before the first pull request**: Vercel deploys the repository already (impeccable_hosted_previews lists deployments Vercel made, production ones or of pushes, and none of a pull request; on a repository with several apps, those of the project that builds the app, named in `project`), so its previews start with the test drive's push. Then there is nothing to prove in step 1 yet: impeccable_ask with `vercel-setup` is refused, since there is no sign-in, project or connection to make; go on to pull-requests' step 4, which pushes the test drive, waits for Vercel's deployment of the pushed branch (impeccable_hosted_previews with `branch`, and the app's `appKey`), proves the test drive's page there, past Vercel's login as preview-protection says, and then step 2 saves the method.
+
 ### Steps
 
 1. **Prove the newest preview** with impeccable_prove_preview: the address of the newest successful Preview deployment of a pull request (on a repository with several apps, the newest of those impeccable_hosted_previews listed for the app's `appKey`, the deployments of the Vercel project that builds its folder) (or a page on it a visitor opens without signing in, when the app's own sign-in answers there), and words the page shows that the checkout holds, such as the app's name in its title. Done when it answers `proven: true`; when an address no longer answers, try the next newest, three at most.

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

@@ -1,6 +1,6 @@
 ### When this applies
 
-The checkout is set up for Vercel (`vercel.json`, `.vercel/project.json`, a `vercel` dependency or script), or the person picked Vercel in server-previews, and Vercel has never deployed it: impeccable_hosted_previews lists no deployment that Vercel made (`vercel: true`), and no `error` (an error says nothing either way). These steps replace the playbook's step 3. As in vercel-previews, the repository needs no workflow and no setup pull request.
+The checkout is set up for Vercel (`vercel.json`, `.vercel/project.json`, a `vercel` dependency or script), or the person picked Vercel in server-previews, and Vercel has never deployed it: impeccable_hosted_previews lists no deployment that Vercel made (`vercel: true`) of any kind, production ones included, and no `error` (an error says nothing either way); on a repository with several apps, it names no project of the app's (`unmatched`). A repository Vercel deploys already, with no pull request yet, is vercel-previews' ("before the first pull request"), and step 1's screen is refused for it. These steps replace the playbook's step 3. As in vercel-previews, the repository needs no workflow and no setup pull request.
 
 ### Steps
 

package/dist/tools.js

@@ -10,7 +10,7 @@ import { defineTool } from '@earendil-works/pi-coding-agent';
 import { agreeToHostSetup, bindPreviewPullRequest, chooseHostTeam, chosenHostTeam, classifyPreviewCommand, endHostSetup, hostSetupAgreed, isSecretFile, linkedByRun, observePreviewAttempts, parseCommand, previewRetryState, settleVercelFirstDeployment, vercelProjectsAdded } from './fence.js';
 import { requestJson } from './http.js';
 import { appsLeftOut, focusCheckup, focusInstructions, focusState, severalApps } from './focus.js';
-import { APPS_QUESTION, HOST_QUESTIONS, HOST_SCREENS, HOST_SIGNED_IN, sentTo, startedIn } from './host-questions.js';
+import { APPS_QUESTION, HOST_QUESTIONS, HOST_SCREENS, HOST_SIGNED_IN, namedAppQuestion, sentTo, startedIn } from './host-questions.js';
 import { enableNetlifyPreviews, folderOf } from './host-previews.js';
 import { checkoutNames, liveShaped, netlifySiteOf, previewHostName, provePreview, readHostedPreviews } from './hosted.js';
 import { cfRunner, cfStatus, CLOUDFLARE_APP_PAGE, connectCloudflareProject, enableCloudflarePreviews, pagesProject, pagesProjectName, readCloudflarePreviews } from './cloudflare.js';
@@ -107,6 +107,21 @@ export function resolveWrite(instructions, setupApi, repo, path) {
     }
     return { error: `No PUT or POST in the instructions' "endpoints" matches ${pathname}. Pick one from there.` };
 }
+/** The last screen's words for a run on several apps: the picked apps not set up, by name, the line naming which are and which are not, and a line for each that is not. */
+export function appsSummary(apps) {
+    const picked = apps.filter((a) => a.state !== 'unpicked');
+    const ready = picked.filter((a) => a.state === 'ready');
+    const rest = picked.filter((a) => a.state !== 'ready');
+    const names = (list) => list.map((a) => a.name).join(', ');
+    const line = [...(ready.length ? [`Set up: ${names(ready)}.`] : []), ...(rest.length ? [`Not set up: ${names(rest)}.`] : [])].join(' ');
+    return { notReady: rest.map((a) => a.name), line, todo: rest.flatMap((a) => (a.left ? [a.left] : [])) };
+}
+/** A host's lock in front of a preview, as impeccable_prove_preview names it: how the person reads it, the tool that gets a key past it, and the step left where none was saved (preview-protection's step 3). */
+const LOCKS = {
+    'vercel-protection': { lock: "Vercel's login", tool: 'impeccable_vercel_bypass', left: 'Save the Vercel bypass secret on the setup page' },
+    'netlify-protection': { lock: "Netlify's password or team login", tool: 'impeccable_netlify_password', left: 'Save the Netlify site password on the setup page, or make the site public on its Visitor access page' },
+    'cloudflare-access': { lock: 'Cloudflare Access', tool: 'impeccable_cloudflare_access', left: 'Save the Cloudflare service token on the setup page' },
+};
 const NO_INPUT = { type: 'object', properties: {}, additionalProperties: false };
 /** Why the status line and the task list say different things, one task in progress at a time and the status its detail; null when they agree. */
 function stageError(status, tasks) {
@@ -803,18 +818,34 @@ export async function driveCoversSetup(cwd, setupBranch, driveBranch) {
  * What the pushed `head` changes against `base`, as their remote-tracking refs in this checkout show GitHub: each file's
  * `git diff --name-status` letter and its path as it is, never quoted; a rename as a removal and an addition. Null when either ref is missing or git fails.
  */
-export async function pushedChanges(cwd, base, head) {
+export async function pushedChanges(cwd, base, head, lessSetup = false) {
     try {
+        const git = (args, timeout = 10_000) => execFileAsync('git', args, { cwd, timeout, env: gitEnvironment() });
         // The two branches as the remote has them, fetched so the diff can be read here: refs/remotes/origin/* sit in the checkout's git folder, where a command in the sandbox can move them.
         const refs = [`refs/heads/${base}`, `refs/heads/${head}`];
-        const { stdout: heads } = await execFileAsync('git', ['ls-remote', '--heads', 'origin', ...refs], { cwd, timeout: 60_000, env: gitEnvironment() });
+        const { stdout: heads } = await git(['ls-remote', '--heads', 'origin', ...refs], 60_000);
         const sha = new Map(heads.split('\n').filter(Boolean).map((line) => line.split('\t').reverse()));
         if (!refs.every((ref) => sha.has(ref)))
             return null;
-        await execFileAsync('git', ['fetch', '--quiet', '--no-tags', '--no-write-fetch-head', 'origin', ...refs], { cwd, timeout: 60_000, env: gitEnvironment() });
-        const { stdout } = await execFileAsync('git', ['diff', '-z', '--name-status', '--no-renames', `${sha.get(refs[0])}...${sha.get(refs[1])}`], { cwd, timeout: 10_000, env: gitEnvironment() });
-        const fields = stdout.split('\0');
-        return Array.from({ length: Math.floor(fields.length / 2) }, (_, i) => ({ status: fields[2 * i], path: fields[2 * i + 1] }));
+        await git(['fetch', '--quiet', '--no-tags', '--no-write-fetch-head', 'origin', ...refs], 60_000);
+        // From where the two met (three dots), so a base that moved on since the branch left it adds nothing of its own.
+        const changed = async (from, to) => {
+            const { stdout } = await git(['diff', '-z', '--name-status', '--no-renames', `${from}...${to}`]);
+            const fields = stdout.split('\0');
+            return Array.from({ length: Math.floor(fields.length / 2) }, (_, i) => ({ status: fields[2 * i], path: fields[2 * i + 1] }));
+        };
+        const pushed = sha.get(refs[1]);
+        if (!lessSetup)
+            return changed(sha.get(refs[0]), pushed);
+        // The test drive branches from the setup commit, so a diff from the base carries the setup branch's files too (the workflow, a build fix). Read from the local setup branch under the pushed head instead (impeccable/setup, or its -N; of several, the nearest), the changes are the test drive's own: a file the setup branch changed and the test drive changed again is among them, one it left as the setup branch had it is not.
+        const { stdout: setups } = await git(['for-each-ref', '--format=%(refname)', 'refs/heads/impeccable/setup', 'refs/heads/impeccable/setup-*']);
+        const isAncestor = (of, to) => git(['merge-base', '--is-ancestor', of, to]).then(() => true, () => false);
+        let setup;
+        for (const ref of setups.split('\n').filter(Boolean)) {
+            if ((await isAncestor(ref, pushed)) && (setup === undefined || (await isAncestor(setup, ref))))
+                setup = ref;
+        }
+        return changed(setup ?? sha.get(refs[0]), pushed);
     }
     catch {
         return null;
@@ -1648,6 +1679,12 @@ export function createTools(ctx) {
     /** On a repository with several apps: the app each production address a host tool answered is the live app of, read for that app's own project or site, and the apps whose host preview a proof opened. */
     const liveApps = new Map();
     const provenApps = new Set();
+    /** On a repository with several apps (#286): the method each app's preview write saved; the host's lock a proof of each app's preview met; and the apps whose lock was met with no key tool called for them since, which holds every other app's steps until it is. */
+    const appMethods = new Map();
+    const lockMet = new Map();
+    const lockPending = new Map();
+    /** The projects whose deployments Vercel made of this repository, as impeccable_hosted_previews read them, by the app read for ('' for the repository): a repository Vercel deploys already needs no Vercel setup, since its previews start with the first pull request (#286). */
+    const vercelDeployed = new Map();
     /** Each Vercel project's production address, read from Vercel, by origin, and the project it was read from: the one live address the project's own bypass secret is sent to, since a secret is one project's, and the link file can name another project of this repository between the two reads. */
     const vercelProductions = new Map();
     /** The bypass secret a proof sends to `origin`: the one proved there, or, for a live address, the one of the project whose production it is. */
@@ -1938,6 +1975,10 @@ export function createTools(ctx) {
     let confirmedApps = false;
     /** Each app's folder, by key, as the state names it: what its host project or site must build. */
     const appFolders = new Map();
+    /** The apps as the state last listed them. */
+    let knownApps = null;
+    /** An app's name as the state gives it, or its key. */
+    const appName = (key) => knownApps?.find((a) => a.key === key)?.name ?? key;
     /**
      * A read of the state or the checkup, trimmed to this setup before the model sees it. The setup token covers the apps
      * there were at sign-in, so an app the scan proposed later reads `not-selected`: the run signs in again, for a token
@@ -1971,6 +2012,7 @@ export function createTools(ctx) {
         });
         for (const app of apps)
             appFolders.set(app.key, app.folder);
+        knownApps = apps;
         return apps;
     };
     /** An app's folder, read from the state the first time it is asked for. */
@@ -1988,6 +2030,48 @@ export function createTools(ctx) {
             return `Refused: give "appKey", the key of an app this run sets up (${[...pickedApps].join(', ')}). Nothing was ${what}.`;
         return null;
     };
+    /**
+     * On a repository with several apps, why a step for another app than `appKey` may not run yet: an app's proof met a
+     * host's lock, and the tool that gets a key past it was not called for that app since, so its key would never be put
+     * in place (#286). Null where it may: no lock met, or every one answered by its tool.
+     */
+    const lockRefusal = (appKey, what) => {
+        for (const [key, gate] of lockPending) {
+            if (key === appKey)
+                continue;
+            const { lock, tool } = LOCKS[gate];
+            return `Refused: ${appName(key)}'s preview is behind ${lock}, and ${tool} was not called for it: call it first, as preview-protection says, so each app gets its own key. Nothing was ${what}.`;
+        }
+        return null;
+    };
+    /** How this run left each app the state lists (#286), for the report and the last screen. */
+    const appOutcomes = async (pi) => {
+        const apps = knownApps ?? (await stateApps(pi)) ?? [];
+        return apps.map(({ key, name, folder }) => {
+            const method = appMethods.get(key);
+            const gate = lockMet.get(key);
+            const proven = provenApps.has(key);
+            if (!pickedApps?.has(key))
+                return { key, name, folder, state: 'unpicked' };
+            if (method !== undefined && (method !== 'preview-deploy' || proven))
+                return { key, name, folder, state: 'ready' };
+            if (gate && !proven)
+                return { key, name, folder, state: 'locked', left: `${name}: its previews are behind ${LOCKS[gate].lock}, and no key was saved. ${LOCKS[gate].left}.` };
+            return { key, name, folder, state: 'unset', left: `${name}: no preview method was saved; the report says why.` };
+        });
+    };
+    /** The report's section on the apps, one line each, from what this run saved and proved rather than from the model's words. */
+    const appsSection = (apps) => `\n\n## Each app, as this run left it\n\n${apps.map((a) => {
+        const where = `${a.name} (${a.folder || '/'})`;
+        const lock = lockMet.has(a.key) ? LOCKS[lockMet.get(a.key)].lock : undefined;
+        if (a.state === 'ready')
+            return `- ${where}: set up. Method: ${appMethods.get(a.key)}${provenApps.has(a.key) ? `, its preview proven${lock ? ` past ${lock}` : ''}` : ''}.`;
+        if (a.state === 'locked')
+            return `- ${where}: not set up. Its previews are behind ${lock}, and no key was saved for it.`;
+        if (a.state === 'unset')
+            return `- ${where}: not set up. No preview method was saved for it.`;
+        return `- ${where}: not set up this run.`;
+    }).join('\n')}`;
     /** Each app's Vercel project, found once a run (a failure is read again, the CLI may have signed in since). */
     const vercelApps = new Map();
     /** The app's Vercel project as this repository's, read now for its deployments: the one that builds the app's folder, or why none can be told. */
@@ -2016,15 +2100,17 @@ export function createTools(ctx) {
         const apps = await stateApps(pi);
         if (!apps || apps.length < 2)
             return 'Refused: the setup state could not be read, or lists fewer than two apps: read it again with impeccable_state, then ask again.';
-        if (ctx.app !== undefined && apps.some((a) => a.key === ctx.app)) {
-            pickedApps = new Set([ctx.app]);
-            return JSON.stringify({ values: [ctx.app], named: true });
+        // Started for one app (--app, from its card): one confirm screen naming it instead of the list, whose Skip opens the list for someone who wants another app (#286).
+        const named = ctx.app !== undefined ? apps.find((a) => a.key === ctx.app) : undefined;
+        if (named && !(await ask(namedAppQuestion(named))).skipped) {
+            pickedApps = new Set([named.key]);
+            return JSON.stringify({ values: [named.key], named: true });
         }
         // Started below the top: the app whose folder holds that folder (the deepest, never the root's) is ticked too, and the hint says so.
         const start = ctx.start ?? '';
         const here = start ? apps.filter((a) => a.folder && (start === a.folder || start.startsWith(`${a.folder}/`))).sort((a, b) => b.folder.length - a.folder.length)[0] : undefined;
         const hint = here ? startedIn(`${here.name}'s folder`) : start ? startedIn(start) : APPS_QUESTION.hint;
-        const answer = await ask({ ...APPS_QUESTION, hint, options: apps.map((a) => ({ label: `${a.name} · ${a.folder || '/'}`, value: a.key, selected: confirmedApps || a.enabled || a === here })) });
+        const answer = await ask({ ...APPS_QUESTION, hint, options: apps.map((a) => ({ label: `${a.name} · ${a.folder || '/'}`, value: a.key, selected: confirmedApps || a.enabled || a === here || a === named })) });
         if (answer.skipped) {
             pickedApps = new Set(apps.filter((a) => a.enabled).map((a) => a.key));
             return JSON.stringify({ skipped: true, on: [...pickedApps] });
@@ -2114,7 +2200,7 @@ export function createTools(ctx) {
             // On a repository with several apps, nothing but the apps write goes before the apps question, and an app's setting or check names a picked app.
             const forApp = /\/(preview|test-accounts|connection-check|latest-pull-check)$/.test(target.url);
             if (!target.url.endsWith('/apps')) {
-                const refused = appRefusal(object(p.body)?.appKey, 'saved', forApp);
+                const refused = appRefusal(object(p.body)?.appKey, 'saved', forApp) ?? (target.url.endsWith('/preview') ? lockRefusal(object(p.body)?.appKey, 'saved') : null);
                 if (refused)
                     return refused;
             }
@@ -2167,6 +2253,8 @@ export function createTools(ctx) {
                     savedHost = provenHost;
                 if (saved?.appKey !== undefined)
                     perApp = true;
+                if (saved?.appKey !== undefined && typeof saved.intendedMethod === 'string')
+                    appMethods.set(String(saved.appKey), saved.intendedMethod);
                 if (saved && 'intendedMethod' in saved)
                     hostMethod = saved.intendedMethod === 'preview-deploy';
                 for (const key of Object.keys(object(p.body) ?? {}))
@@ -2191,12 +2279,18 @@ export function createTools(ctx) {
             // A test account never comes back to the model, even if the API echoed it.
             return testAccounts ? redact(answerText(response), typed.values()) : answerText(response);
         }),
-        tool('impeccable_ask', 'Ask the person', 'Ask the person one question in a dialog, and wait for the answer; the web page shows the run waiting meanwhile. Answers {"value": "…"} for text and single, {"values": […]} for multi, {"confirmed": true} for confirm, {"username": "…", "password": "secret:…"} for account, or {"skipped": true}. A host\'s setup question (id "vercel-setup", "vercel-team", "netlify-setup" or "netlify-team") is worded by this tool: give it that id and its kind. So is the apps question on a repository with several apps (id "apps", kind "multi"), which lists the state\'s apps itself and answers {"values": […]}, {"values": [key], "named": true} when the command was started for that app, or {"skipped": true, "on": […]}. netlify-setup and vercel-setup are the host\'s sign-in: it shows its screen only when that CLI is signed out, signs the person in through the browser with a retry, and answers {"confirmed": true, "signedIn": true}, with "team" (the one the project goes into) or "teams" to choose from when the person has several, {"confirmed": true, "cli": "missing"} when the CLI is to be installed first and this asked again, or {"skipped": true}.', ASK, async (p, pi, signal) => {
+        tool('impeccable_ask', 'Ask the person', 'Ask the person one question in a dialog, and wait for the answer; the web page shows the run waiting meanwhile. Answers {"value": "…"} for text and single, {"values": […]} for multi, {"confirmed": true} for confirm, {"username": "…", "password": "secret:…"} for account, or {"skipped": true}. A host\'s setup question (id "vercel-setup", "vercel-team", "netlify-setup" or "netlify-team") is worded by this tool: give it that id and its kind. So is the apps question on a repository with several apps (id "apps", kind "multi"), which lists the state\'s apps itself and answers {"values": […]}, {"values": [key], "named": true} when the command was started for that app (it shows one confirm screen naming the app instead of the list, and the list when the person asks for other apps there), or {"skipped": true, "on": […]}. netlify-setup and vercel-setup are the host\'s sign-in: it shows its screen only when that CLI is signed out, signs the person in through the browser with a retry, and answers {"confirmed": true, "signedIn": true}, with "team" (the one the project goes into) or "teams" to choose from when the person has several, {"confirmed": true, "cli": "missing"} when the CLI is to be installed first and this asked again, or {"skipped": true}.', ASK, async (p, pi, signal) => {
             // A skip never stops the run, so every question offers one.
             const asked = p;
             if (asked.id === APPS_QUESTION.id && appsRepo)
                 return appsQuestion(pi);
             const host = /^(netlify|vercel)-(setup|team)$/.exec(asked.id);
+            // The Vercel setup is for a repository Vercel has never deployed: one it deploys already (every app this run sets up, on a repository with several), as impeccable_hosted_previews read it, gets its previews from the first pull request on (#286). An app with no project of its own still gets the screen, and a setup under way (asked again once the CLI was installed) is not stopped here.
+            const deployed = appsRepo ? pickedApps !== undefined && pickedApps.size > 0 && [...pickedApps].every((key) => vercelDeployed.has(key)) : vercelDeployed.has('');
+            if (asked.id === 'vercel-setup' && deployed && !hostSignIns.has('vercel')) {
+                const projects = [...vercelDeployed.values()].filter(Boolean);
+                return `Refused: Vercel deploys this repository already${projects.length ? ` (${projects.join(', ')})` : ''}: it made deployments of it, production included, so its previews start with the first pull request, and there is no Vercel sign-in, project or connection to make. Go on as vercel-previews says: build and push the test drive as pull-requests' step 4 says, wait for Vercel's deployment of the pushed branch with impeccable_hosted_previews and branch, prove the test drive's page there (past Vercel's login as preview-protection says), and save the method.`;
+            }
             if (host?.[2] === 'setup')
                 return JSON.stringify(await hostSignIn(host[1], pi, signal));
             if (host && (teamChoices.get(host[1])?.length ?? 0) < 2)
@@ -2265,11 +2359,18 @@ export function createTools(ctx) {
                 return `Refused: ${found.problem}.`;
             drive.url = found.url;
             // The page that links to the test drive is an existing file the branch changes; files under dot folders (.github, .netlify) and dotfiles never link to it (#241).
-            const changes = !recordedBranches && found.base ? await (ctx.pushedChanges ?? pushedChanges)(pi.cwd, found.base, found.branch) : null;
+            const changes = !recordedBranches && found.base ? await (ctx.pushedChanges ?? pushedChanges)(pi.cwd, found.base, found.branch, true) : null;
             const files = (changes ?? []).filter(({ path }) => !path.split('/').some((part) => part.startsWith('.')));
             if (files.length && files.every(({ status }) => status === 'A')) {
                 return `Refused: ${found.branch} only adds ${files.map(({ path }) => path).join(', ')} and changes no existing page, so nothing links to the test drive. Commit the page that links to it and push, prove the new push's preview again as pull-requests' step 4 says, then record it again.`;
             }
+            // On a repository with several apps, the test drive's page goes into a picked app's own folder, and no other app is touched (#286): a file it adds anywhere else is refused, whatever its name. The setup branch's own files (a build fix at the root) are not in `files`, as pushedChanges leaves them out.
+            if (appsRepo && pickedApps) {
+                const folders = (await Promise.all([...pickedApps].map((key) => appFolder(pi, key)))).filter((folder) => folder !== undefined);
+                const outside = files.filter(({ status, path }) => status === 'A' && !folders.some((folder) => !folder || path.startsWith(`${folder}/`))).map(({ path }) => path);
+                if (outside.length)
+                    return `Refused: ${found.branch} adds ${outside.join(', ')}, outside the folders of the apps this run sets up (${folders.map((folder) => folder || '/').join(', ')}). The test drive's page goes into each picked app's own folder, as the monorepo case says, and no other app is touched: move it, push, prove the new push's preview again as pull-requests' step 4 says, then record it again.`;
+            }
             let setupBranch = recordedBranches?.setup, setupBase = recordedBranches?.setupBase;
             if (setup) {
                 // The setup pull request carries the preview attempts, so its binding cannot change.
@@ -2299,6 +2400,9 @@ export function createTools(ctx) {
             const control = left.find((line) => plainText(line) !== line);
             if (control)
                 return `Refused: "${control}" holds a control character or an escape sequence. Each line of "left" is plain text. Nothing was saved: call impeccable_report again.`;
+            const pending = lockRefusal(undefined, 'saved');
+            if (pending)
+                return `${pending} Call impeccable_report again once it answered.`;
             // The web page keeps the task list as the report leaves it, so no task may still read as waiting or running (#83).
             const open = ctx.sync.payload.tasks.filter((t) => !t.id.startsWith('preview-attempt-') && (t.status === 'pending' || t.status === 'in_progress'));
             if (open.length)
@@ -2312,6 +2416,10 @@ export function createTools(ctx) {
                 const shown = (path) => path.replace(/[\\`*_[\]<>|~]/g, '\\$&').replace(/[\x00-\x1f\x7f]/g, (c) => JSON.stringify(c).slice(1, -1));
                 markdown += `\n\n## What the setup pull request changes\n\n${changes ? changes.map(({ status, path }) => `- ${shown(path)} (${verbs[status] ?? status})`).join('\n') || 'Nothing: it carries no file.' : 'This checkout could not list its files: read them on the pull request before merging.'}`;
             }
+            // On a repository with several apps, how this run left each app, from what it saved and proved (#286).
+            const apps = appsRepo && pickedApps ? await appOutcomes(pi) : undefined;
+            if (apps)
+                markdown += appsSection(apps);
             if (previews.active && retry.pr) {
                 await observe(signal);
                 const lines = attempts().map((a, i) => `${i + 1}. [Attempt ${i + 1}](${a.url}) (run attempt ${a.attempt}): ${a.status}. ${a.diagnostics.map((d) => `${d.appKey}: step ${d.stage ?? 'unverified'}. ${d.reason}`).join(' ')}${a.changes.length ? ` Changed settings: ${a.changes.join(', ')}.` : ''}`);
@@ -2335,14 +2443,14 @@ export function createTools(ctx) {
                 return `Error: the report was refused (${res.status}: ${res.error}). Fix what it says and call impeccable_report again.`;
             }
             // Otherwise final: a completed write whose answer was lost may still have landed, so it is never taken back.
-            ctx.onReport({ markdown, left, testPr: drive, setupPr: ctx.sync.payload.setup_pr, ...(savedHost ? { hostedBy: savedHost } : {}) });
+            ctx.onReport({ markdown, left, testPr: drive, setupPr: ctx.sync.payload.setup_pr, ...(savedHost ? { hostedBy: savedHost } : {}), ...(apps ? { apps } : {}) });
             pi.shutdown();
             const saved = res?.ok ? 'Saved.' : `The web page did not take it (${res?.error ?? 'no answer'}).`;
             return { text: `${saved} The terminal shows the summary and the command exits.`, terminate: true };
         }),
         tool('impeccable_hosted_previews', 'Hosted previews', 'Read the deployments GitHub has on record for this repository: the 20 newest, each with its latest status, its address, its environment, whether Vercel made it and the pull requests whose commit it built. An error says nothing either way. Without branch, where GitHub records a production deployment Vercel made and this folder is linked to the project (.vercel/project.json) the Vercel CLI reads as this repository\'s, production is the live app\'s address, the project\'s own domain, for the before. With branch (a branch of this run, pushed, before its pull request exists), only its head\'s, waiting up to five minutes for Vercel\'s deployment of it to finish building, under a status line with its timer, and again on the person\'s yes when the time ran out. A Production deployment of that branch (a project\'s first is, whatever branch it builds) is listed as its preview only while the project this folder is linked to is locked at every address (impeccable_vercel_connect locks it) and made it, read from Vercel at that moment, since a production deployment is otherwise served at the project\'s own address without a login; then no proof opens it. It changes nothing on the host and proves nothing about the page.', HOSTED_PREVIEWS, async (p, pi, signal) => {
             const branch = p.branch;
-            const refused = appRefusal(p.appKey, 'read');
+            const refused = appRefusal(p.appKey, 'read') ?? lockRefusal(p.appKey, 'read');
             if (refused)
                 return refused;
             // The fact, the live app and an app's project read the same projects: each `vercel api` call is made once.
@@ -2412,6 +2520,13 @@ export function createTools(ctx) {
                 if (app)
                     listedApps.set(url.origin, { appKey: appKey, link: app.link, name: app.name });
             }
+            // Vercel deploys the repository (this app's project did) when it made a deployment of it, production included: then its previews start with the first pull request, and no Vercel setup is asked (#286).
+            if (branch === undefined) {
+                if (evidence.deployments.some((d) => d.vercel && d.state === 'success'))
+                    vercelDeployed.set(appKey ?? '', app?.name ?? '');
+                else
+                    vercelDeployed.delete(appKey ?? '');
+            }
             // What vercel.json and the linked project (the app's, with its folder's vercel.json) say of the test drive's branch rides with the plain evidence, never with a wait: reported, never changed.
             if (branch === undefined) {
                 const fact = await (ctx.vercelPreviewsReader ?? vercelPreviewsFact)(pi.cwd, `${ctx.owner}/${ctx.repo}`, () => vercel, app ? { directory: app.folder, link: app.link } : undefined);
@@ -2435,7 +2550,7 @@ export function createTools(ctx) {
         }),
         tool('impeccable_netlify_previews', 'Netlify previews', "Read whether this repository's pull requests get Netlify deploy previews: the 10 newest, each with its site, its address, its state and where that was read: GitHub's commit status or Netlify's bot comment on the pull request, or the Netlify CLI on this machine when it is signed in (read only: it never signs in). production is the live site's own address, for the before. cli says whether that CLI is missing, signed out, signed in or did not answer. An error says something could not be read, which is unknown rather than absent. With pull (a pull request of this run, a draft included: Netlify builds a deploy preview only for a pull request), only that pull request's, waiting up to five minutes for one to finish building, under a status line with its timer, and again on the person's yes when the time ran out. It changes nothing on Netlify and proves nothing about the page.", NETLIFY_PREVIEWS, async (p, pi, signal) => {
             const pull = p.pull;
-            const refused = appRefusal(p.appKey, 'read');
+            const refused = appRefusal(p.appKey, 'read') ?? lockRefusal(p.appKey, 'read');
             if (refused)
                 return refused;
             // On a repository with several apps, only the site that builds the app's folder (#281).
@@ -2473,7 +2588,7 @@ export function createTools(ctx) {
             const branch = p.branch;
             if (pull !== undefined && branch !== undefined)
                 return 'Invalid input: give pull or branch, not both.';
-            const refused = appRefusal(p.appKey, 'read');
+            const refused = appRefusal(p.appKey, 'read') ?? lockRefusal(p.appKey, 'read');
             if (refused)
                 return refused;
             // On a repository with several apps, only the Pages project that builds the app's folder (#281): told by the plain read, which a wait for a build keeps to.
@@ -2556,6 +2671,14 @@ export function createTools(ctx) {
                 provenHost = previewHostName(url) ?? provenHost;
             if (proof.proven && app)
                 provenApps.add(app.appKey);
+            if (proof.proven && app)
+                lockPending.delete(app.appKey);
+            // The lock in front of an app's preview is that app's own: its key tool is the next call for it, and every other app's steps wait for that (#286). An earlier proof of the app (another preview, or one the key opened before) says nothing about this lock: the app is proven again only once something opens it.
+            if (app && proof.gate && Object.hasOwn(LOCKS, proof.gate)) {
+                lockMet.set(app.appKey, proof.gate);
+                lockPending.set(app.appKey, proof.gate);
+                provenApps.delete(app.appKey);
+            }
             if (proof.proven && proof.pattern)
                 provenPattern = proof.pattern;
             if (proof.gate === 'vercel-protection' || proof.gate === 'netlify-protection')
@@ -2694,6 +2817,8 @@ export function createTools(ctx) {
             if (gated?.gate !== 'vercel-protection' || !vercelMade.has(new URL(gated.url).origin))
                 return 'Refused: this is for a preview that Vercel made, listed by impeccable_hosted_previews, which impeccable_prove_preview answered with gate "vercel-protection". Prove one first.';
             const at = gated;
+            if (at.app)
+                lockPending.delete(at.app.appKey);
             const { origin, host } = new URL(at.url);
             // Where the setup API keeps the secret: the app's own on a repository with several apps, else the repository's.
             const store = at.app?.appKey ?? '';
@@ -2781,6 +2906,8 @@ export function createTools(ctx) {
             if (!gated || !site)
                 return 'Refused: this is for a Netlify deploy preview, listed by impeccable_netlify_previews, which impeccable_prove_preview answered with gate "netlify-protection". Prove one first.';
             const at = gated;
+            if (at.app)
+                lockPending.delete(at.app.appKey);
             /** The address pattern the proof with the password answers, saved as the method once the password is. */
             let pattern;
             const prove = async (password, form = false) => {
@@ -2880,9 +3007,12 @@ export function createTools(ctx) {
         tool('impeccable_cloudflare_access', 'Cloudflare Access', 'Get past the Cloudflare Access login that impeccable_prove_preview met (gate "cloudflare-access") in front of a Cloudflare Pages preview, the way Cloudflare documents for tools: a service token, sent in two headers, that a Service Auth policy of the Access application allows. It does the rest as the person: one screen asking to create the token, Cloudflare\'s sign-in in the browser where cf, Cloudflare\'s CLI, is not signed in here with Access (with a retry), then the token named "Impeccable reviews" created through cf and allowed in the policy of the application in front of the preview; one screen taking a Cloudflare API token only where that sign-in cannot create it; on a skip, or where that cannot be done, one screen taking a pasted client id and secret, only once an Access application in the person\'s accounts was read to cover the preview (none read: refused, with the reason, since the token goes to no other address). It opens the preview with the token and saves it for reviews. Answers {"status": …}: saved (the preview is proven, and pattern is the address pattern to save with the method; token says whether it was created or typed, application which Access application allows it, expires when a created one runs out, apiToken true when the person\'s Cloudflare API token created it), skipped (nothing was saved; reason says what stopped it), refused (no Access application of the person\'s covers the preview, or the typed token did not open it; reason says which) or save-failed (the setup API did not take it all; reason says how far it got: call it once more). No token ever comes back.', NO_INPUT, async (_p, pi, signal) => {
             if (!accessGated)
                 return 'Refused: this is for a Cloudflare Pages preview impeccable_cloudflare_previews listed, which impeccable_prove_preview answered with gate "cloudflare-access". Prove one first.';
+            const at = accessGated;
+            // The call for this app is made, whatever it answers: the skip asked once stands for the next app's lock too.
+            if (at.app)
+                lockPending.delete(at.app.appKey);
             if (accessOutcome?.status === 'skipped')
                 return JSON.stringify(accessOutcome);
-            const at = accessGated;
             let proof;
             const prove = async (token) => (proof = await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, access: token }));
             const base = `${ctx.setupApi}/repos/${encodeURIComponent(ctx.repo)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impeccable/reviews",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Set up a repository for Impeccable for PRs from your terminal.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,

package/dist/playbook/github-previews.js

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

package/dist/playbook/netlify-pattern.js

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

package/dist/playbook/netlify-previews.js

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

package/dist/playbook/probe-preview.js

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

package/dist/playbook/protection-secrets.js

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

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

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

package/dist/playbook/publication-wait.js

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

package/dist/playbook/vercel-protection.js

@@ -1,121 +0,0 @@
-import { execFile } from 'node:child_process';
-import { constants } from 'node:fs';
-import { lstat, open, realpath } from 'node:fs/promises';
-import { join } from 'node:path';
-const METADATA_LIMIT = 16 * 1024;
-const OUTPUT_LIMIT = 2 * 1024 * 1024;
-function record(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value)
-        ? value : undefined;
-}
-/** Only the root's small project-link metadata is read; CLI authentication stays with the CLI. */
-async function linkedProject(cwd) {
-    try {
-        const root = await realpath(cwd);
-        const directory = join(root, '.vercel');
-        const directoryStat = await lstat(directory);
-        if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink() || await realpath(directory) !== directory)
-            return;
-        const path = join(directory, 'project.json');
-        if (!(await lstat(path)).isFile())
-            return;
-        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-        try {
-            const stat = await file.stat();
-            const currentDirectory = await lstat(directory);
-            const currentFile = await lstat(path);
-            if (!stat.isFile() || stat.size > METADATA_LIMIT
-                || currentDirectory.dev !== directoryStat.dev || currentDirectory.ino !== directoryStat.ino
-                || currentFile.isSymbolicLink() || currentFile.dev !== stat.dev || currentFile.ino !== stat.ino
-                || await realpath(path) !== path)
-                return;
-            const buffer = Buffer.alloc(METADATA_LIMIT + 1);
-            const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
-            if (bytesRead > METADATA_LIMIT)
-                return;
-            const metadata = record(JSON.parse(buffer.toString('utf8', 0, bytesRead)));
-            if (typeof metadata?.projectId !== 'string' || !/^prj_[A-Za-z0-9]{1,128}$/.test(metadata.projectId)
-                || typeof metadata.orgId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(metadata.orgId))
-                return;
-            return { root, projectId: metadata.projectId, orgId: metadata.orgId };
-        }
-        finally {
-            await file.close();
-        }
-    }
-    catch {
-        return;
-    }
-}
-/** Reuse one existing default automation bypass in memory, without exposing project responses or keys. */
-export async function useExistingVercelBypass(input, dependencies) {
-    const { signal } = dependencies;
-    if (signal?.aborted)
-        return { status: 'cancelled' };
-    if (!/^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/.test(input.owner)
-        || !/^[a-zA-Z0-9_.-]{1,100}$/.test(input.repo) || input.repo === '.' || input.repo === '..') {
-        return { status: 'project-mismatch' };
-    }
-    const linked = await linkedProject(input.cwd);
-    if (signal?.aborted)
-        return { status: 'cancelled' };
-    if (!linked)
-        return { status: 'not-linked' };
-    const runVercel = dependencies.runVercel ?? ((args) => new Promise((resolve, reject) => {
-        const child = execFile('vercel', args, {
-            cwd: linked.root, encoding: 'utf8', timeout: 30_000, maxBuffer: OUTPUT_LIMIT, signal,
-        }, (error, stdout) => error ? reject(new Error('Vercel project lookup failed.')) : resolve(stdout));
-        child.stdin?.end();
-    }));
-    // teamId selects the linked team. Legacy personal projects omit it and still require accountId to match.
-    const route = `/v9/projects/${linked.projectId}${linked.orgId.startsWith('team_') ? `?teamId=${linked.orgId}` : ''}`;
-    let selected;
-    try {
-        const stdout = await runVercel(['api', route, '--method', 'GET', '--raw', '--non-interactive'], signal);
-        if (signal?.aborted)
-            return { status: 'cancelled' };
-        if (Buffer.byteLength(stdout, 'utf8') > OUTPUT_LIMIT)
-            return { status: 'unavailable' };
-        const project = record(JSON.parse(stdout));
-        const link = record(project?.link);
-        if (project?.id !== linked.projectId || project.accountId !== linked.orgId
-            || !link || !['github', 'github-limited'].includes(String(link.type))
-            || typeof link.org !== 'string' || link.org.toLowerCase() !== input.owner.toLowerCase()
-            || typeof link.repo !== 'string' || link.repo.toLowerCase() !== input.repo.toLowerCase()) {
-            return { status: 'project-mismatch' };
-        }
-        const bypasses = record(project.protectionBypass);
-        if (!bypasses || Object.keys(bypasses).length > 128)
-            return { status: 'unavailable' };
-        const candidates = [];
-        for (const [value, metadata] of Object.entries(bypasses)) {
-            const bypass = record(metadata);
-            if (bypass?.scope !== 'automation-bypass')
-                continue;
-            if (!/^[A-Za-z0-9]{32}$/.test(value)
-                || (bypass.isEnvVar !== undefined && typeof bypass.isEnvVar !== 'boolean'))
-                return { status: 'unavailable' };
-            // An omitted isEnvVar is the legacy default. Explicit false keys must never be chosen implicitly.
-            if (bypass.isEnvVar !== false)
-                candidates.push(value);
-        }
-        if (candidates.length > 1)
-            return { status: 'ambiguous' };
-        if (candidates.length === 0)
-            return { status: 'unavailable' };
-        selected = candidates[0];
-        dependencies.rememberSecret(selected);
-    }
-    catch {
-        return { status: signal?.aborted ? 'cancelled' : 'unavailable' };
-    }
-    if (signal?.aborted)
-        return { status: 'cancelled' };
-    try {
-        const status = await dependencies.save(selected);
-        return { status: ['saved', 'save-failed', 'partial-save', 'cancelled'].includes(status) ? status : 'save-failed' };
-    }
-    catch {
-        return { status: signal?.aborted ? 'cancelled' : 'save-failed' };
-    }
-}