@needmoretruth/nmts-cli 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 Each version's entry is what changed for the person or the program using `nmts`. The product's own
 update history, which covers the site and the server too, is at https://nmts.me/updates.
 
+## 0.40.0 — 2026-09-20
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/storage-control`: what `nmts extend`
+  and `nmts wallet storage` (the listing, `split`, `merge`, `transfer`) do, without the prompts or the
+  printing. The commands are unchanged: the same reviews, the same `--yes`, the same unlock, the same
+  exit codes. `nmts-sdk` 0.6.0 is built on it.
+
 ## 0.39.0 — 2026-09-20
 
 - The library surface has a new entry, `@needmoretruth/nmts-cli/drive-erase`: what `nmts erase` does,

package/README.ko.md

@@ -50,7 +50,7 @@ nmts --help
 
 ```sh
 npm install -g github:needmoretruth/nmts-cli            # 기본 브랜치
-npm install -g github:needmoretruth/nmts-cli#v0.39.0    # 버전을 고정할 때
+npm install -g github:needmoretruth/nmts-cli#v0.40.0    # 버전을 고정할 때
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 

package/README.md

@@ -51,7 +51,7 @@ default branch, from a pinned version, or from the tarball attached to the
 
 ```sh
 npm install -g github:needmoretruth/nmts-cli            # the default branch
-npm install -g github:needmoretruth/nmts-cli#v0.39.0    # a pinned version
+npm install -g github:needmoretruth/nmts-cli#v0.40.0    # a pinned version
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 

package/dist/artifact-about.d.ts

@@ -11,7 +11,7 @@ export declare const CRYPTO_SPEC_URL = "https://github.com/needmoretruth/nmts-re
  *   is the field's own contract — what the writer says about itself — and a person holding two
  *   copies of one account's artefacts can then tell which program made each.
  */
-export declare const WRITTEN_BY = "nmts-cli 0.39.0";
+export declare const WRITTEN_BY = "nmts-cli 0.40.0";
 /** Which of the three artefacts a wrapper is. A reader holding several can sort them. */
 export type ArtifactKind = "recovery-list" | "file-list" | "recovery-kit";
 /**

package/dist/commands/extend.d.ts

@@ -1,4 +1,4 @@
-import { type ExtendReads, type SignExtension } from "../extend-plan.ts";
+import type { ExtendReads, SignExtension } from "../extend-plan.ts";
 import type { StandingTipInput } from "../standing-tip.ts";
 export interface ExtendOptions {
     server?: string | undefined;
@@ -14,8 +14,8 @@ export interface ExtendOptions {
     /**
      * The chain reads.
      *
-     * ⚠ A SEAM, NOT AN OPTION — no flag reaches it. See `ExtendReads`: a test that talked to a live
-     *   storage network could not run offline and could never be asked to be at its own ceiling.
+     * ⚠ A SEAM, NOT AN OPTION — no flag reaches it. A test that talked to a live storage network
+     *   could not run offline and could never be asked to be at its own ceiling.
      */
     readChain?: (network: string) => Promise<ExtendReads> | ExtendReads;
     /**

package/dist/commands/extend.js

@@ -6,9 +6,9 @@
 //    nobody — NMTS included — can reverse it. That difference is said out loud, in the output,
 //    before the agreement is asked for.
 //
-// ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. The reads and the quote are free and happen first, so
-//    `--dry-run` answers with a real number and never reaches the key. Nothing below the quote can
-//    run without `requireWalletGrant("extend", …)` having passed.
+// ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. The reads and the quote are free and happen first
+//    (`planExtension`), so `--dry-run` answers with a real number and never reaches the key.
+//    Nothing below the quote can run without `requireWalletGrant("extend", …)` having passed.
 //
 // ⛔ THE SERVER DOES NOT EXTEND ANYTHING, and this command is shaped by that. `POST
 //    /v1/items/{id}/extended` means "record an extension the device already signed": the storage is
@@ -19,21 +19,19 @@
 // ⛔ AND A FILE THAT IS NOT RUNNING OUT IS NOT EXTENDED BY ACCIDENT. Extending early loses nothing
 //    — epochs are added to what is left — so this is not a refusal on principle; it is a refusal
 //    to spend money on a deadline nobody is near, unless somebody says so with `--yes`.
+//
+// ⚠ WHAT IS DECIDED HERE AND WHAT IS NOT. The reads, the arithmetic, the price, the balances, the
+//   signature and the recording are `storage-control.ts`, which the SDK calls as well; this file is
+//   the terminal over them — the sentences, the agreement, the standing gift and the exit code.
 import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
-import { request } from "../api.js";
-import { buildIndex, entryAt, fullPathOf, KIND_FILE, normalisePath } from "../drive-paths.js";
 import { NmtsError } from "../errors.js";
-import { daysLeftInWords, daysLeftUntilEpoch, stageOf, } from "../expiry.js";
-import { asExtendPreview, chooseEpochs, headroom, soonestEnd, } from "../extend-plan.js";
-import { isRecord } from "../guards.js";
-import { readFileList } from "../manifest.js";
+import { daysLeftInWords } from "../expiry.js";
+import { describeBudget, shortfallNextStep } from "../extend-budget.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { openSession } from "../session.js";
-import { coinAmount, walletAddress } from "../wallet.js";
-import { payingWalletIndex } from "../wallet-pay-index.js";
-import { activeWalletOf } from "../shared/lib/drive/manifest-settings.js";
-import { budgetFacts, describeBudget, readBudget, shortfallNextStep } from "../extend-budget.js";
+import { applyExtension, planExtension } from "../storage-control.js";
+import { walletIndexOf } from "../wallet-pay-index.js";
 export async function extend(target, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const now = options.now ?? Date.now();
@@ -44,129 +42,50 @@ export async function extend(target, options = {}) {
         });
     }
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    if (list.manifest === null) {
-        throw new NmtsError("This account has no file list, so there is nothing to extend.", { exitCode: 4 });
-    }
-    const entries = list.manifest.entries;
-    // The standing share is the person's, and it is read from the same sealed list this file came from.
-    const settings = list.manifest.settings;
-    const entry = entryAt(entries, normalisePath(target), {
-        nothingHappened: "Nothing was signed and nothing was charged.",
-    });
-    if (entry.kind !== KIND_FILE) {
-        throw new NmtsError(`No file at "${fullPathOf(buildIndex(entries), entry)}".`, {
-            exitCode: 4,
-            nextStep: "That is a folder. Nothing was signed and nothing was charged — storage is bought per " +
-                "file, so this takes one file at a time.",
-        });
-    }
-    const path = fullPathOf(buildIndex(entries), entry);
-    // ⛔ THE SERVER SAYS WHICH BLOBS, AND NOTHING ELSE. Its `expiry_epoch` is client-reported and
-    //    advisory; a command that spends money reads the chain's own answer below.
-    const preview = asExtendPreview(await request(session.server, `/v1/items/${encodeURIComponent(entry.id)}/extend-preview`, {
-        token: session.apiKey,
-    }));
-    if (preview.targets.length === 0) {
-        throw new NmtsError(`Nothing on "${path}" can be extended from here.`, {
-            exitCode: 4,
-            nextStep: nothingToExtend(preview),
-        });
-    }
-    const reads = await (options.readChain ?? defaultReads)(session.network);
-    const window = await reads.readWindow();
-    if (window === null) {
-        // ⛔ Not "nothing needs extending". The two look identical from outside and mean opposite things.
-        throw new NmtsError(`The ${session.network} storage network could not be read.`, {
-            exitCode: 1,
-            nextStep: `Nothing was signed and nothing was charged. Which epoch the network is in, and how far ` +
-                `ahead it will sell, are facts only the chain has — this tool will not spend against a ` +
-                `guess. Try again, or name a different Sui node in NMTS_SUI_RPC.`,
-        });
-    }
-    const clock = window.clock;
-    const leases = await reads.readLeases(preview.targets.map((t) => t.objectId));
-    const endEpoch = soonestEnd(leases);
-    if (endEpoch === null) {
-        throw new NmtsError(`The chain holds no storage term for "${path}".`, {
-            exitCode: 4,
-            nextStep: nothingToExtend(preview),
-        });
-    }
-    const stage = stageOf(clock, endEpoch, now);
-    if (stage === "lapsed") {
-        throw new NmtsError(`The storage term for "${path}" has already ended.`, {
-            exitCode: 4,
-            nextStep: `Nothing was signed and nothing was charged. A lease is extended before it ends — once it ` +
+    // ⛔ A NUMBER THAT IS NOT ONE IS REFUSED BEFORE ANYTHING IS READ. Absent, the account's own number
+    //    comes out of the sealed list the plan reads — one read, so the address that is priced and
+    //    the address that signs cannot differ.
+    const named = options.wallet === undefined || options.wallet === "" ? undefined : walletIndexOf(options.wallet);
+    const plan = await planExtension(session, target, {
+        now,
+        epochs: options.epochs,
+        wallet: named,
+        readChain: options.readChain,
+        // ⚠ THE LAST SENTENCE IS THIS FILE'S: `nmts get` is a command at a prompt.
+        hints: {
+            lapsed: `Nothing was signed and nothing was charged. A lease is extended before it ends — once it ` +
                 `is over there is no storage object left to extend, and the bytes may already be gone. ` +
                 `\`${BINARY_NAME} get\` says whether they can still be read.`,
-        });
-    }
-    const epochs = chooseEpochs(options.epochs, headroom(leases, clock.current, window.maxAhead));
-    const newEndEpoch = endEpoch + epochs;
-    const before = daysLeftUntilEpoch(clock, endEpoch, now);
-    const after = daysLeftUntilEpoch(clock, newEndEpoch, now);
-    // ⛔ A COST THAT COULD NOT BE COMPUTED MUST NOT BECOME A COST OF ZERO. `quote` rejects rather
-    //    than defaulting, and that rejection stops this run before the agreement is asked for.
-    const frost = await reads.quote(leases, epochs);
-    const cohort = Math.max(0, ...preview.targets.map((t) => t.sharedItems));
-    const unreachable = preview.treasuryParts + preview.untrackedParts;
-    // What the wallet holds and what the chain would charge — read, never assumed (`extend-budget.ts`).
-    // ⛔ WHICH WALLET PAYS comes out of the list this run already read, before the price is measured
-    //    against a balance: the address below is the one that will sign (`wallet-pay-index.ts`).
-    const wallet = await payingWalletIndex({ ...options, readActiveWallet: async () => activeWalletOf(settings) });
-    const address = await walletAddress(session.code, wallet);
-    const budget = await readBudget(reads, {
-        address,
-        objectIds: preview.targets.map((t) => t.objectId),
-        epochs,
-        priceFrost: frost,
+        },
     });
-    const facts = {
-        file: path,
-        itemId: entry.id,
-        network: session.network,
-        epoch: clock.current,
-        endEpoch,
-        epochs,
-        newEndEpoch,
-        daysLeft: before,
-        daysLeftAfter: after,
-        blobs: leases.length,
-        priceFrost: frost.toString(),
-        priceWal: coinAmount(frost),
-        paidFrom: "wallet",
-        filesOnTheSameBlobs: cohort,
-        partsThatCannotBeExtended: unreachable,
-        ...budgetFacts(budget),
-    };
+    const { facts, budget } = plan;
     if (options.dryRun === true) {
-        // ⛔ NOTHING BELOW THIS BRANCH RUNS. No key is derived, no agreement is asked for, and the
-        //    signing module is not even loaded — `--dry-run` is a price and nothing else.
+        // ⛔ NOTHING BELOW THIS BRANCH RUNS. No key is derived for signing, no agreement is asked for,
+        //    and the signing module is not even loaded — `--dry-run` is a price and nothing else.
         if (options.json) {
             say(JSON.stringify({ ...facts, dryRun: true, signed: false }));
             return 0;
         }
-        describe(say, facts, cohort, unreachable);
+        describe(say, facts);
         describeBudget(say, budget);
         say(``);
         if (budget.shortfall !== null)
             say(`  ⚠ ${budget.shortfall} As it stands, it would be refused.`);
         say(`  Nothing was signed and nothing was charged. Run the same command without --dry-run to`);
         say(`  buy it.`);
-        if (stage === "later")
+        if (plan.stage === "later")
             say(`  It is not near its deadline, so buying it also needs --yes.`);
         return 0;
     }
     if (!options.json) {
-        describe(say, facts, cohort, unreachable);
+        describe(say, facts);
         describeBudget(say, budget);
     }
     // ⛔ ASKED AFTER THE PRICE IS KNOWN AND BEFORE ANYTHING IS SIGNED. Extending early loses nothing,
     //    so this is not a refusal on principle — it is a refusal to spend on a deadline that is not
     //    close, unless somebody says otherwise out loud.
-    if (stage === "later" && options.yes !== true) {
-        throw new NmtsError(`"${path}" is not near the end of its storage term.`, {
+    if (plan.stage === "later" && options.yes !== true) {
+        throw new NmtsError(`"${plan.path}" is not near the end of its storage term.`, {
             exitCode: 4,
             nextStep: `Nothing was signed and nothing was charged. Extending early loses nothing — the epochs ` +
                 `are added to what is left — but it spends now for time this file does not need yet. ` +
@@ -181,49 +100,37 @@ export async function extend(target, options = {}) {
     // ⛔ THE ONE GATE THAT STANDS BETWEEN A PROGRAM AND SOMEBODY'S WALLET. Everything above this line
     //    is a read; nothing below it can be undone. The grant names a scope, runs out, and may carry
     //    a ceiling — this signature is held against all three (`wallet-grant.ts`).
-    const spend = { walFrost: frost, suiMist: budget.feeMist ?? 0n };
+    const spend = { walFrost: budget.priceFrost, suiMist: budget.feeMist ?? 0n };
     requireWalletGrant("extend", spend, new Date(now));
-    const sign = options.sign ?? (await import("../wallet-sign.js")).signExtension;
-    const digest = await sign({
-        network: session.network,
-        code: session.code,
-        wallet,
-        objectIds: preview.targets.map((t) => t.objectId),
-        epochs,
+    const outcome = await applyExtension(session, plan, {
+        sign: options.sign,
+        // What left the wallet is added to the grant's ledger first — the fee as estimated, since the
+        // amount actually charged is not read back here.
+        onSigned: () => recordWalletSpend(spend),
     });
-    // What left the wallet is added to the grant's ledger first — the fee as estimated, since the
-    // amount actually charged is not read back here.
-    recordWalletSpend(spend);
-    // From here the storage IS extended. Recording it is bookkeeping, and a failure to record must
-    // never be reported as a failure to extend — that reading invites a second run, which pays again.
-    let replay = false;
-    try {
-        const recorded = await request(session.server, `/v1/items/${encodeURIComponent(entry.id)}/extended`, { method: "POST", token: session.apiKey, body: { epochs, tx_digest: digest } });
-        replay = isRecord(recorded) && recorded["replay"] === true;
-    }
-    catch (error) {
+    if (!outcome.recorded) {
         if (options.json) {
-            say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: false }));
+            say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest: outcome.digest, recorded: false }));
         }
         else {
             say(``);
-            say(`  The storage IS extended and the payment has been made — transaction ${digest}.`);
+            say(`  The storage IS extended and the payment has been made — transaction ${outcome.digest}.`);
             say(`  What failed is telling the NMTS server about it, so the drive will go on showing the`);
             say(`  old date until something tells it. ⛔ Do not run this command again for this file:`);
             say(`  that would buy the same epochs a second time. Opening the account in a browser reads`);
             say(`  the chain directly.`);
-            say(`  Cause: ${error instanceof Error ? error.message : String(error)}`);
+            say(`  Cause: ${outcome.notRecorded}`);
         }
         return 1;
     }
     if (options.json) {
-        say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: true, replay }));
+        say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest: outcome.digest, recorded: true, replay: outcome.replay }));
     }
     else {
         say(``);
-        say(`  Extended. The storage now ends at epoch ${newEndEpoch} — ${daysLeftInWords(after)}.`);
-        say(`  Transaction ${digest}`);
-        if (replay)
+        say(`  Extended. The storage now ends at epoch ${facts.newEndEpoch} — ${daysLeftInWords(facts.daysLeftAfter)}.`);
+        say(`  Transaction ${outcome.digest}`);
+        if (outcome.replay)
             say(`  The server had already recorded this transaction, so nothing was written twice.`);
     }
     // ⛔ AFTER THE PAYMENT, NEVER INSIDE IT, and it cannot change the answer above. In --json the
@@ -232,17 +139,19 @@ export async function extend(target, options = {}) {
         server: session.server,
         network: resolveNetwork(session.server, session.network),
         code: session.code,
-        settings,
-        wallet,
-        paidWalFrost: frost,
+        settings: plan.settings,
+        wallet: plan.wallet,
+        paidWalFrost: budget.priceFrost,
         say: options.json === true ? (line) => void process.stderr.write(`${line}\n`) : say,
         ...(options.tip ?? {}),
     });
     return 0;
 }
 /** What the numbers say, for a person, in the order somebody deciding needs them. */
-function describe(say, facts, cohort, unreachable) {
+function describe(say, facts) {
     const when = (epoch, left) => `epoch ${epoch} — ${daysLeftInWords(left)}`;
+    const cohort = facts.filesOnTheSameBlobs;
+    const unreachable = facts.partsThatCannotBeExtended;
     say(`${facts.file}`);
     say(`  Storage ends at ${when(facts.endEpoch, facts.daysLeft)}.`);
     say(`  Extending by ${facts.epochs} epoch${facts.epochs === 1 ? "" : "s"} moves that to ` +
@@ -262,21 +171,3 @@ function describe(say, facts, cohort, unreachable) {
     say(`  This is paid in WAL from the wallet this NMTS key derives — not from credits, which`);
     say(`  is what every other command in this tool spends. \`${BINARY_NAME} wallet\` shows what is in it.`);
 }
-/** Why a file has nothing to extend, said as the two different things it can be. */
-function nothingToExtend(preview) {
-    const parts = [];
-    if (preview.treasuryParts > 0) {
-        parts.push(`${preview.treasuryParts} part${preview.treasuryParts === 1 ? " is" : "s are"} on storage NMTS ` +
-            `paid for, which this account cannot extend`);
-    }
-    if (preview.untrackedParts > 0) {
-        parts.push(`${preview.untrackedParts} part${preview.untrackedParts === 1 ? " has" : "s have"} no ` +
-            `recorded storage object, so there is nothing to name on the chain`);
-    }
-    const why = parts.length === 0 ? "The server lists no storage object for it." : `${parts.join(", and ")}.`;
-    return `Nothing was signed and nothing was charged. ${why} Opening the account in a browser shows what it is stored on.`;
-}
-/** The real chain reads. Imported only when no seam was supplied — it loads the storage SDK. */
-async function defaultReads(network) {
-    return (await import("../extend-chain.js")).extendReads(network);
-}

package/dist/commands/wallet-storage-ops.d.ts

@@ -1,7 +1,7 @@
 import { type Network } from "../network.ts";
-import { type StorageOpsReads } from "../storage-control-chain.ts";
+import { type StorageOp, type StorageOpsReads } from "../storage-control.ts";
 import type { SignStorageOp } from "../wallet-sign.ts";
-export type StorageOp = "split" | "merge" | "transfer";
+export type { StorageOp } from "../storage-control.ts";
 export interface StorageOpsOptions {
     server?: string | undefined;
     network?: string | undefined;