@impeccable/reviews 0.1.0 → 0.1.1

package/dist/fence.js

@@ -1,5 +1,7 @@
+import { execFileSync } from 'node:child_process';
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { DATA_NOTE, scan, scanRecorder } from './scan.js';
 const allow = (reason = 'on the allowlist') => ({ verdict: 'allow', reason });
 const deny = (reason) => ({ verdict: 'deny', reason });
 const never = (reason) => ({ verdict: 'never', reason });
@@ -179,10 +181,12 @@ function pathsOf(args) {
     return args.flatMap((a) => (a.startsWith('--') && a.includes('=') ? [a.slice(a.indexOf('=') + 1)] : a.startsWith('-') ? [] : [a]));
 }
 const inside = (args, where) => !pathsOf(args).some((a) => outside(a, where));
+/** Files named as examples, whose secrets are placeholders. */
+const EXAMPLE = /\.(example|sample|template|dist)$/;
 /** A .env file, or a pattern that can name one, holds live secrets; the examples next to it do not. */
 export function isSecretFile(path) {
     const name = basename(path);
-    return name.startsWith('.env') && !/\.(example|sample|template|dist)$/.test(name);
+    return name.startsWith('.env') && !EXAMPLE.test(name);
 }
 function rmRecursiveForce(words) {
     const at = words.indexOf('rm');
@@ -275,7 +279,7 @@ function commitReads(args) {
     }
     return values;
 }
-function git(args, where, protectedBranches) {
+function git(args, where, protectedBranches, held = false) {
     const [sub, ...rest] = args[0] === '--no-pager' ? args.slice(1) : args;
     if (sub === 'status' || sub === 'diff' || sub === 'log' || sub === 'show' || sub === 'add') {
         const excluded = sub === 'add' && rest.includes(EXCLUDE_ENV);
@@ -304,7 +308,10 @@ function git(args, where, protectedBranches) {
         return allow();
     if (sub === 'push' && rest.length === 3 && (rest[0] === '-u' || rest[0] === '--set-upstream') && rest[1] === 'origin') {
         const branch = rest[2];
-        return branch.includes(':') || branch === 'HEAD' || protectedBranches.includes(branch) ? deny('a push to the default branch') : allow();
+        if (branch.includes(':') || branch === 'HEAD' || protectedBranches.includes(branch))
+            return deny('a push to the default branch');
+        // A connected Vercel project builds every push, and calls a new project's first deployment Production, public at the project's own address.
+        return held ? deny("a push before impeccable_vercel_connect settled the linked Vercel project's first deployment: run it first") : allow();
     }
     return deny('a git command off the allowlist');
 }
@@ -430,6 +437,16 @@ const NETLIFY_VALID = {
     '--context': /^deploy-preview$/,
     '--account-slug': /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/,
 };
+/** The Vercel project the folder is linked to, as `vercel link` wrote it in `.vercel/project.json`; null with none. */
+function linkedVercelProject(dir) {
+    try {
+        const id = JSON.parse(readFileSync(join(dir, '.vercel', 'project.json'), 'utf8')).projectId;
+        return typeof id === 'string' ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Whether the folder is linked to a Netlify site: `.netlify/state.json` names it. */
 function linkedToSite(dir) {
     try {
@@ -444,8 +461,9 @@ function linkedToSite(dir) {
  * project's link and creation, in the person's own current team or the one team they chose (`team`), and a built draft
  * deploy for a deploy preview of a linked folder. The sign-in and the repository's connection are the tools' (a
  * `netlify login` outside the sign-in screen, and a `netlify init` that asks its questions in a terminal, never run).
- * Never production or a project's removal, and nothing of its environment variables, its API (which reaches them) or
- * a token on the command line.
+ * Never production or a project's removal, and nothing of its environment variables, its API (which reaches them, and
+ * prints a site's password: impeccable_netlify_password runs it in the command's own process) or a token on the
+ * command line.
  */
 function netlify(args, where, agreed, team) {
     const words = [];
@@ -477,6 +495,8 @@ function netlify(args, where, agreed, team) {
         return deny('the Netlify sign-in is impeccable_ask\'s, with the id netlify-setup: it opens the browser from the sign-in screen');
     if (sub === 'init')
         return deny('netlify init asks its questions in a terminal this run does not have: impeccable_netlify_connect connects the repository');
+    if (sub === 'api')
+        return deny("netlify api prints a site's settings, its password among them: impeccable_netlify_password and impeccable_netlify_connect run it in the command's own process");
     if (!agreed)
         return deny('sets Netlify up, and the person has not signed in to Netlify for that');
     /** Only these options, each with a value of its kind. */
@@ -510,7 +530,7 @@ const VERCEL_TEAM = ['--scope', '-S', '--team'];
  * command's own process, so no secret reaches the model, and `api` and `curl` reach them too) or a token on the command
  * line.
  */
-function vercel(args, where, agreed, team) {
+function vercel(args, where, agreed, team, settlement = null) {
     const words = [];
     const options = new Map();
     for (let i = 0; i < args.length; i++) {
@@ -551,9 +571,17 @@ function vercel(args, where, agreed, team) {
         case 'project':
             return ['add', 'ls', 'list'].includes(rest[0] ?? '') && rest.length <= 2 && only(...VERCEL_TEAM) ? allow() : deny('a vercel project command off the allowlist');
         case 'git':
+            // Vercel could not reach the repository, which released the push as it built nothing: a connection now would let it build the project's first deployment, served publicly, so the tool that locks the project makes it.
+            if (settlement?.how === 'connection')
+                return deny('a vercel git connect after Vercel could not reach the repository: impeccable_vercel_connect connects it and locks a new project before anything is pushed');
             return rest.join(' ') === 'connect' && only(...VERCEL_TEAM) ? allow() : deny('a vercel git command other than connect');
-        case 'deploy':
+        case 'deploy': {
+            // A deploy builds the project the folder it runs in is linked to: the one --cwd names, else this one.
+            const folder = resolve(where.cwd, typeof cwd === 'string' ? cwd : '.');
+            if (!(settlement?.how === 'project' && settlement.projectId === linkedVercelProject(folder)))
+                return deny("a deploy before impeccable_vercel_connect settled the first deployment of the project this folder is linked to: a deploy from here builds it whether or not Vercel reaches the repository");
             return rest.length <= 1 && inside(rest, where) && only('--yes', '-y', '--target', ...VERCEL_TEAM) ? allow() : deny('a vercel deploy off the preview allowlist');
+        }
         case 'env':
             return deny("Vercel's environment variables are the person's");
         default:
@@ -611,7 +639,7 @@ function simpleCommand(seg, where, opts) {
                 return deny('a cd that runs only sometimes: put it first, or after ;');
             return isFolder(realPath(resolve(where.cwd, args[0]))) ? allow() : deny('a cd into a folder that is not there');
         case 'git':
-            return git(args, where, opts.protectedBranches);
+            return git(args, where, opts.protectedBranches, opts.hosts.has('vercel') && !(opts.vercelSettled && opts.vercelSettled.projectId === linkedVercelProject(where.root)));
         case 'gh':
             if (args[0] === 'pr' && (args[1] === 'create' || args[1] === 'view'))
                 return allow();
@@ -636,16 +664,101 @@ function simpleCommand(seg, where, opts) {
         case 'netlify':
             return netlify(args, where, opts.hosts.has('netlify'), opts.teams.get('netlify'));
         case 'vercel':
-            return vercel(args, where, opts.hosts.has('vercel'), opts.teams.get('vercel'));
+            return vercel(args, where, opts.hosts.has('vercel'), opts.teams.get('vercel'), opts.vercelSettled);
         default:
             if (PACKAGE_MANAGERS.has(cmd) && installsHostCli(cmd, args, opts.hosts))
                 return allow('installs the CLI of the host the person said yes to');
             return PACKAGE_MANAGERS.has(cmd) ? packageManager(cmd, args, where, opts.scriptsChanged) : deny(`${cmd} is not on the allowlist`);
     }
 }
+/** A refusal by a content check: a command naming a file that holds credentials, or text shaped like a secret where `sink` would take it off the machine. */
+const found = (pattern, sink) => ({
+    verdict: 'deny',
+    reason: pattern.context === 'command' ? `names ${pattern.description}, which holds credentials (${pattern.name})` : `${sink} holds text shaped like ${pattern.description} (${pattern.name})`,
+    hit: { pattern, sink },
+});
+/** A file's text, when the command may read it (in the checkout or the scratch folder, and no .env file); null otherwise, or when it cannot be read. */
+function readable(path, where) {
+    if (path.startsWith('~') || /[$*?[]/.test(path) || isSecretFile(path) || (outside(path, where) && !inScratch(path, where)))
+        return null;
+    try {
+        return readFileSync(resolve(where.cwd, path), 'utf8').slice(0, 1_000_000);
+    }
+    catch {
+        return null;
+    }
+}
+/** The messages of the commits `revisions` name, as git log gives them; null when git cannot read them. */
+function commitMessages(revisions, cwd) {
+    try {
+        // The closing -- reads each as a commit even where a file of the same name is there.
+        return execFileSync('git', ['log', '--format=%B', ...revisions, '--'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000, maxBuffer: 16 * 1024 * 1024 });
+    }
+    catch {
+        return null;
+    }
+}
+/** The words of a git commit or a gh pr create that are its message, title or body: text, not paths. */
+function textWords(words) {
+    const text = new Set();
+    const commit = words[0] === 'git' && (words[1] === 'commit' || (words[1] === '--no-pager' && words[2] === 'commit'));
+    if (!commit && !(words[0] === 'gh' && words[1] === 'pr' && words[2] === 'create'))
+        return text;
+    words.forEach((w, i) => {
+        if (commit ? /^-[a-zA-Z]*m$|^--message$/.test(w) : /^(?:-t|--title|-b|--body)$/.test(w))
+            text.add(i + 1);
+        else if (commit ? /^-[a-zA-Z]*m.|^--message=/.test(w) : /^-[tb].|^--(?:title|body)=/.test(w))
+            text.add(i);
+    });
+    return text;
+}
+/**
+ * The content checks on a command the fence allows: a file that holds credentials, named anywhere in it but its message; and
+ * text shaped like a secret in what it sends off the machine: a commit's message, or the file or commit it takes one from, and
+ * a pull request's title, body, body file, or the commit messages --fill takes them from.
+ */
+function contentCheck(seg, where, defaultBranch) {
+    const text = textWords(seg.words);
+    for (const [i, word] of [...seg.words, ...seg.redirects.map((r) => r.target)].entries()) {
+        if (text.has(i))
+            continue;
+        const path = word.startsWith('-') && word.includes('=') ? word.slice(word.indexOf('=') + 1) : word;
+        const hit = scan('command', word).find((p) => !p.outsideOnly || outside(path, where));
+        if (hit)
+            return found(hit, 'the command');
+    }
+    const [cmd, ...rest] = seg.words;
+    const args = cmd === 'git' && rest[0] === '--no-pager' ? rest.slice(1) : rest;
+    const texts = [];
+    if (cmd === 'git' && args[0] === 'commit') {
+        texts.push(['the commit message', args.slice(1).join('\n')]);
+        // -F reads a file, and -c and -C take another commit's message: a value may name both, a file and a commit, so both are read.
+        for (const v of commitReads(args.slice(1)))
+            texts.push(['the commit message file', readable(v, where)], ['the commit message it reuses', commitMessages(['-1', '--end-of-options', v], where.cwd)]);
+    }
+    else if (cmd === 'gh' && args[0] === 'pr' && args[1] === 'create') {
+        const parsed = createArguments(args.slice(2));
+        texts.push(["the pull request's title or body", args.slice(2).join('\n')]);
+        if (parsed?.bodyFile)
+            texts.push(["the pull request's body file", readable(parsed.bodyFile, where)]);
+        if (parsed?.filled) {
+            // What gh fills the title and body from: the commits on the head that the base does not have, or the newest hundred when git cannot tell which.
+            const base = parsed.base ?? defaultBranch, head = parsed.head ?? 'HEAD';
+            const ranges = [...(base ? [`origin/${base}..${head}`, `${base}..${head}`].map((range) => ['--end-of-options', range]) : []), ['-n', '100', '--end-of-options', head]];
+            const messages = ranges.reduce((read, range) => read ?? commitMessages(range, where.cwd), null);
+            texts.push(["the commit messages --fill takes the pull request's title and body from", messages]);
+        }
+    }
+    for (const [sink, text] of texts) {
+        const hit = text ? scan('output', text)[0] : undefined;
+        if (hit)
+            return found(hit, sink);
+    }
+    return null;
+}
 /** The fence's answer for one shell command run from the checkout's top folder. */
 export function classifyCommand(command, root, options = {}) {
-    const opts = { protectedBranches: options.protectedBranches ?? ['main', 'master'], scriptsChanged: options.scriptsChanged ?? false, hosts: options.hosts ?? new Set(), teams: options.teams ?? new Map() };
+    const opts = { protectedBranches: options.protectedBranches ?? ['main', 'master'], scriptsChanged: options.scriptsChanged ?? false, hosts: options.hosts ?? new Set(), teams: options.teams ?? new Map(), vercelSettled: options.vercelSettled ?? null };
     const segments = parseCommand(command);
     if (!segments)
         return deny('uses shell syntax the fence does not read');
@@ -654,7 +767,9 @@ export function classifyCommand(command, root, options = {}) {
     const where = { root: realPath(root), cwd: root, scratch: options.scratch && realPath(options.scratch) };
     let result = allow();
     for (const seg of segments) {
-        const decision = simpleCommand(seg, where, opts);
+        let decision = simpleCommand(seg, where, opts);
+        if (decision.verdict === 'allow')
+            decision = contentCheck(seg, where, opts.protectedBranches[0]) ?? decision;
         if (decision.verdict === 'never')
             return decision;
         if (decision.verdict === 'deny' && result.verdict === 'allow')
@@ -830,7 +945,7 @@ function createArguments(args) {
         return;
     if (values.has('body-file') && (!bodyFile || bodyFile === '-'))
         return;
-    return { head, repository: values.get('repo'), bodyFile };
+    return { head, repository: values.get('repo'), bodyFile, base: values.get('base'), filled };
 }
 /** Called synchronously only after the ordinary fence allows the entire command. */
 export function reservePreviewCommand(state, command, root, scratch) {
@@ -1002,6 +1117,14 @@ export function chooseHostTeam(log, questionId, team) {
     if (host && Object.hasOwn(HOST_CLIS, host) && hostsAgreed(log).has(host) && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(team))
         teamsChosen(log).set(host, team);
 }
+/** What impeccable_vercel_connect settled of the linked Vercel project's first deployment in this run, by the run's log. */
+const settledVercel = new WeakMap();
+export function settleVercelFirstDeployment(log, settlement) {
+    settledVercel.set(log, settlement);
+}
+export function vercelFirstDeploymentSettled(log) {
+    return settledVercel.get(log) ?? null;
+}
 /** Tool calls a run makes before the fence refuses more: a setup takes far fewer, and a run steered elsewhere stops there. */
 export const MAX_TOOL_CALLS = 400;
 /** What still runs past the cap, so the run can say where it got to and end. */
@@ -1010,14 +1133,56 @@ const FINISHING = new Set(['impeccable_progress', 'impeccable_report']);
 const CREDENTIAL = /TOKEN|SECRET|PASSW(?:OR)?D|PASSPHRASE|CREDENTIAL|PRIVATE|(?:^|_)(?:API_?)?KEY(?:_|$)|APIKEY|AUTH(?!OR)|COOKIE|_PWD$|DATABASE_URL$|^(?:AWS|AZURE|ANTHROPIC|OPENAI|OP_SESSION)_/i;
 /**
  * The environment for the agent's shell: the person's, without credentials, whether by name or as a URL's password (a database's
- * connection string), a proxy's too. A folder or a socket is a place, not a secret, so VERCEL_AUTH_CONFIG_DIR and SSH_AUTH_SOCK stay; gh
- * and git sign in from their own config and keychain.
+ * connection string), a proxy's too. A folder, a socket or AWS's region setting is a place, not a secret, whatever its name looks like, so
+ * VERCEL_AUTH_CONFIG_DIR, SSH_AUTH_SOCK and AWS_REGION stay; gh and git sign in from their own config and keychain.
  */
+const PLACE = /_(?:DIR|HOME|SOCK)$|^AWS_(?:DEFAULT_)?REGION$/;
 export function shellEnvironment(env) {
-    return Object.fromEntries(Object.entries(env).filter(([name, value]) => /_(?:DIR|HOME|SOCK)$/.test(name)
-        || (!CREDENTIAL.test(name) && !/:\/\/[^/@\s:]*:[^/@\s]+@/.test(value ?? ''))));
+    return Object.fromEntries(Object.entries(env).filter(([name, value]) => (PLACE.test(name) || !CREDENTIAL.test(name)) && !/:\/\/[^/@\s:]*:[^/@\s]+@/.test(value ?? '')));
+}
+/** The impeccable_* tools whose input is saved, sent to the web page or shown to the person. */
+const OUTPUT_TOOLS = new Set(['impeccable_write', 'impeccable_report', 'impeccable_progress', 'impeccable_ask']);
+/** Every string in a value, by where it sits: body.env.API_TOKEN, tasks[2].title. */
+function strings(value, at = '') {
+    if (typeof value === 'string')
+        return [[at, value]];
+    if (Array.isArray(value))
+        return value.flatMap((v, i) => strings(v, `${at}[${i}]`));
+    if (value && typeof value === 'object')
+        return Object.entries(value).flatMap(([k, v]) => strings(v, at ? `${at}.${k}` : k));
+    return [];
 }
-export function fenceExtension(root, log, protectedBranches, scratch) {
+/**
+ * Text shaped like a secret in what a tool call writes, saves or shows: the new text of a write or an edit (never what it
+ * replaces, and nothing in a .env file's example such as .env.example), and every string the impeccable_* tools take.
+ * Each string is read with its field's name in front, so a secret-like name set to a random value is seen too.
+ */
+function outputCheck(tool, input) {
+    let fields;
+    if (tool === 'write' || tool === 'edit') {
+        // A .env file's example holds placeholders; another file named as an example (config.ts.example) is checked like any file.
+        if (basename(String(input.path ?? '')).startsWith('.env') && EXAMPLE.test(String(input.path ?? '')))
+            return null;
+        fields = tool === 'write' ? [['content', input.content]] : [['newText', input.newText], ...strings(input.edits, 'edits').filter(([at]) => at.endsWith('.newText'))];
+    }
+    else {
+        fields = strings(input);
+    }
+    // The one reference impeccable_write swaps for what the person typed: a test account's password.
+    const swapped = (at, text) => tool === 'impeccable_write' && /(?:^|\/)test-accounts$/.test(String(input.path)) && /^body\.accounts\[\d+\]\.password$/.test(at) && /^secret:[0-9a-f]{12}$/.test(text);
+    for (const [at, text] of fields) {
+        if (typeof text !== 'string' || swapped(at, text))
+            continue;
+        const hit = scan('output', `${at.replace(/\[\d+\]/g, '').split('.').pop()}: ${text}`)[0];
+        if (hit)
+            return found(hit, at);
+    }
+    return null;
+}
+/** What the model reads after an output check refused a call: why, and the way a setup carries a secret instead. */
+const SECRET_RULE = 'A secret never goes into a file, a setting, a commit, a pull request or a message, so nothing was done: take it out. Where the setup needs one, name it as a repository secret, ${{ secrets.NAME }}, and put "Add the NAME repository secret" in the report\'s left.';
+/** `scans` takes every content check's match: the debug log's, and --scan-report's file when there is one. */
+export function fenceExtension(root, log, protectedBranches, scratch, scans = scanRecorder(log)) {
     const retry = previewRetryState(log);
     return (pi) => {
         /** The first file the agent changed that the scripts and tools load, and the first of those but vite.config, which also stops the local preview check. */
@@ -1035,7 +1200,7 @@ export function fenceExtension(root, log, protectedBranches, scratch) {
             let shown;
             if (event.toolName === 'bash') {
                 shown = String(input.command ?? '');
-                decision = classifyCommand(shown, root, { protectedBranches, scriptsChanged, scratch, hosts: hostsAgreed(log), teams: teamsChosen(log) });
+                decision = classifyCommand(shown, root, { protectedBranches, scriptsChanged, scratch, hosts: hostsAgreed(log), teams: teamsChosen(log), vercelSettled: vercelFirstDeploymentSettled(log) });
                 if (decision.verdict === 'allow')
                     decision = reservePreviewCommand(retry, shown, root, scratch);
             }
@@ -1046,6 +1211,8 @@ export function fenceExtension(root, log, protectedBranches, scratch) {
             else if (['read', 'write', 'edit', 'grep', 'find', 'ls'].includes(event.toolName)) {
                 shown = `${event.toolName} ${String(input.path ?? '.')}`;
                 decision = classifyFileTool(event.toolName, input.path, root, scratch);
+                if ((event.toolName === 'write' || event.toolName === 'edit') && decision.verdict === 'allow')
+                    decision = outputCheck(event.toolName, input) ?? decision;
                 // The name written to and the file it resolves to: through a symlink, a vite.config may be another config.
                 const loaded = [String(input.path), realPath(resolve(root, String(input.path)))].filter((p) => LOADED.test(p));
                 if ((event.toolName === 'write' || event.toolName === 'edit') && decision.verdict === 'allow' && loaded.length) {
@@ -1054,12 +1221,27 @@ export function fenceExtension(root, log, protectedBranches, scratch) {
                         previewChanged ??= String(input.path);
                 }
             }
+            else if (OUTPUT_TOOLS.has(event.toolName)) {
+                const refused = outputCheck(event.toolName, input);
+                if (!refused)
+                    return undefined;
+                shown = event.toolName;
+                decision = refused;
+            }
             else {
                 return undefined;
             }
+            if (decision.hit) {
+                scans.record({ pattern: decision.hit.pattern.name, severity: decision.hit.pattern.severity, sink: decision.hit.sink, tool: event.toolName, action: 'block' });
+                // The command or the path only: never the text that matched.
+                if (event.toolName === 'bash')
+                    shown = 'bash';
+            }
             log.write(`fence ${decision.verdict} (${decision.reason})`, shown);
             if (decision.verdict === 'allow')
                 return undefined;
+            if (decision.hit?.pattern.context === 'output')
+                return { block: true, reason: `Refused: ${decision.reason}. ${SECRET_RULE}` };
             if (decision.verdict === 'never')
                 return { block: true, reason: `Blocked: ${decision.reason}. Impeccable never does this; find another way.` };
             return {
@@ -1067,5 +1249,18 @@ export function fenceExtension(root, log, protectedBranches, scratch) {
                 reason: `Refused: ${decision.reason}. The person is never asked to run a command. Find another way with what runs (a package script, a config change, another tool on the list); if there is none, leave the step undone and put it in the report under "What was skipped, and why", with the exact command for the person.`,
             };
         });
+        // What the agent reads is data: text in it shaped like instructions gets a line saying so, and the result is otherwise as it was.
+        pi.on('tool_result', (event) => {
+            if (!['read', 'grep', 'bash'].includes(event.toolName))
+                return undefined;
+            const input = event.input;
+            const sources = event.toolName === 'bash' ? (parseCommand(String(input.command ?? ''))?.flatMap((seg) => seg.words) ?? []) : [input.path, input.glob].filter((s) => typeof s === 'string');
+            const hits = scan('input', event.content.map((c) => (c.type === 'text' ? c.text : '')).join('\n'), sources);
+            if (!hits.length)
+                return undefined;
+            for (const hit of hits)
+                scans.record({ pattern: hit.name, severity: hit.severity, sink: 'the result', tool: event.toolName, action: 'tag' });
+            return { content: [{ type: 'text', text: DATA_NOTE }, ...event.content] };
+        });
     };
 }

package/dist/focus.js

@@ -6,54 +6,82 @@
  */
 /** The state items and checkup checks this setup works on. */
 const ITEMS = new Set(['scan', 'preview', 'signin']);
-/** The one lock in front of the previews this setup gets past, Vercel's, as the state's item, card and check name it. Where the lock is Vercel's they are part of the setup; for any other (Cloudflare Access) they are left alone. */
-const LOCK = { item: 'preview-protection', card: 'protection', host: 'Vercel' };
+/** The locks in front of the previews this setup gets past, Vercel's login, Netlify's password and Cloudflare Access, by the host the state's item, card and check name. Where the lock is one of theirs they are part of the setup; for any other they are left alone. */
+const LOCK = { item: 'preview-protection', card: 'protection', hosts: ['Vercel', 'Netlify', 'Cloudflare Access'] };
+/** The apps question, as the state's item and card and the write name it: part of the setup only on a repository whose scan proposed several apps, which is where the state has the item (the monorepo case). */
+const APPS = { item: 'apps', card: 'apps', write: 'apps' };
 /** The setup page's cards this setup covers, by their key in the state's `steps`: every other card is not part of it. */
 const CARDS = new Set(['installed', 'preview', 'signin', 'done']);
 /** The writes this setup makes, by their key in the instructions' `endpoints` and `writes`; `previewUrlPattern` saves the address of a host's previews that the host does not report to GitHub. */
 const WRITES = new Set(['preview', 'testAccounts', 'connectionCheck', 'latestPullCheck', 'previewUrlPattern']);
 /** What the model reads of the instructions; `steps`, `rules`, `endpoints` and `writes` are trimmed further. */
 const INSTRUCTIONS = ['product', 'goal', 'signIn', 'buildSettings', 'endpoints', 'writes', 'steps', 'rules'];
-/** A step or rule about a card this setup leaves alone: several apps, the design contract or profile, personas, review modules and settings, exclusions, preview protection (which the case reads from the state's item), preview credentials, the address pattern. */
-const OTHER_CARDS = /\bapps\b|\bprofile\b|\bcontract\b|persona|\bmodules?\b|exclu|protect|bypass|Cloudflare Access|review.settings|reviewSettings|preview-auth|previewAuth|pattern/i;
+/** The words of a step or rule about a card this setup leaves alone: the design contract or profile, personas, review modules and settings, exclusions, preview protection (which the case reads from the state's item), preview credentials, the address pattern; and several apps, except in the monorepo case. */
+const OTHER_CARD_WORDS = [String.raw `\bprofile\b`, String.raw `\bcontract\b`, 'persona', String.raw `\bmodules?\b`, 'exclu', 'protect', 'bypass', 'Cloudflare Access', 'review.settings', 'reviewSettings', 'preview-auth', 'previewAuth', 'pattern'];
+const otherCards = (apps) => new RegExp([...(apps ? [] : [String.raw `\bapps\b`]), ...OTHER_CARD_WORDS].join('|'), 'i');
 const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined);
 const only = (value, keys) => Object.fromEntries(Object.entries(value).filter(([key]) => keys.has(key)));
 const without = (value, keys) => Object.fromEntries(Object.entries(value).filter(([key]) => !keys.includes(key)));
-/** GET /api/setup/instructions, trimmed to this setup. */
-export function focusInstructions(instructions) {
+const withApps = (keys, key, apps) => (apps ? new Set([...keys, key]) : keys);
+const records = (value) => (Array.isArray(value) ? value.map(record).filter((item) => item !== undefined) : []);
+const reposOf = (answer) => records(record(answer)?.repos);
+/** A repository of the state or the checkup whose scan proposed several apps: it has the apps item, or the apps check, to answer or answered. */
+const hasApps = (repo) => Boolean(record(repo.items)?.[APPS.item]) || records(repo.checks).some((check) => check.key === APPS.item);
+/** Whether a repository in the state or the checkup has several apps. */
+export function severalApps(answer) {
+    return reposOf(answer).some(hasApps);
+}
+/**
+ * Whether the state or the checkup shows a card of this setup `not-selected` on `repo`, a repository with several apps.
+ * The command's token covers the apps there were when the person signed in, so this is an app the scan proposed later.
+ */
+export function appsLeftOut(answer, repo) {
+    const out = (status) => status === 'not-selected';
+    return reposOf(answer).some((r) => String(r.name).toLowerCase() === repo.toLowerCase() && hasApps(r)
+        && (Object.entries(record(r.items) ?? {}).some(([key, item]) => ITEMS.has(key) && (out(record(item)?.status) || records(record(item)?.perApp).some((app) => out(app.status))))
+            || records(r.checks).some((check) => ITEMS.has(String(check.key)) && out(check.state))));
+}
+/** GET /api/setup/instructions, trimmed to this setup; with `apps`, for a state with several apps, the apps write and the lines about several apps stay. */
+export function focusInstructions(instructions, { apps = false } = {}) {
     const all = record(instructions);
     if (!all)
         return instructions;
+    const writes = withApps(WRITES, APPS.write, apps);
+    const other = otherCards(apps);
     const trim = (key, value) => {
         if (key === 'endpoints' || key === 'writes')
-            return record(value) ? only(record(value), WRITES) : value;
+            return record(value) ? only(record(value), writes) : value;
         if (key === 'steps' || key === 'rules')
-            return Array.isArray(value) ? value.filter((line) => typeof line !== 'string' || !OTHER_CARDS.test(line)) : value;
+            return Array.isArray(value) ? value.filter((line) => typeof line !== 'string' || !other.test(line)) : value;
         return value;
     };
     return Object.fromEntries(INSTRUCTIONS.filter((key) => key in all).map((key) => [key, trim(key, all[key])]));
 }
-/** Whether a state item is the lock this setup gets past. */
-const vercelLock = (item) => record(item)?.host === LOCK.host;
-/** GET /api/setup/state, trimmed to this setup: each repository's scan, preview and sign-in, the lock in front of its previews when it is Vercel's, and the titles of the cards left alone. */
+/** Whether a state item is a lock this setup gets past. */
+const hostLock = (item) => LOCK.hosts.includes(String(record(item)?.host));
+/** GET /api/setup/state, trimmed to this setup: each repository's scan, preview and sign-in, its apps item where the scan proposed several apps, the lock in front of its previews when it is one this setup gets past, and the titles of the cards left alone. */
 export function focusState(state) {
     const all = record(state);
     if (!all)
         return state;
     const steps = Array.isArray(all.steps) ? all.steps.map(record) : [];
-    // The lock's card is part of the setup only when every lock the scan read is Vercel's: another host's keeps it among the cards left alone.
+    // The lock's card is part of the setup only when every lock the scan read is one this setup gets past: another host's keeps it among the cards left alone.
     const locks = Array.isArray(all.repos) ? all.repos.map((r) => record(record(r)?.items)?.[LOCK.item]).filter(Boolean) : [];
-    const vercelOnly = locks.length > 0 && locks.every(vercelLock);
-    const outside = steps.filter((step) => step && !CARDS.has(String(step.key)) && !(vercelOnly && step.key === LOCK.card) && typeof step.title === 'string').map((step) => step.title);
+    const hostsOnly = locks.length > 0 && locks.every(hostLock);
+    const apps = severalApps(all);
+    const cards = withApps(CARDS, APPS.card, apps);
+    const items = withApps(ITEMS, APPS.item, apps);
+    const writes = withApps(WRITES, APPS.write, apps);
+    const outside = steps.filter((step) => step && !cards.has(String(step.key)) && !(hostsOnly && step.key === LOCK.card) && typeof step.title === 'string').map((step) => step.title);
     const repo = (value) => {
         const r = record(value);
         if (!r)
             return value;
-        const items = record(r.items);
+        const own = record(r.items);
         return {
             ...r,
-            ...(items ? { items: Object.fromEntries(Object.entries(items).filter(([key, item]) => ITEMS.has(key) || (key === LOCK.item && vercelLock(item)))) } : {}),
-            ...(record(r.endpoints) ? { endpoints: only(record(r.endpoints), WRITES) } : {}),
+            ...(own ? { items: Object.fromEntries(Object.entries(own).filter(([key, item]) => items.has(key) || (key === LOCK.item && hostLock(item)))) } : {}),
+            ...(record(r.endpoints) ? { endpoints: only(record(r.endpoints), writes) } : {}),
         };
     };
     return {
@@ -64,9 +92,9 @@ export function focusState(state) {
 }
 /**
  * GET /api/setup/checkup, trimmed the same way: each repository's checks of the
- * scan, the preview and the sign-in, the lists with only those checks' entries,
- * and the status those lists make. Its summary and advice counted every card, so
- * they go.
+ * scan, the preview, the sign-in and the apps (a check only a repository with
+ * several apps has), the lists with only those checks' entries, and the status
+ * those lists make. Its summary and advice counted every card, so they go.
  */
 export function focusCheckup(checkup) {
     const all = record(checkup);
@@ -80,7 +108,7 @@ export function focusCheckup(checkup) {
         if (!r || !Array.isArray(r.checks))
             return value;
         // The lock's check names its host in what it says while it asks for a key; once the key is saved it says nothing of the host, and the lists no longer carry it.
-        const checks = r.checks.filter((c) => ITEMS.has(String(record(c)?.key)) || (record(c)?.key === LOCK.item && new RegExp(`\\b${LOCK.host}\\b`).test(String(record(c)?.says))));
+        const checks = r.checks.filter((c) => ITEMS.has(String(record(c)?.key)) || record(c)?.key === APPS.item || (record(c)?.key === LOCK.item && new RegExp(`\\b(${LOCK.hosts.join('|')})\\b`).test(String(record(c)?.says))));
         for (const says of checks.map((c) => record(c)?.says))
             if (typeof r.name === 'string' && typeof says === 'string' && says)
                 kept.push({ repo: r.name, says });

package/dist/host-questions.js

@@ -19,7 +19,9 @@ export const HOST_QUESTIONS = {
     },
     'netlify-team': { kind: 'single', title: 'Netlify team', prompt: 'Which Netlify team should own the new site?' },
 };
-/** The screens a tool shows on its own: a sign-in's retry, the one-time access the host's GitHub app needs, and the consent to a bypass secret for Vercel's login, with the paste when the CLI cannot make one. */
+/** Where a person reads or changes a site's password in Netlify, as Netlify's docs name the page on every plan. */
+export const NETLIFY_PASSWORD_WHERE = 'Project configuration → General → Visitor access';
+/** The screens a tool shows on its own: a sign-in's retry, the one-time access the host's GitHub app needs, and the consent to a key for a host's lock (a bypass secret for Vercel's login, the site password for Netlify's, a service token for Cloudflare Access), with the paste where the run does not get one. */
 export const HOST_SCREENS = {
     'netlify-signin-retry': { id: 'netlify-signin-retry', kind: 'confirm', title: 'Sign in to Netlify', prompt: 'The sign-in did not complete.', confirmLabel: 'Try again', skipLabel: 'Skip' },
     'netlify-access': {
@@ -61,6 +63,49 @@ export const HOST_SCREENS = {
         prompt: 'Vercel keeps your previews behind a login, and the Vercel CLI here could not make a bypass secret for them: that takes your Vercel sign-in, this folder linked to the project, and the Member role. Make one yourself: your project → Settings → Deployment Protection → Protection Bypass for Automation → Create, named "Impeccable reviews". It is stored encrypted and used only to open previews.',
         hint: 'Paste the secret',
     },
+    // Netlify's site password in front of the previews: the one consent to storing the password the run reads from the site as the person, and the paste when it cannot read it.
+    'netlify-password': {
+        id: 'netlify-password',
+        kind: 'confirm',
+        title: 'Your Netlify previews are protected',
+        hint: `Impeccable reviews each pull request on its preview, and Netlify keeps yours behind the site password. The run reads that password from your site as you and stores it encrypted, used only to open previews. Change it any time in ${NETLIFY_PASSWORD_WHERE}.`,
+        prompt: 'Store the site password for Impeccable?',
+        confirmLabel: 'Store',
+        skipLabel: 'Skip',
+    },
+    'netlify-password-key': {
+        id: 'netlify-password-key',
+        kind: 'text',
+        sensitive: true,
+        title: 'Your Netlify previews are protected',
+        prompt: `Netlify keeps your previews behind the site password, and the run could not read it: the Netlify CLI here is signed out, the site is in none of your teams, or Netlify does not give the password back. Find it, or set a new one, in ${NETLIFY_PASSWORD_WHERE}. It is stored encrypted and used only to open previews.`,
+        hint: 'Paste the password',
+    },
+    // Cloudflare Access in front of the previews: the one consent to a service token the run creates as the person, the API token that takes (wrangler's sign-in cannot reach Access), and the paste where the run does not create one.
+    'cloudflare-access': {
+        id: 'cloudflare-access',
+        kind: 'confirm',
+        title: 'Your Cloudflare previews are protected',
+        hint: 'Impeccable reviews each pull request on its preview, and Cloudflare Access keeps yours behind a login. Cloudflare\'s way in for tools is a service token made for one tool: the run creates one named "Impeccable reviews" and allows it in your Access application\'s policy. It is stored encrypted, used only to open previews, and you can revoke it any time in Zero Trust → Access controls → Service credentials.',
+        prompt: 'Create the token for Impeccable?',
+        confirmLabel: 'Create',
+        skipLabel: 'Skip',
+    },
+    'cloudflare-access-api': {
+        id: 'cloudflare-access-api',
+        kind: 'text',
+        sensitive: true,
+        title: 'One Cloudflare API token',
+        prompt: 'Creating the token takes a Cloudflare API token, used for this run only and stored nowhere. Make one at dash.cloudflare.com/profile/api-tokens → Create Token → Create Custom Token, with two permissions: Access: Apps and Policies → Edit, and Access: Service Tokens → Edit.',
+        hint: 'Paste the API token',
+    },
+    'cloudflare-access-key': {
+        id: 'cloudflare-access-key',
+        kind: 'account',
+        fields: ['Client ID', 'Client secret'],
+        title: 'Your Cloudflare previews are protected',
+        prompt: 'Cloudflare Access keeps your previews behind a login. Paste a service token for Impeccable, or make one: Zero Trust → Access controls → Service credentials → Service Tokens → Create Service Token, named "Impeccable reviews", then allow it in your Access application with a Service Auth policy. It is stored encrypted and used only to open previews.',
+    },
 };
 /** The ids whose screens the tool puts up itself, when it needs the person, and takes down: the web page follows those, not the model's call. */
 export const TOOL_SHOWN = new Set(['netlify-setup', 'vercel-setup']);