@needmoretruth/nmts-cli 0.17.2

package/dist/commands/create.js

@@ -0,0 +1,356 @@
+// `nmts create` — bringing a NEW account into existence and handing its code to a person.
+//
+// ⛔ THE CODE IS MADE HERE AND IS THE ONLY COPY THAT WILL EVER EXIST. The server is told an
+//    account id and a one-way secret derived from the code; it stores a verifier of the second
+//    and never the code itself. Nothing on the far end can send it back, reset it, or recognise a
+//    replacement: if it is lost the account and every file in it are gone, for the holder and for
+//    NMTS alike. That is why the code is the LAST thing this prints, with nothing after it but
+//    the one command that would store it, and why nothing else in the output competes with it.
+//
+// ⛔ IT STORES NOTHING AND SWITCHES NOTHING OVER. `nmts login` is what puts a code on this
+//    machine, and it is a separate act on purpose: this command runs with the credentials of the
+//    account that is DOING the creating, and writing the new code into `credentials.json` would
+//    silently replace them — the next `nmts ls` would report an empty account and nothing would
+//    say why. So the code is printed (or written where you point it), the command that stores it
+//    is named, and this stops.
+//
+// ⛔ WITH `--json` THE CODE DOES NOT GO INTO THE OUTPUT. Machine-readable output is read by a
+//    program, which means it lands in a pipe, a file, a CI log or an agent's transcript — the
+//    exact places `credentials.ts` spends its whole header keeping the account code out of. So
+//    `--json` is refused unless `--out <file>` names somewhere for the code to go, and the JSON
+//    then carries the PATH and not the value. That is the same shape this tool already recommends
+//    for handing a secret to a container (`NMTS_ACCOUNT_CODE_FILE` — a variable holding a
+//    filename, never the value), and the same reasoning `stdout.ts` uses about handing bytes to
+//    something that is not a person: what is safe to show a human at a terminal and what is safe
+//    to hand a program are different questions. `--out -` is refused for the same reason.
+//
+// ⛔ AND THE FILE IS WRITTEN BEFORE THE ACCOUNT IS ASKED FOR. A full disk, a bad path or a name
+//    already taken must fail while there is still nothing to lose; discovering it AFTER the
+//    server has created the account would mean an account exists whose only key we are about to
+//    drop. If the creation then fails, the file is removed again — no account, no code, no trace.
+//
+// ⛔ THE FIRST DOOR OF `POST /v1/accounts` IS NOT AVAILABLE TO THIS TOOL AND NEVER WILL BE. The
+//    server takes either a solved human check with no credential, or an API key whose account had
+//    a PERSON pass that check within four of its weeks. A machine cannot solve the first, so this
+//    command works only for a caller that already has an account and a verified key — and it says
+//    that plainly, before it makes anything, rather than failing with a message about scopes.
+import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { request, ServerError } from "../api.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { askAPersonToVerify, humanCheck } from "../human-check.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { newAccountCode, registrationProofOf } from "../registration.js";
+import { resolveServer } from "../server.js";
+import { requireApiKey } from "../session.js";
+import { STDOUT_TARGET } from "../stdout.js";
+export async function create(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const apiKey = requireApiKey();
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    // ⛔ EVERY REFUSAL THAT DOES NOT NEED THE NETWORK HAPPENS FIRST, so a run that was never going
+    //    to work does not spend one of the creator's two accounts for the day finding that out.
+    const codeFile = codeFileTarget(options.out);
+    if (options.json === true && codeFile === null)
+        throw jsonNeedsAFile();
+    const check = await humanCheck(server, apiKey);
+    if (!check.live)
+        throw askAPersonToVerify("No account can be created");
+    const inForce = await termsInForce(server, apiKey);
+    const accepted = inForce === null ? null : acceptanceOffered(inForce, options);
+    const code = await newAccountCode();
+    const proof = await registrationProofOf(code);
+    // The file, then the account — see the header. Nothing below this line may fail without either
+    // removing the file or leaving an account whose code is in it.
+    if (codeFile !== null)
+        writeCodeFile(codeFile, code);
+    let answer;
+    try {
+        answer = await request(server, "/v1/accounts", {
+            method: "POST",
+            token: apiKey,
+            body: {
+                account_id: proof.accountId,
+                auth_secret: proof.authSecret,
+                // ⚠ Absent when no documents are in force. The server ignores them in that case, and
+                //   sending a pair it is not asking for would be recording an acceptance of nothing.
+                ...(accepted === null ? {} : { terms_version: accepted.terms, privacy_version: accepted.privacy }),
+            },
+        });
+    }
+    catch (error) {
+        // ⛔ "THE REQUEST FAILED" AND "THE ACCOUNT WAS NOT CREATED" ARE DIFFERENT FACTS. A refusal the
+        //    server ANSWERED is it deciding: nothing exists, and a code file for it is a file somebody
+        //    keeps forever for nothing. A dropped connection, a timeout, or an answer nothing could
+        //    parse leaves the question open — the account may be there — and deleting the file then
+        //    would destroy the only key to it, which is the one irreversible mistake on this path.
+        if (codeFile !== null && error instanceof ServerError)
+            rmSync(codeFile, { force: true });
+        throw codeFile !== null && !(error instanceof ServerError)
+            ? uncertain(codeFile, error)
+            : explain(error, inForce);
+    }
+    const createdAt = accountField(answer, "created_at");
+    if (options.json === true && codeFile !== null) {
+        // ⛔ NO `account_code` FIELD, AND THERE NEVER WILL BE. See the header.
+        say(JSON.stringify({
+            account_id: proof.accountId,
+            created_at: createdAt,
+            code_file: codeFile,
+            server,
+            network,
+        }));
+        return 0;
+    }
+    sayCreated(say, proof.accountId, server, network);
+    if (codeFile === null)
+        sayTheCode(say, code);
+    else
+        sayWhereTheCodeWent(say, codeFile);
+    return 0;
+}
+/**
+ * Where the code goes, or `null` for the screen.
+ *
+ * ⛔ `-` IS REFUSED, WHICH IS THE OPPOSITE OF WHAT IT MEANS EVERYWHERE ELSE IN THIS TOOL. In
+ *    `get` and `listfile` it means "hand the bytes to whatever is reading stdout", and that is
+ *    right for a file somebody already has. Here it would mean putting the only copy of an
+ *    account code into the same stream a program is parsing — which is the one place this command
+ *    exists to keep it out of.
+ */
+function codeFileTarget(out) {
+    if (out === undefined || out === "")
+        return null;
+    if (out === STDOUT_TARGET) {
+        throw new NmtsError("The new account code will not be sent to stdout.", {
+            exitCode: 2,
+            nextStep: `Nothing was created. stdout is what a program reads and a log keeps, and this is the ` +
+                `only copy of the code. Name a file — \`--out ./account-code.txt\` — or leave --out off ` +
+                `and read it off the screen.`,
+        });
+    }
+    const path = isAbsolute(out) ? out : resolve(process.cwd(), out);
+    let existing = null;
+    try {
+        existing = statSync(path);
+    }
+    catch {
+        // Not there is exactly what this wants.
+    }
+    if (existing !== null) {
+        // ⛔ NO `--force` HERE, DELIBERATELY. Everywhere else in this tool --force replaces a file
+        //    that can be fetched again. The file this would replace may be the only copy of ANOTHER
+        //    account's code, and overwriting it destroys that account with no way back.
+        throw new NmtsError(`${path} is already there.`, {
+            exitCode: 4,
+            nextStep: existing.isDirectory()
+                ? `--out names the FILE the code goes into, not a directory.`
+                : `Nothing was created. That file is not replaced, whatever --force says: it may hold ` +
+                    `the only copy of another account's code. Name one that does not exist.`,
+        });
+    }
+    return path;
+}
+/**
+ * Write the code where the caller pointed, readable by nobody else.
+ *
+ * ⚠ `wx` FAILS IF THE NAME APPEARED SINCE THE CHECK ABOVE, which is the point of using it rather
+ *   than trusting that check: between the two, something else may have written there.
+ *
+ * ⚠ ON WINDOWS THE MODE IS IGNORED and the file inherits the folder's permissions — the same
+ *   limit `credentials.ts` documents, and claiming otherwise would be claiming a guarantee the
+ *   platform does not give.
+ */
+function writeCodeFile(path, code) {
+    const dir = resolve(path, "..");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        writeFileSync(path, `${code}\n`, { mode: 0o600, flag: "wx" });
+    }
+    catch (error) {
+        // ⛔ THE CAUSE IS NAMED BUT THE CODE IS NOT. `writeFileSync`'s errno line carries the path and
+        //    never the contents, so it is safe to pass on; the code itself appears in no message here.
+        throw new NmtsError(`The account code could not be written to ${path}.`, {
+            exitCode: 1,
+            nextStep: `Nothing was created — the file is written before the account is asked for, so that a ` +
+                `failure here costs nothing. Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+/** What documents this server is enforcing, read from the one route a key may ask. */
+async function termsInForce(server, apiKey) {
+    const answer = await request(server, "/v1/account/summary", { token: apiKey });
+    const terms = isRecord(answer) ? answer["terms"] : null;
+    if (!isRecord(terms))
+        return null;
+    const t = terms["required_terms_version"];
+    const p = terms["required_privacy_version"];
+    // ⚠ BOTH OR NEITHER. The server holds one pair or none (`RequiredTerms`), so a half-answer is a
+    //   version of this API this tool does not understand — and guessing which half to send would
+    //   be recording an acceptance of a document nobody named.
+    if (typeof t !== "string" || typeof p !== "string" || t === "" || p === "")
+        return null;
+    return { terms: t, privacy: p };
+}
+/**
+ * The acceptance a PERSON offered on the command line, checked against what is in force.
+ *
+ * ⛔ THIS TOOL NEVER FILLS THESE IN. It has just read the two versions from the server and could
+ *    put them in the request without asking anybody — and that is precisely the thing it must not
+ *    do. The server's own rule for a credential held by a machine is that a machine cannot
+ *    consent: a key that could accept would produce exactly the unrecorded acceptance the record
+ *    exists to prevent. What a command line CAN carry is a person's act, named by them, after
+ *    they have read the documents — so the two versions have to be typed, and typing the version
+ *    rather than a yes is what makes the acceptance name a document instead of a prompt.
+ *
+ * ⚠ AND NO MECHANISM HERE CAN TELL A PERSON FROM A PROGRAM. Nothing in a command-line tool can.
+ *   That is why the refusal says out loud who is meant to type it, exactly as this tool's own
+ *   agreements do — a rule, not a protection, and saying otherwise would be claiming one that is
+ *   not there.
+ */
+function acceptanceOffered(inForce, options) {
+    const terms = options.acceptTerms?.trim() ?? "";
+    const privacy = options.acceptPrivacy?.trim() ?? "";
+    if (terms === inForce.terms && privacy === inForce.privacy)
+        return inForce;
+    throw termsRefusal(inForce, terms !== "" || privacy !== "");
+}
+function termsRefusal(inForce, named) {
+    return new NmtsError(named
+        ? "The documents named on the command line are not the ones in force."
+        : "A new account is recorded as accepting the documents in force, and nobody has.", {
+        // ⛔ 5 — "waiting on the person's agreement". Not 1: nothing went wrong, and not 2: the
+        //    command line is not malformed. What is missing is a decision only a person can take.
+        exitCode: 5,
+        nextStep: [
+            `Nothing was created and no account code was made.`,
+            ``,
+            `In force now:`,
+            `  Terms of Service  ${inForce.terms}`,
+            `  Privacy Policy    ${inForce.privacy}`,
+            ``,
+            // ⚠ THE DOCUMENTS ARE ON THE PRODUCT SITE, not on whatever --server names. A development
+            //   server enforces versions and publishes no pages; sending somebody to read them there
+            //   would send them nowhere.
+            `Read them at ${HOME_URL}/terms and ${HOME_URL}/privacy .`,
+            ``,
+            `The server records the new account as having accepted that pair, and will not make one`,
+            `without it. This tool will not fill the two versions in for you: a machine cannot`,
+            `consent, and a credential that could accept would produce exactly the unrecorded`,
+            `acceptance the record exists to prevent.`,
+            ``,
+            `A person who has read both can say so, naming what they read:`,
+            ``,
+            `  ${BINARY_NAME} create --accept-terms ${inForce.terms} --accept-privacy ${inForce.privacy}`,
+            ``,
+            `⛔ If a program is reading this on somebody's behalf: show it to them and let them`,
+            `   decide. Do not run that command yourself.`,
+        ].join("\n"),
+    });
+}
+/**
+ * Turn the two refusals this command can hear into something a reader can act on.
+ *
+ * ⚠ EVERYTHING ELSE IS LEFT ALONE. `api.ts` already advises on a revoked key, a scope a key was
+ *   not given, and an account that has not accepted the terms; repeating any of that here would
+ *   be a second wording for one problem.
+ */
+function explain(error, inForce) {
+    if (!(error instanceof ServerError))
+        return error;
+    if (error.code === "TERMS_VERSION_MISMATCH" && inForce !== null) {
+        // The server moved between the read above and the write. Say that, rather than repeating the
+        // versions this run read — they are the stale ones.
+        return new NmtsError("The documents in force changed while this ran.", {
+            exitCode: 5,
+            nextStep: `Nothing was created. Run \`${BINARY_NAME} create\` again with no --accept flags: it will ` +
+                `print the pair that is in force now, for a person to read and name.`,
+        });
+    }
+    if (error.code === "RATE_LIMITED") {
+        return new NmtsError(error.message, {
+            exitCode: 4,
+            nextStep: `An account that creates accounts may make two a day and five a week, counted by the ` +
+                `server across restarts. Nothing was created and nothing was spent. Waiting is the only ` +
+                `thing that lifts it — a second key on the same account shares the same allowance.`,
+        });
+    }
+    return error;
+}
+/**
+ * The server never answered, so nobody here knows whether the account exists.
+ *
+ * ⛔ THE FILE IS KEPT AND THE DOUBT IS SAID OUT LOUD. Reporting this as a plain failure would
+ *    leave somebody with a code file they think is rubbish, for an account that may hold the only
+ *    thing they will ever be able to open it with.
+ */
+function uncertain(path, cause) {
+    return new NmtsError(`The server did not answer, so whether the account was created is not known here.`, {
+        exitCode: 1,
+        nextStep: [
+            `${path} was KEPT, and it holds the only code that account would have.`,
+            ``,
+            `Keep it until you know. Nothing on this machine can tell the two cases apart, and the`,
+            `cost of being wrong is one small file against an account nobody could ever open.`,
+            `Running this again makes a DIFFERENT account; it does not retry this one.`,
+            ``,
+            `Cause: ${cause instanceof Error ? cause.message : String(cause)}`,
+        ].join("\n"),
+    });
+}
+function jsonNeedsAFile() {
+    return new NmtsError("--json needs --out, because the account code will not go into the output.", {
+        exitCode: 2,
+        nextStep: `Nothing was created. Machine-readable output is read by a program and kept by a log, and ` +
+            `the code is the only key this account will ever have. \`--out ./account-code.txt\` writes ` +
+            `it to a file only you can read; the JSON then names that file. Without --json the code is ` +
+            `printed on the screen for a person to keep.`,
+    });
+}
+/** One field of the answer's `account` object, or null. The server's shape, not ours. */
+function accountField(answer, field) {
+    const account = isRecord(answer) ? answer["account"] : null;
+    if (!isRecord(account))
+        return null;
+    const value = account[field];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function sayCreated(say, accountId, server, network) {
+    say(`A new account exists on ${server} (${network}).`);
+    say(``);
+    say(`  account id  ${accountId}`);
+    say(``);
+    say(`Nothing on this machine changed. The account code you were signed in as is still the one`);
+    say(`this tool uses; this new account is not stored, and not switched to.`);
+    say(``);
+}
+/**
+ * The code, last, with the one thing that has to be understood before it.
+ *
+ * ⛔ NOTHING FOLLOWS IT BUT THE COMMAND THAT STORES IT. A screen of next steps under an account
+ *    code is how a person scrolls past the only copy of it.
+ */
+function sayTheCode(say, code) {
+    say(`⛔ THIS IS THE ONLY COPY OF THE ACCOUNT CODE THAT WILL EVER EXIST.`);
+    say(`   NMTS keeps a verifier and never the code. It cannot be reset, resent or replaced.`);
+    say(`   Lose it and the account and every file in it are gone — for you and for NMTS.`);
+    say(``);
+    say(`   ${code}`);
+    say(``);
+    say(`To use this machine as that account: \`${BINARY_NAME} logout\`, then \`${BINARY_NAME} login\`.`);
+}
+function sayWhereTheCodeWent(say, path) {
+    say(`⛔ THE ONLY COPY OF THE ACCOUNT CODE IS NOW IN ONE FILE, AND NOWHERE ELSE.`);
+    say(`   NMTS keeps a verifier and never the code. It cannot be reset, resent or replaced.`);
+    say(`   Lose that file and the account and every file in it are gone.`);
+    say(``);
+    say(`   ${path}`);
+    say(``);
+    say(`It was written readable by you alone. To use this machine as that account:`);
+    say(`\`${BINARY_NAME} logout\`, then \`${BINARY_NAME} login\`.`);
+}

package/dist/commands/env.js

@@ -0,0 +1,136 @@
+// `nmts env` — what this machine is, and what that means for the account code.
+//
+// ⛔ IT ASKS THE SERVER NOTHING AND NEEDS NO CREDENTIAL. It is the first command an agent can run
+//    on a machine it has never seen, and a command that needed to be signed in to say "there is
+//    nowhere safe to keep the code here" would say it too late.
+import { adviseFor, readEnvironment } from "../environment.js";
+import { PASSPHRASE_ENV_VAR, resolveAccountCode, resolveApiKey, } from "../credentials.js";
+import { BINARY_NAME, SUPPORT_EMAIL, VERSION } from "../product.js";
+import { checkingIsOff, NO_CHECK_ENV_VAR, readCheck } from "../update-check.js";
+import { isNewer } from "../update-source.js";
+/**
+ * Where a credential came from, in words rather than in the field name.
+ *
+ * ⛔ `--json` keeps the field name. A machine wants a value it can compare; a person reading the
+ *    table wants to know whether the thing on disk is the code or a sealed copy of it, and
+ *    "file-locked" does not say that to somebody who has never read this source.
+ */
+function sourceWords(source) {
+    switch (source) {
+        case "env":
+            return "environment variable — readable by anything running as you";
+        case "secret-file":
+            return "a file named by an environment variable";
+        case "file":
+            return "this tool's own file, unsealed";
+        case "file-locked":
+            return "this tool's own file, sealed with a passphrase";
+    }
+}
+/**
+ * What the version check last did, in one line.
+ *
+ * ⛔ IT IS IN HERE BECAUSE THE CHECK IS QUIET. It is the only request this tool makes that no
+ *    command asked for, and it never fails a command — so if it has been failing for a month,
+ *    this line is the only place that says so. A quiet mechanism with nowhere to report is
+ *    indistinguishable from one that is not running.
+ */
+function updateCheckWords(running) {
+    if (checkingIsOff())
+        return `off — ${NO_CHECK_ENV_VAR} is set`;
+    const record = readCheck();
+    if (record === null)
+        return `has not run yet`;
+    const when = record.checkedAt.slice(0, 16).replace("T", " ");
+    if (record.failed !== undefined)
+        return `⛔ last try ${when} UTC did not answer — ${record.failed}`;
+    if (record.latest === undefined)
+        return `last ran ${when} UTC and found nothing to compare`;
+    return isNewer(record.latest, running)
+        ? `${record.latest} is published (this is ${running}) — \`${BINARY_NAME} update\` installs it`
+        : `${record.latest} is newest, looked up ${when} UTC`;
+}
+export function env(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const environment = readEnvironment();
+    // ⛔ WHETHER, NOT WHAT. Nothing about a credential's VALUE is read here, printed here, or
+    //    returned by --json. What is reported is that one was found and where it came from.
+    let code = null;
+    let key = null;
+    // ⛔ REFUSED IS NOT ABSENT, AND THIS COMMAND IS THE ONE PLACE THAT MUST SAY WHICH. Both of these
+    //    used to swallow the failure and report "not found" — so a credentials file gone
+    //    world-readable, which is a leak nothing else in the system ever mentions, was invisible in
+    //    the very command written to be run first on a machine nobody knows. The MESSAGE is kept
+    //    (it names a path, never a value); the credential is not.
+    let codeProblem = null;
+    let keyProblem = null;
+    try {
+        code = resolveAccountCode();
+    }
+    catch (error) {
+        codeProblem = error instanceof Error ? error.message : String(error);
+    }
+    try {
+        key = resolveApiKey();
+    }
+    catch (error) {
+        keyProblem = error instanceof Error ? error.message : String(error);
+    }
+    const advice = adviseFor(environment, code !== null);
+    if (options.json) {
+        say(JSON.stringify({
+            ...environment,
+            accountCode: code === null
+                ? codeProblem === null
+                    ? null
+                    : { present: false, refused: codeProblem }
+                : { present: true, source: code.source },
+            apiKey: key === null
+                ? keyProblem === null
+                    ? null
+                    : { present: false, refused: keyProblem }
+                : { present: true, source: key.source },
+            advice,
+            updateCheck: checkingIsOff() ? { off: true } : (readCheck() ?? { ran: false }),
+        }));
+        return 0;
+    }
+    say(`  system        ${environment.os} ${environment.osRelease} · node ${environment.node}`);
+    const mapping = environment.rootMapped === null
+        ? ""
+        : environment.rootMapped
+            ? " · rootless (root here is an ordinary user on the host)"
+            : " · root here is root on the host";
+    say(`  containment   ${environment.containment}${mapping}`);
+    say(`  running as    uid ${environment.uid ?? "n/a"}`);
+    say(`  private files ${environment.privateStorage ? "yes" : "NO — this filesystem does not keep a file mode"}`);
+    say(`  config        ${environment.configDir}`);
+    say(`  terminal      ${environment.interactive ? "yes" : "no — nothing here can be typed"}`);
+    say(`  browser       ${environment.browserReachable ? "reachable" : "not reachable"}`);
+    const found = (got, problem) => (got !== null ? `found — ${sourceWords(got.source)}` : problem !== null ? `⛔ REFUSED — ${problem}` : "not found");
+    say(`  account code  ${found(code, codeProblem)}`);
+    if (code?.source === "file-locked") {
+        // ⛔ THE ANSWER AN AGENT NEEDS BEFORE IT RUNS ANYTHING ELSE. A sealed code with no way to
+        //    supply the passphrase is not a usable credential, and finding that out on the first
+        //    upload — after the file has been read and sealed — is finding it out too late.
+        const havePassphrase = (process.env[PASSPHRASE_ENV_VAR] ?? "").length > 0;
+        const how = havePassphrase
+            ? `${PASSPHRASE_ENV_VAR} is set`
+            : environment.interactive
+                ? `it will be asked for on the terminal`
+                : `⛔ NOT AVAILABLE — no ${PASSPHRASE_ENV_VAR} and no terminal`;
+        say(`  passphrase    ${how}`);
+    }
+    say(`  api key       ${found(key, keyProblem)}`);
+    say(`  version check ${updateCheckWords(VERSION)}`);
+    if (advice.length > 0) {
+        say(``);
+        for (const item of advice) {
+            say(`  ${item.level === "warn" ? "⛔" : "·"} ${item.text}`);
+        }
+    }
+    say(``);
+    say(`  \`${BINARY_NAME} env --json\` is the same thing in one line.`);
+    say(`  Something here wrong or missing? ${SUPPORT_EMAIL}`);
+    return 0;
+}

package/dist/commands/expiring.js

@@ -0,0 +1,167 @@
+// `nmts expiring` — which files are about to run out of the storage they were paid for.
+//
+// ⛔ IT IS ITS OWN COMMAND AND NOT A COLUMN IN `ls`. `ls` answers from the sealed file list alone
+//    and says so; this answers from three places at once — the chain for the epoch clock, the
+//    server for which files end when, and the list for what those files are called. Folding it in
+//    would make the cheapest and most-run command in this tool depend on a chain read that can be
+//    slow, blocked, or down, and the honest behaviour when that read fails is to STOP. A listing
+//    that stops because a storage network is unreachable is a worse listing.
+//
+// ⛔ NOTHING HERE IS DRAWN AS SAFE BECAUSE IT COULD NOT BE READ. An unreadable clock refuses; a
+//    file whose storage period was never recorded is reported as unrecorded and kept out of the
+//    ranking; a file the server names and the list does not is printed as an id rather than
+//    dropped. Silence is the failure this whole surface exists to prevent — the account screen and
+//    this command are the only two places an expiry warning ever appears, because NMTS holds no
+//    address to send one to.
+//
+// ⛔ AND IT BUYS NOTHING. What this does is make the deadline visible in time for somebody to act
+//    on it. Acting on it is `nmts extend`, which spends from the person's own wallet and asks for
+//    its own agreement first — this command reads, and no amount of it costs anything.
+import { request } from "../api.js";
+import { buildIndex, fullPathOf } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { daysLeftInWords, daysLeftUntilEpoch, stageOf, warningCutoffEpoch, } from "../expiry.js";
+import { readFileList } from "../manifest.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { openSession } from "../session.js";
+import { humanSize } from "../units.js";
+export async function expiring(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const now = options.now ?? Date.now();
+    const session = await openSession(options);
+    const readClock = options.readClock ??
+        (async () => (await import("../walrus-write.js")).readEpochWindow(session.network));
+    const clock = await readClock();
+    if (clock === null) {
+        // ⛔ Not "nothing is expiring". The two look identical from outside and mean opposite things.
+        throw new NmtsError(`The ${session.network} storage network's epoch clock could not be read.`, {
+            exitCode: 1,
+            nextStep: `Nothing was changed and nothing here can be answered without it: which epoch the network ` +
+                `is in is a fact only the chain has, and this tool will not count days from a constant. ` +
+                `Try again, or name a different Sui node in NMTS_SUI_RPC.`,
+        });
+    }
+    const cutoff = warningCutoffEpoch(clock);
+    const answer = asExpiringAnswer(await request(session.server, `/v1/items/expiring?before_epoch=${cutoff}`, { token: session.apiKey }));
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    const index = buildIndex(list.manifest?.entries ?? []);
+    const rows = answer.rows.map((row) => {
+        const entry = index.byId.get(row.id);
+        const stage = stageOf(clock, row.expiryEpoch, now);
+        const left = stage === "unrecorded" ? null : daysLeftUntilEpoch(clock, row.expiryEpoch, now);
+        return {
+            id: row.id,
+            path: entry === undefined ? null : fullPathOf(index, entry),
+            size: entry?.size ?? null,
+            expiryEpoch: row.expiryEpoch,
+            stage,
+            daysLeft: left === null ? null : left.days,
+            daysLeftExact: left?.exact ?? true,
+        };
+    });
+    // ⛔ SORTED BY DEADLINE, WITH THE UNKNOWNS AT THE BOTTOM. The server orders by the recorded epoch
+    //    and an unrecorded one is 0, so taking that order would head a list called "running out" with
+    //    the files nobody knows anything about.
+    const dated = rows.filter((r) => r.stage !== "unrecorded").sort((a, b) => a.expiryEpoch - b.expiryEpoch);
+    const unrecorded = rows.filter((r) => r.stage === "unrecorded");
+    if (options.json) {
+        say(JSON.stringify({
+            network: session.network,
+            epoch: clock.current,
+            epochDurationMs: clock.durationMs,
+            /** ⚠ Absent from the network's own answer most of the time — see `expiry.ts`. */
+            epochStartedMs: clock.startedMs,
+            beforeEpoch: cutoff,
+            truncated: answer.truncated,
+            files: [...dated, ...unrecorded],
+        }));
+        return 0;
+    }
+    const epochDays = clock.durationMs / 86_400_000;
+    say(`The ${session.network} storage network is at epoch ${clock.current}, and one epoch is ` +
+        `${epochDays === Math.round(epochDays) ? epochDays : epochDays.toFixed(1)} days.`);
+    if (dated.length === 0 && unrecorded.length === 0) {
+        say(`Nothing in this account runs out before epoch ${cutoff}.`);
+        return 0;
+    }
+    const width = Math.max(...[...dated, ...unrecorded].map((r) => nameOf(r).length));
+    if (dated.length > 0) {
+        say(``);
+        for (const row of dated) {
+            const left = row.daysLeft === null ? "" : daysLeftInWords({ days: row.daysLeft, exact: row.daysLeftExact });
+            const size = row.size === null ? "" : humanSize(row.size);
+            say(`${nameOf(row).padEnd(width)}  ${size.padStart(9)}  ends at epoch ${row.expiryEpoch}, ${left}` +
+                MARK[row.stage]);
+        }
+        say(``);
+        say(`${dated.length} file${dated.length === 1 ? "" : "s"} run out before epoch ${cutoff}.`);
+    }
+    if (unrecorded.length > 0) {
+        say(``);
+        for (const row of unrecorded) {
+            say(`${nameOf(row).padEnd(width)}  ${(row.size === null ? "" : humanSize(row.size)).padStart(9)}`);
+        }
+        say(``);
+        say(`${unrecorded.length} file${unrecorded.length === 1 ? " has" : "s have"} no storage period ` +
+            `recorded. That is not a short one: whatever uploaded them could not read the network's ` +
+            `epoch clock, so nothing was written down. The chain still knows; a browser can show it.`);
+    }
+    if (rows.some((r) => r.path === null)) {
+        say(``);
+        say(`  Rows marked "(not in the file list)" are files the server is holding that this account's`);
+        say(`  list does not name. An upload can commit and then fail before the list was written.`);
+        say(`  Nothing here can repair that; opening the account in a browser can.`);
+    }
+    if (answer.truncated) {
+        say(``);
+        say(`  The server stopped at its limit, so there are more than these. Extending some of them`);
+        say(`  and running this again shows the next ones.`);
+    }
+    say(``);
+    say(`Extending storage is paid for from your own wallet and signed on this machine: ` +
+        `\`${BINARY_NAME} extend <path>\`, or the browser at ${HOME_URL}. It spends WAL rather than ` +
+        `credits, and it asks once before it signs.`);
+    return 0;
+}
+/** What a row is called, with the reason spelled out when it has no name. */
+function nameOf(row) {
+    return row.path ?? `(not in the file list) ${row.id}`;
+}
+/** The two stages that need a word beside them. `soon` is the warning itself and needs none. */
+const MARK = {
+    lapsed: "  — TERM ENDED",
+    urgent: "  — EXTEND NOW",
+    soon: "",
+    later: "",
+    unrecorded: "",
+};
+/**
+ * What `GET /v1/items/expiring` answers, narrowed rather than trusted.
+ *
+ * ⛔ A ROW THIS CANNOT READ IS A REFUSAL, NOT A ROW TO SKIP. Skipping would turn a wire change into
+ *    a shorter warning list, which is the one way this command can fail without anybody noticing.
+ */
+function asExpiringAnswer(value) {
+    const unreadable = () => {
+        throw new NmtsError("The server answered with an expiry list this version cannot read.", {
+            nextStep: "Update this tool. Nothing was changed, and the account is not in any different state.",
+        });
+    };
+    if (typeof value !== "object" || value === null)
+        return unreadable();
+    const raw = Reflect.get(value, "items");
+    if (!Array.isArray(raw))
+        return unreadable();
+    const items = raw;
+    const rows = [];
+    for (const item of items) {
+        if (typeof item !== "object" || item === null)
+            return unreadable();
+        const id = Reflect.get(item, "item_id");
+        const epoch = Reflect.get(item, "expiry_epoch");
+        if (typeof id !== "string" || typeof epoch !== "number")
+            return unreadable();
+        rows.push({ id, expiryEpoch: epoch });
+    }
+    return { rows, truncated: Reflect.get(value, "truncated") === true };
+}