@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/install.js

@@ -0,0 +1,150 @@
+// THE INSTALL OF A PRIVATE COPY: WHICH COMMAND, WHETHER IT MAY BE CACHED, AND HOW A PACKAGE MANAGER IS STARTED ON WINDOWS.
+// The commands are constants: nothing in the repo can change them. They install exactly what the lock file says and, where the package manager
+// allows it, with the package scripts switched off (a postinstall script would run a program the agent wrote).
+// -- DEP-MODULES -- //
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+// -- CONSTANTS -- //
+/** The programs that are .cmd shims on Windows. */
+const SHIMMED = /^(yarn|npm|pnpm|npx)$/;
+/** The files an install depends on. */
+const LOCK_INPUTS = [
+    'yarn.lock',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+    '.pnpmfile.cjs',
+    '.yarnrc.yml'
+];
+// -- FUNCTIONS -- //
+const has = (dir, file) => existsSync(join(dir, file));
+/** Which package manager the lock file in `dir` names, or null when there is none (a frozen install needs one) or no package.json. */
+export function packageManagerOf(dir) {
+    if (!has(dir, 'package.json'))
+        return null;
+    if (has(dir, 'yarn.lock'))
+        return 'yarn';
+    if (has(dir, 'package-lock.json'))
+        return 'npm';
+    if (has(dir, 'pnpm-lock.yaml'))
+        return 'pnpm';
+    return null;
+}
+/**
+ * The frozen install command for `dir`, or null when it has no lock file. Yarn with a .yarnrc.yml is Yarn 4, whose own `--immutable` is the frozen
+ * form; the others get --ignore-scripts.
+ */
+export function installCommand(dir) {
+    switch (packageManagerOf(dir)) {
+        case 'yarn':
+            return has(dir, '.yarnrc.yml')
+                ? ['yarn', 'install', '--immutable']
+                : ['yarn', 'install', '--frozen-lockfile', '--ignore-scripts'];
+        case 'npm':
+            return ['npm', 'ci', '--ignore-scripts'];
+        case 'pnpm':
+            return ['pnpm', 'install', '--frozen-lockfile', '--ignore-scripts'];
+        default:
+            return null;
+    }
+}
+/**
+ * True when the finished install of `dir` may be kept and copied into another folder. A pnpm install never is: pnpm writes the absolute path of its
+ * store into node_modules/.modules.yaml, and its links point into that store, so a copy in another folder is refused by the next pnpm run.
+ */
+export function installCacheable(dir) {
+    const manager = packageManagerOf(dir);
+    if (!manager || manager === 'pnpm')
+        return false;
+    // A node_modules that pnpm made is never cached whatever lock file sits beside it
+    if (has(dir, join('node_modules', '.modules.yaml')) || has(dir, '.modules.yaml'))
+        return false;
+    return true;
+}
+/** A hash of the files an install depends on: what the installed dependencies depend on. */
+export function lockHash(dir) {
+    const h = createHash('sha1');
+    for (const f of LOCK_INPUTS)
+        if (has(dir, f))
+            h.update(f).update(readFileSync(join(dir, f)));
+    return h.digest('hex');
+}
+/** The first file on PATH named `name` with one of the executable extensions, or null. Case-insensitive on Windows. */
+export function findOnPath(name, pathEnv, exts, exists = existsSync) {
+    for (const dir of pathEnv.split(delimiter).filter(Boolean))
+        for (const ext of exts) {
+            const file = join(dir, name + ext);
+            if (exists(file))
+                return file;
+        }
+    return null;
+}
+/**
+ * What to start for a command. On Windows yarn, npm and pnpm are usually .cmd shims, which a plain spawn cannot find and Node refuses to start
+ * directly (EINVAL): they go through `cmd.exe /d /s /c name.cmd`, unless a real .exe of that name is first on PATH. The arguments came from a command
+ * that was already checked (words, flags and a port, no shell characters), so cmd.exe has nothing to interpret. Elsewhere the argv is unchanged.
+ */
+export function programArgv(argv, opts = {}) {
+    const [file, ...args] = argv;
+    if (!file || (opts.platform ?? process.platform) !== 'win32' || !SHIMMED.test(file))
+        return argv;
+    const found = findOnPath(file, opts.pathEnv ?? '', ['.exe', '.cmd', '.bat'], opts.exists);
+    if (found && found.toLowerCase().endsWith('.exe'))
+        return [found, ...args];
+    return ['cmd.exe', '/d', '/s', '/c', `${file}.cmd`, ...args];
+}
+/** The PATH of an environment object, whatever its case (Windows calls it Path). */
+export function pathOf(env) {
+    for (const k of Object.keys(env))
+        if (k.toLowerCase() === 'path')
+            return env[k] ?? '';
+    return '';
+}
+/**
+ * The folder an install runs in: `appCwd` when it holds a lock file, else the nearest folder above it, up to `stopAt` (the root of the private copy), that does.
+ * A monorepo keeps one lock file at the top and the apps below it. Null when there is none, and the install is skipped.
+ */
+export function installDirFor(appCwd, stopAt) {
+    const top = resolve(stopAt);
+    let dir = resolve(appCwd);
+    for (let i = 0; i < 32; i++) {
+        if (packageManagerOf(dir))
+            return dir;
+        if (dir === top)
+            return null;
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        // Never above the copy
+        const rel = relative(top, up);
+        if (rel.startsWith('..') || isAbsolute(rel))
+            return null;
+        dir = up;
+    }
+    return null;
+}
+/** How a version is asked for. A test replaces it. */
+export const versionIo = {
+    run: (argv, opts) => new Promise((resolveRun) => {
+        const [file, ...args] = programArgv(argv, { pathEnv: pathOf(opts.env) });
+        if (!file)
+            return resolveRun('');
+        execFile(file, args, { cwd: opts.cwd, env: opts.env, windowsHide: true, timeout: 30_000 }, (err, stdout) => resolveRun(err ? '' : (String(stdout).trim().split(/\r?\n/)[0] ?? '')));
+    })
+};
+const versions = new Map();
+/** The version of a package manager as `<pm> --version` prints it, asked once per process. An empty string when it cannot be asked (the cache key then differs from every real version). */
+export async function packageManagerVersion(pm, cwd, env = process.env) {
+    const known = versions.get(pm);
+    if (known !== undefined)
+        return known;
+    const version = (await versionIo.run([pm, '--version'], { cwd, env })).slice(0, 40);
+    // A failed ask is not remembered: the next run asks again
+    if (version)
+        versions.set(pm, version);
+    return version;
+}
+/** Forgets the versions asked so far (tests). */
+export const forgetPackageManagerVersions = () => versions.clear();

package/dist/checks/live.js

@@ -0,0 +1,76 @@
+// LIVE-SITE REGISTRATIONS: A REGISTRATION WITH A URL AND NO REPO. NOTHING IS BUILT OR STARTED; THE RUN IS UNVERIFIED AND NEVER WRITES.
+// This file only judges the settings (url and extraHosts) and hands the guard its options. Writes are never allowed on a live site: a check
+// there drives pages and reads, and the guard stops every POST, PUT, PATCH and DELETE.
+// -- MODULES -- //
+import { FORBIDDEN_PORTS } from './guardrails.js';
+// -- CONSTANTS -- //
+const MAX_EXTRA_HOSTS = 16;
+/** A plain DNS name: dot separated labels of letters, digits and dashes. No wildcard, port, path or underscore. */
+const HOST_NAME = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+const LOCAL_HOSTS = new Set([
+    'localhost',
+    '127.0.0.1',
+    '[::1]',
+    '::1',
+    '0.0.0.0',
+    'host.docker.internal'
+]);
+// -- FUNCTIONS -- //
+const isLoopbackName = (h) => LOCAL_HOSTS.has(h) || h.endsWith('.localhost') || /^127\./.test(h) || h === '[::]';
+/** True for a dotted IPv4 address (also the short and number forms a browser accepts) or anything holding a colon (IPv6). */
+const isIpLiteral = (h) => h.includes(':') || h.startsWith('[') || /^[0-9.]+$/.test(h) || /^0x[0-9a-f]+$/i.test(h);
+/** One plain sentence per problem with the live-site settings. An empty list means they are acceptable. */
+export function liveSiteProblems(cfg) {
+    const problems = [];
+    if (cfg.url !== undefined) {
+        let u = null;
+        try {
+            u = new URL(String(cfg.url));
+        }
+        catch {
+            problems.push('The site address is not a web address.');
+        }
+        if (u) {
+            if (u.protocol !== 'http:' && u.protocol !== 'https:')
+                problems.push('The site address must start with http:// or https://.');
+            else {
+                if (u.username || u.password)
+                    problems.push('The site address may not hold a user name or password.');
+                const host = u.hostname.toLowerCase();
+                if (isLoopbackName(host)) {
+                    const port = Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+                    if (FORBIDDEN_PORTS.has(port))
+                        problems.push(`The site address uses port ${port}, which a check never uses.`);
+                }
+            }
+        }
+    }
+    const extra = cfg.extraHosts ?? [];
+    if (!Array.isArray(extra))
+        return [...problems, 'The extra hosts must be a list of host names.'];
+    if (extra.length > MAX_EXTRA_HOSTS)
+        problems.push(`At most ${MAX_EXTRA_HOSTS} extra hosts are allowed.`);
+    for (const raw of extra) {
+        const h = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+        const shown = typeof raw === 'string' ? raw.slice(0, 60) : String(typeof raw);
+        if (!h || (!HOST_NAME.test(h) && !isIpLiteral(h)))
+            problems.push(`The extra host "${shown}" is not an exact host name (no wildcard, port, path or address).`);
+        else if (isIpLiteral(h))
+            problems.push(`The extra host "${shown}" is an IP address. Only host names are allowed.`);
+        else if (isLoopbackName(h))
+            problems.push(`The extra host "${shown}" is this machine, which is never an extra host.`);
+    }
+    return problems;
+}
+/** What the child's guard is given for a live site: writes never allowed, and only the exact extra hosts reachable besides the site. */
+export function liveSiteGuardOptions(cfg) {
+    const bad = liveSiteProblems(cfg);
+    if (bad.length)
+        throw new Error(bad[0]);
+    return {
+        allowWrites: false,
+        extraHosts: [...new Set((cfg.extraHosts ?? []).map((h) => h.trim().toLowerCase()))]
+    };
+}
+/** True when the settings describe a live site (a url and no repo to build). */
+export const isLiveSite = (cfg) => typeof cfg.url === 'string' && cfg.url !== '';

package/dist/checks/lock.js

@@ -0,0 +1,207 @@
+// FILE LOCKS FOR THE CHECK COMMANDS: A SHORT EXCLUSIVE LOCK (THE AUDIT CHAIN) AND THE ONE-WORKER-PER-MACHINE LOCK OF `check watch`.
+// Two lessons are built in. A lock file that is created empty and written afterwards looks stale to a second process, so the file is written whole into a
+// temporary file and linked into place in one step. A stale lock that is unlinked and then created again lets two contenders in, so a stale lock is RENAMED
+// aside, what was moved is compared with the stale one that was seen, and a fresh lock that was moved by mistake is put back.
+// -- DEP-MODULES -- //
+import { randomBytes } from 'node:crypto';
+import { linkSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { renameRetry } from './fsretry.js';
+import { assertName, ensureDir, locksDir } from './paths.js';
+// -- CONSTANTS -- //
+/** A lock whose content cannot be read is only treated as stale after this long (it is created whole, so this means a damaged file). */
+const UNREADABLE_GRACE_MS = 2_000;
+/** For a lock that only a dead process may lose. */
+export const NEVER_STALE_MS = Number.MAX_SAFE_INTEGER;
+/**
+ * The worker lock is lost by a dead process, and also by a heartbeat that stopped: a crashed worker whose process id was handed to another program would otherwise lock
+ * out `check watch` for ever. The worker touches its lock every few seconds (watch.ts), so this is long enough to survive a busy machine.
+ */
+export const WORKER_STALE_MS = 3 * 60_000;
+// -- FUNCTIONS -- //
+/** True when a process with this id exists (it may belong to another user, which still counts as alive). */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+const lockPath = (name) => join(locksDir(), `${assertName(name, 'lock name')}.lock`);
+function parseBody(text) {
+    try {
+        const v = JSON.parse(text);
+        if (!v || typeof v !== 'object')
+            return null;
+        const b = v;
+        if (typeof b.pid !== 'number' || typeof b.at !== 'string' || typeof b.token !== 'string')
+            return null;
+        return { pid: b.pid, at: b.at, token: b.token };
+    }
+    catch {
+        return null;
+    }
+}
+function readText(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function isStale(text, file, staleMs) {
+    const body = text === null ? null : parseBody(text);
+    if (body)
+        return !pidAlive(body.pid) || Date.now() - Date.parse(body.at) > staleMs;
+    // Unreadable or damaged: given a moment, then stale
+    try {
+        return Date.now() - statSync(file).mtimeMs > UNREADABLE_GRACE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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 file aside under a name of its own. Returns what was moved, or null when somebody else moved it first. When what was moved is not
+ * `expected` (somebody made a new lock between the look and the move), it is linked back.
+ */
+function moveAside(file, expected, keep) {
+    const aside = `${file}.aside.${process.pid}.${randomBytes(4).toString('hex')}`;
+    try {
+        renameSync(file, aside);
+    }
+    catch {
+        return null;
+    }
+    const moved = readText(aside);
+    if (moved !== null && moved !== expected && keep(moved)) {
+        try {
+            linkSync(aside, file);
+        }
+        catch {
+            /* A newer lock is already there: the one that was moved is dropped */
+        }
+    }
+    rmSync(aside, { force: true });
+    return moved ?? '';
+}
+/**
+ * Takes the lock `name` without waiting. Returns null when a live holder has it. A lock whose process is gone, or that is older than `staleMs`,
+ * is taken over.
+ */
+export function acquireLock(name, { staleMs }) {
+    const file = lockPath(name);
+    ensureDir(locksDir());
+    const token = randomBytes(8).toString('hex');
+    const mine = JSON.stringify({ pid: process.pid, at: new Date().toISOString(), token }) +
+        '\n';
+    for (let attempt = 0; attempt < 6; attempt++) {
+        if (tryCreate(file, mine))
+            return makeLock(file, token);
+        const held = readText(file);
+        if (held === null && !statExists(file))
+            continue; // Released between the two looks
+        if (!isStale(held, file, staleMs))
+            return null;
+        // Stale: moved aside in one step, so of two contenders only one moves it. A fresh lock that was moved by mistake goes back
+        moveAside(file, held, (moved) => !isStale(moved, file, staleMs));
+    }
+    return null;
+}
+const statExists = (file) => {
+    try {
+        statSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+function makeLock(file, token) {
+    let released = false;
+    return {
+        file,
+        touch() {
+            if (released)
+                return;
+            const text = readText(file);
+            const body = text === null ? null : parseBody(text);
+            if (!body || body.token !== token)
+                return;
+            const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+            try {
+                const next = { ...body, at: new Date().toISOString() };
+                writeFileSync(tmp, JSON.stringify(next) + '\n', { mode: 0o600 });
+                renameRetry(tmp, file);
+            }
+            catch {
+                // The next touch tries again
+                rmSync(tmp, { force: true });
+            }
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            // Moved aside first, so a lock that was taken over from us in the meantime is never removed by mistake
+            const text = readText(file);
+            if (text === null || parseBody(text)?.token !== token)
+                return;
+            moveAside(file, text, () => true);
+        }
+    };
+}
+const nap = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** Runs `fn` while holding the lock, waiting up to `waitMs` for another holder. Throws one plain sentence when it could not get the lock. */
+export function withLockSync(name, fn, { staleMs = 15_000, waitMs = 20_000 } = {}) {
+    const until = Date.now() + waitMs;
+    let lock = acquireLock(name, { staleMs });
+    while (!lock) {
+        if (Date.now() > until)
+            throw new Error(`Another process kept the "${name}" lock for more than ${Math.round(waitMs / 1000)} seconds.`);
+        nap(15);
+        lock = acquireLock(name, { staleMs });
+    }
+    try {
+        return fn();
+    }
+    finally {
+        lock.release();
+    }
+}
+/** The process id that holds a lock, or null when nobody does. For the plain sentence of a refused second worker. */
+export function lockHolderPid(name) {
+    const text = readText(lockPath(name));
+    const body = text === null ? null : parseBody(text);
+    return body && pidAlive(body.pid) ? body.pid : null;
+}
+/**
+ * The one-worker-per-machine lock of `check watch`. A dead process loses it, and so does one whose heartbeat stopped for three minutes (a reused process id).
+ * The worker calls `touch()` on its lock regularly. Returns null when another worker holds it; the caller says so in one plain line.
+ */
+export function machineLock(name) {
+    return acquireLock(`machine-${name}`, { staleMs: WORKER_STALE_MS });
+}

package/dist/checks/login.js

@@ -0,0 +1,203 @@
+// `check login <NAME> --org <slug> [--seeded]`: SAVING A SIGN-IN FOR A REGISTRATION'S SITE, AND THE RULES FOR USING ONE
+// --seeded signs in with a seeded account (AFB_CHECKS_<NAME>_EMAIL and _PASSWORD) or the recipe's test user, through the app's own form.
+// Without --seeded a person signs in by hand in a visible browser window: that needs an interactive terminal, and is refused without one.
+// This file is the ONE place in the bridge that reads a terminal, and only in waitForEnter, only after the TTY check.
+// Nothing here starts a preview itself: the caller injects `target`, and the sign in function is injected too, so tests launch no browser.
+// A cookie, a password or a token is never printed.
+// -- DEP-MODULES -- //
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { loadPlaywright } from './browser.js';
+import { ORG_SLUG, registrationsDir } from './paths.js';
+import { expiryNote, loadProfileChecked, saveProfile } from './profiles.js';
+import { redact } from './redact.js';
+import { signInWithPassword } from './signin.js';
+// -- CONSTANTS -- //
+const NAME = /^[A-Za-z0-9_-]{1,32}$/;
+// -- FUNCTIONS -- //
+/** The variable names of a registration: AFB_CHECKS_<NAME upper, dash to underscore>_EMAIL and _PASSWORD. */
+export function envNames(name) {
+    const n = String(name).toUpperCase().replace(/-/g, '_');
+    return { email: `AFB_CHECKS_${n}_EMAIL`, password: `AFB_CHECKS_${n}_PASSWORD` };
+}
+/** The seeded account of a registration from the environment, or null when either variable is missing or empty. */
+export function seededAccount(name, env = process.env) {
+    const n = envNames(name);
+    const email = env[n.email];
+    const password = env[n.password];
+    return email && password ? { email, password } : null;
+}
+/**
+ * Whether a run uses a saved sign-in. Only when the script's header (or the check) names the very registration the run uses: a run that was
+ * routed there by a fallback, or a script that names another registration, opens signed out. Names compare without regard to case.
+ */
+export function chooseState(input) {
+    const { registration, scriptRegistration, profile } = input;
+    if (!profile || !scriptRegistration || !registration)
+        return 'none';
+    return scriptRegistration.toLowerCase() === registration.toLowerCase() ? 'saved' : 'none';
+}
+/** Pictures of a signed-in run are uploaded only when the owner opted in on the registration. A signed-out run uploads as usual. */
+export function pictureUploadAllowed(registration, signedIn) {
+    return !signedIn || registration.uploadSignedInPictures === true;
+}
+/** The saved sign-in a run should open with, with the expiry note, or null. Applies chooseState. */
+export function savedStateFor(input) {
+    const { profile, damaged } = loadProfileChecked(input.org, input.registration, input.bindKey);
+    // A saved sign-in that cannot be opened says so: the run would otherwise go signed out and fail on a sign-in page with no explanation
+    if (damaged)
+        return {
+            profile: null,
+            note: 'The saved sign-in is damaged, make it again (agent-flow-board check login).'
+        };
+    if (chooseState({ ...input, profile }) !== 'saved' || !profile)
+        return null;
+    return { profile, note: expiryNote(profile) };
+}
+/** Cookies and origins that belong to the site's hosts, nothing else (no other site's sign-in is saved). */
+export function keepRelated(state, hosts) {
+    const s = state;
+    const bare = (d) => d.replace(/^\./, '').toLowerCase();
+    const related = (d) => hosts.some((h) => {
+        const a = bare(d);
+        const b = h.toLowerCase();
+        return a === b || b.endsWith(`.${a}`) || a.endsWith(`.${b}`);
+    });
+    return {
+        cookies: (s?.cookies ?? []).filter((c) => related(String(c.domain ?? ''))),
+        origins: (s?.origins ?? []).filter((o) => {
+            try {
+                return related(new URL(String(o.origin)).hostname);
+            }
+            catch {
+                return false;
+            }
+        })
+    };
+}
+/** The one terminal read of the bridge: waits for the person to press Enter. Used only by the headed login, after the TTY check. */
+function waitForEnter(question) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, () => {
+            rl.close();
+            resolve();
+        });
+    });
+}
+/** The headed login: a visible browser the person drives, then Enter. Only cookies and origins of the site are kept. */
+async function headedLogin(target, say) {
+    const { chromium } = await loadPlaywright();
+    const browser = await chromium.launch({ headless: false });
+    try {
+        const ctx = await browser.newContext({ baseURL: target.baseUrl, viewport: null });
+        const page = await ctx.newPage();
+        await page.goto(target.baseUrl);
+        say(`A browser window is open on ${target.baseUrl}. Sign in there the way you normally do (a password or Google).`);
+        say('When you can see you are signed in, come back here and press Enter. Do not close the window first.');
+        await waitForEnter('Press Enter when signed in... ');
+        const hosts = [new URL(target.baseUrl).hostname, ...(target.hosts ?? [])];
+        return keepRelated(await ctx.storageState(), hosts);
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+    }
+}
+function loadRegistrationFile(org, name) {
+    try {
+        return JSON.parse(readFileSync(join(registrationsDir(), org, `${name}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** The default target: only a live site needs no preview. A repo registration needs the caller to start its preview. */
+async function defaultTarget(registration) {
+    if (!registration.url)
+        throw new Error(`${registration.name} is built from a repo, so its sign-in needs a preview. Start one through the run command.`);
+    return {
+        baseUrl: registration.url,
+        hosts: registration.extraHosts ?? [],
+        stop: async () => undefined
+    };
+}
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+/** `check login <NAME> --org <slug> [--seeded]`. Exit code 0 saved, 1 a problem with what was asked, 2 could not run. */
+export async function loginCommand(args, ctx) {
+    const deps = {
+        signIn: (baseUrl, account) => signInWithPassword(baseUrl, account),
+        headed: headedLogin,
+        isTTY: Boolean(process.stdin.isTTY),
+        env: process.env,
+        loadRegistration: loadRegistrationFile,
+        target: defaultTarget,
+        save: saveProfile,
+        ...ctx.deps
+    };
+    const say = (line) => ctx.log(line);
+    const flags = new Set(['--org']);
+    const positional = args.filter((a, i) => !a.startsWith('--') && !flags.has(args[i - 1] ?? ''));
+    const name = positional[0];
+    const org = flagValue(args, '--org');
+    const seeded = args.includes('--seeded');
+    if (!name || !org) {
+        say('Usage: check login <NAME> --org <slug> [--seeded]');
+        return 1;
+    }
+    if (!NAME.test(name) || !ORG_SLUG.test(org)) {
+        say('The registration name or the organisation is not a plain name.');
+        return 1;
+    }
+    // A headed login waits for a person at a screen: without a terminal it would wait for ever, so it stops at once
+    if (!seeded && !deps.isTTY) {
+        say('Signing in by hand needs a person at a terminal (it opens a browser window and waits), so it is refused here. Use --seeded with AFB_CHECKS_<NAME>_EMAIL and AFB_CHECKS_<NAME>_PASSWORD set, or a registration whose recipe has a test user.');
+        return 1;
+    }
+    const registration = deps.loadRegistration(org, name);
+    if (!registration || registration.org !== org) {
+        say(`No registration "${name}" in ${org}.`);
+        return 1;
+    }
+    let target = null;
+    const secrets = [];
+    try {
+        target = await deps.target(registration);
+        const bindKey = new URL(target.baseUrl).origin;
+        let state;
+        if (seeded) {
+            const account = seededAccount(name, deps.env) ?? target.testUser ?? null;
+            if (!account) {
+                const n = envNames(name);
+                say(`No account to sign in with. Set ${n.email} and ${n.password}, or give the recipe a test user.`);
+                return 1;
+            }
+            secrets.push(account.password);
+            state = await deps.signIn(target.baseUrl, account);
+        }
+        else {
+            state = await deps.headed(target, say);
+        }
+        const kept = state;
+        if (!kept || (!(kept.cookies?.length ?? 0) && !(kept.origins?.length ?? 0))) {
+            say('Nothing was saved because the browser holds no sign-in for this address.');
+            return 1;
+        }
+        deps.save(org, name, bindKey, state);
+        say(`Saved the sign-in for ${org}/${name} on ${bindKey}. It stays on this machine, sealed.`);
+        if (ctx.json)
+            ctx.out(JSON.stringify({ saved: true, registration: `${org}/${name}`, site: bindKey }));
+        return 0;
+    }
+    catch (e) {
+        say(redact(e instanceof Error ? e.message : String(e), secrets));
+        return 2;
+    }
+    finally {
+        await target?.stop().catch(() => undefined);
+    }
+}