@needmoretruth/nmts-cli 0.17.2

package/dist/commands/login.js

@@ -0,0 +1,335 @@
+// `nmts login` — keep an account code on this machine, in one of three shapes.
+//
+// ⚠ IT DOES NOT CHECK THE CODE WITH THE SERVER, AND IT SAYS SO. The code never goes to the server
+//    at all — it is what opens the files, and nothing on the far end has ever seen it — so there
+//    is nobody to ask whether it is the right one. Its own check symbol is verified here, offline,
+//    and that is the whole of what can be known: a code for an account that does not exist is
+//    stored and looks fine until a command needs the server.
+//
+// ⛔ THE API KEY IS THE OTHER HALF OF SETTING THIS TOOL UP, AND IT IS CHECKED. It is a credential
+//    the SERVER issued, so the server can be asked about it — and it is, before it is written
+//    down, against the one route a key reaches without holding any permission. Until this command
+//    took one, a key could only arrive in an environment variable that vanishes with the terminal
+//    or by somebody editing the credentials file by hand. Where a key comes from and what is done
+//    to it lives in `api-key.ts`; what a person is told about it lives here.
+//
+// ⛔⭐ THE DEFAULT IS SEALED (owner, 2026-08-23: *support storing it, but by default only with
+//    encryption or the like; if they agree to a disclaimer and unlock it, allow plain storage
+//    too*). So there are three shapes and the person picks, rather than the tool deciding for
+//    them and being wrong on somebody's laptop:
+//
+//      nmts login            sealed under a passphrase.  Asks nothing.
+//      nmts login --plain    in the clear at mode 600.   Asks once: `unsafe-code-storage`.
+//      nmts login --env      stores nothing; prints the variable to set. Asks once: `plain-env`.
+//
+// ⚠ AND WHAT A PERSON DOES OUTSIDE THIS TOOL IS THEIRS. Writing the code into a note, a password
+//   manager or a repository is not something this can see, and it is not something it should try
+//   to stop. What it can do is make the shape it writes ITSELF a decision.
+import { assertUsableCode } from "../account.js";
+import { keySourceName, keyToStore, settleApiKey } from "../api-key.js";
+import { lockCode, samePassphrase } from "../code-vault.js";
+import { API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, CODE_ENV_VAR, CODE_FILE_ENV_VAR, PASSPHRASE_ENV_VAR, codeStorageIsPrivate, credentialsPath, modesAreEnforced, readCredentialsFile, readSecretFile, writeCredentials, } from "../credentials.js";
+import { requireConsent } from "../consent.js";
+import { NmtsError } from "../errors.js";
+import { firstRunNotice } from "../notice.js";
+import { holdTerminal, promptSecret, stdinIsATerminal } from "../prompt.js";
+import { askAboutCollisions } from "../setup-questions.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { resolveNetwork } from "../network.js";
+import { resolveServer } from "../server.js";
+/**
+ * ⚠ EIGHT, AND NO COMPOSITION RULES. scrypt makes a short passphrase expensive to attack, not
+ *   safe: four characters is guessed whatever the cost factor. Requiring a digit and a capital
+ *   would not change that and would push people to reuse the one they always type.
+ */
+const MIN_PASSPHRASE = 8;
+export async function login(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const server = resolveServer(options.server);
+    // ⛔ Settled BEFORE the notice and before anything is written: if the network cannot be decided,
+    //    nothing about this account should be stored at all.
+    const network = resolveNetwork(server, options.network);
+    const existing = readCredentialsFile();
+    if (options.plain === true && options.env === true) {
+        throw new NmtsError("--plain and --env ask for two different things.", {
+            exitCode: 2,
+            nextStep: "--plain writes the code to this machine; --env writes nothing and prints it.",
+        });
+    }
+    if (existing === null)
+        say(firstRunNotice());
+    // ⛔ ONE HOLD OVER EVERY QUESTION THIS COMMAND ASKS. Between two prompts the terminal is back in
+    //    line mode, where it echoes what is typed and swallows lines the next prompt never sees —
+    //    and this command asks up to three things with a check in the middle.
+    const exit = await holdTerminal(async () => {
+        const code = await readTheCode(options);
+        // ⛔ CHECKED BEFORE IT IS WRITTEN. The engine verifies the code's own check symbol offline, so
+        //    a mistyped code fails here as "that is not a code" instead of being stored and coming
+        //    back later as a sign-in failure indistinguishable from a wrong password or a suspended
+        //    account.
+        await assertUsableCode(code);
+        if (options.env === true)
+            return printEnvForm(code, say);
+        // ⛔ THE KEY IS SETTLED BEFORE THE PASSPHRASE IS ASKED FOR, for the reason the code is checked
+        //    before it: everything that can refuse this run should refuse it before somebody has typed
+        //    a passphrase twice. It comes after the `--env` branch because that branch writes nothing
+        //    at all — there is nowhere for a key to go, and asking for one would be a question whose
+        //    answer this command would then throw away.
+        const key = await settleApiKey({
+            server,
+            stored: existing?.apiKey,
+            readKey: options.readApiKey,
+            confirmReplace: options.confirmKeyReplace,
+        });
+        const apiKey = keyToStore(key);
+        const exit = options.plain === true
+            ? storePlain(code, server, network, apiKey, say)
+            : await storeSealed(code, server, network, apiKey, options, say);
+        sayCheckSymbol(say, key.kind === "stored");
+        sayAboutTheKey(key, server, say);
+        return exit;
+    });
+    // ⛔ AFTER THE HOLD, AND ONLY WHEN THE SIGN-IN WORKED. Inside the hold the terminal is in raw
+    //    mode and a line prompt never sees a line; before the end, this would be a question about a
+    //    setup that then failed. Why it is asked at all is in `setup-questions.ts`.
+    if (exit === 0)
+        await askAboutCollisions(say);
+    return exit;
+}
+/**
+ * Where `login` gets the code to store.
+ *
+ * ⛔⭐ THE ENVIRONMENT PATH ASKS HERE TOO, AND AN ADVERSARIAL REVIEW IS WHY. This function used to
+ *    read `NMTS_ACCOUNT_CODE` directly, so `login` was the one command that used a plain
+ *    environment variable without the agreement every other command demands — and the code it
+ *    took that way came back out as a sealed store, which needs no agreement at all. Two commands
+ *    and the recorded decision was gone, while the documentation said it could not be.
+ *
+ * ⚠ ORDER: a file first, because that is the shape this tool recommends and it asks for nothing;
+ *   then the environment, which asks once; then the terminal.
+ */
+async function readTheCode(options) {
+    const fromFile = readSecretFile(CODE_FILE_ENV_VAR);
+    const fromEnv = process.env[CODE_ENV_VAR];
+    if (options.readCode === undefined && fromFile === null && fromEnv !== undefined && fromEnv.length > 0) {
+        requireConsent("plain-env");
+    }
+    const code = options.readCode !== undefined
+        ? await options.readCode()
+        : fromFile !== null
+            ? fromFile
+            : fromEnv !== undefined && fromEnv.length > 0
+                ? fromEnv
+                : await promptSecret(`Account code (not shown as you type): `, CODE_ENV_VAR);
+    if (code.length === 0) {
+        throw new NmtsError("No account code was given.", {
+            exitCode: 2,
+            nextStep: stdinIsATerminal()
+                ? `Run \`${BINARY_NAME} login\` again and paste the code.`
+                : `Set ${CODE_ENV_VAR} in the environment.`,
+        });
+    }
+    return code;
+}
+/** Seal it. The default, and the only shape that survives the file being copied off the machine. */
+async function storeSealed(code, server, network, apiKey, options, say) {
+    const passphrase = await newPassphrase(options);
+    const lockedCode = lockCode(code, passphrase);
+    writeCredentials({ lockedCode, server, network, ...(apiKey ? { apiKey } : {}) });
+    say(`Sealed for ${server} (${network}) in ${credentialsPath()}`);
+    say(``);
+    say(`  What is on disk is not the account code. Opening it needs the passphrase, so a copy of`);
+    say(`  this file — in a backup, a synced folder, a container image, a stolen disk — is worth`);
+    say(`  nothing on its own.`);
+    say(``);
+    say(`  ⚠ It does NOT protect the code from anything running as you on this machine while you`);
+    say(`    are using the tool. Whatever supplies the passphrase can be read the same way.`);
+    say(``);
+    say(`  Every command that needs the code will ask for the passphrase, or read it from`);
+    say(`  ${PASSPHRASE_ENV_VAR}. Opening it costs a fraction of a second and 64 MiB of memory each`);
+    say(`  time, on purpose: that is what makes guessing the passphrase expensive.`);
+    return 0;
+}
+/**
+ * In the clear, behind the disclaimer.
+ *
+ * ⛔ THE AGREEMENT IS DEMANDED BEFORE THE CODE IS WRITTEN. ⚠ Not before anything at all happens:
+ *    `codeStorageIsPrivate()` runs first and creates the config directory 0700 while measuring
+ *    whether a file there can be kept private — that measurement is what the refusal's text has
+ *    to be right about, so it cannot come after it.
+ */
+function storePlain(code, server, network, apiKey, say) {
+    const private_ = codeStorageIsPrivate();
+    requireConsent("unsafe-code-storage");
+    writeCredentials({ accountCode: code, server, network, ...(apiKey ? { apiKey } : {}) });
+    say(`Stored in the clear for ${server} (${network}) in ${credentialsPath()}`);
+    if (modesAreEnforced()) {
+        say(`  The file is readable only by you (mode 600). It is not encrypted: anything running as`);
+        say(`  you can read it, which includes every agent you run on this machine.`);
+    }
+    else {
+        say(`  Windows does not apply a file mode here, so the file inherits the folder's permissions.`);
+    }
+    if (!private_) {
+        say(``);
+        say(`  ⛔ This machine did not keep the mode that was asked for, so anybody who can reach that`);
+        say(`     path can read the code. \`${BINARY_NAME} login\` without --plain seals it instead,`);
+        say(`     and ${CODE_ENV_VAR}_FILE names a file this tool never copies.`);
+    }
+    return 0;
+}
+/**
+ * Write nothing; print what to set.
+ *
+ * ⛔ THIS PRINTS THE ACCOUNT CODE, which every other part of this tool refuses to do. It is the
+ *    one command whose entire purpose is to hand it back, it says so, and it is behind an
+ *    agreement that names how an environment variable leaks.
+ */
+function printEnvForm(code, say) {
+    requireConsent("plain-env");
+    // ⛔ SINGLE QUOTES AND NO INTERPOLATION. A shell cannot be persuaded to run part of a
+    //    single-quoted string, and a code containing a single quote — the one character that would
+    //    break it — cannot exist: the alphabet is Crockford base32, and `'` is refused by the parser
+    //    that already accepted this code.
+    //
+    // ⛔ AND THE WHITESPACE COMES OUT FIRST. The parser treats EVERY whitespace character as an
+    //    ignorable separator, so a perfectly valid code can arrive with newlines in it — and this
+    //    printed it as eight lines while calling it one, the first of which was an unterminated
+    //    string. What is printed has to be a line somebody can paste.
+    say(`export ${CODE_ENV_VAR}='${code.replace(/\s+/gu, "")}'`);
+    say(``);
+    say(`  Nothing was written to this machine. Paste that where your program's environment is set.`);
+    say(``);
+    say(`  ⚠ The code is now on this screen, and probably in this terminal's scrollback. An`);
+    say(`    environment variable is readable by anything running as you, by every child process,`);
+    say(`    and — inside a container — by anybody who can run \`docker inspect\`.`);
+    say(``);
+    say(`  ${CODE_ENV_VAR}_FILE names a FILE holding the code instead, and has none of those.`);
+    return 0;
+}
+/**
+ * What is known about the code once it is stored — which depends on whether a key was checked.
+ *
+ * ⛔⭐ THE SECOND HALF WENT FALSE THE DAY THIS COMMAND STARTED CHECKING A KEY. "Whether the account
+ *    exists has not been checked" was exactly right while nothing here spoke to the server; after a
+ *    key is accepted, an account demonstrably exists. What is STILL unknown is a different thing
+ *    and a sharper one — whether the code and the key belong to the SAME account — and it cannot
+ *    be checked by anybody, because the code never goes to the server. Saying the old sentence
+ *    after a key had just been accepted would have been the tool describing the world before it.
+ */
+function sayCheckSymbol(say, keyWasAccepted) {
+    say(``);
+    say(`  The code is well-formed — its own check symbol matches. That was verified here, offline.`);
+    if (!keyWasAccepted) {
+        say(`  Whether the account EXISTS has not been checked: signing in goes through a human check`);
+        say(`  this tool cannot pass yet, so that will first show up on a command that needs the server.`);
+        return;
+    }
+    say(`  ⚠ Whether it is the code for the account the KEY belongs to has not been checked, and`);
+    say(`    cannot be: the code never goes to the server, so nothing can compare the two. A code`);
+    say(`    from a different account looks like an account with nothing in it.`);
+}
+/**
+ * What was decided about the API key, said after where the code went.
+ *
+ * ⛔ THE HANDLE AND NOTHING ELSE. The half printed here is the one the account screen lists; the
+ *    secret half is not shown in a confirmation, in an error, or under --json anywhere else in
+ *    this tool. Whoever ran this command already has the key, so there is nothing to gain by
+ *    echoing it — and a confirmation lands in scrollback, in a screen share, and in whatever an
+ *    agent writes to its log.
+ */
+function sayAboutTheKey(outcome, server, say) {
+    switch (outcome.kind) {
+        case "unchanged":
+            // The key that was here is still here and was not touched. Nothing happened to report.
+            return;
+        case "none":
+            say(``);
+            say(`No API key is stored, and every command that talks to the server needs one.`);
+            say(``);
+            say(`  Make one on the account screen at ${HOME_URL}, then run \`${BINARY_NAME} login\` again`);
+            say(`  with it in ${API_KEY_ENV_VAR} — or paste it when this asks. It is checked with the`);
+            say(`  server before it is written down.`);
+            say(``);
+            say(`  ${API_KEY_FILE_ENV_VAR} names a FILE holding the key instead, which is the shape a`);
+            say(`  container cannot leak. The key waives the human check a browser sign-in does, and`);
+            say(`  nothing else — it opens no file.`);
+            return;
+        case "stored":
+            say(``);
+            say(`Key ${outcome.handle} stored for ${server}.`);
+            say(``);
+            say(`  That is the key's public handle — the part the account screen lists. The secret half`);
+            say(`  is not printed here.`);
+            say(``);
+            say(`  ${server} accepted it just now, so it is a key this account has and nothing has`);
+            say(`  revoked. It waives the human check a browser sign-in does, and nothing else — it`);
+            say(`  opens no file, and what it is allowed to ask for was decided when it was made.`);
+            if (!outcome.verified) {
+                say(``);
+                say(`  ⚠ Nothing has checked lately that a person is behind this account, so some requests`);
+                say(`    are refused and the rest are held to tighter limits. \`${BINARY_NAME} verify\` prints`);
+                say(`    a code for a person to type at a browser.`);
+            }
+            return;
+        case "kept":
+            say(``);
+            say(`⚠ A different API key is in ${keySourceName(outcome.from)}. It was NOT stored.`);
+            say(``);
+            say(`  The key already on this machine is left as it is. Replacing one is something to say`);
+            say(`  out loud, not something a run about the account code does on the way past — every`);
+            say(`  agent using the old one would stop working at a moment nobody would connect to this.`);
+            say(``);
+            say(`  While that variable is set, every command uses what it holds anyway: the environment`);
+            say(`  wins over what is stored. To store it instead — at a terminal, run this again and`);
+            say(`  answer the question it asks; with no terminal, \`${BINARY_NAME} logout\` first and`);
+            say(`  then \`${BINARY_NAME} login\`.`);
+            return;
+    }
+}
+/**
+ * A passphrase for a NEW seal: from the environment, or typed twice.
+ *
+ * ⚠ The environment form is not confirmed, because there is nothing to confirm it against and
+ *   asking would hang. A typo there produces a file whose passphrase nobody knows — which is why
+ *   the message below says to keep it, not merely to choose it.
+ */
+async function newPassphrase(options) {
+    const ask = options.readPassphrase;
+    const fromEnv = process.env[PASSPHRASE_ENV_VAR];
+    if (ask === undefined && fromEnv !== undefined && fromEnv.length > 0) {
+        if (fromEnv.length < MIN_PASSPHRASE)
+            throw tooShort();
+        return fromEnv;
+    }
+    if (ask === undefined && !stdinIsATerminal()) {
+        throw new NmtsError("Sealing the account code needs a passphrase, and there is no terminal.", {
+            exitCode: 2,
+            nextStep: [
+                `One of these:`,
+                `  · set ${PASSPHRASE_ENV_VAR} and run this again`,
+                `  · ${BINARY_NAME} login --plain   store it unsealed (asks for an agreement first)`,
+                `  · ${BINARY_NAME} login --env     store nothing; print the variable to set`,
+            ].join("\n"),
+        });
+    }
+    const prompt = ask ?? ((q) => promptSecret(q, PASSPHRASE_ENV_VAR));
+    const first = await prompt(`New passphrase for the stored code (not shown as you type): `);
+    if (first.length < MIN_PASSPHRASE)
+        throw tooShort();
+    const again = await prompt(`Type it again: `);
+    if (!samePassphrase(first, again)) {
+        throw new NmtsError("Those two passphrases are not the same.", {
+            exitCode: 2,
+            nextStep: `Nothing was written. Run \`${BINARY_NAME} login\` again.`,
+        });
+    }
+    return first;
+}
+function tooShort() {
+    return new NmtsError(`That passphrase is shorter than ${MIN_PASSPHRASE} characters.`, {
+        exitCode: 2,
+        nextStep: `Nothing was written. A short passphrase is guessed whatever the tool does to slow guessing ` +
+            `down. ⛔ If it is lost, the sealed copy cannot be opened by anybody — keep it somewhere.`,
+    });
+}

package/dist/commands/logout.js

@@ -0,0 +1,33 @@
+// `nmts logout` — remove the stored account code from this machine.
+//
+// ⚠ WHAT IT DOES NOT DO. It removes a file. It does not end any session on the server, and it
+//    cannot reach a copy of the code that has already been read by something else on this machine.
+//    Saying "logged out" without saying that would suggest a revocation that did not happen.
+import { rmSync } from "node:fs";
+import { credentialsPath } from "../credentials.js";
+export function logout(write) {
+    const say = write ?? ((line) => process.stdout.write(`${line}\n`));
+    const path = credentialsPath();
+    let removed = true;
+    try {
+        rmSync(path);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            removed = false;
+        else
+            throw error;
+    }
+    say(removed ? `Removed ${path}` : `Nothing to remove — ${path} does not exist.`);
+    if (removed) {
+        say(`  This deleted a file. It did not end anything on the server, and it cannot reach a copy`);
+        say(`  that something on this machine already read.`);
+    }
+    return 0;
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/commands/ls.js

@@ -0,0 +1,202 @@
+// `nmts ls` — what is in the account, read from the sealed file list.
+//
+// ⚠ IT ANSWERS FROM THE LIST, NOT FROM THE FILES. Names, sizes and folders live in one sealed
+//   blob that only this account's key opens; the server holds it and cannot read it. So this
+//   command proves what the list says, and proves nothing about whether the bytes behind each
+//   entry are still fetchable — that is what `get` will be for.
+//
+// ⛔ TRASHED ENTRIES ARE HIDDEN BY DEFAULT AND SAID TO BE HIDDEN. A count that silently omits
+//    things is how somebody concludes a file is gone. `--all` shows them, marked.
+//
+// ⛔ AND THAT RULE GOVERNS THE TWO NEW WAYS OF SHOWING LESS. `--find` prints a subset and says how
+//    many files it left out and that folders holding no match are gone from the table; `--sort`
+//    changes the order and never the membership. A narrowed listing that looks exactly like a full
+//    one is the same defect as a silent trash filter, arrived at from a different direction.
+//
+// ⛔ A WRONG OPTION IS REFUSED BEFORE THE ACCOUNT IS TOUCHED. `--sort largest` is a wrong command
+//    line, not a failing account, so it costs no round trip and reads as exit 2 — otherwise an
+//    agent that mistyped a key goes off investigating the account instead of its own arguments.
+import { CODE_ENV_VAR } from "../credentials.js";
+import { buildIndex, fullPathOf, isLive, KIND_FOLDER, trashedAt } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { marksOf, markSuffix } from "../mark-render.js";
+import { idsForQuery, needleOf } from "../list-view-find.js";
+import { orderRows, parseSortKey } from "../list-view-order.js";
+import { readFileList } from "../manifest.js";
+import { openSession } from "../session.js";
+import { daysLeftInTrash, TRASH_RETENTION_DAYS } from "../trash-sweep.js";
+import { humanSize } from "../units.js";
+/**
+ * How much of a trashed entry's thirty days is left, in the words beside its row.
+ *
+ * ⛔ A TRASHED ROW HAS TO SAY WHEN. "[trash]" on its own tells somebody the file is recoverable and
+ *    not for how long, so the row that is about to lose its key looks exactly like the one thrown
+ *    away this morning — and the entry, once dropped, takes with it this account's copy of the key
+ *    that opens the file.
+ */
+function trashWindow(trashedAtMs, nowMs) {
+    const left = daysLeftInTrash(trashedAtMs, nowMs);
+    if (left <= 0)
+        return `past ${TRASH_RETENTION_DAYS} days — \`nmts sweep\` drops it`;
+    return `${left} day${left === 1 ? "" : "s"} left`;
+}
+/**
+ * The order this command has printed since it existed: whole paths, ascending.
+ *
+ * ⛔ IT IS STILL THE DEFAULT, and `--sort` is what asks for the browser's order instead. A path
+ *    order is the only one that draws the tree — every file sits under the folder that holds it —
+ *    and that is what somebody reading a flat listing of a whole drive is reading it for. Changing
+ *    the default would also silently rewrite what every script that already parses this output
+ *    sees.
+ *
+ * ⚠ `--desc` reverses it exactly, the same way it reverses the other three keys.
+ */
+function byPath(rows, dir) {
+    const sorted = [...rows].sort((a, b) => a.path.localeCompare(b.path));
+    return dir === "desc" ? sorted.reverse() : sorted;
+}
+export async function ls(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const now = options.now ?? Date.now();
+    const dir = options.desc === true ? "desc" : "asc";
+    const sort = options.sort === undefined ? null : parseSortKey(options.sort);
+    // ⛔ AN EMPTY QUERY IS REFUSED RATHER THAN IGNORED. `--find "$THING"` with nothing in `THING` is
+    //    a script that lost its variable, and both quiet answers are wrong: listing everything hands
+    //    back a drive that was never asked for, and listing nothing reports an empty account.
+    const needle = options.find === undefined ? null : needleOf(options.find);
+    if (needle === "") {
+        throw new NmtsError(`--find was given nothing to look for.`, {
+            exitCode: 2,
+            nextStep: `Nothing was listed. Give it part of a file's name, as in \`--find report\`.`,
+        });
+    }
+    // ⛔ THE REFUSALS ARE ONE TEXT, so they are resolved in one place. This command used to carry its
+    //    own copy of the "no API key" wording — the sentence a new user is most likely to see — and
+    //    it had already drifted from the other three (2026-08-23).
+    const session = await openSession({ server: options.server, network: options.network });
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (list.manifest === null) {
+        if (options.json) {
+            say(JSON.stringify({ state: "absent", entries: [] }));
+            return 0;
+        }
+        say(`This account has no file list yet. Nothing has been uploaded from any device.`);
+        return 0;
+    }
+    // ⛔ "IN THE TRASH" IS INHERITED. Trashing a folder marks the folder and nothing under it, so a
+    //    filter on `e.deletedAt` alone leaves every file inside it listed as live — while the server,
+    //    which was told to drop those rows, refuses their bytes. That is the one state this tool is
+    //    built to avoid, and it shipped: `hiddenTrashed` said 1 while two unreachable files were
+    //    printed as live (2026-08-23).
+    const index = buildIndex(list.manifest.entries);
+    const listed = options.all
+        ? list.manifest.entries
+        : list.manifest.entries.filter((e) => isLive(index, e));
+    const hidden = list.manifest.entries.length - listed.length;
+    // The query runs over what was going to be shown, so `--find` and `--all` compose instead of one
+    // quietly widening the other: a search without `--all` searches the drive, not the trash.
+    const keep = needle === null ? null : idsForQuery(index, listed, needle);
+    const shown = keep === null ? listed : listed.filter((e) => keep.has(e.id));
+    const filteredOutFiles = keep === null ? 0 : listed.filter((e) => e.kind !== KIND_FOLDER && !keep.has(e.id)).length;
+    const mapped = shown.map((e) => ({
+        id: e.id,
+        path: fullPathOf(index, e),
+        name: e.name,
+        kind: e.kind,
+        size: e.size,
+        createdAt: e.createdAt,
+        updatedAt: e.updatedAt,
+        trashed: !isLive(index, e),
+        // ⚠ When the thirty days run out. Present only for the trash, and only where the tool can
+        //   say it: an entry trashed by inheritance carries its ancestor's instant, not its own.
+        trashedAt: trashedAt(index, e),
+        marks: marksOf(e),
+        ...(e.pinned === true ? { pinned: true } : {}),
+    }));
+    const rows = sort === null ? byPath(mapped, dir) : orderRows(mapped, sort, dir);
+    if (options.json) {
+        say(JSON.stringify({
+            state: "present",
+            seq: list.seq,
+            serverSeqDisagreed: list.serverSeqDisagreed ?? null,
+            firstTimeOnThisMachine: list.firstTimeOnThisMachine,
+            hiddenTrashed: options.all ? 0 : hidden,
+            // What `--find` was given and how many files it dropped, so a caller can tell a narrowed
+            // listing from a whole one instead of comparing counts against a drive it cannot see.
+            query: options.find ?? null,
+            hiddenByQuery: filteredOutFiles,
+            entries: rows.map((row) => ({
+                id: row.id,
+                path: row.path,
+                name: row.name,
+                kind: row.kind === KIND_FOLDER ? "folder" : "file",
+                size: row.size,
+                createdAt: row.createdAt,
+                updatedAt: row.updatedAt,
+                trashed: row.trashed,
+                trashedAt: row.trashedAt,
+                marks: row.marks,
+            })),
+        }));
+        return 0;
+    }
+    if (rows.length === 0) {
+        if (needle === null) {
+            say(`The file list is empty${hidden > 0 ? ` (${hidden} in the trash, hidden)` : ""}.`);
+        }
+        else {
+            say(`No file in this account has "${options.find}" in its name` +
+                (hidden > 0 ? ` (${hidden} in the trash, not searched — \`--all\` searches those too)` : ``) +
+                `.`);
+        }
+    }
+    else {
+        const width = Math.max(...rows.map((r) => r.path.length));
+        for (const row of rows) {
+            const size = row.kind === KIND_FOLDER ? "" : humanSize(row.size);
+            const mark = row.trashed
+                ? `  [trash${row.trashedAt === null ? "" : `, ${trashWindow(row.trashedAt, now)}`}]`
+                : "";
+            say(`${row.path.padEnd(width)}  ${size.padStart(9)}${mark}${markSuffix(row.marks)}`);
+        }
+        say(``);
+        const files = rows.filter((r) => r.kind !== KIND_FOLDER).length;
+        const total = rows.filter((r) => r.kind !== KIND_FOLDER).reduce((n, r) => n + r.size, 0);
+        say(`${files} file${files === 1 ? "" : "s"} · ${humanSize(total)}` +
+            (needle === null ? `` : ` matching "${options.find}"`) +
+            (hidden > 0
+                ? needle === null
+                    ? ` · ${hidden} in the trash, hidden (--all shows them)`
+                    : ` · ${hidden} in the trash, not searched (--all searches those too)`
+                : ``));
+        // ⛔ THE TABLE SAYS WHAT IT LEFT OUT. Under a query the rows above are not the drive, and the
+        //    two ways that misleads are both quiet ones: files that did not match are simply absent,
+        //    and so is every folder holding none of them — including a folder whose own name contains
+        //    the text, because the query is matched against file names only.
+        if (needle !== null) {
+            say(``);
+            if (filteredOutFiles > 0) {
+                // Counted against what this same listing would have shown WITHOUT the query, so the
+                // sentence stays true under `--all` as well: it never claims to have counted the trash.
+                say(`  Without --find this listing would also have shown ${filteredOutFiles} other ` +
+                    `file${filteredOutFiles === 1 ? "" : "s"}, which did not match.`);
+            }
+            say(`  Only file names are matched, so a folder is never a match of its own — the folders`);
+            say(`  above are the ones that hold a match, and folders holding none are not listed.`);
+        }
+    }
+    // ⛔ Said out loud rather than left as a footnote: on a first run there was nothing on this
+    //    machine to compare the version against, so a rolled-back list would have looked normal.
+    if (list.firstTimeOnThisMachine) {
+        say(``);
+        say(`  First listing on this machine, so nothing here could have caught an older list being`);
+        say(`  served in place of the current one. From now on this tool refuses a version lower than`);
+        say(`  the highest it has seen for this account.`);
+    }
+    if (list.serverSeqDisagreed !== undefined) {
+        say(``);
+        say(`  The server said version ${list.serverSeqDisagreed}; the sealed list says ${list.seq}.`);
+        say(`  The sealed number is the one that is authenticated, so it is the one used.`);
+    }
+    return 0;
+}