@agent-flow-board/bridge 0.2.0 → 0.3.0

package/dist/checks/command.js

@@ -4,19 +4,22 @@
 // -- DEP-MODULES -- //
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 // -- MODULES -- //
-import { verifyAudit } from './audit.js';
-import { bindFolder, listBindings, pinStatus } from './bind.js';
-import { ensureBrowser, playwrightRuntimeDir } from './browser.js';
+import { bindFolder } from './bind.js';
+import { ensureBrowser } from './browser.js';
 import { connectChecks, loadRunnerToken, runnerAccount } from './connect.js';
-import { forgetConnection, listConnections, recordConnection } from './connections.js';
-import { ORG_SLUG, checksHome, scriptPath } from './paths.js';
+import { 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 { clearRuns, sweepOrphans } from './scope.js';
-import { permissionFlag } from './sandbox.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>',
@@ -25,14 +28,36 @@ export const CHECK_USAGE = [
     '  pull <item> <key> --server <url> --org <slug> [--accept-hash <sha256>]   read the board copy of a script; accept it by hash',
     '  bind --org <slug> --project <KEY> [--dir <repo>]   remember the folder of a board project for "check watch"',
     '  watch [--parallel N] [--once]   take queued runs from the boards this machine is connected to',
-    '  status [--json]  |  doctor [--fix] [--json]  |  clear [--all]  |  setup  |  disconnect --server <url> --org <slug>'
+    '  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];
-    const flag = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+    // 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) => {
@@ -83,12 +108,27 @@ export async function checkMain(ctx) {
             return 0;
         }
         if (sub === 'run') {
-            const item = args[1];
-            const key = args[2];
+            // `--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>');
+                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`);
@@ -100,6 +140,7 @@ export async function checkMain(ctx) {
                 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,
@@ -162,6 +203,25 @@ export async function checkMain(ctx) {
             }));
             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');
@@ -180,7 +240,8 @@ export async function checkMain(ctx) {
                 store: ctx.store,
                 fetch: ctx.fetch,
                 log,
-                parallel: Number(flag('--parallel') ?? 3) || 3,
+                // 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
             });
@@ -192,13 +253,6 @@ export async function checkMain(ctx) {
             log('The browser is ready.');
             return 0;
         }
-        if (sub === 'status' || sub === 'doctor')
-            return await statusOrDoctor(ctx, sub === 'doctor', has('--fix'), json);
-        if (sub === 'clear') {
-            const r = clearRuns({ all: has('--all') });
-            log(`Removed ${r.removed} finished run folder(s).`);
-            return 0;
-        }
         log(CHECK_USAGE);
         return 2;
     }
@@ -211,70 +265,3 @@ export async function checkMain(ctx) {
         return 2;
     }
 }
-async function statusOrDoctor(ctx, doctor, fix, json) {
-    const problems = [];
-    const audit = verifyAudit();
-    if (!audit.ok)
-        problems.push({
-            problem: 'The audit log does not verify (it was edited or cut).',
-            next: 'Do not edit it. Move checks/audit.log aside to start a new chain.'
-        });
-    if (!permissionFlag())
-        problems.push({
-            problem: 'This Node has no permission model, so check scripts cannot be sandboxed.',
-            next: 'Install Node 20.18 or later (or any Node 22).'
-        });
-    if (!playwrightRuntimeDir()) {
-        if (doctor && fix)
-            await ensureBrowser(ctx.log);
-        else
-            problems.push({
-                problem: 'The browser is not installed.',
-                next: 'Run: agent-flow-board check setup'
-            });
-    }
-    const swept = doctor && fix ? await sweepOrphans(ctx.log) : 0;
-    const connections = listConnections().map((c) => ({
-        ...c,
-        connected: Boolean(loadRunnerToken(ctx.store, c.server, c.org))
-    }));
-    for (const c of connections)
-        if (!c.connected)
-            problems.push({
-                problem: `${c.org} on ${c.server} has no runner token.`,
-                next: `Run: agent-flow-board check connect --server ${c.server} --org ${c.org} --json`
-            });
-    const bindings = listBindings().map((b) => ({
-        org: b.org,
-        project: b.projectKey,
-        folder: b.folder,
-        pin: pinStatus(b.org, b.projectKey)
-    }));
-    for (const b of bindings)
-        if (b.pin !== 'ok')
-            problems.push({
-                problem: `${b.org}/${b.project}: the files that decide what runs changed in ${b.folder}.`,
-                next: `In that folder run a check once: agent-flow-board check run <item> <key> --org ${b.org}`
-            });
-    const state = {
-        home: checksHome(),
-        connections,
-        bindings,
-        audit: { ok: audit.ok, lines: audit.lines },
-        browser: Boolean(playwrightRuntimeDir()),
-        swept,
-        problems
-    };
-    if (json)
-        ctx.out(JSON.stringify(state));
-    else {
-        ctx.log(`State folder: ${state.home}`);
-        ctx.log(`Connections: ${connections.map((c) => `${c.org}@${c.server}${c.connected ? '' : ' (no token)'}`).join(', ') || 'none'}`);
-        ctx.log(`Bound folders: ${bindings.map((b) => `${b.org}/${b.project} -> ${b.folder} (${b.pin})`).join('; ') || 'none'}`);
-        for (const p of problems)
-            ctx.log(`Problem: ${p.problem} Next: ${p.next}`);
-        if (!problems.length)
-            ctx.log('Nothing is wrong.');
-    }
-    return doctor && problems.length ? 1 : 0;
-}

package/dist/checks/commands.js

@@ -0,0 +1,219 @@
+// THE COMMANDS `check project`, `check approve` AND `check roots`. Plain handlers: they take the arguments after the command word and a small context, print through it and return
+// an exit code (0 done, 1 refused with the problems listed, 2 could not run). Nothing here reads a terminal. `check approve` only asks whether it IS on a terminal, because a code is
+// made by the owner and never by an agent.
+// -- DEP-MODULES -- //
+import { isatty } from 'node:tty';
+// -- MODULES -- //
+import { APPROVAL_ACTIONS, Refusal, UsageError, isApprovalAction, mintApproval } from './approve.js';
+import { forgetRegistration, hasState, pinRegistration, pinState, readRegistrations, registerProject } from './registry.js';
+import { addRoot, listRoots, readRoots, removeRoot } from './roots.js';
+// -- CONSTANTS -- //
+const BOOLEAN_FLAGS = new Set([
+    '--recipe',
+    '--remove',
+    '--adopt-env',
+    '--upload-pictures',
+    '--json'
+]);
+// -- FUNCTIONS -- //
+function parse(args) {
+    const pos = [];
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] ?? '';
+        if (!a.startsWith('--')) {
+            pos.push(a);
+            continue;
+        }
+        const eq = a.indexOf('=');
+        if (eq > 0) {
+            flags.set(a.slice(0, eq), a.slice(eq + 1));
+        }
+        else if (BOOLEAN_FLAGS.has(a)) {
+            flags.set(a, true);
+        }
+        else {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('--'))
+                throw new UsageError(`${a} needs a value.`);
+            flags.set(a, next);
+            i++;
+        }
+    }
+    return { pos, flags };
+}
+const text = (p, name) => {
+    const v = p.flags.get(name);
+    return typeof v === 'string' ? v : undefined;
+};
+function need(p, name) {
+    const v = text(p, name);
+    if (!v)
+        throw new UsageError(`${name} is needed.`);
+    return v;
+}
+/** Runs a handler body and turns what it throws into an exit code and one plain line. */
+async function guarded(ctx, body) {
+    try {
+        return await body();
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        ctx.log(message);
+        return e instanceof Refusal ? 1 : 2;
+    }
+}
+const show = (ctx, value, lines) => {
+    if (ctx.json)
+        ctx.out(JSON.stringify(value));
+    else
+        for (const l of lines)
+            ctx.out(l);
+};
+export const PROJECT_USAGE = [
+    '  project <NAME> --org <slug> --repo <dir> [--app-dir web] [--board-project KEY] [--recipe] [--extra-hosts a,b]',
+    '  project <NAME> --org <slug> --url https://site [--board-project KEY] [--extra-hosts a,b] --approval <code>',
+    '  project list [--org <slug>]  |  project forget <NAME> --org <slug> [--remove]  |  project pin <NAME> --org <slug>'
+].join('\n');
+/** `check project ...`: register, list, forget or pin a registration. */
+export async function projectCommand(args, ctx) {
+    return guarded(ctx, async () => {
+        const p = parse(args);
+        const json = ctx.json || p.flags.has('--json');
+        const c = { ...ctx, json };
+        const sub = p.pos[0];
+        if (!sub)
+            throw new UsageError(`Say what to do.\n${PROJECT_USAGE}`);
+        if (sub === 'list') {
+            const org = text(p, '--org');
+            const { registrations, problems } = readRegistrations(org);
+            const rows = registrations.map((r) => ({
+                org: r.org,
+                name: r.name,
+                boardProject: r.boardProject,
+                kind: r.url ? 'site' : 'repo',
+                repo: r.repo ?? null,
+                appDir: r.appDir ?? null,
+                url: r.url ?? null,
+                pin: pinState(r),
+                adoptEnv: r.adoptEnv,
+                state: hasState(r.org, r.name)
+            }));
+            show(c, { registrations: rows, problems }, [
+                ...rows.map((r) => `${r.org}/${r.name}  serves ${r.boardProject}  ${r.url ?? `${r.repo}${r.appDir ? ` (${r.appDir})` : ''}`}  pin ${r.pin}${r.adoptEnv ? '  adopts .env' : ''}${r.state ? '  holds state' : ''}`),
+                ...(rows.length ? [] : ['No registrations.']),
+                ...problems
+            ]);
+            return problems.length ? 1 : 0;
+        }
+        if (sub === 'forget') {
+            const name = p.pos[1];
+            if (!name)
+                throw new UsageError('forget needs a registration name.');
+            const r = forgetRegistration(need(p, '--org'), name, { remove: p.flags.has('--remove') });
+            show(c, r, [
+                `${r.removed ? 'Removed' : 'Forgot the saved state of'} ${r.name}${r.hadState ? '' : ' (it held none)'}.`
+            ]);
+            return 0;
+        }
+        if (sub === 'pin') {
+            const name = p.pos[1];
+            if (!name)
+                throw new UsageError('pin needs a registration name.');
+            const r = pinRegistration(need(p, '--org'), name);
+            show(c, { ...r, before: r.before?.slice(0, 12) ?? null, after: r.after.slice(0, 12) }, [
+                r.changed
+                    ? `Pinned ${r.name}: ${r.before ? r.before.slice(0, 12) : 'none'} -> ${r.after.slice(0, 12)} (${r.files.join(', ') || 'no files'}).`
+                    : `${r.name} is already pinned (${r.after.slice(0, 12)}).`
+            ]);
+            return 0;
+        }
+        if (p.pos.length > 1)
+            throw new UsageError(`Unexpected "${p.pos[1]}".\n${PROJECT_USAGE}`);
+        const hosts = text(p, '--extra-hosts');
+        const input = {
+            org: need(p, '--org'),
+            name: sub,
+            ...(text(p, '--board-project') ? { boardProject: text(p, '--board-project') } : {}),
+            ...(text(p, '--repo') ? { repo: text(p, '--repo') } : {}),
+            ...(text(p, '--app-dir') ? { appDir: text(p, '--app-dir') } : {}),
+            ...(text(p, '--url') ? { url: text(p, '--url') } : {}),
+            ...(hosts
+                ? {
+                    extraHosts: hosts
+                        .split(',')
+                        .map((h) => h.trim())
+                        .filter(Boolean)
+                }
+                : {}),
+            recipe: p.flags.has('--recipe'),
+            adoptEnv: p.flags.has('--adopt-env'),
+            uploadSignedInPictures: p.flags.has('--upload-pictures')
+        };
+        const approvals = {
+            ...(text(p, '--approval') ? { register: text(p, '--approval') } : {}),
+            ...(text(p, '--adopt-env-approval')
+                ? { adoptEnv: text(p, '--adopt-env-approval') }
+                : {}),
+            ...(text(p, '--pictures-approval')
+                ? { pictures: text(p, '--pictures-approval') }
+                : {})
+        };
+        const reg = registerProject(input, approvals);
+        show(c, { org: reg.org, name: reg.name, boardProject: reg.boardProject, database: reg.database }, [
+            `Registered ${reg.org}/${reg.name} for ${reg.boardProject}${reg.url ? ` (live site ${new URL(reg.url).hostname})` : ''}. The files that decide what runs are pinned by "check project pin ${reg.name} --org ${reg.org}" or the first run in the folder.`
+        ]);
+        return 0;
+    });
+}
+/**
+ * `check approve --action <register|secrets|adopt-env|roots|pictures> --target <name or folder>`: the owner's single-use code. Refused without an interactive terminal.
+ * `env.isTTY` is for the tests; the command itself passes the real flag of the terminal.
+ */
+export async function approveCommand(args, ctx, env = {}) {
+    return guarded(ctx, () => {
+        const p = parse(args);
+        const action = need(p, '--action');
+        if (!isApprovalAction(action))
+            throw new UsageError(`--action is one of ${APPROVAL_ACTIONS.join(', ')}.`);
+        const target = need(p, '--target');
+        const isTTY = env.isTTY ?? (isatty(0) && isatty(1));
+        const made = mintApproval(action, target, { isTTY });
+        show(ctx, { action, target, code: made.code, expiresAt: made.expiresAt }, [
+            `Approval code for ${action} on ${target}: ${made.code}`,
+            `It works once and expires at ${made.expiresAt}. Give it to the command that asked for it, with --approval.`
+        ]);
+        return 0;
+    });
+}
+/** `check roots add <dir> --approval <code> | list | remove <dir> --approval <code>`. */
+export async function rootsCommand(args, ctx) {
+    return guarded(ctx, () => {
+        const p = parse(args);
+        const sub = p.pos[0] ?? 'list';
+        if (sub === 'list') {
+            const { roots, problem } = readRoots();
+            show(ctx, { roots, problem }, [
+                ...(roots.length
+                    ? roots
+                    : ['No roots. The owner adds one: check roots add <folder> --approval <code>.']),
+                ...(problem ? [problem] : [])
+            ]);
+            return problem ? 1 : 0;
+        }
+        const dir = p.pos[1];
+        if (!dir)
+            throw new UsageError(`${sub} needs a folder.`);
+        if (sub === 'add') {
+            const real = addRoot(dir, text(p, '--approval'));
+            show(ctx, { root: real, roots: listRoots() }, [`Root added: ${real}`]);
+            return 0;
+        }
+        if (sub === 'remove') {
+            const real = removeRoot(dir, text(p, '--approval'));
+            show(ctx, { root: real, roots: listRoots() }, [`Root removed: ${real}`]);
+            return 0;
+        }
+        throw new UsageError('Use: roots add <dir> --approval <code> | roots list | roots remove <dir> --approval <code>');
+    });
+}

package/dist/checks/connections.js

@@ -1,10 +1,11 @@
 // THE BOARDS THIS MACHINE IS CONNECTED TO FOR CHECKS: SERVER AND ORGANISATION ONLY, NEVER A TOKEN (THE TOKEN IS IN THE TOKEN STORE)
 // `check watch` re-reads this list on every loop, so a `check connect` for a second organisation is picked up without a restart.
 // -- DEP-MODULES -- //
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 // -- MODULES -- //
 import { checksHome, ensureDir, ORG_SLUG } from './paths.js';
+import { renameRetry } from './fsretry.js';
 // -- FUNCTIONS -- //
 const file = () => join(checksHome(), 'connections.json');
 export function listConnections() {
@@ -30,12 +31,12 @@ export function recordConnection(c) {
     ensureDir(checksHome());
     const tmp = `${file()}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify(next, null, 1), { mode: 0o600 });
-    renameSync(tmp, file());
+    renameRetry(tmp, file());
 }
 export function forgetConnection(server, org) {
     const next = listConnections().filter((x) => !(x.server === server && x.org === org));
     ensureDir(checksHome());
     const tmp = `${file()}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify(next, null, 1), { mode: 0o600 });
-    renameSync(tmp, file());
+    renameRetry(tmp, file());
 }