@impeccable/reviews 0.1.6 → 0.1.8

package/dist/login.js

@@ -1,8 +1,10 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
+import { win32 } from 'node:path';
 import { requestJson } from './http.js';
 import { UserError } from './log.js';
+import { LOOPBACK } from './preflight.js';
 import { askPerson } from './ui/bridge.js';
 /** The callback ports, in the order the contract lists them; the Worker accepts no other. */
 export const CALLBACK_PORTS = [8239, 8238, 8240, 8237, 8236, 8235];
@@ -40,7 +42,8 @@ function page(res, status, message, more = '') {
 /**
  * The page the tab shows once the code has come: it asks the command every
  * half second where to go next, and goes there (the progress page), or says
- * what went wrong; without scripts, a link does the asking.
+ * what went wrong; without scripts, a link does the asking. It hears the
+ * answer once.
  */
 function waitingPage(res, state) {
     const script = `<script>(function(){var said=document.getElementById('said'),next='/next?state='+encodeURIComponent(new URLSearchParams(location.search).get('state')||'');function ask(){fetch(next,{cache:'no-store'}).then(function(r){return r.json()}).then(function(a){if(a.page&&/^https?:/.test(a.page))location.replace(a.page);else if(a.error)said.textContent=a.error;else setTimeout(ask,500)},function(){said.textContent='Back to your terminal.'})}ask()})()</script>`;
@@ -53,8 +56,11 @@ function waitingPage(res, state) {
  * the callback. A wrong state gets a 400 and the wait goes on; the right one
  * hands over the code and answers at once with a page that asks `/next` where
  * to go, which says "not yet" until `land` knows (a JSON `wait`), then the
- * page or what went wrong. `/go` is the same for a tab without scripts: a
- * redirect, or the waiting page again.
+ * page or what went wrong, once. `/go` is the same for a tab without scripts:
+ * a redirect, or the waiting page again. Only the first callback with the
+ * right state counts: a later one gets a 400 and changes nothing, unless it
+ * is the same tab reloading, which waits again. `/next` and `/go` answer only
+ * once that callback has brought a code, since the state is all they check.
  */
 export async function startCallbackServer(state, ports = CALLBACK_PORTS) {
     let resolve;
@@ -65,7 +71,11 @@ export async function startCallbackServer(state, ports = CALLBACK_PORTS) {
     });
     /** A tab brought the code, and waits to hear where to go. */
     let visited = false;
+    /** What the one callback that counts brought: its code, or '' when it said the sign-in did not finish. */
+    let brought;
     let landing;
+    /** The tab has heard where to go, so nothing more is said. */
+    let said = false;
     let heard = () => { };
     const told = new Promise((r) => (heard = r)).finally(() => untold.delete(told));
     const answer = (req, res) => {
@@ -75,9 +85,15 @@ export async function startCallbackServer(state, ports = CALLBACK_PORTS) {
             return void res.writeHead(404, { connection: 'close' }).end();
         if (url.searchParams.get('state') !== state)
             return page(res, 400, 'This sign-in is not the one your terminal started. Run impeccable-reviews again.');
-        // Heard once the answer that says where to go has left for the tab.
-        if (route !== '/callback' && landing)
-            res.once('finish', heard);
+        if (route !== '/callback') {
+            if (!visited || said)
+                return page(res, 400, 'Back to your terminal.');
+            // Heard once the answer that says where to go has left for the tab.
+            if (landing) {
+                said = true;
+                res.once('finish', heard);
+            }
+        }
         if (route === '/next')
             return void res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store', connection: 'close' }).end(JSON.stringify(landing ?? { wait: true }));
         if (route === '/go') {
@@ -87,12 +103,14 @@ export async function startCallbackServer(state, ports = CALLBACK_PORTS) {
         }
         const got = url.searchParams.get('code');
         const error = url.searchParams.get('error');
+        if (brought !== undefined)
+            return got && !error && got === brought && !said ? waitingPage(res, state) : page(res, 400, 'This sign-in already had its answer. Back to your terminal.');
+        brought = !got || error ? '' : got;
         if (!got || error) {
             page(res, 400, 'Sign-in did not finish. Back to your terminal.');
             return reject(new UserError(`Sign-in did not finish${error ? ` (${error})` : ''}. Run impeccable-reviews again.`));
         }
-        if (!visited)
-            untold.add(told);
+        untold.add(told);
         visited = true;
         resolve(got);
         waitingPage(res, state);
@@ -178,15 +196,29 @@ export function parsePasted(text, state) {
     }
     return /^[A-Za-z0-9._~-]{8,}$/.test(trimmed) ? trimmed : null;
 }
+/**
+ * The platform's command that opens `url` in the default browser, with no shell between. Null for anything but an https
+ * address, or plain http to this machine (localhost, 127.0.0.1, [::1] or a .localhost name), free of quotes, spaces,
+ * control characters and what a shell would read (^ | < >): Windows' opener runs a local file or any other protocol it is
+ * handed, and the address may come from the model or the setup API.
+ */
+export function browserCommand(url, platform = process.platform) {
+    const parsed = URL.canParse(url) ? new URL(url) : null;
+    const web = parsed?.protocol === 'https:' || (parsed?.protocol === 'http:' && (LOOPBACK.has(parsed.hostname) || /^(?:[a-z0-9-]+\.)+localhost$/.test(parsed.hostname)));
+    if (!web || /["^|<>\s\x00-\x1f\x7f]/.test(url))
+        return null;
+    // rundll32 by its full path: the run's folder is the checkout, which Windows would otherwise look in first.
+    return platform === 'darwin' ? ['open', [url]]
+        : platform === 'win32' ? [win32.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'rundll32.exe'), ['url.dll,FileProtocolHandler', url]]
+            : ['xdg-open', [url]];
+}
 /** Opens the address in the default browser; a failure is fine because the address is printed too. BROWSER=none skips it. */
 export function openBrowser(url) {
-    if (process.env.BROWSER === 'none')
+    const opener = browserCommand(url);
+    if (process.env.BROWSER === 'none' || !opener)
         return;
-    const [command, args, verbatim] = process.platform === 'darwin' ? ['open', [url], false]
-        : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', `"${url}"`], true]
-            : ['xdg-open', [url], false];
     try {
-        const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsVerbatimArguments: verbatim });
+        const child = spawn(opener[0], opener[1], { stdio: 'ignore', detached: true });
         child.on('error', () => { });
         child.unref();
     }

package/dist/main.js

@@ -4,19 +4,19 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import { runAgent } from './agent.js';
-import { fenceExtension, hostsAgreed, placeOf } from './fence.js';
+import { fenceExtension, guardedFileOperations, hostsAgreed, placeOf } from './fence.js';
 import { focusInstructions, focusState, severalApps } from './focus.js';
 import { requestJson } from './http.js';
 import { copyText, letTabsHear, openBrowser, progressPage, screenPrompt, setupAuth, signIn } from './login.js';
 import { createLog, UserError } from './log.js';
 import { firstMessage, playbook, setupContext } from './playbook.js';
-import { checkoutFrontEnd, parseFlags, readCheckout, stateSaysNoFrontEnd, USAGE } from './preflight.js';
+import { checkoutFrontEnd, parseFlags, readCheckout, skipWorkingFolderForCommands, stateSaysNoFrontEnd, USAGE } from './preflight.js';
 import { startSandbox } from './sandbox.js';
 import { scanRecorder } from './scan.js';
 import { createReporter, reportingOff } from './report.js';
-import { createSessionSync, syncExtension } from './sync.js';
+import { createSessionSync, pageStatus, plainReport, syncExtension } from './sync.js';
 import { checkPushAccess, readPushAccess } from './push-access.js';
-import { createTools, resultLine } from './tools.js';
+import { 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';
@@ -62,6 +62,7 @@ async function nothingToSetUp(sync, reporter, why, title, result, links) {
     process.exit(2);
 }
 export async function main(argv) {
+    skipWorkingFolderForCommands();
     let log = createLog(false);
     let sync;
     // Nothing is reported until the flags say where to and whether to.
@@ -110,8 +111,9 @@ export async function main(argv) {
             log,
             place: placeOf,
             hosts: () => hostsAgreed(log),
+            noSandbox: flags.noSandbox,
         });
-        if (!(await showIntro(slug, sandbox.warning))) {
+        if (!(await showIntro(slug, [sandbox.warning, sandbox.noPreview].filter(Boolean).join(' ') || undefined))) {
             reporter.step({ event: 'setup_command_sign_in_ended', outcome: 'cancelled' });
             return void (await reporter.done());
         }
@@ -173,7 +175,7 @@ export async function main(argv) {
         sync = liveSync;
         log.write('run started', { run_id: run.run_id, cap_usd: run.cap_usd, expires_at: run.expires_at });
         // Impeccable reviews web front ends: a checkout without one stops here, before the state is read or anything runs.
-        const frontEnd = checkoutFrontEnd(checkout.root);
+        const frontEnd = checkoutFrontEnd(checkout.root, log);
         log.write('front end', frontEnd);
         const webPage = { label: 'Web page', url: page };
         if (frontEnd === 'none')
@@ -191,6 +193,11 @@ export async function main(argv) {
             const setupPage = state.data.account?.setupPage;
             await nothingToSetUp(liveSync, reporter, 'skipped_repo', 'Repository skipped', SKIPPED, [...(typeof setupPage === 'string' && onHost(setupPage) ? [{ label: 'Setup page', url: setupPage }] : []), webPage]);
         }
+        // --app names one app of a repository with several: a key that is none of them stops here, with the keys there are, rather than asking about apps it did not mean.
+        const appKeys = (state.data?.repos ?? []).find((r) => r?.name === token.repository.name)?.apps?.flatMap((a) => (typeof a?.key === 'string' ? [a.key] : [])) ?? [];
+        if (flags.app && severalApps(state.data) && !appKeys.includes(flags.app)) {
+            throw new UserError(`--app ${flags.app} is not an app of ${slug}. Its apps are ${appKeys.join(', ')}. Run it again with one of them, or without --app.`);
+        }
         // The setup pushes as the person, so whether git may push is asked of GitHub now, before anything is created.
         const push = await checkPushAccess(slug, () => readPushAccess(checkout.root), async (screen) => {
             liveSync.update({ phase: 'waiting', question: { id: screen.id, prompt: screen.prompt } });
@@ -212,10 +219,22 @@ export async function main(argv) {
         let report;
         let fatal;
         let cancelled = false;
+        /** The setup pull request the end screens open and copy, rebuilt from this checkout's owner and repo and its number; one that is not that is left out. */
+        const shownSetupPr = (pr) => {
+            const own = ownPullRequest(pr, checkout.owner, checkout.repo);
+            if (pr && !own)
+                log.write('setup pull request left out', { number: pr.number });
+            return own;
+        };
         const finish = async () => {
+            // What a command left in the git folders goes before the summary, where the person reads it.
+            const removed = sandbox.finish();
+            if (removed.length)
+                log.write('git settings removed', removed);
             if (report) {
                 const saved = await settle(liveSync.flush(), 5000);
-                const { testPr, setupPr } = report;
+                const { testPr } = report;
+                const setupPr = shownSetupPr(report.setupPr);
                 // 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)
@@ -223,7 +242,7 @@ export async function main(argv) {
                 await showOutro({
                     outcome: testPr ? 'done' : 'partial',
                     title: testPr ? "You're all set up" : 'Settings saved',
-                    result: resultLine(report),
+                    result: resultLine({ ...report, setupPr }),
                     link: (setupPr ?? testPr)?.url,
                     links: [
                         ...(testPr ? [{ label: 'Test drive, watch the review there', url: testPr.url }] : []),
@@ -232,32 +251,32 @@ export async function main(argv) {
                         { label: 'Web page', url: page },
                     ],
                     todo: report.left,
-                    warnings: saved && !saved.ok ? [`The web page missed the last update (${saved.error}), so it may lag behind this.`] : [],
+                    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.
                 if (!saved?.ok)
-                    say(`\n${report.markdown.trim()}`);
+                    say(`\n${plainReport(report.markdown)}`);
                 if (!saved?.ok)
                     reporter.step({ event: 'setup_command_stopped', outcome: 'update_lost' });
                 await reporter.done();
                 process.exit(0);
             }
             const waiting = liveSync.payload.phase === 'waiting' ? liveSync.payload.question?.prompt : undefined;
-            const why = fatal ? `Impeccable stopped: ${fatal}` : waiting ? `Impeccable stopped while waiting for an answer: ${waiting}` : 'Impeccable stopped before the setup finished.';
+            const why = pageStatus(fatal ? `Impeccable stopped: ${fatal}` : waiting ? `Impeccable stopped while waiting for an answer: ${waiting}` : 'Impeccable stopped before the setup finished.');
             const stopped = fatal ? 'model_error' : waiting ? 'unanswered' : cancelled ? 'stopped' : 'failed';
             liveSync.update({ phase: 'error', status: why, question: null, stop_reason: stopped });
             const saved = await settle(liveSync.flush(), 5000);
             if (!saved?.ok)
                 reporter.step({ event: 'setup_command_stopped', outcome: 'update_lost' });
             const missed = saved?.ok ? [] : [`The web page missed this (${saved?.error ?? 'no answer'}), so it may still show the run as going.`];
-            const { test_pr: drive, setup_pr: setup } = liveSync.payload;
+            const drive = liveSync.payload.test_pr, setup = shownSetupPr(liveSync.payload.setup_pr);
             await showOutro({
                 outcome: 'stopped',
                 title: cancelled && !fatal ? 'Setup cancelled' : 'Setup failed',
                 result: why,
                 links: [...(drive ? [{ label: 'Test drive', url: drive.url }] : []), ...(setup ? [{ label: 'Setup pull request', url: setup.url }] : []), { label: 'Web page', url: page }],
                 todo: ['Run impeccable-reviews again to carry on. What was saved stays saved; the web page has the details.'],
-                warnings: missed,
+                warnings: [...removed, ...missed],
             });
             await reporter.done();
             process.exit(1);
@@ -286,12 +305,16 @@ export async function main(argv) {
                 previewWait: previewWait(),
                 sandbox,
                 pushAccess: push.outcome,
+                severalApps: severalApps(state.data),
+                ...(flags.app ? { app: flags.app } : {}),
+                start: checkout.start,
             }),
             extensions: [
                 fenceExtension(checkout.root, log, checkout.protectedBranches, scratch, scans),
-                syncExtension(liveSync, { onFatal: (message) => void (fatal = message), onQuit: finish }),
+                syncExtension(liveSync, { onFatal: (message) => void (fatal = message), onQuit: finish }, scans),
             ],
             bash: sandbox.shell,
+            files: guardedFileOperations(checkout.root, scratch),
             interactive,
             runId: run.run_id,
             transcript: flags.transcript,

package/dist/netlify-password.js

@@ -29,7 +29,7 @@ const NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const ID = /^[A-Za-z0-9-]{1,64}$/;
 /** A password as the header can carry it: one line, of a length a person would type. */
 const password = (value) => (typeof value === 'string' && value.length > 0 && value.length <= 200 && !/[\r\n\0]/.test(value) ? value : null);
-/** The site's protection, read through the CLI; null when it could not say: signed out, or no site of that name in a team of the person's. */
+/** The site's protection, read through the CLI, which is what makes the site the person's; null when it could not say: signed out, no site of that name in a team of the person's, or a site read back under another name. */
 export async function readSite(run, site) {
     let read;
     try {
@@ -38,7 +38,7 @@ export async function readSite(run, site) {
     catch {
         return null;
     }
-    if (typeof read?.id !== 'string' || !ID.test(read.id) || typeof read.name !== 'string' || !NAME.test(read.name))
+    if (typeof read?.id !== 'string' || !ID.test(read.id) || read.name !== site || !NAME.test(site))
         return null;
     const given = password(read.password);
     return { id: read.id, name: read.name, hasPassword: read.has_password === true || given !== null, password: given, teamLogin: read.sso_login === true };
@@ -47,7 +47,8 @@ export async function readSite(run, site) {
  * Gets the site password in place for the address Netlify's lock stands in front of, and saves only one that opens it.
  * The site's settings say what the lock is: a password, which the person's yes has the run store when Netlify gives it
  * back; the team login, which the person's yes has the run lift by making the site public; or neither. When the CLI
- * cannot read the site, or Netlify gives no password back, the person may paste the password.
+ * cannot read the site, no password goes anywhere, since the site's lock may be another's; when Netlify gives none
+ * back for a site it read, the person may paste the password.
  */
 export async function passNetlifyLock(deps) {
     let site = await readSite(deps.run, deps.site);
@@ -71,11 +72,12 @@ export async function passNetlifyLock(deps) {
         const failed = await deps.save(password);
         return failed ? { status: 'save-failed', reason: failed, protection: 'password', ...from } : { status: 'saved', password: how, protection: 'password', ...from, value: password };
     };
+    // A site the CLI cannot read as the person is not shown to be theirs: a password typed for it could go to anyone's deploy preview that asks for one.
+    if (!site)
+        return { status: 'refused', reason: `The Netlify CLI could not read the site ${deps.site} as the person: it is signed out, or the site is in no team of theirs. A password goes only to a site of the person's, so none was asked for or sent.` };
     /** Why the run has no password to open the preview with, for the paste screen's skip. */
     let stopped;
-    if (!site)
-        stopped = 'The Netlify CLI could not read the site: it is signed out, or the site is in no team of the person\'s.';
-    else if (site.hasPassword) {
+    if (site.hasPassword) {
         if (!site.password)
             stopped = 'Netlify does not give the site password back.';
         else if (!(await deps.consent()))

package/dist/netlify.js

@@ -1,14 +1,17 @@
 import { execFile } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { promisify } from 'node:util';
+import { folderOf, netlifyPreviewsFact, pickPreviewsFact } from './host-previews.js';
 import { gitEnvironment } from './sandbox.js';
 /**
  * Netlify: the deploy previews this repository's pull requests get (from
  * GitHub's record and from the Netlify CLI on this machine when it is signed
- * in), whether that CLI is signed in, and the connection of a site to this
- * repository through Netlify's site settings and its GitHub app. Nothing here
+ * in), whether that CLI is signed in, whether a site built from this
+ * repository builds Deploy Previews at all (host-previews.ts), and the
+ * connection of a site to this repository through Netlify's site settings and
+ * its GitHub app. Nothing here
  * reads a token, and nothing comes back beyond the fields below.
  */
 const execFileAsync = promisify(execFile);
@@ -121,13 +124,15 @@ async function fromGitHub(owner, repo, gh, only) {
     return { previews: found, heads: new Map(heads.map((head) => [head.number, head.sha])), failed };
 }
 /** What the Netlify CLI on this machine knows, when it is signed in: the sites built from this repository, and their deploy previews. */
-async function fromCli(owner, repo, netlify, only) {
+async function fromCli(owner, repo, netlify, only, directory) {
     const { cli } = await netlifyStatus(netlify);
+    const addresses = new Map();
     if (cli !== 'signed-in')
-        return { cli, sites: [], previews: [], failed: cli === 'unknown' };
+        return { cli, sites: [], addresses, previews: [], failed: cli === 'unknown' };
     const slug = `${owner}/${repo}`.toLowerCase();
     const sites = [];
     const previews = [];
+    const facts = [];
     let failed = false;
     try {
         for (const site of list(JSON.parse(await netlify(['sites:list', '--json'])))) {
@@ -135,7 +140,16 @@ async function fromCli(owner, repo, netlify, only) {
             // A site is this repository's only when it is built from it: the folder's own link to a site says nothing of that.
             if (typeof site.name !== 'string' || typeof site.id !== 'string' || !new RegExp(`^${SITE}$`).test(site.name) || typeof path !== 'string' || path.toLowerCase() !== slug)
                 continue;
+            // For one app, only the site whose base directory is the app's folder.
+            if (directory !== undefined && folderOf(record(site.build_settings)?.base) !== directory)
+                continue;
             sites.push(site.name);
+            const fact = netlifyPreviewsFact(site);
+            if (fact)
+                facts.push(fact);
+            // The site's own address, its custom domain when it has one: what Netlify prints as ssl_url.
+            if (typeof site.ssl_url === 'string' && /^https:\/\/[a-z0-9.-]{1,253}$/i.test(site.ssl_url))
+                addresses.set(site.name, site.ssl_url.toLowerCase());
             try {
                 // The newest 100 deploy previews, newest first: the first deploy of a pull request is its current one.
                 for (const deploy of list(JSON.parse(await netlify(['api', 'listSiteDeploys', '--data', JSON.stringify({ site_id: site.id, 'deploy-previews': true, per_page: 100 })])))) {
@@ -153,14 +167,26 @@ async function fromCli(owner, repo, netlify, only) {
     catch {
         failed = true;
     }
-    return { cli: 'signed-in', sites, previews, failed };
+    const pullRequestPreviews = pickPreviewsFact(facts);
+    return { cli: 'signed-in', sites, addresses, previews, failed, ...(pullRequestPreviews ? { pullRequestPreviews } : {}) };
 }
+/** The site whose address `production` is: the newest preview's, else the first the evidence names. */
+export const liveSite = (evidence) => evidence.previews[0]?.site ?? evidence.sites[0];
 /** Whether this repository's pull requests get Netlify deploy previews: the sites and the newest previews that GitHub and the signed-in Netlify CLI name; or, with `pull`, that pull request's only. */
 export async function readNetlifyPreviews(owner, repo, cwd, deps = {}) {
     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 { sites: [], previews: [], cli: 'missing', error: "Netlify's previews could not be read." };
     }
-    const [github, cli] = await Promise.all([fromGitHub(owner, repo, deps.gh ?? commandRunner('gh', cwd, { signal: deps.signal }), deps.pull), fromCli(owner, repo, deps.netlify ?? commandRunner('netlify', cwd, { signal: deps.signal }), deps.pull)]);
+    const [read, cli] = await Promise.all([fromGitHub(owner, repo, deps.gh ?? commandRunner('gh', cwd, { signal: deps.signal }), deps.pull), fromCli(owner, repo, deps.netlify ?? commandRunner('netlify', cwd, { signal: deps.signal }), deps.pull, deps.directory)]);
+    // For one app's folder, GitHub's record counts only for the site the CLI read as building it: a site's name says nothing of its folder.
+    const where = deps.directory ? `the folder ${deps.directory}` : "the repository's root";
+    const unmatched = deps.directory === undefined ? undefined
+        : cli.cli !== 'signed-in' ? `Which Netlify site builds ${where} cannot be told: the Netlify CLI here is not signed in, and only a site's settings name the folder it builds (its base directory).`
+            : cli.sites.length > 1 ? `Several Netlify sites build ${where} (${cli.sites.join(', ')}), so which one is this app's cannot be told.`
+                : !cli.sites.length && !cli.failed ? `No Netlify site of this repository builds ${where} (its base directory), as far as the Netlify CLI here can see.` : undefined;
+    const github = deps.directory === undefined ? read : { ...read, previews: unmatched ? [] : read.previews.filter((p) => cli.sites.includes(p.site)) };
+    if (unmatched)
+        Object.assign(cli, { sites: [], previews: [], addresses: new Map(), pullRequestPreviews: undefined });
     // A deploy of an older commit than its pull request's head says nothing of the head's own preview: a commit status, which names the head, outranks it, and a wait for that pull request's preview ignores it.
     const older = (p) => p.from === 'netlify cli' && Boolean(p.sha) && github.heads.has(p.pullRequest) && github.heads.get(p.pullRequest) !== p.sha;
     // Of a pull request's status and the CLI's deploy of the same commit the later change is the truer, a status winning a tie; an older commit's deploy comes next, a bot's comment, which names no commit and changes no state, last.
@@ -172,11 +198,18 @@ export async function readNetlifyPreviews(owner, repo, cwd, deps = {}) {
             previews.push(p);
     // The most recently updated first: an old pull request with a high number is not the newest preview.
     previews.sort((a, b) => b.at - a.at);
+    const sites = [...new Set([...cli.sites, ...previews.map((p) => p.site)])];
+    // The live site, at its own domain when the CLI read one, else where Netlify serves every site.
+    const live = liveSite({ sites, previews });
     return {
-        sites: [...new Set([...cli.sites, ...previews.map((p) => p.site)])],
+        sites,
+        ...(live ? { production: cli.addresses.get(live) ?? `https://${live}.netlify.app` } : {}),
         previews: previews.slice(0, NEWEST).map(({ at, sha, ...preview }) => preview),
         cli: cli.cli,
         ...(github.failed || cli.failed ? { error: "Some of Netlify's previews could not be read: what is missing is unknown, not absent." } : {}),
+        // The site's settings ride with the plain evidence, not with a wait for one pull request's preview.
+        ...(deps.pull === undefined && cli.pullRequestPreviews ? { pullRequestPreviews: cli.pullRequestPreviews } : {}),
+        ...(unmatched ? { unmatched } : {}),
     };
 }
 const CLONE_WAIT = { totalMs: 60_000, everyMs: 5_000 };
@@ -195,9 +228,9 @@ async function pause(ms, deps) {
     }
 }
 /** The site this folder is linked to, as `netlify link` and `sites:create` leave it in .netlify/state.json. */
-async function linkedSiteId(cwd) {
+export function linkedNetlifySite(cwd) {
     try {
-        const id = JSON.parse(await readFile(join(cwd, '.netlify', 'state.json'), 'utf8')).siteId;
+        const id = JSON.parse(readFileSync(join(cwd, '.netlify', 'state.json'), 'utf8')).siteId;
         return typeof id === 'string' && /^[A-Za-z0-9-]{1,64}$/.test(id) ? id : undefined;
     }
     catch {
@@ -252,11 +285,12 @@ export async function waitForNetlifyAccess(siteId, deps) {
  * when a repository is linked: the repository, its default branch, and the installation of Netlify's GitHub app on the
  * repository's GitHub account, which Netlify names on every site of the person's that the app already builds from that
  * account. GitHub sends the app each push and pull request, so the pull requests build deploy previews. Then the first
- * build says whether the app reads the repository.
+ * build says whether the app reads the repository. Only a site this run's own sites:create made takes the connection,
+ * and a site built from another repository keeps it: the person's sites are never pointed elsewhere.
  */
 export async function connectNetlifySite(owner, repo, cwd, deps) {
     const not = (reason, more = {}) => ({ connected: false, reason, ...more });
-    const siteId = await linkedSiteId(cwd);
+    const siteId = linkedNetlifySite(cwd);
     if (!siteId)
         return not('This folder is linked to no Netlify site: link or create one first.');
     let site;
@@ -284,10 +318,16 @@ export async function connectNetlifySite(owner, repo, cwd, deps) {
     if (typeof settings?.repo_path === 'string' && settings.repo_path.toLowerCase() === slug) {
         // Connected before this run: its newest build says whether the app still reads the repository.
         const reads = await netlifyReadsRepository(siteId, 0, { ...deps, wait: { totalMs: 0, everyMs: 0 } });
+        const fact = netlifyPreviewsFact(site);
+        const previews = fact ? { pullRequestPreviews: fact } : {};
         return reads === 'no' && positive(settings.installation_id)
-            ? not("Netlify's GitHub app cannot read the repository.", { site: linked, how: 'already', access: accessPage(settings.installation_id) })
-            : { connected: true, site: linked, how: 'already' };
+            ? not("Netlify's GitHub app cannot read the repository.", { site: linked, how: 'already', access: accessPage(settings.installation_id), ...previews })
+            : { connected: true, site: linked, how: 'already', ...previews };
     }
+    if (typeof settings?.repo_path === 'string' && settings.repo_path)
+        return not('The linked site is built from another repository, and stays so: link a site built from this repository, or create one with netlify sites:create.', { site: linked });
+    if (!deps.linked.has(siteId))
+        return not('The linked site was not created in this run: only a site netlify sites:create made here, or one built from this repository already, takes the connection.', { site: linked });
     const branch = github?.default_branch;
     const fullName = typeof github?.full_name === 'string' && github.full_name.toLowerCase() === slug ? github.full_name : undefined;
     if (!github || !positive(github.id) || typeof branch !== 'string' || !branch || !fullName)
@@ -330,7 +370,9 @@ export async function connectNetlifySite(owner, repo, cwd, deps) {
     }
     if (record(updated?.build_settings)?.repo_path !== fullName)
         return not('Netlify did not keep the repository in the site settings.', { site: linked });
+    const fact = updated && netlifyPreviewsFact(updated);
+    const previews = fact ? { pullRequestPreviews: fact } : {};
     return (await netlifyReadsRepository(siteId, since, deps)) === 'no'
-        ? not("Netlify's GitHub app cannot read the repository.", { site: linked, how: 'github-app', access: accessPage(installation) })
-        : { connected: true, site: linked, how: 'github-app' };
+        ? not("Netlify's GitHub app cannot read the repository.", { site: linked, how: 'github-app', access: accessPage(installation), ...previews })
+        : { connected: true, site: linked, how: 'github-app', ...previews };
 }

package/dist/pi-paths.js

@@ -0,0 +1,69 @@
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * How pi's file tools turn the model's path string into the path they open, mirrored from @earendil-works/pi-coding-agent
+ * (normalizePath and resolvePath in dist/utils/paths.js, resolveToCwd and resolveReadPath in dist/core/tools/path-utils.js),
+ * which the package does not export. The fence judges the path pi opens, never the string the model typed, so each of
+ * these is held against pi's own in test/pi-paths.test.ts: a pi upgrade that changes them fails there.
+ */
+const UNICODE_SPACES = /[  -   　]/g;
+/** Git Bash, MSYS, Cygwin and WSL drive paths, as pi takes them on Windows. */
+export function windowsShellPath(path) {
+    if (!path.startsWith('/') || path.startsWith('//') || path.includes('\\'))
+        return path;
+    const match = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i.exec(path);
+    if (!match)
+        return path;
+    const suffix = match[2]?.replaceAll('/', '\\');
+    return `${match[1].toUpperCase()}:\\${suffix ?? ''}`;
+}
+function normalizePath(input, platform, tool) {
+    let normalized = tool ? input.replace(UNICODE_SPACES, ' ') : input;
+    if (tool && normalized.startsWith('@'))
+        normalized = normalized.slice(1);
+    if (platform === 'win32')
+        normalized = windowsShellPath(normalized);
+    const home = homedir();
+    if (normalized === '~')
+        return home;
+    if (normalized.startsWith('~/') || (platform === 'win32' && normalized.startsWith('~\\')))
+        return join(home, normalized.slice(2));
+    if (/^file:\/\//.test(normalized))
+        return fileURLToPath(normalized);
+    return normalized;
+}
+/** The path pi's write, edit, grep, find and ls tools open for the model's string. */
+export function resolveToCwd(path, cwd, platform = process.platform) {
+    const normalized = normalizePath(path, platform, true);
+    return isAbsolute(normalized) ? resolve(normalized) : resolve(normalizePath(cwd, platform, false), normalized);
+}
+const exists = (path) => {
+    try {
+        accessSync(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The path pi's read tool opens: the string's own, or, when that is not there, the first of its spellings that is (a narrow no-break space before AM/PM, NFD, a curly apostrophe, both). */
+export function resolveReadPath(path, cwd, platform = process.platform) {
+    const resolved = resolveToCwd(path, cwd, platform);
+    if (exists(resolved))
+        return resolved;
+    const amPm = resolved.replace(/ (AM|PM)\./gi, ' $1.');
+    if (amPm !== resolved && exists(amPm))
+        return amPm;
+    const nfd = resolved.normalize('NFD');
+    if (nfd !== resolved && exists(nfd))
+        return nfd;
+    const curly = resolved.replace(/'/g, '’');
+    if (curly !== resolved && exists(curly))
+        return curly;
+    const nfdCurly = nfd.replace(/'/g, '’');
+    if (nfdCurly !== resolved && exists(nfdCurly))
+        return nfdCurly;
+    return resolved;
+}

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

@@ -1,6 +1,6 @@
 ### When this applies
 
-Cloudflare Pages deploys previews of the pull requests: impeccable_cloudflare_previews lists a built preview of a pull request (`state` success), with its address and the branch's alias. Ask it only where the repository is set up for Cloudflare (`wrangler.toml`, `wrangler.json` or `wrangler.jsonc`, a `wrangler` or `@cloudflare/*` package, a `.pages.dev` address in the README or the workflows), but its record decides, not the checkout: Cloudflare's GitHub app posts a check run on each commit it built and a comment on the pull request, and cf, Cloudflare's CLI, lists the project's deployments when it is signed in here. Cloudflare 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.
+Cloudflare Pages deploys previews of the pull requests: impeccable_cloudflare_previews lists a built preview of a pull request (`state` success), with its address and the branch's alias. Ask it only where the repository is set up for Cloudflare (`wrangler.toml`, `wrangler.json` or `wrangler.jsonc`, a `wrangler` or `@cloudflare/*` package, a `.pages.dev` or `.workers.dev` address in the README or the workflows), but its record decides, not the checkout: Cloudflare's GitHub app posts a check run on each commit it built and a comment on the pull request, and cf, Cloudflare's CLI, lists the project's deployments when it is signed in here. It applies as well where the checkout is set up for Cloudflare and no pull request got a preview: the answer then says why (`pullRequestPreviews`, `worker`, `githubApp`), and "No pull-request previews" below says what the run does about each cause, in that order, before any other preview is set up. Cloudflare 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.
 
 ### Steps
 
@@ -9,9 +9,17 @@ Cloudflare Pages deploys previews of the pull requests: impeccable_cloudflare_pr
 
 ### Reference
 
+- **The live app**: `production` in the evidence is the project's own address, `https://<project>.pages.dev`; live-app-address says how it becomes the before, in step 2's write.
 - **Behind Cloudflare Access** (`gate: "cloudflare-access"`): Cloudflare's login stands in front of the previews. Get past it as preview-protection says, which proves the preview, and go on with step 2; when nothing got past it, that case says how the run ends.
 - **Another app, or no answer from any of the three**: Cloudflare's previews do not show this app. Set the preview up as server-previews or static-site says instead, and say under "What is not verified" what the Cloudflare address answered.
-- **Nothing listed**: Cloudflare's previews are not on record, so set the preview up as server-previews or static-site says. An `error` means a read failed, so a preview may exist that is not listed: say so under "What is not verified".
+- **No pull-request previews**: the checkout is set up for Cloudflare and nothing is listed, or a project's settings build none. The aim holds: find out why from the answer, in this order, and for each cause ask once with the tool that fixes it, before anything is pushed and never a second time; with a preview listed, after step 1's proof and preview-protection's steps, so the person sees the lock's question and this one back to back, at most one each. Each tool shows its one screen and does the change as the person, or opens the page where it cannot. After `enabled` or `connected`, nothing is listed yet, so the test drive's build is the first preview: take pull-requests' step 4 the Cloudflare way and save the method on its alias as step 2 says, no setup pull request.
+  1. **Previews off** (`pullRequestPreviews` with `enabled: false` and `cause` `previews` or `deployments`, with its `reason`): cf, signed in, found the Pages project built from this repository, and its settings build no previews of pull requests. impeccable_enable_previews (`host: "cloudflare"`) turns the preview branch control on; deployments off altogether is the person's change, on the page it opens.
+  2. **Not connected** (`cause: "source"`): the Pages project the checkout names (its wrangler config, or the README's pages.dev address) exists with no Git repository connected, so no push builds. impeccable_cloudflare_connect connects it to this repository.
+  3. **A Worker, not a Pages project** (`worker` in the answer, and no `pullRequestPreviews`): Cloudflare builds the repository as a Worker (Workers Builds: its check runs name the script, or the wrangler config or the README's workers.dev address does), which gives pull requests no preview, and a Worker with static assets no branch build at all. impeccable_cloudflare_connect, with the build command and output folder the checkout runs, creates a Pages project for the repository and connects it; the Worker stays as it is. The same tool creates the project where the config names a Pages project cf finds nowhere.
+  4. **Cloudflare's GitHub app cannot see the repository** (`githubApp` in the answer: the app's installation covers selected repositories, or `installed: false`): a project connected with previews on still gets no build, since the app builds only the repositories its installation names. Nothing in the account shows it, so the wait for the test drive's build tells: when none comes, the wait's own screen opens the installation page (`githubApp.page`) and waits again on the person's yes. Its `reason` says when they skipped it or no build came after the retries.
+- **`skipped` or `refused` from any of these**: push no test drive on Cloudflare (pull-requests' "No preview, no test drive" where a preview was proven; else set the preview up as server-previews or static-site says, never without saying so) and say under "What was skipped, and why" which cause stopped it, with the `reason`, and name the `page` where there is one; the person was asked in this run, so `left` stays empty.
+- **No `pullRequestPreviews`, no `worker`** (`cli` signed out or unknown, or no Pages project built from this repository among the accounts cf reaches): the check could not be made. Say so in one line under "What is not verified", naming why, and go on as the aim says: nothing listed, as "Nothing listed" says; a preview listed, as the steps say, where the wait for the test drive's build then tells.
+- **Nothing listed**, and neither `pullRequestPreviews` nor `worker` nor a project the checkout names: Cloudflare's previews are not on record, so set the preview up as server-previews or static-site says. An `error` means a read failed, so a preview may exist that is not listed: say so under "What is not verified".
 - **The pull requests**: no setup pull request; the test drive branches from the default branch, and Cloudflare builds every pushed branch, so pull-requests' step 4 goes the Vercel way with impeccable_cloudflare_previews in place of impeccable_hosted_previews: with `branch: "impeccable/test-drive"` it waits up to five minutes for the check run on the pushed head, under a status line with its timer, and the test drive's page is proven on the alias it lists before the pull request opens. In place of pull-requests' step 3, build the test drive branch once with the build Cloudflare runs (the Pages project's build command, which the checkout's `package.json` `build` script usually is), so a page that does not build is never pushed.
-- The evidence is read only: link, deploy and change nothing on Cloudflare. The one Cloudflare sign-in is impeccable_cloudflare_access's, behind Access, on the person's yes. Cloudflare does not report its previews as GitHub deployments, so Impeccable finds them by their address pattern, the branch's alias: save the pattern the proof answered, and no other.
-- The report names the address that answered with this app under "What we found", and the pattern saved under "What was configured, and by whom". The test drive's own preview, which Cloudflare builds after the run, goes under "What is not verified".
+- The evidence is read only: link, deploy and change nothing on Cloudflare beyond what impeccable_enable_previews and impeccable_cloudflare_connect do on the person's yes. The Cloudflare sign-ins are those tools' own, on the person's yes. Cloudflare does not report its previews as GitHub deployments, so Impeccable finds them by their address pattern, the branch's alias: save the pattern the proof answered, and no other.
+- The report names the address that answered with this app under "What we found" (and the Worker, where Cloudflare builds one), and the pattern saved under "What was configured, and by whom", with the pull-request previews turned on when they were (`by` says whether the run or the person did), the Pages project created or connected (`created` says which; name its `subdomain` address) and the access given to Cloudflare's GitHub app, since the account changed. The test drive's own preview, which Cloudflare builds after the run, goes under "What is not verified".

package/dist/playbook/cases/first-preview-failure.md

@@ -6,7 +6,7 @@ A rerun: the setup pull request an earlier run opened has a preview job that fai
 
 1. **Record** the earlier pull requests with impeccable_test_pr: the open test drive, and the setup pull request in `setup_pr`. That binding cannot change. Done when it answers "Recorded".
 2. **Read the attempts** with impeccable_preview_run. Done when you know the failed attempt's `stage` and `reason`, the `budget`, and that the state's `lastRun` for the app is the same run.
-3. **Reproduce and correct**: run the failed step again with impeccable_verify_preview and find the smallest correction (see the table). Done when the correction passes locally, or no safe one exists: then push nothing more, and report.
+3. **Reproduce and correct**: run the failed step again with impeccable_verify_preview and find the smallest correction (see the table). Where the check is skipped on this machine (its answer says it has no sandbox for it), reason from the attempt's `stage`, the table and the repository's files instead, and the next attempt is what proves the correction. Done when the correction passes locally, or, with the check skipped, is the smallest the table gives: then step 4. When no safe correction exists, push nothing more, and report.
 4. **Push one correction**: save it with impeccable_write to `preview` (with `appKey`), impeccable_sync_workflow, commit on the setup branch, push once, then impeccable_preview_run again. Done when the new attempt shows in `budget`.
 5. **Check it once** with impeccable_write to `latest-pull-check`: `verified: true` means this setup pull request's preview answered at the pushed head, which a passed job alone does not prove. A 409 `no-preview-running` or a job still starting is expected. Done when it answered; report the outcome you saw.
 6. **Open a new test drive** from the corrected setup branch, with the default branch as its base (the earlier one ran on the old head), record it with impeccable_test_pr beside the same setup pull request, then impeccable_report. Done when impeccable_report answered.

package/dist/playbook/cases/live-app-address.md

@@ -0,0 +1,15 @@
+### When this applies
+
+Every run that saves a preview method, for the state's `before` item: the address of the live app, which every review then shows beside the change. The item reads `optional` until an address is saved, so the checkup never waits on it; the run sets it all the same, from what the host or the repository already says, and asks nobody: the host's own address of the connected project changes nothing of the person's. Where Impeccable builds the previews itself (static-site), its build of the default branch is the before and the item reads done on its own: set nothing.
+
+### Steps
+
+1. **Find the address**: the `production` address a host tool answered (impeccable_netlify_previews, the Netlify site's own; impeccable_cloudflare_previews, the Pages project's, `https://<project>.pages.dev`; impeccable_hosted_previews, the linked Vercel project's own domain where GitHub records a production deployment of it; impeccable_vercel_connect's `productionUrl` where production exists), else the live-site line the item's `proposal` read in the README, checked against the file, when it is the site's or project's own address on one of the hosts (an address elsewhere is only the host tools' to name). A project or site created in this run has no live app yet. Done when you have one address, or know there is none.
+2. **Prove it** with impeccable_prove_preview, under the status line *"Opening the live app"*: that address, or a page on it a visitor opens without signing in, and words the page shows that the checkout holds. A key the run already got in place (Vercel's bypass secret, Netlify's site password, Cloudflare's service token) goes with it where the lock is the same project's or site's. Done when it answers `proven: true`. **An address no key opens is not set**: a `gate`, the app's own sign-in on every page, or no answer leaves the item as it is, and the report says what the address answered.
+3. **Save it** with impeccable_write to `preview`: `beforeUrl` the proven address, in the same write as the method where the proof came before it (`{"intendedMethod": "preview-deploy", "beforeUrl": "https://…"}`), else in a write of its own; `appKey` the app's on a repository of several apps, one address per app. Done when the answer carries `beforeUrl`; its `beforeCheck.access` says how Impeccable's own check opened it: `ok`; `auth-wall`, the app's sign-in, which the saved test accounts get past; anything else goes under "What is not verified".
+
+### Reference
+
+- **The report** names the address under "What was configured, and by whom" (*The live app's address, https://…, as the before of every review, by the setup agent.*), or, with none set, says under "What was skipped, and why" what stopped it: no live app yet, no address known, or what the address answered.
+- Never save a preview's address (one deployment's, with a hash or a branch in its name), a placeholder, or an address the proof did not answer with this app: impeccable_write refuses an unproven one. Clear nothing: an address the person saved stays.
+- **Status lines** belong to the Preview method task.