allaboard 0.0.0-stage → 0.4.0

package/dist/core/config.js

@@ -0,0 +1,174 @@
+/** Load the daemon's configuration from the `.env` of its instance's configuration folder. */
+import { lstatSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { parseEnv } from "node:util";
+import { strip } from "../text.js";
+import { errorCode } from "../values.js";
+import { SETUP_SECTIONS, setupGuide } from "../version.js";
+import { expandUser, resolvePath } from "./paths.js";
+/** The variables that select the agent and the chat; absent, the registry's defaults hold. */
+export const SELECTORS = ["ALLABOARD_AGENT", "ALLABOARD_CHAT"];
+const [AGENT_VARIABLE, CHAT_VARIABLE] = SELECTORS;
+/** The variables the core itself requires; each module names its own. */
+export const REQUIRED = ["ALLOWED_ROOT"];
+/** The configuration is missing, unsafe or invalid; the message says what to fix. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+// python-dotenv's own pattern (`dotenv/variables.py`, 1.2.4): `${NAME}` and `${NAME:-default}`.
+// `$NAME` without braces, a lone `$` and `${NAME:other}` stay as they are.
+const VARIABLE = /\$\{([^}:]*)(?::-([^}]*))?\}/g;
+/**
+ * The key names of `text` in the order the file defines them. `util.parseEnv` returns its keys
+ * sorted, which loses the order python-dotenv resolves in: a name defined later in the file does
+ * not exist yet for the values before it. A key `parseEnv` read that no line start names (should
+ * a syntax differ) goes last, so no key is dropped.
+ */
+function fileOrder(text, keys) {
+    const wanted = new Set(keys);
+    const ordered = new Set();
+    for (const [, key] of text.matchAll(/^[ \t]*(?:export[ \t]+)?([^\s=#]+)[ \t]*=/gm)) {
+        if (key !== undefined && wanted.has(key))
+            ordered.add(key);
+    }
+    return [...ordered, ...keys.filter((key) => !ordered.has(key))];
+}
+/**
+ * The values of a `.env` text with `${NAME}` and `${NAME:-default}` expanded as python-dotenv does
+ * by default (`interpolate=True`), which is how the Python daemon read this file. A name
+ * resolves from the values the file defined above it, else from `env`, else to its default, else
+ * to nothing; an `env` entry that is empty counts as set. The expanded value is final: nothing in
+ * it is expanded again. Quotes were dropped by `parseEnv` and python-dotenv expands inside single
+ * quotes too, so every value is expanded alike. Differences from python-dotenv: a key repeated in
+ * the file (the last value is used and expanded once, where python-dotenv expands each
+ * occurrence) and a bare `NAME` line with no `=` (python-dotenv records it as unset and
+ * `${NAME:-d}` then gives nothing; here `d`).
+ *
+ * The syntax is Node's. Of 24 cases run through `util.parseEnv` of Node 26.5.1 and python-dotenv
+ * 1.2.1 (2026-10-11), 7 read differently: a `#` right after an unquoted
+ * value starts a comment (`C=a#b` is `a`; python-dotenv keeps `a#b`), and `A= # note` is empty
+ * (python-dotenv: `# note`); inside quotes a backslash is kept as written, `\n` in double quotes
+ * aside, so `\t` and `\\` stay two characters and a `\"` ends the value at that quote
+ * (python-dotenv decodes them); and three shapes python-dotenv skips as malformed are read: a
+ * name with a space (`KEY WITH SPACE=1`), text after a closing quote (`B="p"q` is `p`) and an
+ * unclosed quote (the value keeps the quote).
+ */
+export function expandEnv(text, env = process.env) {
+    const raw = new Map(Object.entries(parseEnv(text)));
+    const resolved = new Map();
+    for (const key of fileOrder(text, [...raw.keys()])) {
+        const value = raw.get(key);
+        if (value === undefined)
+            continue;
+        resolved.set(key, value.replace(VARIABLE, (_match, name, fallback) => {
+            const defined = resolved.get(name);
+            if (defined !== undefined)
+                return defined;
+            const inherited = Object.hasOwn(env, name) ? env[name] : undefined;
+            return inherited ?? fallback ?? "";
+        }));
+    }
+    return Object.fromEntries(resolved);
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return false;
+        throw error;
+    }
+}
+/** The values of `names` that `values` holds, readable by lookup and shown by nothing. */
+function hiddenVariables(names, values) {
+    const hidden = Object.create(null);
+    for (const name of names) {
+        const value = values[name];
+        if (Object.hasOwn(values, name) && value !== undefined) {
+            Object.defineProperty(hidden, name, { value, enumerable: false });
+        }
+    }
+    return hidden;
+}
+/** The module `variable` selects (its default when the file does not set it), or a `ConfigError`. */
+function selected(variable, chosen, fallback, held) {
+    const name = chosen ?? fallback;
+    const module = Object.hasOwn(held, name) ? held[name] : undefined;
+    if (module === undefined) {
+        throw new ConfigError(`${variable} is "${name}", which this daemon does not hold; the valid names are: ` +
+            Object.keys(held).sort().join(", "));
+    }
+    return [name, module];
+}
+/**
+ * Read and validate `.env` for the modules it selects; throws ConfigError, never touches
+ * `process.env`. The values a module's own checks refuse (the shape of a token) are its to
+ * judge when it is built.
+ */
+export function loadConfig(modules, configDir, env = process.env) {
+    const envPath = join(configDir, ".env");
+    let st;
+    try {
+        st = lstatSync(envPath);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            throw new ConfigError(`${envPath} does not exist; see ${setupGuide(SETUP_SECTIONS.configuration)}`);
+        }
+        throw error;
+    }
+    if (!st.isFile()) {
+        throw new ConfigError(`${envPath} must be a regular file, not a link`);
+    }
+    // Ownership and mode are POSIX facts; the daemon is not supported on Windows yet.
+    if (process.platform !== "win32") {
+        if (st.uid !== process.getuid?.()) {
+            throw new ConfigError(`${envPath} must belong to the user running allaboard`);
+        }
+        // The tokens drive a shell on this machine: nobody but the owner may read them.
+        if (st.mode & 0o077) {
+            throw new ConfigError(`${envPath} is readable by others; run: chmod 600 ${envPath}`);
+        }
+    }
+    const values = {};
+    // A byte order mark would become part of the first variable's name.
+    const text = readFileSync(envPath, "utf8").replace(/^\ufeff/, "");
+    for (const [key, raw] of Object.entries(expandEnv(text, env))) {
+        const value = raw === undefined ? "" : strip(raw);
+        if (value)
+            values[key] = value;
+    }
+    const [agent, agentModule] = selected(AGENT_VARIABLE, values[AGENT_VARIABLE], modules.defaults.agent, modules.agents);
+    const [chat, chatModule] = selected(CHAT_VARIABLE, values[CHAT_VARIABLE], modules.defaults.chat, modules.chats);
+    // The chat's, then the agent's, then the core's own.
+    const missing = [...chatModule.required, ...agentModule.required, ...REQUIRED].filter((key) => !Object.hasOwn(values, key));
+    if (missing.length > 0) {
+        throw new ConfigError(`missing in ${envPath}: ${missing.join(", ")}`);
+    }
+    const written = values.ALLOWED_ROOT;
+    const expanded = expandUser(written);
+    // A relative path would read from the working directory: the terminal's folder at Checkpoint 2,
+    // `/` under launchd.
+    if (!isAbsolute(expanded)) {
+        throw new ConfigError(`ALLOWED_ROOT must be an absolute path, or one starting with ~/; it is "${written}"`);
+    }
+    const root = resolvePath(expanded);
+    if (!isDirectory(root)) {
+        throw new ConfigError(`ALLOWED_ROOT is not a directory: ${root}`);
+    }
+    return Object.defineProperties({ agent, chat, allowedRoot: root, configDir }, {
+        agentVariables: {
+            value: hiddenVariables([...agentModule.required, ...agentModule.optional], values),
+            enumerable: false,
+        },
+        chatVariables: {
+            value: hiddenVariables([...chatModule.required, ...chatModule.optional], values),
+            enumerable: false,
+        },
+    });
+}

package/dist/core/files/changed.js

@@ -0,0 +1,125 @@
+/**
+ * The changed files of a session: those added or modified since the thread started, committed or
+ * not, and the untracked ones that are not ignored. The measurements behind the git commands are
+ * in the `listing.ts` header.
+ */
+import { monotonicClock } from "../../clock.js";
+import { len, strip } from "../../text.js";
+import { GIT_TIMEOUT, runGit } from "../footer.js";
+import { Semaphore } from "../sessions/tasks.js";
+import { GIT_CHAINS, relation, scoped, under } from "./listing.js";
+import { TIMED_OUT, within } from "./waiting.js";
+const DECIMAL = /^\p{Nd}+$/u;
+/**
+ * Where the repository's HEAD was when the thread started, which `startedAt` (seconds since the
+ * epoch) says: `HEAD@{<seconds> +0000}`, read from HEAD's own reflog (a linked worktree has its
+ * own). A commit, or the empty tree when the repository was made after the thread began (below),
+ * so that every file counts. Null when git has no answer: no reflog (a repository with
+ * `core.logAllRefUpdates` off, or a first commit not made yet), or a `startedAt` that is no time.
+ *
+ * Measured on git 2.54.0 (2026-10-05, 2026-10-06). The bare number is read as a time
+ * (`HEAD@{1790000150}`) and so is the internal format with its zone, which is the one used: it
+ * leaves no room for git's approximate dates. A time before the oldest entry gives that entry's
+ * old commit (a log that `git reflog expire` shortened) or, when its old value is null, its new
+ * one: the first commit, or a clone's tip, which would leave that commit's own files out of what
+ * changed. The two are told apart by commands that read the log and write nothing:
+ *
+ * - `rev-list -g --until=<seconds> +0000 --count HEAD` is 0 when every entry is after the thread's
+ *   start (it counts the entries up to that time, as `HEAD@{<time>}` does);
+ * - `rev-list -g --count HEAD` is the number of entries, N, and `rev-parse --verify --quiet
+ *   HEAD@{N}` is the oldest entry's old value, which fails when it is null (the repository was
+ *   made, or cloned, since); a shortened log answers;
+ * - `hash-object -t tree /dev/null` is the empty tree of the repository's hash algorithm.
+ *
+ * A log that git cannot be asked this about keeps the answer `HEAD@{<time>}` gave.
+ */
+export async function startCommit(repository, startedAt, signal) {
+    if (!Number.isSafeInteger(startedAt) || startedAt < 0)
+        return null;
+    const when = `${startedAt} +0000`;
+    const found = await runGit(repository, ["rev-parse", "--verify", "--quiet", `HEAD@{${when}}`], signal);
+    const start = strip(found ?? "") || null;
+    if (start === null)
+        return null;
+    const until = await runGit(repository, ["rev-list", "-g", `--until=${when}`, "--count", "HEAD"], signal);
+    if (until === null || strip(until) !== "0")
+        return start;
+    const entries = await runGit(repository, ["rev-list", "-g", "--count", "HEAD"], signal);
+    if (entries === null || !DECIMAL.test(strip(entries)))
+        return start;
+    const oldest = await runGit(repository, ["rev-parse", "--verify", "--quiet", `HEAD@{${strip(entries)}}`], signal);
+    if (oldest)
+        return start;
+    const emptied = await runGit(repository, ["hash-object", "-t", "tree", "/dev/null"], signal);
+    return strip(emptied ?? "") || start;
+}
+/**
+ * The files in the part of the repository that is `folder` or inside it, added or modified since
+ * `start`, committed or not, and the untracked ones that are not ignored, as paths from `folder`.
+ * Not checked for existence: a deleted file may be named (`newestFirst` drops it). With no `start`,
+ * only what is not committed. Null when git fails.
+ */
+export async function changedSince(repository, folder, start, signal) {
+    const found = await relation(repository, folder);
+    if (found === null)
+        return null;
+    const [stripped, add] = found;
+    const scope = scoped(stripped);
+    const status = await runGit(repository, [
+        "--literal-pathspecs",
+        "--no-optional-locks",
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+        "--ignore-submodules=all",
+        "--no-renames",
+        ...scope,
+    ], signal);
+    if (status === null)
+        return null;
+    // `XY path`: two status letters and a space come before the path.
+    const names = status
+        .split("\0")
+        .filter((entry) => len(entry) > 3)
+        .map((entry) => entry.slice(3));
+    if (start !== null) {
+        const committed = await runGit(repository, [
+            "--literal-pathspecs",
+            "diff-tree",
+            "-r",
+            "-z",
+            "--name-only",
+            "--no-renames",
+            "--diff-filter=AMT",
+            start,
+            "HEAD",
+            ...scope,
+        ], signal);
+        // A start that no longer resolves (rewritten history): the uncommitted files alone.
+        names.push(...(committed ?? "").split("\0"));
+    }
+    return under(names.join("\0"), stripped, add);
+}
+/**
+ * The changed files of every repository of `repositories` (see `changedSince`), each from where
+ * its own HEAD was when the thread started, at `startedAt` seconds since the epoch
+ * (`startCommit`; null when the chat cannot tell, which counts from no start), as paths from `folder`,
+ * each once. A repository whose git fails or runs over `GIT_TIMEOUT` adds none.
+ */
+export async function changedIn(folder, repositories, startedAt, options = {}) {
+    const clock = options.clock ?? monotonicClock;
+    const start = options.start ?? startCommit;
+    const since = options.since ?? changedSince;
+    const gate = new Semaphore(options.chains ?? GIT_CHAINS);
+    // The turn is waited for outside the time limit: that is git's own.
+    const changed = (repository) => gate.run(async () => {
+        const found = await within(clock, GIT_TIMEOUT / 1000, async (signal) => {
+            const from = startedAt === null ? null : await start(repository, startedAt, signal);
+            return (await since(repository, folder, from, signal)) ?? [];
+        });
+        return found === TIMED_OUT ? [] : found;
+    });
+    const parts = await Promise.all(repositories.map(changed));
+    return [...new Set(parts.flat())];
+}

package/dist/core/files/listing.js

@@ -0,0 +1,382 @@
+/**
+ * Which files the search offers. Inside a repository the daemon's git may run in
+ * (`trustedRepository`: the one holding the session's folder, or the ones found at most two levels
+ * below it) the files come from git, through the footer's `runGit`: the tracked ones and the
+ * untracked ones that are not ignored. That is what the terminal's `@` file picker does, since its
+ * setting `respectGitignore` defaults to `true` and leaves out the files that match `.gitignore`
+ * patterns (code.claude.com/docs/en/settings-reference, read 2026-10-05). Everywhere else the
+ * folder is walked: regular files only, no symlinked folder entered, no `.git` entered.
+ *
+ * Every git command of `!open` (here and in `changed.ts`) is plumbing or `status` under
+ * `--no-optional-locks`, because `git diff` refreshes and rewrites the index under `index.lock`
+ * (see `changesOf` in the footer), and a lock left by a killed command would stop the owner's own
+ * `git add` and commit. Measured on git 2.54.0 (2026-10-05, and 2026-10-06 for the reflog
+ * commands) on a scratch repository, with the index's inode, mtime and sha256 compared before and
+ * after, in four states of the work tree (clean; a tracked file touched and left unchanged, which
+ * is a stat-dirty file; a tracked file edited; an untracked file):
+ *
+ * - never written, in any state: `rev-parse --verify HEAD@{<time>}` and `HEAD@{<n>}`, `rev-list
+ *   -g --count` (also with `--until`), `hash-object -t tree /dev/null`, `ls-files --cached
+ *   --others --exclude-standard`, `diff-tree -r`, `diff-files`, `diff-index` and
+ *   `--no-optional-locks status`;
+ * - written for the stat-dirty file: `status` without `--no-optional-locks`, `diff --name-only`
+ *   and `--no-optional-locks diff --name-only`;
+ * - reported as changed when only touched: `diff-files` and `diff-index` (the footer's commands);
+ *   not reported: `status`, which compares the content of a file whose stat differs.
+ *
+ * So the committed changes come from `diff-tree` and the rest from `status`, which also lists the
+ * untracked files. `test/core/files/changed.test.ts` repeats the measurement on every run.
+ */
+import { lstat, readdir } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { monotonicClock } from "../../clock.js";
+import { getLogger } from "../../log.js";
+import { compareCodePoints, len } from "../../text.js";
+import { errorName } from "../../values.js";
+import { foldersWithin } from "../folders.js";
+import { runGit } from "../footer.js";
+import { cancellable, Semaphore } from "../sessions/tasks.js";
+import { relativeTo } from "./paths.js";
+import { realpathLoose, regularFiles } from "./read.js";
+import { TIMED_OUT, within } from "./waiting.js";
+export const logger = getLogger("allaboard.core.files");
+// A folder's listing is kept for LISTING_TTL (LISTING_PARTIAL_TTL when it is not complete), so
+// the keystrokes of one search do not walk the folder again, and a listing stops at
+// LISTING_BUDGET with what it found; LISTING_KEPT folders are kept at most. All in seconds.
+export const LISTING_BUDGET = 2.0;
+export const LISTING_TTL = 30.0;
+export const LISTING_PARTIAL_TTL = 3.0;
+export const LISTING_KEPT = 16;
+// The repositories found in a folder are kept for a shorter time than its files: one the owner
+// trusts while the session runs should show within moments. At most GIT_CHAINS
+// repositories are asked at once, the rest wait their turn.
+export const REPOSITORIES_TTL = 5.0;
+export const GIT_CHAINS = 4;
+/** `repository` when it has a work tree git can list, else null. */
+export function usable(repository) {
+    if (repository === null || repository.gitDir === null || repository.insideGitDir)
+        return null;
+    return repository;
+}
+/**
+ * How the folder and the repository's root meet, as `[strip, add]`: git's paths are relative to
+ * the root, and a path from the folder is that path less `strip` and with `add` before it. A
+ * folder inside the repository strips its own path from the root (`""` at the root itself), a
+ * repository inside the folder adds its own path from the folder, and any other pair is null.
+ */
+export async function relation(repository, folder) {
+    const real = await realpathLoose(folder);
+    const inside = relativeTo(repository.root, real);
+    if (inside !== null)
+        return [inside.split(sep).join("/"), ""];
+    const held = relativeTo(real, repository.root);
+    if (held !== null)
+        return ["", `${held.split(sep).join("/")}/`];
+    return null;
+}
+/**
+ * The paths of a NUL-separated git output that lie under `strip`, as paths from the folder, each
+ * once.
+ */
+export function under(output, strip, add) {
+    const start = strip ? `${strip}/` : "";
+    const names = output
+        .split("\0")
+        .filter((name) => name.startsWith(start))
+        .map((name) => name.slice(start.length));
+    return [...new Set(names.filter((name) => name).map((name) => `${add}${name}`))];
+}
+export function scoped(strip) {
+    return strip ? ["--", strip] : [];
+}
+/** The folders under `folder`, as `!bind` lists them, that hold a `.git` entry. */
+async function repositoryFolders(folder) {
+    let below;
+    try {
+        below = await foldersWithin(folder);
+    }
+    catch (error) {
+        // A system error has a code.
+        if (typeof error?.code === "string")
+            return [];
+        throw error;
+    }
+    const holding = await Promise.all(below.map((path) => path === folder
+        ? false
+        : lstat(join(path, ".git")).then(() => true, () => false)));
+    return below.filter((_path, index) => holding[index]);
+}
+/**
+ * The repositories the daemon's git may run in for a session started in `folder`: the one holding
+ * the folder when `lookup` finds it usable, else the usable ones found at most two levels below
+ * it (the depth `!bind` lists folders to), none of them inside another.
+ */
+export async function repositoriesOf(folder, lookup) {
+    const held = usable(await lookup(folder));
+    if (held !== null)
+        return [held];
+    const below = await repositoryFolders(folder);
+    const looked = await Promise.all(below.map((candidate) => lookup(candidate)));
+    const found = new Map();
+    for (const repository of looked.map(usable)) {
+        if (repository !== null)
+            found.set(repository.root, repository);
+    }
+    return [...found.values()];
+}
+/**
+ * The regular files under `root` as paths from it, the shallower first: a symlink is neither
+ * followed nor listed, no `.git` is entered, nor any folder in `skip` (paths). Stops when
+ * `expired()` is true, with what it has found; the flag says the walk reached its end.
+ */
+export async function walkFiles(root, skip, expired) {
+    const found = [];
+    const queue = [[root, ""]];
+    let next = 0;
+    while (next < queue.length && !expired()) {
+        const [directory, prefix] = queue[next];
+        next += 1;
+        try {
+            for (const entry of await readdir(directory, { withFileTypes: true })) {
+                if (entry.name === ".git")
+                    continue;
+                const path = join(directory, entry.name);
+                // `Dirent` describes the entry itself: a symlink is neither a directory nor a file.
+                if (entry.isDirectory()) {
+                    if (!skip.has(path))
+                        queue.push([path, `${prefix}${entry.name}/`]);
+                }
+                else if (entry.isFile()) {
+                    found.push(`${prefix}${entry.name}`);
+                }
+            }
+        }
+        catch (error) {
+            // A folder the daemon may not open (macOS privacy, permissions) lists nothing.
+            logger.debug(`skipped an unreadable folder: ${error.code}`);
+        }
+    }
+    return [found, next >= queue.length];
+}
+/**
+ * The tracked files and the untracked ones that are not ignored, in the part of the repository
+ * that is `folder` or inside it, as paths from `folder`; null when git fails. Not checked for
+ * existence: a tracked file deleted from the work tree is listed (`regularFiles` drops it).
+ */
+export async function projectFiles(repository, folder, signal) {
+    const found = await relation(repository, folder);
+    if (found === null)
+        return null;
+    const [strip, add] = found;
+    const out = await runGit(repository, [
+        // Literal: the folder's name is not a glob.
+        "--literal-pathspecs",
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        ...scoped(strip),
+    ], signal);
+    return out === null ? null : under(out, strip, add);
+}
+/**
+ * The files `!open` can name under `folder`, as paths from it: from git inside a repository of
+ * `repositories`, the folder's own disk anywhere else. Within `budget` seconds: what is found by
+ * then is returned, a repository whose listing is not done adding nothing. The flag says nothing
+ * was left out: no walk or git listing ran out of time or failed.
+ */
+export async function folderFiles(folder, repositories, budget, options = {}) {
+    const clock = options.clock ?? monotonicClock;
+    const list = options.list ?? projectFiles;
+    const deadline = clock.time() + budget;
+    const real = await realpathLoose(folder);
+    const gate = new Semaphore(options.chains ?? GIT_CHAINS);
+    const listed = async (repository) => {
+        // Waiting for a turn is part of the budget: it is the listing's own.
+        const found = await within(clock, budget, (signal) => gate.run(() => list(repository, folder, signal), signal));
+        if (found === TIMED_OUT)
+            return [[], false];
+        return [found ?? [], found !== null];
+    };
+    let walked = [];
+    let walkDone = true;
+    let parts;
+    if (repositories.some((r) => relativeTo(r.root, real) !== null)) {
+        // Every file of the folder is in the repository that holds it.
+        parts = await Promise.all(repositories.map(listed));
+    }
+    else {
+        const skip = new Set(repositories.map((r) => r.root));
+        const [walk, ...listings] = await Promise.all([
+            walkFiles(real, skip, () => clock.time() >= deadline),
+            ...repositories.map(listed),
+        ]);
+        [walked, walkDone] = walk;
+        parts = listings;
+    }
+    const files = [...new Set([...walked, ...parts.flatMap(([found]) => found)])];
+    return [files, walkDone && parts.every(([, done]) => done)];
+}
+/**
+ * What is made for a folder, kept for as long as its maker says, at most `limit` folders (the
+ * oldest go first) with the expired ones removed on the next request. Requests for a folder whose
+ * value is being made wait for that one.
+ */
+class Kept {
+    #limit;
+    #clock;
+    #kept = new Map();
+    #running = new Map();
+    constructor(limit, clock) {
+        this.#limit = limit;
+        this.#clock = clock;
+    }
+    /** The folders whose value is kept. */
+    folders() {
+        return [...this.#kept.keys()];
+    }
+    /**
+     * The value, and whether it was made for this request (not kept). `make` answers the value and
+     * how long to keep it, null for not at all. `again` skips what is kept. A request whose `signal`
+     * aborts stops waiting; the work goes on for the others.
+     */
+    async get(folder, make, options = {}) {
+        const now = this.#clock.time();
+        for (const [path, entry] of [...this.#kept]) {
+            if (entry.until <= now)
+                this.#kept.delete(path);
+        }
+        const kept = options.again ? undefined : this.#kept.get(folder);
+        if (kept !== undefined)
+            return [kept.value, false];
+        let task = this.#running.get(folder);
+        if (task === undefined) {
+            const started = this.#make(folder, make);
+            task = started;
+            this.#running.set(folder, started);
+            const done = () => {
+                if (this.#running.get(folder) === started)
+                    this.#running.delete(folder);
+            };
+            started.then(done, done);
+        }
+        return [await cancellable(task, options.signal), true];
+    }
+    async #make(folder, make) {
+        const started = this.#clock.time();
+        const [value, keep] = await make();
+        if (keep !== null) {
+            this.#kept.delete(folder);
+            this.#kept.set(folder, { until: started + keep, value });
+            while (this.#kept.size > this.#limit) {
+                this.#kept.delete(this.#kept.keys().next().value);
+            }
+        }
+        return value;
+    }
+}
+/** The paths that contain `words`, ignoring case: those whose file name does first, then the shorter paths, then by path. */
+export function rank(paths, words) {
+    const wanted = words.toLowerCase();
+    const found = [...paths].filter((path) => path.toLowerCase().includes(wanted));
+    const named = (path) => path
+        .slice(path.lastIndexOf("/") + 1)
+        .toLowerCase()
+        .includes(wanted);
+    return found.toSorted((left, right) => Number(!named(left)) - Number(!named(right)) ||
+        len(left) - len(right) ||
+        compareCodePoints(left, right));
+}
+/**
+ * The files of a session's folder for the search, and the repositories found in it, kept in
+ * memory: the chat asks again on every keystroke, and a folder is not walked each time. A listing is
+ * kept `ttl` seconds when it is complete and `partialTtl` when it ran out of time or git failed
+ * for part of it, so a folder too large for the budget is not walked on each keystroke but is not
+ * taken for complete either. The repositories are kept `repositoriesTtl` seconds. At most `limit`
+ * folders of each are kept (the oldest go first), and the expired ones are removed on the next
+ * request. Requests for a folder that is being listed wait for that listing. A kept listing is
+ * never the reason for "no match": `search` makes it again first.
+ */
+export class Listings {
+    #lookup;
+    #ttl;
+    #partialTtl;
+    #repositoriesTtl;
+    #budget;
+    #clock;
+    #regular;
+    #listed;
+    #found;
+    constructor(lookup, options = {}) {
+        const limit = options.limit ?? LISTING_KEPT;
+        this.#lookup = lookup;
+        this.#ttl = options.ttl ?? LISTING_TTL;
+        this.#partialTtl = options.partialTtl ?? LISTING_PARTIAL_TTL;
+        this.#repositoriesTtl = options.repositoriesTtl ?? REPOSITORIES_TTL;
+        this.#budget = options.budget ?? LISTING_BUDGET;
+        this.#clock = options.clock ?? monotonicClock;
+        this.#regular = options.regular ?? regularFiles;
+        this.#listed = new Kept(limit, this.#clock);
+        this.#found = new Kept(limit, this.#clock);
+    }
+    /** The folders whose listing is kept. */
+    keptListings() {
+        return this.#listed.folders();
+    }
+    /**
+     * The repositories the daemon's git may run in for a session started in `folder`
+     * (`repositoriesOf`). Rejects with what the lookup rejects with.
+     */
+    async repositories(folder, options = {}) {
+        const find = async () => [
+            await repositoriesOf(folder, this.#lookup),
+            this.#repositoriesTtl,
+        ];
+        return (await this.#found.get(folder, find, options))[0];
+    }
+    /**
+     * The folder's files as paths from it. Never rejects but for the signal: a listing that fails
+     * is empty, incomplete and not kept. `again` makes it anew whatever is kept.
+     */
+    async of(folder, options = {}) {
+        const [listing, fresh] = await this.#listed.get(folder, () => this.#list(folder, options.again ?? false), options);
+        return fresh ? listing : { ...listing, fresh: false };
+    }
+    async #list(folder, again) {
+        try {
+            const repositories = await this.repositories(folder, { again });
+            const [files, complete] = await folderFiles(folder, repositories, this.#budget, {
+                clock: this.#clock,
+            });
+            return [{ files, complete, fresh: true }, complete ? this.#ttl : this.#partialTtl];
+        }
+        catch (error) {
+            // A search that finds nothing beats a modal that never loads.
+            logger.warning(`could not list a folder's files: ${errorName(error)}`);
+            return [{ files: [], complete: false, fresh: true }, null];
+        }
+    }
+    /**
+     * The files of the folder whose path contains `words`, in `rank`'s order, that exist
+     * (`regularFiles`), at most `limit` of them checked. Past the limit `count` is the number of
+     * matches by name. When a kept listing finds none, the folder is listed again and searched
+     * anew: a file made since the listing is not told to be missing.
+     */
+    async search(folder, words, options = {}) {
+        const { limit, signal } = options;
+        const listing = await this.of(folder, { signal });
+        let found = await this.#matching(folder, listing, words, limit);
+        if (found.paths.length === 0 && !listing.fresh) {
+            const again = await this.of(folder, { again: true, signal });
+            found = await this.#matching(folder, again, words, limit);
+        }
+        return found;
+    }
+    async #matching(folder, listing, words, limit) {
+        const ranked = rank(listing.files, words);
+        const paths = await this.#regular(folder, ranked, limit);
+        const count = limit !== undefined && paths.length >= limit ? ranked.length : paths.length;
+        return { paths, count, complete: listing.complete };
+    }
+}