@agent-flow-board/bridge 0.2.0 → 0.4.0

package/dist/checks/signinKey.js

@@ -0,0 +1,104 @@
+// THE MACHINE'S SIGN IN KEY: A P-256 KEY PAIR WHOSE PUBLIC HALF IS PUBLISHED TO THE BOARD, SO THE OWNER CAN TYPE A TEST ACCOUNT'S PASSWORD ON THE BOARD WITHOUT ANY AGENT SEEING IT
+// The private half lives in the same sealed store as the saved sign ins (AES-GCM under the key in the bridge home) and is opened only in this process. A password is decrypted in memory,
+// goes to the page through Playwright `fill` and is never an argument, an environment variable, a log line or an audit line. The format mirrors src/lib/shared/signinCrypto.ts.
+// Honest limit: a process that runs as the same OS user can read the key files, like every other local secret here.
+// -- DEP-MODULES -- //
+import { createHash, webcrypto } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { appendAudit } from './audit.js';
+import { checksHome, ensureDir } from './paths.js';
+import { seal, unseal } from './store.js';
+// -- CONSTANTS -- //
+export const SIGNIN_ALG = 'ECDH-P256+HKDF-SHA256+AES-256-GCM';
+const subtle = webcrypto.subtle;
+const enc = new TextEncoder();
+const keyFile = () => join(checksHome(), 'signin-key.bin');
+const idFile = () => join(checksHome(), 'signin-key.id');
+const AAD = 'signin-private-key';
+// -- FUNCTIONS -- //
+const b64u = (bytes) => Buffer.from(bytes).toString('base64url');
+const unb64u = (text) => new Uint8Array(Buffer.from(text, 'base64url'));
+/** The text that binds a ciphertext to where it may be opened. Must equal signinAad in src/lib/shared/signinCrypto.ts. */
+export const signinAad = (orgId, runnerId, registration, keyId) => `afb-signin-v1|${orgId}|${runnerId}|${registration.toLowerCase()}|${keyId}`;
+/** Twelve hex characters in groups of four, the same rule as the board and the browser. */
+export function fingerprintOf(publicKey) {
+    const hex = createHash('sha256')
+        .update(Buffer.from(publicKey, 'base64url'))
+        .digest('hex')
+        .slice(0, 12);
+    return hex.match(/.{4}/g).join('-');
+}
+/** Makes the key pair once and keeps the private half sealed. Returns the id and the public half. */
+export async function ensureSigninKey() {
+    ensureDir(checksHome());
+    if (existsSync(keyFile()) && existsSync(idFile())) {
+        const pair = readPair();
+        if (pair)
+            return pair;
+    }
+    const pair = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+        'deriveBits'
+    ]);
+    const pkcs8 = new Uint8Array(await subtle.exportKey('pkcs8', pair.privateKey));
+    const pub = new Uint8Array(await subtle.exportKey('raw', pair.publicKey));
+    const keyId = b64u(webcrypto.getRandomValues(new Uint8Array(12)));
+    writeFileSync(keyFile(), seal(AAD, pkcs8), { mode: 0o600 });
+    writeFileSync(idFile(), JSON.stringify({ keyId, publicKey: b64u(pub) }), { mode: 0o600 });
+    pkcs8.fill(0);
+    appendAudit('signin key made', { keyId });
+    return { keyId, publicKey: b64u(pub) };
+}
+function readPair() {
+    try {
+        const v = JSON.parse(readFileSync(idFile(), 'utf8'));
+        return typeof v.keyId === 'string' && typeof v.publicKey === 'string'
+            ? { keyId: v.keyId, publicKey: v.publicKey }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Publishes the public key. The board accepts it only on this machine's own runner token; a changed key is shown there with its time. */
+export async function publishSigninKey(board) {
+    const { keyId, publicKey } = await ensureSigninKey();
+    const done = await board.publishSigninKey({ keyId, publicKey });
+    return done;
+}
+/** The fingerprint of this machine's key, for `check status`, or null when none was made yet. */
+export function localFingerprint() {
+    const pair = existsSync(idFile()) ? readPair() : null;
+    return pair ? fingerprintOf(pair.publicKey) : null;
+}
+/** Opens one envelope in memory. A ciphertext for another org, runner, registration or key fails here, because the associated data differs. */
+export async function openSignin(envelope, where) {
+    const me = readPair();
+    if (!me || me.keyId !== envelope.keyId || envelope.alg !== SIGNIN_ALG)
+        throw new Error('That sign in was made for another key of this machine.');
+    const pkcs8 = new Uint8Array(unseal(AAD, new Uint8Array(readFileSync(keyFile()))));
+    let account;
+    try {
+        const priv = await subtle.importKey('pkcs8', pkcs8, { name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits']);
+        const pack = JSON.parse(envelope.ciphertext);
+        const peer = await subtle.importKey('raw', unb64u(pack.epk), { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+        const bits = await subtle.deriveBits({ name: 'ECDH', public: peer }, priv, 256);
+        const aad = enc.encode(signinAad(where.orgId, where.runnerId, envelope.registration, envelope.keyId));
+        const base = await subtle.importKey('raw', bits, 'HKDF', false, ['deriveKey']);
+        const key = await subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: aad }, base, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+        const plain = await subtle.decrypt({ name: 'AES-GCM', iv: unb64u(pack.iv), additionalData: aad }, key, unb64u(pack.ct));
+        const v = JSON.parse(new TextDecoder().decode(plain));
+        if (typeof v.e !== 'string' || typeof v.p !== 'string')
+            throw new Error('shape');
+        account = { email: v.e, password: v.p };
+    }
+    catch {
+        // Never says why: nothing about the contents leaves this function
+        throw new Error('That sign in could not be opened on this machine.');
+    }
+    finally {
+        pkcs8.fill(0);
+    }
+    return account;
+}

package/dist/checks/singleflight.js

@@ -0,0 +1,307 @@
+// SINGLE-FLIGHT FOR BUILDS AND INSTALLS ACROSS PROCESSES: WHEN SEVERAL RUNS NEED THE SAME THING, ONE BUILDS AND THE OTHERS WAIT FOR ITS RESULT.
+// The lock is a file made whole and linked into place (like lock.ts). Its body holds the process id, the process start time, a token and a HEARTBEAT that the
+// builder refreshes on an unref'd timer. A lock is stale only when its heartbeat is missing for `staleMs`: never because a process id looks dead or alive,
+// because Windows reuses process ids. The builder writes its outcome to a result file named by its token BEFORE it gives the lock back, so a waiter that sees
+// the lock go away reads what happened: a success is handed to every waiter, a deterministic failure is handed to every waiter as the same error, and an
+// infrastructure failure (the work threw an error marked `infra: true`) makes one waiter the next builder. A builder that died leaves no result: the lock
+// goes stale and one waiter takes it over. The work should be async (spawned processes), because a blocked event loop cannot beat.
+// -- DEP-MODULES -- //
+import { randomBytes } from 'node:crypto';
+import { linkSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { assertName, ensureDir, locksDir } from './paths.js';
+/** Marks a failure of the machine (a full disk, a killed process, a network error) rather than of the code being built: one waiter tries again. */
+export class InfraError extends Error {
+    infra = true;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'InfraError';
+    }
+}
+/** What every waiter gets when the builder failed deterministically: the same name and message, not a retry. */
+export class SharedBuildError extends Error {
+    shared = true;
+    originalName;
+    constructor(name, message) {
+        super(message);
+        this.name = 'SharedBuildError';
+        this.originalName = name;
+    }
+}
+/** This caller waited as long as it was allowed to for a build that did not finish. */
+export class FlightTimeoutError extends Error {
+    code = 'FLIGHT_TIMEOUT';
+    constructor(name, ms) {
+        super(`Gave up waiting ${Math.round(ms / 1000)} seconds for the build "${name}" of another run.`);
+        this.name = 'FlightTimeoutError';
+    }
+}
+// -- CONSTANTS -- //
+/** A lock whose content cannot be read is only stale after this long (it is made whole, so this means a damaged file). */
+const UNREADABLE_GRACE_MS = 2_000;
+/** Result files are kept this long for slow waiters, then removed by the next builder. */
+const RESULT_KEEP_MS = 10 * 60_000;
+/** When this process started, to the nearest few milliseconds. */
+const PROCESS_START = new Date(Date.now() - process.uptime() * 1000).toISOString();
+// -- FUNCTIONS -- //
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const lockFile = (name) => join(locksDir(), `sf-${assertName(name, 'flight name')}.lock`);
+const resultFile = (name, token) => join(locksDir(), `sf-${assertName(name, 'flight name')}.${token}.result`);
+function readText(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function parseBody(text) {
+    if (text === null)
+        return null;
+    try {
+        const v = JSON.parse(text);
+        if (!v ||
+            typeof v.pid !== 'number' ||
+            typeof v.start !== 'string' ||
+            typeof v.beat !== 'string' ||
+            typeof v.token !== 'string')
+            return null;
+        return { pid: v.pid, start: v.start, beat: v.beat, token: v.token };
+    }
+    catch {
+        return null;
+    }
+}
+/** Stale by a missing heartbeat only. The process id is never looked at. */
+function isStale(text, file, staleMs) {
+    const body = parseBody(text);
+    if (body) {
+        const beat = Date.parse(body.beat);
+        return !Number.isFinite(beat) || Date.now() - beat > staleMs;
+    }
+    try {
+        return Date.now() - statSync(file).mtimeMs > UNREADABLE_GRACE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/** Writes a file whole: a temporary file renamed into place, so a reader never sees half of it. */
+function writeWhole(file, text) {
+    const tmp = `${file}.${process.pid}.${randomBytes(3).toString('hex')}.tmp`;
+    writeFileSync(tmp, text, { mode: 0o600 });
+    try {
+        renameSync(tmp, file);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+}
+/** Creates the lock file with its whole content at once. False when somebody holds it. */
+function tryCreate(file, text) {
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    writeFileSync(tmp, text, { mode: 0o600 });
+    try {
+        linkSync(tmp, file);
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            return false;
+        throw e;
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/** Moves the lock aside in one step, so of two contenders only one moves it. A fresh lock that was moved by mistake is linked back. */
+function moveAside(file, expected, staleMs) {
+    const aside = `${file}.aside.${process.pid}.${randomBytes(4).toString('hex')}`;
+    try {
+        renameSync(file, aside);
+    }
+    catch {
+        return;
+    }
+    const moved = readText(aside);
+    if (moved !== null && moved !== expected && !isStale(moved, aside, staleMs)) {
+        try {
+            linkSync(aside, file);
+        }
+        catch {
+            /* A newer lock is already there */
+        }
+    }
+    rmSync(aside, { force: true });
+}
+const bodyText = (token, beat) => JSON.stringify({
+    pid: process.pid,
+    start: PROCESS_START,
+    beat: beat.toISOString(),
+    token
+}) + '\n';
+/** Takes the lock without waiting. Returns the token, or null when somebody with a fresh heartbeat holds it. */
+function tryAcquire(name, staleMs) {
+    const file = lockFile(name);
+    ensureDir(locksDir());
+    const token = randomBytes(8).toString('hex');
+    const mine = bodyText(token, new Date());
+    for (let attempt = 0; attempt < 6; attempt++) {
+        if (tryCreate(file, mine))
+            return token;
+        const held = readText(file);
+        if (held === null)
+            continue; // Released between the two looks
+        if (!isStale(held, file, staleMs))
+            return null;
+        moveAside(file, held, staleMs);
+    }
+    return null;
+}
+/** Gives the lock back, but only when it still carries our token (it may have been taken over after a long pause). */
+function release(name, token, staleMs) {
+    const file = lockFile(name);
+    const text = readText(file);
+    if (parseBody(text)?.token !== token)
+        return;
+    const aside = `${file}.aside.${process.pid}.${randomBytes(4).toString('hex')}`;
+    try {
+        renameSync(file, aside);
+    }
+    catch {
+        return;
+    }
+    const moved = readText(aside);
+    if (moved !== null && parseBody(moved)?.token !== token && !isStale(moved, aside, staleMs)) {
+        try {
+            linkSync(aside, file);
+        }
+        catch {
+            /* A newer lock is already there */
+        }
+    }
+    rmSync(aside, { force: true });
+}
+/** Refreshes the heartbeat of our lock. Returns false when the lock is no longer ours. */
+function beat(name, token) {
+    const file = lockFile(name);
+    const body = parseBody(readText(file));
+    if (!body)
+        return true; // Unreadable for a moment: try again on the next beat
+    if (body.token !== token)
+        return false;
+    try {
+        writeWhole(file, bodyText(token, new Date()));
+    }
+    catch {
+        /* Windows may refuse the swap while a reader has the file open: the next beat tries again */
+    }
+    return true;
+}
+function readOutcome(name, token) {
+    const text = readText(resultFile(name, token));
+    if (text === null)
+        return null;
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' && typeof v.ok === 'boolean' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function purgeOldResults(name) {
+    const prefix = `sf-${name}.`;
+    try {
+        for (const n of readdirSync(locksDir())) {
+            if (!n.startsWith(prefix) || !n.endsWith('.result'))
+                continue;
+            const f = join(locksDir(), n);
+            try {
+                if (Date.now() - statSync(f).mtimeMs > RESULT_KEEP_MS)
+                    rmSync(f, { force: true });
+            }
+            catch {
+                /* Gone */
+            }
+        }
+    }
+    catch {
+        /* No folder yet */
+    }
+}
+const isInfra = (e) => !!e && typeof e === 'object' && e.infra === true;
+/**
+ * Runs `work` once for everybody who asks for `name` at the same time, across processes. The caller that takes the lock is the builder and its `work`
+ * result (which must be JSON-serialisable, for example a cache key) is handed to the waiters. See the header of this file for failures and crashes.
+ */
+export async function singleFlight(name, work, opts = {}) {
+    const heartbeatMs = opts.heartbeatMs ?? 2_000;
+    const staleMs = Math.max(opts.staleMs ?? 15_000, heartbeatMs * 5);
+    const waiterLimitMs = opts.waiterLimitMs ?? 10 * 60_000;
+    const pollMs = opts.pollMs ?? 100;
+    lockFile(name); // Refuses a name that is not plain before anything is made
+    const deadline = Date.now() + waiterLimitMs;
+    let watched = null;
+    const handled = new Set();
+    for (;;) {
+        // 1. The outcome of the build we are waiting for, written before its lock was given back
+        if (watched && !handled.has(watched)) {
+            const out = readOutcome(name, watched);
+            if (out) {
+                if (out.ok)
+                    return { role: 'waiter', result: out.value };
+                if (!out.infra)
+                    throw new SharedBuildError(out.name, out.message);
+                handled.add(watched); // An infrastructure failure: whoever takes the lock first builds again
+                watched = null;
+            }
+        }
+        if (opts.signal?.aborted)
+            throw new Error('The run was stopped.');
+        // 2. Take the lock and build
+        const token = tryAcquire(name, staleMs);
+        if (token)
+            return runBuilder(name, token, work, heartbeatMs, staleMs);
+        // 3. Somebody else builds: remember which build, look again soon
+        const body = parseBody(readText(lockFile(name)));
+        if (body && !handled.has(body.token))
+            watched = body.token;
+        if (Date.now() >= deadline)
+            throw new FlightTimeoutError(name, waiterLimitMs);
+        await sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+    }
+}
+async function runBuilder(name, token, work, heartbeatMs, staleMs) {
+    purgeOldResults(name);
+    let lost = false;
+    const timer = setInterval(() => {
+        if (!lost && !beat(name, token))
+            lost = true;
+    }, heartbeatMs);
+    timer.unref();
+    const record = (outcome) => {
+        try {
+            writeWhole(resultFile(name, token), JSON.stringify(outcome));
+        }
+        catch {
+            /* Waiters then find no outcome and the lock going away: the next one builds */
+        }
+    };
+    try {
+        const value = await work();
+        record({ ok: true, value: value ?? null });
+        return { role: 'builder', result: value };
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        record({ ok: false, infra: isInfra(e), name: err.name, message: err.message });
+        throw e;
+    }
+    finally {
+        clearInterval(timer);
+        release(name, token, staleMs);
+    }
+}

package/dist/checks/store.js

@@ -0,0 +1,92 @@
+// THE SEALED STORE: AES-256-GCM WITH A KEY THAT LIVES IN THE BRIDGE HOME, NEVER INSIDE THE CHECKS FOLDER, A RUN, A COPY OR A PATH A PREVIEW ENV NAMES.
+// seal() binds a text (`aad`, for example the registration org/NAME) into the seal without storing it, so a sealed file opens only for the same text and a copy made for
+// another registration fails. The blob is iv (12 bytes) | tag (16 bytes) | ciphertext. Nothing here ever prints or returns a key.
+// -- DEP-MODULES -- //
+import { execFileSync } from 'node:child_process';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { configDir } from '../tokenStore.js';
+// -- CONSTANTS -- //
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+// -- FUNCTIONS -- //
+/** The key file sits beside the token store in the bridge home, one level above the checks folder. */
+export const sealKeyFile = () => join(configDir(), 'checks.key');
+const nap = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** Limits the key file to the current user on Windows (icacls on this one file only; the folder and its inheritance are left alone). Best effort. */
+function lockDownFile(file) {
+    try {
+        if (process.platform === 'win32') {
+            const user = process.env.USERNAME;
+            if (!user)
+                return;
+            execFileSync('icacls', [file, '/inheritance:r', '/grant:r', `${user}:F`], {
+                stdio: 'ignore',
+                windowsHide: true,
+                timeout: 10_000
+            });
+        }
+        else
+            chmodSync(file, 0o600);
+    }
+    catch {
+        /* Not fatal: the key is still outside every folder an agent or a check works in */
+    }
+}
+/**
+ * The key. Several processes may start at once on a machine that has none yet: the file is made exclusively (the first one wins) and a key that is
+ * still being written is waited for. A file that stays the wrong size is damaged and named, never replaced.
+ */
+function key() {
+    const file = sealKeyFile();
+    for (let i = 0; i < 80; i++) {
+        if (!existsSync(file)) {
+            mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+            try {
+                writeFileSync(file, randomBytes(KEY_BYTES), { mode: 0o600, flag: 'wx' });
+                lockDownFile(file);
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+        }
+        let k = null;
+        try {
+            k = readFileSync(file);
+        }
+        catch {
+            /* Gone again or being written: wait */
+        }
+        if (k && k.length === KEY_BYTES)
+            return k;
+        nap(25);
+    }
+    throw new Error(`The sealing key file (checks.key in the bridge home) is damaged. Nothing sealed with it can be opened; remove the file and import the secrets again.`);
+}
+/** Seals `plaintext` for `aad`. */
+export function seal(aad, plaintext) {
+    const iv = randomBytes(IV_BYTES);
+    const c = createCipheriv('aes-256-gcm', key(), iv);
+    c.setAAD(Buffer.from(aad, 'utf8'));
+    const ct = Buffer.concat([c.update(plaintext), c.final()]);
+    return Buffer.concat([iv, c.getAuthTag(), ct]);
+}
+/** Opens a blob made by seal() for the same `aad`. Throws one plain sentence when the blob is damaged or was made for another text. */
+export function unseal(aad, blob) {
+    const b = Buffer.from(blob);
+    if (b.length < IV_BYTES + TAG_BYTES)
+        throw new Error('The sealed data is too short to be valid.');
+    try {
+        const d = createDecipheriv('aes-256-gcm', key(), b.subarray(0, IV_BYTES));
+        d.setAAD(Buffer.from(aad, 'utf8'));
+        d.setAuthTag(b.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));
+        return Buffer.concat([d.update(b.subarray(IV_BYTES + TAG_BYTES)), d.final()]);
+    }
+    catch {
+        throw new Error('The sealed data is damaged or was sealed for something else.');
+    }
+}

package/dist/checks/surface.js

@@ -0,0 +1,124 @@
+// THE FILES THAT DECIDE WHAT A BUILD AND A START RUN. A registration keeps a hash of them (its pin), so a change to a script, a lockfile, the package manager's own program or a
+// build config is noticed and the commands are checked against the guardrails again before the new hash is pinned. This is change detection for the build setup, not a defence
+// against the agent: the preview runs the app's own code, which the agent writes.
+// -- DEP-MODULES -- //
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+// -- CONSTANTS -- //
+const FIXED = [
+    'yarn.lock',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+    '.pnpmfile.cjs',
+    '.yarnrc.yml',
+    '.npmrc',
+    '.afb-checks.json'
+];
+/** Files at the folder root that tools load as code when they build: vite.config.ts, svelte.config.js, postcss.config.cjs and the like. */
+const CONFIG = /\.config\.(c|m)?[jt]s$|^\.postcssrc/;
+/** Folders whose files run as the package manager. */
+const PROGRAM_DIRS = ['.yarn/releases', '.yarn/plugins'];
+// -- FUNCTIONS -- //
+/** What a path is, without following a link: a link or an unreadable entry still counts, so it can never be skipped or crash the hash. */
+function kind(p) {
+    try {
+        const s = lstatSync(p);
+        return s.isSymbolicLink() ? 'link' : s.isDirectory() ? 'dir' : 'file';
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+function text(file) {
+    try {
+        return readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+    }
+    catch {
+        return '\0unreadable';
+    }
+}
+/** A file as it goes into the hash: its content, or the fact that it is a link or cannot be read. */
+const body = (file) => (kind(file) === 'file' ? text(file) : `\0${kind(file)}`);
+function filesIn(dir, base) {
+    const out = [];
+    if (!existsSync(dir))
+        return out;
+    let names;
+    try {
+        names = readdirSync(dir).sort();
+    }
+    catch {
+        return [relative(base, dir).split(sep).join('/')];
+    }
+    for (const name of names) {
+        const full = join(dir, name);
+        if (kind(full) === 'dir')
+            out.push(...filesIn(full, base));
+        else
+            out.push(relative(base, full).split(sep).join('/'));
+    }
+    return out;
+}
+/**
+ * The hash of the surface of an app folder and the names of the files that went into it. When the app sits in a subfolder of the git root (`parent`), the package
+ * manager's settings of the root also count (yarn merges .yarnrc.yml upward), so the root's fixed files and program folders are hashed under a `root:` prefix.
+ */
+export function surfaceHash(repo, parent = null) {
+    const names = [];
+    const parts = [];
+    const pkg = join(repo, 'package.json');
+    if (kind(pkg) !== 'unreadable') {
+        let scripts;
+        try {
+            const parsed = JSON.parse(text(pkg));
+            scripts =
+                parsed && typeof parsed === 'object'
+                    ? (parsed.scripts ?? {})
+                    : {};
+        }
+        catch {
+            scripts = { __unreadable: true };
+        }
+        names.push('package.json#scripts');
+        parts.push(`package.json#scripts\0${JSON.stringify(scripts)}`);
+    }
+    const list = (dir) => {
+        try {
+            return existsSync(dir) ? readdirSync(dir) : [];
+        }
+        catch {
+            return [];
+        }
+    };
+    const rootNames = list(repo);
+    const listed = [
+        ...new Set([
+            ...FIXED.filter((f) => rootNames.includes(f)),
+            ...rootNames.filter((f) => CONFIG.test(f))
+        ])
+    ].sort();
+    for (const f of listed) {
+        names.push(f);
+        parts.push(`${f}\0${body(join(repo, f))}`);
+    }
+    for (const d of PROGRAM_DIRS)
+        for (const f of filesIn(join(repo, d), repo)) {
+            names.push(f);
+            parts.push(`${f}\0${body(join(repo, f))}`);
+        }
+    if (parent && resolve(parent) !== resolve(repo)) {
+        const parentNames = list(parent);
+        for (const f of FIXED.filter((n) => parentNames.includes(n) && n !== '.afb-checks.json')) {
+            names.push(`root:${f}`);
+            parts.push(`root:${f}\0${body(join(parent, f))}`);
+        }
+        for (const d of PROGRAM_DIRS)
+            for (const f of filesIn(join(parent, d), parent)) {
+                names.push(`root:${f}`);
+                parts.push(`root:${f}\0${body(join(parent, f))}`);
+            }
+    }
+    return { hash: createHash('sha256').update(parts.join('\n')).digest('hex'), files: names };
+}