@needmoretruth/nmts-cli 0.17.2

package/dist/net-retry.js

@@ -0,0 +1,84 @@
+// Going on across a connection that dropped, changed, or is simply slow.
+//
+// ⛔ THE POLICY IS NOT WRITTEN HERE. It is `shared/lib/net/retry-budget.ts`, copied byte for byte
+//    from the browser, so that both programs mean the same thing by "we tried". What IS here is
+//    the waiting, because how you wait is different in a terminal than in a page.
+//
+// ⛔ WHAT MAY BE REPEATED, AND WHAT MAY NEVER BE. Repeating a GET costs nothing. Repeating a write
+//    whose outcome is unknown can spend money twice -- a request that reached the server and died
+//    on the way back looks exactly like one that never arrived. So a write is repeated ONLY when
+//    it carries an idempotency key, which is the server's promise that a second copy of the same
+//    request is the same request. Everything else fails once and says so.
+//
+// ⛔ NOTHING IS RETRIED SILENTLY. A person running this in a terminal and an agent reading its
+//    output both need to know that the tool is waiting rather than stuck; `onWait` is how they are
+//    told, and every command that can wait passes something.
+//
+// ⚠ NODE HAS NO "ONLINE" EVENT AND NO ONLINE FLAG. A browser can be told the network came back;
+//   here the only way to find out is to ask again. So the offline branch of the policy is not
+//   reachable from this file, and the whole budget is the online one -- which is honest: without a
+//   signal to wait for, waiting longer is just waiting.
+import { nextAttempt, WATCHED_RETRY_BUDGET_MS } from "./shared/lib/net/retry-budget.js";
+/**
+ * How long a command goes on trying before it reports the failure.
+ *
+ * ⛔ SHORTER THAN ANYTHING ELSE, BECAUSE SOMEBODY TYPED THIS AND IS LOOKING AT IT. The long budget
+ *    is for work nobody is watching -- a page uploading in the background, which has money already
+ *    spent on it and resumes where it stopped. A terminal that sits silent is indistinguishable
+ *    from one that has hung, an agent has a deadline of its own, and running the command again
+ *    costs nothing. What this has to cover is a link that blinks, not a server that is down.
+ */
+export const CLI_RETRY_BUDGET_MS = Math.round(WATCHED_RETRY_BUDGET_MS / 3);
+/** Run `step` until it succeeds or the budget is spent. Rejects with the LAST error. */
+export async function keepTrying(step, options) {
+    const now = options.now ?? (() => Date.now());
+    const random = options.random ?? Math.random;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let elapsedOnlineMs = 0;
+    for (let attempt = 1;; attempt += 1) {
+        options.signal?.throwIfAborted();
+        try {
+            return await step();
+        }
+        catch (error) {
+            if (options.signal?.aborted === true)
+                throw error;
+            if (!options.retryable(error))
+                throw error;
+            const plan = nextAttempt({
+                attempt,
+                elapsedOnlineMs,
+                elapsedOfflineMs: 0,
+                online: true,
+                random: random(),
+                budgetMs: options.budgetMs ?? CLI_RETRY_BUDGET_MS,
+            });
+            if (!plan.again)
+                throw error;
+            options.onWait?.({ attempt, waitMs: plan.waitMs, error });
+            const before = now();
+            await sleep(plan.waitMs);
+            // The time that actually passed, not the time that was planned: a machine that was suspended
+            // mid-wait spent all of it, and charging the planned number would let it wait for ever.
+            elapsedOnlineMs += Math.max(0, now() - before);
+        }
+    }
+}
+/**
+ * Is this failure one that asking again could fix?
+ *
+ * ⛔ A REFUSAL IS NOT A BLIP. The server saying no -- wrong key, no credits, not found -- is an
+ *    answer, and repeating it spends the budget to hear it again later. Only the shapes that mean
+ *    "nobody answered" or "not right now" come back here as true.
+ */
+export function isTransient(error, status) {
+    if (typeof status === "number")
+        return status === 408 || status === 429 || status >= 500;
+    if (!(error instanceof Error))
+        return false;
+    // ⛔ A DEADLINE THAT FIRED IS NOT A BLIP. The request already had its thirty seconds; asking
+    //    again usually spends thirty more and ends the same way, and the deadline exists precisely so
+    //    that an agent loop is not left waiting. What comes back here as true is a connection that
+    //    was refused, reset or never made -- which is what moving between networks looks like.
+    return /could not reach|fetch failed|network|ECONNRESET|ECONNREFUSED|ECONNABORTED|EAI_AGAIN|ENOTFOUND|socket hang up/i.test(`${error.message} ${String(error.cause ?? "")}`);
+}

package/dist/network.js

@@ -0,0 +1,43 @@
+// Which storage network this run uses — and why it is never guessed.
+//
+// ⛔ THE TRAP THIS EXISTS TO CLOSE. In the web app the network comes from an environment variable
+//    read at module load, and an EMPTY value silently means "testnet". A production build refuses
+//    to start that way; a Node process does not. So a tool that inherited that default would point
+//    a mainnet account at testnet aggregators, testnet relays and a testnet chain check — and
+//    would report that everything was fine while looking in a place the files were never in.
+//
+// ⛔ SO THE RULE HERE IS: the live server implies mainnet, and ANY other server must say which
+//    network it is. There is no fallback. A tool that has to guess where somebody's files are
+//    should stop instead.
+import { NmtsError } from "./errors.js";
+import { DEFAULT_SERVER } from "./server.js";
+export const NETWORKS = ["mainnet", "testnet"];
+export const NETWORK_ENV_VAR = "NMTS_NETWORK";
+function isNetwork(value) {
+    return NETWORKS.includes(value);
+}
+/**
+ * Decide the network for this run.
+ *
+ * `explicit` beats the environment, which beats the one inference this function is willing to
+ * make: the live server is mainnet. Anything else and it refuses.
+ */
+export function resolveNetwork(server, explicit) {
+    const stated = explicit ?? process.env[NETWORK_ENV_VAR];
+    if (stated !== undefined && stated.length > 0) {
+        if (!isNetwork(stated)) {
+            throw new NmtsError(`Not a network: ${stated}`, {
+                exitCode: 2,
+                nextStep: `Use one of: ${NETWORKS.join(", ")}.`,
+            });
+        }
+        return stated;
+    }
+    if (server === DEFAULT_SERVER)
+        return "mainnet";
+    throw new NmtsError(`Cannot tell which storage network ${server} uses.`, {
+        exitCode: 2,
+        nextStep: `Set ${NETWORK_ENV_VAR}=mainnet or ${NETWORK_ENV_VAR}=testnet. ` +
+            `Guessing would look for your files on a network they were never stored on.`,
+    });
+}

package/dist/notice.js

@@ -0,0 +1,45 @@
+// The one thing this tool says before it keeps an account code on a machine.
+//
+// ⛔ WHY IT EXISTS. Handing an agent your account code is handing it the vault: in NMTS every key
+//    is derived from that one code — the file keys and the wallet both — so an agent that leaks it
+//    has leaked everything at once, and the account cannot be re-keyed because the account IS the
+//    code. The owner asked for this to be said out loud (2026-08-23).
+//
+// ⛔ WHY IT SAYS FACTS AND NOT "WE ARE NOT LIABLE". A disclaimer is a contract term, and the Terms
+//    of Service in force today do not carry one for this. Printing a term we have not published
+//    would be claiming an agreement that does not exist. A clause covering this is drafted for the
+//    next version of the published Terms; until that version is in force, this text states only
+//    what is verifiably true, which is the part that actually helps somebody decide anyway.
+//    ⛔ When that version ships, the term belongs in the Terms — not here. This stays facts.
+//
+// ⛔ WHY IT IS SHOWN ONCE AND NOT EVERY RUN. A warning printed on every command is a warning
+//    nobody reads, and it would land in the middle of an agent's output forever. It is shown at
+//    the moment the decision is made — when the code is first written to this machine.
+import { PRODUCT_NAME } from "./product.js";
+/**
+ * The text shown before an account code is stored on this machine.
+ *
+ * Every sentence here is a measured fact about how NMTS works, not a prediction and not a
+ * comparison. If any of it stops being true, this text is wrong and must change with the code.
+ */
+export function firstRunNotice() {
+    return [
+        `${PRODUCT_NAME} is about to keep your account code on this machine.`,
+        ``,
+        `  Your account code is the only key to your account. The keys that encrypt`,
+        `  your files and the keys to your wallet are all derived from it.`,
+        ``,
+        `  Keeping it here is what lets this tool work while you are away. It also`,
+        `  means any program that can read your files can read it, including any`,
+        `  agent you run on this machine.`,
+        ``,
+        `  If it leaves this machine — in a log line, in a prompt, in a repository —`,
+        `  whoever holds it can read every file in the account and spend from the`,
+        `  wallet. NMTS cannot undo that: requests made with your code cannot be`,
+        `  told apart from your own, and the code cannot be changed while keeping`,
+        `  the account.`,
+        ``,
+        `  Give an agent an account you would be willing to lose.`,
+        ``,
+    ].join("\n");
+}

package/dist/product.js

@@ -0,0 +1,38 @@
+// The product's own names, in one place.
+//
+// WHY A MODULE FOR THREE STRINGS. The name reached the code before it was settled — first
+// "NMTS for Agent", then "NMTS for Agents", and finally `nmts-cli` with the tool itself just
+// called `nmts` (owner, 2026-08-23). A name spelled out at twelve call sites is a name that
+// ends up spelled three ways.
+//
+// ⛔ "for agents" is NOT part of the name. It says who this is for, which belongs in the README
+//    and the package description where it can change without renaming anything.
+/** What a person reads, and what the tool calls itself. Owner-settled 2026-08-23. */
+export const PRODUCT_NAME = "nmts";
+/** What an agent types. The same word: there is nothing to translate between the two. */
+export const BINARY_NAME = "nmts";
+/**
+ * This build's version.
+ *
+ * ⛔ Kept here rather than read from `package.json`: the published build has no package.json
+ *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
+ *    command importing the entry point is a cycle waiting to bite.
+ */
+export const VERSION = "0.17.2";
+/** Where the product lives, for messages that need to send somebody somewhere real. */
+export const HOME_URL = "https://nmts.me";
+/** The source, so a person holding only the built program can find what it was built from. */
+export const SOURCE_URL = "https://github.com/needmoretruth/nmts-cli";
+/** Who holds the copyright. One place, because it is also the answer to "who can license this". */
+export const COPYRIGHT = "Copyright 2026 needmoretruth";
+/**
+ * Where to write about a fault, a confusing message, or anything that got in the way.
+ *
+ * ⛔ IT IS IN THE TOOL AND NOT ONLY IN THE README, because the moment somebody wants to report
+ *    something is the moment it went wrong -- and that is exactly when nobody goes looking for a
+ *    web page. The smallest annoyance is worth an email; most of them are cheap to fix and
+ *    invisible from here.
+ */
+export const SUPPORT_EMAIL = "nmts@nmts.me";
+/** The document in the source repository that is written for an agent rather than for a person. */
+export const AGENTS_DOC = "AGENTS.md";

package/dist/progress.js

@@ -0,0 +1,110 @@
+// Showing how far along something is, without making a mess of a pipe.
+//
+// ⛔ A TERMINAL AND A PIPE ARE DIFFERENT AUDIENCES. A person watching wants one line that rewrites
+//    itself; an agent capturing stdout wants text it can read, and a thousand carriage returns in
+//    its buffer is noise it has to strip before it can find the answer. So the same reporter
+//    behaves differently depending on where it is writing, and the decision is made once, here.
+//
+// ⛔ IT NEVER WRITES TO STDOUT WHEN THE OUTPUT IS MACHINE-READABLE. `--json` promises one JSON
+//    document and nothing else; a progress line would break every parser that trusted that.
+export function stderrSink() {
+    return {
+        // ⛔ STDERR, NOT STDOUT. Progress is not the answer, and a caller redirecting the answer to a
+        //    file must not find it interleaved with percentages.
+        write: (text) => void process.stderr.write(text),
+        interactive: process.stderr.isTTY === true,
+    };
+}
+/** A reporter that says nothing. What `--json` gets, and what a test gets by default. */
+export function silentSink() {
+    return { write: () => { }, interactive: false };
+}
+/** How much has to change before a non-interactive sink is told again, as a fraction. */
+const PIPE_STEP = 0.1;
+/**
+ * Report progress through one phase.
+ *
+ * On a terminal the line rewrites in place, to a tenth of a percent — fine enough that a large
+ * upload visibly moves rather than appearing to hang. Into a pipe it prints a plain line every ten
+ * percent, which is legible in a log and small enough not to bury the result.
+ */
+export class Progress {
+    sink;
+    label;
+    lastPrinted = -1;
+    dirty = false;
+    constructor(sink, label) {
+        this.sink = sink;
+        this.label = label;
+    }
+    update(done, total) {
+        if (total <= 0)
+            return;
+        const fraction = Math.min(1, Math.max(0, done / total));
+        if (this.sink.interactive) {
+            // A tenth of a percent, and never the same number twice: at gigabyte scale the callback
+            // fires far more often than the display can change.
+            const tenths = Math.floor(fraction * 1000);
+            if (tenths === this.lastPrinted)
+                return;
+            this.lastPrinted = tenths;
+            this.dirty = true;
+            this.sink.write(`\r  ${this.label} ${(tenths / 10).toFixed(1)}%   `);
+            return;
+        }
+        const step = Math.floor(fraction / PIPE_STEP);
+        if (step === this.lastPrinted)
+            return;
+        this.lastPrinted = step;
+        this.sink.write(`  ${this.label} ${Math.round(step * PIPE_STEP * 100)}%\n`);
+    }
+    /** Finish the line, so whatever prints next starts clean. */
+    done() {
+        if (this.sink.interactive && this.dirty) {
+            this.sink.write(`\r  ${this.label} 100.0%   \n`);
+            this.dirty = false;
+        }
+    }
+}
+/**
+ * A `fetch` that counts the bytes of the request body as they go out.
+ *
+ * ⛔ THE BODY IS RE-WRAPPED, NOT RE-READ. The bytes are handed to the request as a stream that
+ *    reports each chunk on its way past, so nothing is copied and the count is what actually left
+ *    rather than what was queued.
+ *
+ * ⚠ `duplex: "half"` is required by the fetch specification for a streaming body and Node enforces
+ *   it. Without it the request throws before a single byte is sent.
+ */
+export function countingFetch(onSent, chunkBytes = 256 * 1024) {
+    return async (url, init) => {
+        const body = init?.body;
+        if (!(body instanceof Uint8Array))
+            return fetch(url, init);
+        const total = body.length;
+        let sent = 0;
+        const stream = new ReadableStream({
+            pull(controller) {
+                if (sent >= total) {
+                    controller.close();
+                    return;
+                }
+                const end = Math.min(sent + chunkBytes, total);
+                controller.enqueue(body.subarray(sent, end));
+                sent = end;
+                onSent(sent, total);
+            },
+        });
+        const next = {
+            ...init,
+            body: stream,
+            duplex: "half",
+        };
+        // ⚠ A streaming body has no length the runtime can work out, and some servers need one.
+        const headers = new Headers(init?.headers);
+        if (!headers.has("content-length"))
+            headers.set("content-length", String(total));
+        next.headers = headers;
+        return fetch(url, next);
+    };
+}

package/dist/prompt.js

@@ -0,0 +1,145 @@
+// Reading a secret from a terminal without putting it on the screen.
+//
+// ⛔ WHY NOT `readline`. It echoes what is typed, and an account code on screen ends up in
+//    scrollback, in a screen share, and in the terminal recording some agents keep. The usual
+//    workaround — swapping `process.stdout.write` for a muted one while the question is open — is
+//    a global mutation in a process that may be writing other output, and it stays broken if the
+//    promise rejects between the swap and the restore. This reads the raw stream instead: nothing
+//    global changes, and echo never happens because nothing echoes it.
+//
+// ⚠ THIS REQUIRES A REAL TERMINAL. When stdin is a pipe — which is how an agent usually runs this
+//    tool — there is nothing to prompt, and waiting would hang on a stream that will never carry a
+//    keystroke. The caller is told to use the environment variable, which is the right answer for
+//    an agent anyway.
+//
+// The keystroke rules live in secret-reader.ts and are tested without a terminal.
+import { NmtsError } from "./errors.js";
+import { SecretReader } from "./secret-reader.js";
+/**
+ * Bytes typed ahead at a prompt that has already closed, waiting for the next one.
+ *
+ * ⛔ MODULE STATE, AND IT HAS TO BE. The thing being carried across is one keyboard, and each
+ *    prompt is a separate call — there is nowhere else for it to live. It holds only what a
+ *    person typed at this process's own terminal, it is cleared as it is consumed, and nothing
+ *    reads it but the next prompt.
+ */
+let pending = new Uint8Array(0);
+/**
+ * Hold the terminal in raw mode across a RUN of prompts.
+ *
+ * ⛔ WITHOUT THIS, THE GAP BETWEEN TWO PROMPTS ECHOES. `promptSecret` sets raw mode for its own
+ *    question and restores it afterwards, which was right while this tool asked one thing. `login`
+ *    now asks three in a row with work in between (the code is checked before a passphrase is
+ *    asked for), and in that gap the terminal is back in line mode: it echoes what is typed, and
+ *    its line discipline holds whole lines that the next prompt then never sees. Measured through
+ *    a pty: a paste of code + passphrase + confirmation ended in "Cancelled" with both
+ *    passphrases printed on the screen.
+ *
+ * ⚠ Restoring is what the `finally` is for, including on a throw — a process that exits leaving a
+ *   terminal in raw mode leaves the person's shell unusable.
+ */
+export async function holdTerminal(body) {
+    const stdin = process.stdin;
+    if (!stdinIsATerminal())
+        return body();
+    const was = stdin.isRaw === true;
+    stdin.setRawMode(true);
+    try {
+        return await body();
+    }
+    finally {
+        stdin.setRawMode(was);
+        // Anything typed past the last question belongs to nobody. It is not carried out of here.
+        pending.fill(0);
+        pending = new Uint8Array(0);
+    }
+}
+export function stdinIsATerminal() {
+    return process.stdin.isTTY === true;
+}
+/** Ask for a secret on the terminal, echoing nothing. Ctrl-C and Ctrl-D abandon the prompt. */
+export async function promptSecret(question, envVar) {
+    if (!stdinIsATerminal()) {
+        throw new NmtsError("There is no terminal to type into (stdin is not a TTY).", {
+            exitCode: 3,
+            nextStep: `Set ${envVar} in the environment instead.`,
+        });
+    }
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw === true;
+    const reader = new SecretReader();
+    // ⛔ TYPED-AHEAD INPUT IS ANSWERED FIRST. A terminal delivers a pasted block as ONE chunk, so
+    //    somebody answering three prompts with three pasted lines sends all three before the second
+    //    prompt exists. Reading only from the stream would throw the last two away — and `login`
+    //    asks three questions in a row, so that was the ordinary case, not the odd one.
+    if (pending.length > 0) {
+        const carried = pending;
+        pending = new Uint8Array(0);
+        const ahead = reader.push(carried);
+        carried.fill(0);
+        if (ahead.kind !== "more") {
+            pending = reader.takeLeftover();
+            process.stderr.write(`${question}\n`);
+            if (ahead.kind === "cancelled") {
+                reader.wipe();
+                throw new NmtsError("Cancelled.", { exitCode: 130 });
+            }
+            return ahead.value;
+        }
+    }
+    // ⛔ THE QUESTION GOES TO STDERR, NOT STDOUT. A prompt is not output: stdout is what a caller
+    //    parses, redirects and — under `nmts mcp` — reads as protocol. An adversarial review caught
+    //    this one: a passphrase prompt written to stdout put non-protocol bytes on the MCP wire,
+    //    where the other end sees a parse error and the tool simply disappears.
+    process.stderr.write(question);
+    stdin.setRawMode(true);
+    stdin.resume();
+    try {
+        return await new Promise((resolve, reject) => {
+            const onData = (chunk) => {
+                const step = reader.push(chunk);
+                if (step.kind === "more")
+                    return;
+                stdin.off("data", onData);
+                process.stderr.write("\n");
+                if (step.kind === "cancelled") {
+                    reader.wipe();
+                    reject(new NmtsError("Cancelled.", { exitCode: 130 }));
+                    return;
+                }
+                pending = reader.takeLeftover();
+                resolve(step.value);
+            };
+            stdin.on("data", onData);
+        });
+    }
+    finally {
+        reader.wipe();
+        stdin.setRawMode(wasRaw);
+        stdin.pause();
+    }
+}
+/**
+ * Ask a question whose answer is not a secret, and echo what is typed.
+ *
+ * ⛔ NOT FOR SECRETS. `promptSecret` exists for those: it turns echo off and wipes what it read.
+ *    This one is for a choice, where seeing what you typed is the point.
+ *
+ * ⛔ IT MUST NOT BE CALLED INSIDE `holdTerminal`. That puts the terminal in raw mode, where
+ *    readline gets characters one at a time and no line ever arrives.
+ *
+ * ⚠ Returns the empty string when there is no terminal, so callers can treat "nobody was there"
+ *   as "nothing was chosen" rather than as an answer. A setup script must not hang here.
+ */
+export async function promptLine(question) {
+    if (!stdinIsATerminal())
+        return "";
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}