@impeccable/reviews 0.1.0

package/dist/playbook/cases/workflow-as-person.md

@@ -0,0 +1,23 @@
+### When this applies
+
+The setup commit carries the workflow the state offers in the preview item's `file` (`.github/workflows/impeccable-preview.yml`), committed from the person's own checkout and GitHub account.
+
+### Steps
+
+1. **Check access** with impeccable_workflow_access, before branching the setup branch from the `origin/<defaultBranch>` it refreshes. Done when `base.status` is "refreshed" and `originMatches` is true.
+   - **`needsWorkflowScope` is true**: ask through impeccable_ask whether the person has turned on workflow access for their GitHub account (title "Workflow access"), then check again.
+   - **`workflowScope` is unknown** (a fine-grained token, SSH): go on; the push shows whether access is there.
+2. **Sync the workflow** on the setup branch, once the settings are saved: impeccable_sync_workflow writes the state's file byte for byte and removes the retired file the state names. Done when it answers `ok: true`.
+   - **`workflowStanding` is current**: nothing to write; leave the file as it is.
+   - **absent, out-of-date, older-generation or retired**: the tool writes the fresh file.
+   - **unknown**: the current workflow could not be read. Leave the file as it is and sync nothing: the step is done, and the workflow goes under "What is not verified".
+   - **Refused for local edits**: nothing changed. Keep the person's edits, ask them through impeccable_ask to resolve the conflict, then sync again.
+3. **Commit** only the setup files: the workflow, the retired file's removal, a build fix. Then call impeccable_sync_workflow again. Done when `stagedMatches` and `committedMatches` are true, and `retiredRemoval.staged` and `retiredRemoval.committed` too when it names a retired file; null means nothing was compared.
+
+### Reference
+
+- **Never write or edit the workflow file yourself**: the state's bytes are the workflow, and impeccable_sync_workflow writes them. After any later change to the settings, sync again on the same pull request.
+- The workflow uses GitHub's OIDC identity, so it needs no repository secret of its own.
+- **The team's own workflow already deploys previews**: ask which should supply them (a single choice) before adding this one.
+- **A default branch other than main**: target it all the same, and say under "What is not verified" that the workflow's push trigger names main, so merging does not build the default branch's preview.
+- The report names two limits: pull requests from forks get no preview, and neither do pull requests into a branch without the workflow, unless they carry it, as the setup pull request and the test drive do.

package/dist/playbook/github-previews.js

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

package/dist/playbook/netlify-pattern.js

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

package/dist/playbook/netlify-previews.js

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

package/dist/playbook/probe-preview.js

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

package/dist/playbook/protection-secrets.js

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

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

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

package/dist/playbook/publication-wait.js

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

package/dist/playbook/vercel-protection.js

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