@needmoretruth/nmts-cli 0.17.2

package/dist/help.js

@@ -0,0 +1,192 @@
+// What `nmts` prints when asked what it can do.
+//
+// ⛔ COMMANDS THAT ARE NOT BUILT ARE MARKED, NOT HIDDEN. An agent that discovers a command by
+//    running it and getting "unknown command" learns the wrong thing — it will try synonyms. Being
+//    told the command exists and is unfinished is a fact it can act on: stop, and do not retry.
+import { AGENTS_DOC, BINARY_NAME, HOME_URL, PRODUCT_NAME, SOURCE_URL } from "./product.js";
+import { API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, CODE_ENV_VAR, CODE_FILE_ENV_VAR, PASSPHRASE_ENV_VAR, } from "./credentials.js";
+import { NETWORK_ENV_VAR } from "./network.js";
+import { LATEST_RELEASE_URL, NO_CHECK_ENV_VAR } from "./update-source.js";
+import { SERVER_ENV_VAR } from "./server.js";
+import { AGGREGATOR_ENV_VAR } from "./walrus.js";
+import { CHECK_DOES_NOT_PROVE, CHECK_PROVES, RECOVERY_TOOL_URL, wrapText, } from "./recovery-release.js";
+export function helpText(version) {
+    return [
+        `${PRODUCT_NAME} ${version} — command-line access to end-to-end encrypted NMTS storage.`,
+        ``,
+        `USAGE`,
+        `  ${BINARY_NAME} <command> [options]`,
+        ``,
+        `COMMANDS`,
+        `  login                 Keep an account code on this machine, sealed — and take an API key`,
+        `  logout                Remove the stored account code`,
+        `  whoami                Show which account the stored code belongs to (offline)`,
+        `  create                Make a NEW account. Prints its code once — nothing can print it again`,
+        `  ls                    List files in the account`,
+        `  usage                 What the account holds: counts, bytes, largest files, trash`,
+        `  balance               Credits left, what they buy, and the ceilings on spending`,
+        `  trial                 What is left of this week's free credits. \`trial apply\` asks for some`,
+        `  expiring              List files whose bought storage runs out soon`,
+        `  extend <path>         Buy more storage time for one file — **spends WAL from the wallet**`,
+        `  public-code           The code other accounts send files to. \`--publish\` makes it reachable`,
+        `  wallet                Show the account's wallet address, and its SUI and WAL balances`,
+        `  wallet address        Just the address, derived on this machine — no network call`,
+        `  put <file>            Encrypt one file and upload it, paid with credits`,
+        `  get <path>            Download one file and decrypt it`,
+        `  pull [folder]         Download a whole folder, or the whole account, keeping its shape`,
+        `  push <directory>      Upload a whole directory, keeping its shape — **spends credits**`,
+        `  rm <paths>            Move things to the trash — restorable for 30 days`,
+        `  restore <paths>       Bring things back out of the trash`,
+        `  sweep                 Drop trash entries whose 30 days have run out. Asks first`,
+        `  rebuild               Build a file list from the server's rows, for an account with none`,
+        `  listfile              Write this machine's copy of the sealed file list out as a file`,
+        `  mkdir <path>          Make a folder, and any folder above it that is missing`,
+        `  mv <paths> <folder>   Move things into a folder. \`/\` is the top of the drive`,
+        `  rename <path> <name>  Give one thing a new name`,
+        `  star <files>          Star files — they are gathered in favourites as well`,
+        `  unstar <files>        Take the star off`,
+        `  pin <files>           Hold files at the top of the folder they are in`,
+        `  unpin <files>         Let them fall back into the ordinary order`,
+        `  label <name> <files>  Put one label on files. A label exists while a file wears it`,
+        `  unlabel <name> <files>`,
+        `                        Take one label off files`,
+        `  share <path> <addr>   Give one file to another account. Withdrawing does not recall it`,
+        `  shares                What was shared with this account`,
+        `  receive <id>          Download one file somebody shared with this account`,
+        `  unshare <id>          Withdraw a share you sent, or remove one you were sent`,
+        `  env                   What this machine is, and what it means for the account code`,
+        `  consent               See what this machine has agreed to, and change it`,
+        `  mode                  How much an agent driving this tool may decide without asking`,
+        `  on-collision          What to do when an upload's name is already in use`,
+        `  update                Install the newest published release of this tool`,
+        `  recovery              Download the standalone program that reads files back without NMTS`,
+        `  recovery-list         Write the file that finds your bytes without NMTS. Holds no code`,
+        `  kit                   Recovery kit: that list AND your account code, together in one file`,
+        `  verify                Ask a person to pass the check that opens this account's limits`,
+        `  mcp                   Serve this account's commands as tools, for an agent that speaks MCP`,
+        `  s3                    Serve the drive to any S3 program, on this machine only`,
+        ``,
+        `OPTIONS`,
+        `  --server <url>        NMTS server (default ${SERVER_ENV_VAR} or the live one)`,
+        `  --network <name>      mainnet or testnet. Required for any server but the live one`,
+        `  --json                Machine-readable output (ls, usage, get, put, env, verify,`,
+        `                        expiring, sweep, rebuild, pull, wallet, shares, share, receive,`,
+        `                        recovery, balance, trial, extend, recovery-list, kit, update,`,
+        `                        create — create needs --out as well, so the code never enters`,
+        `                        the output)`,
+        `  --all                 Include what is in the trash (ls)`,
+        `  --find <text>         List only the files whose name contains this text (ls). Folders`,
+        `                        appear only where they hold a match`,
+        `  --sort <key>          name, size or date. Default: whole paths, ascending (ls)`,
+        `  --desc                Reverse whichever order is in effect (ls)`,
+        `  --hidden              Include entries whose name begins with a dot (push)`,
+        `  --out <path>          Where to write files (get, pull, mcp, listfile, recovery,`,
+        `                        recovery-list, kit, create). Default: here`,
+        `  --out -               Send a fetched file to stdout instead of writing it (get, listfile)`,
+        `  --force               Replace a file that is already there (get, pull, listfile,`,
+        `                        recovery, recovery-list, kit), or rebuild an account this machine`,
+        `                        has seen a list for (rebuild). \`create\` never replaces a file`,
+        `  --name <name>         The name the uploaded file gets in the drive (put)`,
+        `  --to <folder>         Destination folder, as \`${BINARY_NAME} ls\` prints it (put, push)`,
+        `  --dry-run             Say what it would cost, and stop (put, push, extend), or what it`,
+        `                        would install, and stop (update). With \`extend\` nothing is`,
+        `                        signed and the wallet key is never touched`,
+        `  --part-size <n>       Bytes per part for a large upload (put, push). Default 64MiB.`,
+        `  --on-collision <what> rename | overwrite, for THIS run only (put, push). Without it the`,
+        `                        machine's own setting decides -- see \`${BINARY_NAME} on-collision\`.`,
+        `                        a plain number, or one with KiB, MiB or GiB. Bigger parts mean`,
+        `                        fewer purchases; smaller parts use less memory`,
+        `  --yes                 Go ahead with something that cannot be taken back (sweep, rebuild),`,
+        `                        or extend a file that is nowhere near its deadline (extend)`,
+        `  --epochs <n>          How many of the storage network's epochs to add (extend)`,
+        `  --port <n>            Which loopback port to listen on (s3). Default 9000`,
+        `  --accept-terms <v>    The version of the Terms of Service a PERSON read and accepts for`,
+        `                        the new account (create). A version, never "the current one"`,
+        `  --accept-privacy <v>  The version of the Privacy Policy accepted in the same act (create)`,
+        `  --publish             Publish this account's public code (public-code). Permanent —`,
+        `                        it cannot be withdrawn or changed afterwards`,
+        `  --status              Say whether the check is live, and stop (verify)`,
+        `  --plain               Store the code unsealed instead (login). Asks for an agreement`,
+        `  --env                 Store nothing; print the variable to set (login). Same agreement`,
+        `  --version             Print the version and exit`,
+        `  --help                Print this and exit`,
+        ``,
+        `ENVIRONMENT`,
+        `  ${CODE_FILE_ENV_VAR.padEnd(24)}Names a FILE holding the account code. The recommended way, and`,
+        `                          the only one that asks nothing: the file is read, never copied.`,
+        `  ${CODE_ENV_VAR.padEnd(24)}The account code itself. Takes precedence over anything stored,`,
+        `                          and asks once — an environment variable is readable through`,
+        `                          \`docker inspect\`, /proc/<pid>/environ and most CI logs.`,
+        `  ${PASSPHRASE_ENV_VAR.padEnd(24)}Opens a sealed stored code without a terminal.`,
+        `  ${API_KEY_FILE_ENV_VAR.padEnd(24)}Names a FILE holding the API key. \`${BINARY_NAME} login\` reads this`,
+        `                          first, and a container cannot leak it the way it leaks a value.`,
+        `  ${API_KEY_ENV_VAR.padEnd(24)}Key made on the account screen. It waives the human check a`,
+        `                          browser sign-in does, and nothing else — it opens no file.`,
+        `                          \`${BINARY_NAME} login\` checks one it finds here with the server and`,
+        `                          then stores it, so it outlives the terminal it was set in.`,
+        `  ${SERVER_ENV_VAR.padEnd(24)}Server to talk to. For development stacks.`,
+        `  ${AGGREGATOR_ENV_VAR.padEnd(24)}Storage-network read hosts, comma-separated. Replaces`,
+        `                          the built-in list rather than adding to it.`,
+        `  ${NETWORK_ENV_VAR.padEnd(24)}mainnet or testnet. Never guessed: a wrong one looks in a place`,
+        `                          your files were never stored.`,
+        `  ${NO_CHECK_ENV_VAR.padEnd(24)}Set to anything to stop the version check described below.`,
+        ``,
+        // ⛔ THE TWO SENTENCES ABOUT THE CHECK ARE IMPORTED, NOT RETYPED. They are also printed by
+        //    the command itself, and a second copy is how one of them starts promising more than the
+        //    other. What is added here is the other half of the same honesty: where the file goes.
+        `THE RECOVERY PROGRAM`,
+        `  \`${BINARY_NAME} recovery\` downloads one executable for this machine from the releases at`,
+        ``,
+        `    ${RECOVERY_TOOL_URL}`,
+        ``,
+        ...wrapText(CHECK_PROVES).map((line) => `  ${line}`),
+        ...wrapText(CHECK_DOES_NOT_PROVE).map((line) => `  ${line}`),
+        ``,
+        `  It writes one file where you point it, refuses a name that is already taken unless you`,
+        `  pass --force, and installs nothing: no copy goes onto your PATH.`,
+        ``,
+        // ⛔ IT IS WRITTEN DOWN BECAUSE IT IS THE ONLY REQUEST THIS TOOL MAKES THAT NOBODY ASKED FOR.
+        //    Everything else it sends goes to the NMTS server or the storage network because a command
+        //    needed it. This one goes to a third host, on its own, and a tool that does that without
+        //    saying so is one whose network behaviour has to be found out with a packet capture.
+        `THE VERSION CHECK`,
+        `  Once a day, after a command has finished, this asks which release of this tool is newest:`,
+        ``,
+        `    ${LATEST_RELEASE_URL}`,
+        ``,
+        `  and writes the answer down. When it is newer than the one running, the NEXT run prints one`,
+        `  line on stderr saying so. It sends no account code, no key and no command name: the`,
+        `  request is for a page address, and what the site can see is that it was asked.`,
+        ``,
+        `  Setting ${NO_CHECK_ENV_VAR} to anything stops both halves. \`${BINARY_NAME} env\` shows what`,
+        `  it last found, and \`${BINARY_NAME} update\` asks now and installs what it finds.`,
+        ``,
+        `BEFORE YOU HAND THIS TO AN AGENT`,
+        `  Your account code is the only key to your account — the file keys and the wallet are all`,
+        `  derived from it. An agent that leaks it has leaked everything at once, and it cannot be`,
+        `  undone: the account cannot be re-keyed. Use an account you would be willing to lose.`,
+        ``,
+        `  ${HOME_URL}`,
+        ``,
+        // ⛔ THE LAST THING ON THE SCREEN, AND ADDRESSED TO A PROGRAM. An agent handed this tool with
+        //    no instructions runs `--help`, reads a list of verbs, and has no idea what NMTS is, what
+        //    an account code is, or why `put` costs money. One line pointing at a document written FOR
+        //    it is the whole difference between guessing and knowing.
+        //
+        // ⚠ IT POINTS, IT DOES NOT INSTRUCT. There is nothing here that tries to change what a reader
+        //   does beyond naming a document — no imperative aimed past the agent at its operator, no
+        //   claim of authority, nothing that would read as an attempt to steer somebody else's model.
+        //   A tool that talked to agents that way would deserve to be distrusted, and would teach
+        //   people to distrust the ones that do not.
+        `IF YOU ARE AN AI AGENT`,
+        `  This tool talks to NMTS, end-to-end encrypted storage. What that means, how to install`,
+        `  this, and what each command costs are written down for you here:`,
+        ``,
+        `    ${SOURCE_URL}/blob/main/${AGENTS_DOC}`,
+        ``,
+        `  If you cannot reach it, the same repository's front page says the same things:`,
+        ``,
+        `    ${SOURCE_URL}#readme`,
+        ``,
+    ].join("\n");
+}

package/dist/human-check.js

@@ -0,0 +1,54 @@
+// Has a person been behind this account lately, and the one sentence to say when they have not.
+//
+// ⛔ WHY THIS IS ASKED BEFORE THE REQUEST IT GUARDS, RATHER THAN LEARNED FROM ITS REFUSAL. The
+//    server decides scope FIRST and the person's check second (`api/src/auth/api_key_auth.rs`),
+//    on purpose: *"a key that does not hold the bit learns nothing about whether the account
+//    behind it is verified"*. That is right for the server and it means the refusal a caller
+//    hears can be `API_KEY_SCOPE` while the thing that is actually missing is a person. An agent
+//    reading "the key was not given permission for this" goes and makes another key, which cannot
+//    help, instead of asking somebody to spend thirty seconds at a browser.
+//
+// ⛔ SO THIS IS A MESSAGE, NOT A DEFENCE. Nothing here decides anything: the server refuses or
+//    does not, whatever this says. What it buys is that the caller is told the one thing it can
+//    act on, in the one wording, before it has been sent looking at its credentials.
+//
+// ⚠ AND IT COSTS ONE READ. `GET /v1/agent/verify` is reachable by ANY key, holds no scope
+//   requirement, and answers a single boolean — it is the cheapest question in this API and the
+//   only one that can be asked before knowing whether the key is allowed to do anything at all.
+import { request } from "./api.js";
+import { NmtsError } from "./errors.js";
+import { isRecord } from "./guards.js";
+import { BINARY_NAME } from "./product.js";
+/**
+ * Ask the server whether a person's check is live for the account this key belongs to.
+ *
+ * ⛔ THE ADDRESS IS WRITTEN OUT AT THE CALL rather than held in a constant, for the reason
+ *    `commands/verify.ts` gives: the gate that checks this tool's addresses against the server's
+ *    own routes reads the literal in the call, and a constant would make it stop looking here.
+ */
+export async function humanCheck(server, apiKey) {
+    const answer = await request(server, "/v1/agent/verify", { token: apiKey });
+    if (!isRecord(answer) || typeof answer["verified"] !== "boolean") {
+        throw new NmtsError("The server's answer did not say whether this account is verified.", {
+            exitCode: 1,
+            nextStep: `This version of \`${BINARY_NAME}\` and that server do not agree about this. Update the tool, or check --server.`,
+        });
+    }
+    const until = answer["verified_until"];
+    return { live: answer["verified"], until: typeof until === "string" ? until : null };
+}
+/**
+ * The one refusal for "a person has to do something first".
+ *
+ * ⛔ IT NAMES THE COMMAND AND SAYS WHO HAS TO RUN IT. `verify` prints a short code and waits; the
+ *    typing is a person's, at a browser, and no amount of retrying here replaces it. Saying only
+ *    "refused" would send an agent round the loop of credentials it already has.
+ */
+export function askAPersonToVerify(whatIsRefused) {
+    return new NmtsError(`${whatIsRefused} until somebody passes this account's human check.`, {
+        exitCode: 4,
+        nextStep: `Run \`${BINARY_NAME} verify\`. It prints a short code and an address; a person opens that ` +
+            `address, types the code, and this account's limits are lifted for four of the server's ` +
+            `weeks. Nothing on this machine can pass that check — being unable to is what it measures.`,
+    });
+}

package/dist/item-trash.js

@@ -0,0 +1,25 @@
+// Move one item into the trash on the server, or bring it back.
+//
+// ⛔ 404 IS "ALREADY IN THE STATE YOU ASKED FOR", which is what a half-finished run leaves behind.
+//    Treating it as a failure would make the retry of an interrupted command impossible -- the one
+//    moment the retry is needed.
+//
+// ⛔ AND THIS IS AS FAR AS AN API KEY REACHES. `POST /v1/items/erase` -- the one that destroys a
+//    row for good -- is closed to keys and stays closed (`api` domain/agent_routes.rs, Reach::Never:
+//    "PERMANENT destruction. The soft delete is reachable because it is recoverable; this is the
+//    line where that stops."). Anything in this tool that says a file is gone forever is wrong.
+import { request, ServerError } from "./api.js";
+export async function setTrashed(base, apiKey, id, trashed) {
+    const held = encodeURIComponent(id);
+    try {
+        if (trashed)
+            await request(base, `/v1/items/${held}`, { method: "DELETE", token: apiKey });
+        else
+            await request(base, `/v1/items/${held}/restore`, { method: "POST", token: apiKey, body: {} });
+    }
+    catch (error) {
+        if (error instanceof ServerError && error.status === 404)
+            return;
+        throw error;
+    }
+}

package/dist/kit-file.js

@@ -0,0 +1,133 @@
+// The RECOVERY KIT — the one file that carries everything, account code included.
+//
+// ⛔⛔ IT HOLDS THE ACCOUNT CODE IN THE CLEAR, AND THAT IS THE FORMAT. It was decided deliberately
+//    and against the earlier rule, by the owner, with the cost stated: whoever holds this file
+//    holds the account AND the wallet, because one code derives both. The two artefacts therefore
+//    mean two different things and every screen and every command must say which is which:
+//      · recovery LIST — sealed. Worthless to a thief. The account code opens it.
+//      · recovery KIT  — everything. One stolen file is a total loss.
+//    The warning is not a formality; it is what makes the choice an honest one to offer.
+//
+// ⛔ THERE IS NO SPECIFICATION FOR THIS FORMAT. Its only authorities are the two programs that
+//    already write and read it: `web/src/lib/auth/recovery-kit.ts` (writer) and
+//    `recovery/src/kitfile.rs` (reader). The shape below was read off BOTH.
+//    ⚠ WHERE THEY DIFFER: the reader requires only `format`, `version` and `account_id`, treats
+//      `account_code` and `recovery_list` as optional, and reads nothing else — no
+//      `generated_at`, no `account_fingerprint`, no `recovery_manifest_blob`, no `about`. The
+//      writer always emits all of them. That is not a contradiction, it is the reader being
+//      deliberately lenient (it sets no `deny_unknown_fields`), and it is why adding a field never
+//      moved the kit version. This writer emits the writer's full set.
+//
+// ⛔ THE MACHINE BLOCK IS DELIMITED BY FIXED ASCII, NEVER BY THE HEADING ABOVE IT. The headings are
+//    written in whatever language the person was using; a parser that looked for one would work in
+//    one language and fail in another — on the day somebody is recovering, which is the only day
+//    it matters.
+//
+// ⚠ THE HUMAN HALF IS ENGLISH ONLY, and the browser's is bilingual. The English sentences below
+//   are the site's own, word for word (`RecoveryKit.*` in `web/src/messages/en.json`), so the two
+//   programs do not describe one artefact differently; the Korean half lives in message bundles
+//   this package does not import, and inventing a translation here would be worse than the gap.
+//   `cli/src/list-file.ts` set that precedent for the sibling artefact.
+import { createHash } from "node:crypto";
+import { artifactAbout } from "./artifact-about.js";
+import { RECOVERY_TOOL_URL } from "./recovery-release.js";
+/** Start of the machine block. ⛔ Fixed bytes, never translated. */
+export const KIT_DATA_BEGIN = "--- BEGIN NMTS RECOVERY KIT DATA ---";
+/** End of the machine block. */
+export const KIT_DATA_END = "--- END NMTS RECOVERY KIT DATA ---";
+/** The marker a reader matches on before anything else is attempted. */
+export const KIT_FORMAT = "nmts-recovery-kit";
+/**
+ * Kit version. 2 is the one that carries the recovery list; v1 carried only the code.
+ *
+ * ⛔ NOT RAISED FOR ANYTHING THIS TOOL ADDS. `MAX_KIT_VERSION` in the standalone program refuses a
+ *    higher number outright, so a bump breaks every published build in exchange for fields those
+ *    builds are happy to ignore.
+ */
+export const KIT_VERSION = 2;
+/**
+ * A short, human-checkable fingerprint of the PUBLIC account id.
+ *
+ * ⚠ RESTATED FROM `web/src/lib/auth/account-code.ts::accountIdFingerprint`, which this package
+ *   cannot import. It has to produce the same string: a person comparing a kit written here with
+ *   one written in a browser is checking two spellings of the same account.
+ *
+ * ⛔ IT FINGERPRINTS THE ACCOUNT ID, WHICH IS PUBLIC — never the account code and never a key. It
+ *    lets somebody confirm two files refer to one account without either of them exposing a secret.
+ */
+export function accountIdFingerprint(accountId) {
+    const hex = createHash("sha256")
+        .update(accountId, "utf8")
+        .digest("hex")
+        .slice(0, 16)
+        .toUpperCase();
+    // Grouped 4 by 4 for reading aloud: "AB12-CD34-EF56-7890".
+    return hex.replace(/(.{4})(?=.)/g, "$1-");
+}
+/** Build the kit's text: a part for a person, then a part for a program. */
+export function buildRecoveryKit(input) {
+    const data = {
+        format: KIT_FORMAT,
+        version: KIT_VERSION,
+        generated_at: input.generatedAt,
+        account_id: input.accountId,
+        account_fingerprint: accountIdFingerprint(input.accountId),
+        account_code: input.code,
+        // ⛔ ALWAYS NULL HERE. That field names a copy of the list on the storage network, and this
+        //    tool writes no such copy — a value would be an address nothing was ever written to.
+        recovery_manifest_blob: null,
+        recovery_list: input.recoveryList,
+        about: artifactAbout("recovery-kit"),
+    };
+    const lines = [
+        `# NMTS Recovery Kit`,
+        `Created: ${input.generatedAt}`,
+        ``,
+        // ⛔ THE THEFT WARNING COMES FIRST, ABOVE THE CODE IT IS ABOUT. A caution printed underneath
+        //    the thing it cautions about has already been disregarded by the time it is read.
+        `⛔ Anyone who holds this file holds this account: every file in it, and the wallet that pays ` +
+            `for storage. One account code opens both.`,
+        `Do not keep it in a folder that syncs or backs up on its own, and do not send it to anyone. ` +
+            `A drawer is often safer than a cloud folder.`,
+        ``,
+        `This file is the only way to recover your NMTS files. Keep it private.`,
+        `This file carries your account code in the clear, your account identifier and fingerprint, ` +
+            `and the whole recovery list.`,
+        `Anyone with this code can open your files. If you lose it, no one — including NMTS — can ` +
+            `recover them.`,
+        ``,
+        `Account code:`,
+        `    ${input.code}`,
+        ``,
+        `Account identifier: ${data.account_id}`,
+        `Fingerprint: ${data.account_fingerprint}`,
+        `Recovery manifest blob: not yet created`,
+        `Recovery list: ${input.recoveryList === null
+            ? `not included — this account had no files when the kit was made`
+            : `included in this file (${input.listFileCount ?? 0} files)`}`,
+        ``,
+        `--- HOW TO GET YOUR FILES BACK (English) ---`,
+        `1. Get the recovery program from ${RECOVERY_TOOL_URL} — it runs on Linux, macOS and ` +
+            `Windows, and its full source is there.`,
+        `2. Open a terminal where you saved the program, and run:`,
+        `       nmts-recovery --map <this file> --out <a folder to write into>`,
+        `   It takes the account code and the file list out of this file, fetches your files from ` +
+            `public Walrus storage, checks every piece, and writes them out.`,
+        `3. To click instead of typing, run:  nmts-recovery --gui`,
+        `   That opens a page only this machine can reach. The program still does the work; the page ` +
+            `only shows the list and sends back what you ticked.`,
+        `4. To see what your account code derives — your public code and your wallet addresses — ` +
+            `run:  nmts-recovery --derive`,
+        `If you would rather it opened no network connections, run it with --print-fetch-plan: it ` +
+            `prints the exact addresses to fetch by hand, then restores from the folder you filled.`,
+        ``,
+        `--- FOR A PROGRAM ---`,
+        KIT_DATA_BEGIN,
+        JSON.stringify(data, null, 2),
+        KIT_DATA_END,
+        ``,
+    ];
+    // A short id slug keeps filenames distinct without printing the whole account id.
+    const slug = input.accountId.replace(/[^A-Za-z0-9]/g, "").slice(0, 8) || "account";
+    return { filename: `nmts-recovery-kit-${slug}.txt`, content: lines.join("\n") };
+}

package/dist/list-file.js

@@ -0,0 +1,71 @@
+// The sealed file list as a FILE somebody keeps — the same wrapper the browser hands out.
+//
+// ⛔ ONE FORMAT, NOT TWO. `format`, `version` and the `.nmtslist` extension are what a reader
+//    matches on, and a person recovering an account may hold copies written by a browser and by
+//    this command months apart. A second spelling of the same artefact would mean whoever helps
+//    them has two formats to work out instead of one, at the worst possible moment. Everything in
+//    the document below is therefore the browser's, byte for byte, with the two exceptions named
+//    at the bottom of this comment.
+//
+// ⛔ NOTHING SECRET IN THE HEADER, AND THAT INCLUDES SIZES. The plaintext part of this file says
+//    what the file IS — never what is inside it, not a file name, not a count, not a total. The
+//    contents are one sealed envelope that opens with the account code and nothing else, so a
+//    stranger who finds this learns which account it belongs to and no more.
+//
+// ⛔ THE ACCOUNT CODE IS NOT IN IT, and that is not an oversight to fix later. This file plus the
+//    code is the account; keeping both in one place would make one theft into a total loss.
+//
+// ⚠ WHAT DIFFERS FROM THE BROWSER'S COPY, and neither is a format difference:
+//    · The finder's note is English only. The browser ships it in English and Korean because it
+//      cannot know which language the person who finds the file years later reads; this package
+//      ships English strings only, and inventing a translation here would be worse than the gap.
+//    · `about.app_version` names THIS PROGRAM and its version rather than the site release. It is
+//      the field's own contract — a claim the writer makes about itself — and a person holding two
+//      copies of one account's list can then tell which program wrote each.
+import { artifactAbout, WRITTEN_BY } from "./artifact-about.js";
+/** Wrapper format identifier, distinct from the recovery list's. */
+export const LIST_FILE_FORMAT = "nmts-file-list";
+/** The shell's version. Not the file list's own version, which is `seq`. */
+export const LIST_FILE_VERSION = 1;
+/** Filename extension. Deliberately not the recovery list's: the two must not be confusable. */
+export const LIST_FILE_EXTENSION = "nmtslist";
+// ⚠ THE HEADER BLOCK IS NOT SPELLED HERE. Three artefacts carry the same one — this file, the
+//   recovery list and the recovery kit — and it is built in `artifact-about.ts` so that a renamed
+//   program or a moved document reaches all three. `WRITTEN_BY` is re-exported because it is the
+//   value this wrapper puts in `app_version`, and a test reads it from here.
+export { WRITTEN_BY };
+/** Plain-language lines for whoever finds this file with no idea what it is. */
+const NOTE = [
+    `This file is an encrypted copy of an NMTS (nmts.me) file list — the names, folders and file ` +
+        `keys of one account, locked with its account code.`,
+    `It is written by the \`nmts\` command from the copy that machine keeps. A higher number in the ` +
+        `filename is a newer copy.`,
+    `It does not replace the recovery list: storage-network addresses live only in the recovery ` +
+        `list. Keep both, somewhere other than the account code.`,
+];
+/**
+ * Build the document and the name to offer it under.
+ *
+ * Pure on purpose: it touches no disk and no clock, so what it produces can be compared against
+ * the format itself rather than against whatever the machine running it happened to be doing.
+ *
+ * ⚠ THE VERSION IS IN THE FILENAME, ZERO-PADDED, so a folder holding several copies sorts into
+ *   the order they were written and the newest is the last one.
+ */
+export function buildFileListFile(input) {
+    const doc = {
+        format: LIST_FILE_FORMAT,
+        version: LIST_FILE_VERSION,
+        seq: input.seq,
+        ...(input.savedAt === undefined ? {} : { saved_at: input.savedAt }),
+        account_id: input.accountId,
+        sealed: input.sealed,
+        note: [...NOTE],
+        about: artifactAbout("file-list"),
+    };
+    const slug = input.accountId.replace(/[^A-Za-z0-9]/g, "").slice(0, 8) || "account";
+    return {
+        filename: `nmts-file-list-${slug}-${String(input.seq).padStart(4, "0")}.${LIST_FILE_EXTENSION}`,
+        content: `${JSON.stringify(doc, null, 2)}\n`,
+    };
+}

package/dist/list-view-find.js

@@ -0,0 +1,71 @@
+// `--find` — which entries a name query leaves in the listing.
+//
+// ⛔ THE QUERY NAMES FILES. A folder is never matched by it, and a folder whose own name contains
+//    the text is not a result. Somebody searching for `report` wants the files called report, and
+//    a listing that also printed an empty folder called `reports` would be answering a question
+//    nobody asked — worse, it would print a row with nothing under it and no way to tell whether
+//    the folder is empty or whether its contents were filtered away.
+//
+// ⛔ BUT A MATCH KEEPS ITS FOLDERS. `ls` prints whole paths, and the folders on the way to a match
+//    are part of what that path means; dropping them would leave the listing describing a drive
+//    whose shape is not this account's. So the entries that survive are: every file that matches,
+//    plus every folder between one of those files and the top of the drive.
+//
+// ⛔ WHICH MEANS: UNDER A QUERY, A FOLDER HOLDING NO MATCH IS NOT PRINTED — an empty folder never
+//    is, and neither is a full one whose files all fail the query. That omission is deliberate and
+//    it is SAID OUT LOUD by the listing that made it, because a filtered listing that looks like a
+//    full one is exactly how somebody concludes a folder was lost.
+//
+// ⚠ FOLDING, NOT BYTES. Both sides are lowercased through the locale before comparing, which is
+//   what makes the search case-insensitive in the alphabets that have cases and harmless in the
+//   ones that do not. The stored name is never touched: it belongs to whoever wrote it.
+import { KIND_FOLDER } from "./drive-paths.js";
+/** The text to look for, folded. Empty means the option carried nothing to search on. */
+export function needleOf(query) {
+    return query.trim().toLocaleLowerCase();
+}
+/** Does this name contain the (already folded) needle? */
+export function nameContains(name, needle) {
+    return name.toLocaleLowerCase().includes(needle);
+}
+/**
+ * Walk from an entry to the top of the drive, marking every folder on the way as one to keep.
+ *
+ * ⚠ The `seen` set is not defensive tidiness. A list where two folders are each other's parent
+ *   would loop here forever, and a list is a document that can be rebuilt by any device and any
+ *   older build of any of them.
+ */
+function keepAncestors(index, entry, keep) {
+    const seen = new Set([entry.id]);
+    let parentId = entry.parentId;
+    while (parentId !== null && !seen.has(parentId)) {
+        seen.add(parentId);
+        const parent = index.byId.get(parentId);
+        // A broken chain simply stops: the file is printed with the detached mark its path already
+        // carries, and nothing above the break is invented.
+        if (parent === undefined)
+            return;
+        keep.add(parent.id);
+        parentId = parent.parentId;
+    }
+}
+/**
+ * The ids to print for one query: the matching files, and the folders that lead to them.
+ *
+ * `entries` is what the listing was going to show anyway — live only, or everything under `--all`
+ * — and the ancestors added here are inside that same set by construction. Being in the trash is
+ * INHERITED, so a live file cannot sit under a trashed folder, and with `--all` there is nothing
+ * left to be outside the set.
+ */
+export function idsForQuery(index, entries, needle) {
+    const keep = new Set();
+    for (const entry of entries) {
+        if (entry.kind === KIND_FOLDER)
+            continue;
+        if (!nameContains(entry.name, needle))
+            continue;
+        keep.add(entry.id);
+        keepAncestors(index, entry, keep);
+    }
+    return keep;
+}

package/dist/list-view-order.js

@@ -0,0 +1,96 @@
+// The order a listing comes out in — the browser drive's rule, written out again here.
+//
+// ⛔ IT IS A TRANSCRIPTION, AND THAT IS THE WHOLE POINT. One account is read in a browser and from
+//    this tool, often minutes apart. If `--sort size` here and the size order there disagreed
+//    about two files of equal size, or about where folders sit, somebody comparing the two screens
+//    has no way to tell which of them is lying about their own drive — both are complete, exact
+//    listings of the same sealed list. So the rules below are the ones the NMTS web drive sorts
+//    by, transcribed in full.
+//
+// ⛔ TRANSCRIBED RATHER THAN IMPORTED. Nothing in this package reads the browser tree: that tree
+//    is React-bound and built by a different toolchain, and this tool has to keep running when it
+//    is packaged on its own. What holds the two together is that the rule is small enough to write
+//    down completely — which is what the block below does.
+//
+// WHAT THE RULE IS, IN FULL:
+//   1. Names compare with the machine's own locale and NUMERIC collation, so `photo 2` comes
+//      before `photo 10`. Plain text order puts 10 first, which reads as a defect to anybody who
+//      has ever numbered files.
+//   2. A tie on size or date falls back to the name, so two runs over one unchanged list print the
+//      same order rather than wobbling.
+//   3. Descending is the EXACT REVERSE of ascending — the tie-break included, and not the
+//      comparator with its sign flipped. Flipping the sign would leave the name tie-break running
+//      upwards inside a downwards list, so reversing the sort would leave the tied rows sitting in
+//      the order they were already in.
+//   4. Folders are their own group, above the files, whichever way the sort runs. The browser
+//      draws them as a separate section above the file list; a flat listing has no sections, so
+//      the group order is what carries that promise across.
+//   5. Rows carrying the pinned mark are lifted to the top of their group afterwards, keeping the
+//      order the sort gave them. That is the only thing pinning is for, and it has to hold under
+//      every key and both directions or it means nothing.
+//
+// ⚠ A FOLDER HAS NO SIZE OF ITS OWN — the sealed list stores 0 — so sorting folders by size sorts
+//   them by name. That is the honest outcome rather than a gap: a folder's weight is known only by
+//   walking it, and inventing one to sort by would be a fabricated number in a column of measured
+//   ones.
+//
+// ⚠ ONE DIFFERENCE THAT IS NOT A DIFFERENCE. The browser compares an RFC3339 string; the sealed
+//   list holds milliseconds and this compares those. They order the same instants — the string
+//   form is zero-padded and in UTC, so text order is chronological order — and they tie on the
+//   same rows, because equal milliseconds render as one equal string.
+import { KIND_FOLDER } from "./drive-paths.js";
+import { NmtsError } from "./errors.js";
+/** What `--sort` accepts, in the order the help text names them. */
+export const SORT_KEYS = ["name", "size", "date"];
+/**
+ * One of the three keys, or the refusal that names all three.
+ *
+ * ⛔ IT IS CHECKED BEFORE ANYTHING IS FETCHED. A misspelled key is a wrong command line, not a
+ *    failing account, and an agent that read "could not list your files" after typing `--sort
+ *    largest` would go looking at the account. Exit 2 says the same thing every other bad option
+ *    in this tool says.
+ */
+export function parseSortKey(input) {
+    // Compared rather than asserted: the compiler checks that every key in the list is a SortKey,
+    // which a cast from `string` would not.
+    for (const key of SORT_KEYS)
+        if (key === input)
+            return key;
+    throw new NmtsError(`"${input}" is not something this can sort by.`, {
+        exitCode: 2,
+        nextStep: `Nothing was listed. Sort by one of: ${SORT_KEYS.join(", ")}.`,
+    });
+}
+function byName(a, b) {
+    return a.name.localeCompare(b.name, undefined, { numeric: true });
+}
+function comparatorFor(sort) {
+    if (sort === "size")
+        return (a, b) => a.size - b.size || byName(a, b);
+    if (sort === "date")
+        return (a, b) => a.createdAt - b.createdAt || byName(a, b);
+    return byName;
+}
+/** One group — folders, or files — ordered, reversed if asked, then the pinned rows lifted. */
+function orderGroup(rows, sort, dir) {
+    const sorted = [...rows].sort(comparatorFor(sort));
+    const ordered = dir === "desc" ? sorted.reverse() : sorted;
+    if (!ordered.some((row) => row.pinned === true))
+        return ordered;
+    return [
+        ...ordered.filter((row) => row.pinned === true),
+        ...ordered.filter((row) => row.pinned !== true),
+    ];
+}
+/**
+ * Rows in the browser's order: folders first, then files, each group by the chosen key.
+ *
+ * The input array is left alone — a caller printing one order and counting over another would
+ * otherwise depend on which of the two ran first.
+ */
+export function orderRows(rows, sort, dir) {
+    return [
+        ...orderGroup(rows.filter((row) => row.kind === KIND_FOLDER), sort, dir),
+        ...orderGroup(rows.filter((row) => row.kind !== KIND_FOLDER), sort, dir),
+    ];
+}