@agent-flow-board/bridge 0.1.0 → 0.2.0

package/dist/checks/child.js

@@ -0,0 +1,211 @@
+// RUNS ONE CHECK FILE IN ITS OWN PROCESS, started by sandbox.ts with Node's permission model on (dist/checks/child.js).
+// It reads one job from stdin (the saved sign-in is handed over there, never written to disk here), drives the page, writes its
+// result and its pictures into the run folder, and prints one line per event. It never sees the board or any token.
+// Under the permission model there are no child processes, no worker threads and no file access outside the folders sandbox.ts names,
+// and the only environment variable it reads is AFB_PLAYWRIGHT_DIR. It imports nothing that touches the bridge's token store.
+// -- DEP-MODULES -- //
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// -- MODULES -- //
+import { guardContext, pageForCheck, unwrap } from './guard.js';
+import { redact } from './redact.js';
+// -- CONSTANTS -- //
+const CHECK_LIMIT_MS = 120_000;
+const MAX_SHOT_HEIGHT = 2400;
+// -- FUNCTIONS -- //
+const readStdin = () => new Promise((resolve) => {
+    let s = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => (s += d));
+    process.stdin.on('end', () => resolve(s));
+});
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+async function main() {
+    const job = JSON.parse(await readStdin());
+    const needles = job.needles ?? [];
+    const extraHosts = job.extraHosts ?? [];
+    const origin = new URL(job.baseUrl).origin;
+    // PLAYWRIGHT: the parent names the node_modules folder that holds it; it is the only place outside the run folder this process can read
+    const pwDir = process.env.AFB_PLAYWRIGHT_DIR;
+    if (!pwDir)
+        throw new Error('The parent did not say where Playwright is.');
+    const req = createRequire(import.meta.url);
+    const { chromium } = req(join(pwDir, 'playwright-core'));
+    // expect() comes with @playwright/test. Without it a check that calls expect gets one plain sentence
+    let realExpect;
+    try {
+        realExpect = req(join(pwDir, '@playwright', 'test')).expect;
+    }
+    catch {
+        realExpect = () => {
+            throw new Error('expect() needs @playwright/test, which is not installed next to Playwright. Run "agent-flow-board check setup".');
+        };
+    }
+    // expect() needs the real locator, so it is given one here, and the check only ever sees the matchers
+    const checkExpect = Object.assign((value, message) => realExpect(unwrap(value), message), {
+        soft: (value, message) => realExpect.soft?.(unwrap(value), message),
+        poll: (fn, options) => realExpect.poll?.(fn, options)
+    });
+    const out = (event) => process.stdout.write(`EVENT ${JSON.stringify(event)}\n`);
+    const say = (m) => out({ type: 'log', text: redact(String(m), needles).slice(0, 600) });
+    const shotsDir = join(job.runDir, 'shots');
+    mkdirSync(shotsDir, { recursive: true });
+    const steps = [];
+    const lines = [];
+    let n = 0;
+    let page;
+    let expiredSeen = false;
+    let counts = { writes: 0, outside: 0 };
+    async function takeShot(caption) {
+        if (!page)
+            return null;
+        const file = `${String(++n).padStart(2, '0')}.jpg`;
+        try {
+            const height = await page.evaluate(() => document.documentElement.scrollHeight);
+            const bytes = await page.screenshot({
+                type: 'jpeg',
+                quality: 55,
+                fullPage: true,
+                ...(height > MAX_SHOT_HEIGHT
+                    ? { clip: { x: 0, y: 0, width: job.viewport.width, height: MAX_SHOT_HEIGHT } }
+                    : {})
+            });
+            writeFileSync(join(shotsDir, file), bytes);
+            return { file, caption };
+        }
+        catch {
+            return null;
+        }
+    }
+    let result = 'pass';
+    let reason;
+    const started = Date.now();
+    // The browser was started by the tool; this process only connects to it, so it never has to start a program itself
+    const browser = await chromium.connect(job.ws);
+    try {
+        const ctx = await browser.newContext({
+            baseURL: job.baseUrl,
+            viewport: job.viewport,
+            storageState: job.storageState ?? undefined,
+            serviceWorkers: 'block'
+        });
+        // ChildJob has no allowWrites: a check run in the sandbox never writes
+        counts = await guardContext(ctx, { origin, allowWrites: false, extraHosts, onBlocked: say });
+        const real = await ctx.newPage();
+        page = real;
+        let violation = null;
+        // A page that ends up anywhere but the app under test (file:, chrome:, view-source:) fails the run
+        real.on('framenavigated', (f) => {
+            try {
+                const u = new URL(f.url());
+                if (u.protocol !== 'about:' &&
+                    (!['http:', 'https:'].includes(u.protocol) ||
+                        (u.origin !== origin && !extraHosts.includes(u.hostname))))
+                    violation = `The page went to ${u.protocol}//${u.host}, which is not the app under test.`;
+            }
+            catch {
+                /* about:blank and the like */
+            }
+        });
+        // A signed-in run that is sent to a sign-in page has an expired sign-in
+        real.on('framenavigated', (f) => {
+            try {
+                if (f === real.mainFrame() &&
+                    job.storageState &&
+                    /\/(sign-?in|log-?in|login|auth)(\/|$|\?)/i.test(new URL(f.url()).pathname))
+                    expiredSeen = true;
+            }
+            catch {
+                /* about:blank and the like */
+            }
+        });
+        const step = async (name, fn) => {
+            const t0 = Date.now();
+            try {
+                await fn();
+                const shot = await takeShot(name);
+                steps.push({ name, status: 'pass', ms: Date.now() - t0, shot: shot?.file ?? null });
+                out({ type: 'step', name, status: 'pass', ms: Date.now() - t0 });
+            }
+            catch (e) {
+                const shot = await takeShot(`${name} (failed)`);
+                const error = redact(messageOf(e).split('\n').slice(0, 4).join(' '), needles).slice(0, 500);
+                steps.push({ name, status: 'fail', ms: Date.now() - t0, shot: shot?.file ?? null, error });
+                out({ type: 'step', name, status: 'fail', ms: Date.now() - t0, error });
+                throw e;
+            }
+        };
+        const shot = async (caption = 'Shot') => {
+            const s = await takeShot(caption);
+            if (s)
+                steps.push({ name: caption, status: 'shot', ms: 0, shot: s.file });
+        };
+        const log = (m) => {
+            const t = redact(String(m), needles);
+            lines.push(t);
+            say(t);
+        };
+        const fn = (await import(pathToFileURL(job.checkFile).href)).default;
+        if (typeof fn !== 'function')
+            throw new Error('A check file must export default an async function({ page, step, shot, expect, log, baseUrl }).');
+        let timer;
+        try {
+            await Promise.race([
+                fn({
+                    page: pageForCheck(real, { origin, extraHosts }),
+                    step,
+                    shot,
+                    expect: checkExpect,
+                    log,
+                    baseUrl: job.baseUrl
+                }),
+                new Promise((_, rej) => (timer = setTimeout(() => rej(new Error('The check took longer than 2 minutes.')), CHECK_LIMIT_MS)))
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (violation)
+            throw new Error(violation);
+        if (!steps.length) {
+            const s = await takeShot('End of the check');
+            if (s)
+                steps.push({ name: 'End of the check', status: 'shot', ms: 0, shot: s.file });
+        }
+    }
+    catch (e) {
+        result = 'fail';
+        reason = redact(messageOf(e).split('\n').slice(0, 4).join(' '), needles).slice(0, 700);
+        if (!steps.some((s) => s.status === 'fail') && page) {
+            const s = await takeShot('Where it stopped');
+            if (s)
+                steps.push({ name: 'Where it stopped', status: 'shot', ms: 0, shot: s.file });
+        }
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    if (result === 'fail' && expiredSeen)
+        reason =
+            `The saved sign-in no longer works: the app sent the browser to its sign-in page. Sign in again and rerun. (${reason ?? ''})`.trim();
+    const final = {
+        schema: 1,
+        result,
+        reason: reason ?? null,
+        durationMs: Date.now() - started,
+        steps,
+        log: lines.join('\n'),
+        blockedWrites: counts.writes,
+        blockedOutside: counts.outside
+    };
+    writeFileSync(join(job.runDir, 'result.json'), JSON.stringify(final, null, 1));
+    out({ type: 'done', result });
+}
+main().then(
+// Nothing else is waiting, so end now instead of waiting for stray timers
+() => process.exit(0), (e) => {
+    process.stderr.write(`${messageOf(e).slice(0, 600)}\n`);
+    process.exit(1);
+});

package/dist/checks/command.js

@@ -0,0 +1,280 @@
+// THE `check` COMMAND GROUP: connect, run, pull, bind, watch, status, doctor, clear, setup
+// Loaded only when the first argument is `check`, so the hooks and the MCP forwarder never load any of it (and never load Playwright).
+// Nothing here waits on a terminal: every command takes its input from flags and ends on its own.
+// -- DEP-MODULES -- //
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+// -- MODULES -- //
+import { verifyAudit } from './audit.js';
+import { bindFolder, listBindings, pinStatus } from './bind.js';
+import { ensureBrowser, playwrightRuntimeDir } from './browser.js';
+import { connectChecks, loadRunnerToken, runnerAccount } from './connect.js';
+import { forgetConnection, listConnections, recordConnection } from './connections.js';
+import { ORG_SLUG, checksHome, scriptPath } from './paths.js';
+import { pinFiles, resolveProjectConfig } from './recipe.js';
+import { runCheck } from './run.js';
+import { clearRuns, sweepOrphans } from './scope.js';
+import { permissionFlag } from './sandbox.js';
+import { watchChecks } from './watch.js';
+// -- CONSTANTS -- //
+export const CHECK_USAGE = [
+    'Usage: agent-flow-board check <command>',
+    '  connect --server <url> --org <slug> [--project KEY,KEY] [--json]   make this machine a runner (an agent approves the code)',
+    '  run <item> <key> --server <url> --org <slug> [--step 1.2] [--run <id>] [--dir <repo>] [--json]   run one check in this repo',
+    '  pull <item> <key> --server <url> --org <slug> [--accept-hash <sha256>]   read the board copy of a script; accept it by hash',
+    '  bind --org <slug> --project <KEY> [--dir <repo>]   remember the folder of a board project for "check watch"',
+    '  watch [--parallel N] [--once]   take queued runs from the boards this machine is connected to',
+    '  status [--json]  |  doctor [--fix] [--json]  |  clear [--all]  |  setup  |  disconnect --server <url> --org <slug>'
+].join('\n');
+// -- FUNCTIONS -- //
+/** Runs one check command and returns the exit code: 0 done, 1 a check failed or a problem was listed, 2 could not run. */
+export async function checkMain(ctx) {
+    const { args, log, out } = ctx;
+    const sub = args[0];
+    const flag = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+    const has = (name) => args.includes(name);
+    const json = has('--json');
+    const need = (name) => {
+        const v = flag(name);
+        if (!v || v.startsWith('--'))
+            throw new Error(`Say ${name} <value>.`);
+        return v;
+    };
+    const server = () => {
+        const s = flag('--server') ?? process.env.AFB_SERVER;
+        if (!s)
+            throw new Error('Say which board to use: --server https://board.example.com (or set AFB_SERVER).');
+        return s.replace(/\/$/, '');
+    };
+    const org = () => {
+        const o = need('--org');
+        if (!ORG_SLUG.test(o))
+            throw new Error('--org takes an organisation slug: lowercase letters, digits and dashes.');
+        return o;
+    };
+    try {
+        if (sub === 'connect') {
+            const s = server();
+            const o = org();
+            const projects = flag('--project')
+                ?.split(',')
+                .map((p) => p.trim())
+                .filter(Boolean);
+            const done = await connectChecks({
+                server: s,
+                org: o,
+                projects,
+                json,
+                store: ctx.store,
+                fetch: ctx.fetch,
+                log,
+                out
+            });
+            recordConnection({ server: s, org: o, name: done.name });
+            return 0;
+        }
+        if (sub === 'disconnect') {
+            const s = server();
+            const o = org();
+            ctx.store.delete(runnerAccount(s, o));
+            forgetConnection(s, o);
+            log('Disconnected. The runner on the board is removed from the board settings.');
+            return 0;
+        }
+        if (sub === 'run') {
+            const item = args[1];
+            const key = args[2];
+            if (!item || !key || item.startsWith('--') || key.startsWith('--'))
+                throw new Error('Usage: agent-flow-board check run <item> <key> --server <url> --org <slug>');
+            const s = server();
+            const o = org();
+            const token = loadRunnerToken(ctx.store, s, o);
+            if (!token)
+                throw new Error(`This machine is not connected to ${o} on ${s}. Run: agent-flow-board check connect --server ${s} --org ${o} --json`);
+            const outcome = await runCheck({
+                server: s,
+                org: o,
+                item,
+                key,
+                dir: resolve(flag('--dir') ?? process.cwd()),
+                step: flag('--step'),
+                runId: flag('--run'),
+                runnerToken: token,
+                personalToken: ctx.personalToken(s, o),
+                fetch: ctx.fetch,
+                log,
+                headed: has('--headed')
+            });
+            if (json)
+                out(JSON.stringify({
+                    ok: outcome.exitCode === 0,
+                    runId: outcome.runId,
+                    message: outcome.message
+                }));
+            else
+                log(outcome.message);
+            // The last line is always the result file, so an agent can read it
+            if (outcome.resultPath)
+                out(`RESULT ${outcome.resultPath}`);
+            return outcome.exitCode;
+        }
+        if (sub === 'pull') {
+            const item = args[1];
+            const key = args[2];
+            if (!item || !key)
+                throw new Error('Usage: agent-flow-board check pull <item> <key> --server <url> --org <slug> [--accept-hash <sha256>]');
+            const s = server();
+            const o = org();
+            const personal = ctx.personalToken(s, o);
+            if (!personal)
+                throw new Error(`Not signed in to ${o} on ${s}. Run: agent-flow-board login --json --server ${s} --org ${o}`);
+            const res = await ctx.fetch(`${s}/api/v1/orgs/${encodeURIComponent(o)}/items/${encodeURIComponent(item)}/browser-checks`, {
+                headers: { authorization: `Bearer ${personal}` },
+                signal: AbortSignal.timeout(30_000)
+            });
+            const body = (await res.json().catch(() => ({})));
+            if (!res.ok)
+                throw new Error(body.error?.message ?? `The board answered ${res.status}.`);
+            const script = body.checks?.find((c) => c.key === key)?.script;
+            if (!script)
+                throw new Error(`The board has no saved script for ${item} ${key}.`);
+            const hash = createHash('sha256').update(script).digest('hex');
+            const target = scriptPath(o, item, key);
+            const local = existsSync(target) ? readFileSync(target, 'utf8') : null;
+            const accept = flag('--accept-hash');
+            if (accept) {
+                if (accept !== hash)
+                    throw new Error('The board script changed since you read it (its hash is different), so nothing was written. Pull again.');
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, script);
+                log(`Wrote ${target}.`);
+                return 0;
+            }
+            // The script is text written by someone else: it is shown as data and never run until it is accepted by its hash
+            out(JSON.stringify({
+                item,
+                key,
+                hash,
+                local: local === null ? 'none' : local === script ? 'same' : 'different',
+                target,
+                script
+            }));
+            return 0;
+        }
+        if (sub === 'bind') {
+            const o = org();
+            const project = need('--project');
+            const dir = resolve(flag('--dir') ?? process.cwd());
+            const cfg = resolveProjectConfig(dir);
+            bindFolder(o, project, cfg.repo, pinFiles(cfg.repo));
+            log(`Bound ${o}/${project} to ${cfg.repo}.`);
+            return 0;
+        }
+        if (sub === 'watch') {
+            const ac = new AbortController();
+            const stop = () => ac.abort();
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            const n = await watchChecks({
+                store: ctx.store,
+                fetch: ctx.fetch,
+                log,
+                parallel: Number(flag('--parallel') ?? 3) || 3,
+                once: has('--once'),
+                signal: ac.signal
+            });
+            log(`Took ${n} run(s).`);
+            return 0;
+        }
+        if (sub === 'setup') {
+            await ensureBrowser(log);
+            log('The browser is ready.');
+            return 0;
+        }
+        if (sub === 'status' || sub === 'doctor')
+            return await statusOrDoctor(ctx, sub === 'doctor', has('--fix'), json);
+        if (sub === 'clear') {
+            const r = clearRuns({ all: has('--all') });
+            log(`Removed ${r.removed} finished run folder(s).`);
+            return 0;
+        }
+        log(CHECK_USAGE);
+        return 2;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (json)
+            out(JSON.stringify({ ok: false, event: 'error', error: message }));
+        else
+            log(message);
+        return 2;
+    }
+}
+async function statusOrDoctor(ctx, doctor, fix, json) {
+    const problems = [];
+    const audit = verifyAudit();
+    if (!audit.ok)
+        problems.push({
+            problem: 'The audit log does not verify (it was edited or cut).',
+            next: 'Do not edit it. Move checks/audit.log aside to start a new chain.'
+        });
+    if (!permissionFlag())
+        problems.push({
+            problem: 'This Node has no permission model, so check scripts cannot be sandboxed.',
+            next: 'Install Node 20.18 or later (or any Node 22).'
+        });
+    if (!playwrightRuntimeDir()) {
+        if (doctor && fix)
+            await ensureBrowser(ctx.log);
+        else
+            problems.push({
+                problem: 'The browser is not installed.',
+                next: 'Run: agent-flow-board check setup'
+            });
+    }
+    const swept = doctor && fix ? await sweepOrphans(ctx.log) : 0;
+    const connections = listConnections().map((c) => ({
+        ...c,
+        connected: Boolean(loadRunnerToken(ctx.store, c.server, c.org))
+    }));
+    for (const c of connections)
+        if (!c.connected)
+            problems.push({
+                problem: `${c.org} on ${c.server} has no runner token.`,
+                next: `Run: agent-flow-board check connect --server ${c.server} --org ${c.org} --json`
+            });
+    const bindings = listBindings().map((b) => ({
+        org: b.org,
+        project: b.projectKey,
+        folder: b.folder,
+        pin: pinStatus(b.org, b.projectKey)
+    }));
+    for (const b of bindings)
+        if (b.pin !== 'ok')
+            problems.push({
+                problem: `${b.org}/${b.project}: the files that decide what runs changed in ${b.folder}.`,
+                next: `In that folder run a check once: agent-flow-board check run <item> <key> --org ${b.org}`
+            });
+    const state = {
+        home: checksHome(),
+        connections,
+        bindings,
+        audit: { ok: audit.ok, lines: audit.lines },
+        browser: Boolean(playwrightRuntimeDir()),
+        swept,
+        problems
+    };
+    if (json)
+        ctx.out(JSON.stringify(state));
+    else {
+        ctx.log(`State folder: ${state.home}`);
+        ctx.log(`Connections: ${connections.map((c) => `${c.org}@${c.server}${c.connected ? '' : ' (no token)'}`).join(', ') || 'none'}`);
+        ctx.log(`Bound folders: ${bindings.map((b) => `${b.org}/${b.project} -> ${b.folder} (${b.pin})`).join('; ') || 'none'}`);
+        for (const p of problems)
+            ctx.log(`Problem: ${p.problem} Next: ${p.next}`);
+        if (!problems.length)
+            ctx.log('Nothing is wrong.');
+    }
+    return doctor && problems.length ? 1 : 0;
+}

package/dist/checks/connect.js

@@ -0,0 +1,79 @@
+// CONNECTING THIS MACHINE TO A BOARD AS A CHECK RUNNER
+// One device sign in under the client name afb-checks (an agent approves it with tool_connection_approve and the verifier, or a person types the
+// code on the /device page), one call that makes this machine a runner of the organisation, then only the runner token is kept. The personal
+// token is forgotten at once. The runner token has its own entry in the token store, apart from the sign in of the hooks and MCP.
+// -- DEP-MODULES -- //
+import { hostname } from 'node:os';
+// -- MODULES -- //
+import { deviceLogin } from '../device.js';
+import { accountKey } from '../tokenStore.js';
+// -- CONSTANTS -- //
+/** The client name the board approves with the manage permission, used once to make the runner. */
+export const TOOL_CLIENT_NAME = 'afb-checks';
+// -- FUNCTIONS -- //
+/** The token store entry of the runner token for a server and organisation. */
+export const runnerAccount = (server, org) => `${accountKey(server, org)}.checks`;
+/**
+ * A name for this machine's runner. A repeat of the same owner and name replaces the old token on the board, so this name is different from the
+ * one the standalone afb-checks tool uses on the same machine: connecting the bridge must never cut that tool off.
+ */
+export function runnerName() {
+    const host = hostname()
+        .replace(/[^A-Za-z0-9 ._-]/g, '')
+        .slice(0, 36) || 'this-machine';
+    return `${host} agent-flow-board`.slice(0, 60);
+}
+/** The runner token for a server and organisation, or null when this machine has not been connected. AFB_CHECKS_TOKEN overrides it, for tests. */
+export function loadRunnerToken(store, server, org) {
+    return process.env.AFB_CHECKS_TOKEN ?? store.get(runnerAccount(server, org));
+}
+/** Makes this machine a runner of the organisation. Never prints a token. */
+export async function connectChecks(options) {
+    const url = new URL(options.server);
+    if (url.protocol !== 'https:' && !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))
+        throw new Error('The board address must start with https:// (only an address on this machine may use http).');
+    const personal = await deviceLogin(options.server, options.fetch, options.log, {
+        name: TOOL_CLIENT_NAME,
+        pkce: true,
+        wait: options.wait,
+        onCode: (c) => {
+            if (options.json)
+                options.out(JSON.stringify({
+                    event: 'code',
+                    userCode: c.userCode,
+                    verificationUri: c.verificationUri,
+                    verifier: c.verifier,
+                    expiresIn: c.expiresInSeconds
+                }));
+            else
+                options.log('On that page choose your organisation and tick "Change project settings" (manage). This is used once, to make this machine a runner.');
+        }
+    });
+    const name = runnerName();
+    const projects = options.projects?.length ? options.projects : undefined;
+    const res = await options.fetch(`${options.server}/api/v1/orgs/${encodeURIComponent(options.org)}/runners/tool`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${personal.token}`,
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify({ name, ...(projects ? { projects } : {}) }),
+        signal: AbortSignal.timeout(30_000)
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.token)
+        throw new Error(body.error?.message ?? `The board answered ${res.status} when making this machine a runner.`);
+    options.store.set(runnerAccount(options.server, options.org), body.token);
+    const served = projects ? projects.join(', ') : 'every project of the organisation you may use';
+    if (options.json)
+        options.out(JSON.stringify({
+            event: 'connected',
+            server: options.server,
+            org: options.org,
+            name,
+            projects: projects ?? 'all'
+        }));
+    else
+        options.log(`Connected as "${name}". It serves ${served}.`);
+    return { name, served };
+}

package/dist/checks/connections.js

@@ -0,0 +1,41 @@
+// THE BOARDS THIS MACHINE IS CONNECTED TO FOR CHECKS: SERVER AND ORGANISATION ONLY, NEVER A TOKEN (THE TOKEN IS IN THE TOKEN STORE)
+// `check watch` re-reads this list on every loop, so a `check connect` for a second organisation is picked up without a restart.
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { checksHome, ensureDir, ORG_SLUG } from './paths.js';
+// -- FUNCTIONS -- //
+const file = () => join(checksHome(), 'connections.json');
+export function listConnections() {
+    if (!existsSync(file()))
+        return [];
+    try {
+        const v = JSON.parse(readFileSync(file(), 'utf8'));
+        return Array.isArray(v)
+            ? v.filter((c) => !!c &&
+                typeof c.server === 'string' &&
+                typeof c.org === 'string' &&
+                ORG_SLUG.test(c.org) &&
+                typeof c.name === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Adds or replaces the connection for a server and organisation. Written whole, never half. */
+export function recordConnection(c) {
+    const next = [...listConnections().filter((x) => !(x.server === c.server && x.org === c.org)), c];
+    ensureDir(checksHome());
+    const tmp = `${file()}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 1), { mode: 0o600 });
+    renameSync(tmp, file());
+}
+export function forgetConnection(server, org) {
+    const next = listConnections().filter((x) => !(x.server === server && x.org === org));
+    ensureDir(checksHome());
+    const tmp = `${file()}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 1), { mode: 0o600 });
+    renameSync(tmp, file());
+}