@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/download-part.d.ts

@@ -0,0 +1,40 @@
+import type { CryptoGlue } from "./crypto.ts";
+import { type ReadOptions } from "./walrus.ts";
+export interface PartView {
+    part_index: number;
+    storage_kind: number;
+    network?: number;
+    blob_id: string;
+    patch_id?: string;
+}
+export interface PartsResponse {
+    size: number;
+    parts: PartView[];
+}
+export declare function asParts(value: unknown): PartsResponse;
+/**
+ * Fetch one part's sealed bytes.
+ *
+ * ⛔ Refuse before reading, not after. A part on a storage network this build has no reader for
+ *    would otherwise be fetched from a Walrus aggregator, 404, and be reported as missing bytes —
+ *    which is a different thing and sends somebody looking for the wrong one.
+ */
+export declare function fetchPart(part: PartView, chain: string, read: ReadOptions | undefined): Promise<Uint8Array>;
+/**
+ * Open ONE part and pass its contribution on, a chunk at a time. Returns how much of the file it
+ * contributed.
+ *
+ * ⛔ THE SEALED BYTES ARE FED IN ONE CHUNK AT A TIME, not all at once. Handing the engine the whole
+ *    part would make it hand back the whole part's plaintext in one array, which is the ceiling
+ *    this path exists to remove; feeding it a chunk's worth means at most one chunk of plaintext
+ *    exists at a time. The size fed is the format's own chunk plus its tag, so a well-formed
+ *    stream yields exactly one chunk per push — and a stream whose header declares a different
+ *    chunk size still works, because the engine buffers what it has not finished.
+ *
+ * ⛔ `finish()` IS WHAT CATCHES A PART CUT SHORT. Every chunk that arrived authenticates; only the
+ *    end-of-stream check knows the rest is missing. Skipping it would accept a truncated part.
+ *
+ * ⛔ THE ENGINE-SIDE SESSION IS FREED ON EVERY PATH OUT, including a failure: it holds the file
+ *    key until it is, and a download that failed is exactly when nobody comes back to tidy up.
+ */
+export declare function openPart(crypt: CryptoGlue, dek: Uint8Array, part: PartView, sealed: Uint8Array, isLast: boolean, remaining: number, emit: (body: Uint8Array) => Promise<void>): Promise<number>;

package/dist/download-sink.d.ts

@@ -0,0 +1,76 @@
+import { type ByteDestination } from "./stdout.ts";
+/**
+ * Somewhere a file's plaintext is delivered in order, and made visible only once.
+ *
+ * The shape is three-part on purpose: `write` moves bytes, `commit` is the only thing that may
+ * make them readable under the name somebody asked for, and `abandon` must leave nothing behind.
+ * A destination that cannot separate those three cannot hold the integrity promise above.
+ */
+export interface PlaintextSink {
+    /**
+     * The file's real length, from the sealed list, BEFORE a single stored part is fetched.
+     *
+     * ⛔ A destination that cannot take a file this size refuses HERE, where nothing has been read
+     *    from the network and nothing has been written. Discovering it half way through means the
+     *    refusal costs a download that was never going to be delivered.
+     */
+    expect(size: number): void;
+    /** Take the next run of plaintext, in order. Resolves when the bytes are no longer needed. */
+    write(bytes: Uint8Array): Promise<void>;
+    /**
+     * Everything checked: make the file visible, or hand it over.
+     *
+     * False means the reader closed the pipe before the file was done — see `handOver`. Every other
+     * failure throws: a caller must not be able to mistake "it stopped half way" for "delivered".
+     */
+    commit(): Promise<boolean>;
+    /** Something did not check out: leave nothing behind. Never throws. */
+    abandon(): Promise<void>;
+}
+/**
+ * Write to a file, through a temporary name beside it, renamed into place only when the whole
+ * file has been proved.
+ *
+ * ⛔ THE TEMPORARY FILE IS IN THE SAME DIRECTORY AS THE DESTINATION, not in a system temporary
+ *    directory, and that is the whole mechanism: `rename` is atomic only within one filesystem,
+ *    and only an atomic rename guarantees that a reader either sees nothing under the real name or
+ *    sees the finished file. A temporary directory can be — and on the machines this runs on
+ *    usually is — a different filesystem, where the same call becomes copy-then-delete and a
+ *    reader can catch the copy half done.
+ *
+ * ⛔ IT IS CREATED 0600 AND THE RENAME KEEPS THAT. The file is somebody's plaintext; it must not
+ *    be readable by other accounts on the machine for the seconds it takes to download, any more
+ *    than it may be afterwards.
+ */
+export declare function fileSink(destination: string, options: {
+    force: boolean;
+}): PlaintextSink;
+/**
+ * How much plaintext `--out -` will hold before it hands anything over. One part's worth.
+ *
+ * ⛔ NOT AN ARBITRARY NUMBER: it is the upload path's default part size, which is the most memory
+ *    this tool has ever asked for. Keeping the stdout ceiling there means the whole tool's bound
+ *    is one part plus one chunk whichever direction the bytes are going.
+ */
+export declare const STDOUT_HOLD_LIMIT: number;
+/**
+ * Hand the whole file to whatever is reading stdout — after it has been proved, not during.
+ *
+ * ⛔ THERE IS NO RENAME ON A PIPE, so the trick the file path uses is not available: a byte handed
+ *    to a reader cannot be taken back, and a reader that has already consumed half a file cannot
+ *    be told afterwards that the half was wrong. An exit code does not fix that — `nmts get x
+ *    --out - > y` leaves the truncated bytes in `y` whatever the exit code says, and an agent
+ *    reading a pipe usually acts on what it read. So this branch keeps the ORIGINAL guarantee
+ *    rather than the original size: the file is held, checked, and only then handed over, exactly
+ *    as before streaming existed.
+ *
+ * ⛔ WHICH MEANS IT HAS TO REFUSE SOMEWHERE, AND IT REFUSES OUT LOUD AND EARLY. Above the ceiling
+ *    the answer is a refusal naming `--out <name>`, which streams and is checked before the file
+ *    appears — not a silent trade of the guarantee for the size, and not the out-of-memory crash
+ *    that this used to be. `put` already refuses this way rather than discovering a limit halfway.
+ *
+ * ⚠ Every protection this branch already had is still here and still applies to the whole file:
+ *   bytes a terminal would act on are refused (`readableOnATerminal`), a reader that closed the
+ *   pipe first is an ordinary end and not a failure, and any other write failure throws.
+ */
+export declare function stdoutSink(to: ByteDestination, limit?: number): PlaintextSink;

package/dist/download.d.ts

@@ -0,0 +1,79 @@
+import type { PlaintextSink } from "./download-sink.ts";
+import type { ReadOptions } from "./walrus.ts";
+export interface FetchedFile {
+    /**
+     * How many plaintext bytes were delivered — the file's real length.
+     *
+     * ⚠ A COUNT, NOT THE BYTES. There is deliberately nothing here to read the file out of: the
+     *   plaintext went to the sink as it was produced and was zeroed behind it, and a field holding
+     *   it would put the ceiling this module exists to remove straight back.
+     */
+    byteCount: number;
+    /** How many stored objects it came from. */
+    partCount: number;
+    /** Whether the file's own sealed hash was there to check against, and matched. */
+    contentHashChecked: boolean;
+    /**
+     * Whether the whole file reached its destination.
+     *
+     * False has exactly one meaning: the program reading `--out -` closed the pipe before the file
+     * was done, which is an ordinary end and not a failure (`handOver`). Anything else throws.
+     */
+    delivered: boolean;
+}
+export interface FetchInput {
+    base: string;
+    apiKey: string;
+    accountCode: string;
+    itemId: string;
+    /** The file's real length, from the account's sealed file list. */
+    size: number;
+    /** Wrapped file key from the sealed file list. Without it nothing can be opened. */
+    dekWrapped: string;
+    /** Sealed whole-file hash from the sealed file list, when the account recorded one. */
+    contentHashCt?: string | undefined;
+    /**
+     * Which CHAIN this account's storage lives on — `mainnet` or `testnet`.
+     *
+     * ⛔ NOT the same question as a part's `network` field. That one says which STORAGE NETWORK holds
+     *    the bytes (Walrus, and so far only Walrus); this one picks which of that network's
+     *    aggregators to ask, because a blob id is meaningful on exactly one chain.
+     */
+    chain: string;
+    read?: ReadOptions;
+    /** Where the plaintext goes as it is decrypted. Committed only after the whole file checks out. */
+    sink: PlaintextSink;
+}
+/**
+ * Fetch, decrypt and verify one file.
+ *
+ * The NMTS key is used and not kept: the data key is derived, unwrapped keys are zeroed, and
+ * the derivation output — which holds every other key in the account — never outlives this call.
+ */
+/**
+ * Fetch, decrypt and verify one file whose key is ALREADY OPEN.
+ *
+ * ⛔ SPLIT OUT BECAUSE THERE ARE TWO WAYS TO GET THAT KEY, and only one of them belongs to the
+ *    account holding it. A file this account owns has its key wrapped in its own sealed list; a
+ *    file somebody SHARED has its key inside an envelope only this account can open, sealed under
+ *    a different separator, and its real length comes from what the sender sealed rather than from
+ *    the account's own list. Everything after the key is identical — and writing it twice is how
+ *    one copy comes to check the hash and the other does not.
+ */
+export declare function fetchWithKey(input: {
+    base: string;
+    apiKey: string;
+    /** Where the server describes the stored parts. Different for an owned and a shared file. */
+    descriptorPath: string;
+    /** The file's REAL plaintext length. */
+    size: number;
+    /** The file's own key, already unwrapped. Wiped here. */
+    dek: Uint8Array;
+    /** The whole-plaintext digest to check against, or null when none was recorded. */
+    expected: Uint8Array | null;
+    chain: string;
+    read?: ReadOptions;
+    /** Where the plaintext goes as it is decrypted. Committed only after the whole file checks out. */
+    sink: PlaintextSink;
+}): Promise<FetchedFile>;
+export declare function fetchFile(input: FetchInput): Promise<FetchedFile>;

package/dist/download.js

@@ -2,7 +2,7 @@
 //
 // ⛔ THE SERVER NEVER SEES THE FILE, AND NOTHING HERE TRUSTS IT WITH ONE. It says which stored
 //    objects a file is made of and how big the file is; every byte that becomes the file is
-//    decrypted here under a key derived from the account code, and the whole thing is checked
+//    decrypted here under a key derived from the NMTS key, and the whole thing is checked
 //    against a hash the account sealed for itself. A server that lies about the parts, or an
 //    aggregator that returns the wrong bytes, produces a refusal — never a quietly wrong file.
 //
@@ -34,7 +34,7 @@ import { NmtsError } from "./errors.js";
 /**
  * Fetch, decrypt and verify one file.
  *
- * The account code is used and not kept: the data key is derived, unwrapped keys are zeroed, and
+ * The NMTS key is used and not kept: the data key is derived, unwrapped keys are zeroed, and
  * the derivation output — which holds every other key in the account — never outlives this call.
  */
 /**
@@ -74,7 +74,7 @@ export async function fetchFile(input) {
     catch {
         dataKey.fill(0);
         throw new NmtsError("This file's key did not open with this account's key.", {
-            nextStep: "Either the account code belongs to somebody else, or the file list has been altered.",
+            nextStep: "Either the NMTS key belongs to somebody else, or the file list has been altered.",
         });
     }
     let expected = null;

package/dist/drive-paths.d.ts

@@ -0,0 +1,73 @@
+import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+import { buildIndex, isLive, type ManifestIndex, trashedAt } from "./shared/lib/drive/manifest-index.ts";
+/** Folder. The same numeric codes the items API uses. */
+export declare const KIND_FOLDER = 0;
+/** File. */
+export declare const KIND_FILE = 1;
+export { buildIndex, isLive, trashedAt };
+export type { ManifestIndex };
+/**
+ * The full path of one entry, marked when the walk could not reach the root.
+ *
+ * ⚠ The `seen` set is not defensive tidiness: a list where two folders are each other's parent
+ *   would loop forever, and a list is a file that can arrive from anywhere.
+ */
+export declare function fullPathOf(index: ManifestIndex, entry: ManifestEntry): string;
+/**
+ * `/photos/2026/` and `./photos/2026` and `photos/2026` are one path.
+ *
+ * ⛔ AND SO ARE THE TWO SPELLINGS OF `café`. Unicode gives the same visible name more than one
+ *    byte sequence — macOS hands back the decomposed form from the shell and the filesystem while
+ *    a browser typically wrote the composed one. Comparing raw bytes meant `nmts rm café` could
+ *    address a DIFFERENT entry from the one on screen. Both sides of every comparison here are
+ *    folded to one form; what gets STORED is untouched, because the name belongs to whoever wrote
+ *    it.
+ */
+/**
+ * Strip a folder's own path off one of its descendants, in DRIVE terms.
+ *
+ * ⛔ IT IS STRING ARITHMETIC AND NOT `node:path`. A drive path always uses `/`, whatever separator
+ *    the machine reading it happens to use, and `path.relative` answers in the MACHINE's
+ *    separator. On Windows that turned `deep/under.txt` into `deep\under.txt`, which the
+ *    containment check downstream then refused as a name trying to leave its directory — so
+ *    fetching a folder failed outright on one of the three platforms this tool ships for, and
+ *    every test passed, because on the other two the two separators are the same character.
+ *    ⚠ That is the whole class: a drive path and a path on this disk are different kinds of thing,
+ *    and `node:path` is only ever right about the second.
+ *
+ * A path that is not under the prefix comes back unchanged — the caller decides what that means.
+ */
+export declare function underPrefix(prefix: string, drivePath: string): string;
+export declare function normalisePath(input: string): string;
+/** The same folding, for one name rather than a path. */
+export declare function normaliseName(name: string): string;
+export interface FindOptions {
+    /** Include entries in the trash. Off by default — `rm` twice must not find its own work. */
+    includeTrashed?: boolean;
+    /** Only entries of this kind. */
+    kind?: number;
+    /** What the caller is about to do, for the refusal's second line. */
+    nothingHappened?: string;
+}
+/**
+ * The one entry at this path, or a refusal saying which of the two ways it failed.
+ *
+ * ⛔ EXIT CODE 4, NOT 1: the command exists and could not do it, which is a different thing from
+ *    the command being wrong. An agent is told to stop rather than to retry.
+ */
+export declare function entryAt(entries: readonly ManifestEntry[], path: string, options?: FindOptions): ManifestEntry;
+/**
+ * The folder id a destination names, or null for the top of the drive.
+ *
+ * ⚠ An empty destination is the ROOT, and that is not the same as "no destination given" being an
+ *   error: `--to ""` and `--to /` both mean the top, which is what somebody types to move
+ *   something back out of a folder.
+ */
+export declare function folderIdFor(wanted: string | undefined, entries: readonly ManifestEntry[], nothingHappened?: string): string | null;
+/**
+ * The names already used in one folder — what a new or renamed entry must not collide with.
+ *
+ * ⚠ Folded the same way paths are, so the two spellings of one visible name count as one taken
+ *   name. Two entries a person cannot tell apart are worse than a refusal they can act on.
+ */
+export declare function namesIn(entries: readonly ManifestEntry[], parentId: string | null): Set<string>;

package/dist/environment.d.ts

@@ -0,0 +1,62 @@
+import { type HostSighting } from "./agent-host.ts";
+/** How this process is contained, as far as it can tell. */
+export type Containment = "docker" | "podman" | "container" | "none" | "unknown";
+export interface Environment {
+    /** `linux`, `darwin`, `win32`, … — what Node reports, not a guess. */
+    os: NodeJS.Platform;
+    osRelease: string;
+    /** Node's own version. An agent choosing between behaviours may care. */
+    node: string;
+    containment: Containment;
+    /**
+     * Is root here somebody else on the host?
+     *
+     * ⚠ NOT THE SAME QUESTION AS `uid`. A rootless container is uid 0 inside and an ordinary user
+     *   outside; a rootful one is root in both places. `null` where it cannot be measured.
+     */
+    rootMapped: boolean | null;
+    /** The effective user id INSIDE this process's namespace, where the platform has one. */
+    uid: number | null;
+    /** Can a file here be kept private? MEASURED — see `codeStorageIsPrivate`. */
+    privateStorage: boolean;
+    /** Where anything this tool keeps would go. */
+    configDir: string;
+    /** Is there a person at a keyboard? A prompt is impossible without one. */
+    interactive: boolean;
+    /** Could a browser be opened here — needed for anything behind a human check. */
+    browserReachable: boolean;
+    /**
+     * Which agent hosts left a marker in this environment.
+     *
+     * ⚠ EVERY ONE OF THESE IS AN ANCESTOR, NOT NECESSARILY THE PARENT — markers are inherited, so a
+     *   tool started by an agent that was itself started by another agent sees both. The direct
+     *   parent is only knowable over the protocol, and that lives in the MCP server, not here.
+     *   Empty means no marker was found, which includes every host that clears the environment.
+     */
+    agentHosts: HostSighting[];
+}
+/**
+ * Is this a container, and which kind?
+ *
+ * The three signals, in order of how much they actually prove:
+ *   · `/run/.containerenv` — Podman writes it, and it names its own settings inside.
+ *   · `/.dockerenv` — Docker writes it and has for a decade.
+ *   · the process's own cgroup line naming a runtime.
+ * On a platform where none of those files can exist the answer is `unknown`, not `none`.
+ */
+export declare function detectContainment(): Containment;
+export declare function readEnvironment(): Environment;
+/** One fact worth acting on, and what to do about it. */
+export interface Advice {
+    /** `warn` is something to tell the person about. `note` is context. */
+    level: "warn" | "note";
+    text: string;
+}
+/**
+ * What this environment means, in the terms somebody has to decide in.
+ *
+ * ⛔ WRITTEN FOR AN AGENT TO REPEAT TO A PERSON. Each line is a complete sentence about a fact
+ *    that was measured here, so passing it along loses nothing. None of it is an instruction
+ *    aimed past the reader.
+ */
+export declare function adviseFor(env: Environment, hasStoredCode: boolean): Advice[];

package/dist/environment.js

@@ -1,4 +1,4 @@
-// Working out where this tool is running, and what that means for the account code.
+// Working out where this tool is running, and what that means for the NMTS key.
 //
 // ⛔ IT IS FOR THE AGENT, AND THE AGENT IS FOR THE PERSON. A program driving this tool cannot see
 //    what a person can — whether it is inside a container, whether the home directory survives the
@@ -16,6 +16,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { platform, release, tmpdir, userInfo } from "node:os";
 import { configDir, codeStorageIsPrivate, modesAreEnforced } from "./credentials.js";
+import { HOST_NAMES, hostsInEnvironment, washingHosts } from "./agent-host.js";
+import { BINARY_NAME } from "./product.js";
 /**
  * Is this a container, and which kind?
  *
@@ -104,6 +106,7 @@ export function readEnvironment() {
         configDir: configDir(),
         interactive: process.stdin.isTTY === true,
         browserReachable: canOpenBrowser(),
+        agentHosts: hostsInEnvironment(),
     };
 }
 /**
@@ -118,8 +121,8 @@ export function adviseFor(env, hasStoredCode) {
     if (!env.privateStorage) {
         out.push({
             level: "warn",
-            text: `This filesystem does not keep the mode a file is written with, so a stored account code ` +
-                `could be read by anything else that can reach ${env.configDir}. Supplying the code for ` +
+            text: `This filesystem does not keep the mode a file is written with, so a stored NMTS key ` +
+                `could be read by anything else that can reach ${env.configDir}. Supplying the NMTS key for ` +
                 `each run instead of storing it avoids that.`,
         });
     }
@@ -127,13 +130,13 @@ export function adviseFor(env, hasStoredCode) {
         out.push({
             level: "note",
             text: `This is a ${env.containment} container. Anything written to ${env.configDir} is lost when ` +
-                `it is removed unless that path is a volume, so a stored account code will not be there ` +
+                `it is removed unless that path is a volume, so a stored NMTS key will not be there ` +
                 `next time.`,
         });
         out.push({
             level: "warn",
-            text: `Do not pass the account code as an environment variable in a container: the whole ` +
-                `environment is visible to anybody who can inspect it. Put the code in a file and name ` +
+            text: `Do not pass the NMTS key as an environment variable in a container: the whole ` +
+                `environment is visible to anybody who can inspect it. Put the NMTS key in a file and name ` +
                 `that file in NMTS_ACCOUNT_CODE_FILE, or pipe it in.`,
         });
         // ⛔ TWO DIFFERENT FACTS, and conflating them is how "rootless" gets reported backwards. What
@@ -162,7 +165,7 @@ export function adviseFor(env, hasStoredCode) {
     if (!env.interactive && !hasStoredCode) {
         out.push({
             level: "warn",
-            text: `There is no terminal here, so this tool cannot ask for the account code. It has to ` +
+            text: `There is no terminal here, so this tool cannot ask for the NMTS key. It has to ` +
                 `arrive in the environment or in a file named by NMTS_ACCOUNT_CODE_FILE.`,
         });
     }
@@ -170,13 +173,13 @@ export function adviseFor(env, hasStoredCode) {
         out.push({
             level: "note",
             text: `No browser can be opened here. Anything that needs a human check — making an account, ` +
-                `applying for the free trial — has to be done on a machine that has one.`,
+                `renewing the account's four-week check — has to be done on a machine that has one.`,
         });
     }
     if (env.os === "win32") {
         out.push({
             level: "note",
-            text: `Windows applies no POSIX file mode, so a stored account code inherits the folder's ` +
+            text: `Windows applies no POSIX file mode, so a stored NMTS key inherits the folder's ` +
                 `permissions rather than being restricted to one user.`,
         });
     }
@@ -186,5 +189,22 @@ export function adviseFor(env, hasStoredCode) {
             text: `The configuration directory is inside the temporary directory and may be cleared at any time.`,
         });
     }
+    // ⛔ THE ONE THING THAT SURPRISES PEOPLE. Three of the five agents this tool knows clear the
+    //    environment before starting an MCP server and put back a fixed list of names — none of
+    //    which is ours. So a person who exported the NMTS key, attached the tool, and watched
+    //    it say "not found" did everything right; the value was dropped between the two. Saying so
+    //    while the marker is still visible (in the shell, where nothing has been cleared yet) is the
+    //    only moment it can be said before the failure rather than after it.
+    const washing = washingHosts(env.agentHosts);
+    if (washing.length > 0) {
+        const names = washing.map((id) => HOST_NAMES[id]).join(" and ");
+        out.push({
+            level: "warn",
+            text: `${names} clears the environment before starting an MCP server and restores only a fixed ` +
+                `list of names, which does not include NMTS_ACCOUNT_CODE or NMTS_ACCOUNT_CODE_FILE. Those ` +
+                `work in a terminal here and will not reach the tool once it is attached. Sign in once ` +
+                `with \`${BINARY_NAME} login\` so the NMTS key is in this tool's own file instead.`,
+        });
+    }
     return out;
 }

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/** A failure this tool understood, with an exit code and something the caller can do. */
+export declare class NmtsError extends Error {
+    readonly exitCode: number;
+    /** One line naming the next action, or null when there is nothing useful to suggest. */
+    readonly nextStep: string | null;
+    constructor(message: string, options?: {
+        exitCode?: number;
+        nextStep?: string | null;
+    });
+}
+/** Nothing is signed in on this machine and no code was supplied. */
+export declare class NotLoggedInError extends NmtsError {
+    constructor(binary: string, envVar: string);
+}
+/** The command exists but is not built yet. Said plainly rather than failing as if it broke. */
+export declare class NotBuiltYetError extends NmtsError {
+    constructor(what: string);
+}
+/** Render a failure for a terminal an agent is reading. */
+export declare function renderError(error: unknown, binary: string): string;
+/** Exit code for an unknown failure, kept distinct from the ones above. */
+export declare const UNKNOWN_FAILURE_EXIT = 1;

package/dist/errors.js

@@ -5,7 +5,7 @@
 //    tells an agent nothing it can use; "your API key was revoked — issue a new one at
 //    nmts.me/account" tells it whether to retry, ask, or stop.
 //
-// ⛔ NOTHING SECRET IS EVER INTERPOLATED. Not the account code, not the API key, not a session
+// ⛔ NOTHING SECRET IS EVER INTERPOLATED. Not the NMTS key, not the API key, not a session
 //    token. An error string is the one place a secret escapes without anybody choosing to print
 //    it, and agents copy error strings into logs and prompts by default.
 //
@@ -13,7 +13,7 @@
 //    unknown error's `message` goes out verbatim, which is right (a swallowed cause is a debug
 //    session nobody can start) and is also a hole: an adversarial review made `JSON.parse` fail on
 //    the credentials file, and V8's own message quotes about thirty characters of the input —
-//    nine symbols of a real account code reached stderr. The fix is not here. It is that anything
+//    nine symbols of a real NMTS key reached stderr. The fix is not here. It is that anything
 //    reading a file the code is in must catch its own parser and throw a message of its own
 //    (`credentials.ts`, `unusable`). ▶ Any NEW code that parses a secret-bearing file owes the
 //    same, and this paragraph is the reason why.
@@ -32,7 +32,7 @@ export class NmtsError extends Error {
 /** Nothing is signed in on this machine and no code was supplied. */
 export class NotLoggedInError extends NmtsError {
     constructor(binary, envVar) {
-        super(`No NMTS account code on this machine.`, {
+        super(`No NMTS key on this machine.`, {
             exitCode: 3,
             nextStep: `Run \`${binary} login\`, or set ${envVar} in the environment.`,
         });

package/dist/exit.d.ts

@@ -0,0 +1,44 @@
+/** The exit code a failure asks for, or the generic one. */
+export declare function exitCodeFor(error: unknown): number;
+/**
+ * Stop a closed pipe from becoming a crash.
+ *
+ * ⛔ `nmts ls | head` IS AN ORDINARY THING TO DO, and without this it prints a ten-line stack
+ *    trace instead of the answer. `head` closes the pipe once it has its lines; the next write
+ *    raises EPIPE, and Node turns an unhandled stream error into a fatal one. Every shell tool is
+ *    expected to end quietly there — that is what SIGPIPE does for programs that do not intercept
+ *    it — and an agent piping this into anything would otherwise read a crash and conclude the
+ *    tool is broken.
+ *
+ * ⚠ ONLY EPIPE. A write that fails for any other reason is still a real failure and still throws;
+ *   swallowing all stream errors would hide a full disk behind silence.
+ */
+export declare function endQuietlyOnClosedPipe(): void;
+/**
+ * Is the module at `moduleFilename` the program, or is something importing it?
+ *
+ * ⛔ THE FILENAME IS PASSED IN AND NOT READ HERE. `import.meta.filename` inside this module
+ *    would name THIS file, which is never the program; the caller's own is the question.
+ *
+ * ⛔ THE COMPARISON IS BETWEEN REAL PATHS, AND THAT IS THE WHOLE POINT. `npm install -g` does not
+ *    copy the command onto your PATH — it puts a SYMLINK there, pointing at `dist/main.js` inside
+ *    the installed package. Node then loads the module by its real
+ *    path, so the module's own name is `.../dist/main.js` while `process.argv[1]` is
+ *    `.../bin/nmts`. Comparing those two directly is never true for an installed command: `nmts --version` printed NOTHING and exited 0, and
+ *    so did every other command. The whole tool did nothing at all, silently, and only when
+ *    installed — which is the one way a person who is not us runs it.
+ *
+ * ⚠ `realpathSync` THROWS on a path that is not there. `process.argv[1]` normally exists, but a
+ *   caller is free to hand Node something else, and a crash before the first line of output would
+ *   be a worse answer than not running. Not resolving is treated as "not the program", which is
+ *   the same answer this was giving before symlinks were considered at all.
+ */
+export declare function invokedDirectly(moduleFilename: string): boolean;
+/**
+ * Say so if a newer release is already known about, and refresh what is known for next time.
+ *
+ * ⛔ AFTER THE COMMAND, NOT BEFORE IT. Whatever was asked for has already been printed and the
+ *    exit code is already decided; nothing here can change either. ⛔ AND ONLY FROM `main`: the
+ *    tests drive `run` directly, so no test and no embedded caller ever reaches a network.
+ */
+export declare function noteUpdateAfter(argv: readonly string[], version: string): Promise<void>;

package/dist/expiry.d.ts

@@ -0,0 +1,58 @@
+import { NOTICE_DAYS, NOTICE_EPOCHS, URGENT_DAYS, URGENT_EPOCHS, type DaysLeft } from "./shared/lib/extend/epochs.ts";
+export { NOTICE_DAYS, NOTICE_EPOCHS, URGENT_DAYS, URGENT_EPOCHS };
+export type { DaysLeft };
+/** Where the storage network's clock stands. Built by `epochClock`, never assembled by hand. */
+export interface EpochClock {
+    /** The epoch the network is in. */
+    readonly current: number;
+    /** One epoch's length in milliseconds — read from the network, never assumed. */
+    readonly durationMs: number;
+    /** When the current epoch began, or null when the network did not say. */
+    readonly startedMs: number | null;
+}
+/**
+ * A clock, or null when what the network answered cannot be counted with.
+ *
+ * ⛔ THE INVARIANT LIVES IN THE TYPE, so every function below can divide by `durationMs` without
+ *    asking again. A zero or a NaN out of a chain read would otherwise become an Infinity printed
+ *    as a number of days, and there would be no single place to have caught it.
+ */
+export declare function epochClock(current: number, durationMs: number, startedMs: number | null): EpochClock | null;
+/**
+ * How far ahead a warning stage reaches, in epochs: a floor in days and a floor in epochs, wider
+ * one wins.
+ *
+ * The day count rounds UP, because arriving a tick late is the quiet failure the whole surface
+ * exists to prevent.
+ */
+export declare function warningEpochs(clock: EpochClock, days: number, floorEpochs: number): number;
+/**
+ * Whole days from `nowMs` until `epoch` is reached, by the network's own clock.
+ *
+ * With an anchor both ends collapse onto one moment. Without one, the honest answer is the
+ * earliest the epoch can arrive — see the header for why the other edge is never used.
+ */
+export declare function daysLeftUntilEpoch(clock: EpochClock, epoch: number, nowMs: number): DaysLeft;
+/**
+ * How much trouble one file's storage term is in.
+ *
+ * `lapsed` is not a prediction: the term ran out and the bytes may already be unreadable. It is
+ * kept separate from `urgent` because the action differs — an urgent file can still be extended,
+ * a lapsed one usually cannot.
+ */
+export type ExpiryStage = "unrecorded" | "lapsed" | "urgent" | "soon" | "later";
+export declare function stageOf(clock: EpochClock, expiryEpoch: number, nowMs: number): ExpiryStage;
+/**
+ * The epoch to ask the server about: everything ending before this is inside the warning window.
+ *
+ * The cutoff is computed HERE and sent as an absolute number because the server does not read the
+ * chain and cannot work it out — `GET /v1/items/expiring` takes the answer, not the question.
+ */
+export declare function warningCutoffEpoch(clock: EpochClock): number;
+/**
+ * How long is left, said the way a person reads it.
+ *
+ * ⚠ "or more" is not hedging: it is the difference between a measurement and a floor, and dropping
+ *   it would turn a lower bound into a promise about a deletion date.
+ */
+export declare function daysLeftInWords(left: DaysLeft): string;

package/dist/extend-budget.d.ts

@@ -0,0 +1,35 @@
+import type { ExtendReads } from "./extend-plan.ts";
+export interface Budget {
+    /** The address that would sign — the one `nmts wallet` prints and the one somebody funds. */
+    readonly address: string;
+    /** What the extension costs, in FROST. */
+    readonly priceFrost: bigint;
+    /** Held now, in base units — or null when the chain could not answer. */
+    readonly walFrost: bigint | null;
+    readonly suiMist: bigint | null;
+    /** The chain fee the dry run measured, in MIST — or null when it could not be measured. */
+    readonly feeMist: bigint | null;
+    /** Why each unread balance could not be read, in the words the chain gave. */
+    readonly unread: readonly string[];
+    /** What the wallet is known to be short of, or null when nothing known says it is short. */
+    readonly shortfall: string | null;
+}
+/** Read the wallet and measure the fee, then say whether the known numbers cover the purchase. */
+export declare function readBudget(reads: ExtendReads, input: {
+    address: string;
+    objectIds: readonly string[];
+    epochs: number;
+    priceFrost: bigint;
+}): Promise<Budget>;
+/** The budget as the machine-readable answer carries it. ⚠ Base units are strings — see `Facts`. */
+export declare function budgetFacts(b: Budget): {
+    wallet: string;
+    walletWal: string | null;
+    walletSui: string | null;
+    feeMist: string | null;
+    feeSui: string | null;
+};
+/** The next step when the wallet is short: where to send what, said once. */
+export declare function shortfallNextStep(b: Budget): string;
+/** The fee and the wallet, for a person, after the price. */
+export declare function describeBudget(say: (line: string) => void, b: Budget): void;