@needmoretruth/nmts-cli 0.17.2

package/dist/exit.js

@@ -0,0 +1,107 @@
+// How this program ends.
+//
+// ⛔ SPLIT OUT OF `main.ts` RATHER THAN INVENTED. Each of these was written there and moved here
+//    unchanged, on the day that file passed the length gate — the rule in this repository is that
+//    a file gets divided when it is being worked on. What belongs together here is "the shape of
+//    the ending": everything in `main.ts` decides WHAT to do, and everything here decides how the
+//    process stops saying so — the code it leaves behind, the one failure that must not become
+//    one, whether it was the program at all, and the last line it prints.
+import { realpathSync } from "node:fs";
+import { parseArgs } from "./args.js";
+import { NmtsError, UNKNOWN_FAILURE_EXIT } from "./errors.js";
+/** The exit code a failure asks for, or the generic one. */
+export function exitCodeFor(error) {
+    if (error instanceof NmtsError)
+        return error.exitCode;
+    return UNKNOWN_FAILURE_EXIT;
+}
+/**
+ * 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 function endQuietlyOnClosedPipe() {
+    for (const stream of [process.stdout, process.stderr]) {
+        stream.on("error", (error) => {
+            if (error.code === "EPIPE") {
+                process.exitCode = 0;
+                return;
+            }
+            throw error;
+        });
+    }
+}
+/**
+ * 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 function invokedDirectly(moduleFilename) {
+    const invokedAs = process.argv[1];
+    if (invokedAs === undefined)
+        return false;
+    if (invokedAs === moduleFilename)
+        return true;
+    try {
+        return realpathSync(invokedAs) === moduleFilename;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Commands the version notice stays out of.
+ *
+ * ⛔ `update` BECAUSE IT IS THE NOTICE'S OWN SUBJECT — it has just said more about versions than
+ *    one line could, and repeating a shorter version of it underneath would be noise.
+ * ⛔ `mcp` BECAUSE IT DOES NOT END. It is a server on a pipe, and its stderr is read by whatever
+ *    started it; a line arriving there whenever the process happens to stop is not a notice, it is
+ *    an unexplained log entry.
+ */
+const NO_NOTICE = ["update", "mcp"];
+/**
+ * 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 async function noteUpdateAfter(argv, version) {
+    let command;
+    try {
+        command = parseArgs(argv).command;
+    }
+    catch {
+        // A command line this could not read is one that failed above. Nothing to add to it.
+        return;
+    }
+    if (command !== null && NO_NOTICE.includes(command))
+        return;
+    // ⛔ THE SWITCH IS NOT CHECKED HERE AS WELL. `noteUpdate` reads it, and reading it twice would
+    //    put one rule in two files — the shape that ends with one of them changing. There is nothing
+    //    to save by checking early: the module holding the switch is the module being loaded.
+    const { noteUpdate } = await import("./update-check.js");
+    await noteUpdate({ running: version });
+}

package/dist/expiry.js

@@ -0,0 +1,115 @@
+// When bought storage runs out — the arithmetic, with no network in it.
+//
+// ⛔ A DAY COUNT IS A FLOOR, NOT A MEASUREMENT, UNLESS THE NETWORK SAID WHEN THIS EPOCH BEGAN.
+//    The storage network always reports which epoch it is in and usually nothing about how far
+//    into it we are. Counting `(end - current)` whole epochs therefore assumes the current epoch
+//    has not started yet — on a network whose epoch is fourteen days that overstates the runway by
+//    up to fourteen days, and a file with 23 days left gets told it has 28. This tool is allowed
+//    to warn early and is not allowed to warn late, so without an anchor the answer is
+//    `(end - current - 1)` epochs and `exact` is false, which is what makes the caller print
+//    "or more" instead of a flat number.
+//
+// ⛔ AND THE EPOCH COMPARISON DECIDES WHETHER A TERM HAS ENDED, never the day count. A lease that
+//    ends AT the current epoch has no epoch left to be read in, while an unanchored clock can
+//    still put a positive number of days beside it.
+//
+// ⛔ AN UNRECORDED PERIOD IS NOT A SHORT ONE. `expiry_epoch` is 0 for a file whose uploader could
+//    not read the epoch clock, and 0 sorts below every real deadline — so a listing that ranked by
+//    the number alone would put "we do not know" at the top of a list headed "about to be lost".
+//    `stageOf` answers `unrecorded` for those and the caller keeps them apart.
+//
+// ⛔ THE ARITHMETIC IS NOT WRITTEN HERE ANY MORE (2026-08-24). It used to be a second
+//    implementation of the browser's, with only the four thresholds machine-compared — and a
+//    compared VALUE does not stop two programs computing different answers from it. The browser's
+//    copy lived in a file that also imports its wallet client, which cannot follow into a
+//    command-line package, so the pure half was split out there and is copied here byte for byte
+//    (`shared/lib/extend/epochs.ts`). What is left in this file is the part the browser has no use
+//    for: a validated clock, the stage a file is in, the cutoff to ask the server about, and the
+//    words a person reads.
+//
+// PURE: no network, no SDK, no clock of its own — `nowMs` is always passed in. That is what lets
+// `node --test` drive the branches a real network only reaches during an epoch change.
+import { daysLeftUntilEpoch as sharedDaysLeftUntilEpoch, NOTICE_DAYS, NOTICE_EPOCHS, URGENT_DAYS, URGENT_EPOCHS, warningEpochs as sharedWarningEpochs, } from "./shared/lib/extend/epochs.js";
+// ⛔ Re-exported under the same names: a caller has no reason to know which of the two files a
+//    threshold came from, and making it know would be a second thing to keep in step.
+export { NOTICE_DAYS, NOTICE_EPOCHS, URGENT_DAYS, URGENT_EPOCHS };
+/**
+ * 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 function epochClock(current, durationMs, startedMs) {
+    if (!Number.isSafeInteger(current) || current < 0)
+        return null;
+    if (!Number.isFinite(durationMs) || durationMs <= 0)
+        return null;
+    if (startedMs !== null && !Number.isFinite(startedMs))
+        return null;
+    return { current, durationMs, startedMs };
+}
+/**
+ * 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 function warningEpochs(clock, days, floorEpochs) {
+    return sharedWarningEpochs(days, floorEpochs, clock.durationMs);
+}
+/**
+ * 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 function daysLeftUntilEpoch(clock, epoch, nowMs) {
+    const left = sharedDaysLeftUntilEpoch(epoch, clock, nowMs);
+    // ⛔ THE SHARED FUNCTION ANSWERS `null` FOR A CLOCK IT CANNOT DIVIDE BY, and this one cannot
+    //    hand that back: every caller here is already past `epochClock`, which refuses such a clock
+    //    at the boundary — that is the whole reason `EpochClock` is a type you cannot assemble by
+    //    hand. So `null` here would mean the validator and the arithmetic disagree about what a
+    //    usable clock is, and a wrong number of days on a screen about deletion is worse than a stop.
+    if (left === null) {
+        throw new Error("the storage network's clock passed validation and then could not be counted with");
+    }
+    return left;
+}
+export function stageOf(clock, expiryEpoch, nowMs) {
+    // 0 is the column's "nothing was recorded" — see the header. Anything below it is a value no
+    // network produced, and guessing at what it meant would be the same mistake in a smaller print.
+    if (!Number.isFinite(expiryEpoch) || expiryEpoch <= 0)
+        return "unrecorded";
+    if (expiryEpoch <= clock.current)
+        return "lapsed";
+    if (expiryEpoch <= clock.current + warningEpochs(clock, URGENT_DAYS, URGENT_EPOCHS))
+        return "urgent";
+    if (expiryEpoch < clock.current + warningEpochs(clock, NOTICE_DAYS, NOTICE_EPOCHS))
+        return "soon";
+    return "later";
+}
+/**
+ * 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 function warningCutoffEpoch(clock) {
+    return clock.current + warningEpochs(clock, NOTICE_DAYS, NOTICE_EPOCHS);
+}
+/**
+ * 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 function daysLeftInWords(left) {
+    if (left.days < 0)
+        return left.exact ? "already ended" : "may already have ended";
+    if (left.days < 1)
+        return left.exact ? "ends today" : "could end today";
+    const days = `${left.days} day${left.days === 1 ? "" : "s"}`;
+    return left.exact ? `${days} left` : `${days} or more left`;
+}

package/dist/extend-chain.js

@@ -0,0 +1,137 @@
+// The chain reads behind `nmts extend`: what a lease says, how far ahead the network sells, and
+// what more epochs cost.
+//
+// ⛔ EVERYTHING HERE IS A READ. Nothing in this file builds a transaction, holds a key or moves an
+//    asset — the signature lives next door in `extend-sign.ts`, alone, so that the file which can
+//    spend is the smallest one in this tool. What is shared is the client builder below, because
+//    the two must talk to the same chain: a quote read from one network and a payment made on
+//    another is a payment for nothing.
+//
+// ⛔ SPLIT FROM THE COMMAND SO THE COMMAND CAN BE TESTED. `extend-plan.ts` decides what an
+//    extension buys and `commands/extend.ts` decides what to say about it; both are driven by
+//    `node --test` against fakes. A test that needed a live storage network could not run offline,
+//    would answer differently every fortnight, and could never be asked to fail on demand.
+//
+// ⛔ AND NOTHING IS DEFAULTED TO ZERO. A lease that cannot be read, a shape the Move struct does
+//    not have, a price the system object will not give — each throws with its reason. A cost of
+//    zero on a screen that asks for money is the one wrong answer nobody would question.
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { walrus } from "@mysten/walrus";
+import { NmtsError } from "./errors.js";
+import { epochClock } from "./expiry.js";
+import { isRecord } from "./guards.js";
+import { epochStartedMs } from "./walrus-write.js";
+import { suiRpcHost } from "./walrus.js";
+/** How long one chain question gets. A read that stalls is a read that failed. */
+export const EXTEND_READ_TIMEOUT_MS = 20_000;
+/**
+ * A Walrus-aware client for one network.
+ *
+ * ⛔ THE NETWORK NAME REACHES THE SDK AS WELL AS THE URL, exactly as it does for an upload. A
+ *    mirror pointed at the wrong chain would otherwise be discovered as a refusal from the storage
+ *    contract — after a transaction had been signed.
+ */
+export function walrusClient(network) {
+    return build(network);
+}
+function build(network) {
+    return new SuiJsonRpcClient({
+        network: network === "mainnet" ? "mainnet" : "testnet",
+        url: suiRpcHost(network),
+    }).$extend(walrus({}));
+}
+/** A number off the wire, whether it arrived as a number or as one of Sui's 64-bit strings. */
+function numberOf(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== "string" || value.trim() === "")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * One blob's lease, read from the Blob object itself.
+ *
+ * ⛔ NARROWED FROM `unknown`, NOT FROM THE SDK'S TYPE. `MoveStruct` is a three-way union whose
+ *    members do not all carry an index signature, so reading a field off it means asserting — and
+ *    an assertion compiles whether or not the check above it is right. What matters is the shape
+ *    on the wire, and the predicate in `guards.ts` is what carries that narrowing.
+ */
+export async function readBlobLease(client, objectId) {
+    const response = await client.getObject({
+        id: objectId,
+        options: { showContent: true },
+    });
+    const data = isRecord(response) ? response["data"] : undefined;
+    const content = isRecord(data) ? data["content"] : undefined;
+    if (!isRecord(content) || content["dataType"] !== "moveObject") {
+        throw new NmtsError(`The storage object ${objectId} could not be read from the chain.`, {
+            exitCode: 1,
+            nextStep: "Nothing was signed and nothing was charged. The blob may already have been deleted, or " +
+                "this tool may be pointed at the wrong network — `nmts env` says which one it is using.",
+        });
+    }
+    const fields = content["fields"];
+    const storage = isRecord(fields) ? fields["storage"] : undefined;
+    const storageFields = isRecord(storage) ? storage["fields"] : undefined;
+    const size = numberOf(isRecord(fields) ? fields["size"] : undefined);
+    const endEpoch = numberOf(isRecord(storageFields) ? storageFields["end_epoch"] : undefined);
+    if (size === null || endEpoch === null) {
+        // ⛔ A shape change in the Move struct surfaces HERE, not as a wrong price downstream.
+        throw new NmtsError(`The storage object ${objectId} is not shaped the way this version reads.`, {
+            exitCode: 1,
+            nextStep: "Nothing was signed and nothing was charged. Update this tool.",
+        });
+    }
+    return { objectId, size, endEpoch };
+}
+/**
+ * The reads one `nmts extend` run needs, bound to one network.
+ *
+ * ⚠ THE WINDOW IS `null` RATHER THAN A GUESS when the network cannot be read, exactly as it is for
+ *   `nmts expiring`: the caller stops. An unread clock and a file in no danger look identical from
+ *   outside and are the opposite of each other.
+ */
+export function extendReads(network) {
+    const client = build(network);
+    return {
+        async readWindow() {
+            try {
+                const [system, staking] = await Promise.all([
+                    client.walrus.systemState(),
+                    client.walrus.stakingState(),
+                ]);
+                const clock = epochClock(Number(system.committee.epoch), Number(staking.epoch_duration), epochStartedMs(staking.epoch_state));
+                if (clock === null)
+                    return null;
+                // How far ahead a lease may reach: the protocol's future-accounting ring length, which is
+                // exactly what `storage_accounting::max_epochs_ahead` returns. Read, never assumed — it
+                // is the difference between offering a length the network will sell and one it refuses
+                // on-chain after the transaction is signed.
+                const maxAhead = numberOf(system.future_accounting.length);
+                if (maxAhead === null || maxAhead <= 0)
+                    return null;
+                return { clock, maxAhead };
+            }
+            catch {
+                return null;
+            }
+        },
+        readLeases(objectIds) {
+            return Promise.all(objectIds.map((id) => readBlobLease(client, id)));
+        },
+        /**
+         * What extending every one of these blobs by `epochs` costs, in FROST (WAL base units).
+         *
+         * ⭐ STORAGE ONLY. Extending pays for space over time; the write cost was paid once when the
+         *    blob was registered and is not charged again. That is why extending is markedly cheaper
+         *    than uploading the same bytes afresh, and why `totalCost` is the wrong field here.
+         */
+        async quote(leases, epochs) {
+            if (epochs <= 0 || leases.length === 0)
+                return 0n;
+            const costs = await Promise.all(leases.map((lease) => client.walrus.storageCost(lease.size, epochs)));
+            return costs.reduce((sum, cost) => sum + BigInt(cost.storageCost), 0n);
+        },
+    };
+}

package/dist/extend-plan.js

@@ -0,0 +1,149 @@
+// What extending a file's storage would buy, worked out before anything is signed.
+//
+// ⛔ NO NETWORK, NO SDK, NO KEY. Everything here is arithmetic over numbers somebody else read, so
+//    `node --test` can drive every branch — including the ones a live storage network only reaches
+//    by being at its ceiling, or by having sold a lease that already ran out. The reads live in
+//    `extend-chain.ts`, the signature in `extend-sign.ts`, and neither can be reached from here.
+//
+// ⛔ THE CHAIN IS THE AUTHORITY ON WHEN A LEASE ENDS, not the server's `expiry_epoch`. That column
+//    is client-reported and advisory — it is what `nmts expiring` ranks by, because ranking is all
+//    it does — and a command that spends money reads the Blob object itself. The server's answer
+//    is used for exactly one thing: knowing WHICH blobs to ask the chain about.
+//
+// ⛔ AND AN EXTENSION IS ADDED TO WHAT IS LEFT, never counted from today. Extending early loses
+//    nothing, which is why this tool is allowed to offer it at all; the new end is
+//    `endEpoch + epochs`, and that is the number every day count below is measured from.
+import { NmtsError } from "./errors.js";
+import { isRecord } from "./guards.js";
+import { BINARY_NAME } from "./product.js";
+/**
+ * The longest extension the NMTS server will RECORD, in epochs.
+ *
+ * ⛔ IT IS THE SERVER'S NUMBER AND IT IS CHECKED HERE ANYWAY, before the money moves. `api`'s
+ *    `MAX_EXTEND_EPOCHS` (routes/storage.rs) refuses to record anything longer — and the recording
+ *    happens AFTER the signature, so a length the chain would happily sell and the server would
+ *    refuse to write down produces the worst outcome this command has: storage that is really
+ *    extended, paid for, and a drive that goes on saying the old date.
+ *
+ * ⚠ A SECOND COPY, deliberately. The alternative is discovering the limit from a 400 after
+ *   spending. `check:cli-routes` holds the addresses level; nothing holds this number level, so it
+ *   is named with its origin and the refusal it produces says what the server would have said.
+ */
+export const MAX_RECORDABLE_EPOCHS = 104;
+/**
+ * How long an extension is when nobody says.
+ *
+ * The same term one credit buys on the upload rail (`upload-price.ts`, `UPLOAD_EPOCHS`) and the
+ * cheapest rung the browser's picker offers. ⚠ It is a number of EPOCHS, not of days: two epochs
+ * is two days on testnet and twenty-eight on mainnet, so every surface that prints it prints the
+ * days beside it, read from the network's own clock.
+ */
+export const DEFAULT_EXTEND_EPOCHS = 2;
+/**
+ * The preview, or a refusal.
+ *
+ * ⛔ A TARGET THIS CANNOT READ IS A REFUSAL, NOT A TARGET TO SKIP. Skipping one would produce a
+ *    transaction that extends some of a file's blobs and leaves the others to expire — and the
+ *    file is unreadable if any single one of them goes, so the money would buy nothing.
+ */
+export function asExtendPreview(value) {
+    const unreadable = () => {
+        throw new NmtsError("The server answered with an extension plan this version cannot read.", {
+            nextStep: "Update this tool. Nothing was signed, and nothing was charged.",
+        });
+    };
+    if (!isRecord(value))
+        return unreadable();
+    const raw = value["targets"];
+    if (!Array.isArray(raw))
+        return unreadable();
+    const targets = [];
+    for (const item of raw) {
+        if (!isRecord(item))
+            return unreadable();
+        const objectId = item["sui_object_id"];
+        const shared = item["shared_items"];
+        if (typeof objectId !== "string" || objectId === "")
+            return unreadable();
+        if (typeof shared !== "number" || !Number.isFinite(shared))
+            return unreadable();
+        targets.push({ objectId, sharedItems: shared });
+    }
+    const treasury = value["treasury_parts"];
+    const untracked = value["untracked_parts"];
+    if (typeof treasury !== "number" || typeof untracked !== "number")
+        return unreadable();
+    return { targets, treasuryParts: treasury, untrackedParts: untracked };
+}
+/**
+ * When the file actually runs out: the SOONEST end epoch across the blobs it rides on.
+ *
+ * ⛔ SOONEST, NOT FURTHEST. One expired blob is enough to make the file unreadable, so the file's
+ *    deadline is the first of them. Null when there is no lease to read, which is a real state
+ *    (every part on treasury-paid storage) and is never drawn as "now".
+ */
+export function soonestEnd(leases) {
+    if (leases.length === 0)
+        return null;
+    return Math.min(...leases.map((l) => l.endEpoch));
+}
+/**
+ * The largest number of epochs these leases can ALL be extended by.
+ *
+ * The ceiling is per-blob — a lease may not end more than `maxAhead` epochs past the current one —
+ * so the blob that already reaches furthest into the future is the binding one. 0 is a real
+ * answer ("already paid as far ahead as the network allows"), not a failure.
+ */
+export function headroom(leases, current, maxAhead) {
+    if (leases.length === 0)
+        return 0;
+    const furthest = Math.max(...leases.map((l) => l.endEpoch));
+    return Math.max(0, current + maxAhead - furthest);
+}
+/**
+ * How many epochs to buy: what was asked for, or the default, checked against both ceilings.
+ *
+ * ⛔ IT REFUSES RATHER THAN CLAMPS. Quietly buying fewer epochs than somebody asked for spends
+ *    their money on something they did not ask for, and quietly buying more spends more of it.
+ *    Each refusal names the ceiling that produced it, because the two have different remedies:
+ *    the network's is a wait, the server's is a shorter extension repeated later.
+ */
+export function chooseEpochs(asked, available) {
+    if (available <= 0) {
+        throw new NmtsError("This file's storage is already paid as far ahead as the network allows.", {
+            exitCode: 4,
+            nextStep: "Nothing was signed and nothing was charged. The storage network refuses a lease that " +
+                "ends further ahead than its own ceiling; extending again becomes possible as the " +
+                "network's epoch moves forward.",
+        });
+    }
+    const epochs = asked === undefined ? DEFAULT_EXTEND_EPOCHS : parseEpochs(asked);
+    if (epochs > available) {
+        throw new NmtsError(`The storage network will sell at most ${available} more epoch${available === 1 ? "" : "s"} on this file.`, {
+            exitCode: 4,
+            nextStep: `Nothing was signed and nothing was charged. A lease may not end further ahead than the ` +
+                `network's own ceiling. Ask for ${available} or fewer: \`${BINARY_NAME} extend --epochs ${available}\`.`,
+        });
+    }
+    if (epochs > MAX_RECORDABLE_EPOCHS) {
+        throw new NmtsError(`This tool extends by at most ${MAX_RECORDABLE_EPOCHS} epochs at a time.`, {
+            exitCode: 4,
+            nextStep: `Nothing was signed and nothing was charged. The NMTS server refuses to record a longer ` +
+                `one, so the storage would really be extended and the drive would go on showing the old ` +
+                `date. Extend by ${MAX_RECORDABLE_EPOCHS} or fewer, more than once if you need to.`,
+        });
+    }
+    return epochs;
+}
+/** A whole positive number of epochs, or the one refusal for anything else. */
+function parseEpochs(asked) {
+    const epochs = typeof asked === "number" ? asked : Number(asked.trim());
+    if (!Number.isSafeInteger(epochs) || epochs <= 0) {
+        throw new NmtsError(`An extension is a whole number of epochs: ${String(asked)}.`, {
+            exitCode: 2,
+            nextStep: `Nothing was signed and nothing was charged. \`--epochs 4\` buys four more of the storage ` +
+                `network's epochs — one day each on testnet, fourteen on mainnet.`,
+        });
+    }
+    return epochs;
+}

package/dist/extend-sign.js

@@ -0,0 +1,130 @@
+// ⛔ THE ONE FILE IN THIS TOOL THAT SIGNS. Everything it can do moves real assets and cannot be
+//    reversed by anybody, including NMTS.
+//
+// ⛔ IT IS REACHED FROM EXACTLY ONE PLACE: `commands/extend.ts`, after `requireConsent("wallet")`
+//    and after the price has been read and printed. Nothing else imports it, and it is loaded
+//    lazily so that a run which does not spend never even brings the code into memory.
+//
+// ⛔ NO KEY LEAVES THIS FILE. `wallet.ts` states the rule for the whole tool — no function returns
+//    a seed, a private key or a keypair — and this file is the one exception to the reason for it
+//    (something has to hold a key to sign) rather than to the rule itself: the keypair is built
+//    inside a function, asked one question, and dropped. ⚠ `@mysten/sui` keeps the secret inside
+//    its own object with no method that clears it, exactly as it does in the browser's worker; what
+//    is controlled here is lifetime. The buffers this file makes — the derived material, the wallet
+//    root, the seed — are wiped on every path out, failures included.
+//
+// ⛔ THE DERIVATION IS THE ENGINE'S, AT THE INDEX THE BROWSER USES. A second derivation written
+//    here would be free to drift from the one `nmts wallet address` prints, and the way that
+//    surfaces is a transaction signed by a wallet the person has never funded.
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { Transaction } from "@mysten/sui/transactions";
+import { assertUsableCode } from "./account.js";
+import { DERIVED, loadCrypto } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+import { walrusClient } from "./extend-chain.js";
+import { isRecord } from "./guards.js";
+import { BUILT_IN_WALLET_INDEX } from "./wallet.js";
+/**
+ * The keypair the account code derives.
+ *
+ * ⛔ NOT EXPORTED. A caller that could hold this could sign anything, and the whole of this tool's
+ *    story about the wallet is that one command signs one shape of transaction.
+ */
+async function keypairFor(code) {
+    // The one refusal text for a malformed code lives in `account.ts`, so a typo fails here the same
+    // way it fails everywhere else in this tool rather than as an engine error.
+    await assertUsableCode(code);
+    const glue = await loadCrypto();
+    let bytes = null;
+    let derived = null;
+    let root = null;
+    let seed = null;
+    try {
+        bytes = glue.account_code_parse(code);
+        // ⛔ THIS BUFFER IS EVERY KEY IN THE ACCOUNT, not just the wallet root: the sign-in secret, the
+        //    key that opens the files, the key that opens the file list.
+        derived = glue.kdf_derive(bytes);
+        const [from, to] = DERIVED.walletRoot;
+        root = derived.slice(from, to);
+        seed = glue.wallet_seed_for(root, BUILT_IN_WALLET_INDEX);
+        return Ed25519Keypair.fromSecretKey(seed);
+    }
+    catch (error) {
+        if (error instanceof NmtsError)
+            throw error;
+        // ⛔ An engine message about a code can carry the code (`errors.ts`), so it is never passed on.
+        throw new NmtsError("The account code could not be read on this machine.", { exitCode: 1 });
+    }
+    finally {
+        seed?.fill(0);
+        root?.fill(0);
+        derived?.fill(0);
+        bytes?.fill(0);
+    }
+}
+/**
+ * The address this tool would sign as.
+ *
+ * ⛔ IT EXISTS TO BE HELD AGAINST `walletAddress`. That function is what `nmts wallet address`
+ *    prints and what somebody funds; this one is what a transaction would actually be signed by.
+ *    Nothing else in this package proves the two are the same wallet, and the failure if they ever
+ *    part is silent — a signature from an address with nothing in it, or worse, money sent to an
+ *    address that signs nothing. A test compares them, offline, for free.
+ */
+export async function signerAddress(code) {
+    return (await keypairFor(code)).toSuiAddress();
+}
+/**
+ * Extend every listed blob by `epochs`, in ONE transaction, signed by the account's own wallet.
+ *
+ * ONE SIGNATURE FOR ALL OF IT: `extendBlob` returns a transaction fragment, so every blob a file
+ * sits on goes into the same transaction. A multi-part file is one payment and one gas fee, not
+ * five — and a partial extension would buy nothing, because one expired blob is enough to make the
+ * file unreadable.
+ *
+ * ⛔ THE IDS ARE DE-DUPLICATED. Naming the same blob twice pays for the same epochs twice.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED. A refusal from the node, a timeout, a
+ *   connection that dropped after the bytes went out — none of them say whether the transaction
+ *   was executed. The caller re-reads the chain rather than offering a second attempt against
+ *   numbers it read before.
+ */
+export const signExtension = async ({ network, code, objectIds, epochs }) => {
+    const unique = [...new Set(objectIds)];
+    if (unique.length === 0) {
+        throw new NmtsError("There is nothing on this file that can be extended.", { exitCode: 4 });
+    }
+    if (!Number.isSafeInteger(epochs) || epochs <= 0) {
+        throw new NmtsError("An extension must be a positive whole number of epochs.", { exitCode: 2 });
+    }
+    const client = walrusClient(network);
+    const keypair = await keypairFor(code);
+    const tx = new Transaction();
+    // The sender must be set before the fragments resolve: paying with the SDK's default coin
+    // selection picks the WAL coins from the sender's own address.
+    tx.setSender(keypair.toSuiAddress());
+    for (const blobObjectId of unique) {
+        tx.add(client.walrus.extendBlob({ blobObjectId, epochs }));
+    }
+    const result = await client.signAndExecuteTransaction({
+        transaction: tx,
+        signer: keypair,
+        options: { showEffects: true },
+    });
+    // ⛔ A DIGEST IS NOT A SUCCESS. A transaction that was executed and FAILED still has one, and the
+    //    gas for it is still gone; recording it as an extension would move the drive's expiry date
+    //    over storage nobody bought. The status is asked for above and read here.
+    const effects = result.effects;
+    const status = isRecord(effects) ? effects["status"] : undefined;
+    const outcome = isRecord(status) ? status["status"] : undefined;
+    if (outcome === "failure") {
+        const why = isRecord(status) ? status["error"] : undefined;
+        throw new NmtsError(`The storage network refused the extension: ${typeof why === "string" ? why : "no reason was given"}.`, {
+            exitCode: 1,
+            nextStep: `The storage was NOT extended and the file still ends when it did. The transaction fee ` +
+                `was spent. The usual causes are too little WAL or SUI in this account's wallet — ` +
+                `\`nmts wallet\` shows both — or a length the network will no longer sell.`,
+        });
+    }
+    return result.digest;
+};

package/dist/guards.js

@@ -0,0 +1,15 @@
+// Narrowing `unknown` without asserting.
+//
+// ⛔ WHY A MODULE FOR THIS. Everything that arrives from outside this program — a server answer, a
+//    tool call's arguments, a file somebody wrote — starts as `unknown`, and the shortest way to
+//    use it is `value as Record<string, unknown>`. That assertion compiles whether or not the check
+//    above it is right, and it keeps compiling after somebody edits the check. A predicate makes
+//    the compiler carry the narrowing instead, so the two can never drift apart.
+//
+// ⚠ ARRAYS ARE NOT RECORDS HERE. `typeof [] === "object"` and `[] !== null`, so the obvious
+//   two-part check lets an array through as an object — which is how a JSON array ends up being
+//   read for named fields and quietly answering `undefined` to every one of them.
+/** True for a plain JSON object: not null, not an array. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}