@agent-flow-board/bridge 0.1.0 → 0.3.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,267 @@
+// 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, relative, resolve } from 'node:path';
+// -- MODULES -- //
+import { bindFolder } from './bind.js';
+import { ensureBrowser } from './browser.js';
+import { connectChecks, loadRunnerToken, runnerAccount } from './connect.js';
+import { forgetConnection, recordConnection } from './connections.js';
+import { ORG_SLUG, scriptPath, scriptsDir } from './paths.js';
+import { pinFiles, resolveProjectConfig } from './recipe.js';
+import { runCheck } from './run.js';
+import { watchChecks } from './watch.js';
+import { approveCommand, projectCommand, rootsCommand } from './commands.js';
+import { clearCommand, healthCommand } from './doctor.js';
+import { importLegacyCommand } from './importlegacy.js';
+import { loginCommand } from './login.js';
+import { secretsCommand } from './secretscmd.js';
+import { serviceCommand } from './service.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',
+    '  run ... also takes [--registration NAME] [--file <script inside the scripts folder>] [--headed]',
+    '  project <NAME> --org <slug> (--repo <dir> [--app-dir web] [--board-project KEY] [--recipe] | --url <address> [--extra-hosts a,b]) [--adopt-env --adopt-env-approval <code>] [--upload-pictures --pictures-approval <code>] [--approval <code>] | project list|forget|pin',
+    '  approve --action <roots|register|secrets|adopt-env|pictures> --target <name>   (the owner, on a terminal)  |  roots add|list|remove <dir> [--approval <code>]',
+    '  secrets import|list|forget --org <slug> --project <NAME> [--from <file> --keys A,B --test-ref <ref> --test-inbox <email> --owner-said "<sentence>" --allow-service-role --approval <code>]',
+    '  login <NAME> --org <slug> --seeded  |  service install|uninstall|status [--no-start]  |  import-legacy --from <afb-checks folder> --org <slug> [--dry-run]',
+    '  status [--json]  |  doctor [--fix] [--json]  |  clear [runs|profiles|auth|dbs|previews|all] [--all] [--yes]  |  setup  |  disconnect --server <url> --org <slug>'
+].join('\n');
+// -- FUNCTIONS -- //
+/** The value of --parallel: undefined when the flag is absent (the machine decides), else a whole number from 1 up. */
+export function parallelFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error(`--parallel takes a whole number of 1 or more, not "${raw.slice(0, 20)}".`);
+    return n;
+}
+/** 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];
+    // A flag that is given takes the next word as its value; a missing value, or another flag in its place (--step --json), is an error and never a silent default
+    const flag = (name) => {
+        if (!args.includes(name))
+            return undefined;
+        const v = args[args.indexOf(name) + 1];
+        if (v === undefined || v.startsWith('--'))
+            throw new Error(`Say ${name} <value>.`);
+        return v;
+    };
+    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') {
+            // `--file <script>` names a script inside the scripts folder (<org>/<item>/<key>.mjs) instead of the item and the key
+            let item = args[1];
+            let key = args[2];
+            let fileOrg = null;
+            const fileFlag = flag('--file');
+            if (fileFlag) {
+                const rel = relative(scriptsDir(), resolve(fileFlag)).split(/[\\/]/);
+                const base = rel[2]?.replace(/\.mjs$/, '');
+                if (rel.length !== 3 || rel.includes('..') || !base)
+                    throw new Error(`--file must be a script inside ${scriptsDir()}, in the form <org>/<item>/<key>.mjs.`);
+                fileOrg = rel[0] ?? null;
+                item = rel[1];
+                key = base;
+            }
+            if (!item || !key || item.startsWith('--') || key.startsWith('--'))
+                throw new Error('Usage: agent-flow-board check run <item> <key> --server <url> --org <slug> (or --file <script>)');
+            const s = server();
+            const o = org();
+            // The folder of a script names its organisation: a script of one organisation is never run as another's
+            if (fileOrg !== null && fileOrg !== o)
+                throw new Error(`--file is a script of the organisation ${fileOrg.slice(0, 40)}, but --org says ${o}. Use the same organisation in both.`);
+            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'),
+                registration: flag('--registration'),
+                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;
+        }
+        // The registration, approval, sign in and service commands live in their own modules; each takes the arguments after its word
+        if (sub === 'project')
+            return await projectCommand(args.slice(1), { log, out, json });
+        if (sub === 'approve')
+            return await approveCommand(args.slice(1), { log, out, json });
+        if (sub === 'roots')
+            return await rootsCommand(args.slice(1), { log, out, json });
+        if (sub === 'login')
+            return await loginCommand(args.slice(1), { log, out, json });
+        if (sub === 'service')
+            return await serviceCommand(args.slice(1), { log, out, json });
+        if (sub === 'secrets')
+            return await secretsCommand(args.slice(1), { log, out, json });
+        if (sub === 'import-legacy')
+            return await importLegacyCommand(args.slice(1), { log, out, json });
+        if (sub === 'clear')
+            return await clearCommand(args.slice(1), { log, out, json, store: ctx.store });
+        if (sub === 'status' || sub === 'doctor')
+            return await healthCommand(args, { log, out, json, store: ctx.store });
+        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,
+                // Without --parallel the slots come from the machine (CPUs and free memory); a value that is not a whole number above 0 is refused, never turned into 3
+                parallel: parallelFlag(flag('--parallel')),
+                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;
+        }
+        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;
+    }
+}