@agent-flow-board/bridge 0.1.0 → 0.3.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/connect.js

@@ -0,0 +1,79 @@
+// CONNECTING THIS MACHINE TO A BOARD AS A CHECK RUNNER
+// One device sign in under the client name afb-checks (an agent approves it with tool_connection_approve and the verifier, or a person types the
+// code on the /device page), one call that makes this machine a runner of the organisation, then only the runner token is kept. The personal
+// token is forgotten at once. The runner token has its own entry in the token store, apart from the sign in of the hooks and MCP.
+// -- DEP-MODULES -- //
+import { hostname } from 'node:os';
+// -- MODULES -- //
+import { deviceLogin } from '../device.js';
+import { accountKey } from '../tokenStore.js';
+// -- CONSTANTS -- //
+/** The client name the board approves with the manage permission, used once to make the runner. */
+export const TOOL_CLIENT_NAME = 'afb-checks';
+// -- FUNCTIONS -- //
+/** The token store entry of the runner token for a server and organisation. */
+export const runnerAccount = (server, org) => `${accountKey(server, org)}.checks`;
+/**
+ * A name for this machine's runner. A repeat of the same owner and name replaces the old token on the board, so this name is different from the
+ * one the standalone afb-checks tool uses on the same machine: connecting the bridge must never cut that tool off.
+ */
+export function runnerName() {
+    const host = hostname()
+        .replace(/[^A-Za-z0-9 ._-]/g, '')
+        .slice(0, 36) || 'this-machine';
+    return `${host} agent-flow-board`.slice(0, 60);
+}
+/** The runner token for a server and organisation, or null when this machine has not been connected. AFB_CHECKS_TOKEN overrides it, for tests. */
+export function loadRunnerToken(store, server, org) {
+    return process.env.AFB_CHECKS_TOKEN ?? store.get(runnerAccount(server, org));
+}
+/** Makes this machine a runner of the organisation. Never prints a token. */
+export async function connectChecks(options) {
+    const url = new URL(options.server);
+    if (url.protocol !== 'https:' && !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))
+        throw new Error('The board address must start with https:// (only an address on this machine may use http).');
+    const personal = await deviceLogin(options.server, options.fetch, options.log, {
+        name: TOOL_CLIENT_NAME,
+        pkce: true,
+        wait: options.wait,
+        onCode: (c) => {
+            if (options.json)
+                options.out(JSON.stringify({
+                    event: 'code',
+                    userCode: c.userCode,
+                    verificationUri: c.verificationUri,
+                    verifier: c.verifier,
+                    expiresIn: c.expiresInSeconds
+                }));
+            else
+                options.log('On that page choose your organisation and tick "Change project settings" (manage). This is used once, to make this machine a runner.');
+        }
+    });
+    const name = runnerName();
+    const projects = options.projects?.length ? options.projects : undefined;
+    const res = await options.fetch(`${options.server}/api/v1/orgs/${encodeURIComponent(options.org)}/runners/tool`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${personal.token}`,
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify({ name, ...(projects ? { projects } : {}) }),
+        signal: AbortSignal.timeout(30_000)
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.token)
+        throw new Error(body.error?.message ?? `The board answered ${res.status} when making this machine a runner.`);
+    options.store.set(runnerAccount(options.server, options.org), body.token);
+    const served = projects ? projects.join(', ') : 'every project of the organisation you may use';
+    if (options.json)
+        options.out(JSON.stringify({
+            event: 'connected',
+            server: options.server,
+            org: options.org,
+            name,
+            projects: projects ?? 'all'
+        }));
+    else
+        options.log(`Connected as "${name}". It serves ${served}.`);
+    return { name, served };
+}

package/dist/checks/connections.js

@@ -0,0 +1,42 @@
+// 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, 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() {
+    if (!existsSync(file()))
+        return [];
+    try {
+        const v = JSON.parse(readFileSync(file(), 'utf8'));
+        return Array.isArray(v)
+            ? v.filter((c) => !!c &&
+                typeof c.server === 'string' &&
+                typeof c.org === 'string' &&
+                ORG_SLUG.test(c.org) &&
+                typeof c.name === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Adds or replaces the connection for a server and organisation. Written whole, never half. */
+export function recordConnection(c) {
+    const next = [...listConnections().filter((x) => !(x.server === c.server && x.org === c.org)), c];
+    ensureDir(checksHome());
+    const tmp = `${file()}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 1), { mode: 0o600 });
+    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 });
+    renameRetry(tmp, file());
+}

package/dist/checks/copy.js

@@ -0,0 +1,320 @@
+// THE PRIVATE COPY OF A REPO FOR ONE RUN, SO A RUN BUILDS AND SERVES FROM ITS OWN FOLDER AND NEVER FROM THE ONE A PERSON'S PREVIEW SERVES.
+// A git repo with a commit is copied as a local clone (`git clone --local --no-checkout`: nothing is fetched from anywhere else and nothing is
+// written into the repo's own .git, objects are hard linked), with the origin removed and HEAD checked out detached; then only the working-tree
+// changes (tracked and untracked, not ignored) are copied over it, so a run tests what is on disk now. A git repo with no commit is copied from the
+// files git lists; a folder that is not a git repo is copied with caps on files and size. Env files, keys, links and programs named like the
+// package managers are never copied. If HEAD moves while the copy is made, the copy is made once more.
+// -- DEP-MODULES -- //
+import { execFile } from 'node:child_process';
+import { copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+// -- MODULES -- //
+import { ensureDir, under } from './paths.js';
+// -- CONSTANTS -- //
+/** A file bigger than this is not copied (a build output, a dump, a video). */
+export const MAX_COPY_BYTES = 5 * 1024 * 1024;
+/** A folder that is not a git repo is copied whole, so it may not be a whole disk. */
+export const MAX_PLAIN_FILES = 20_000;
+export const MAX_PLAIN_BYTES = 400 * 1024 * 1024;
+/** Source and document extensions: a file named secrets.ts or credentials.json is code or text a project owns, not a credentials dump, so it is copied. */
+const SOURCE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|svelte|json|md)$/i;
+/**
+ * Files that are never copied, by name: secrets, keys, and a program named like the ones a shell would look up. The credentials rule only applies to a file
+ * without a source extension, and the program rule only to a real program (a script file such as lib/git.js is source). A path git tracks is never skipped
+ * by these (it is already in the commit); env files are the exception, they have their own rule.
+ */
+const NEVER = [
+    { re: /(^|\/)\.env(\.[^/]*)?$/i, why: 'an env file' },
+    { re: /\.(pem|key|p12|pfx|jks|keystore)$/i, why: 'a key file' },
+    { re: /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i, why: 'an ssh key' },
+    { re: /(^|\/)(credentials?|secrets?)(\.[^/]*)?$/i, why: 'a credentials file' },
+    {
+        re: /(^|\/)(yarn|npm|npx|pnpm|node|git)\.(cmd|bat|exe|com|ps1|vbs)$/i,
+        why: 'a program named like a tool it would be run as'
+    }
+];
+/** An example env file holds no secrets and is copied. */
+const ENV_EXAMPLE = /\.(example|sample|template)$/i;
+/** The reason a path is never copied, or null. Exported for the tests. */
+export function neverCopy(rel, tracked) {
+    for (const n of NEVER) {
+        if (!n.re.test(rel))
+            continue;
+        if (n.why === 'an env file') {
+            if (ENV_EXAMPLE.test(rel))
+                continue;
+            return n.why;
+        }
+        if (tracked)
+            continue;
+        if (n.why === 'a credentials file' && SOURCE_EXT.test(rel))
+            continue;
+        return n.why;
+    }
+    return null;
+}
+const SKIP_DIR = /(^|\/)(\.git|node_modules)(\/|$)/;
+/** Env files a build tool loads on its own in a production build. A committed one is taken out of the copy as well. */
+const TRACKED_ENV = /(^|\/)\.env(\.local|\.production|\.production\.local)?$/i;
+// -- FUNCTIONS -- //
+/** Runs git with an argument list and no shell. Resolves with the exit status; never throws. */
+export function git(cwd, args) {
+    return new Promise((resolveResult) => {
+        execFile('git', args, {
+            cwd,
+            windowsHide: true,
+            encoding: 'buffer',
+            maxBuffer: 256 * 1024 * 1024,
+            timeout: 10 * 60_000
+        }, (err, stdout, stderr) => {
+            const code = err
+                ? typeof err.code === 'number'
+                    ? err.code
+                    : -1
+                : 0;
+            resolveResult({
+                status: code,
+                stdout: stdout,
+                stderr: String(stderr ?? '')
+            });
+        });
+    });
+}
+const must = (r, what) => {
+    if (r.status !== 0)
+        throw new Error(`${what} failed: ${(r.stderr || r.stdout.toString('utf8')).trim().slice(-300)}`);
+    return r.stdout;
+};
+/** The commit of HEAD, or null when the folder has no commit (or is not a git repo). */
+export async function headCommit(repo) {
+    const r = await git(repo, ['rev-parse', '--verify', 'HEAD']);
+    return r.status === 0 ? r.stdout.toString('utf8').trim() || null : null;
+}
+/** The top folder of the git repo `folder` is in, or null when it is in none. */
+export async function gitRoot(folder) {
+    const r = await git(folder, ['rev-parse', '--show-toplevel']);
+    if (r.status !== 0)
+        return null;
+    const out = r.stdout.toString('utf8').trim();
+    return out ? resolve(out) : null;
+}
+/** The tracked and the untracked-not-ignored files of a repo, as paths relative to it. Null when the folder is not a git repo. */
+export async function listFiles(repo) {
+    const r = await git(repo, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']);
+    if (r.status !== 0)
+        return null;
+    return [...new Set(r.stdout.toString('utf8').split('\0').filter(Boolean))];
+}
+/** The changes of a working tree as { deleted, changed } paths relative to the git root, from git itself (NUL separated, so any file name works). */
+export async function workingTreeChanges(root) {
+    const out = must(await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']), 'git status').toString('utf8');
+    const parts = out.split('\0');
+    if (parts.at(-1) === '')
+        parts.pop();
+    const deleted = [];
+    const changed = [];
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (entry.length < 4)
+            continue;
+        const x = entry[0];
+        const y = entry[1];
+        const file = entry.slice(3);
+        if (x === 'R' || x === 'C') {
+            // A rename lists the new name, then the old one
+            const from = parts[++i];
+            if (x === 'R')
+                deleted.push(from);
+            changed.push(file);
+        }
+        else if (x === 'D' || y === 'D')
+            deleted.push(file);
+        else
+            changed.push(file);
+    }
+    return { deleted, changed };
+}
+/** The real path of a folder (so 8.3 names and case do not matter when two paths are compared), or its resolved path. */
+const realOf = (folder) => {
+    try {
+        return realpathSync.native(folder);
+    }
+    catch {
+        return resolve(folder);
+    }
+};
+const safeRel = (rel) => !!rel && !isAbsolute(rel) && !rel.split(/[\\/]/).includes('..') && !rel.includes('\0');
+/**
+ * Copies one file of the repo into the copy. Returns true when it was copied. A link is refused by name (a copy that followed it could carry files
+ * from outside the repo into the build); the other reasons to leave a file out are listed in `skipped`.
+ */
+function copyOne(ctx, rel) {
+    if (!safeRel(rel))
+        throw new Error(`The file "${rel.slice(0, 80)}" is not a file the tool copies.`);
+    const parts = rel.split('/');
+    if (parts[0] === '.git')
+        throw new Error(`The file "${rel.slice(0, 80)}" is not a file the tool copies.`);
+    if (SKIP_DIR.test(rel))
+        return false;
+    // Every folder above the file must be a real folder
+    for (let i = 1; i < parts.length; i++) {
+        const folder = parts.slice(0, i).join('/');
+        let st;
+        try {
+            st = lstatSync(join(ctx.src, folder));
+        }
+        catch {
+            break;
+        }
+        if (st.isSymbolicLink())
+            throw new Error(`"${folder.slice(0, 80)}" is a link. A check does not copy links; remove it or ignore it in git.`);
+    }
+    const from = join(ctx.src, ...parts);
+    let st;
+    try {
+        st = lstatSync(from);
+    }
+    catch {
+        return false; // Listed by git but deleted in the working tree
+    }
+    if (st.isSymbolicLink())
+        throw new Error(`"${rel.slice(0, 80)}" is a link. A check does not copy links; remove it or ignore it in git.`);
+    if (!st.isFile())
+        return false;
+    const never = neverCopy(rel, ctx.tracked.has(rel));
+    if (never) {
+        ctx.skipped.push({ path: rel, why: never });
+        return false;
+    }
+    if (st.size > MAX_COPY_BYTES) {
+        ctx.skipped.push({ path: rel, why: 'larger than 5 MB' });
+        return false;
+    }
+    const to = under(ctx.dest, ...parts);
+    mkdirSync(dirname(to), { recursive: true, mode: 0o700 });
+    copyFileSync(from, to);
+    return true;
+}
+/** Every file of a folder that is not a git repo, as relative paths, with the limits that keep it from being a whole disk. */
+function plainFiles(repo, limits = {}) {
+    const maxFiles = limits.files ?? MAX_PLAIN_FILES;
+    const maxBytes = limits.bytes ?? MAX_PLAIN_BYTES;
+    const out = [];
+    let bytes = 0;
+    const walk = (rel) => {
+        for (const e of readdirSync(join(repo, rel), { withFileTypes: true })) {
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (SKIP_DIR.test(`${r}/`))
+                continue;
+            if (e.isSymbolicLink())
+                throw new Error(`"${r.slice(0, 80)}" is a link. A check does not copy links; remove it or ignore it in git.`);
+            if (e.isDirectory())
+                walk(r);
+            else if (e.isFile()) {
+                out.push(r);
+                bytes += lstatSync(join(repo, r)).size;
+                if (out.length > maxFiles || bytes > maxBytes)
+                    throw new Error(`${repo} is not a git repo and holds more than ${maxFiles} files or ${Math.round(maxBytes / 1024 / 1024)} MB, which is too much to copy for a run. Make it a git repo, or point the project at a smaller folder.`);
+            }
+        }
+    };
+    walk('');
+    return out;
+}
+/** The tracked links of a checked-out clone, by name: a link in the commit would reach outside the copy. */
+async function trackedLinks(dir) {
+    const out = must(await git(dir, ['ls-files', '-s', '-z']), 'git ls-files').toString('utf8');
+    const links = [];
+    for (const entry of out.split('\0').filter(Boolean)) {
+        const tab = entry.indexOf('\t');
+        if (tab > 0 && entry.startsWith('120000 '))
+            links.push(entry.slice(tab + 1));
+    }
+    return links;
+}
+async function cloneCopy(root, dest, head, ctx) {
+    ensureDir(dirname(dest));
+    must(await git(dirname(dest), ['clone', '--local', '--no-checkout', '--quiet', root, dest]), 'git clone');
+    await git(dest, ['remote', 'remove', 'origin']);
+    must(await git(dest, ['checkout', '--quiet', '--force', '--detach', head]), 'git checkout');
+    const links = await trackedLinks(dest);
+    if (links.length)
+        throw new Error(`"${links[0].slice(0, 80)}" is a link in the commit. A check does not copy links; remove it from git.`);
+    const tracked = must(await git(dest, ['ls-files', '-z']), 'git ls-files').toString('utf8');
+    for (const f of tracked.split('\0').filter(Boolean)) {
+        ctx.tracked.add(f);
+        if (TRACKED_ENV.test(f))
+            rmSync(under(dest, f), { force: true });
+    }
+    const { deleted, changed } = await workingTreeChanges(root);
+    for (const rel of deleted) {
+        if (!safeRel(rel) || SKIP_DIR.test(rel))
+            continue;
+        try {
+            rmSync(under(dest, rel), { force: true });
+        }
+        catch {
+            ctx.skipped.push({ path: rel, why: 'could not remove it' });
+        }
+    }
+    let copied = 0;
+    for (const rel of changed)
+        if (copyOne(ctx, rel))
+            copied++;
+    return copied;
+}
+/**
+ * Makes one run's private copy of `repo` in `dest` (which must not exist yet). The copy is made from the git root that holds `repo`;
+ * `repoInCopy` says where `repo` is inside it. A link anywhere in what is copied is refused by name.
+ */
+export async function makePrivateCopy(repo, dest, opts = {}) {
+    const log = opts.log ?? (() => { });
+    const root = (await gitRoot(repo)) ?? resolve(repo);
+    for (let attempt = 1;; attempt++) {
+        const ctx = { src: root, dest, skipped: [], tracked: new Set() };
+        const head = await headCommit(root);
+        let files = 0;
+        let mode;
+        if (head) {
+            mode = 'clone';
+            files = await cloneCopy(root, dest, head, ctx);
+        }
+        else {
+            mkdirSync(dest, { recursive: true, mode: 0o700 });
+            const listed = await listFiles(root);
+            mode = listed ? 'listed' : 'plain';
+            if (listed) {
+                const cached = await git(root, ['ls-files', '--cached', '-z']);
+                if (cached.status === 0)
+                    for (const f of cached.stdout.toString('utf8').split('\0').filter(Boolean))
+                        ctx.tracked.add(f);
+            }
+            for (const rel of listed ?? plainFiles(root, opts.limits))
+                if (copyOne(ctx, rel))
+                    files++;
+        }
+        await opts.afterCopy?.(attempt);
+        // Another commit made in the repo while it was being copied would leave a tree that is neither commit: it is copied again, once
+        if (head && attempt === 1 && (await headCommit(root)) !== head) {
+            log('The repo moved to another commit while it was being copied; copying again.');
+            rmSync(dest, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            continue;
+        }
+        if (ctx.skipped.length) {
+            log(`${ctx.skipped.length} file(s) were not copied (env files, keys, files over 5 MB).`);
+            // Names only, never content
+            for (const k of ctx.skipped)
+                log(`  not copied: ${k.path.slice(0, 120)} (${k.why})`);
+        }
+        const rel = relative(realOf(root), realOf(repo));
+        return {
+            files,
+            skipped: ctx.skipped.length,
+            skippedList: ctx.skipped,
+            head,
+            sourceRoot: root,
+            repoInCopy: rel && !rel.startsWith('..') ? join(dest, rel) : dest,
+            mode
+        };
+    }
+}