@agent-flow-board/bridge 0.1.0 → 0.3.0

package/README.md

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

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

package/dist/checks/bind.js

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