@vincemakes/kiso-web 0.0.0-stage → 0.53.0

package/dist/main/fork.js

@@ -0,0 +1,25 @@
+import { ForkRefusedError } from "@vincemakes/kiso-runtime";
+import { Refusal } from "./files.js";
+/**
+ * Fork a Work: the runtime's SessionStore.fork (one rule for the terminal, the web app and the products, plan fork rev 2),
+ * after the run that ended at `atSeq` (absent: the last). The runtime copies the log to that run's end, writes the fork's
+ * sidecar (the parent's profile, "… (fork)", its origin) and gives the fork note to the model with the fork's first input,
+ * after the copied history: never in the system prompt, where it cost the fork's first request the whole history's cache
+ * (0% against 88% measured on co). The host still remembers the lineage for the forks it made before.
+ */
+export function forkWork(space, settings, parent, atSeq) {
+    if (!space.store.ids().includes(parent))
+        throw new Refusal(404, "no such Work in this folder");
+    let made;
+    try {
+        made = space.store.fork(parent, atSeq === undefined ? {} : { afterSeq: atSeq });
+    }
+    catch (error) {
+        if (error instanceof ForkRefusedError)
+            throw new Refusal(409, error.message.replace(/session/g, "Work"));
+        throw error;
+    }
+    const fork = { parent, title: made.origin.title, atSeq: made.origin.afterSeq, at: made.origin.at };
+    settings.forked(parent, made.id, fork);
+    return { id: made.id, fork };
+}

package/dist/main/fs-routes.js

@@ -0,0 +1,69 @@
+import { execFileSync } from "node:child_process";
+import { readdirSync, realpathSync } from "node:fs";
+import { listDir, readPreview, readTaskLog, Refusal } from "./files.js";
+/**
+ * The read doors of the page: a Work's folder (a tree, a file, the list the
+ * composer's @ picks from) and a background task's log. GET only, behind the host's guard; every path is
+ * judged by files.ts, a task id only by the task manager of a session that
+ * exists in the Work's folder.
+ */
+export const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+export function deskRead(url, space) {
+    try {
+        const rel = url.searchParams.get("path") ?? "";
+        if (url.pathname === "/desk/task-log") {
+            const session = url.searchParams.get("session") ?? "";
+            const task = url.searchParams.get("task") ?? "";
+            if (!SAFE_ID.test(session) || !SAFE_ID.test(task) || !space.store.ids().includes(session))
+                throw new Refusal(404, "no such task");
+            const info = space.tasks.managerFor(session).list().find((t) => t.id === task);
+            if (info === undefined)
+                throw new Refusal(404, "no such task");
+            return { status: 200, body: readTaskLog(info.outputPath) };
+        }
+        let root;
+        try {
+            root = realpathSync(space.workspace);
+        }
+        catch {
+            throw new Refusal(404, "the folder is gone");
+        }
+        return { status: 200, body: url.pathname === "/desk/fs/tree" ? listDir(root, rel) : readPreview(root, rel) };
+    }
+    catch (error) {
+        if (error instanceof Refusal)
+            return { status: error.status, body: { code: "refused", message: error.message } };
+        return { status: 500, body: { code: "internal", message: "unreadable" } };
+    }
+}
+const AT_CAP = 2000;
+const AT_SKIP = new Set([".git", "node_modules", ".kiso", "dist", "build", ".next", ".venv", "__pycache__"]);
+/** The files `@` can name, as the terminal lists them: git's own list (tracked and untracked, ignores honoured), else a bounded walk; `truncated` when the cap cut it. */
+export function atFiles(space) {
+    let files;
+    try {
+        files = execFileSync("git", ["ls-files", "-c", "-o", "--exclude-standard"], { cwd: space.workspace, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 1 << 24, timeout: 3000 }).split("\n").filter((p) => p !== "");
+    }
+    catch {
+        files = [];
+        const walk = (dir, prefix) => {
+            try {
+                for (const e of readdirSync(dir, { withFileTypes: true })) {
+                    if (files.length > AT_CAP)
+                        return;
+                    if (AT_SKIP.has(e.name))
+                        continue;
+                    if (e.isDirectory())
+                        walk(`${dir}/${e.name}`, `${prefix}${e.name}/`);
+                    else if (e.isFile())
+                        files.push(`${prefix}${e.name}`);
+                }
+            }
+            catch {
+                // an unreadable directory adds nothing
+            }
+        };
+        walk(space.workspace, "");
+    }
+    return { files: files.slice(0, AT_CAP), truncated: files.length > AT_CAP };
+}

package/dist/main/git.js

@@ -0,0 +1,117 @@
+import { execFile } from "node:child_process";
+import { Refusal } from "./files.js";
+/**
+ * The rail's Changes from git, and the one write it can make on the person's word: commit the files they ticked, push the branch
+ * and open a pull request with `gh`. Reads are bounded (a timeout each, nothing on a folder outside git); the writes run only
+ * from the dialog's confirm (POST), never by themselves, and refuse what they cannot do in words.
+ */
+const run = (cwd, cmd, args, timeout = 3000) => new Promise((resolve, reject) => execFile(cmd, [...args], { cwd, timeout, maxBuffer: 1 << 23, env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1" } }, (err, out, errOut) => (err === null ? resolve(out) : reject(new Error((errOut || err.message).trim())))));
+const tryRun = (cwd, cmd, args, timeout) => run(cwd, cmd, args, timeout).then((o) => o.trim(), () => null);
+let ghSignedIn = null;
+/** `gh auth status`, asked once per host process: a sign-in does not come and go between two clicks. */
+const ghReady = (cwd) => (ghSignedIn ??= tryRun(cwd, "gh", ["auth", "status"], 5000).then((o) => o !== null));
+async function baseOf(cwd) {
+    const head = await tryRun(cwd, "git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+    if (head !== null)
+        return head.replace(/^origin\//, "");
+    for (const name of ["main", "master"])
+        if ((await tryRun(cwd, "git", ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`])) !== null)
+            return name;
+    return null;
+}
+/** The changed paths and their two-letter codes (`git status -z`: NUL-separated, so a path with a space or a quote is read whole; a rename gives its new path). */
+async function statusOf(cwd) {
+    const out = (await run(cwd, "git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"]).catch(() => "")).split("\0");
+    const map = new Map();
+    for (let i = 0; i < out.length; i++) {
+        const e = out[i];
+        if (e.length < 4)
+            continue;
+        map.set(e.slice(3), e.slice(0, 2));
+        if (e[0] === "R" || e[0] === "C")
+            i += 1; // the old path follows a rename or a copy
+    }
+    return map;
+}
+/** The base as a ref to compare with: origin's copy when there is one (what the PR is judged against), else the local branch. */
+const baseRef = async (cwd, base) => ((await tryRun(cwd, "git", ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${base}`])) !== null ? `origin/${base}` : base);
+export async function gitOf(cwd) {
+    const none = { repo: false, branch: null, base: null, ahead: 0, files: [], dirty: false, canPr: false, pr: null };
+    if ((await tryRun(cwd, "git", ["rev-parse", "--is-inside-work-tree"])) !== "true")
+        return none;
+    const branch = await tryRun(cwd, "git", ["symbolic-ref", "--short", "HEAD"]);
+    const base = await baseOf(cwd);
+    const ref = base === null ? null : await baseRef(cwd, base);
+    const fork = ref === null ? null : await tryRun(cwd, "git", ["merge-base", ref, "HEAD"]);
+    const ahead = ref === null ? 0 : Number((await tryRun(cwd, "git", ["rev-list", "--count", `${ref}..HEAD`])) ?? 0);
+    const dirty = await statusOf(cwd);
+    const numstat = fork === null ? "" : await run(cwd, "git", ["diff", "--numstat", "-z", "--no-renames", fork]).catch(() => "");
+    const files = new Map();
+    for (const entry of numstat.split("\0").filter((l) => l !== "")) {
+        const [a, r, path] = entry.split("\t");
+        files.set(path, { path, added: a === "-" ? null : Number(a), removed: r === "-" ? null : Number(r), state: "modified", dirty: dirty.has(path) });
+    }
+    for (const [path, code] of dirty) {
+        const state = code.includes("?") || code.includes("A") ? "new" : code.includes("D") ? "deleted" : "modified";
+        files.set(path, { ...(files.get(path) ?? { path, added: null, removed: null }), state, dirty: true });
+    }
+    const remote = await tryRun(cwd, "git", ["remote", "get-url", "origin"]);
+    const canPr = branch !== null && base !== null && branch !== base && remote !== null && (await ghReady(cwd));
+    let pr = null;
+    if (canPr) {
+        const json = await tryRun(cwd, "gh", ["pr", "view", "--json", "number,title,url,state,statusCheckRollup"], 6000);
+        if (json !== null) {
+            const p = JSON.parse(json);
+            const checks = p.statusCheckRollup ?? [];
+            pr = { number: p.number, title: p.title, url: p.url, state: p.state, checks: { total: checks.length, done: checks.filter((c) => c.status === "COMPLETED").length, failed: checks.filter((c) => c.conclusion === "FAILURE").length } };
+        }
+    }
+    return { repo: true, branch, base, ahead, files: [...files.values()], dirty: dirty.size > 0, canPr, pr };
+}
+/** Commit the files the person ticked, with their message: those paths only (never `git add -A`), so nothing they did not see is committed. */
+export async function commit(cwd, message, paths) {
+    if (message.trim() === "")
+        throw new Refusal(400, "a commit needs a message");
+    if (paths.length === 0)
+        throw new Refusal(400, "no file was chosen");
+    const listed = await statusOf(cwd);
+    const strange = paths.filter((p) => !listed.has(p));
+    if (strange.length > 0)
+        throw new Refusal(400, `not a changed file of this folder: ${strange.join(", ")}`);
+    await run(cwd, "git", ["add", "--", ...paths]);
+    await run(cwd, "git", ["commit", "-m", message, "--", ...paths]).catch((e) => {
+        throw new Refusal(409, `git refused the commit: ${e.message}`);
+    });
+    return { sha: (await run(cwd, "git", ["rev-parse", "--short", "HEAD"])).trim() };
+}
+/** Push the branch and open its pull request into the base; refused with the reason when the folder cannot. */
+export async function openPr(cwd, title, body) {
+    const g = await gitOf(cwd);
+    if (!g.canPr || g.branch === null || g.base === null)
+        throw new Refusal(409, "a pull request needs a branch other than the base, a remote named origin, and gh signed in");
+    if (g.dirty)
+        throw new Refusal(409, "commit the changes first: a pull request carries commits, not the working tree");
+    if (g.ahead === 0)
+        throw new Refusal(409, `${g.branch} has no commit that ${g.base} does not have`);
+    if (title.trim() === "")
+        throw new Refusal(400, "a pull request needs a title");
+    await run(cwd, "git", ["push", "-u", "origin", "HEAD"], 60_000).catch((e) => {
+        throw new Refusal(409, `git push failed: ${e.message}`);
+    });
+    const out = await run(cwd, "gh", ["pr", "create", "--base", g.base, "--head", g.branch, "--title", title, "--body", body], 60_000).catch((e) => {
+        throw new Refusal(409, `gh pr create failed: ${e.message}`);
+    });
+    const url = out.trim().split("\n").pop() ?? "";
+    return { number: Number(/\/pull\/(\d+)/.exec(url)?.[1] ?? 0), url };
+}
+/** The dialog's starting draft from the branch's own commits: one commit gives its subject; several, the branch's name and a list. */
+export async function prDraft(cwd) {
+    const g = await gitOf(cwd);
+    if (g.base === null)
+        return { title: "", body: "" };
+    const ref = await baseRef(cwd, g.base);
+    const subjects = ((await tryRun(cwd, "git", ["log", "--format=%s", `${ref}..HEAD`])) ?? "").split("\n").filter((s) => s !== "").reverse();
+    if (subjects.length === 1)
+        return { title: subjects[0], body: "" };
+    return { title: (g.branch ?? "").replace(/^[^/]*\//, "").replace(/[-_]/g, " "), body: subjects.map((s) => `- ${s}`).join("\n") };
+}

package/dist/main/headless.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { kisoHome } from "@vincemakes/kiso-runtime";
+import { revokeSessions } from "./auth.js";
+import { startFromEnv } from "./env.js";
+/**
+ * `kiso-web [--port 4317] [--no-open] [--revoke-sessions]`: the host in this process, the page at http://127.0.0.1:<port>, and the
+ * default browser opened once on `#c=<one-time connect code>`. The port is fixed (a page added to the Dock keeps its address): if
+ * another kiso-web host holds it, the browser is opened on that host; anything else holding it is an error that names the process.
+ * The server runs while the command runs. Configuration beyond the flags: env.ts. It prints `READY {json}` once it listens (the proofs
+ * read it); with `--no-open` it also prints the address to open, whose code is good once, for two minutes.
+ */
+const DEFAULT_PORT = 4317;
+const USAGE = "usage: kiso-web [--port <n>] [--no-open] [--revoke-sessions]";
+const say = (line) => void process.stdout.write(`${line}\n`);
+const fail = (line) => {
+    process.stderr.write(`kiso-web: ${line}\n`);
+    process.exit(1);
+};
+function parseArgs(argv) {
+    let port = Number(process.env["KISO_WEB_PORT"] || DEFAULT_PORT);
+    let open = true;
+    let revoke = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--no-open")
+            open = false;
+        else if (arg === "--revoke-sessions")
+            revoke = true;
+        else if (arg === "--port" || arg.startsWith("--port="))
+            port = Number(arg.includes("=") ? arg.slice(7) : argv[++i]);
+        else if (arg === "--help" || arg === "-h")
+            (say(USAGE), process.exit(0));
+        else
+            fail(`unknown argument ${arg}\n${USAGE}`);
+    }
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+        fail(`--port must be a port number\n${USAGE}`);
+    return { port, open, revoke };
+}
+/** Where a running host leaves its scripts' token for another `kiso-web` on the same port (mode 0600, removed on exit). */
+const hostFile = (home, port) => join(home, `web-host-${port}.json`);
+/** Who answers on the port: a kiso-web host, something else, or nobody. */
+async function probe(port) {
+    try {
+        const r = await fetch(`http://127.0.0.1:${port}/auth/status`, { signal: AbortSignal.timeout(1_500) });
+        return (await r.json().catch(() => ({}))).app === "kiso-web" ? "kiso-web" : "other";
+    }
+    catch (error) {
+        const code = error.cause?.code;
+        return code === "ECONNREFUSED" ? "free" : "other";
+    }
+}
+/** The process listening on the port, in words, for the error. */
+function holder(port) {
+    try {
+        const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fpc"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const pid = /^p(\d+)$/m.exec(out)?.[1];
+        const command = /^c(.+)$/m.exec(out)?.[1];
+        if (pid !== undefined)
+            return `${command ?? "a process"} (pid ${pid})`;
+    }
+    catch {
+        // no lsof, or nothing found
+    }
+    return "another program";
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => say(`Open ${url} in your browser.`));
+    child.unref();
+}
+/** A connect address from the host already on the port, by the token it left; without one, the bare address (a browser signed in before still is). */
+async function addressFrom(home, port) {
+    const origin = `http://127.0.0.1:${port}`;
+    try {
+        const { token } = JSON.parse(readFileSync(hostFile(home, port), "utf8"));
+        const r = await fetch(`${origin}/auth/code`, { method: "POST", headers: { authorization: `Bearer ${token}` } });
+        if (r.ok)
+            return `${origin}/#c=${(await r.json()).code}`;
+    }
+    catch {
+        // fall through
+    }
+    return `${origin}/`;
+}
+async function main() {
+    const { port, open, revoke } = parseArgs(process.argv.slice(2));
+    const home = process.env["KISO_WEB_DATA"] ?? kisoHome();
+    if (revoke)
+        return say(`kiso-web: ${revokeSessions(home)} session(s) revoked; each browser signs in again from kiso web.`);
+    if (port !== 0) {
+        const found = await probe(port);
+        if (found === "kiso-web") {
+            const url = await addressFrom(home, port);
+            if (open)
+                openBrowser(url);
+            return say(`kiso web is already running at http://127.0.0.1:${port}${open ? "; opened it in your browser" : `; open ${url}`}.`);
+        }
+        if (found === "other")
+            fail(`port ${port} is held by ${holder(port)}. Stop it, or start kiso web on another port with --port.`);
+    }
+    const host = await startFromEnv({ port }).catch((error) => error.code === "EADDRINUSE" ? fail(`port ${port} is held by ${holder(port)}. Stop it, or start kiso web on another port with --port.`) : Promise.reject(error));
+    const record = hostFile(home, host.port);
+    writeFileSync(record, JSON.stringify({ pid: process.pid, token: host.token }), { mode: 0o600 });
+    chmodSync(record, 0o600);
+    const url = `${host.origin}/#c=${host.connectCode()}`;
+    process.stdout.write(`READY ${JSON.stringify({ origin: host.origin, port: host.port, pid: process.pid, openRuns: host.service.openRuns(), ...(open ? {} : { connect: url }) })}\n`);
+    say(`kiso web is running at ${host.origin} (Ctrl-C stops it).`);
+    if (open)
+        openBrowser(url);
+    else
+        say(`Open ${url} (the code in it works once, for two minutes).`);
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        rmSync(record, { force: true });
+        void host.close(5_000).then(() => process.exit(0));
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+}
+main().catch((err) => fail(err instanceof Error ? err.message : String(err)));

package/dist/main/history-worker.js

@@ -0,0 +1,18 @@
+import { parentPort } from "node:worker_threads";
+import { SessionStore } from "@vincemakes/kiso-runtime";
+/**
+ * Lists one session folder off the host's thread: `SessionStore.list()` reads
+ * every log whole to title it, and one folder of long sessions takes seconds.
+ * Message in: `{ dir }`. Message out: `{ dir, metas }` or `{ dir, error }`.
+ */
+parentPort.on("message", (message) => {
+    try {
+        const store = new SessionStore(message.dir);
+        const metas = store.list();
+        store.closeAll();
+        parentPort.postMessage({ dir: message.dir, metas });
+    }
+    catch (error) {
+        parentPort.postMessage({ dir: message.dir, error: error instanceof Error ? error.message : String(error) });
+    }
+});

package/dist/main/history.js

@@ -0,0 +1,151 @@
+import { readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { Worker } from "node:worker_threads";
+import { sessionFolders } from "@vincemakes/kiso-code/config";
+/**
+ * The history: every Work of every project folder under the kiso home, the
+ * terminal's own layout (`projects/<enc>/`). Reading a folder's titles is
+ * slow (see history-worker.ts), so it happens in a worker, one folder at a
+ * time, the folder in use first, and a folder is read again only when its
+ * files changed (count, bytes, newest write) and not more often than
+ * `MIN_AGE_MS`. A request answers from what is read so far and says it is
+ * still `scanning`.
+ */
+const MIN_AGE_MS = 3_000;
+const MAX_ROWS = 400;
+/** What the host knows about a Work it holds open: a run live, or waiting for an answer. */
+/** A delegated child's parent (the longest id of its folder that `sub-<id>-` starts with: a parent id may have any shape) and its
+ *  role (what follows the task's number; a role starts with a letter, a hex delegation id may be all digits); nothing for any
+ *  other session. */
+export function delegated(id, ids) {
+    if (!id.startsWith("sub-"))
+        return {};
+    const parent = ids.filter((p) => p !== id && id.startsWith(`sub-${p}-`)).sort((a, b) => b.length - a.length)[0];
+    const role = /-\d+-(\D.*)$/.exec(id.slice(4 + (parent?.length ?? 0)))?.[1];
+    return { ...(parent === undefined ? {} : { parent }), ...(role === undefined ? {} : { role }) };
+}
+/** The folder's files as one string: it changes when a log is added or written, or a Work's name file (`<id>.meta.json`, the
+ *  runtime's titles read it) is written by a rename. */
+function printOf(dir) {
+    let count = 0;
+    let bytes = 0;
+    let newest = 0;
+    for (const name of readdirSync(dir)) {
+        const meta = name.endsWith(".meta.json");
+        if (!name.endsWith(".jsonl") && !meta)
+            continue;
+        try {
+            const s = statSync(join(dir, name));
+            if (meta) {
+                newest = Math.max(newest, s.mtimeMs);
+                continue;
+            }
+            if (s.size === 0)
+                continue;
+            count += 1;
+            bytes += s.size;
+            newest = Math.max(newest, s.mtimeMs);
+        }
+        catch {
+            // gone between the listing and the stat
+        }
+    }
+    return `${count}:${bytes}:${newest}`;
+}
+export class History {
+    #home;
+    #live;
+    #marksOf;
+    #reads = new Map();
+    #queue = [];
+    #worker = null;
+    #inflight = null;
+    constructor(home, live, marksOf = () => ({})) {
+        this.#home = home;
+        this.#live = live;
+        this.#marksOf = marksOf;
+    }
+    /** `fresh` names a folder whose listing is read again now, whatever its age. */
+    async snapshot(current, fresh) {
+        const rows = [];
+        const now = Date.now();
+        for (const folder of sessionFolders(this.#home)) {
+            if (folder.kind !== "project" || folder.workspace === null)
+                continue;
+            let print;
+            try {
+                print = printOf(folder.dir);
+            }
+            catch {
+                continue;
+            }
+            const read = this.#reads.get(folder.dir);
+            const due = read === undefined || (read.print !== print && (now - read.at >= MIN_AGE_MS || fresh === basename(folder.dir)));
+            if (due)
+                this.#enqueue(folder.dir, folder.dir === current.dir);
+            if (read === undefined)
+                continue;
+            const key = basename(folder.dir);
+            const ids = read.metas.map((m) => m.id);
+            for (const meta of read.metas) {
+                rows.push({
+                    // a fork's parent: the store's own record (any app made it), else the host's (forks it made before)
+                    ...(meta.forkedFrom !== undefined ? { parent: meta.forkedFrom } : {}),
+                    ...this.#marksOf(meta.id),
+                    ...delegated(meta.id, ids),
+                    id: meta.id,
+                    key,
+                    folder: basename(folder.workspace),
+                    title: meta.title,
+                    createdAt: meta.createdAt,
+                    updatedAt: meta.updatedAt,
+                    events: meta.events,
+                    runs: meta.runs,
+                    state: "idle",
+                });
+            }
+        }
+        rows.sort((a, b) => b.updatedAt - a.updatedAt);
+        const works = await Promise.all(rows.slice(0, MAX_ROWS).map(async (row) => ({ ...row, state: await this.#live(row.key, row.id) })));
+        return { current: { key: current.key, folder: basename(current.dir) }, works, scanning: this.#inflight !== null || this.#queue.length > 0 };
+    }
+    #enqueue(dir, first) {
+        if (this.#inflight === dir || this.#queue.includes(dir))
+            return;
+        if (first)
+            this.#queue.unshift(dir);
+        else
+            this.#queue.push(dir);
+        this.#pump();
+    }
+    #pump() {
+        if (this.#inflight !== null)
+            return;
+        const dir = this.#queue.shift();
+        if (dir === undefined)
+            return;
+        this.#inflight = dir;
+        const print = printOf(dir);
+        const worker = (this.#worker ??= new Worker(new URL("./history-worker.js", import.meta.url)));
+        // both listeners go when either answers: one read, one pair (the worker lives across reads, so a kept listener piles up)
+        const done = (message) => {
+            worker.off("message", done);
+            worker.off("error", failed);
+            // an unreadable folder is remembered empty: it is tried again when its files change
+            this.#reads.set(dir, { print, metas: message.metas ?? [], at: Date.now() });
+            this.#inflight = null;
+            this.#pump();
+        };
+        const failed = (error) => {
+            this.#worker = null;
+            done({ dir, error: error.message });
+        };
+        worker.on("message", done);
+        worker.on("error", failed);
+        worker.postMessage({ dir });
+    }
+    close() {
+        void this.#worker?.terminate();
+        this.#worker = null;
+    }
+}