@impeccable/reviews 0.1.0

package/dist/focus.js

@@ -0,0 +1,98 @@
+/**
+ * The setup covers one situation: a web front end previewed by the host that
+ * already deploys its pull requests or by Impeccable itself, with at most the
+ * app's own sign-in. These trim what the setup API says to that situation
+ * before the model reads it, so the setup page's other cards never reach the run.
+ */
+/** 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 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;
+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 all = record(instructions);
+    if (!all)
+        return instructions;
+    const trim = (key, value) => {
+        if (key === 'endpoints' || key === 'writes')
+            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 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. */
+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.
+    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 repo = (value) => {
+        const r = record(value);
+        if (!r)
+            return value;
+        const items = 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) } : {}),
+        };
+    };
+    return {
+        ...without(all, ['summary', 'steps']),
+        ...(outside.length ? { notPartOfThisSetup: outside } : {}),
+        ...(Array.isArray(all.repos) ? { repos: all.repos.map(repo) } : {}),
+    };
+}
+/**
+ * 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.
+ */
+export function focusCheckup(checkup) {
+    const all = record(checkup);
+    if (!all || !Array.isArray(all.repos))
+        return checkup;
+    // The lists carry no check key, so an entry stays only when it begins with a kept check's words: "<repository>: <what it says>…",
+    // or "<repository> (<app>): …". Anything else goes, however the other cards word it.
+    const kept = [];
+    const repos = all.repos.map((value) => {
+        const r = record(value);
+        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))));
+        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 });
+        return { ...r, checks };
+    });
+    const begins = (entry, { repo, says }) => entry.startsWith(`${repo}: ${says}`) || (entry.startsWith(`${repo} (`) && entry.startsWith(`): ${says}`, entry.indexOf('): ')));
+    const lists = ['next', 'forPerson', 'waitingFor'].map((key) => {
+        const list = all[key];
+        return Array.isArray(list) ? list.filter((entry) => typeof entry === 'string' && kept.some((check) => begins(entry, check))) : list;
+    });
+    const [next, forPerson, waitingFor] = lists;
+    const status = !lists.every(Array.isArray) ? all.status
+        : next.length || forPerson.length ? 'incomplete' : waitingFor.length ? 'waiting' : 'complete';
+    return { ...without(all, ['summary', 'runAgain']), status, repos, next, forPerson, waitingFor };
+}

package/dist/host-questions.js

@@ -0,0 +1,71 @@
+/** The ids the model may name, each worded here whatever else it writes for that id. */
+export const HOST_QUESTIONS = {
+    'vercel-setup': {
+        kind: 'confirm',
+        title: 'Vercel, but no previews yet',
+        hint: 'Impeccable reviews each pull request on a preview. Vercel can host those previews: the run sets it up. It needs your Vercel sign-in; what is live stays as it is.',
+        prompt: 'Sign in to Vercel in your browser?',
+        confirmLabel: 'Sign in',
+        skipLabel: 'Skip',
+    },
+    'vercel-team': { kind: 'single', title: 'Vercel team', prompt: 'Which Vercel team should own the new project?' },
+    'netlify-setup': {
+        kind: 'confirm',
+        title: 'Netlify, but no previews yet',
+        hint: 'Impeccable reviews each pull request on a preview. Netlify can host those previews: the run sets it up. It needs your Netlify sign-in; what is live stays as it is.',
+        prompt: 'Sign in to Netlify in your browser?',
+        confirmLabel: 'Sign in',
+        skipLabel: 'Skip',
+    },
+    '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. */
+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': {
+        id: 'netlify-access',
+        kind: 'confirm',
+        title: 'Netlify needs access on GitHub',
+        hint: "Netlify's GitHub app can't see this repository yet. Give it access on the GitHub page that opens. The run carries on by itself once it can.",
+        prompt: 'Open GitHub to give Netlify access?',
+        confirmLabel: 'Open GitHub',
+        skipLabel: 'Skip',
+    },
+    'netlify-access-retry': { id: 'netlify-access-retry', kind: 'confirm', title: 'Netlify needs access on GitHub', prompt: "Netlify still can't see the repository.", confirmLabel: 'Try again', skipLabel: 'Skip' },
+    'vercel-signin-retry': { id: 'vercel-signin-retry', kind: 'confirm', title: 'Sign in to Vercel', prompt: 'The sign-in did not complete.', confirmLabel: 'Try again', skipLabel: 'Skip' },
+    'vercel-access': {
+        id: 'vercel-access',
+        kind: 'confirm',
+        title: 'Vercel needs access on GitHub',
+        hint: "Vercel's GitHub app can't see this repository yet. Give it access on the GitHub page that opens. The run carries on by itself once it can.",
+        prompt: 'Open GitHub to give Vercel access?',
+        confirmLabel: 'Open GitHub',
+        skipLabel: 'Skip',
+    },
+    'vercel-access-retry': { id: 'vercel-access-retry', kind: 'confirm', title: 'Vercel needs access on GitHub', prompt: "Vercel still can't see the repository.", confirmLabel: 'Try again', skipLabel: 'Skip' },
+    // Vercel's login in front of the previews: the one consent to a bypass secret the run creates as the person, and the paste when the CLI cannot.
+    'vercel-bypass': {
+        id: 'vercel-bypass',
+        kind: 'confirm',
+        title: 'Your Vercel previews are protected',
+        hint: 'Impeccable reviews each pull request on its preview, and Vercel keeps yours behind a login. Vercel\'s way in for tools is a bypass secret made for one tool: the run creates one in your project, named "Impeccable reviews". It is stored encrypted, used only to open previews, and you can revoke it any time in Settings → Deployment Protection.',
+        prompt: 'Create the secret for Impeccable?',
+        confirmLabel: 'Create',
+        skipLabel: 'Skip',
+    },
+    'vercel-bypass-key': {
+        id: 'vercel-bypass-key',
+        kind: 'text',
+        sensitive: true,
+        title: 'Your Vercel previews are protected',
+        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',
+    },
+};
+/** 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']);
+/** A question as the person reads it: the fixed words for a host's id, else the model's own. */
+export function hostQuestion(q) {
+    const fixed = Object.hasOwn(HOST_QUESTIONS, q.id) ? HOST_QUESTIONS[q.id] : undefined;
+    return fixed ? { id: q.id, prompt: fixed.prompt } : q;
+}

package/dist/hosted.js

@@ -0,0 +1,195 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { BYPASS_HEADER } from './vercel-bypass.js';
+/**
+ * Previews a host already deploys: what GitHub has on record of the
+ * repository's deployments (Vercel; Netlify's previews are read in netlify.ts),
+ * and the proof that a preview address, Vercel's or Netlify's, answers with
+ * this app. Neither changes anything on the host, and neither hands back more
+ * than the fields below: no response body, header or other GitHub field.
+ */
+const execFileAsync = promisify(execFile);
+/** How many deployments, and how many pull requests, the evidence reads: the newest. */
+const LIMIT = 20;
+const STATES = ['error', 'failure', 'inactive', 'in_progress', 'queued', 'pending', 'success'];
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined);
+const positive = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+/** An https address without credentials, a query or a fragment, as origin and path; null for anything else. */
+function address(value) {
+    if (typeof value !== 'string' || value.length > 2048 || !/^https:\/\/[^\s\\?#@]+$/.test(value) || !URL.canParse(value))
+        return null;
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`.replace(/\/$/, '');
+}
+/** A branch name GitHub can be asked about: the characters git allows, no `..`, and neither a slash nor a dot at the end. */
+const branchName = (value) => /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(value) && !value.includes('..') && !value.endsWith('/') && !value.endsWith('.');
+/**
+ * GitHub's record of this repository's deployments: the newest, each with its latest status and the pull requests whose
+ * commit it built; or, with `branch`, that branch's head's only, so a pushed branch's deployment is found before any
+ * pull request exists.
+ */
+export async function readHostedPreviews(owner, repo, deps = {}) {
+    const unread = { deployments: [], error: "GitHub's deployments could not be read." };
+    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 unread;
+    if (deps.branch !== undefined && !branchName(deps.branch))
+        return unread;
+    const runGh = deps.runGh ?? (async (args) => (await execFileAsync('gh', args, {
+        encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024, signal: deps.signal, env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+    })).stdout);
+    const list = async (route) => {
+        const data = JSON.parse(await runGh(['api', '--hostname', 'github.com', '--method', 'GET', route]));
+        if (!Array.isArray(data))
+            throw new Error(`${route} is not a list`);
+        return data.slice(0, LIMIT);
+    };
+    const base = `/repos/${owner}/${repo}`;
+    try {
+        // A branch's head, as GitHub has it after the push.
+        const ref = deps.branch !== undefined ? record(JSON.parse(await runGh(['api', '--hostname', 'github.com', '--method', 'GET', `${base}/branches/${encodeURIComponent(deps.branch)}`]))) : undefined;
+        const head = record(ref?.commit)?.sha;
+        if (deps.branch !== undefined && (ref?.name !== deps.branch || typeof head !== 'string' || !/^[0-9a-f]{40}$/.test(head)))
+            return unread;
+        const [deployments, pulls] = await Promise.all([
+            list(`${base}/deployments?${head ? `sha=${head}&` : ''}per_page=${LIMIT}`),
+            deps.branch !== undefined ? [] : list(`${base}/pulls?state=all&sort=updated&direction=desc&per_page=${LIMIT}`),
+        ]);
+        const heads = pulls.map(record).flatMap((pull) => (pull && positive(pull.number) ? [{ number: pull.number, sha: record(pull.head)?.sha }] : []));
+        const numbers = (found) => found.map(record).flatMap((pull) => (pull && positive(pull.number) ? [pull.number] : []));
+        let unsaid = false;
+        const read = await Promise.all(deployments.map(record).map(async (d) => {
+            if (!d || !positive(d.id) || typeof d.sha !== 'string' || !/^[0-9a-f]{40}$/.test(d.sha))
+                return null;
+            // GitHub lists a deployment's statuses newest first.
+            const latest = record((await list(`${base}/deployments/${d.id}/statuses?per_page=1`))[0]);
+            const state = STATES.find((s) => s === latest?.state) ?? null;
+            const environment = typeof d.environment === 'string' && d.environment.length <= 100 && !/[\x00-\x1f\x7f]/.test(d.environment) ? d.environment : null;
+            const url = state ? address(latest?.environment_url) : null;
+            let pullRequests = heads.filter((pull) => pull.sha === d.sha).map((pull) => pull.number);
+            // A pull request whose head moved on since, or that was updated before the 20 read, still names the commit. When GitHub cannot say, this one stays unlinked and the evidence says so. A branch's head is asked for by its branch, before its pull request exists, so none is looked for.
+            if (!pullRequests.length && state === 'success' && url && deps.branch === undefined)
+                pullRequests = numbers(await list(`${base}/commits/${d.sha}/pulls`).catch(() => ((unsaid = true), [])));
+            return { sha: d.sha, environment, state, url, vercel: record(d.creator)?.login === 'vercel[bot]', pullRequests };
+        }));
+        return { deployments: read.filter((d) => d !== null), ...(unsaid ? { error: 'GitHub could not say which pull requests some previews belong to: read again.' } : {}) };
+    }
+    catch {
+        return unread;
+    }
+}
+const HOSTS = {
+    vercel: { name: 'Vercel', gate: 'vercel-protection', login: /(^|\.)vercel\.com$/ },
+    netlify: { name: 'Netlify', gate: 'netlify-protection', login: /(^|\.)netlify\.com$/ },
+};
+const NETLIFY = /^(?=[^.]{1,63}\.netlify\.app$)deploy-preview-[1-9]\d{0,6}--([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.netlify\.app$/;
+/** A deployment's own address: https on one name, and nothing else. Vercel's is one name under vercel.app, Netlify's a pull request's deploy preview. */
+const hostOf = (url) => {
+    if (url.protocol !== 'https:' || url.username || url.password || url.port || url.search || url.hash)
+        return null;
+    return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.vercel\.app$/.test(url.hostname) ? 'vercel' : NETLIFY.test(url.hostname) ? 'netlify' : null;
+};
+/** The host a preview address belongs to, by name; null for an address of neither. */
+export function previewHostName(url) {
+    const host = URL.canParse(url) ? hostOf(new URL(url)) : null;
+    return host ? HOSTS[host].name : null;
+}
+const ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', lsquo: '‘', rsquo: '’', ldquo: '“', rdquo: '”',
+    hellip: '…', middot: '·', bull: '•', laquo: '«', raquo: '»', copy: '©', reg: '®', trade: '™', times: '×',
+};
+/** Text as a reader meets it: entities decoded, case and runs of space ignored. */
+function plain(text) {
+    return text.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]+);/gi, (whole, name) => {
+        const code = name[0] !== '#' ? NaN : /^#x/i.test(name) ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1));
+        return name[0] !== '#' ? (ENTITIES[name.toLowerCase()] ?? whole) : code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+    }).replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/** Whether a file the checkout tracks holds the words; .env files are never read. */
+async function inCheckout(root, words) {
+    try {
+        await execFileAsync('git', ['grep', '--quiet', '--fixed-strings', '--ignore-case', '-e', words, '--', '.', ':(exclude,glob)**/.env*'], { cwd: root, timeout: 30_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The words a visitor sees: the title and the text, without comments, scripts, styles, tags or attributes. */
+const visible = (html) => plain(html.replace(/<!--[\s\S]*?-->|<(script|style|noscript|template)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, ' ').replace(/<[^>]*>/g, ' '));
+/** The first `max` bytes of a page, as text. */
+async function pageText(res, max = 1_000_000) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return '';
+    const chunks = [];
+    try {
+        for (let size = 0; size < max;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Opens a preview address the way a visitor does, signed in nowhere, and proves it: it answers, and its page shows
+ * `words` that a file of the checkout at `root` holds, so the page is this app's and not another site's. With `bypass`, a
+ * Vercel bypass secret, a Vercel address is opened with it in the header Vercel reads it from, as reviews do; no other host's is.
+ */
+export async function provePreview(url, words, root, deps = {}) {
+    const unproven = (reason, status = null) => ({ proven: false, status, reason });
+    const host = URL.canParse(url) ? hostOf(new URL(url)) : null;
+    if (!host)
+        return unproven('Only a Vercel preview address, https://<name>.vercel.app, or a Netlify deploy preview, https://deploy-preview-<n>--<name>.netlify.app, with no query, is opened.');
+    const { name, gate, login } = HOSTS[host];
+    const phrase = words.trim();
+    if (phrase.length < 3 || phrase.length > 120 || /[\r\n]/.test(phrase))
+        return unproven('The words are 3 to 120 characters on one line.');
+    if (!(await inCheckout(root, phrase)))
+        return unproven("No file of this checkout holds those words: give words the app's pages show, from its source.");
+    const signal = AbortSignal.any([AbortSignal.timeout(15_000), ...(deps.signal ? [deps.signal] : [])]);
+    const opened = deps.bypass && host === 'vercel';
+    const headers = { accept: 'text/html', ...(opened ? { [BYPASS_HEADER]: deps.bypass } : {}) };
+    // Where the login stands in front all the same, the bypass secret did not get past it.
+    const still = opened ? ' even with the bypass secret' : '';
+    let target = new URL(url);
+    try {
+        for (let hop = 0; hop < 4; hop++) {
+            const res = await (deps.fetch ?? fetch)(target, { redirect: 'manual', headers, credentials: 'omit', signal });
+            if (res.status >= 300 && res.status < 400) {
+                await res.body?.cancel().catch(() => { });
+                const location = res.headers.get('location') ?? '';
+                const next = URL.canParse(location, target.href) ? new URL(location, target) : null;
+                if (next && login.test(next.hostname))
+                    return { ...unproven(`The address sent the browser to ${name}'s login${still}.`, res.status), gate };
+                if (next?.origin !== target.origin)
+                    return unproven('The address sent the browser to another site.', res.status);
+                target = next;
+                continue;
+            }
+            if (res.status === 401 || (host === 'netlify' && res.status === 403)) {
+                // Vercel's own page names Vercel; any other 401 there is the app's own sign-in, which a page a visitor opens without signing in gets past.
+                // A password or a login in front of a Netlify preview answers 401 or 403 on every page of it, and its page names nothing to go by.
+                const page = await pageText(res, 64_000);
+                return host === 'netlify' || /vercel/i.test(page) ? { ...unproven(`The address asked for ${name}'s login or password${still}.`, res.status), gate }
+                    : unproven("The address asked for the app's own sign-in: try a page a visitor opens without signing in.", 401);
+            }
+            if (res.status < 200 || res.status >= 300) {
+                await res.body?.cancel().catch(() => { });
+                return unproven(`The address answered ${res.status}.`, res.status);
+            }
+            return visible(await pageText(res)).includes(plain(phrase))
+                ? { proven: true, status: res.status, ...(host === 'netlify' ? { pattern: `https://deploy-preview-{pr}--${NETLIFY.exec(new URL(url).hostname)[1]}.netlify.app` } : {}) }
+                : unproven('The page does not show those words: it is another app, or another page.', res.status);
+        }
+        return unproven('The address redirected too many times.');
+    }
+    catch {
+        return unproven('The address did not answer.');
+    }
+}

package/dist/http.js

@@ -0,0 +1,36 @@
+/** One JSON request. Never throws: a failure comes back as `ok: false` with a short `error`. */
+export async function requestJson(url, init, log) {
+    const method = init.method ?? 'GET';
+    const started = Date.now();
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: {
+                accept: 'application/json',
+                ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+                ...(init.token ? { authorization: `Bearer ${init.token}` } : {}),
+            },
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            signal: AbortSignal.timeout(init.timeoutMs ?? 60_000),
+        });
+        const text = await res.text();
+        let data = text;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Not JSON: keep the text.
+        }
+        log?.write(`${method} ${url} -> ${res.status} in ${Date.now() - started} ms`);
+        if (res.ok)
+            return { ok: true, status: res.status, data };
+        const said = data && typeof data === 'object' ? data.error : undefined;
+        const error = typeof said === 'string' ? said : typeof data === 'string' && data ? data.slice(0, 200) : res.statusText || `HTTP ${res.status}`;
+        return { ok: false, status: res.status, data, error };
+    }
+    catch (err) {
+        const error = err instanceof Error ? (err.name === 'TimeoutError' ? 'the request timed out' : err.message) : String(err);
+        log?.write(`${method} ${url} failed: ${error}`);
+        return { ok: false, status: 0, data: null, error };
+    }
+}

package/dist/log.js

@@ -0,0 +1,38 @@
+import { appendFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** An error whose message is written for the person at the terminal. */
+export class UserError extends Error {
+}
+const TOKEN = /\b(pst|phr)_[A-Za-z0-9._~+/=-]+/g;
+const NAMES = 'access_token|run_token|code_verifier|code|authorization|x-api-key';
+const FIELD = new RegExp(`("?(?:${NAMES})"?\\s*[:=]\\s*"?)(?:Bearer\\s+)?[^"&\\s,}]+`, 'gi');
+/** A field whose value is a credential, such as an authorization header. */
+export const SECRET_FIELD = new RegExp(`^(?:${NAMES})$`, 'i');
+export function redact(text, secrets = []) {
+    let out = text;
+    for (const secret of secrets)
+        if (secret)
+            out = out.split(secret).join('[redacted]');
+    return out.replace(TOKEN, '$1_[redacted]').replace(FIELD, '$1[redacted]');
+}
+export function createLog(debug, dir = tmpdir()) {
+    const secrets = new Set();
+    const secret = (value) => void secrets.add(value);
+    if (!debug)
+        return { secret, write: () => { } };
+    const path = join(dir, `impeccable-reviews-${new Date().toISOString().replace(/[:.]/g, '-')}.log`);
+    return {
+        path,
+        secret,
+        write(message, data) {
+            const detail = data === undefined ? '' : ` ${typeof data === 'string' ? data : JSON.stringify(data)}`;
+            try {
+                appendFileSync(path, `${redact(`${new Date().toISOString()} ${message}${detail}`, secrets)}\n`, { mode: 0o600 });
+            }
+            catch {
+                // A debug log that cannot be written is not worth stopping the run for.
+            }
+        },
+    };
+}