@impeccable/reviews 0.1.9 → 0.1.11

package/dist/tools.js

@@ -10,17 +10,18 @@ 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, namedAppQuestion, sentTo, startedIn } from './host-questions.js';
+import { APPS_QUESTION, HOST_QUESTIONS, HOST_SCREENS, HOST_SIGNED_IN, namedAppQuestion, sentTo, startedIn, vercelBypassPaste } 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';
 import { passCloudflareAccess } from './cloudflare-access.js';
 import { commandRunner, connectNetlifySite, liveSite, netlifyStatus, netlifyTeams, readNetlifyPreviews, waitForNetlifyAccess } from './netlify.js';
 import { basicCredentials, PASSWORD_HEADER, passNetlifyLock } from './netlify-password.js';
-import { connectVercelProject, lockedDeploymentHosts, prepareFirstDeployment, projectMadeDeployment, readLinkedProject, readOwnProject, vercelPreviewsFact, vercelProjectFor, vercelProjectPage, vercelStatus, vercelTeams, waitForVercelAccess, waitForVercelLock } from './vercel.js';
+import { connectVercelProject, lockedDeploymentHosts, prepareFirstDeployment, projectMadeDeployment, readLinkedProject, readOwnProject, vercelDashboardScope, vercelPreviewsFact, vercelProjectFor, vercelProjectPage, vercelStatus, vercelTeams, waitForVercelAccess, waitForVercelLock } from './vercel.js';
 import { BYPASS_HEADER, passVercelLogin, readLink } from './vercel-bypass.js';
 import { fitsTask, stagesOf } from './stages.js';
 import { redact } from './log.js';
+import { scan } from './scan.js';
 import { gitEnvironment } from './sandbox.js';
 import { openBrowser } from './login.js';
 import { STATUS_MAX, statusVoiceError, TASK_STATUSES } from './sync.js';
@@ -170,6 +171,11 @@ const REPORT = {
             description: `What waits on the person besides merging the setup pull request and closing the test drive: one line each, at most ${STATUS_MAX} characters, such as "Add the admin test account on the setup page". The terminal counts them. Leave it out when nothing does.`,
             items: { type: 'string', minLength: 1 },
         },
+        apps: {
+            type: 'array',
+            description: 'On a repository with several apps: for each picked app whose preview was not proven or keyed, why, in plain words of at most 200 characters, such as "not checked: the person stopped after the first app". Names only, never an address or a key.',
+            items: { type: 'object', additionalProperties: false, required: ['appKey', 'reason'], properties: { appKey: { type: 'string', minLength: 1 }, reason: { type: 'string', minLength: 1 } } },
+        },
     },
 };
 const WRITE = {
@@ -1687,6 +1693,17 @@ export function createTools(ctx) {
     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 person's Vercel teams as the CLI listed them this run, once: a project's dashboard page is named by its own team, never the CLI's current scope or Vercel's picker, which open whatever project they like. */
+    let vercelTeamList;
+    /** A page of a Vercel project's dashboard, under the team the project's own ids name (the link file's or Vercel's list's); the team this run chose where the CLI cannot list the teams, and Vercel's picker last. */
+    const vercelPageFor = async (vercel, link, page, project) => {
+        let scope;
+        if (link && project) {
+            vercelTeamList ??= vercelTeams(vercel);
+            scope = await vercelDashboardScope(vercel, link, await vercelTeamList);
+        }
+        return vercelProjectPage(page, scope ?? chosenHostTeam(ctx.log, 'vercel'), project);
+    };
     /** 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. */
     const bypassFor = (origin, live) => {
         const store = bypassOrigins.get(origin);
@@ -1713,6 +1730,7 @@ export function createTools(ctx) {
                 // The CLI's current scope is the team; one team is the team; several with none current are the person's pick.
                 team: async () => {
                     const teams = await vercelTeams(cli);
+                    vercelTeamList = Promise.resolve(teams);
                     const one = teams.find((t) => t.current) ?? (teams.length === 1 ? teams[0] : undefined);
                     return one ? { team: one.value, choices: [] } : { choices: teams.map(({ label, value }) => ({ label, value })) };
                 },
@@ -1863,6 +1881,8 @@ export function createTools(ctx) {
         if (appsRepo) {
             const folders = new Map(await Promise.all([...(pickedApps ?? [])].map(async (key) => [await appFolder(pi, key), key])));
             connectedApp = project.rootDirectory !== undefined ? folders.get(project.rootDirectory) : undefined;
+            if (project.name)
+                noteApp(connectedApp, { host_project: project.name });
             if (connectedApp === undefined) {
                 // A project not connected to this repository builds no push of it, so the push goes; one connected already would build it, so it stays held.
                 if (project.repository !== repository.toLowerCase())
@@ -1891,7 +1911,7 @@ export function createTools(ctx) {
         vercelProject = first.project ?? vercelProject;
         // Vercel refused the lock: the person turns it on in the project's settings, in this run, and the read sees it.
         if (first.production === 'none' && !first.locked) {
-            const page = vercelProjectPage('settings/deployment-protection', chosenHostTeam(ctx.log, 'vercel'), vercelProject);
+            const page = await vercelPageFor(vercel, link, 'settings/deployment-protection', vercelProject);
             first = await onHostPage('vercel-lock', () => page, (f) => f.production !== 'exists' && !f.locked, first, () => waitForVercelLock(vercel, link, repository, { wait: ctx.hostWait?.access ?? { totalMs: 300_000, everyMs: 10_000 }, signal }), {
                 waiting: "Waiting for Vercel's login on the project",
                 skipped: 'The person skipped locking the Vercel project.',
@@ -1955,8 +1975,10 @@ export function createTools(ctx) {
         const app = appKey !== undefined ? { appKey } : {};
         if (!(await call(pi, `${base}/preview-auth/protection-header`, { method: 'PUT', body: { value, ...app } })).ok)
             return { stored: false, failed: `The setup API did not store the ${what}.` };
+        noteApp(appKey, { key_placed: true });
         if (!(await call(pi, `${base}/preview-protection`, { method: 'PUT', body: { method: 'header', headerName: header, ...app } })).ok)
             return { stored: true, failed: `The setup API stored the ${what}, but not the setting that sends it: it is turned on under Deployment protection on the setup page.` };
+        noteApp(appKey, { method_saved: true });
         return { stored: true, failed: null };
     };
     /** The instructions the writes are checked against: the first state may have come before the scan proposed the apps, so a later read that shows them brings the apps write in. */
@@ -1973,6 +1995,35 @@ export function createTools(ctx) {
     let pickedApps;
     /** This run confirmed the scan's proposal, so nothing was answered before: the question opens with every app picked. */
     let confirmedApps = false;
+    /** What the run did for each picked app, as its own tool calls found it, sent with the session whenever it changes (#2307). */
+    const appSummaries = new Map();
+    const sendApps = () => ctx.sync.update({ apps: [...appSummaries.values()].slice(0, 50) });
+    const pick = (keys) => {
+        pickedApps = keys;
+        const before = new Map(appSummaries);
+        appSummaries.clear();
+        for (const key of keys)
+            appSummaries.set(key, before.get(key) ?? { app_key: key, host_project: null, preview_proven: false, preview_host: null, key_placed: false, method_saved: false });
+        sendApps();
+    };
+    const noteApp = (key, patch) => {
+        const was = key !== undefined ? appSummaries.get(key) : undefined;
+        if (!was || Object.entries(patch).every(([field, value]) => was[field] === value))
+            return;
+        appSummaries.set(key, { ...was, ...patch });
+        sendApps();
+    };
+    /** The command saw the app's preview open at `url`, whether or not a key for it was saved after: only its hostname is kept. */
+    const sawApp = (key, url, proof) => {
+        if (proof.proven)
+            noteApp(key, { preview_proven: true, preview_host: new URL(url).hostname });
+        return proof;
+    };
+    /** A proof opened the app's preview at `url`, so its method may be saved. */
+    const proveApp = (key, url) => {
+        provenApps.add(key);
+        noteApp(key, { preview_proven: true, preview_host: new URL(url).hostname });
+    };
     /** 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. */
@@ -2103,7 +2154,7 @@ export function createTools(ctx) {
         // 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]);
+            pick(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.
@@ -2112,11 +2163,11 @@ export function createTools(ctx) {
         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 || a === named })) });
         if (answer.skipped) {
-            pickedApps = new Set(apps.filter((a) => a.enabled).map((a) => a.key));
+            pick(new Set(apps.filter((a) => a.enabled).map((a) => a.key)));
             return JSON.stringify({ skipped: true, on: [...pickedApps] });
         }
         const values = (answer.values ?? []).filter((value) => apps.some((a) => a.key === value));
-        pickedApps = new Set(values);
+        pick(new Set(values));
         return JSON.stringify({ values });
     }
     return [
@@ -2253,6 +2304,8 @@ export function createTools(ctx) {
                     savedHost = provenHost;
                 if (saved?.appKey !== undefined)
                     perApp = true;
+                if (saved && 'intendedMethod' in saved && typeof saved.appKey === 'string')
+                    noteApp(saved.appKey, { method_saved: true });
                 if (saved?.appKey !== undefined && typeof saved.intendedMethod === 'string')
                     appMethods.set(String(saved.appKey), saved.intendedMethod);
                 if (saved && 'intendedMethod' in saved)
@@ -2434,12 +2487,26 @@ export function createTools(ctx) {
             const covered = test_pr && recordedBranches?.setup
                 ? await (ctx.driveCoversSetup ?? driveCoversSetup)(pi.cwd, recordedBranches.setup, recordedBranches.drive) : null;
             const drive = covered === false ? undefined : test_pr;
+            // Why an app was not proven or keyed goes with its summary only as plain words, with no address (a scheme, or a host with a path or query) and nothing shaped like a secret; anything else is dropped.
+            const appsBefore = new Map(appSummaries);
+            for (const { appKey, reason } of p.apps ?? []) {
+                const plain = reason.trim();
+                const address = /[a-z][a-z0-9+.-]*:\/\/|[a-z0-9-]+(?:\.[a-z0-9-]+)+[/?#]/i.test(plain);
+                if (plain.length <= 200 && plainText(plain) === plain && !address && !scan('output', plain).length)
+                    noteApp(appKey, { reason: plain });
+            }
             // The web page lists what is left too, within the Worker's 20 lines (REPORT and the check above keep each line non-empty and short).
             ctx.sync.update({ phase: 'completed', status: 'Setup finished', question: null, report_markdown: markdown, test_pr: drive, left: left.slice(0, 20) });
             const res = await ctx.sync.flush();
             if (res && res.status >= 400 && res.status < 500) {
                 // A definite no: the run is still open on the server, so the session goes back to what it was and the agent can send the report again.
                 ctx.sync.update({ phase, status, question, report_markdown, test_pr, left: leftBefore });
+                // Its reasons go with it: the report sent again gives its own.
+                if (appsBefore.size) {
+                    for (const [key, was] of appsBefore)
+                        appSummaries.set(key, was);
+                    sendApps();
+                }
                 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.
@@ -2494,7 +2561,9 @@ export function createTools(ctx) {
             const ofBranch = (d) => (branch !== undefined ? d.vercel : isPreview(d));
             // A head's build is still building until it has a final status.
             const final = (evidence) => Boolean(evidence.error) || evidence.deployments.some((d) => ofBranch(d) && (d.state === 'success' || d.state === 'failure' || d.state === 'error'));
-            const evidence = branch !== undefined ? await awaitBuild('Vercel', `Waiting for Vercel to build ${testDriveBranch(branch) ? "the test drive's preview" : `the preview of ${branch}`}`, read, final, () => vercelProjectPage('settings/git', chosenHostTeam(ctx.log, 'vercel'), app?.name ?? vercelProject), signal) : await read();
+            // The project's Git settings, for the screen a build that never comes opens: the app's project's own page, else the linked project's.
+            const gitPage = branch !== undefined ? await vercelPageFor(vercel, app ? app.link : await readLink(pi.cwd), 'settings/git', app?.name ?? vercelProject) : '';
+            const evidence = branch !== undefined ? await awaitBuild('Vercel', `Waiting for Vercel to build ${testDriveBranch(branch) ? "the test drive's preview" : `the preview of ${branch}`}`, read, final, () => gitPage, signal) : await read();
             /** The project the evidence is of: the app's, else the one this folder is linked to. */
             const link = async () => (app ? app.link : readLink(pi.cwd));
             /** The hosts of the linked project's deployments while it is locked at every address, read from Vercel once a Production deployment turns up, and once per call. */
@@ -2546,6 +2615,8 @@ export function createTools(ctx) {
                     vercelProductions.set(new URL(production).origin, linked.projectId);
                 noteProduction(production, 'vercel', undefined, appKey);
             }
+            if (app?.name)
+                noteApp(appKey, { host_project: app.name });
             return JSON.stringify({ ...(appKey !== undefined ? { appKey, project: app.name } : {}), ...evidence, ...(production ? { production } : {}) });
         }),
         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) => {
@@ -2581,6 +2652,9 @@ export function createTools(ctx) {
             if (evidence.pullRequestPreviews)
                 previewFacts.set('netlify', evidence.pullRequestPreviews);
             noteProduction(evidence.production, 'netlify', liveSite(evidence), appKey);
+            const site = evidence.unmatched ? undefined : liveSite(evidence);
+            if (site)
+                noteApp(appKey, { host_project: site });
             return JSON.stringify(appKey !== undefined ? { appKey, ...evidence } : evidence);
         }),
         tool('impeccable_cloudflare_previews', 'Cloudflare Pages previews', "Read whether this repository's pull requests get Cloudflare Pages previews: the 10 newest, each with its address, the branch's alias (https://<branch>.<project>.pages.dev, which follows the branch's latest build), its state and where that was read: the check run or the pull request comment Cloudflare's GitHub app posts, or cf, Cloudflare's CLI, on this machine when it is signed in (read only: it never signs in). production is the project's own address, https://<project>.pages.dev, the live app, for the before. cli says whether cf is missing, signed out, signed in or did not answer. An error says something could not be read, which is unknown rather than absent, and unread says whose: GitHub or cf. pullRequestPreviews says whether the Pages project built from this repository builds previews of pull requests at all (enabled false, with the cause: source, deployments or previews); worker says Cloudflare builds a Worker from the repository (Workers Builds), which gives pull requests no preview; githubApp says what gh reads of Cloudflare's GitHub app on the owner, and the page where it gets access. With pull (a pull request of this run) or branch (a branch of this run, pushed, before its pull request exists), only that one's, waiting up to five minutes for its build to finish, under a status line with its timer, and again on the person's yes when the time ran out; where the project's settings build every branch and no build came, the wait's screen opens the GitHub page where Cloudflare's app gets access to the repository instead, and waits again. It changes nothing on Cloudflare and proves nothing about the page.", CLOUDFLARE_PREVIEWS, async (p, pi, signal) => {
@@ -2616,8 +2690,10 @@ export function createTools(ctx) {
             const evidence = subject ? { ...waited, ...(app ? { githubApp: app } : {}) } : waited;
             if (!subject)
                 cloudflareEvidence = evidence;
-            if (!subject && appKey !== undefined && !evidence.unmatched && evidence.project)
+            if (!subject && appKey !== undefined && !evidence.unmatched && evidence.project) {
                 cloudflareApps.set(appKey, { project: evidence.project, label: (evidence.production && pagesProject(evidence.production)) || evidence.project });
+                noteApp(appKey, { host_project: evidence.project });
+            }
             for (const origin of cloudflareListed)
                 listedApps.delete(origin);
             cloudflareListed.clear();
@@ -2670,7 +2746,7 @@ export function createTools(ctx) {
             if (proof.proven)
                 provenHost = previewHostName(url) ?? provenHost;
             if (proof.proven && app)
-                provenApps.add(app.appKey);
+                proveApp(app.appKey, url);
             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.
@@ -2852,7 +2928,7 @@ export function createTools(ctx) {
                 hostedPreviewProven = true;
                 provenHost = 'Vercel';
                 if (at.app)
-                    provenApps.add(at.app.appKey);
+                    proveApp(at.app.appKey, at.url);
             };
             // A secret in hand already for the same store and project: another address of the project opens with it.
             const held = bypassHeld.get(store);
@@ -2868,13 +2944,15 @@ export function createTools(ctx) {
                 // A project the folder is not linked to is named on the CLI's reads and makes; the reads are held to its id all the same.
                 ...(at.app?.name ? { project: at.app.name } : {}),
                 consent: async () => !(await ask(sentTo(HOST_SCREENS['vercel-bypass'], at.url))).skipped,
-                paste: async () => {
-                    // The project's own settings page, in its team where the run knows it; else Vercel's picker.
-                    (ctx.openBrowser ?? openBrowser)(vercelProjectPage('settings/deployment-protection', chosenHostTeam(ctx.log, 'vercel'), project.name));
-                    const answer = await ask(sentTo(HOST_SCREENS['vercel-bypass-key'], at.url));
+                paste: async (stopped) => {
+                    // This project's own settings page, under its own team (the one its ids name, as the CLI lists the person's teams): never another project of the account's.
+                    (ctx.openBrowser ?? openBrowser)(await vercelPageFor(vercel, link, 'settings/deployment-protection', project.name));
+                    const answer = await ask(sentTo(vercelBypassPaste(stopped), at.url));
                     return answer.skipped ? undefined : answer.value?.trim();
                 },
-                prove: (secret) => provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, bypass: secret }),
+                ...(ctx.hostWait?.bypass ? { wait: ctx.hostWait.bypass } : {}),
+                ...(signal ? { signal } : {}),
+                prove: async (secret) => sawApp(at.app?.appKey, at.url, await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, bypass: secret })),
                 save: async (secret) => {
                     const saved = await saveLock(pi, 'secret', BYPASS_HEADER, secret, at.app?.appKey);
                     stored = saved.stored;
@@ -2911,7 +2989,7 @@ export function createTools(ctx) {
             /** 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) => {
-                const proof = await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, password, form });
+                const proof = sawApp(at.app?.appKey, at.url, await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, password, form }));
                 if (proof.proven && proof.pattern)
                     pattern = proof.pattern;
                 return proof;
@@ -2922,7 +3000,7 @@ export function createTools(ctx) {
                 if ((await prove(undefined)).proven) {
                     provenPattern = pattern ?? provenPattern;
                     if (at.app)
-                        provenApps.add(at.app.appKey);
+                        proveApp(at.app.appKey, at.url);
                     return JSON.stringify(stands);
                 }
                 passwordStands.delete(site);
@@ -2933,7 +3011,7 @@ export function createTools(ctx) {
             if (passwordSaved && sitePassword && passwordSites.has(site) && (await prove(sitePassword)).proven) {
                 provenPattern = pattern ?? provenPattern;
                 if (at.app)
-                    provenApps.add(at.app.appKey);
+                    proveApp(at.app.appKey, at.url);
                 return JSON.stringify(passwordSaved);
             }
             /** The store took this attempt's password: what was in hand no longer matches it, unless the setting followed. */
@@ -2981,7 +3059,7 @@ export function createTools(ctx) {
                 hostedPreviewProven = true;
                 provenHost = 'Netlify';
                 if (at.app)
-                    provenApps.add(at.app.appKey);
+                    proveApp(at.app.appKey, at.url);
                 provenPattern = pattern ?? provenPattern;
             }
             if (value) {
@@ -2992,7 +3070,7 @@ export function createTools(ctx) {
                 hostedPreviewProven = true;
                 provenHost = 'Netlify';
                 if (at.app)
-                    provenApps.add(at.app.appKey);
+                    proveApp(at.app.appKey, at.url);
                 provenPattern = pattern ?? provenPattern;
                 passwordSaved = passwordOutcome;
             }
@@ -3014,12 +3092,13 @@ export function createTools(ctx) {
             if (accessOutcome?.status === 'skipped')
                 return JSON.stringify(accessOutcome);
             let proof;
-            const prove = async (token) => (proof = await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, access: token }));
+            const prove = async (token) => (proof = sawApp(at.app?.appKey, at.url, await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, access: token })));
             const base = `${ctx.setupApi}/repos/${encodeURIComponent(ctx.repo)}`;
             const save = async (token) => {
                 const app = at.app ? { appKey: at.app.appKey } : {};
                 if (!(await call(pi, `${base}/preview-auth/access`, { method: 'PUT', body: { clientId: token.id, clientSecret: token.secret, ...app } })).ok)
                     return 'The setup API did not store the service token.';
+                noteApp(at.app?.appKey, { key_placed: true });
                 // An app that signs in with Access sends this token already: the setting would make it a second credential, which the setup API refuses.
                 const repos = object((await call(pi, `${ctx.setupApi}/state`)).data)?.repos;
                 const lock = Array.isArray(repos) ? object(object(repos.map(object).find((r) => r?.name === ctx.repo)?.items)?.['preview-protection']) : undefined;
@@ -3027,6 +3106,7 @@ export function createTools(ctx) {
                     return null;
                 if (!(await call(pi, `${base}/preview-protection`, { method: 'PUT', body: { method: 'access', ...app } })).ok)
                     return 'The setup API stored the service token, but not the setting that sends it: it is turned on under Preview protection on the setup page.';
+                noteApp(at.app?.appKey, { method_saved: true });
                 return null;
             };
             let answer;
@@ -3077,7 +3157,7 @@ export function createTools(ctx) {
                 hostedPreviewProven = true;
                 provenHost = 'Cloudflare Pages';
                 if (at.app)
-                    provenApps.add(at.app.appKey);
+                    proveApp(at.app.appKey, at.url);
                 if (pattern)
                     provenPattern = pattern;
             }

package/dist/ui/look.js

@@ -63,7 +63,7 @@ function block(lines, width, size = Math.max(0, ...lines.map((line) => visibleWi
     const left = ' '.repeat(Math.max(0, Math.floor((width - Math.min(size, width)) / 2)));
     return lines.map((line) => left + truncateToWidth(line, width - left.length, '…'));
 }
-/** Plain text wrapped to at most `max` columns: a sentence a line when each fits, else lines as even as the words allow. */
+/** A paragraph of plain text wrapped to at most `max` columns: a sentence a line when each fits, else lines as even as the words allow. */
 function balanced(text, max) {
     const sentences = text.split(/(?<=[.!?])\s+/);
     if (sentences.length > 1 && sentences.every((line) => visibleWidth(line) <= max))
@@ -76,8 +76,8 @@ function balanced(text, max) {
     }
     return lines;
 }
-/** Supporting text: wrapped, soft, each line centered. */
-const said = (text, inner, st) => balanced(text, Math.min(TEXT_WIDTH, inner)).map((line) => center(st.soft(line), inner));
+/** Supporting text: wrapped, soft, each line centered; a blank line in it parts paragraphs, each wrapped on its own and an empty row between. */
+const said = (text, inner, st) => text.split('\n\n').flatMap((part, i) => [...(i ? [''] : []), ...balanced(part, Math.min(TEXT_WIDTH, inner)).map((line) => center(st.soft(line), inner))]);
 /** Wrapped text whose first line starts with `first` and the rest line up under it. */
 const hang = (text, width, first) => wrapTextWithAnsi(text, Math.max(10, width - first.length)).map((line, i) => (i ? ' '.repeat(first.length) : first) + line);
 /** An address cut into rows no wider than `width`, after a slash where one falls in the row's last two thirds, each linking to the whole of it, so any row opens it. */

package/dist/vercel-bypass.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { redactShapes } from './scan.js';
 /**
  * Getting past Vercel's Deployment Protection the way Vercel documents it for tools: Protection Bypass for Automation, a
  * secret of the project that a request sends in the x-vercel-protection-bypass header (every plan has it; a team member
@@ -67,24 +69,71 @@ function pick(secrets, before) {
     const newest = (list) => [...list].sort((a, b) => b.createdAt - a.createdAt)[0];
     return newest(secrets.filter((s) => s.note === SECRET_NOTE)) ?? (before && newest(secrets.filter((s) => !before.has(s.value))));
 }
-/** Makes the secret with the label through `vercel api`; a CLI without `api` (or one Vercel refuses) falls back to its own command, which the same role check stops. */
+/**
+ * What a failed CLI run printed, as one line for a reason the screen and the model read: Vercel's own error message
+ * where the output is its JSON, else the first line that says "Error"; nothing shaped like a secret, which a CLI can
+ * echo back from its arguments, since the reason goes to the model and the transcript.
+ */
+export function cliSaid(err) {
+    const printed = `${String(err.stdout ?? '')}\n${String(err.stderr ?? '')}`;
+    const json = printed.slice(printed.indexOf('{'), printed.lastIndexOf('}') + 1);
+    let said = '';
+    try {
+        const error = record(record(JSON.parse(json))?.error);
+        if (typeof error?.message === 'string' && error.message)
+            said = error.message.trim();
+    }
+    catch {
+        // Not JSON: the lines below.
+    }
+    if (!said) {
+        const line = printed.split('\n').map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').trim()).find((l) => /error/i.test(l));
+        said = (line ?? '').replace(/^error[:!]?\s*/i, '');
+    }
+    return redactShapes(said).slice(0, 200);
+}
+/** Vercel's answer to a role that may not make the secret: 403, or its words for it. */
+const REFUSED = /forbidden|not authorized|not_authorized|permission|\b403\b/i;
+/**
+ * Makes the secret with the label through `vercel api`; a CLI without `api` (or one Vercel refuses) falls back to its own
+ * command, which the same role check stops. Once made, which kind the project now holds (labelled through `api`, or the
+ * CLI's own without a label); else why not, in Vercel's words where it gave any, the role named only where Vercel refused.
+ */
 async function make(run, link, name) {
+    const said = [];
     if (link) {
         try {
             await run(makeApi(link));
-            return true;
+            return { made: 'labelled' };
         }
-        catch {
+        catch (err) {
             // The CLI's own command below fails the same way when the role is missing, and works when `api` is the one missing.
+            said.push(cliSaid(err));
         }
     }
     try {
         await run(makeArgs(name));
-        return true;
+        return { made: 'unlabelled' };
     }
-    catch {
-        return false;
+    catch (err) {
+        said.push(cliSaid(err));
     }
+    const words = said.filter(Boolean).at(-1);
+    const detail = words ? ` (Vercel said: ${words})` : '';
+    return {
+        reason: REFUSED.test(said.join('\n'))
+            ? `Vercel refused to make a bypass secret on the project for the Vercel CLI here${detail}: that takes the Member role, or Project Administrator.`
+            : `The Vercel CLI here could not make a bypass secret on the project${detail}.`,
+    };
+}
+/** The proof again, while Vercel's login still stands in front of the address, until the edge takes a secret made moments ago or the wait runs out; any other answer stands at once. */
+async function admitted(secret, deps) {
+    const wait = deps.wait ?? { totalMs: 30_000, everyMs: 3_000 };
+    let proof = await deps.prove(secret);
+    for (const end = Date.now() + wait.totalMs; !proof.proven && proof.gate === 'vercel-protection' && Date.now() < end && !deps.signal?.aborted; proof = await deps.prove(secret)) {
+        await sleep(wait.everyMs, undefined, { signal: deps.signal });
+    }
+    return proof;
 }
 /**
  * Gets a bypass secret in place for the address Vercel's login stands in front of, and saves only one that opens it. The
@@ -96,46 +145,62 @@ export async function passVercelLogin(deps) {
     const link = await deps.link();
     const project = await readProject(deps.run, link, deps.project);
     const from = project?.name ? { project: project.name } : {};
+    const wait = deps.wait ?? { totalMs: 30_000, everyMs: 3_000 };
     const finish = async (secret, how) => {
         deps.remember(secret);
-        const proof = await deps.prove(secret);
+        // A secret made moments ago may take the edge a few seconds: its proof is tried again while the login stands.
+        const proof = how === 'created' ? await admitted(secret, { ...deps, wait }) : await deps.prove(secret);
         if (!proof.proven)
             return { reason: proof.reason ?? 'The address did not open with the secret.' };
         const failed = await deps.save(secret);
         return failed ? { status: 'save-failed', reason: failed, ...from } : { status: 'saved', secret: how, ...from, value: secret };
     };
-    /** Why the CLI's way ended without a secret that opens the preview, for the paste screen's skip. */
+    /** Why the CLI's way ended without a secret that opens the preview, for the paste screen and its skip. */
     let stopped;
+    /** What the project holds for the person to copy rather than make another: a secret labelled for Impeccable (its own, or one this run made), or one the CLI's own command made without a label. */
+    let held = 'none';
     if (!project)
         stopped = 'The Vercel CLI could not read the project: it is signed out, this folder is not linked to the project, or the role does not allow it.';
     else {
         const own = pick(project.secrets);
         if (own) {
+            held = 'labelled';
             const done = await finish(own.value, 'existing');
             if ('status' in done)
                 return done;
-            stopped = done.reason;
+            stopped = `The project's secret labelled "${SECRET_NOTE}" did not open the preview: ${done.reason}`;
         }
         else {
             if (!(await deps.consent()))
                 return { status: 'skipped', reason: 'The person skipped creating a bypass secret.', ...from };
             const before = new Set(project.secrets.map((s) => s.value));
-            if (!(await make(deps.run, link, deps.project)))
-                stopped = 'The Vercel CLI could not make a bypass secret on the project: that takes the Member role or Project Administrator.';
+            const made = await make(deps.run, link, deps.project);
+            if ('reason' in made)
+                stopped = made.reason;
             else {
-                const ours = pick((await readProject(deps.run, link, deps.project))?.secrets ?? [], before);
+                // The project holds the secret from here on, whatever the reads below say: the screen says to copy it, never to make another.
+                held = made.made;
+                // Read back by its label, again for a few seconds while the settings do not list it yet.
+                let ours;
+                for (const end = Date.now() + wait.totalMs;;) {
+                    ours = pick((await readProject(deps.run, link, deps.project))?.secrets ?? [], before);
+                    if (ours || Date.now() >= end || deps.signal?.aborted)
+                        break;
+                    await sleep(wait.everyMs, undefined, { signal: deps.signal });
+                }
                 if (!ours)
-                    stopped = 'The secret the Vercel CLI made could not be read back.';
+                    stopped = `The Vercel CLI made a bypass secret${held === 'labelled' ? ` labelled "${SECRET_NOTE}"` : ' (without a label)'}, but could not read it back from the project's settings within ${Math.round(wait.totalMs / 1000)} s.`;
                 else {
+                    held = ours.note === SECRET_NOTE ? 'labelled' : 'unlabelled';
                     const done = await finish(ours.value, 'created');
                     if ('status' in done)
                         return done;
-                    stopped = done.reason;
+                    stopped = `The Vercel CLI made a bypass secret${held === 'labelled' ? ` labelled "${SECRET_NOTE}"` : ' (without a label)'}, but the preview did not open with it within ${Math.round(wait.totalMs / 1000)} s: ${done.reason}`;
                 }
             }
         }
     }
-    const typed = await deps.paste();
+    const typed = await deps.paste({ reason: stopped, held });
     if (typed === undefined)
         return { status: 'skipped', reason: stopped, ...from };
     if (!isBypassSecret(typed))

package/dist/vercel.js

@@ -17,20 +17,31 @@ export async function vercelStatus(vercel) {
     }
 }
 /**
- * `vercel teams ls --json`: the teams the person is a member of, each by its slug (what `--team` takes) and name, and
- * which one is the CLI's current scope. The JSON is on stdout; the table the CLI prints otherwise goes to stderr.
+ * `vercel teams ls --json`: the teams the person is a member of, each by its slug (what `--team` takes), its name and
+ * its id, and which one is the CLI's current scope. The JSON is on stdout; the table the CLI prints otherwise goes to
+ * stderr.
  */
 export async function vercelTeams(vercel) {
     try {
         const listed = JSON.parse(await vercel(['teams', 'ls', '--json'])).teams;
         return (Array.isArray(listed) ? listed : []).flatMap((team) => typeof team.slug === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(team.slug)
-            ? [{ value: team.slug, label: typeof team.name === 'string' && team.name ? team.name.slice(0, 100) : team.slug, current: team.current === true }]
+            ? [{ value: team.slug, label: typeof team.name === 'string' && team.name ? team.name.slice(0, 100) : team.slug, current: team.current === true, ...(typeof team.id === 'string' && /^team_[A-Za-z0-9]+$/.test(team.id) ? { id: team.id } : {}) }]
             : []);
     }
     catch {
         return [];
     }
 }
+/**
+ * The scope a project's dashboard pages sit under, `https://vercel.com/<scope>/<project>/…`, for the project `link`
+ * names: its team's slug, as the CLI lists the person's teams, or for a project of the personal scope the username the
+ * CLI is signed in as. Undefined when the CLI cannot say, where the caller falls back to Vercel's picker.
+ */
+export async function vercelDashboardScope(vercel, link, teams) {
+    if (link.orgId.startsWith('team_'))
+        return (teams ?? (await vercelTeams(vercel))).find((team) => team.id === link.orgId)?.value;
+    return (await vercelStatus(vercel)).user;
+}
 /** Where Vercel's GitHub app is installed or given more repositories. */
 export const VERCEL_APP_PAGE = 'https://github.com/apps/vercel/installations/new';
 /**

package/package.json

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