@agent-flow-board/bridge 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @agent-flow-board/bridge
 
-The local bridge to an [Agent Flow Board](https://afb.arbenger.com) server. It forwards the board's MCP over stdio, runs the hooks of your coding tool (Claude Code, Antigravity, Gemini CLI) so the board stays true, and writes the status file that the editor status line reads. It holds no tool code: every tool lives on the server.
+The local bridge to an [Agent Flow Board](https://afb.arbenger.com) server. It forwards the board's MCP over stdio, runs the hooks of your coding tool (Claude Code, Antigravity, Gemini CLI) so the board stays true, and writes the status file that the editor status line reads. It holds no board tool code: every MCP tool lives on the server. It also runs browser checks on this machine (see Browser checks below).
 
 ## Install
 
@@ -22,6 +22,18 @@ Needs Node 20 or later. Run it with no arguments to see its usage; the list shou
 | `agent-flow-board mcp --server <url> --org <slug>`                | Forwards MCP over stdio, for tools that only speak stdio.                                                                                                                                                  |
 | `agent-flow-board queue list`                                     | Shows writes held while the board could not be reached.                                                                                                                                                    |
 
+### Browser checks
+
+| Command                                                                             | What it does                                                                                                                                                                                 |
+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-flow-board check connect --server <url> --org <slug> --json`                 | Makes this machine a check runner of the organisation. An agent approves the printed code with the board's MCP. Only the runner token is kept.                                               |
+| `agent-flow-board check run <item> <key> --server <url> --org <slug> [--step 1.2]`  | Asks for the run, claims that run only, builds a private copy of the repo in the current folder, previews it, runs the check in a sandbox and reports. Exit 0 pass, 1 fail, 2 could not run. |
+| `agent-flow-board check pull <item> <key> --server <url> --org <slug>`              | Shows the board's copy of a check script as data. `--accept-hash <sha256>` writes exactly that text.                                                                                         |
+| `agent-flow-board check watch [--parallel N] [--once]`                              | Takes runs started from the board's Run button, for folders where `check run` was used before.                                                                                               |
+| `agent-flow-board check status`, `check doctor --fix`, `check clear`, `check setup` | Reads and repairs the state, removes old runs, installs the browser. All take `--json`.                                                                                                      |
+
+Check scripts and run state live in `~/.agent-flow-board/checks/`, never in a repo. Playwright is not installed with the bridge: the first run installs it there.
+
 The easy way to set everything up is the **Editor status** tab on the board's **Connect a tool** page: copy its prompt into Claude Code and the agent does the steps, asking you once before it writes anything.
 
 ## What it writes

package/dist/checks/audit.js

@@ -0,0 +1,125 @@
+// A HASH-CHAINED AUDIT LOG OF WHAT THE CHECK COMMANDS DID. Each line carries the MAC of the line before it (HMAC-SHA256 with a key that only this machine has),
+// so an edited line or a cut shows. It is evidence, not prevention. Only short action words and plain numbers are logged: never a token, a password, a secret's
+// path or a command text.
+// -- DEP-MODULES -- //
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { appendFileSync, existsSync, linkSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { withLockSync } from './lock.js';
+import { auditFile, checksHome, ensureDir } from './paths.js';
+// -- CONSTANTS -- //
+const MAX_ACTION = 40;
+const MAX_VALUE = 200;
+// -- FUNCTIONS -- //
+const keyFile = () => join(checksHome(), 'audit.key');
+/** The head file keeps the MAC and the count of the last line, which is what shows a cut tail (the chain of the lines left is still true). */
+const headFile = () => `${auditFile()}.head`;
+/** The key, created once with mode 0600. It is written whole into a temporary file and linked into place, so another process never reads half of it. */
+function homeKey() {
+    ensureDir(checksHome());
+    const file = keyFile();
+    if (!existsSync(file)) {
+        const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+        writeFileSync(tmp, randomBytes(32).toString('hex'), { mode: 0o600, flag: 'wx' });
+        try {
+            linkSync(tmp, file);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    }
+    return Buffer.from(readFileSync(file, 'utf8').trim(), 'hex');
+}
+const lineMac = (key, prev, text) => createHmac('sha256', Buffer.concat([Buffer.from('afb check audit:'), key]))
+    .update(`${prev}\n${text}`)
+    .digest('hex');
+const readLines = () => existsSync(auditFile()) ? readFileSync(auditFile(), 'utf8').split(/\r?\n/).filter(Boolean) : [];
+function tail(lines) {
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const e = JSON.parse(lines[i] ?? '');
+            if (e && typeof e === 'object' && typeof e.mac === 'string')
+                return e.mac;
+        }
+        catch {
+            /* A damaged line is skipped, and verifyAudit reports it */
+        }
+    }
+    return '';
+}
+function clean(detail) {
+    const out = {};
+    for (const [k, v] of Object.entries(detail)) {
+        const name = k.replace(/[^A-Za-z0-9_]/g, '').slice(0, 40);
+        if (name)
+            out[name] = typeof v === 'string' ? v.slice(0, MAX_VALUE) : v;
+    }
+    return out;
+}
+/** Adds one line to the chain. Reading the last line and appending the next one is one step under a lock, so two writers never fork the chain. */
+export function appendAudit(action, detail = {}) {
+    const key = homeKey();
+    const word = action.replace(/[^A-Za-z0-9 _.:-]/g, '').slice(0, MAX_ACTION) || 'action';
+    withLockSync('audit', () => {
+        const lines = readLines();
+        const prev = tail(lines);
+        const text = JSON.stringify({
+            at: new Date().toISOString(),
+            action: word,
+            detail: clean(detail),
+            prev
+        });
+        const mac = lineMac(key, prev, text);
+        appendFileSync(auditFile(), JSON.stringify({ ...JSON.parse(text), mac }) + '\n', {
+            mode: 0o600
+        });
+        const head = { lines: lines.length + 1, head: mac };
+        const tmp = `${headFile()}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(head), { mode: 0o600 });
+        renameSync(tmp, headFile());
+    });
+}
+function readHead() {
+    try {
+        const v = JSON.parse(readFileSync(headFile(), 'utf8'));
+        return typeof v.lines === 'number' && typeof v.head === 'string'
+            ? { lines: v.lines, head: v.head }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+const same = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/** True when every line holds the MAC of the line before it and the last line is the one the head file names (a cut tail shows there). */
+export function verifyAudit() {
+    const lines = readLines();
+    const head = readHead();
+    if (!lines.length)
+        return { ok: head === null || head.lines === 0, lines: 0, head: '' };
+    const key = homeKey();
+    let prev = '';
+    for (let i = 0; i < lines.length; i++) {
+        let e;
+        try {
+            e = JSON.parse(lines[i] ?? '');
+        }
+        catch {
+            return { ok: false, lines: lines.length, head: prev };
+        }
+        const { mac, ...rest } = e;
+        if (typeof mac !== 'string' || e.prev !== prev)
+            return { ok: false, lines: lines.length, head: prev };
+        if (!same(lineMac(key, prev, JSON.stringify(rest)), mac))
+            return { ok: false, lines: lines.length, head: prev };
+        prev = mac;
+    }
+    // A cut tail, or a line added by hand after the last one, is not what the head file recorded
+    const matches = head !== null && head.lines === lines.length && head.head === prev;
+    return { ok: matches, lines: lines.length, head: prev };
+}

package/dist/checks/bind.js

@@ -0,0 +1,99 @@
+// THE FOLDER BINDING OF `check watch`: WHICH REAL FOLDER BUILDS THE PROJECT <org>/<KEY>, AND THE PIN OF THE FILES THAT DECIDED WHAT RUNS.
+// When the pin changes (a new script, a changed recipe, a new lockfile) the watcher stops and tells the person to run `check run` in that
+// folder, which looks at the new setup and pins it again. Nothing in the repo can re-pin by itself.
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// -- MODULES -- //
+import { bindingsFile, ensureDir, ORG_SLUG } from './paths.js';
+import { checkRepoFolder } from './guardrails.js';
+import { pinFiles } from './recipe.js';
+// -- CONSTANTS -- //
+const PROJECT_KEY = /^[A-Z][A-Z0-9]{1,9}$/;
+// -- FUNCTIONS -- //
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function idOf(org, projectKey) {
+    if (!ORG_SLUG.test(org))
+        throw new Error('The organisation is not a slug.');
+    if (!PROJECT_KEY.test(projectKey))
+        throw new Error('The project key must be 2 to 10 capital letters or digits, starting with a letter.');
+    return `${org}/${projectKey}`;
+}
+function readAll() {
+    const file = bindingsFile();
+    if (!existsSync(file))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON. Fix or remove it.`);
+    }
+    const out = {};
+    if (isRecord(parsed) && isRecord(parsed.bindings))
+        for (const [id, v] of Object.entries(parsed.bindings))
+            if (isRecord(v) && typeof v.folder === 'string' && typeof v.pin === 'string')
+                out[id] = { folder: v.folder, pin: v.pin };
+    return out;
+}
+/** Writes a temp file in the same folder, then renames it over the real one, so a reader never sees half a file. */
+function writeAll(bindings) {
+    const file = bindingsFile();
+    ensureDir(dirname(file));
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify({ version: 1, bindings }, null, 2) + '\n', { mode: 0o600 });
+        renameSync(temp, file);
+    }
+    catch (e) {
+        rmSync(temp, { force: true });
+        throw e;
+    }
+}
+/** Binds a project to a folder. Refuses a folder the guardrails refuse. Stores the real path and the given pin. */
+export function bindFolder(org, projectKey, folder, pin) {
+    const id = idOf(org, projectKey);
+    const problem = checkRepoFolder(folder);
+    if (problem)
+        throw new Error(problem);
+    const all = readAll();
+    all[id] = { folder: realpathSync.native(folder), pin };
+    writeAll(all);
+}
+/** The folder and pin of a project, or null when it has none. */
+export function boundFolder(org, projectKey) {
+    const found = readAll()[idOf(org, projectKey)];
+    return found ? { folder: found.folder, pin: found.pin } : null;
+}
+/** Every binding, sorted by org and key. */
+export function listBindings() {
+    return Object.entries(readAll())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([id, v]) => {
+        const [org = '', projectKey = ''] = id.split('/');
+        return { org, projectKey, folder: v.folder, pin: v.pin };
+    });
+}
+/** Removes a binding. True when there was one. */
+export function unbind(org, projectKey) {
+    const id = idOf(org, projectKey);
+    const all = readAll();
+    if (!(id in all))
+        return false;
+    delete all[id];
+    writeAll(all);
+    return true;
+}
+/**
+ * Whether the files that decide what runs are still the ones the person approved. `changed` also covers a folder that is gone or no longer
+ * allowed: the caller tells the person to run `check run` in that folder, which looks again and re-pins.
+ */
+export function pinStatus(org, projectKey) {
+    const found = boundFolder(org, projectKey);
+    if (!found)
+        return 'unbound';
+    if (checkRepoFolder(found.folder))
+        return 'changed';
+    return pinFiles(join(found.folder)) === found.pin ? 'ok' : 'changed';
+}

package/dist/checks/board.js

@@ -0,0 +1,107 @@
+// THE BOARD, SEEN FROM THE CHECK COMMANDS: THE RUNNER API WITH THE TOOL'S OWN RUNNER TOKEN
+// A runner token is not a personal token. It can take a queued run, beat for it, upload evidence and report a result, and nothing else.
+// -- MODULES -- //
+import { TOOL_PROTOCOL } from './paths.js';
+// -- CONSTANTS -- //
+/** One call to the board may take this long, uploads included. A half open connection must not hang the run for ever. */
+export const CALL_TIMEOUT_MS = 120_000;
+/** Asking for a run waits a short while only. */
+export const CLAIM_TIMEOUT_MS = 20_000;
+/** Raised when the board refuses a call. Carries the board's own words and code. */
+export class BoardError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'BoardError';
+    }
+}
+// -- FUNCTIONS -- //
+/** The calls of the runner API, as the check commands make them. */
+export class RunnerBoard {
+    server;
+    token;
+    doFetch;
+    extraHeaders;
+    constructor(server, token, doFetch = (input, init) => fetch(input, init), 
+    /** Extra headers sent with every call: the audit head and the slots, built by the caller, never required. */
+    extraHeaders = () => ({})) {
+        this.server = server;
+        this.token = token;
+        this.doFetch = doFetch;
+        this.extraHeaders = extraHeaders;
+    }
+    async call(method, path, body, type, timeoutMs = CALL_TIMEOUT_MS) {
+        let res;
+        let text;
+        try {
+            res = await this.doFetch(`${this.server.replace(/\/$/, '')}/api/v1/runner${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${this.token}`,
+                    'x-afb-tool-protocol': String(TOOL_PROTOCOL),
+                    ...this.extraHeaders(),
+                    ...(type ? { 'content-type': type } : {})
+                },
+                body: body,
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+            text = await res.text();
+        }
+        catch (e) {
+            const name = e?.name;
+            if (name === 'TimeoutError' || name === 'AbortError')
+                throw new BoardError(0, 'TIMEOUT', `The board did not answer within ${Math.round(timeoutMs / 1000)} seconds.`);
+            throw e;
+        }
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            /* Not JSON */
+        }
+        if (!res.ok) {
+            const err = json?.error;
+            if (res.status === 401)
+                throw new BoardError(401, 'UNAUTHENTICATED', 'The board no longer accepts this machine for checks. Run: agent-flow-board check connect --server <url> --org <slug> --json');
+            throw new BoardError(res.status, err?.code ?? 'ERROR', err?.message ?? `The board answered ${res.status}.`);
+        }
+        return json;
+    }
+    /** Takes the run with this id, and no other. Null when it is not queued for this runner. */
+    async claim(runId) {
+        const out = await this.call('POST', '/claim', JSON.stringify({ runId }), 'application/json', CLAIM_TIMEOUT_MS);
+        return out.job;
+    }
+    /** Takes the oldest queued run this runner may take, for `check watch`. */
+    async claimNext() {
+        const out = await this.call('POST', '/claim', undefined, undefined, CLAIM_TIMEOUT_MS);
+        return out.job;
+    }
+    /** How many runs wait for this runner. Nothing is taken. */
+    async peek() {
+        return (await this.call('POST', '/peek')).waiting;
+    }
+    /** Says the process is alive and still on this run. A conflict means the board gave up on it. */
+    beat(runId) {
+        return this.call('POST', `/runs/${encodeURIComponent(runId)}/beat`);
+    }
+    /** Gives back the named runs only, never the runs of another process of the same runner. */
+    async release(runIds) {
+        if (!runIds.length)
+            return 0;
+        return (await this.call('POST', '/release', JSON.stringify({ runIds }), 'application/json')).released;
+    }
+    /** Stores a file of a run as evidence and returns its attachment id. */
+    async upload(runId, file) {
+        const q = `filename=${encodeURIComponent(file.filename)}&caption=${encodeURIComponent(file.caption)}`;
+        const out = await this.call('POST', `/runs/${encodeURIComponent(runId)}/artifacts?${q}`, file.bytes, 'application/octet-stream');
+        return out.attachmentId;
+    }
+    finish(runId, report) {
+        return this.call('POST', `/runs/${encodeURIComponent(runId)}/finish`, JSON.stringify(report), 'application/json');
+    }
+}

package/dist/checks/browser.js

@@ -0,0 +1,170 @@
+// THE BROWSER OF A CHECK: ONE CHROMIUM SERVER STARTED BY THE PARENT, WHICH THE SANDBOXED CHILD ONLY CONNECTS TO.
+// Playwright is not a dependency of the bridge (it is large and most people never run a check). It is found next to the bridge when it is there,
+// and otherwise installed once into ~/.agent-flow-board/checks/runtime. Nothing in this file imports Playwright at load time.
+// -- DEP-MODULES -- //
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+// -- MODULES -- //
+import { checksHome, ensureDir } from './paths.js';
+// -- CONSTANTS -- //
+/** The Playwright version the runtime install pins, so a check behaves the same on every machine. */
+const PLAYWRIGHT_VERSION = '1.64.0';
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+// -- FUNCTIONS -- //
+/** Where the runtime install lives. It is a folder of the bridge's own state, never a repo. */
+const runtimeDir = () => join(checksHome(), 'runtime');
+const looksInstalled = (nodeModules) => existsSync(join(nodeModules, 'playwright-core', 'package.json'));
+/**
+ * The node_modules folder that holds playwright-core (and @playwright/test when it is there): next to the bridge first, then the runtime
+ * install. The sandboxed child is allowed to read this folder and nothing else outside its own. Null when Playwright is not installed anywhere.
+ */
+export function playwrightRuntimeDir() {
+    try {
+        const pkg = createRequire(import.meta.url).resolve('playwright-core/package.json');
+        // .../node_modules/playwright-core/package.json -> .../node_modules
+        return dirname(dirname(pkg));
+    }
+    catch {
+        /* Not next to the bridge: try the runtime install */
+    }
+    const own = join(runtimeDir(), 'node_modules');
+    return looksInstalled(own) ? own : null;
+}
+/** Loads playwright-core from the folder playwrightRuntimeDir names, by absolute path. */
+export async function loadPlaywright() {
+    const dir = playwrightRuntimeDir();
+    if (!dir)
+        throw new Error('Playwright is not installed yet. Run "agent-flow-board check setup" and it will install it.');
+    const req = createRequire(join(dir, 'package.json'));
+    return req(join(dir, 'playwright-core'));
+}
+/**
+ * A browser the parent starts, so a check's process only connects to it and never has to start a program itself.
+ * Every host except the preview's (and the hosts named) is unresolvable, whatever a check does with routes.
+ */
+export async function launchBrowserServer({ headed = false, hosts = [] } = {}) {
+    const { chromium } = await loadPlaywright();
+    const exclude = [...new Set(['127.0.0.1', 'localhost', ...hosts])]
+        .map((h) => `EXCLUDE ${h}`)
+        .join(', ');
+    const server = await chromium.launchServer({
+        headless: !headed,
+        args: [
+            `--host-resolver-rules=MAP * ~NOTFOUND, ${exclude}`,
+            '--disable-background-networking',
+            '--no-first-run'
+        ]
+    });
+    return { wsEndpoint: () => server.wsEndpoint(), close: () => server.close() };
+}
+/** Says whether an installer failure looks like no network or a proxy, so the one-line error can tell the person what to look at. */
+export function describeInstallFailure(output) {
+    if (/proxy|407|tunnel|ECONNRESET|self[- ]signed|certificate/i.test(output))
+        return 'it looks like a proxy problem (check HTTPS_PROXY and the proxy settings)';
+    if (/ENOTFOUND|EAI_AGAIN|ENETUNREACH|ECONNREFUSED|ETIMEDOUT|getaddrinfo|offline|network/i.test(output))
+        return 'it looks like this machine is offline';
+    return 'see the last lines above';
+}
+/** Runs a program with the exact arguments (no shell, no stdin) and sends every output line to `log`. Resolves with the exit code and the last output. */
+function runLogged(file, args, log, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd,
+            shell: false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let tail = '';
+        const feed = (chunk) => {
+            for (const line of chunk.toString('utf8').split(/\r?\n/)) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                tail = `${tail}\n${t}`.slice(-2000);
+                log(t);
+            }
+        };
+        child.stdout.on('data', feed);
+        child.stderr.on('data', feed);
+        const timer = setTimeout(() => child.kill(), INSTALL_TIMEOUT_MS);
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, tail });
+        });
+    });
+}
+/** The npm that belongs to this Node: its npm-cli.js, so no shell is needed. Null when it is not where Node keeps it. */
+function npmCli() {
+    const root = dirname(process.execPath);
+    const candidates = [
+        join(root, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        join(root, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')
+    ];
+    return candidates.find((c) => existsSync(c)) ?? null;
+}
+/**
+ * Installs Playwright into the runtime folder of the bridge's state.
+ * This is the ONE place npm is used: it installs a runtime for the installed bridge into ~/.agent-flow-board, never into a repo,
+ * so the Yarn-only rule of the repos does not apply here.
+ */
+async function installRuntime(log) {
+    const dir = ensureDir(runtimeDir());
+    const manifest = join(dir, 'package.json');
+    if (!existsSync(manifest))
+        writeFileSync(manifest, JSON.stringify({ private: true }, null, 2));
+    log(`Installing Playwright ${PLAYWRIGHT_VERSION} into ${dir} (first use only)...`);
+    // @playwright/test brings the expect that checks use; playwright-core is what the parent drives
+    const npmArgs = [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--prefix',
+        dir,
+        `playwright-core@${PLAYWRIGHT_VERSION}`,
+        `@playwright/test@${PLAYWRIGHT_VERSION}`
+    ];
+    const cli = npmCli();
+    const out = await new Promise((resolve) => {
+        const done = (error, stdout, stderr) => resolve({ error, text: `${stdout}\n${stderr}` });
+        if (cli)
+            execFile(process.execPath, [cli, ...npmArgs], { windowsHide: true, timeout: INSTALL_TIMEOUT_MS, shell: false }, (e, so, se) => done(e, so, se));
+        else
+            execFile('npm', npmArgs, { windowsHide: true, timeout: INSTALL_TIMEOUT_MS, shell: process.platform === 'win32' }, (e, so, se) => done(e, so, se));
+    });
+    if (out.error || !looksInstalled(join(dir, 'node_modules'))) {
+        const last = out.text.trim().split('\n').slice(-3).join(' ').slice(0, 300);
+        throw new Error(`Could not install Playwright: ${describeInstallFailure(out.text)}. ${last}`);
+    }
+}
+/**
+ * Makes sure Playwright and its Chromium are there. The first use installs them (a few hundred megabytes, with progress lines in `log`);
+ * later uses return at once. Never prompts. A failure is one Error that says whether it looks like offline or a proxy.
+ */
+export async function ensureBrowser(log = () => { }) {
+    if (!playwrightRuntimeDir())
+        await installRuntime(log);
+    const dir = playwrightRuntimeDir();
+    if (!dir)
+        throw new Error('Playwright was installed but cannot be found.');
+    const { chromium } = await loadPlaywright();
+    try {
+        if (existsSync(chromium.executablePath()))
+            return;
+    }
+    catch {
+        /* No executable path known yet: install below */
+    }
+    log('Installing the Chromium browser for Playwright (first use only)...');
+    const cli = join(dir, 'playwright-core', 'cli.js');
+    if (!existsSync(cli))
+        throw new Error('Playwright is installed but its installer (cli.js) is missing. Remove the runtime folder and try again.');
+    const { code, tail } = await runLogged(process.execPath, [cli, 'install', 'chromium'], log).catch((e) => ({ code: -1, tail: String(e) }));
+    if (code !== 0)
+        throw new Error(`Could not install the Chromium browser: ${describeInstallFailure(tail)}. ${tail.split('\n').slice(-2).join(' ').trim().slice(0, 300)}`);
+}