@needmoretruth/nmts-cli 0.17.2

package/dist/download.js

@@ -0,0 +1,163 @@
+// Getting one file's bytes back: ask the server where the parts are, read them, open them, check them.
+//
+// ⛔ 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
+//    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.
+//
+// ⛔ ONLY THE LAST PART MAY BE PADDED. That is the write side's promise (a part carries the bytes
+//    it declares, and only the last is rounded up to hide the true size), and it is what makes the
+//    answer unique: with padding allowed anywhere, several splits would fit the same numbers and a
+//    reader would be guessing which one produced the file. It is checked here rather than assumed.
+//
+// ⛔⭐ THE FILE IS NEVER HELD, AND THE INTEGRITY PROMISE MOVED RATHER THAN WEAKENED. This used to
+//    keep every decrypted byte, check the whole-file digest, and hand back a finished array — so
+//    nothing wrong could ever reach a destination. It also meant a file that could be UPLOADED
+//    (part by part, bounded by one part) could not be brought back on a machine smaller than the
+//    file: the ceiling had simply moved to the other direction. Plaintext now flows to a
+//    `PlaintextSink` as it is produced, and the promise is kept by the destination instead — a
+//    file lands under a temporary name in the destination's own directory and is renamed into
+//    place only after the digest matches, and `--out -` still proves the whole file before it
+//    hands over a byte because a pipe has no rename (`download-sink.ts` carries both arguments).
+//
+// ⛔ WHAT ONE DOWNLOAD COSTS IN MEMORY IS NOW ONE PART PLUS ONE CHUNK, not the file: the sealed
+//    bytes of the part being read (64 MiB by default, whatever `--part-size` the uploader chose),
+//    the engine's own buffer for the chunk it is assembling, and the one chunk of plaintext it
+//    hands back — 4 MiB each in NCF-3. A hundred-gigabyte file costs the same as a hundred-megabyte
+//    one. The exception is `--out -`, which is bounded by `STDOUT_HOLD_LIMIT` and refuses above it.
+import { createHash } from "node:crypto";
+import { request } from "./api.js";
+import { AAD, DERIVED, loadCrypto } from "./crypto.js";
+import { asParts, fetchPart, openPart } from "./download-part.js";
+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 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 async function fetchWithKey(input) {
+    const described = asParts(await request(input.base, input.descriptorPath, { token: input.apiKey }));
+    if (described.parts.length === 0) {
+        throw new NmtsError("The server says this file has no stored parts.", {
+            nextStep: "Nothing was written. The file list names it, so open the account in a browser and compare.",
+        });
+    }
+    // ⛔ The server's `size` is a hint; the length the caller was given is the authority.
+    const ordered = [...described.parts].sort((a, b) => a.part_index - b.part_index);
+    const crypt = await loadCrypto();
+    const dek = input.dek;
+    const expected = input.expected;
+    return collect(crypt, ordered, dek, expected, input.size, input.chain, input.read, input.sink);
+}
+export async function fetchFile(input) {
+    const crypt = await loadCrypto();
+    const [from, to] = DERIVED.dataKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(input.accountCode));
+    const dataKey = derived.slice(from, to);
+    derived.fill(0);
+    let dek;
+    try {
+        dek = crypt.envelope_open(dataKey, new TextEncoder().encode(AAD.dekWrap), Buffer.from(input.dekWrapped, "base64url"));
+    }
+    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.",
+        });
+    }
+    let expected = null;
+    if (input.contentHashCt !== undefined && input.contentHashCt !== "") {
+        try {
+            expected = crypt.envelope_open(dataKey, new TextEncoder().encode(AAD.contentHash), Buffer.from(input.contentHashCt, "base64url"));
+        }
+        catch {
+            dataKey.fill(0);
+            dek.fill(0);
+            throw new NmtsError("This file's recorded hash did not open with this account's key.");
+        }
+    }
+    dataKey.fill(0);
+    return fetchWithKey({
+        base: input.base,
+        apiKey: input.apiKey,
+        descriptorPath: `/v1/items/${encodeURIComponent(input.itemId)}/parts?for=download`,
+        size: input.size,
+        dek,
+        expected,
+        chain: input.chain,
+        sink: input.sink,
+        ...(input.read === undefined ? {} : { read: input.read }),
+    });
+}
+/**
+ * Read every part, open it as it arrives, pass on exactly what it contributes, and check the
+ * whole against a hash before any of it is made visible.
+ *
+ * ⛔ ONLY THE LAST PART MAY BE PADDED. Every part but the last contributes all of itself; the last
+ *    is trimmed to what is left of the file. That is the write side's promise, and it is what
+ *    makes the arithmetic have one answer instead of several.
+ *
+ * ⛔ THE SINK IS COMMITTED IN EXACTLY ONE PLACE — after the parts add up AND the digest matches —
+ *    and abandoned on every other way out of this function. That pairing is the whole of the
+ *    integrity guarantee now that bytes move before the last chunk is checked: a reader either
+ *    sees the finished file or sees nothing under that name.
+ */
+async function collect(crypt, ordered, dek, expected, size, chain, read, sink) {
+    const hasher = createHash("sha256");
+    let remaining = size;
+    try {
+        // ⛔ Asked before a byte is fetched. A destination that cannot take a file this size says so
+        //    now, while "nothing was written" is still free.
+        sink.expect(size);
+        for (let i = 0; i < ordered.length; i += 1) {
+            const part = ordered[i];
+            if (part === undefined)
+                continue;
+            const sealed = await fetchPart(part, chain, read);
+            remaining -= await openPart(crypt, dek, part, sealed, i === ordered.length - 1, remaining, async (body) => {
+                hasher.update(body);
+                await sink.write(body);
+            });
+        }
+        if (remaining !== 0) {
+            throw new NmtsError(`The stored parts are ${remaining} bytes short of the file this list describes.`, {
+                nextStep: "Nothing was written. Open the account in a browser and compare before uploading anything again.",
+            });
+        }
+        if (expected !== null) {
+            const got = hasher.digest();
+            const same = expected.length === got.length && expected.every((b, i) => b === got[i]);
+            expected.fill(0);
+            if (!same) {
+                throw new NmtsError("The file came back whole but does not match the hash this account recorded for it.", {
+                    nextStep: "Nothing was written. Every part decrypted, so this is not a wrong key — the bytes " +
+                        "themselves are not the ones that were uploaded.",
+                });
+            }
+        }
+        const delivered = await sink.commit();
+        return { byteCount: size, partCount: ordered.length, contentHashChecked: expected !== null, delivered };
+    }
+    catch (failure) {
+        // ⛔ EVERY way out that is not the commit above leaves nothing behind — a wrong network, a
+        //    part that would not open, arithmetic that does not add up, a digest that does not match,
+        //    a disk that filled. This is the one place that knows the download did not finish.
+        await sink.abandon();
+        throw failure;
+    }
+    finally {
+        dek.fill(0);
+    }
+}

package/dist/drive-paths.js

@@ -0,0 +1,170 @@
+// Turning a path a person typed into an entry in the sealed file list, and back.
+//
+// ⛔ PATHS ARE NOT STORED — THEY ARE COMPUTED. The list holds a name and a parent id per entry, so
+//    "photos/2026/a.jpg" exists only as the walk from a.jpg up to the root. Two folders may share
+//    a last name at different depths, which is why every lookup here matches the WHOLE path and
+//    why an ambiguous one is refused rather than resolved to the first hit.
+//
+// ⛔ AND NOTHING HERE GUESSES. A path that names nothing, and a path that names two things, are
+//    both refusals with their own words. A command that picked one would eventually pick wrong on
+//    somebody's account and delete the other file.
+//
+// ⛔ "IN THE TRASH" IS INHERITED, NOT STAMPED (2026-08-23, found by adversarial review).
+//    Trashing a folder marks the FOLDER and nothing under it, on purpose: stamping the children
+//    would restart each one's own thirty-day clock and make "restore" ambiguous. So an entry is in
+//    the trash when it OR ANY ANCESTOR carries `deletedAt`, and reading only `entry.deletedAt` is
+//    wrong. This file used to do exactly that, and the result was a drive that listed files whose
+//    bytes the server had already stopped serving — the one state this tool is built to avoid.
+//    ▶ The walk lives in the browser's index module, which is copied here byte for byte.
+//
+// ⛔ ONE PATH FUNCTION, NOT THREE. `ls`, `get` and the lookups below each had their own walk, and
+//    two of them disagreed about a broken parent chain — so `ls` printed a path (`…/a.txt`) that no
+//    command would accept, while an unrelated healthy file at `a.txt` became unaddressable because
+//    the third walk silently resolved the orphan to the same string. **The path that is printed
+//    must be the path that matches**, so there is one function and everybody calls it.
+import { NmtsError } from "./errors.js";
+import { buildIndex, isLive, KIND_FILE as SHARED_KIND_FILE, KIND_FOLDER as SHARED_KIND_FOLDER, trashedAt, } from "./shared/lib/drive/manifest-index.js";
+/** Folder. The same numeric codes the items API uses. */
+export const KIND_FOLDER = SHARED_KIND_FOLDER;
+/** File. */
+export const KIND_FILE = SHARED_KIND_FILE;
+export { buildIndex, isLive, trashedAt };
+/**
+ * What a broken parent chain is drawn as.
+ *
+ * ⚠ It is deliberately a character nobody types. An entry whose parent is missing HAS no path a
+ *   person can name, and pretending it sits at the root would let one orphan take a healthy file
+ *   hostage: two different entries would answer to the same string and every command would refuse
+ *   both as ambiguous.
+ */
+const DETACHED = "…";
+/**
+ * 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 function fullPathOf(index, entry) {
+    const parts = [entry.name];
+    const seen = new Set([entry.id]);
+    let parentId = entry.parentId;
+    let detached = false;
+    while (parentId !== null) {
+        const parent = index.byId.get(parentId);
+        if (parent === undefined || seen.has(parent.id)) {
+            detached = true;
+            break;
+        }
+        seen.add(parent.id);
+        parts.unshift(parent.name);
+        parentId = parent.parentId;
+    }
+    if (detached)
+        parts.unshift(DETACHED);
+    return parts.join("/");
+}
+/**
+ * `/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 function underPrefix(prefix, drivePath) {
+    if (prefix === "")
+        return drivePath;
+    const head = prefix.endsWith("/") ? prefix : `${prefix}/`;
+    return drivePath.startsWith(head) ? drivePath.slice(head.length) : drivePath;
+}
+export function normalisePath(input) {
+    const stripped = input.replace(/^\.?\/+/u, "").replace(/\/+$/u, "").normalize("NFC");
+    // A bare "." is where you already are — the top of the drive, not a folder called ".".
+    return stripped === "." ? "" : stripped;
+}
+/** The same folding, for one name rather than a path. */
+export function normaliseName(name) {
+    return name.normalize("NFC");
+}
+/**
+ * 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 function entryAt(entries, path, options = {}) {
+    const target = normalisePath(path);
+    if (target === "") {
+        throw new NmtsError(`"${path}" names the whole drive, not one thing in it.`, { exitCode: 2 });
+    }
+    const index = buildIndex(entries);
+    const at = (e) => normalisePath(fullPathOf(index, e)) === target;
+    const matches = entries.filter((e) => (options.includeTrashed === true || isLive(index, e)) &&
+        (options.kind === undefined || e.kind === options.kind) &&
+        at(e));
+    const only = matches[0];
+    if (only === undefined) {
+        // ⛔ A path that exists BUT IS IN THE TRASH gets its own sentence. "No such thing" would send
+        //    somebody looking for a typo when what they need is `--all` or `restore`.
+        const trashed = entries.some((e) => !isLive(index, e) && at(e));
+        throw new NmtsError(trashed ? `"${target}" is in the trash.` : `Nothing in this account is at "${target}".`, {
+            exitCode: 4,
+            nextStep: trashed
+                ? `${options.nothingHappened ?? "Nothing changed."} \`nmts ls --all\` lists the trash.`
+                : `${options.nothingHappened ?? "Nothing changed."} \`nmts ls\` lists what is there.`,
+        });
+    }
+    if (matches.length > 1) {
+        throw new NmtsError(`"${target}" names ${matches.length} things in this account.`, {
+            exitCode: 4,
+            nextStep: `${options.nothingHappened ?? "Nothing changed."} Rename one of them first.`,
+        });
+    }
+    return only;
+}
+/**
+ * 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 function folderIdFor(wanted, entries, nothingHappened) {
+    if (wanted === undefined)
+        return null;
+    const target = normalisePath(wanted);
+    if (target === "" || target === ".")
+        return null;
+    return entryAt(entries, target, { kind: KIND_FOLDER, ...(nothingHappened ? { nothingHappened } : {}) }).id;
+}
+/**
+ * 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 function namesIn(entries, parentId) {
+    const taken = new Set();
+    for (const e of entries) {
+        // A trashed entry still holds its name: restoring it must not land on top of a live one.
+        if (e.parentId === parentId)
+            taken.add(normaliseName(e.name));
+    }
+    return taken;
+}

package/dist/environment.js

@@ -0,0 +1,190 @@
+// Working out where this tool is running, and what that means for the account code.
+//
+// ⛔ 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
+//    next run, whether the code it was handed can be kept private here. Those are the facts that
+//    decide whether an upload is safe to start, and they are exactly the facts nobody thinks to
+//    mention. So they are measured and printed.
+//
+// ⛔ EVERY ANSWER IS MEASURED OR "UNKNOWN". There is no guessing here: not knowing is a fact worth
+//    reporting, and an invented one is worse than a missing one. The failure this avoids is the
+//    tool cheerfully saying "not a container" on a runtime it has never heard of.
+//
+// ⚠ NOTHING HERE IS A SECURITY BOUNDARY. Everything below is discoverable by anything running in
+//   the same place; none of it protects anything. It exists so that what happens next is a
+//   decision rather than a surprise.
+import { existsSync, readFileSync } from "node:fs";
+import { platform, release, tmpdir, userInfo } from "node:os";
+import { configDir, codeStorageIsPrivate, modesAreEnforced } from "./credentials.js";
+/**
+ * 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 function detectContainment() {
+    if (platform() !== "linux")
+        return "unknown";
+    if (existsSync("/run/.containerenv"))
+        return "podman";
+    if (existsSync("/.dockerenv"))
+        return "docker";
+    try {
+        const cgroup = readFileSync("/proc/1/cgroup", "utf8");
+        if (/\b(docker|podman|containerd|kubepods|lxc)\b/.test(cgroup))
+            return "container";
+        // PID 1 in a plain cgroup-v2 root line is what an ordinary host looks like.
+        return "none";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Is this process inside a USER NAMESPACE that maps root to somebody else?
+ *
+ * ⛔ THIS IS WHAT "ROOTLESS" ACTUALLY MEANS, and measuring the uid instead gets it backwards.
+ *    A rootless Podman container runs as uid 0 INSIDE — so "am I root?" answers yes — while that
+ *    0 maps to an ordinary user on the host, which is the whole point. `/run/.containerenv` was
+ *    the obvious place to ask and it is EMPTY on the Podman measured here (2026-08-23), so the
+ *    answer has to come from the mapping itself.
+ *
+ * `/proc/self/uid_map` is `<inside> <outside> <count>` per line. Root mapped to root over the
+ * whole range is the ordinary, un-namespaced case:
+ *   host / rootful Docker: `0 0 4294967295`
+ *   rootless Podman:       `0 1000 1` then `1 100000 65536`
+ *
+ * `null` on any platform or kernel that does not publish it — not knowing is a fact, not a no.
+ */
+function inUserNamespace() {
+    try {
+        const first = readFileSync("/proc/self/uid_map", "utf8").trim().split("\n")[0];
+        const parts = first?.trim().split(/\s+/) ?? [];
+        if (parts.length < 3)
+            return null;
+        const inside = Number(parts[0]);
+        const outside = Number(parts[1]);
+        if (!Number.isFinite(inside) || !Number.isFinite(outside))
+            return null;
+        return !(inside === 0 && outside === 0);
+    }
+    catch {
+        return null;
+    }
+}
+/** Could this process open a browser for a person to look at? */
+function canOpenBrowser() {
+    if (platform() === "darwin" || platform() === "win32")
+        return true;
+    // On Linux a graphical session is what makes a browser possible. Neither variable being set is
+    // the ordinary case for a container, a build step, or a machine reached over ssh.
+    return Boolean(process.env["DISPLAY"] || process.env["WAYLAND_DISPLAY"]);
+}
+export function readEnvironment() {
+    const containment = detectContainment();
+    const inContainer = containment === "docker" || containment === "podman" || containment === "container";
+    let uid = null;
+    try {
+        uid = modesAreEnforced() ? userInfo().uid : null;
+    }
+    catch {
+        uid = null;
+    }
+    return {
+        os: platform(),
+        osRelease: release(),
+        node: process.versions.node,
+        containment,
+        rootMapped: inContainer ? inUserNamespace() : null,
+        uid,
+        privateStorage: codeStorageIsPrivate(),
+        configDir: configDir(),
+        interactive: process.stdin.isTTY === true,
+        browserReachable: canOpenBrowser(),
+    };
+}
+/**
+ * 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 function adviseFor(env, hasStoredCode) {
+    const out = [];
+    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 ` +
+                `each run instead of storing it avoids that.`,
+        });
+    }
+    if (env.containment !== "none" && env.containment !== "unknown") {
+        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 ` +
+                `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 ` +
+                `that file in NMTS_ACCOUNT_CODE_FILE, or pipe it in.`,
+        });
+        // ⛔ TWO DIFFERENT FACTS, and conflating them is how "rootless" gets reported backwards. What
+        //    matters for the host is whether root HERE is root THERE; the uid inside is separate.
+        if (env.rootMapped === true) {
+            out.push({
+                level: "note",
+                text: `This container is rootless: root inside it is an ordinary user on the host, so a ` +
+                    `mistake in any program here — this one included — is bounded by that user's reach.`,
+            });
+        }
+        else if (env.rootMapped === false) {
+            out.push({
+                level: "warn",
+                text: `Root inside this container is root on the host. Running it rootless — \`podman run\` as ` +
+                    `an ordinary user, or Docker's rootless mode — bounds what a mistake here can reach.`,
+            });
+        }
+        if (env.uid === 0 && env.rootMapped !== true) {
+            out.push({
+                level: "warn",
+                text: `This process is running as root. Nothing this tool does needs that.`,
+            });
+        }
+    }
+    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 ` +
+                `arrive in the environment or in a file named by NMTS_ACCOUNT_CODE_FILE.`,
+        });
+    }
+    if (!env.browserReachable) {
+        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.`,
+        });
+    }
+    if (env.os === "win32") {
+        out.push({
+            level: "note",
+            text: `Windows applies no POSIX file mode, so a stored account code inherits the folder's ` +
+                `permissions rather than being restricted to one user.`,
+        });
+    }
+    if (env.configDir.startsWith(tmpdir())) {
+        out.push({
+            level: "warn",
+            text: `The configuration directory is inside the temporary directory and may be cleared at any time.`,
+        });
+    }
+    return out;
+}

package/dist/errors.js

@@ -0,0 +1,71 @@
+// How this tool fails.
+//
+// ⛔ AN AGENT READS THESE. Every message here is written for a reader that will act on it without
+//    asking a person: it says what happened, and it says the one thing to do next. "Unauthorized"
+//    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
+//    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.
+//
+// ⛔⭐ THAT RULE COVERS WHAT THIS TOOL WRITES — AND `renderError` PRINTS WHAT IT DID NOT. An
+//    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
+//    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.
+/** A failure this tool understood, with an exit code and something the caller can do. */
+export class NmtsError extends Error {
+    exitCode;
+    /** One line naming the next action, or null when there is nothing useful to suggest. */
+    nextStep;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "NmtsError";
+        this.exitCode = options.exitCode ?? 1;
+        this.nextStep = options.nextStep ?? null;
+    }
+}
+/** 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.`, {
+            exitCode: 3,
+            nextStep: `Run \`${binary} login\`, or set ${envVar} in the environment.`,
+        });
+        this.name = "NotLoggedInError";
+    }
+}
+/** The command exists but is not built yet. Said plainly rather than failing as if it broke. */
+export class NotBuiltYetError extends NmtsError {
+    constructor(what) {
+        super(`${what} is not built yet.`, {
+            exitCode: 4,
+            nextStep: `This is not a failure — the command is announced but unfinished. Do not retry.`,
+        });
+        this.name = "NotBuiltYetError";
+    }
+}
+/** Render a failure for a terminal an agent is reading. */
+export function renderError(error, binary) {
+    if (error instanceof NmtsError) {
+        const lines = [`${binary}: ${error.message}`];
+        // ⛔ EVERY line of the next step is indented, not just the first. A multi-line explanation
+        //    whose second line runs flush to the margin reads as a separate message, and the one
+        //    place that matters is a warning somebody is deciding on.
+        if (error.nextStep) {
+            for (const line of error.nextStep.split("\n"))
+                lines.push(line === "" ? "" : `  ${line}`);
+        }
+        return lines.join("\n");
+    }
+    // Unknown failures print their message and nothing else — no stack, which is where paths,
+    // usernames and sometimes arguments leak into whatever the agent logs.
+    const message = error instanceof Error ? error.message : String(error);
+    return `${binary}: ${message}`;
+}
+/** Exit code for an unknown failure, kept distinct from the ones above. */
+export const UNKNOWN_FAILURE_EXIT = 1;