@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/help.js

@@ -3,7 +3,12 @@
 // ⛔ 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 { AGENTS_DOC, BINARY_NAME, HOME_URL, PRODUCT_NAME, SOURCE_URL, VERSION } from "./product.js";
+// ⛔ THE COPY IS IMPORTED, NOT RETYPED. The same sentences are printed by `nmts support --help`
+//    and above every preview, and what they promise is what is taken out of a message before it
+//    leaves — not a promise to keep in two versions. ⚠ That module has no imports of its own, so
+//    reading it here costs `nmts --help` nothing (`check:cli-startup`).
+import { ATTACH_LOG_TEXT, SUPPORT_LONG, supportHelpText } from "./support-copy.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";
@@ -18,27 +23,65 @@ export function helpText(version) {
         `  ${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`,
+        `  login                 Keep an NMTS key on this machine, sealed — and take an API key`,
+        `  logout                Remove the stored NMTS key`,
+        `  whoami                Show which account the stored NMTS key belongs to (offline)`,
+        `  create                Make a NEW account. Prints its NMTS key once — nothing can print it again.`,
+        `                        With no verified API key, it prints an address for a PERSON to open`,
+        `  key new               Make an API key for this machine out of the NMTS key it already`,
+        `                        holds, and store it. \`--print\` shows it once as well`,
+        `  key list              Every API key of this account: what it may do, when it stops, when it`,
+        `                        was last used. Needs the NMTS key; an API key cannot list keys`,
+        `  key revoke <id|all>   Cut one key, or all of them — whatever uses it stops at once`,
+        `  devices               What is signed in to this account. \`--sign-out <id|all>\` ends one`,
+        `                        or all — a person's act: needs the NMTS key, refused in mode auto`,
         `  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`,
+        `  credits transfer --to <account identifier> <credits>`,
+        `                        Move credits to another account of your own — the one that made this`,
+        `                        account, or one made under it. Never to anyone else`,
         `  expiring              List files whose bought storage runs out soon`,
+        `  losses                Storage the daily check could not find on the chain; --recheck <id> · --dismiss <id>`,
         `  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`,
+        `  delete-account        A PERSON erases this account's server record — irreversible; needs the`,
+        `                        NMTS key, types a sentence, refused in mode auto`,
+        `  accept-terms          A PERSON accepts a new version of the Terms, by typing its version;`,
+        `                        refused in mode auto. Read first: terms · privacy · notices`,
         `  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`,
+        `  wallet address        Just the address, derived on this machine — no network call.`,
+        `                        \`--qr\` draws it as a code a phone can scan`,
+        `  wallet activity       The wallet's recent transactions, named where the chain proves it`,
+        `  wallet storage        The storage resources (size × time) the wallet holds, unbound`,
+        `  wallet storage split <id> --size <n>|--epochs <n> · merge <id> <id> · transfer <id> <address>`,
+        `                        Cut, join or hand over a resource — **signs**, under the wallet unlock`,
+        `  wallet send <SUI|WAL> <amount|max> <address>`,
+        `                        Send coins to an address — **signs and spends from the wallet**.`,
+        `                        Prints the review; sends only with --yes`,
+        `  wallet swap <SUI|WAL> <amount|max>`,
+        `                        Swap one coin for the other on DeepBook or Bluefin (mainnet) —`,
+        `                        **signs and spends**. Without --venue, quotes both and stops`,
+        `  wallet donate <SUI|WAL> <amount>`,
+        `                        A voluntary gift to the developer — **signs and spends**. A person's`,
+        `                        act: refused in mode auto, and needs --yes every time`,
+        `  wallet hall           The gift hall of fame, read from the chain. \`--name <name>\` lists you`,
+        `                        under a name your wallet signs for; \`--remove\` goes back to a`,
+        `                        shortened address. Reading it signs nothing`,
+        `  put <file>            Encrypt one file and upload it, paid with credits — or, with`,
+        `                        \`--pay wallet\`, **signs and spends WAL and SUI from the wallet**`,
         `  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**`,
+        `  push <directory>      Upload a whole directory, keeping its shape — **spends credits**,`,
+        `                        or the wallet with \`--pay wallet\``,
         `  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`,
+        `  erase <paths>         Erase files for good — the server's record and this account's key.`,
+        `                        A typed sentence; \`--release-storage\` also destroys credit-paid storage`,
         `  rebuild               Build a file list from the server's rows, for an account with none`,
+        `  rollback              Put the previous file list back — a person's act`,
         `  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`,
@@ -50,19 +93,32 @@ export function helpText(version) {
         `  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`,
+        `  share <path> <addr>   Give one file to another account. Withdrawing does not recall it.`,
+        `                        In normal mode it asks every time: answer with --yes`,
         `  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`,
+        `  env                   What this machine is, and what it means for the NMTS key`,
+        `  unlock [name]         What this machine has unlocked; \`unlock <name>\` opens one — a person,`,
+        `                        at a terminal. \`lock <name>\` closes it. (\`consent\` is the older name)`,
+        `  mode [name]           How much an agent may decide without asking: default · auto-low ·`,
+        `                        auto-high · skip-permissions. Switched by a person at a terminal`,
         `  on-collision          What to do when an upload's name is already in use`,
+        `  padding [mode]        How file sizes are hidden: standard, pow2, or off for the exact size.`,
+        `                        Applies to the next uploads`,
+        `  deposit [credits]     Credits each credit-paid upload sets aside as a deposit, 0 to 64.`,
+        `                        Default 64; \`put --deposit <n>\` sets it for one upload`,
+        `  tip [percent|off]     The standing share of every storage payment sent to the developer as a`,
+        `                        gift, in WAL, without asking. 0 by default; the gift terms are agreed once`,
         `  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`,
+        `  recovery-list         Write the file that finds your bytes without NMTS. Holds no NMTS key`,
+        `  kit                   Recovery kit: that list AND your NMTS key, together in one file`,
         `  verify                Ask a person to pass the check that opens this account's limits`,
+        `  support               Write to the developer of NMTS: a bug, an error, an idea, a question`,
+        `  notices               What NMTS has posted. <id> prints one; --save <id> keeps it as a file`,
+        `  terms                 The Terms of Service in force. --board for the message board's`,
+        `  privacy               The Privacy Policy in force`,
         `  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`,
         ``,
@@ -70,54 +126,119 @@ export function helpText(version) {
         `  --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)`,
+        `                        expiring, losses, sweep, rebuild, rollback, pull, wallet, shares,`,
+        `                        share, receive, label, unlabel, padding, deposit, whoami --reveal,`,
+        `                        recovery, balance, trial, credits transfer, extend, recovery-list, kit, update, notices,`,
+        `                        devices, key new, key list, key revoke, create. \`key new\` puts the key string in the JSON`,
+        `                        only with --print, and \`create\` needs --out as well, so neither`,
+        `                        secret enters the output by default)`,
+        `  --all                 Include what is in the trash (ls), or take one label off every`,
+        `                        file that carries it (unlabel)`,
+        `  --sent <path>         Who ONE file was shared with, instead of the inbox (shares)`,
+        `  --rename <old>        The label to rename; the new name follows it (label)`,
+        `  --qr                  Draw the wallet address as a code to scan (wallet address)`,
+        `  --remove              Take your name off the gift hall of fame, leaving a shortened`,
+        `                        address (wallet hall). Give this or --name, not both`,
+        `  --days <n> | --until <date>`,
+        `                        How long a wallet agreement lasts, at most 30 days (unlock`,
+        `                        wallet), or how long a new API key lasts (key new). Default 30 days;`,
+        `                        the server clamps at its own ceiling and the reply says the date`,
+        `  --scopes <list>       What a new key may do (key new): read, write, spend, comma-separated.`,
+        `                        Default read. A program that uploads needs all three`,
+        `  --print               Put the new key on the screen once as well (key new). It is stored on`,
+        `                        this machine either way, and NMTS keeps no copy of it`,
+        `  --scope storage|all   What a wallet agreement covers: storage, or also exchanging and`,
+        `                        sending (unlock wallet). Default storage. A gift is in neither`,
+        `  --cap-wal <coins> --cap-sui <coins>`,
+        `                        A ceiling on what this tool may sign away under the agreement`,
+        `  --fee-cap <sui>       A ceiling on the chain fee of one transaction (wallet send, wallet`,
+        `                        swap). Only up to it is used; the rest stays in the wallet`,
+        `  --venue <name>        deepbook or bluefin (wallet swap). Neither is a default: without`,
+        `                        it both quotes are printed and nothing is signed`,
+        `  --slippage-bps <n>    How far below the quote the swap may still fill, in bps — 1 bps`,
+        `                        = 0.01% (wallet swap). 1 to 5000, default 50. Below 10 or above`,
+        `                        200 is an extreme`,
+        `  --accept-extremes     Go on past the extremes gate — slippage, fee cap or a quote more`,
+        `                        than 3% from the site's reference price (wallet swap). A person's`,
+        `                        act, refused while a mode is on`,
+        `  --reveal              Print the NMTS key itself (whoami). A person's act, and`,
+        `                        refused while a mode is on`,
         `  --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`,
+        `                        recovery-list, kit, create, notices, terms, privacy). Default: here`,
         `  --out -               Send a fetched file to stdout instead of writing it (get, listfile)`,
+        `  --lang <en|ko>        Which language of a document (terms, privacy). Default: English`,
+        `  --board               The message board's terms rather than the service's (terms)`,
+        `  --save                Keep the document as a file, under the name the server gives it`,
+        `                        (notices, terms, privacy)`,
         `  --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)`,
+        `  --name <name>         The name the uploaded file gets in the drive (put), or the name to`,
+        `                        be listed under in the gift hall of fame (wallet hall)`,
+        `  --to <folder>         Destination folder, as \`${BINARY_NAME} ls\` prints it (put, push).`,
+        `                        For \`credits transfer\` it is the account identifier that receives`,
         `  --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`,
+        `                        would install, and stop (update). With \`extend\` and \`--pay`,
+        `                        wallet\` 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),`,
+        `  --deposit <n>         Credits THIS upload sets aside per file, 0 to 64 (put, push, with`,
+        `                        credits). Without it the account's own default decides -- see`,
+        `                        \`${BINARY_NAME} deposit\`. 0 means a later release costs twice the fee`,
+        `                        from the balance instead of coming out of the file's deposit`,
+        `  --yes                 Go ahead with something that cannot be taken back (sweep, rebuild,`,
+        `                        rollback, wallet send, wallet swap, wallet donate),`,
         `                        or extend a file that is nowhere near its deadline (extend)`,
-        `  --epochs <n>          How many of the storage network's epochs to add (extend)`,
+        `  --epochs <n>          How many of the storage network's epochs to add (extend), to buy`,
+        `                        (put, push --pay wallet; default 2), or to keep (wallet storage split)`,
+        `  --size <bytes>        What a cut resource keeps: bytes, or with KiB/MiB/GiB (wallet storage split)`,
+        `  --pay credits|wallet  Who pays for an upload's storage (put, push). Default credits.`,
+        `                        wallet = the wallet this NMTS key derives signs and pays the`,
+        `                        network directly, under a wallet agreement of scope storage`,
+        `  --storage fit|whole|<object id>`,
+        `                        Use a free storage resource the wallet already holds (put --pay`,
+        `                        wallet, one-part files). fit cuts it to size and leaves the rest`,
+        `                        free; whole binds all of it with the file. The review says which`,
+        `                        bytes go where. Without it new storage is bought`,
         `  --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)`,
+        `  --no-wait             Print the registration address and stop, instead of waiting for a`,
+        `                        person to open it (create, when there is no verified key)`,
         `  --publish             Publish this account's public code (public-code). Permanent —`,
         `                        it cannot be withdrawn or changed afterwards`,
+        `  --category <c>        What a report is about (support send). The categories are listed by`,
+        `                        \`${BINARY_NAME} support --help\``,
+        `  --sub <s>             Which part of that category (support send). Always optional`,
+        `  --message <text>      The message itself (support send, support reply)`,
+        `  --message-file <p>    A file holding the message instead (support send). With neither, the`,
+        `                        message is read from the standard input`,
+        `  --attach-log [n]      Attach this tool's own record of its last n runs (support send).`,
+        `                        Default 3, most 20`,
+        `  --omit <text>         A value that must not travel. May be given more than once (support`,
+        `                        send, support reply)`,
         `  --status              Say whether the check is live, and stop (verify)`,
-        `  --plain               Store the code unsealed instead (login). Asks for an agreement`,
+        `  --plain               Store the NMTS key 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`,
+        `  ${CODE_FILE_ENV_VAR.padEnd(24)}Names a FILE holding the NMTS key. 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,`,
+        `  ${CODE_ENV_VAR.padEnd(24)}The NMTS key 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.`,
+        `  ${PASSPHRASE_ENV_VAR.padEnd(24)}Opens a sealed stored NMTS key 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`,
@@ -131,6 +252,11 @@ export function helpText(version) {
         `                          your files were never stored.`,
         `  ${NO_CHECK_ENV_VAR.padEnd(24)}Set to anything to stop the version check described below.`,
         ``,
+        `SENDING A REPORT`,
+        ...SUPPORT_LONG.map((line) => (line === `` ? `` : `  ${line}`)),
+        ``,
+        ...ATTACH_LOG_TEXT.map((line) => `  ${line}`),
+        ``,
         // ⛔ 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.
@@ -155,14 +281,14 @@ export function helpText(version) {
         `    ${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`,
+        `  line on stderr saying so. It sends no NMTS key, no API 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`,
+        `  Your NMTS key 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.`,
         ``,
@@ -170,7 +296,7 @@ export function helpText(version) {
         ``,
         // ⛔ 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
+        //    an NMTS key 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
@@ -190,3 +316,43 @@ export function helpText(version) {
         ``,
     ].join("\n");
 }
+/**
+ * `nmts help <command>`: the document for one command, from `docs/commands/`, or the list of
+ * documents when the name matches none.
+ *
+ * ⚠ The directory is read only here, so `--help` itself pays nothing for it (`check:cli-startup`).
+ *   Each document names the commands it covers on its `Commands:` line; that line is the index.
+ */
+export async function helpFor(topic) {
+    const { readdirSync, readFileSync } = await import("node:fs");
+    const dir = new URL("../docs/commands/", import.meta.url);
+    const wanted = topic.trim().toLowerCase();
+    const covered = [];
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(".md")).sort()) {
+        const text = readFileSync(new URL(file, dir), "utf8");
+        const line = text.split("\n").find((l) => l.startsWith("Commands:")) ?? "";
+        const names = line.slice("Commands:".length).split(",").map((n) => n.trim()).filter((n) => n !== "");
+        if (names.includes(wanted))
+            return { text, found: true };
+        covered.push(...names);
+    }
+    return {
+        found: false,
+        text: `No document for "${topic}". \`${BINARY_NAME} help <command>\` knows: ` +
+            `${covered.sort().join(", ")}.\n`,
+    };
+}
+/**
+ * What `--help`, a bare run, `help`, and `help <command>` print, and the exit code.
+ * ⛔ `support` has help of its own: it is READ before deciding, not scanned for an option name.
+ */
+export async function printHelp(args, write) {
+    const topic = args.command === "help" ? args.operands[0] : undefined;
+    if (topic !== undefined) {
+        const doc = await helpFor(topic);
+        write(doc.text);
+        return doc.found ? 0 : 2;
+    }
+    write(args.command === "support" ? supportHelpText() : helpText(VERSION));
+    return 0;
+}

package/dist/human-check.d.ts

@@ -0,0 +1,23 @@
+import { NmtsError } from "./errors.ts";
+/** Where this account stands with the periodic check a person passes. */
+export interface HumanCheck {
+    live: boolean;
+    /** The moment the current window ends, as the server spelled it, or null. */
+    until: string | null;
+}
+/**
+ * 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 declare function humanCheck(server: string, apiKey: string): Promise<HumanCheck>;
+/**
+ * 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 declare function askAPersonToVerify(whatIsRefused: string): NmtsError;

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export { NmtsError, NotLoggedInError, renderError } from "./errors.ts";
+export { request, ServerError, DEFAULT_TIMEOUT_MS } from "./api.ts";
+export type { RequestOptions, ServerRefusal } from "./api.ts";
+export { DEFAULT_SERVER, SERVER_ENV_VAR, resolveServer } from "./server.ts";
+export { NETWORKS, NETWORK_ENV_VAR, resolveNetwork } from "./network.ts";
+export type { Network } from "./network.ts";
+export { API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, CODE_ENV_VAR, CODE_FILE_ENV_VAR, configDir, readSecretFile, resolveAccountCode, resolveApiKey, } from "./credentials.ts";
+export type { CredentialSource, ResolvedCode } from "./credentials.ts";
+export { assertUsableCode, identityOf } from "./account.ts";
+export type { AccountIdentity } from "./account.ts";
+export { AAD, DERIVED, loadCrypto } from "./crypto.ts";
+export type { CryptoGlue } from "./crypto.ts";
+export { readFileList } from "./manifest.ts";
+export type { FileList } from "./manifest.ts";
+export { addEntry, applyManyToList, applyToList, planAddition } from "./manifest-write.ts";
+export type { AddEntryInput, AddEntryResult, ListEditInput, ListEditResult } from "./manifest-write.ts";
+export type { Manifest, ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+export { buildIndex, entryAt, folderIdFor, fullPathOf, isLive, KIND_FILE, KIND_FOLDER, namesIn, normalisePath, trashedAt, } from "./drive-paths.ts";
+export type { FindOptions, ManifestIndex } from "./drive-paths.ts";
+export { setTrashed } from "./item-trash.ts";
+export { fileSource, partKeysOf, uploadFile } from "./upload-file.ts";
+export type { FileUploadInput, FileUploadStep, PlaintextSource } from "./upload-file.ts";
+export { createUploadApi } from "./upload-api.ts";
+export { CREDIT_BYTES, creditsFor, measureLocal, partSizeFor, planAndPrice, UPLOAD_EPOCHS, } from "./upload-price.ts";
+export { clearItemRecord, clearReservation } from "./upload-store.ts";
+export { UploadError } from "./upload-wire.ts";
+export type { BlobProtocol, UploadApi, UploadResult, UploadStep } from "./upload-wire.ts";
+export type { PaddingRule } from "./shared/lib/crypto/size-padding.ts";
+export { DEFAULT_PART_BYTES } from "./seal.ts";
+export { createBlobProtocol, readCurrentEpoch } from "./walrus-write.ts";
+export { fetchFile, fetchWithKey } from "./download.ts";
+export type { FetchedFile, FetchInput } from "./download.ts";
+export { fileSink } from "./download-sink.ts";
+export type { PlaintextSink } from "./download-sink.ts";
+export { AGGREGATOR_ENV_VAR, readBlob, RELAY_ENV_VAR, SUI_RPC_ENV_VAR } from "./walrus.ts";
+export type { ReadOptions } from "./walrus.ts";
+export { coinAmount, readBalances, walletAddress } from "./wallet.ts";
+export type { ChainReader, CoinBalance, WalletBalances } from "./wallet.ts";
+export { chainReader } from "./wallet-chain.ts";
+export { signerAddress, signExtension, signTransfer } from "./wallet-sign.ts";
+export type { SignTransfer } from "./wallet-sign.ts";
+export { HOME_URL, PRODUCT_NAME, SOURCE_URL, SUPPORT_EMAIL, VERSION } from "./product.ts";

package/dist/index.js

@@ -0,0 +1,49 @@
+// The library surface of this package — what `import "@needmoretruth/nmts-cli"` hands a program.
+//
+// ⛔ THIS IS NOT THE COMMAND. `main.ts` is what the `nmts` binary runs; nothing here parses
+//    arguments, prints, prompts or exits. Everything re-exported below takes its inputs as values
+//    and reports through return values and thrown `NmtsError`s, which is what lets another
+//    package — the SDK, or somebody's own server — build on it without inheriting a terminal.
+//
+// ⛔ ONLY MODULES THAT NEVER TOUCH A TERMINAL ARE HERE. `code-access.ts`, `api-key.ts`,
+//    `session.ts` and every `commands/*` file can stop to ask a person something, and a library
+//    that stops to ask on somebody's server is a library that hangs. A program that wants the
+//    NMTS key from the environment reads `credentials.ts` and decides for itself.
+//
+// ⚠ THE PACKAGE'S `exports` MAP NAMES THIS FILE AND A FEW OF THE MODULES BELOW BY SUBPATH. A
+//   module not named there is reachable through this file only; adding a subpath is a promise
+//   that its shape stays put, so it is done on purpose and one at a time.
+// Errors — the one shape every failure below arrives in.
+export { NmtsError, NotLoggedInError, renderError } from "./errors.js";
+// The server: one request function, and what a refusal looks like.
+export { request, ServerError, DEFAULT_TIMEOUT_MS } from "./api.js";
+export { DEFAULT_SERVER, SERVER_ENV_VAR, resolveServer } from "./server.js";
+export { NETWORKS, NETWORK_ENV_VAR, resolveNetwork } from "./network.js";
+// Where a credential can come from on this machine. Reading is here; ASKING is not.
+export { API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, CODE_ENV_VAR, CODE_FILE_ENV_VAR, configDir, readSecretFile, resolveAccountCode, resolveApiKey, } from "./credentials.js";
+// The account: what a code derives, and the engine that derives it.
+export { assertUsableCode, identityOf } from "./account.js";
+export { AAD, DERIVED, loadCrypto } from "./crypto.js";
+// The sealed file list: reading it, editing it, and walking it by path.
+export { readFileList } from "./manifest.js";
+export { addEntry, applyManyToList, applyToList, planAddition } from "./manifest-write.js";
+export { buildIndex, entryAt, folderIdFor, fullPathOf, isLive, KIND_FILE, KIND_FOLDER, namesIn, normalisePath, trashedAt, } from "./drive-paths.js";
+export { setTrashed } from "./item-trash.js";
+// Uploading: sealing here, buying storage with credits, pushing the sealed bytes.
+export { fileSource, partKeysOf, uploadFile } from "./upload-file.js";
+export { createUploadApi } from "./upload-api.js";
+export { CREDIT_BYTES, creditsFor, measureLocal, partSizeFor, planAndPrice, UPLOAD_EPOCHS, } from "./upload-price.js";
+export { clearItemRecord, clearReservation } from "./upload-store.js";
+export { UploadError } from "./upload-wire.js";
+export { DEFAULT_PART_BYTES } from "./seal.js";
+export { createBlobProtocol, readCurrentEpoch } from "./walrus-write.js";
+// Downloading: fetching sealed parts from the storage network and opening them here.
+export { fetchFile, fetchWithKey } from "./download.js";
+export { fileSink } from "./download-sink.js";
+export { AGGREGATOR_ENV_VAR, readBlob, RELAY_ENV_VAR, SUI_RPC_ENV_VAR } from "./walrus.js";
+// The wallet the NMTS key derives: reading it, and signing with it.
+export { coinAmount, readBalances, walletAddress } from "./wallet.js";
+export { chainReader } from "./wallet-chain.js";
+export { signerAddress, signExtension, signTransfer } from "./wallet-sign.js";
+// What this package is.
+export { HOME_URL, PRODUCT_NAME, SOURCE_URL, SUPPORT_EMAIL, VERSION } from "./product.js";

package/dist/item-trash.d.ts

@@ -0,0 +1 @@
+export declare function setTrashed(base: string, apiKey: string, id: string, trashed: boolean): Promise<void>;

package/dist/kit-file.d.ts

@@ -0,0 +1,56 @@
+import { type ArtifactAbout } from "./artifact-about.ts";
+/** Start of the machine block. ⛔ Fixed bytes, never translated. */
+export declare const KIT_DATA_BEGIN = "--- BEGIN NMTS RECOVERY KIT DATA ---";
+/** End of the machine block. */
+export declare const KIT_DATA_END = "--- END NMTS RECOVERY KIT DATA ---";
+/** The marker a reader matches on before anything else is attempted. */
+export declare 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 declare 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 NMTS key and never a key. It
+ *    lets somebody confirm two files refer to one account without either of them exposing a secret.
+ */
+export declare function accountIdFingerprint(accountId: string): string;
+/** The machine-readable payload, read by the standalone recovery program. */
+export interface RecoveryKitData {
+    format: typeof KIT_FORMAT;
+    version: typeof KIT_VERSION;
+    generated_at: string;
+    account_id: string;
+    account_fingerprint: string;
+    /** ⛔ The NMTS key, in the clear. This is the field that makes the file dangerous to hold. */
+    account_code: string;
+    /** Storage-network address of the list, when there is one. Always null from this tool. */
+    recovery_manifest_blob: string | null;
+    /** The whole `.nmtsmap` document, or null when there was nothing to list. */
+    recovery_list: Record<string, unknown> | null;
+    about: ArtifactAbout;
+}
+export interface BuildKitInput {
+    /** Display-form NMTS key, grouped as a person reads it. */
+    code: string;
+    accountId: string;
+    generatedAt: string;
+    /** The parsed `.nmtsmap` document to embed, or null when the account has no files. */
+    recoveryList: Record<string, unknown> | null;
+    /** How many files that list covers. Null when there is no list. */
+    listFileCount: number | null;
+}
+/** Build the kit's text: a part for a person, then a part for a program. */
+export declare function buildRecoveryKit(input: BuildKitInput): {
+    filename: string;
+    content: string;
+};

package/dist/kit-file.js

@@ -1,10 +1,10 @@
-// The RECOVERY KIT — the one file that carries everything, account code included.
+// The RECOVERY KIT — the one file that carries everything, NMTS key included.
 //
-// ⛔⛔ IT HOLDS THE ACCOUNT CODE IN THE CLEAR, AND THAT IS THE FORMAT. It was decided deliberately
+// ⛔⛔ IT HOLDS THE NMTS KEY 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 LIST — sealed. Worthless to a thief. The NMTS key 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.
 //
@@ -52,7 +52,7 @@ export const KIT_VERSION = 2;
  *   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
+ * ⛔ IT FINGERPRINTS THE ACCOUNT ID, WHICH IS PUBLIC — never the NMTS key 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) {
@@ -86,17 +86,17 @@ export function buildRecoveryKit(input) {
         // ⛔ 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.`,
+            `for storage. One NMTS key 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, ` +
+        `This file carries your NMTS key 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 ` +
+        `Anyone with this NMTS key can open your files. If you lose it, no one — including NMTS — can ` +
             `recover them.`,
         ``,
-        `Account code:`,
+        `NMTS key:`,
         `    ${input.code}`,
         ``,
         `Account identifier: ${data.account_id}`,
@@ -111,12 +111,12 @@ export function buildRecoveryKit(input) {
             `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 ` +
+        `   It takes the NMTS key 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 — ` +
+        `4. To see what your NMTS key 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.`,