@agent-flow-board/bridge 0.1.0 → 0.2.0

package/dist/checks/scope.js

@@ -0,0 +1,294 @@
+// THE THINGS ONE RUN OWNS, AND WHAT HAPPENS TO THEM WHEN THE RUN ENDS, WHATEVER ENDS IT.
+// The layer that makes the resources writes a live marker file first (runs/<run id>/ACTIVE: the process id, the start time and what the run made that a
+// crash would leave behind: the preview process, the database container and the private copy). Resources are closed newest first and closing never throws.
+// A later run sweeps what a dead process left: only the exact run folders and copies named by a dead marker (or by no marker and old enough), never a
+// folder that was not made by a run.
+// -- DEP-MODULES -- //
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { pidAlive } from './lock.js';
+import { NAME, copiesDir, ensureDir, runsDir, under } from './paths.js';
+import { removeContainer } from './provision.js';
+// -- CONSTANTS -- //
+const MARKER = 'ACTIVE';
+/** Written when a run ends in order, so a finished run's folder is never mistaken for one whose marker was lost. */
+const ENDED = 'ENDED';
+/** A run folder with no marker is only an orphan after this long (the marker is written first, so younger ones are being made right now). */
+const NO_MARKER_GRACE_MS = 15 * 60_000;
+const DAY_MS = 86_400_000;
+// -- FUNCTIONS -- //
+/** 'r' + a timestamp + random characters: a plain name, and sortable by time. */
+export const newRunId = () => 'r' + Date.now().toString(36) + randomBytes(3).toString('hex');
+const noop = () => { };
+/** Writes a file whole: a temporary file renamed into place, so a reader never sees half of it. */
+function writeWhole(file, text) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, { mode: 0o600 });
+    renameSync(tmp, file);
+}
+function readMarker(dir) {
+    try {
+        const v = JSON.parse(readFileSync(join(dir, MARKER), 'utf8'));
+        if (!v || typeof v !== 'object')
+            return null;
+        const m = v;
+        return typeof m.pid === 'number' && typeof m.runId === 'string' ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class RunScope {
+    runId;
+    disposers = [];
+    log;
+    info = {};
+    started = false;
+    closed = false;
+    constructor(runId = newRunId(), log = noop) {
+        if (!NAME.test(runId))
+            throw new Error('The run id is not a plain name.');
+        this.runId = runId;
+        this.log = log;
+    }
+    /** The folder of this run. */
+    get dir() {
+        return under(runsDir(), this.runId);
+    }
+    /** Writes the live marker. Called before anything else is made; every method that makes a resource calls it too, so it can never be skipped. */
+    start() {
+        if (this.started)
+            return;
+        ensureDir(this.dir);
+        this.started = true;
+        this.writeMarker();
+    }
+    writeMarker() {
+        const marker = {
+            runId: this.runId,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            ...this.info
+        };
+        writeWhole(join(this.dir, MARKER), JSON.stringify(marker) + '\n');
+    }
+    /** Records what a crash would leave behind (the preview process id, the database container, the private copy) so a later sweep can remove it. */
+    setInfo(info) {
+        this.start();
+        this.info = { ...this.info, ...info };
+        this.writeMarker();
+    }
+    /** Registers a resource. It is closed when the scope closes, newest first. */
+    add(name, dispose) {
+        this.start();
+        this.disposers.push({ name, dispose });
+    }
+    /** Closes every resource newest first, then removes the marker. Never throws; a failure goes to the log. Safe to call twice. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        while (this.disposers.length) {
+            const item = this.disposers.pop();
+            if (!item)
+                break;
+            try {
+                await item.dispose();
+            }
+            catch {
+                this.log(`Could not close ${item.name}.`);
+            }
+        }
+        try {
+            if (this.started) {
+                writeWhole(join(this.dir, ENDED), new Date().toISOString() + '\n');
+                rmSync(join(this.dir, MARKER), { force: true });
+            }
+        }
+        catch {
+            this.log('Could not remove the live marker of this run.');
+        }
+    }
+}
+/**
+ * Removes a folder without ever walking through a link: a symlink or junction is removed as a link (not recursed into), a folder is emptied then removed.
+ * Retries a few times because Windows holds files of a process that has only just been killed.
+ */
+export function removeTree(path) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch {
+        return;
+    }
+    if (st.isSymbolicLink()) {
+        try {
+            rmSync(path, { recursive: false, force: true });
+        }
+        catch {
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                rmdirSync(path);
+            }
+        }
+        return;
+    }
+    if (!st.isDirectory()) {
+        rmSync(path, { force: true, maxRetries: 5, retryDelay: 100 });
+        return;
+    }
+    for (const entry of readdirSync(path))
+        removeTree(join(path, entry));
+    // Windows holds a folder for a moment after a process that used it was killed
+    for (let i = 0;; i++) {
+        try {
+            rmdirSync(path);
+            return;
+        }
+        catch (e) {
+            if (i >= 5 || e.code === 'ENOENT') {
+                if (e.code === 'ENOENT')
+                    return;
+                throw e;
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        }
+    }
+}
+/** Kills a process and everything it started. */
+export function killTree(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return Promise.resolve();
+    if (process.platform === 'win32') {
+        // Windows cannot deliver SIGTERM to a child, so the tree is ended by taskkill
+        return new Promise((resolve) => {
+            execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true }, () => resolve());
+        });
+    }
+    // A child spawned detached leads its own group: the negative id reaches the whole group. A child that is not a leader falls back to itself
+    const send = (signal) => {
+        try {
+            process.kill(-pid, signal);
+        }
+        catch {
+            try {
+                process.kill(pid, signal);
+            }
+            catch {
+                /* Already gone */
+            }
+        }
+    };
+    send('SIGTERM');
+    return new Promise((resolve) => {
+        const until = Date.now() + 3_000;
+        const timer = setInterval(() => {
+            if (!pidAlive(pid)) {
+                clearInterval(timer);
+                resolve();
+            }
+            else if (Date.now() > until) {
+                clearInterval(timer);
+                send('SIGKILL');
+                resolve();
+            }
+        }, 100);
+    });
+}
+/** On a stop signal: closes the scope, then calls onKill (which exits the process). Returns the function that removes the handlers. */
+export function installSignalHandlers(scope, onKill) {
+    let busy = false;
+    const handler = () => {
+        if (busy)
+            return;
+        busy = true;
+        void scope.close().finally(() => onKill());
+    };
+    const signals = ['SIGINT', 'SIGTERM', 'SIGBREAK'];
+    for (const s of signals)
+        process.on(s, handler);
+    return () => {
+        for (const s of signals)
+            process.off(s, handler);
+    };
+}
+/** Removes a run folder and its private copy by their exact paths. */
+function removeRun(id) {
+    removeTree(under(copiesDir(), id));
+    removeTree(under(runsDir(), id));
+}
+const ageOf = (path) => {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+};
+const plainIds = (dir) => {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((n) => NAME.test(n));
+};
+/**
+ * Cleans what dead runs left: a run whose marker names a dead process, or that has neither a marker nor an end note and is older than 15 minutes.
+ * Stops the recorded preview process tree and database container, then removes only those run folders and copies. Returns how many runs it cleaned.
+ */
+export async function sweepOrphans(log = noop) {
+    let cleaned = 0;
+    const seen = new Set();
+    for (const id of plainIds(runsDir())) {
+        seen.add(id);
+        const dir = under(runsDir(), id);
+        const marker = readMarker(dir);
+        if (marker) {
+            if (pidAlive(marker.pid))
+                continue;
+        }
+        else if (existsSync(join(dir, MARKER)) ||
+            existsSync(join(dir, ENDED)) ||
+            ageOf(dir) < NO_MARKER_GRACE_MS) {
+            continue; // Finished in order (clearRuns handles it), or too young to judge
+        }
+        if (marker?.previewPid && pidAlive(marker.previewPid))
+            await killTree(marker.previewPid);
+        if (marker?.containerName)
+            await removeContainer(marker.containerName);
+        removeRun(id);
+        cleaned++;
+        log(`Cleaned the leftovers of run ${id}.`);
+    }
+    // A copy whose run folder is gone: removed when it is old enough that no run is still making it
+    for (const id of plainIds(copiesDir())) {
+        if (seen.has(id) || ageOf(under(copiesDir(), id)) < NO_MARKER_GRACE_MS)
+            continue;
+        removeTree(under(copiesDir(), id));
+        cleaned++;
+        log(`Removed the orphaned copy of run ${id}.`);
+    }
+    return cleaned;
+}
+/**
+ * Removes finished run folders (and their copies). A run with the live marker of a running process is always kept; a run whose process died is left to
+ * sweepOrphans, which also stops what it left running. By default only runs older than 7 days go; `all` removes every finished one.
+ */
+export function clearRuns(opts = {}) {
+    const limit = (opts.olderThanDays ?? 7) * DAY_MS;
+    let removed = 0;
+    for (const id of plainIds(runsDir())) {
+        const dir = under(runsDir(), id);
+        if (existsSync(join(dir, MARKER)))
+            continue;
+        if (!opts.all && ageOf(dir) < limit)
+            continue;
+        removeRun(id);
+        removed++;
+    }
+    return { removed };
+}

package/dist/checks/signin.js

@@ -0,0 +1,73 @@
+// SIGNING IN TO THE PREVIEW AS ITS TEST USER
+// The recipe may name a preview-only account (a user the app seeds in the throwaway database). The tool types its email and password into the
+// app's own sign in form in a browser that records nothing, keeps only the cookies and storage it ends with, and forgets the password. The
+// password is only ever typed into the app under test: the sign in page must be on its own address, and nothing else is reachable.
+// -- MODULES -- //
+import { loadPlaywright } from './browser.js';
+import { redact } from './redact.js';
+// -- CONSTANTS -- //
+const DEFAULT_PAGE = {
+    path: '/sign-in',
+    emailLabel: 'Email',
+    passwordLabel: 'Password',
+    submit: 'Sign in'
+};
+// -- FUNCTIONS -- //
+const mask = (email) => email.replace(/^(.).*(@.*)$/, '$1***$2');
+/** Signs in through the app's own form and returns the browser state. The error never holds the password. */
+export async function signInWithPassword(baseUrl, account, page = {}) {
+    const s = { ...DEFAULT_PAGE, ...page };
+    const origin = new URL(baseUrl).origin;
+    if (new URL(s.path, baseUrl).origin !== origin)
+        throw new Error(`The sign in page ${s.path} is not on ${origin}, so nothing was typed.`);
+    const { chromium } = await loadPlaywright();
+    const browser = await chromium.launch({
+        headless: true,
+        args: ['--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1, EXCLUDE localhost']
+    });
+    try {
+        const ctx = await browser.newContext({ baseURL: baseUrl, serviceWorkers: 'block' });
+        await ctx.route('**/*', (route) => new URL(route.request().url()).origin === origin || route.request().url().startsWith('data:')
+            ? route.continue()
+            : route.abort());
+        const tab = await ctx.newPage();
+        await tab.goto(s.path, { waitUntil: 'load', timeout: 30_000 });
+        await tab.getByLabel(s.emailLabel, { exact: true }).fill(account.email);
+        await tab.getByLabel(s.passwordLabel, { exact: true }).fill(account.password);
+        await tab.getByRole('button', { name: s.submit, exact: true }).click();
+        try {
+            await tab.waitForURL((u) => u.pathname !== new URL(s.path, baseUrl).pathname, {
+                timeout: 20_000
+            });
+        }
+        catch {
+            const shown = (await tab
+                .locator('[role=alert]')
+                .first()
+                .textContent({ timeout: 1000 })
+                .catch(() => null))?.trim();
+            throw new Error(redact(`Signing in as ${mask(account.email)} did not leave ${s.path}${shown ? `. The page says: ${shown.slice(0, 200)}` : ''}. An account that only signs in with Google has no password: use a recipe test user, which has one.`, [account.password]));
+        }
+        return await ctx.storageState();
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+    }
+}
+/** Every secret value in a saved browser state (cookie values and stored values), so a run never prints or uploads them. */
+export function stateNeedles(state) {
+    const out = new Set();
+    const add = (v) => {
+        if (typeof v === 'string' && v.length >= 8) {
+            out.add(v);
+            out.add(encodeURIComponent(v));
+        }
+    };
+    const s = state;
+    for (const c of s?.cookies ?? [])
+        add(c.value);
+    for (const o of s?.origins ?? [])
+        for (const l of o.localStorage ?? [])
+            add(l.value);
+    return [...out];
+}

package/dist/checks/types.js

@@ -0,0 +1,2 @@
+// THE SHARED SHAPES OF THE CHECK COMMANDS. EVERY MODULE IN THIS FOLDER IMPORTS FROM HERE, SO THE PARTS FIT.
+export {};

package/dist/checks/watch.js

@@ -0,0 +1,101 @@
+// `check watch`: TAKE QUEUED RUNS FROM EVERY CONNECTED BOARD (THE RUN BUTTON ON THE BOARD)
+// One worker per machine. A queued run is taken only for a project that has a local binding (a folder where `check run` was used) and whose
+// pinned files have not changed since: with none, the run ends "could not run" and the current directory is never a fallback.
+// -- MODULES -- //
+import { appendAudit } from './audit.js';
+import { boundFolder, pinStatus } from './bind.js';
+import { RunnerBoard } from './board.js';
+import { listConnections } from './connections.js';
+import { loadRunnerToken } from './connect.js';
+import { machineLock } from './lock.js';
+import { runCheck } from './run.js';
+import { sweepOrphans } from './scope.js';
+// -- CONSTANTS -- //
+const POLL_MS = 5000;
+const sleep = (ms, signal) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+        clearTimeout(t);
+        resolve();
+    }, { once: true });
+});
+/** Runs the worker until the signal aborts (or one pass with `once`). Returns how many runs it took. */
+export async function watchChecks(o) {
+    const lock = machineLock('watch');
+    if (!lock)
+        throw new Error('Another "check watch" is already running on this machine. Only one worker runs per machine.');
+    const slots = Math.max(1, Math.min(o.parallel, 8));
+    const held = new Map();
+    let taken = 0;
+    try {
+        await sweepOrphans(o.log);
+        appendAudit('watch-start', { slots });
+        do {
+            // The connections are read again on every loop, so a new `check connect` is picked up without a restart
+            for (const c of listConnections()) {
+                if (held.size >= slots || o.signal.aborted)
+                    break;
+                const token = loadRunnerToken(o.store, c.server, c.org);
+                if (!token)
+                    continue;
+                const board = new RunnerBoard(c.server, token, o.fetch, () => ({
+                    'x-afb-tool-slots': `${slots}:${held.size}`
+                }));
+                let job = null;
+                try {
+                    if ((await board.peek()) > 0)
+                        job = await board.claimNext();
+                }
+                catch (e) {
+                    o.log(`${c.org}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+                if (!job)
+                    continue;
+                taken++;
+                const claimed = job;
+                const done = handle(o, c.server, c.org, token, claimed).finally(() => held.delete(claimed.id));
+                held.set(claimed.id, { board, done });
+            }
+            if (o.once)
+                break;
+            await sleep(POLL_MS, o.signal);
+        } while (!o.signal.aborted);
+        await Promise.allSettled([...held.values()].map((h) => h.done));
+        return taken;
+    }
+    finally {
+        // Runs still held when the worker stops go back to the queue, only these, never another process's runs
+        const byBoard = new Map();
+        for (const [id, h] of held)
+            byBoard.set(h.board, [...(byBoard.get(h.board) ?? []), id]);
+        for (const [board, ids] of byBoard)
+            await board.release(ids).catch(() => undefined);
+        appendAudit('watch-stop', { taken });
+        lock.release();
+    }
+}
+async function handle(o, server, org, token, job) {
+    const board = new RunnerBoard(server, token, o.fetch);
+    const fail = (reason) => board.finish(job.id, { result: 'error', reason }).catch(() => undefined);
+    const projectKey = job.project.key;
+    const bound = boundFolder(org, projectKey);
+    if (!bound)
+        return void (await fail(`This machine has no folder for ${projectKey}. In the project's folder run: agent-flow-board check run ${job.item.ref} ${job.check.key} --org ${org}`));
+    if (pinStatus(org, projectKey) !== 'ok')
+        return void (await fail(`The files that decide what runs in ${bound.folder} changed since they were approved. In that folder run: agent-flow-board check run ${job.item.ref} ${job.check.key} --org ${org}`));
+    o.log(`${org}: running ${job.item.ref} ${job.check.key} in ${bound.folder}`);
+    const outcome = await runCheck({
+        server,
+        org,
+        item: job.item.ref,
+        key: job.check.key,
+        dir: bound.folder,
+        step: job.stepKey ?? undefined,
+        claimed: job,
+        runnerToken: token,
+        personalToken: null,
+        fetch: o.fetch,
+        log: o.log
+    });
+    o.log(`${org}: ${job.item.ref} ${job.check.key}: ${outcome.message}`);
+}

package/dist/cli.js

@@ -8,6 +8,7 @@
 // agent-flow-board hook claude|antigravity|gemini [event]   one hook event from stdin, one JSON object to stdout
 // agent-flow-board hooks print claude|antigravity|gemini [--org <slug>]   the settings to paste into the tool
 // agent-flow-board git-hook install|uninstall|check          the warn-only post-commit hook
+// agent-flow-board check connect|run|pull|bind|watch|status|doctor|clear|setup|disconnect   browser checks on this machine (see check usage)
 // agent-flow-board mockup push <file.html> --server <url> --org <slug> --item <ref>   upload one mockup file (never queued)
 // agent-flow-board mockup kit <file.html> --server <url> --org <slug> --project <key>   upload the project's kit (colours, fonts, icons)
 // -- DEP-MODULES -- //
@@ -95,6 +96,22 @@ async function belongsToOrg(server, org, token) {
     }
 }
 async function main() {
+    if (cmd === 'check') {
+        // Loaded only here, so the hooks and the MCP forwarder never load the check code or Playwright
+        const { checkMain } = await import('./checks/command.js');
+        const code = await checkMain({
+            args: args.slice(1),
+            store,
+            fetch: fetchImpl,
+            personalToken: (server, org) => tokenFor(server.replace(/\/$/, ''), org, true),
+            log,
+            out: (line) => process.stdout.write(line + '\n')
+        });
+        // A browser or a preview may still hold a handle open: the exit code is what the caller reads, so end now
+        process.exitCode = code;
+        setTimeout(() => process.exit(code), 300).unref();
+        return;
+    }
     if (cmd === 'hook') {
         // A hook prints exactly one JSON object and always exits 0, so it can never break the tool that runs it
         let out = {};
@@ -258,7 +275,7 @@ async function main() {
         return;
     }
     if (cmd !== 'mcp' && cmd !== 'login') {
-        log('Usage: agent-flow-board mcp|login|logout --server <url>, setup --org <slug>, queue list|retry <id>|drop <id>, or mockup push <file.html>');
+        log('Usage: agent-flow-board mcp|login|logout --server <url>, setup --org <slug>, queue list|retry <id>|drop <id>, mockup push <file.html>, or check connect|run|watch|status');
         process.exit(2);
     }
     const server = serverUrl();

package/dist/hooks/adapters.js

@@ -75,7 +75,9 @@ export const claude = {
                     hookEventName: 'SessionStart',
                     additionalContext: a.context ?? '',
                     ...(a.title ? { sessionTitle: a.title } : {})
-                }
+                },
+                // The one line for the person (an older editor status mod), shown once as the conversation starts
+                ...(a.notice ? { systemMessage: a.notice } : {})
             };
         if (event === 'prompt' && a.title)
             return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', sessionTitle: a.title } };

package/dist/hooks/call.js

@@ -4,6 +4,7 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { configDir } from '../tokenStore.js';
+import { installedModVersion } from './modVersion.js';
 // -- CONSTANTS -- //
 const TIMEOUT_MS = 4000;
 // -- FUNCTIONS -- //
@@ -57,10 +58,14 @@ export async function callHook(o, event) {
             warnOnce(`the server ${o.server} did not give an organisation for this sign-in.`);
             return null;
         }
+        // A Claude Code start tells the board which editor status mod is installed, so it can say when a newer one is served
+        const modVersion = event.tool === 'claude-code' && event.event === 'start'
+            ? installedModVersion(o.home)
+            : undefined;
         const res = await o.fetch(`${o.server}/api/v1/orgs/${org}/hooks`, {
             method: 'POST',
             headers: { authorization: `Bearer ${o.token}`, 'content-type': 'application/json' },
-            body: JSON.stringify(event),
+            body: JSON.stringify(modVersion ? { ...event, modVersion } : event),
             signal: AbortSignal.timeout(TIMEOUT_MS)
         });
         if (!res.ok)

package/dist/hooks/modVersion.js

@@ -0,0 +1,26 @@
+// THE VERSION OF THE EDITOR STATUS MOD THIS PERSON HAS INSTALLED (AFB-20261108-0856)
+// The setup prompt writes the mod to ~/.claude/skills/afb-flow-status. The hook sends the version on a start so the board can say
+// when a newer one is served. A hook must never fail or slow down because of this file, so every problem means "no version".
+// -- DEP-MODULES -- //
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// -- CONSTANTS -- //
+const MOD_FOLDER = ['.claude', 'skills', 'afb-flow-status'];
+const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;
+/** A manifest is a few hundred bytes: a file far bigger than that is not read. */
+const MAX_BYTES = 64 * 1024;
+// -- FUNCTIONS -- //
+/** The installed mod's plain major.minor.patch version, or undefined when there is no mod, no readable manifest or no plain version. */
+export function installedModVersion(home = homedir()) {
+    try {
+        const text = readFileSync(join(home, ...MOD_FOLDER, '.claude-plugin', 'plugin.json'), 'utf8');
+        if (text.length > MAX_BYTES)
+            return undefined;
+        const version = JSON.parse(text).version;
+        return typeof version === 'string' && VERSION.test(version) ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@agent-flow-board/bridge",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
-	"description": "Local bridge to an agent-flow-board server: forwards MCP calls over stdio, runs the coding tool hooks and writes the editor status. It holds no tool code.",
+	"description": "Local bridge to an agent-flow-board server: forwards MCP calls over stdio, runs the coding tool hooks, writes the editor status and runs browser checks on this machine. It holds no board tool code.",
 	"license": "MIT",
 	"homepage": "https://afb.arbenger.com",
 	"repository": {