@needmoretruth/nmts-cli 0.36.3 → 0.38.1

package/AGENTS.md

@@ -40,6 +40,28 @@ for the NMTS key: it asks nothing and works in a container. The NMTS key from `N
 readable through `docker inspect`, `/proc/<pid>/environ` and most CI logs, so that shape stops
 once, for an unlock (`nmts help login`).
 
+## What is built on it today
+
+Each of these works with what is published now. None of it is a plan.
+
+- **Storage for an agent.** Notes, datasets and build outputs that outlive a session or a machine,
+  encrypted before they leave it. This command does it, and so does [its MCP server](#if-your-client-speaks-mcp).
+- **Encrypted storage inside someone's product.** The [SDK](https://github.com/needmoretruth/nmts-sdk)
+  opens an NMTS account for each person who uses a product and keeps that person's files in it. The
+  NMTS key is held by the person (the product cannot read the files) or by the product
+  (`Nmts.managed`), and every SDK method works the same either way. The
+  [terms](https://nmts.me/terms) provide for it in 3.7, for commercial products too.
+- **An S3 endpoint.** `@needmoretruth/nmts-sdk/gateway` speaks S3 with a bucket and a key pair per
+  customer, so django-storages, Rails Active Storage, rclone and backup tools store into NMTS
+  unchanged.
+- **Files that come back without NMTS.** [nmts-recovery](https://github.com/needmoretruth/nmts-recovery)
+  rebuilds an account's files from Walrus with the NMTS key and the recovery list the person saved.
+  No NMTS server takes part.
+
+An account pays with credits or straight from its own wallet. From the wallet, WAL goes to Walrus
+and SUI to the chain, and NMTS takes no fee. NMTS does not inspect or certify products built with the SDK: who holds the
+keys in such a product is that product's own statement.
+
 ## What only a person can do, once
 
 Four things need a person, all at the beginning. If you are being set up, hand this list back in full at once.

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 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.38.1 — 2026-09-20
+
+- The folder and trash functions behind `@needmoretruth/nmts-cli/drive-edit` no longer import
+  `node:crypto`, so a browser bundle that reaches them builds again; the browser entry of `nmts-sdk`
+  does. Nothing a command prints has changed.
+- `AGENTS.md` has a new section, "What is built on it today": storage for an agent, encrypted
+  storage inside a product through the SDK, the S3 endpoint, and recovery without NMTS.
+
+## 0.38.0 — 2026-09-19
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/s3-gateway`: the S3 server `nmts s3`
+  runs, taking a function that says which drive a bucket name means and a list of key pairs that
+  may each be held to named buckets, so a program can put it in front of more than one account and
+  mount it in a server of its own. `nmts s3` is unchanged: the same output, the same bucket, the same
+  refusals. `nmts-sdk` 0.4.0 is built on it.
+
+## 0.37.0 — 2026-09-19
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/drive-edit`: the list edits behind
+  `mkdir`, `mv`, `rename`, `rm` and `restore` as functions that print nothing and refuse with a
+  `code` (`NOT_FOUND`, `NAME_TAKEN`, `BAD_NAME`, `NOT_IN_TRASH`, `INTO_ITSELF`). The commands call the
+  same functions and print what they printed before. `nmts-sdk` 0.3.0 is built on it.
+- Six command documents called the NMTS key "code", the name it had before; `nmts help extend`
+  carried an empty code block.
+
 ## 0.36.3 — 2026-09-19
 
 - `--help` had the `--on-collision` lines in the middle of the `--part-size` description, so the

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.36.3    # 버전을 고정할 때
+npm install -g github:needmoretruth/nmts-cli#v0.38.1    # 버전을 고정할 때
 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.36.3    # a pinned version
+npm install -g github:needmoretruth/nmts-cli#v0.38.1    # 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.36.3";
+export declare const WRITTEN_BY = "nmts-cli 0.38.1";
 /** 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/erase.js

@@ -26,7 +26,7 @@ import { applyToList, batchTargets } from "../manifest-write.js";
 import { BINARY_NAME } from "../product.js";
 import { promptLine, stdinIsATerminal } from "../prompt.js";
 import { openSession } from "../session.js";
-import { filesUnder } from "./trash.js";
+import { filesUnder } from "../drive-edit.js";
 /** The server takes at most this many ids in one erase (`ERASE_BATCH_MAX`). */
 const BATCH = 200;
 /** The refusal a no-deposit release gets when the balance cannot cover the doubled fee. */

package/dist/commands/organise.d.ts

@@ -1,4 +1,3 @@
-import { openSession } from "../session.ts";
 export interface OrganiseOptions {
     server?: string | undefined;
     network?: string | undefined;
@@ -8,38 +7,17 @@ export interface OrganiseOptions {
 /**
  * Make a folder, and any folder above it that is missing.
  *
- * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience. A folder costs
- *   nothing, holds nothing and can be moved to the trash, so the failure mode of creating one too
- *   many is a tidy-up; the failure mode of refusing is an agent that has to discover the tree one
- *   command at a time. Every folder made is named in the output, so it is never a surprise.
+ * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience — the reason is
+ *   beside the code that does it, in `drive-edit.ts`. Every folder made is named in the output, so
+ *   it is never a surprise.
  */
-/**
- * Make a folder path, and every folder above it that is missing, under an OPEN session.
- *
- * ⛔ SPLIT OUT SO AN UPLOAD OF A WHOLE DIRECTORY CAN USE IT. The rules below are the ones a second
- *    copy would get subtly wrong: a folder that is already there IS the folder asked for (never a
- *    numbered one), the decision is taken inside each attempt so a lost race cannot make two, and
- *    what was made before a failure is named rather than silently kept.
- */
-export declare function ensureFolderPath(session: Awaited<ReturnType<typeof openSession>>, wanted: string): Promise<{
-    parentId: string | null;
-    made: string[];
-}>;
 export declare function mkdir(path: string | undefined, options?: OrganiseOptions): Promise<number>;
 /**
  * Move things into a folder. Every operand but the last is something to move; the last is where
  * they go, and an empty one means the top of the drive.
  *
- * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named. The list is rewritten whole on
- *    every save, so a second thing costs nothing extra — while a second WRITE is a second chance
- *    to lose the compare-and-swap, and losing it half way through a run leaves some things moved
- *    and some not, which is a state the caller cannot tell apart from the one it asked for.
- *
- * ⛔ AND THE NAME CHECK RUNS AGAINST WHAT THIS RUN HAS ALREADY MOVED, not against the list as it
- *    was read. Two files called `notes.txt` in two folders, moved into one folder by one command,
- *    would otherwise both be written — two entries at one path, which no command in this tool can
- *    address afterwards: every one of them answers "names 2 things in this account". So the loop
- *    folds each move onto a working copy and asks the working copy the next question.
+ * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named, and every guard is re-decided
+ *    inside the attempt. Both reasons are in `drive-edit.ts`, beside the loop that keeps them.
  */
 export declare function mv(operands: readonly string[], options?: OrganiseOptions): Promise<number>;
 /** Give one thing a new name. The path stays the same otherwise. */

package/dist/commands/organise.js

@@ -1,5 +1,9 @@
 // `nmts mkdir`, `nmts mv` and `nmts rename` — the three edits that touch no bytes.
 //
+// ⛔ WHAT THEY DO IS IN `drive-edit.ts`; WHAT IS HERE IS THE TERMINAL. The list editing moved out
+//    the day the SDK needed the same three verbs without one — one implementation, two callers, so
+//    "what does moving onto a taken name do" is answered in a single place.
+//
 // ⛔ NONE OF THESE ASKS THE SERVER TO CHANGE ANYTHING BUT THE SEALED LIST. A folder has no server
 //    row at all, and a name and a parent live only inside the list — the server holds an id, a
 //    size and a time, and was deliberately never given a place to put a name
@@ -10,97 +14,18 @@
 //
 // ⛔ AND NONE OF THEM STOPS TO ASK. Renaming, moving and making a folder are reversible and cost
 //    nothing, which is the whole test for whether this tool interrupts somebody. It does not.
-import { randomUUID } from "node:crypto";
-import { buildIndex, entryAt, folderIdFor, fullPathOf, KIND_FOLDER, namesIn, normaliseName, normalisePath, } from "../drive-paths.js";
+import { makeFolder, moveEntries, renameEntry, requireNewName } from "../drive-edit.js";
+import { normalisePath } from "../drive-paths.js";
 import { NmtsError } from "../errors.js";
-import { readFileList } from "../manifest.js";
-import { applyManyToList, applyToList, batchTargets } from "../manifest-write.js";
 import { openSession } from "../session.js";
-import { applyIntent } from "../shared/lib/drive/manifest-ops.js";
 const say_ = (line) => void process.stdout.write(`${line}\n`);
 /**
  * Make a folder, and any folder above it that is missing.
  *
- * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience. A folder costs
- *   nothing, holds nothing and can be moved to the trash, so the failure mode of creating one too
- *   many is a tidy-up; the failure mode of refusing is an agent that has to discover the tree one
- *   command at a time. Every folder made is named in the output, so it is never a surprise.
- */
-/**
- * Make a folder path, and every folder above it that is missing, under an OPEN session.
- *
- * ⛔ SPLIT OUT SO AN UPLOAD OF A WHOLE DIRECTORY CAN USE IT. The rules below are the ones a second
- *    copy would get subtly wrong: a folder that is already there IS the folder asked for (never a
- *    numbered one), the decision is taken inside each attempt so a lost race cannot make two, and
- *    what was made before a failure is named rather than silently kept.
+ * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience — the reason is
+ *   beside the code that does it, in `drive-edit.ts`. Every folder made is named in the output, so
+ *   it is never a surprise.
  */
-export async function ensureFolderPath(session, wanted) {
-    const made = [];
-    let parentId = null;
-    let walked = "";
-    for (const name of wanted.split("/")) {
-        // ⚠ A name that is only spaces is refused too. `mkdir` used to accept it, and then `rm` and
-        //   `restore` rejected the very path `ls` printed for it as "no path given" — a code-2 message
-        //   blaming the caller for an argument they had supplied (2026-08-23).
-        if (name.trim() === "" || name === "." || name === "..") {
-            throw new NmtsError(`"${wanted}" is not a folder path this tool will make.`, {
-                exitCode: 2,
-                nextStep: `Empty names, "." and ".." are not folder names in a drive. Nothing was made.`,
-            });
-        }
-        walked = walked === "" ? name : `${walked}/${name}`;
-        const under = parentId;
-        const here = walked;
-        const fresh = randomUUID();
-        let landedOn = fresh;
-        // ⛔ ONE WRITE PER FOLDER, and the check that decides whether to write happens INSIDE the
-        //    attempt. Two things went wrong when it sat outside (2026-08-23):
-        //      · running `mkdir` twice at the same moment made `shared` AND `shared (2)`, because the
-        //        loser of the compare-and-swap re-applied a decision taken against the older list;
-        //      · a trashed folder of the same name made the second `mkdir` produce `photos (2)` while
-        //        printing `Made "photos"`, because it went through the upload helper — and picking a
-        //        free name is the right rule for BYTES and the wrong rule for a folder. A folder with
-        //        that name in that parent IS the folder that was asked for.
-        //    Building the whole chain in memory and writing once would be fewer round trips and would
-        //    also mean a lost compare-and-swap threw away folders the ones below already point at.
-        const result = await applyToList(session, (entries) => {
-            const there = entries.find((e) => e.parentId === under &&
-                normaliseName(e.name) === normaliseName(name) &&
-                e.deletedAt === undefined);
-            if (there !== undefined) {
-                if (there.kind !== KIND_FOLDER) {
-                    throw new NmtsError(`"${here}" is a file, so nothing can be made inside it.`, {
-                        exitCode: 4,
-                        nextStep: made.length > 0 ? `The folders made so far are kept: ${made.join(", ")}.` : "Nothing was made.",
-                    });
-                }
-                landedOn = there.id;
-                return null;
-            }
-            landedOn = fresh;
-            const at = Date.now();
-            return {
-                op: "add",
-                entry: { id: fresh, parentId: under, kind: KIND_FOLDER, name, size: 0, createdAt: at, updatedAt: at },
-            };
-        }).catch((error) => {
-            // ⛔ WHAT SURVIVED IS NAMED. A run that stops half way leaves real folders behind, and the
-            //    message that says so was attached only to the "that is a file" refusal.
-            if (error instanceof NmtsError || made.length === 0)
-                throw error;
-            const because = error instanceof Error ? error.message : "the server refused";
-            throw new NmtsError(because, {
-                exitCode: 1,
-                nextStep: `The folders made so far are kept: ${made.join(", ")}. Running the same command again ` +
-                    `makes the rest — nothing is lost.`,
-            });
-        });
-        if (result.changed)
-            made.push(here);
-        parentId = landedOn;
-    }
-    return { parentId, made };
-}
 export async function mkdir(path, options = {}) {
     const say = options.write ?? say_;
     const wanted = normalisePath(path ?? "");
@@ -108,7 +33,7 @@ export async function mkdir(path, options = {}) {
         throw new NmtsError("`nmts mkdir` needs the path of the folder to make.", { exitCode: 2 });
     }
     const session = await openSession(options);
-    const { parentId, made } = await ensureFolderPath(session, wanted);
+    const { parentId, made } = await makeFolder(session, wanted);
     if (options.json) {
         say(JSON.stringify({ path: wanted, id: parentId, made }));
         return 0;
@@ -125,16 +50,8 @@ export async function mkdir(path, options = {}) {
  * Move things into a folder. Every operand but the last is something to move; the last is where
  * they go, and an empty one means the top of the drive.
  *
- * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named. The list is rewritten whole on
- *    every save, so a second thing costs nothing extra — while a second WRITE is a second chance
- *    to lose the compare-and-swap, and losing it half way through a run leaves some things moved
- *    and some not, which is a state the caller cannot tell apart from the one it asked for.
- *
- * ⛔ AND THE NAME CHECK RUNS AGAINST WHAT THIS RUN HAS ALREADY MOVED, not against the list as it
- *    was read. Two files called `notes.txt` in two folders, moved into one folder by one command,
- *    would otherwise both be written — two entries at one path, which no command in this tool can
- *    address afterwards: every one of them answers "names 2 things in this account". So the loop
- *    folds each move onto a working copy and asks the working copy the next question.
+ * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named, and every guard is re-decided
+ *    inside the attempt. Both reasons are in `drive-edit.ts`, beside the loop that keeps them.
  */
 export async function mv(operands, options = {}) {
     const say = options.write ?? say_;
@@ -148,60 +65,17 @@ export async function mv(operands, options = {}) {
         });
     }
     const session = await openSession(options);
-    const at = Date.now();
-    const outcome = { moved: [], already: [], parentId: null };
-    // ⛔ EVERY GUARD RUNS INSIDE THE ATTEMPT, INCLUDING WHICH ENTRY EACH PATH NAMES. A lost
-    //    compare-and-swap re-applies the intent to a list that changed underneath — and when the
-    //    winner had just taken this name, the loser landed on top of it and produced two entries at
-    //    one path. Meanwhile the tool exited 0 and said the move had been made.
-    const result = await applyManyToList(session, (now) => {
-        const targets = batchTargets(now, paths, { nothingHappened: "Nothing was moved." });
-        const into = folderIdFor(destination, now, "Nothing was moved.");
-        const intents = [];
-        const moved = [];
-        const already = [];
-        let working = now;
-        for (const target of targets) {
-            if (into !== null && (into === target.id || isUnder(working, into, target.id))) {
-                throw new NmtsError(`A folder cannot be moved inside itself.`, {
-                    exitCode: 4,
-                    nextStep: "Nothing was moved.",
-                });
-            }
-            if (into === target.parentId) {
-                already.push(target.name);
-                continue;
-            }
-            if (namesIn(working, into).has(normaliseName(target.name))) {
-                throw new NmtsError(`Something called "${target.name}" is already in that folder.`, {
-                    exitCode: 4,
-                    nextStep: `Nothing was moved. Rename it first: nmts rename "${target.name}" <new name>`,
-                });
-            }
-            const intent = { op: "move", id: target.id, parentId: into, at };
-            intents.push(intent);
-            working = applyIntent(working, intent);
-            moved.push({ id: target.id, name: target.name });
-        }
-        outcome.moved = moved;
-        outcome.already = already;
-        outcome.parentId = into;
-        return intents;
-    });
+    const outcome = await moveEntries(session, paths, destination);
     const shownDestination = normalisePath(destination);
     const where = shownDestination === "" ? "the top of the drive" : `"${shownDestination}"`;
     if (options.json) {
-        const index = buildIndex(result.entries);
         say(JSON.stringify({
-            moved: outcome.moved.map((m) => {
-                const live = result.entries.find((e) => e.id === m.id);
-                return { id: m.id, name: m.name, path: live === undefined ? null : fullPathOf(index, live) };
-            }),
+            moved: outcome.moved.map((m) => ({ id: m.id, name: m.name, path: m.path })),
             already: outcome.already,
             parentId: outcome.parentId,
-            changed: result.changed,
-            reappliedAfterConflict: result.reappliedAfterConflict,
-            seq: result.seq,
+            changed: outcome.changed,
+            reappliedAfterConflict: outcome.reappliedAfterConflict,
+            seq: outcome.seq,
         }));
         return 0;
     }
@@ -214,7 +88,7 @@ export async function mv(operands, options = {}) {
     if (outcome.moved.length > 0 && outcome.already.length > 0) {
         say(`  ${outcome.already.map((n) => `"${n}"`).join(", ")} was already there.`);
     }
-    if (result.changed && result.reappliedAfterConflict) {
+    if (outcome.changed && outcome.reappliedAfterConflict) {
         say(`  Another device wrote the file list first, so this was applied to that version.`);
     }
     return 0;
@@ -228,61 +102,27 @@ export async function rename(path, name, options = {}) {
             nextStep: `For example: nmts rename notes.txt "meeting notes.txt"`,
         });
     }
-    if (name.includes("/")) {
-        throw new NmtsError(`A name cannot contain "/" — that is what makes it a path.`, {
-            exitCode: 2,
-            nextStep: `To move it, use \`nmts mv\`. Nothing was renamed.`,
-        });
-    }
+    // ⛔ ASKED HERE AS WELL AS INSIDE, AND IT IS THE SAME FUNCTION RATHER THAN A SECOND COPY. A name
+    //    with a `/` in it is wrong about the ARGUMENT, so it is refused before a session is opened —
+    //    otherwise a machine with no API key would be told about the key instead of about the name
+    //    that was typed.
+    requireNewName(name);
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    const entries = list.manifest?.entries ?? [];
-    const target = entryAt(entries, path, { nothingHappened: "Nothing was renamed." });
-    const at = Date.now();
-    const before = fullPathOf(buildIndex(entries), target);
-    // ⛔ REFUSED RATHER THAN NUMBERED, AND THE REFUSAL IS RE-DECIDED ON EVERY ATTEMPT. An upload
-    //    picks `report (2).pdf` because nobody was watching; a rename is somebody typing a name on
-    //    purpose, and silently giving them a different one is how two files end up looking like a
-    //    mistake nobody made. Checking once, before the write, was not enough: when another device
-    //    took the name in between, the retry re-applied the old decision and produced two entries at
-    //    one path, which no command in this tool can address afterwards (2026-08-23).
-    const result = await applyToList(session, (now) => {
-        const live = now.find((e) => e.id === target.id);
-        if (live === undefined)
-            return null;
-        if (normaliseName(name) !== normaliseName(live.name) && namesIn(now, live.parentId).has(normaliseName(name))) {
-            throw new NmtsError(`Something called "${name}" is already in that folder.`, {
-                exitCode: 4,
-                nextStep: "Nothing was renamed.",
-            });
-        }
-        return { op: "rename", id: target.id, name, at };
-    });
-    return report(say, options, result.changed, result.reappliedAfterConflict, {
-        text: result.changed ? `Renamed "${before}" to "${name}".` : `"${before}" is already called that.`,
+    const outcome = await renameEntry(session, path, name);
+    return report(say, options, outcome.changed, outcome.reappliedAfterConflict, {
+        text: outcome.changed
+            ? `Renamed "${outcome.fromPath}" to "${name}".`
+            : `"${outcome.fromPath}" is already called that.`,
         json: {
-            id: target.id,
-            from: target.name,
+            id: outcome.id,
+            from: outcome.from,
             to: name,
-            changed: result.changed,
-            reappliedAfterConflict: result.reappliedAfterConflict,
-            seq: result.seq,
+            changed: outcome.changed,
+            reappliedAfterConflict: outcome.reappliedAfterConflict,
+            seq: outcome.seq,
         },
     });
 }
-/** Is `id` at or under `rootId`? Used to refuse moving a folder into its own subtree. */
-function isUnder(entries, id, rootId) {
-    const byId = buildIndex(entries).byId;
-    const seen = new Set();
-    let at = id;
-    while (at !== null && !seen.has(at)) {
-        if (at === rootId)
-            return true;
-        seen.add(at);
-        at = byId.get(at)?.parentId ?? null;
-    }
-    return false;
-}
 function report(say, options, changed, conflicted, out) {
     if (options.json) {
         say(JSON.stringify(out.json));

package/dist/commands/push.js

@@ -36,7 +36,7 @@ import { createUploadApi } from "../upload-api.js";
 import { clearItemRecord, clearReservation } from "../upload-store.js";
 import { CREDIT_BYTES, partSizeFor, planAndPrice, UPLOAD_EPOCHS } from "../upload-price.js";
 import { createBlobProtocol, readCurrentEpoch } from "../walrus-write.js";
-import { ensureFolderPath } from "./organise.js";
+import { ensureFolderPath } from "../drive-edit.js";
 import { payerOf, refuseWalletOnlyOptions } from "./put.js";
 export async function push(target, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));

package/dist/commands/s3.d.ts

@@ -1,15 +1,5 @@
 /** MinIO's port, which is what most S3 tools already have in their examples. */
 export declare const DEFAULT_PORT = 9000;
-/**
- * How long a file list may be reused before it is fetched again.
- *
- * ⛔ THERE IS A CACHE BECAUSE A SYNC IS THOUSANDS OF REQUESTS. Reading the list per request would
- *    mean a server round trip and a decryption for each one, so a listing of a large drive would
- *    take minutes and cost the account's rate budget. ⚠ It also means a file uploaded from another
- *    device can be up to this long in appearing here, which is the trade and is written in the
- *    tool's own words when it starts.
- */
-export declare const LIST_CACHE_MS = 5000;
 export interface S3Options {
     server?: string | undefined;
     network?: string | undefined;