@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/guard.js

@@ -0,0 +1,188 @@
+// GUARDS: WHAT A PAGE MAY REACH, WHAT IT MAY CHANGE, AND WHAT A CHECK IS HANDED.
+// Layer one is the browser itself: every host except the preview's is unresolvable (see browser.ts), whatever a check does with routes.
+// Layer two counts and stops writes. Layer three hands a check a facade of the page that cannot lead back to the context or the cookies.
+// This file imports nothing at runtime, so the sandboxed child can load it. Playwright is only described here by the few members it calls.
+// -- CONSTANTS -- //
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const HIDDEN = new Set([
+    'context',
+    'request',
+    'route',
+    'unroute',
+    'unrouteAll',
+    'routeFromHAR',
+    'routeWebSocket',
+    'addInitScript',
+    'exposeFunction',
+    'exposeBinding',
+    'video',
+    'pause',
+    'browser',
+    'page',
+    'mainFrame',
+    'frames',
+    'frame',
+    'parentFrame',
+    'childFrames',
+    'opener',
+    'storageState',
+    'cookies',
+    'addCookies',
+    'clearCookies',
+    'newPage',
+    'newContext',
+    'newCDPSession'
+]);
+// Only Playwright's own objects are wrapped: plain data (what evaluate returns) is handed over as it is
+const WRAPPED = /^_?(Locator|FrameLocator|Frame|ElementHandle|JSHandle|Response|Request|Keyboard|Mouse|Touchscreen|Dialog|Download|FileChooser|ConsoleMessage|Worker|WebSocket|Page)$/;
+const NODE_MODULES = 'fs|fs/promises|child_process|net|http|https|http2|dgram|dns|tls|worker_threads|vm|os|cluster|module|v8|inspector|repl|readline|stream|zlib|crypto|perf_hooks|async_hooks|wasi|tty|process';
+const UNSAFE = [
+    [/\bchild_process\b/, 'child_process'],
+    [/node:(net|http|https|http2|dgram|dns|tls|worker_threads|vm)\b/, 'a network or process module'],
+    [/\brequire\s*\(/, 'require()'],
+    [
+        new RegExp(`\\bfrom\\s+['"](?:node:)?(?:${NODE_MODULES})['"]`),
+        'a module of Node other than path and url'
+    ],
+    [
+        new RegExp(`\\bimport\\s+['"](?:node:)?(?:${NODE_MODULES})['"]`),
+        'a module of Node other than path and url'
+    ],
+    [/\bprocess\.(env|binding|kill|exit|getBuiltinModule)\b/, 'process'],
+    [/\bfetch\s*\(/, 'fetch()'],
+    [/\bXMLHttpRequest\b/, 'XMLHttpRequest'],
+    [/\bWebSocket\b/, 'WebSocket'],
+    // A dynamic import is fine only for a file next to the check (a relative name written out in full)
+    [/\bimport\s*\(\s*(?!['"]\.{1,2}\/)/, 'a dynamic import of a name that is not a relative file'],
+    [/node:fs|\bfrom\s+['"]fs['"]/, 'the file system'],
+    [/\bprofiles\b/, 'the profiles folder'],
+    [
+        /\.(page|context|browser|cookies|storageState|mainFrame|frames|frame|newPage|newContext|route|unroute|routeFromHAR|routeWebSocket|addInitScript|exposeFunction|exposeBinding)\s*\(|\.request\b/,
+        'a way back to the browser context'
+    ],
+    [
+        /\bgetBuiltinModule\b|\bglobalThis\b|\bFunction\s*\(|\beval\s*\(|\[\s*['"]constructor['"]\s*\]/,
+        'a way around the checks'
+    ]
+];
+// -- FUNCTIONS -- //
+export const hostOf = (url) => {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return '';
+    }
+};
+const sameOrigin = (url, origin) => {
+    try {
+        return new URL(url).origin === origin;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Stops every write and counts what it stopped. A page that submits a form is answered with nothing so it stays where it is.
+ * Writes are only let through when the person said so for this run (allowWrites).
+ */
+export async function guardContext(ctx, { origin, allowWrites = false, extraHosts = [], onBlocked = () => { } }) {
+    const counts = { writes: 0, outside: 0 };
+    await ctx.route('**/*', async (route) => {
+        const req = route.request();
+        const url = req.url();
+        if (url.startsWith('data:') || url.startsWith('blob:'))
+            return route.continue();
+        if (!sameOrigin(url, origin) && !extraHosts.includes(hostOf(url))) {
+            counts.outside++;
+            onBlocked(`blocked a request to ${hostOf(url)}`);
+            return route.abort();
+        }
+        if (!READ_METHODS.has(req.method()) && !allowWrites) {
+            counts.writes++;
+            onBlocked(`stopped a ${req.method()} to ${new URL(url).pathname}`);
+            return req.resourceType() === 'document'
+                ? route.fulfill({ status: 204, body: '' })
+                : route.abort();
+        }
+        return route.continue();
+    });
+    return counts;
+}
+const refuse = (prop) => () => {
+    throw new Error(`${prop} is not available to a check. Checks drive the page; the tool keeps the session and the network rules.`);
+};
+const isThenable = (v) => typeof v.then === 'function';
+/** Wraps something a page returned (a locator, a response, a promise of one) so it can never lead back to the context. */
+function wrap(value, guard) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (isThenable(value))
+        return value.then((v) => wrap(v, guard));
+    if (Array.isArray(value))
+        return value.map((v) => wrap(v, guard));
+    const name = value.constructor?.name ?? '';
+    if (!WRAPPED.test(name))
+        return value;
+    return proxy(value, guard);
+}
+const originals = new WeakMap();
+/** The real object behind something a check was handed, for the tool's own use (expect needs the real locator). */
+export const unwrap = (v) => typeof v === 'object' && v !== null ? (originals.get(v) ?? v) : v;
+function proxy(value, guard) {
+    const made = new Proxy(value, {
+        get(target, prop) {
+            if (typeof prop === 'string' && HIDDEN.has(prop))
+                return new Proxy(refuse(prop), {
+                    get: refuse(prop),
+                    apply: refuse(prop),
+                    set: refuse(prop)
+                });
+            // expect() talks to a locator through its internal _expect and nothing else
+            if (typeof prop === 'string' && prop.startsWith('_') && prop !== '_expect')
+                return undefined;
+            const v = Reflect.get(target, prop, target);
+            // Symbols and the constructor are handed over as they are, so instanceof checks and expect() still recognise a locator
+            if (typeof prop === 'symbol' || prop === 'constructor')
+                return v;
+            if (typeof v !== 'function')
+                return wrap(v, guard);
+            return (...args) => {
+                if (prop === 'goto')
+                    guard.assertNavigable(args[0]);
+                return wrap(v.apply(target, args), guard);
+            };
+        }
+    });
+    originals.set(made, value);
+    return made;
+}
+/** What a check receives instead of the real page: no context, no cookies, no request client, no routes, and no way back to them through a frame, a locator or a response. */
+export function pageForCheck(page, { origin, extraHosts = [] } = {}) {
+    const guard = {
+        assertNavigable(url) {
+            const u = String(url ?? '');
+            if (u.startsWith('/') && !u.startsWith('//'))
+                return;
+            let parsed;
+            try {
+                parsed = new URL(u);
+            }
+            catch {
+                throw new Error(`The check tried to open "${u.slice(0, 60)}", which is not an address of the app under test.`);
+            }
+            if (!['http:', 'https:'].includes(parsed.protocol) ||
+                (origin && parsed.origin !== origin && !extraHosts.includes(parsed.hostname)))
+                throw new Error(`The check tried to open ${parsed.protocol}//${parsed.host}, which is not the app under test.`);
+        }
+    };
+    return proxy(page, guard);
+}
+/** A speed bump, not a wall: names what a check does that a check has no business doing. Refused unless the person says --allow-unsafe. */
+export function lintCheck(source) {
+    const found = [];
+    for (const [re, label] of UNSAFE)
+        if (re.test(source) && !found.includes(label))
+            found.push(label);
+    return found;
+}

package/dist/checks/guardrails.js

@@ -0,0 +1,155 @@
+// THE GUARDRAILS OF THE CHECK COMMANDS. THEY ARE CONSTANTS IN THIS FILE, NEVER DATA: NOTHING IN THE REPO UNDER TEST OR IN A RECIPE CAN WIDEN THEM.
+// WHAT THIS DOES AND DOES NOT PROTECT. The preview runs the code of the repo under test, and the agent writes that code. So no rule here can
+// stop an agent that means harm: it could put anything in the app. The rules stop mistakes and keep real things safe: the database that holds
+// real data, the ports of the servers a person runs, the programs a build is allowed to start, and folders that were never meant to be built.
+// -- DEP-MODULES -- //
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, parse, resolve, sep } from 'node:path';
+// -- MODULES -- //
+import { configDir } from '../tokenStore.js';
+// -- CONSTANTS -- //
+/** Never used by a check: the dev server, the build preview that is served, and the local Docker PostgreSQL that holds real data. */
+export const FORBIDDEN_PORTS = new Set([5180, 5190, 5433]);
+/** The only flags of a build or start command, besides the script name. Anything else could run a file the agent wrote. */
+const ARG_OK = /^(--port|\{port\}|--host|127\.0\.0\.1|--strictPort|--)$/;
+/** The one word a script may be given besides flags: what a database command should do. */
+const SUBCOMMAND_OK = /^migrate$/;
+const WORD = /^[A-Za-z0-9_:.@-]+$/;
+/**
+ * What the body of a package.json script may be: a known build or preview program with a plain command and plain flags. A body that runs a
+ * file, chains commands or sets variables is refused, because that is where an arbitrary program would hide.
+ */
+const BODY_OK = /^(vite|svelte-kit|next|astro|nuxt|nuxi|remix) [a-z][a-z-]*( --?[A-Za-z][A-Za-z-]*( [A-Za-z0-9_.:{}/-]+)?){0,4}$/;
+/** Folders that hold keys and logins: a build never runs inside or at one of them. */
+const SECRET_FOLDERS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker'];
+// -- FUNCTIONS -- //
+const hasPort = (text, port) => new RegExp(`(^|[^0-9])${port}([^0-9]|$)`).test(text);
+/** Paths compare without case on Windows only. */
+const same = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const insideOrSame = (parent, child) => {
+    const p = process.platform === 'win32' ? parent.toLowerCase() : parent;
+    const c = process.platform === 'win32' ? child.toLowerCase() : child;
+    return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+};
+/** One plain sentence when a package.json script is not a plain build or preview command, else null. */
+export function scriptBodyProblem(name, scripts) {
+    const body = String(scripts[name] ?? '');
+    if (!BODY_OK.test(body))
+        return `The script "${name}" runs "${body}", which is not a plain build or preview command (vite, svelte-kit, next, astro, nuxt or remix with plain flags).`;
+    // A script body may not name a port a check never uses, nor bind to anything but this machine
+    for (const p of FORBIDDEN_PORTS)
+        if (hasPort(body, p))
+            return `The script "${name}" mentions port ${p}, which a check never uses.`;
+    const host = /--host(?:\s+(\S+))?/.exec(body);
+    if (host && host[1] !== '127.0.0.1')
+        return `The script "${name}" binds the preview to something other than 127.0.0.1.`;
+    // A pre or post script runs by itself around it, so it is held to the same rule
+    for (const hook of [`pre${name}`, `post${name}`])
+        if (Object.prototype.hasOwnProperty.call(scripts, hook) && !BODY_OK.test(String(scripts[hook])))
+            return `The script "${hook}" runs by itself around "${name}" and is "${scripts[hook]}", which is not a plain build or preview command.`;
+    return null;
+}
+/**
+ * One plain sentence when a build or start command is outside the allowed forms, else null. Allowed: `yarn|npm|pnpm [run] <script>` where the
+ * script is named in package.json and its body is a plain build or preview command, with only the flags above. No shell characters, no `..`,
+ * no other program, and not `node <file>`: a file is where the agent's own program would run.
+ */
+export function commandProblem(cmd, scripts, what) {
+    const text = String(cmd ?? '').trim();
+    if (!text)
+        return `${what} is empty.`;
+    if (/[&|;<>`$()\\\r\n"'*?%^!]/.test(text) || text.includes('..'))
+        return `${what} "${text}" has a character a shell would act on.`;
+    const t = text.split(/\s+/);
+    if (!['yarn', 'npm', 'pnpm'].includes(t[0]))
+        return `${what} "${text}" starts with ${t[0]}. Only yarn, npm or pnpm running a package.json script are allowed.`;
+    let i = 1;
+    if (t[i] === 'run')
+        i++;
+    const script = t[i];
+    if (!script || !WORD.test(script))
+        return `${what} "${text}" names no package.json script.`;
+    if (!Object.prototype.hasOwnProperty.call(scripts, script))
+        return `${what} "${text}" runs "${script}", which is not a script in package.json.`;
+    const body = scriptBodyProblem(script, scripts);
+    if (body)
+        return `${what} "${text}": ${body}`;
+    const rest = t.slice(i + 1);
+    for (let j = 0; j < rest.length; j++) {
+        if (j === 0 && SUBCOMMAND_OK.test(rest[j]))
+            continue;
+        if (!ARG_OK.test(rest[j]))
+            return `${what} "${text}" has the argument ${rest[j]}, which is not one of --port, --host 127.0.0.1 or --strictPort.`;
+        if (rest[j] === '--host' && rest[j + 1] !== '127.0.0.1')
+            return `${what} "${text}" binds the preview to something other than 127.0.0.1.`;
+        if (rest[j] === '--port' && rest[j + 1] !== '{port}')
+            return `${what} "${text}" fixes the port. It must be {port}, so the tool picks a free one.`;
+    }
+    return null;
+}
+/** True when the folder is a git project or sits inside one (a .git folder or file here or in a parent). */
+function insideGit(folder) {
+    let dir = folder;
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return true;
+        const up = dirname(dir);
+        if (up === dir)
+            return false;
+        dir = up;
+    }
+}
+/** The real path of a folder, or its plain resolved path when it cannot be read. */
+function realOrResolved(folder) {
+    try {
+        return realpathSync.native(folder);
+    }
+    catch {
+        return resolve(folder);
+    }
+}
+/**
+ * One plain sentence when the folder may not be built by a check, else null. The rules: it is a folder that exists, a git project (or inside
+ * one), not a drive root, the home folder, the bridge home or a folder of keys and logins, it has no link in its path (a symlink or a Windows
+ * junction would let the build leave the folder the person named), and it holds a package.json.
+ */
+export function checkRepoFolder(folder) {
+    if (typeof folder !== 'string' || !folder.trim())
+        return 'No folder is given.';
+    const resolved = resolve(folder);
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch {
+        return `The folder ${resolved} does not exist.`;
+    }
+    if (!stat.isDirectory())
+        return `${resolved} is not a folder.`;
+    if (parse(resolved).root === resolved)
+        return `${resolved} is the top of a drive. Pick the project's own folder.`;
+    // The real path must be the path as written, component by component: any link on the way is refused
+    let real;
+    try {
+        real = realpathSync.native(resolved);
+    }
+    catch {
+        return `The folder ${resolved} cannot be read.`;
+    }
+    if (!same(real, resolved))
+        return `${resolved} goes through a link (it really is ${real}). Give the real folder path.`;
+    if (same(resolved, resolve(homedir())))
+        return 'That is the home folder. Pick the project folder inside it.';
+    if (insideOrSame(realOrResolved(configDir()), real))
+        return 'That folder is the bridge home, which holds the sign-in. A check never builds there.';
+    for (const part of resolved.split(sep)) {
+        if (SECRET_FOLDERS.includes(part.toLowerCase()))
+            return `${resolved} is inside a ${part} folder, which holds keys or logins. A check never builds there.`;
+    }
+    if (!insideGit(resolved))
+        return `${resolved} is not a git project (no .git here or above it).`;
+    if (!existsSync(join(resolved, 'package.json')))
+        return `${resolved} has no package.json.`;
+    return null;
+}

package/dist/checks/importlegacy.js

@@ -0,0 +1,300 @@
+// `check import-legacy --from <afb-checks folder> --org <slug> [--dry-run] [--json]`: MOVES THE SETUP OF THE STANDALONE afb-checks TOOL INTO THE BRIDGE, READ ONLY ON THE OLD FOLDER.
+// It reads ONLY <from>/data/projects/<org>/*.json (the project definitions: repo, appDir, boardProject, recipe, url, extraHosts) and the check scripts
+// <from>/checks/<org>/<item>/<key>.mjs. It never lists or reads anything else under the old folder: no profiles, no secrets, no keys, no sign-ins.
+// Each project is registered again through registry.ts with adoption OFF and no pin; a repo registration is made only when its folder is inside an owner-approved
+// root (otherwise it is listed with the exact command the owner needs). Each script is checked with lintCheck and copied unchanged (headers kept) into the scripts
+// folder; a script that fails the lint is not copied, and one that differs from an existing script is a conflict and is left as it is.
+// -- DEP-MODULES -- //
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+// -- MODULES -- //
+import { Refusal, UsageError } from './approve.js';
+import { appendAudit } from './audit.js';
+import { checkRepoFolder } from './guardrails.js';
+import { lintCheck } from './guard.js';
+import { NAME, ORG_SLUG, scriptPath } from './paths.js';
+import { PROJECT_KEY, REGISTRATION_NAME, findRegistration, registerProject } from './registry.js';
+import { rootHolding } from './roots.js';
+// -- CONSTANTS -- //
+/** A script larger than this is not a check. */
+const MAX_SCRIPT_BYTES = 1_000_000;
+const MAX_PROJECT_BYTES = 200_000;
+// -- FUNCTIONS: SMALL HELPERS -- //
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const text = (v) => (typeof v === 'string' && v ? v : undefined);
+/** A plain file (not a link) as bytes, or null. Refuses anything larger than `max`. */
+function readPlain(file, max) {
+    try {
+        const st = lstatSync(file);
+        if (!st.isFile() || st.size > max)
+            return null;
+        return readFileSync(file);
+    }
+    catch {
+        return null;
+    }
+}
+/** The names in a folder that pass `ok`, sorted. A folder that is a link is not entered. */
+function listNames(dir, ok) {
+    try {
+        if (lstatSync(dir).isSymbolicLink())
+            return [];
+        return readdirSync(dir).filter(ok).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function parseProject(raw) {
+    if (!raw)
+        return null;
+    try {
+        const v = JSON.parse(raw.toString('utf8'));
+        if (!isRecord(v))
+            return null;
+        return {
+            repo: text(v.repo),
+            appDir: text(v.appDir),
+            boardProject: text(v.boardProject),
+            recipe: v.recipe === true,
+            database: v.database,
+            url: text(v.url),
+            extraHosts: Array.isArray(v.extraHosts)
+                ? v.extraHosts.filter((h) => typeof h === 'string')
+                : undefined,
+            build: text(v.build),
+            start: text(v.start),
+            ready: text(v.ready)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// -- FUNCTIONS: PROJECTS -- //
+function importProject(org, name, old, dryRun) {
+    const skip = (reason, next) => ({
+        kind: 'skipped',
+        skip: { name, reason, ...(next ? { next } : {}) }
+    });
+    const boardProject = old.boardProject ?? name;
+    if (!PROJECT_KEY.test(boardProject))
+        return skip(`its board project "${boardProject.slice(0, 20)}" is not a project key`);
+    const existing = findRegistration(org, name);
+    if (existing)
+        return { kind: 'unchanged' };
+    // A live site needs the owner's code; it is never made here
+    if (old.url) {
+        const hosts = old.extraHosts?.length ? ` --extra-hosts ${old.extraHosts.join(',')}` : '';
+        return skip('a live site is registered only with a code from the owner', `check approve --action register --target ${name}, then check project ${name} --org ${org} --board-project ${boardProject} --url ${old.url}${hosts} --approval <code>`);
+    }
+    if (!old.repo)
+        return skip('the project file names neither a repo folder nor a live site');
+    const folder = resolve(old.repo);
+    if (!existsSync(folder))
+        return skip('its repo folder is not on this machine');
+    const root = rootHolding(folder);
+    if (!root) {
+        const parent = dirname(folder);
+        return skip('its repo folder is not inside a folder the owner approved', `check approve --action roots --target "${parent}", then check roots add "${parent}" --approval <code>, then import again`);
+    }
+    const input = {
+        org,
+        name,
+        boardProject,
+        repo: folder,
+        ...(old.appDir ? { appDir: old.appDir } : {}),
+        recipe: old.recipe === true,
+        adoptEnv: false,
+        uploadSignedInPictures: false
+    };
+    if (dryRun) {
+        const problem = checkRepoFolder(old.appDir ? join(folder, old.appDir) : folder);
+        return problem ? skip(problem) : { kind: 'registered' };
+    }
+    try {
+        registerProject(input);
+        return { kind: 'registered' };
+    }
+    catch (e) {
+        if (e instanceof Refusal)
+            return skip(e.message);
+        throw e;
+    }
+}
+// -- FUNCTIONS: SCRIPTS -- //
+function importScripts(from, org, dryRun) {
+    const out = {
+        found: 0,
+        copied: 0,
+        same: 0,
+        conflicts: [],
+        rejected: []
+    };
+    const base = join(from, 'checks', org);
+    for (const item of listNames(base, (n) => NAME.test(n))) {
+        const itemDir = join(base, item);
+        for (const file of listNames(itemDir, (n) => n.endsWith('.mjs'))) {
+            const key = file.slice(0, -'.mjs'.length);
+            if (!NAME.test(key))
+                continue;
+            const bytes = readPlain(join(itemDir, file), MAX_SCRIPT_BYTES);
+            if (!bytes)
+                continue;
+            out.found++;
+            const reasons = lintCheck(bytes.toString('utf8'));
+            if (reasons.length) {
+                out.rejected.push({ item, key, reasons });
+                continue;
+            }
+            const target = scriptPath(org, item, key);
+            if (existsSync(target)) {
+                const have = readPlain(target, MAX_SCRIPT_BYTES);
+                if (have && have.equals(bytes))
+                    out.same++;
+                else
+                    out.conflicts.push(`${item}/${key}`);
+                continue;
+            }
+            if (!dryRun) {
+                mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+                // 'wx': never replaces a script that appeared in the meantime
+                try {
+                    writeFileSync(target, bytes, { mode: 0o600, flag: 'wx' });
+                }
+                catch (e) {
+                    if (e.code === 'EEXIST') {
+                        out.conflicts.push(`${item}/${key}`);
+                        continue;
+                    }
+                    throw e;
+                }
+            }
+            out.copied++;
+        }
+    }
+    return out;
+}
+// -- FUNCTIONS: THE IMPORT -- //
+/** Reads the old folder (project files and scripts only) and brings both into the bridge. Throws a Refusal or UsageError for input it cannot use. */
+export function importLegacy(opts) {
+    const dryRun = opts.dryRun === true;
+    const org = opts.org;
+    if (!ORG_SLUG.test(org))
+        throw new UsageError('--org takes an organisation slug.');
+    const from = resolve(opts.from);
+    try {
+        if (!lstatSync(from).isDirectory())
+            throw new Error('not a folder');
+    }
+    catch {
+        throw new Refusal(`${basename(from)} is not a folder that exists.`);
+    }
+    const projectsDir = join(from, 'data', 'projects', org);
+    const names = listNames(projectsDir, (n) => n.endsWith('.json')).map((n) => n.slice(0, -5));
+    const projects = {
+        found: 0,
+        registered: [],
+        unchanged: [],
+        skipped: []
+    };
+    const notes = [];
+    for (const name of names) {
+        projects.found++;
+        if (!REGISTRATION_NAME.test(name)) {
+            projects.skipped.push({
+                name: name.slice(0, 40),
+                reason: 'its name is not a registration name'
+            });
+            continue;
+        }
+        const old = parseProject(readPlain(join(projectsDir, `${name}.json`), MAX_PROJECT_BYTES));
+        if (!old) {
+            projects.skipped.push({ name, reason: 'its project file cannot be read' });
+            continue;
+        }
+        if (!old.recipe && (old.build || old.start))
+            notes.push(`${name}: the old build and start commands are not copied; the bridge reads the package scripts or a recipe (.afb-checks.json).`);
+        const r = importProject(org, name, old, dryRun);
+        if (r.kind === 'skipped')
+            projects.skipped.push(r.skip);
+        else if (r.kind === 'registered')
+            projects.registered.push(name);
+        else
+            projects.unchanged.push(name);
+    }
+    const scripts = importScripts(from, org, dryRun);
+    const todo = [];
+    for (const s of projects.skipped)
+        if (s.next)
+            todo.push(`${s.name}: ${s.next}`);
+    if (projects.registered.length || projects.unchanged.length) {
+        todo.push(`Secrets are not moved (they are sealed with the old key). Import them again with an approval code: ${[...projects.registered, ...projects.unchanged].map((n) => `check approve --action secrets --target ${n}`).join('; ')}, then check secrets import ... --approval <code>.`);
+        todo.push(`Make the sign-ins again: ${[...projects.registered, ...projects.unchanged].map((n) => `check login ${n} --org ${org}`).join('; ')}.`);
+    }
+    if (scripts.conflicts.length)
+        todo.push('Compare the conflicting scripts with the ones in the bridge scripts folder and keep the right one by hand; nothing was overwritten.');
+    todo.push('When the bridge has taken over, stop the old worker and its service (the owner does this).');
+    const summary = {
+        ok: !projects.skipped.length && !scripts.conflicts.length && !scripts.rejected.length,
+        dryRun,
+        org,
+        projects,
+        scripts,
+        notes,
+        todo
+    };
+    if (!dryRun)
+        appendAudit('import-legacy', {
+            org,
+            projects: projects.found,
+            registered: projects.registered.length,
+            skipped: projects.skipped.length,
+            scripts: scripts.found,
+            copied: scripts.copied,
+            conflicts: scripts.conflicts.length,
+            rejected: scripts.rejected.length
+        });
+    return summary;
+}
+/** `check import-legacy --from <folder> --org <slug> [--dry-run] [--json]`. Exit 0 all imported, 1 something was skipped or needs the owner, 2 could not run. */
+export async function importLegacyCommand(args, ctx) {
+    const json = ctx.json ?? args.includes('--json');
+    const list = args[0] === 'import-legacy' ? args.slice(1) : args;
+    const flag = (name) => {
+        const i = list.indexOf(name);
+        const v = i >= 0 ? list[i + 1] : undefined;
+        return v === undefined || v.startsWith('--') ? undefined : v;
+    };
+    try {
+        const from = flag('--from');
+        const org = flag('--org');
+        if (!from || !org)
+            throw new UsageError('Usage: agent-flow-board check import-legacy --from <afb-checks folder> --org <slug> [--dry-run] [--json]');
+        const s = importLegacy({ from, org, dryRun: list.includes('--dry-run') });
+        if (json)
+            ctx.out(JSON.stringify(s));
+        else {
+            ctx.log(`${s.dryRun ? 'Would import' : 'Imported'} for ${s.org}: ${s.projects.registered.length} of ${s.projects.found} project(s) registered (${s.projects.unchanged.length} already there), ${s.scripts.copied} of ${s.scripts.found} script(s) copied (${s.scripts.same} already the same).`);
+            for (const p of s.projects.skipped)
+                ctx.log(`Skipped ${p.name}: ${p.reason}.${p.next ? ` Needs: ${p.next}` : ''}`);
+            for (const c of s.scripts.conflicts)
+                ctx.log(`Conflict (left as it is): ${c}`);
+            for (const r of s.scripts.rejected)
+                ctx.log(`Not copied ${r.item}/${r.key}: ${r.reasons.join(', ')}`);
+            for (const n of s.notes)
+                ctx.log(`Note: ${n}`);
+            for (const t of s.todo)
+                ctx.log(`To do (owner): ${t}`);
+        }
+        return s.ok ? 0 : 1;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (json)
+            ctx.out(JSON.stringify({ ok: false, event: 'error', error: message }));
+        else
+            ctx.log(message);
+        return e instanceof Refusal ? 1 : 2;
+    }
+}