@agent-flow-board/bridge 0.2.0 → 0.3.0

package/README.md

@@ -32,8 +32,24 @@ Needs Node 20 or later. Run it with no arguments to see its usage; the list shou
 | `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`.                                                                                                      |
 
+More check commands:
+
+| Command                                                                                   | What it does                                                                                                                                              |
+| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-flow-board check project <NAME> --org <slug> --repo <dir> [--app-dir web]`         | Registers a repo folder (and an optional app folder) for a board project, or a live site with `--url`. A repo must be inside a folder the owner approved. |
+| `agent-flow-board check approve --action <roots\|register\|secrets\|adopt-env\|pictures>` | The owner, on a terminal, gets a single-use code (10 minutes). Agents cannot make one.                                                                    |
+| `agent-flow-board check roots add\|list\|remove`                                          | The owner-approved parent folders a registration may live in (at most 5).                                                                                 |
+| `agent-flow-board check secrets import\|list\|forget`                                     | Seals test Supabase and mail values per registration (owner's code needed). Names only are ever printed.                                                  |
+| `agent-flow-board check login <NAME> --org <slug> --seeded`                               | Saves a sign in for a registration from `AFB_CHECKS_<NAME>_EMAIL` and `_PASSWORD`.                                                                        |
+| `agent-flow-board check service install\|status\|uninstall`                               | Windows: starts the worker when you sign in.                                                                                                              |
+| `agent-flow-board check import-legacy --from <afb-checks folder> --org <slug>`            | Read only: re-registers the old tool's projects and copies its check scripts.                                                                             |
+
+Runs share the machine: a slot set, one browser per host set, one database container with a clone per run, and kept dependencies and builds.
+
 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 sandboxed check can write its own run folder only. What the tool must be able to trust lives outside it: the live and end markers of a run (`checks/markers/`, checked against the names the tool derives for that run before any sweep acts on them) and the install, build, preview and mail-guard logs (`checks/logs/<run id>/`, which can hold values the app printed). Pictures and `result.json` are read from the run folder only when they are plain files (never a link), small enough, and the right kind of file. Changing the folder, the app folder, the site or the hosts of a registration that keeps an adopted `.env` or saved state needs the owner's `register` code (for a live site the code names `NAME@host`), and adopting a `.env` for another folder needs its own `adopt-env` code. A run started by hand stops after 40 minutes (`AFB_CHECKS_RUN_LIMIT_MS` changes it). Warm previews are not enabled in this version: `"warm": true` in a recipe is refused.
+
 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/appdir.js

@@ -0,0 +1,105 @@
+// THE APP FOLDER OF A PROJECT. Some repos keep the app in a subfolder (the git root has no package.json, the app and its lockfile live in web/).
+// A registration may name that folder with `appDir`; the private copy is still made from the git root, but install, build and start run in the
+// app folder, and the files that decide what runs (package.json, lockfile, recipe) are read from there. Without appDir the app folder is the repo root.
+// -- DEP-MODULES -- //
+import { existsSync, lstatSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+// -- MODULES -- //
+import { isInside } from './paths.js';
+// -- CONSTANTS -- //
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,60}$/;
+const BARRED = new Set(['.git', 'node_modules']);
+/** Names Windows keeps for devices, with or without an extension. */
+const DEVICE = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+// -- FUNCTIONS -- //
+/** The cosmetic forms (web\, ./web, web/) become one value: web. Anything else is returned as it is, for appDirText to refuse. */
+export function normalizeAppDir(raw) {
+    let s = String(raw ?? '')
+        .trim()
+        .replace(/\\/g, '/');
+    while (s.startsWith('./'))
+        s = s.slice(2);
+    s = s.replace(/\/+$/, '');
+    return s;
+}
+/** One plain sentence when `appDir` is not a plain relative folder name (or a few of them), else null. Looks at the text only. */
+export function appDirText(appDir) {
+    if (typeof appDir !== 'string' || !appDir)
+        return 'appDir must be a folder name inside the repo, for example web.';
+    if (normalizeAppDir(appDir) !== appDir)
+        return `appDir "${appDir}" must be written as plain folder names with forward slashes and no trailing slash, for example web.`;
+    if (isAbsolute(appDir) || /^[A-Za-z]:/.test(appDir) || appDir.startsWith('/'))
+        return 'appDir must be inside the repo, not an absolute path.';
+    const segments = appDir.split('/');
+    if (segments.length > 4)
+        return 'appDir may name at most 4 nested folders.';
+    for (const s of segments) {
+        if (s === '.' || s === '..')
+            return 'appDir may not contain . or .. .';
+        if (!SEGMENT.test(s))
+            return `appDir has a folder name (${s.slice(0, 40)}) with characters a plain folder name does not use.`;
+        if (BARRED.has(s.toLowerCase()))
+            return `appDir may not go through ${s}.`;
+        // Windows drops a trailing dot, so web. would be read as web while a git path web./src matches nothing
+        if (s.endsWith('.') || DEVICE.test(s))
+            return `appDir has a folder name (${s.slice(0, 40)}) that ends with a dot or is a device name.`;
+    }
+    return null;
+}
+/**
+ * Walks appDir folder by folder from `base`, without following a link: a link, a junction, a file in its place or a folder that leaves `base` is a
+ * problem. Used on the live repo when a registration is made and again on the private copy of every run.
+ */
+export function walkAppDir(base, appDir, what = 'the repo') {
+    const text = appDirText(appDir);
+    if (text)
+        return { problem: text };
+    let cur = base;
+    for (const seg of appDir.split('/')) {
+        cur = join(cur, seg);
+        let st;
+        try {
+            st = lstatSync(cur);
+        }
+        catch {
+            return {
+                problem: `The app folder ${appDir} is not in ${what}${what === 'the repo' ? '' : ' (is it committed?)'}.`
+            };
+        }
+        if (st.isSymbolicLink())
+            return {
+                problem: `The app folder ${appDir} goes through a link (${seg}), which an app folder may not do.`
+            };
+        if (!st.isDirectory())
+            return { problem: `${appDir} is not a folder in ${what}.` };
+    }
+    if (!isInside(base, cur))
+        return { problem: `The app folder ${appDir} leaves ${what}.` };
+    return { dir: cur };
+}
+/** The app folder of a config in the live repo: repo/appDir, or the repo itself. The text is not checked here. */
+export function appRoot(cfg) {
+    return cfg.appDir ? join(cfg.repo, ...cfg.appDir.split('/')) : cfg.repo;
+}
+/** The app folder inside a run's private copy (`root` is the copy of the folder that holds the app folder), or an error that stops the run. */
+export function sandboxAppRoot(root, appDir) {
+    if (!appDir)
+        return root;
+    const r = walkAppDir(root, appDir, 'the private copy of the repo');
+    if (r.problem !== undefined)
+        throw new Error(r.problem);
+    if (!existsSync(join(r.dir, 'package.json')))
+        throw new Error(`The app folder ${appDir} has no package.json in the private copy of the repo (a submodule, or not committed?).`);
+    return r.dir;
+}
+/** A problem with an app folder of a live repo: the text, the walk and the package.json. Null when it is fine. */
+export function appDirProblem(repo, appDir) {
+    const r = walkAppDir(repo, appDir);
+    if (r.problem !== undefined)
+        return r.problem;
+    if (!existsSync(join(r.dir, 'package.json')))
+        return `The app folder ${appDir} has no package.json.`;
+    return null;
+}
+/** The pathspecs of the app files relative to the git root: appPaths are relative to the app folder, so they are prefixed with it. */
+export const gitAppPaths = (appPaths, appDir) => appDir ? appPaths.map((p) => (p === '.' ? appDir : `${appDir}/${p}`)) : appPaths;

package/dist/checks/approve.js

@@ -0,0 +1,213 @@
+// THE OWNER APPROVAL CHANNEL. An agent can ask for things the owner must decide (register a live site, adopt a repo .env, widen the roots, upload pictures of a
+// signed-in run, import secrets). The owner runs `check approve --action <x> --target <name>` on an interactive terminal and gets a single-use code that is valid for
+// 10 minutes for that one action and target. The code is stored hashed (HMAC with a key in the bridge home), so the file never holds a usable code. An agent cannot
+// make a code: minting needs a terminal. This is tamper-evident, not tamper-proof: a process that runs as the same user can read the key.
+// -- DEP-MODULES -- //
+import { createHmac, randomBytes, randomInt, timingSafeEqual } from 'node:crypto';
+import { existsSync, linkSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+// -- MODULES -- //
+import { appendAudit } from './audit.js';
+import { withLockSync } from './lock.js';
+import { approvalsFile, checksHome, ensureDir } from './paths.js';
+import { renameRetry } from './fsretry.js';
+// -- CONSTANTS -- //
+export const APPROVAL_ACTIONS = [
+    'register',
+    'secrets',
+    'adopt-env',
+    'roots',
+    'pictures'
+];
+/** A code is valid for ten minutes. */
+export const APPROVAL_TTL_MS = 10 * 60 * 1000;
+const MAX_CODES = 20;
+const ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+const CODE_LENGTH = 12;
+// -- FUNCTIONS -- //
+/** A refusal the owner or the agent can read: one plain sentence. The command handlers turn it into exit code 1. */
+export class Refusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'Refusal';
+    }
+}
+/** A mistake in how a command was typed (exit code 2). */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+export const isApprovalAction = (v) => APPROVAL_ACTIONS.includes(v);
+/** Writes a temporary file in the same folder and renames it over the real one, so a reader never sees half a file. */
+export function writeFileAtomic(file, text) {
+    ensureDir(dirname(file));
+    const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        writeFileSync(temp, text, { mode: 0o600 });
+        renameRetry(temp, file);
+    }
+    catch (e) {
+        rmSync(temp, { force: true });
+        throw e;
+    }
+}
+const keyFile = () => join(checksHome(), 'approval.key');
+/** The HMAC key of the approvals, the sealed roots and the registration files. Created once, whole, with mode 0600 (linked into place so nobody reads half of it). */
+export function approvalKey() {
+    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 });
+        }
+    }
+    const key = Buffer.from(readFileSync(file, 'utf8').trim(), 'hex');
+    if (key.length !== 32)
+        throw new Error('The approval key file is damaged. Remove it and approve again.');
+    return key;
+}
+/** HMAC-SHA256 hex of a text under the approval key, with a purpose word so one seal can never stand for another. */
+export function seal(purpose, text) {
+    return createHmac('sha256', approvalKey()).update(`${purpose}\0${text}`).digest('hex');
+}
+/** True when two hex strings are equal, compared in constant time. */
+export function sameMac(a, b) {
+    return a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+/**
+ * The target as it is compared: a name is lower cased, a folder (the `roots` action) is its real path when it exists, else its resolved path, lower cased on Windows.
+ * The owner and the agent may therefore write the same target in different spellings.
+ */
+export function normaliseTarget(action, target) {
+    const text = String(target ?? '').trim();
+    if (!text || text.length > 400)
+        throw new Refusal('An approval needs a target (a name or a folder).');
+    if (action !== 'roots')
+        return text.toLowerCase();
+    let full = resolve(text);
+    try {
+        full = realpathSync.native(full);
+    }
+    catch {
+        /* A folder that is gone is compared by the path as written */
+    }
+    return process.platform === 'win32' ? full.toLowerCase() : full;
+}
+function normaliseCode(code) {
+    const text = String(code ?? '')
+        .toUpperCase()
+        .replace(/[\s-]/g, '');
+    return new RegExp(`^[${ALPHABET}]{${CODE_LENGTH}}$`).test(text) ? text : null;
+}
+const macOf = (action, target, code) => seal('approval', `${action}\0${target}\0${code}`);
+function readEntries() {
+    try {
+        const v = JSON.parse(readFileSync(approvalsFile(), 'utf8'));
+        const list = v && typeof v === 'object' ? v.codes : null;
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const e of list) {
+            if (!e || typeof e !== 'object')
+                continue;
+            const { h, action, target, exp } = e;
+            if (typeof h === 'string' &&
+                typeof action === 'string' &&
+                isApprovalAction(action) &&
+                typeof target === 'string' &&
+                typeof exp === 'number')
+                out.push({ h, action, target, exp });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+const writeEntries = (codes) => writeFileAtomic(approvalsFile(), JSON.stringify({ version: 1, codes }, null, 2) + '\n');
+/**
+ * Makes a single-use code for one action and target. Needs an interactive terminal: `isTTY` is passed in by the caller (the command passes the real flag, a test
+ * passes true or false), and without it nothing is made. An older code for the same action and target is replaced.
+ */
+export function mintApproval(action, target, opts) {
+    if (!opts.isTTY)
+        throw new Refusal('An approval code is made by the owner on an interactive terminal. This is not one, so no code was made.');
+    if (!isApprovalAction(action))
+        throw new Refusal(`"${action.slice(0, 30)}" is not an action (${APPROVAL_ACTIONS.join(', ')}).`);
+    const now = opts.now ?? Date.now();
+    const norm = normaliseTarget(action, target);
+    let code = '';
+    for (let i = 0; i < CODE_LENGTH; i++)
+        code += ALPHABET[randomInt(ALPHABET.length)];
+    const exp = now + APPROVAL_TTL_MS;
+    withLockSync('approvals', () => {
+        const kept = readEntries().filter((e) => e.exp > now && !(e.action === action && e.target === norm));
+        kept.push({ h: macOf(action, norm, code), action, target: norm, exp });
+        writeEntries(kept.slice(-MAX_CODES));
+    });
+    appendAudit('approval minted', { action, target: norm, minutes: APPROVAL_TTL_MS / 60000 });
+    return {
+        code: `${code.slice(0, 4)}-${code.slice(4, 8)}-${code.slice(8)}`,
+        expiresAt: new Date(exp).toISOString()
+    };
+}
+/**
+ * True when the code is valid for this action and target right now, without using it. A command with several codes checks all of them with this first and uses them
+ * (consumeApproval) last, so a wrong code never burns the right ones.
+ */
+export function peekApproval(action, target, code, now = Date.now()) {
+    if (!isApprovalAction(action))
+        return false;
+    const plain = normaliseCode(code);
+    if (!plain)
+        return false;
+    let norm;
+    try {
+        norm = normaliseTarget(action, target);
+    }
+    catch {
+        return false;
+    }
+    const want = macOf(action, norm, plain);
+    return readEntries().some((e) => e.exp > now && e.action === action && sameMac(e.h, want));
+}
+/** True once for a valid code of this action and target, and false for a wrong action, a wrong target, an expired, a used or an unknown code. */
+export function consumeApproval(action, target, code, now = Date.now()) {
+    if (!isApprovalAction(action))
+        return false;
+    const plain = normaliseCode(code);
+    if (!plain)
+        return false;
+    let norm;
+    try {
+        norm = normaliseTarget(action, target);
+    }
+    catch {
+        return false;
+    }
+    const want = macOf(action, norm, plain);
+    let hit = false;
+    withLockSync('approvals', () => {
+        const all = readEntries();
+        const live = all.filter((e) => e.exp > now);
+        const found = live.find((e) => e.action === action && sameMac(e.h, want));
+        hit = found !== undefined;
+        const rest = found ? live.filter((e) => e !== found) : live;
+        if (hit || rest.length !== all.length)
+            writeEntries(rest);
+    });
+    if (hit)
+        appendAudit('approved with code', { action, target: norm });
+    return hit;
+}

package/dist/checks/audit.js

@@ -3,11 +3,12 @@
 // 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 { appendFileSync, existsSync, linkSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 // -- MODULES -- //
 import { withLockSync } from './lock.js';
 import { auditFile, checksHome, ensureDir } from './paths.js';
+import { renameRetry } from './fsretry.js';
 // -- CONSTANTS -- //
 const MAX_ACTION = 40;
 const MAX_VALUE = 200;
@@ -81,7 +82,7 @@ export function appendAudit(action, detail = {}) {
         const head = { lines: lines.length + 1, head: mac };
         const tmp = `${headFile()}.${process.pid}.tmp`;
         writeFileSync(tmp, JSON.stringify(head), { mode: 0o600 });
-        renameSync(tmp, headFile());
+        renameRetry(tmp, headFile());
     });
 }
 function readHead() {

package/dist/checks/bind.js

@@ -2,10 +2,11 @@
 // 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 { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 // -- MODULES -- //
 import { bindingsFile, ensureDir, ORG_SLUG } from './paths.js';
+import { renameRetry } from './fsretry.js';
 import { checkRepoFolder } from './guardrails.js';
 import { pinFiles } from './recipe.js';
 // -- CONSTANTS -- //
@@ -44,7 +45,7 @@ function writeAll(bindings) {
     const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
     try {
         writeFileSync(temp, JSON.stringify({ version: 1, bindings }, null, 2) + '\n', { mode: 0o600 });
-        renameSync(temp, file);
+        renameRetry(temp, file);
     }
     catch (e) {
         rmSync(temp, { force: true });