@needmoretruth/nmts-cli 0.17.2

package/dist/commands/extend.js

@@ -0,0 +1,236 @@
+// `nmts extend <path>` — buy more storage time for one file that is already stored.
+//
+// ⛔ THE ONLY COMMAND IN THIS TOOL THAT SIGNS ANYTHING, and the only one that spends from a
+//    WALLET. Every other purchase here is made with credits, which are a promise this service
+//    made; this one moves WAL out of the wallet the account code derives, on a public chain, and
+//    nobody — NMTS included — can reverse it. That difference is said out loud, in the output,
+//    before the agreement is asked for.
+//
+// ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. The reads and the quote are free and happen first, so
+//    `--dry-run` answers with a real number and never reaches the key. Nothing below the quote can
+//    run without `requireConsent("wallet")` having passed.
+//
+// ⛔ THE SERVER DOES NOT EXTEND ANYTHING, and this command is shaped by that. `POST
+//    /v1/items/{id}/extended` means "record an extension the device already signed": the storage is
+//    already bought by the time it is called, so a failure there is a failure to WRITE THE DATE
+//    DOWN and is reported as itself. Saying "extension failed" would invite a second run, and a
+//    second run pays again.
+//
+// ⛔ AND A FILE THAT IS NOT RUNNING OUT IS NOT EXTENDED BY ACCIDENT. Extending early loses nothing
+//    — epochs are added to what is left — so this is not a refusal on principle; it is a refusal
+//    to spend money on a deadline nobody is near, unless somebody says so with `--yes`.
+import { requireConsent } from "../consent.js";
+import { request } from "../api.js";
+import { buildIndex, entryAt, fullPathOf, KIND_FILE, normalisePath } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { daysLeftInWords, daysLeftUntilEpoch, stageOf, } from "../expiry.js";
+import { asExtendPreview, chooseEpochs, headroom, soonestEnd, } from "../extend-plan.js";
+import { isRecord } from "../guards.js";
+import { readFileList } from "../manifest.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { coinAmount } from "../wallet.js";
+export async function extend(target, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const now = options.now ?? Date.now();
+    if (target === undefined || target === "") {
+        throw new NmtsError("Say which file to extend.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} extend <path>\` — the path as \`${BINARY_NAME} ls\` prints it.`,
+        });
+    }
+    const session = await openSession(options);
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (list.manifest === null) {
+        throw new NmtsError("This account has no file list, so there is nothing to extend.", { exitCode: 4 });
+    }
+    const entries = list.manifest.entries;
+    const entry = entryAt(entries, normalisePath(target), {
+        nothingHappened: "Nothing was signed and nothing was charged.",
+    });
+    if (entry.kind !== KIND_FILE) {
+        throw new NmtsError(`No file at "${fullPathOf(buildIndex(entries), entry)}".`, {
+            exitCode: 4,
+            nextStep: "That is a folder. Nothing was signed and nothing was charged — storage is bought per " +
+                "file, so this takes one file at a time.",
+        });
+    }
+    const path = fullPathOf(buildIndex(entries), entry);
+    // ⛔ THE SERVER SAYS WHICH BLOBS, AND NOTHING ELSE. Its `expiry_epoch` is client-reported and
+    //    advisory; a command that spends money reads the chain's own answer below.
+    const preview = asExtendPreview(await request(session.server, `/v1/items/${encodeURIComponent(entry.id)}/extend-preview`, {
+        token: session.apiKey,
+    }));
+    if (preview.targets.length === 0) {
+        throw new NmtsError(`Nothing on "${path}" can be extended from here.`, {
+            exitCode: 4,
+            nextStep: nothingToExtend(preview),
+        });
+    }
+    const reads = await (options.readChain ?? defaultReads)(session.network);
+    const window = await reads.readWindow();
+    if (window === null) {
+        // ⛔ Not "nothing needs extending". The two look identical from outside and mean opposite things.
+        throw new NmtsError(`The ${session.network} storage network could not be read.`, {
+            exitCode: 1,
+            nextStep: `Nothing was signed and nothing was charged. Which epoch the network is in, and how far ` +
+                `ahead it will sell, are facts only the chain has — this tool will not spend against a ` +
+                `guess. Try again, or name a different Sui node in NMTS_SUI_RPC.`,
+        });
+    }
+    const clock = window.clock;
+    const leases = await reads.readLeases(preview.targets.map((t) => t.objectId));
+    const endEpoch = soonestEnd(leases);
+    if (endEpoch === null) {
+        throw new NmtsError(`The chain holds no storage term for "${path}".`, {
+            exitCode: 4,
+            nextStep: nothingToExtend(preview),
+        });
+    }
+    const stage = stageOf(clock, endEpoch, now);
+    if (stage === "lapsed") {
+        throw new NmtsError(`The storage term for "${path}" has already ended.`, {
+            exitCode: 4,
+            nextStep: `Nothing was signed and nothing was charged. A lease is extended before it ends — once it ` +
+                `is over there is no storage object left to extend, and the bytes may already be gone. ` +
+                `\`${BINARY_NAME} get\` says whether they can still be read.`,
+        });
+    }
+    const epochs = chooseEpochs(options.epochs, headroom(leases, clock.current, window.maxAhead));
+    const newEndEpoch = endEpoch + epochs;
+    const before = daysLeftUntilEpoch(clock, endEpoch, now);
+    const after = daysLeftUntilEpoch(clock, newEndEpoch, now);
+    // ⛔ A COST THAT COULD NOT BE COMPUTED MUST NOT BECOME A COST OF ZERO. `quote` rejects rather
+    //    than defaulting, and that rejection stops this run before the agreement is asked for.
+    const frost = await reads.quote(leases, epochs);
+    const cohort = Math.max(0, ...preview.targets.map((t) => t.sharedItems));
+    const unreachable = preview.treasuryParts + preview.untrackedParts;
+    const facts = {
+        file: path,
+        itemId: entry.id,
+        network: session.network,
+        epoch: clock.current,
+        endEpoch,
+        epochs,
+        newEndEpoch,
+        daysLeft: before,
+        daysLeftAfter: after,
+        blobs: leases.length,
+        priceFrost: frost.toString(),
+        priceWal: coinAmount(frost),
+        paidFrom: "wallet",
+        filesOnTheSameBlobs: cohort,
+        partsThatCannotBeExtended: unreachable,
+    };
+    if (options.dryRun === true) {
+        // ⛔ NOTHING BELOW THIS BRANCH RUNS. No key is derived, no agreement is asked for, and the
+        //    signing module is not even loaded — `--dry-run` is a price and nothing else.
+        if (options.json) {
+            say(JSON.stringify({ ...facts, dryRun: true, signed: false }));
+            return 0;
+        }
+        describe(say, facts, cohort, unreachable);
+        say(``);
+        say(`  Nothing was signed and nothing was charged. Run the same command without --dry-run to`);
+        say(`  buy it.`);
+        if (stage === "later")
+            say(`  It is not near its deadline, so buying it also needs --yes.`);
+        return 0;
+    }
+    if (!options.json)
+        describe(say, facts, cohort, unreachable);
+    // ⛔ ASKED AFTER THE PRICE IS KNOWN AND BEFORE ANYTHING IS SIGNED. Extending early loses nothing,
+    //    so this is not a refusal on principle — it is a refusal to spend on a deadline that is not
+    //    close, unless somebody says otherwise out loud.
+    if (stage === "later" && options.yes !== true) {
+        throw new NmtsError(`"${path}" is not near the end of its storage term.`, {
+            exitCode: 4,
+            nextStep: `Nothing was signed and nothing was charged. Extending early loses nothing — the epochs ` +
+                `are added to what is left — but it spends now for time this file does not need yet. ` +
+                `Add --yes to buy it anyway. \`${BINARY_NAME} expiring\` lists what is actually running out.`,
+        });
+    }
+    // ⛔ THE ONE GATE THAT STANDS BETWEEN A PROGRAM AND SOMEBODY'S WALLET. Everything above this line
+    //    is a read; nothing below it can be undone.
+    requireConsent("wallet");
+    const sign = options.sign ?? (await import("../extend-sign.js")).signExtension;
+    const digest = await sign({
+        network: session.network,
+        code: session.code,
+        objectIds: preview.targets.map((t) => t.objectId),
+        epochs,
+    });
+    // From here the storage IS extended. Recording it is bookkeeping, and a failure to record must
+    // never be reported as a failure to extend — that reading invites a second run, which pays again.
+    let replay = false;
+    try {
+        const recorded = await request(session.server, `/v1/items/${encodeURIComponent(entry.id)}/extended`, { method: "POST", token: session.apiKey, body: { epochs, tx_digest: digest } });
+        replay = isRecord(recorded) && recorded["replay"] === true;
+    }
+    catch (error) {
+        if (options.json) {
+            say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: false }));
+        }
+        else {
+            say(``);
+            say(`  The storage IS extended and the payment has been made — transaction ${digest}.`);
+            say(`  What failed is telling the NMTS server about it, so the drive will go on showing the`);
+            say(`  old date until something tells it. ⛔ Do not run this command again for this file:`);
+            say(`  that would buy the same epochs a second time. Opening the account in a browser reads`);
+            say(`  the chain directly.`);
+            say(`  Cause: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return 1;
+    }
+    if (options.json) {
+        say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: true, replay }));
+        return 0;
+    }
+    say(``);
+    say(`  Extended. The storage now ends at epoch ${newEndEpoch} — ${daysLeftInWords(after)}.`);
+    say(`  Transaction ${digest}`);
+    if (replay) {
+        say(`  The server had already recorded this transaction, so nothing was written twice.`);
+    }
+    return 0;
+}
+/** What the numbers say, for a person, in the order somebody deciding needs them. */
+function describe(say, facts, cohort, unreachable) {
+    const when = (epoch, left) => `epoch ${epoch} — ${daysLeftInWords(left)}`;
+    say(`${facts.file}`);
+    say(`  Storage ends at ${when(facts.endEpoch, facts.daysLeft)}.`);
+    say(`  Extending by ${facts.epochs} epoch${facts.epochs === 1 ? "" : "s"} moves that to ` +
+        `${when(facts.newEndEpoch, facts.daysLeftAfter)}.`);
+    say(`  Price ${facts.priceWal} WAL for ${facts.blobs} stored blob${facts.blobs === 1 ? "" : "s"} — ` +
+        `storage only, because the writing was paid for when the file was uploaded.`);
+    if (cohort > 1) {
+        say(`  ${cohort} of this account's files sit on the storage this pays for, so the same payment ` +
+            `extends all of them.`);
+    }
+    if (unreachable > 0) {
+        say(`  ${unreachable} part${unreachable === 1 ? "" : "s"} of this file cannot be extended from here.`);
+    }
+    say(``);
+    // ⛔ REQUIRED, AND IT COMES BEFORE THE AGREEMENT. Every other purchase in this tool spends
+    //    credits; this one spends assets out of a wallet, and nobody can put them back.
+    say(`  This is paid in WAL from the wallet this account code derives — not from credits, which`);
+    say(`  is what every other command in this tool spends. \`${BINARY_NAME} wallet\` shows what is in it.`);
+}
+/** Why a file has nothing to extend, said as the two different things it can be. */
+function nothingToExtend(preview) {
+    const parts = [];
+    if (preview.treasuryParts > 0) {
+        parts.push(`${preview.treasuryParts} part${preview.treasuryParts === 1 ? " is" : "s are"} on storage NMTS ` +
+            `paid for, which this account cannot extend`);
+    }
+    if (preview.untrackedParts > 0) {
+        parts.push(`${preview.untrackedParts} part${preview.untrackedParts === 1 ? " has" : "s have"} no ` +
+            `recorded storage object, so there is nothing to name on the chain`);
+    }
+    const why = parts.length === 0 ? "The server lists no storage object for it." : `${parts.join(", and ")}.`;
+    return `Nothing was signed and nothing was charged. ${why} Opening the account in a browser shows what it is stored on.`;
+}
+/** The real chain reads. Imported only when no seam was supplied — it loads the storage SDK. */
+async function defaultReads(network) {
+    return (await import("../extend-chain.js")).extendReads(network);
+}

package/dist/commands/get.js

@@ -0,0 +1,130 @@
+// `nmts get <path>` — one file back out, decrypted and checked.
+//
+// ⚠ IT REFUSES RATHER THAN WRITES A HALF-RIGHT FILE. A wrong key, a part that will not decrypt,
+//   parts that do not add up to the file the list describes, or a whole-file hash that does not
+//   match — none of them leave a file behind. A file on disk is a claim that it is the file, and a
+//   partial one makes that claim silently.
+//
+// ⛔ WHICH IS NOW KEPT BY A RENAME, NOT BY BUFFERING. The file is written as it is decrypted, so it
+//   is no longer bounded by memory — a file that can be uploaded can be brought back. The bytes go
+//   to a temporary name in the destination's own directory and are renamed into place only after
+//   the whole-file digest matches; the temporary file is deleted when anything fails. `--out -`
+//   has no rename available and keeps the older bargain instead: see `download-sink.ts`.
+//
+// ⛔ IT WILL NOT OVERWRITE. An agent that re-runs a command should not destroy what the previous
+//   run produced, and neither should a person who forgot the file was there. `--force` is the way
+//   to say otherwise, out loud.
+//
+// ⛔ `--out -` HANDS THE FILE TO WHATEVER IS READING stdout AND WRITES NOTHING. Reading one stored
+//   note should not mean leaving a plaintext copy of it on the disk, which is what this command
+//   made an agent do until now. The refusals above still happen first, and all of them happen
+//   before a byte moves — the file is whole and checked in memory before it is handed over, so a
+//   pipe gets a whole file or gets nothing (`stdout.ts`). That is also why this mode, and only
+//   this mode, still has a size ceiling and says so out loud when a file is over it.
+//
+// ⛔ AND IN THAT MODE EVERYTHING A PERSON READS GOES TO stderr — the summary, the missing-hash
+//   warning and the `--json` line alike, because stdout is now carrying the file and a second
+//   thing on it would be part of the file as far as the reader is concerned.
+import { basename, resolve } from "node:path";
+import { CODE_ENV_VAR } from "../credentials.js";
+import { fetchFile } from "../download.js";
+import { fileSink, stdoutSink } from "../download-sink.js";
+import { buildIndex, entryAt, fullPathOf, KIND_FILE, normalisePath } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { readFileList } from "../manifest.js";
+import { resolveNetwork } from "../network.js";
+import { refuseUnwritableName } from "../safe-path.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { processStdout, STDOUT_TARGET } from "../stdout.js";
+export async function get(target, options = {}) {
+    const toStdout = options.out === STDOUT_TARGET;
+    // ⛔ THE HUMAN LINES MOVE OUT OF THE WAY OF THE FILE. When stdout carries the file, a summary
+    //    line printed there is not a summary line — it is bytes appended to what the reader thinks
+    //    is the file.
+    const say = options.write ?? ((line) => (toStdout ? process.stderr : process.stdout).write(`${line}\n`));
+    if (target === undefined || target === "") {
+        throw new NmtsError("Say which file to get.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} get <path>\` — the path as \`${BINARY_NAME} ls\` prints it.`,
+        });
+    }
+    // ⛔ ONE PLACE RESOLVES THE CREDENTIALS, so the "no API key" refusal — the sentence a new user is
+    //    most likely to see — is one text. This command carried its own copy and had already dropped
+    //    a sentence the other three keep (2026-08-23).
+    const session = await openSession({ server: options.server, network: options.network });
+    const chain = resolveNetwork(session.server, session.network);
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (list.manifest === null) {
+        throw new NmtsError("This account has no file list, so there is nothing to get.", { exitCode: 4 });
+    }
+    // ⛔ ONE LOOKUP, SHARED WITH EVERY OTHER COMMAND. This used to walk the parent chain itself and
+    //    read only `e.deletedAt`, which made it disagree with `ls` about a broken chain and, worse,
+    //    offer a file whose folder had been trashed — the server refuses those bytes
+    //    (2026-08-23).
+    const index = buildIndex(list.manifest.entries);
+    const wanted = normalisePath(target);
+    // ⚠ Looked up WITHOUT a kind filter on purpose: a path that names a folder must be told apart
+    //   from a path that names nothing, and a filtered lookup can only say "nothing is there".
+    const entry = entryAt(list.manifest.entries, wanted, { nothingHappened: "Nothing was written." });
+    if (entry.kind !== KIND_FILE) {
+        throw new NmtsError(`No file at "${fullPathOf(index, entry)}".`, {
+            exitCode: 4,
+            nextStep: "That is a folder. Nothing was written — this version gets one file at a time.",
+        });
+    }
+    if (entry.dekWrapped === undefined) {
+        throw new NmtsError(`The file list holds no key for "${wanted}".`, {
+            exitCode: 4,
+            nextStep: "Without it nothing can open the stored bytes. Open the account in a browser.",
+        });
+    }
+    // ⛔ Only the name that came FROM THE DRIVE is judged. `--out` is the person naming a path on
+    //    their own machine, and they are allowed to mean it.
+    if (!toStdout && options.out === undefined)
+        refuseUnwritableName(basename(entry.name));
+    const destination = toStdout ? null : resolve(options.out ?? basename(entry.name));
+    // ⛔ `--force` has nothing to overwrite on the stdout branch and is ignored there on purpose:
+    //    there is no file to protect, and refusing the combination would only make a wrapper script
+    //    harder to write. On the disk branch the sink refuses an occupied name BEFORE the download,
+    //    which the old code could only do after fetching the whole file.
+    const sink = destination === null
+        ? stdoutSink(options.stdout ?? processStdout())
+        : fileSink(destination, { force: options.force === true });
+    const fetched = await fetchFile({
+        base: session.server,
+        apiKey: session.apiKey,
+        accountCode: session.code,
+        itemId: entry.id,
+        size: entry.size,
+        dekWrapped: entry.dekWrapped,
+        contentHashCt: entry.contentHashCt,
+        chain,
+        sink,
+    });
+    // The reader closed the pipe first. It got what it asked for and stopped; saying anything now
+    // would be writing to a pipe nobody is holding — see `handOver`.
+    if (!fetched.delivered)
+        return 0;
+    if (options.json) {
+        say(JSON.stringify({
+            path: wanted,
+            // ⛔ `-` and not a path, because no path was written. A caller that treats this field as a
+            //    file name would otherwise create one — the exact copy this mode exists to avoid.
+            writtenTo: destination ?? STDOUT_TARGET,
+            bytes: fetched.byteCount,
+            parts: fetched.partCount,
+            contentHashChecked: fetched.contentHashChecked,
+        }));
+        return 0;
+    }
+    say(`${destination ?? "stdout"}  ${fetched.byteCount} bytes  from ${fetched.partCount} stored part${fetched.partCount === 1 ? "" : "s"}`);
+    // ⛔ Said out loud when it is absent. "Verified" and "nothing to verify against" are different
+    //    facts, and only one of them means the bytes were checked.
+    if (!fetched.contentHashChecked) {
+        say(``);
+        say(`  This file has no recorded hash in the file list, so nothing here could check the whole`);
+        say(`  file against one. Every part still decrypted under this account's key.`);
+    }
+    return 0;
+}

package/dist/commands/kit.js

@@ -0,0 +1,136 @@
+// `nmts kit` — the recovery kit: one file that is enough to get everything back.
+//
+// ⛔⛔ IT WRITES THE ACCOUNT CODE IN THE CLEAR. That is the format, decided deliberately: the point
+//    of the kit is that a person needs ONE thing, not two. So whoever holds this file holds the
+//    account and the wallet, and this command says exactly that at the moment it writes — not in a
+//    manual, not on a website. The moment somebody makes this file is the moment that fact
+//    matters, and it is not the moment anybody goes looking for a document.
+//
+// ⛔ IT WRITES NOWHERE BUT THE PATH THE CALLER NAMED. Nothing is copied into this tool's own
+//    directory, nothing is left in a temporary file, nothing is printed to the terminal. A command
+//    that quietly kept a second copy of an account code would be the worst defect in this program.
+//
+// ⛔ AND IT NEVER REPLACES A FILE NOBODY ASKED IT TO REPLACE. A taken name is a refusal unless
+//    `--force` says otherwise — the same rule every other writing command here follows.
+//
+// ⛔ NO PARTIAL KIT. If the recovery list cannot be built, nothing is written and the reason is
+//    printed. The browser has a third state for this — a kit whose text says "the list could not
+//    be made this time" — because it is a screen and can carry that sentence to the person who
+//    just pressed the button. This file's MACHINE block has no field for it: `recovery_list: null`
+//    means "this account had no files", and writing that for a build that failed would state the
+//    opposite of the truth in the one document somebody keeps for the worst day. So it refuses.
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { identityOf } from "../account.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { buildRecoveryKit } from "../kit-file.js";
+import { assembleRecoveryList, recordRecoveryList } from "../recovery-assemble.js";
+export async function kit(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const assembled = await assembleRecoveryList({
+        server: options.server,
+        network: options.network,
+    });
+    const { built, session } = assembled;
+    // The sealed list is embedded as the SAME document `nmts recovery-list` writes out, so the
+    // standalone program reads one shape whichever file it is handed.
+    const parsed = JSON.parse(assembled.file.content);
+    if (!isRecord(parsed)) {
+        throw new NmtsError("The recovery list did not come back as a document.", {
+            exitCode: 1,
+            nextStep: "Nothing was written. This is a fault in the tool rather than in the account.",
+        });
+    }
+    const identity = await identityOf(session.code);
+    const file = buildRecoveryKit({
+        // ⛔ THE GROUPED FORM, which is what a person reads and types back. The kit is the artefact a
+        //    person is told to print or to put in a drawer.
+        code: identity.displayCode,
+        accountId: session.accountId,
+        generatedAt: nowFrom(parsed),
+        // ⚠ AN EMPTY ACCOUNT GETS `null`, WHICH MEANS "there were no files", and that is true here:
+        //   the list was built and it covers nothing. It is NOT the spelling for a build that failed —
+        //   this command refuses instead of reaching this line with an unknown.
+        recoveryList: built.fileCount === 0 ? null : parsed,
+        listFileCount: built.fileCount === 0 ? null : built.fileCount,
+    });
+    const destination = destinationFor(options.out, file.filename);
+    if (options.force !== true && existsSync(destination))
+        throw alreadyThere(destination);
+    try {
+        // ⛔ 0600, AND IT IS NOT A FORMALITY HERE. This file is the account code. On a filesystem that
+        //    cannot keep the mode, this is still the only protection there is to ask for.
+        writeFileSync(destination, file.content, {
+            flag: options.force === true ? "w" : "wx",
+            mode: 0o600,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, "code") === "EEXIST") {
+            throw alreadyThere(destination);
+        }
+        throw error;
+    }
+    // The kit embeds a real recovery list, so the account's record moves with it — `kind: "local"`,
+    // the same fact `nmts recovery-list` reports: a list exists and the person is keeping it.
+    await recordRecoveryList(assembled, destination);
+    if (options.json === true) {
+        say(JSON.stringify({
+            writtenTo: destination,
+            mode: "0600",
+            seq: assembled.seq,
+            files: built.fileCount,
+            // ⛔ THE SENTENCE REACHES A READER THAT ONLY PARSES JSON. An agent that hands this file to
+            //    somebody has to be able to say what it is, in the same words.
+            carries: ["account-code", "recovery-list"],
+            warning: "This file contains the account code in the clear. Anyone who holds it holds the " +
+                "account and the wallet.",
+            missingFromSource: built.missingFromSource,
+        }));
+        return 0;
+    }
+    say(`Wrote ${destination}`);
+    say(``);
+    say(`  ⛔ This file contains your account code in the clear, together with the recovery list`);
+    say(`     for ${built.fileCount} file(s). Anyone who holds it holds this account: every file in`);
+    say(`     it, and the wallet that pays for storage. One account code opens both.`);
+    say(``);
+    say(`  It was written only where you see it, with permissions 0600, and nowhere else.`);
+    say(`  Do not keep it in a folder that syncs or backs up on its own, and do not send it to`);
+    say(`  anyone. A drawer is often safer than a cloud folder.`);
+    if (built.missingFromSource.length > 0) {
+        say(``);
+        say(`  ⚠ ${built.missingFromSource.length} file(s) in your file list are not in the account's`);
+        say(`    stored files, so they are not in this kit.`);
+    }
+    return 0;
+}
+/**
+ * The instant the embedded list was taken, read back out of the document rather than re-stamped.
+ *
+ * ⛔ THE TWO HALVES OF THIS FILE MUST NOT CLAIM DIFFERENT MOMENTS. A person comparing "Created" at
+ *    the top with `generated_at` inside would have no way to tell which one to believe.
+ */
+function nowFrom(mapFile) {
+    const at = mapFile["generated_at"];
+    return typeof at === "string" && at.length > 0 ? at : new Date().toISOString();
+}
+/** Where the file goes: the given file name, inside the given directory, or this directory. */
+function destinationFor(out, filename) {
+    if (out === undefined)
+        return join(process.cwd(), filename);
+    const target = isAbsolute(out) ? out : resolve(process.cwd(), out);
+    // A directory that exists means "put it in here under its own name"; anything else is the name
+    // to write.
+    if (existsSync(target) && statSync(target).isDirectory())
+        return join(target, filename);
+    return target;
+}
+function alreadyThere(destination) {
+    return new NmtsError(`${destination} is already there.`, {
+        exitCode: 4,
+        nextStep: `Nothing was written, and no account code was put anywhere. Pass --out to choose another ` +
+            `name, or --force to replace it.`,
+    });
+}

package/dist/commands/listfile.js

@@ -0,0 +1,105 @@
+// `nmts listfile` — writing this machine's copy of the sealed file list out as a file.
+//
+// ⛔ WHY A COPY IS WORTH ANYTHING. The list is where every file's NAME, folder and KEY live. The
+//    server holds it sealed and cannot read it — and an account whose list the server loses is an
+//    account of nameless, unopenable files, even though every byte is still stored. A copy on
+//    somebody's own disk is the answer to that, and it is the artefact an account used only from a
+//    terminal never had: the browser keeps one and can hand it over, this tool kept two numbers.
+//
+// ⛔ IT ANSWERS FROM THIS MACHINE, AND ASKS NOTHING OF ANYBODY. No API key, no server, no network.
+//    What it writes is the copy kept beside the rollback record, refreshed every time this tool
+//    read a newer list — so the version it hands over is the newest version this machine has seen,
+//    which is a fact it can state exactly rather than a promise about the account.
+//
+// ⛔ WHAT THE FILE IS NOT. It is not a recovery on its own. The storage network's addresses are not
+//    in it — those live in the recovery list a browser writes — and neither is the account code,
+//    deliberately: this file plus the code IS the account, and keeping both together turns one
+//    theft into a total loss. Both facts are printed, and both are inside the file for whoever
+//    finds it later without this text.
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { identityOf } from "../account.js";
+import { requireAccountCode } from "../code-access.js";
+import { NmtsError } from "../errors.js";
+import { buildFileListFile } from "../list-file.js";
+import { readKeptList } from "../manifest.js";
+import { BINARY_NAME } from "../product.js";
+export async function listfile(options = {}) {
+    const toStdout = options.out === "-";
+    // ⛔ WITH `--out -` EVERY LINE FOR A PERSON GOES TO STDERR. The document is then the only thing
+    //    on standard output, so `… --out - > copy.nmtslist` produces a file and not a file with an
+    //    explanation glued to the front of it.
+    const say = options.write ??
+        ((line) => process[toStdout ? "stderr" : "stdout"].write(`${line}\n`));
+    const emit = options.writeDocument ?? ((text) => process.stdout.write(text));
+    const resolved = await requireAccountCode();
+    const identity = await identityOf(resolved.code);
+    const kept = readKeptList(identity.accountId);
+    if (kept === null) {
+        throw new NmtsError(`This machine has no copy of this account's file list.`, {
+            exitCode: 4,
+            nextStep: `Nothing was written. Run \`${BINARY_NAME} ls\` once while this machine can reach the ` +
+                `server: every read of the list keeps its sealed bytes here, and this command writes that ` +
+                `copy out. A copy cannot be made from the account code alone — the list itself is what is ` +
+                `being copied.`,
+        });
+    }
+    const file = buildFileListFile({
+        accountId: identity.accountId,
+        seq: kept.seq,
+        savedAt: kept.savedAt,
+        sealed: kept.ct,
+    });
+    if (toStdout) {
+        emit(file.content);
+        saidWhatItIs(say, kept.seq, kept.savedAt, file.filename);
+        return 0;
+    }
+    const destination = destinationFor(options.out, file.filename);
+    try {
+        // ⛔ `wx` UNLESS TOLD OTHERWISE, and 0600 either way. Replacing a file nobody asked to replace
+        //    is not this command's decision, and the bytes are one account's whole file list.
+        writeFileSync(destination, file.content, { flag: options.force === true ? "w" : "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, "code") === "EEXIST") {
+            throw new NmtsError(`${destination} is already there.`, {
+                exitCode: 4,
+                nextStep: `Nothing was written. Pass --out to choose another name, or --force to replace it.`,
+            });
+        }
+        throw error;
+    }
+    say(`Wrote ${destination}`);
+    saidWhatItIs(say, kept.seq, kept.savedAt, file.filename);
+    return 0;
+}
+/** Where the file goes: the given file name, inside the given directory, or this directory. */
+function destinationFor(out, filename) {
+    if (out === undefined)
+        return join(process.cwd(), filename);
+    const target = isAbsolute(out) ? out : resolve(process.cwd(), out);
+    // A directory that exists means "put it in here under its own name"; anything else is the name
+    // to write. Guessing the other way round would silently rename the artefact whose filename is
+    // how a person tells two copies apart.
+    if (existsSync(target) && statSync(target).isDirectory())
+        return join(target, filename);
+    return target;
+}
+/**
+ * The two sentences that stop this file from being mistaken for a recovery.
+ *
+ * ⛔ SAID ON EVERY RUN, not once in a manual. The moment somebody reaches for this file is the
+ *    moment those two facts matter, and it is not the moment anybody goes looking for a document.
+ */
+function saidWhatItIs(say, seq, savedAt, filename) {
+    say(``);
+    say(`  File list version ${seq}, as this machine last read it (${savedAt}).`);
+    say(`  It holds the names, folders and file keys of this account, sealed with the account code.`);
+    say(``);
+    say(`  ⛔ It is not a recovery on its own. It carries no storage-network addresses — those are in`);
+    say(`     the recovery list saved from the account screen — and it does not contain the account`);
+    say(`     code. Keep it somewhere other than the code: together they are the whole account.`);
+    say(`  ⚠ A copy goes stale. Run this again after uploading: of two copies, the one whose`);
+    say(`    filename carries the higher number supersedes the other (this one is ${filename}).`);
+}