@needmoretruth/nmts-cli 0.38.0 → 0.39.0

package/AGENTS.md

@@ -40,6 +40,15 @@ 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
+
+- **Storage for an agent**, outliving a session or a machine: this command, or [its MCP server](#if-your-client-speaks-mcp).
+- **Encrypted storage inside a product.** The [SDK](https://github.com/needmoretruth/nmts-sdk) (`npm install @needmoretruth/nmts-sdk`; it has an `AGENTS.md` of its own) opens an account per user. The user holds the NMTS key, or the product does (`Nmts.managed`); every method works either way, and [terms](https://nmts.me/terms) 3.7 provides for it, commercially too.
+- **An S3 endpoint**, `@needmoretruth/nmts-sdk/gateway`: 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 them from Walrus with the NMTS key and the recovery list the person saved. No NMTS server takes part.
+
+All of it works with what is published now. An account pays with credits or from its own wallet — WAL to Walrus, SUI to the chain, no fee to NMTS. NMTS does not inspect or certify products built with the SDK: who holds the keys in one 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.
@@ -167,12 +176,10 @@ work around it. Setup and the sealed-code rule: `nmts help mcp`.
 
 ## Remembering this across sessions
 
-You will lose this context. The person has to put it somewhere your next session reads: the file
-your client loads from a repository root, holding the first section above and the two
-environment variable names; a saved instruction saying *the `nmts` command manages files in an
-NMTS account; run `nmts env` first, then `nmts --help`, and `nmts help <command>` before a command
-you have not used*; or, for an MCP client, the server entry. The smallest thing that works is one
-line pointing at this file.
+You will lose this context. The person has to put it somewhere your next session reads: the file your client
+loads from a repository root, holding the first section above and the two environment variable names; a saved
+instruction saying *the `nmts` command manages files in an NMTS account; run `nmts env` first, then `nmts --help`,
+and `nmts help <command>` before a command you have not used*; or, for an MCP client, the server entry. One line pointing at this file is the smallest thing that works.
 
 ## Reporting a problem or an idea
 
@@ -182,17 +189,11 @@ run at all, write to `nmts@nmts.me` with what you ran and what it said.
 
 ## Exit codes
 
-`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in ·
-`4` the command exists but could not do it · `5` waiting on the person's agreement ·
-`130` cancelled.
+`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in · `4` the command exists
+but could not do it · `5` waiting on the person's agreement · `130` cancelled.
 
-## Licence
+## Licence and source
 
 Apache-2.0 (it was AGPL-3.0-only until 2026-08-30). **Calling this program from your own code puts
 no obligation on your code at all.** See [LICENSING.md](https://github.com/needmoretruth/nmts-cli/blob/main/LICENSING.md) if you are asked.
-
-## Source
-
-<https://github.com/needmoretruth/nmts-cli> · The same operations as a library, for a program that calls
-NMTS from its own code: `npm install @needmoretruth/nmts-sdk` · <https://github.com/needmoretruth/nmts-sdk>
-(its own document for agents is `AGENTS.md` there).
+Source: <https://github.com/needmoretruth/nmts-cli>.

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 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.39.0 — 2026-09-20
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/drive-erase`: what `nmts erase` does,
+  without the prompt or the printing, so a program can erase files for good with the same order of
+  operations. `nmts erase` is unchanged: the same sentence to type, the same output, the same exit
+  codes. `nmts-sdk` 0.5.0 is built on it.
+- A delegation token can carry a fifth scope, `files_erase`. The server still asks for the NMTS
+  key's own proof on the two erase requests.
+
+## 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`

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

@@ -9,28 +9,21 @@
 //    with credits, `--release-storage` asks the server to destroy the treasury's storage under
 //    each file first, which it does on the chain one blob at a time and reports per file.
 //
-// ⛔ THE SERVER GOES FIRST, THE LIST LAST. A row erased before the list entry leaves a file the
-//    person can see and never open; that is the same order the trash keeps, for the same reason.
-//    A release that fails leaves the file whole — nothing is erased behind a failed release.
+// ⛔ THE ORDER, AND WHAT IT PROTECTS, ARE IN `drive-erase.ts` — the server first, the list last, a
+//    failed release erasing nothing behind it. This file is the terminal over that: the sentence
+//    that has to be typed, the lines a person reads, and the exit code. Nothing about what is
+//    destroyed is decided twice.
 //
 // ⛔ THE SENTENCE IS TYPED IN EVERY MODE BUT SKIP-PERMISSIONS, where the tier gate's `--reason`
 //    and `--yes` stand for it — the same rule as `delete-account`, because it is the same tier.
 import { accountProofFor } from "../account-proof.js";
-import { request, ServerError } from "../api.js";
 import { currentMode } from "../autonomy.js";
 import { CONFIRM_SENTENCE } from "./delete-account.js";
-import { buildIndex, fullPathOf, KIND_FILE } from "../drive-paths.js";
+import { eraseFiles, planErase } from "../drive-erase.js";
 import { NmtsError } from "../errors.js";
-import { readFileList } from "../manifest.js";
-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 "../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. */
-const FEE_INSUFFICIENT = "DEPOSIT_FEE_INSUFFICIENT";
 export async function erase(paths, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     if (paths.length === 0) {
@@ -48,20 +41,11 @@ export async function erase(paths, options = {}) {
         });
     }
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    const entries = list.manifest?.entries ?? [];
-    const index = buildIndex(entries);
-    const targets = batchTargets(entries, paths, { includeTrashed: true, nothingHappened: "Nothing was erased." });
-    const files = uniqueById(targets.flatMap((t) => (t.kind === KIND_FILE ? [t] : filesUnder(entries, t.id))));
-    const going = uniqueById([...targets, ...files]);
-    if (files.length === 0) {
-        throw new NmtsError(`Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
-            exitCode: 4,
-        });
-    }
+    const plan = await planErase(session, paths);
+    const files = plan.files;
     say(`This erases ${files.length} file${files.length === 1 ? "" : "s"} for good. It cannot be undone, and not by the trash.`);
     for (const f of files)
-        say(`  ${fullPathOf(index, f)}`);
+        say(`  ${f.path}`);
     say(``);
     say(`  Erased:       the server's record of each file and this account's key to it, and its shares.`);
     if (options.releaseStorage === true) {
@@ -81,65 +65,12 @@ export async function erase(paths, options = {}) {
     }
     // ⛔ THE PROOF IS BUILT FOR THIS ONE RUN AND NOTHING KEEPS IT.
     const accountProof = await accountProofFor({ code: session.code, source: session.source });
-    const releases = [];
-    if (options.releaseStorage === true) {
-        for (const f of files) {
-            const path = fullPathOf(index, f);
-            try {
-                const reply = await request(session.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
-                    method: "POST",
-                    body: {},
-                    token: session.apiKey,
-                    accountProof,
-                });
-                releases.push({ path, refused: null, ...counts(reply), ...fee(reply) });
-            }
-            catch (error) {
-                // ⛔ THE ONE REFUSAL THAT STOPS THE RUN. A file with no deposit pays twice the chain fee
-                //    out of the balance, and a balance that cannot cover it means the release did not
-                //    happen — erasing behind it would destroy the account's key to bytes that are still
-                //    being served and still being paid for. Nothing is erased, and the two numbers say
-                //    exactly how far short the balance is.
-                if (error instanceof ServerError && error.code === FEE_INSUFFICIENT) {
-                    throw new NmtsError(`${path}: releasing its storage costs ${amount(error, "needed_credits")} credits and this ` +
-                        `account has ${amount(error, "balance_credits")}. It has no deposit, so the fee comes out of the balance.`, {
-                        exitCode: 4,
-                        nextStep: `Nothing was erased. Buy credits and run this again, or leave --release-storage off ` +
-                            `to erase the file and let its storage run out on its own.`,
-                    });
-                }
-                // ⚠ "Not ours to destroy" is an answer, not a failure: the storage was bought by the
-                //   wallet, and the erase goes on. A refusal of the KEY or the proof, and anything the
-                //   server could not do, stops the run before a row is touched.
-                if (error instanceof ServerError && error.status !== 401 && error.status !== 403 && error.status < 500) {
-                    releases.push({ path, released: 0, alreadyReleased: 0, failed: 0, feeCredits: 0, fromDeposit: false, refused: error.message });
-                    continue;
-                }
-                throw error;
-            }
-        }
-    }
-    let erased = 0;
-    for (let i = 0; i < files.length; i += BATCH) {
-        const reply = await request(session.server, "/v1/items/erase", {
-            method: "POST",
-            body: { item_ids: files.slice(i, i + BATCH).map((f) => f.id) },
-            token: session.apiKey,
-            accountProof,
-        });
-        erased += typeof reply === "object" && reply !== null && typeof Reflect.get(reply, "erased") === "number"
-            ? Number(Reflect.get(reply, "erased"))
-            : 0;
-    }
-    // ⛔ THE LIST GOES LAST, and re-decided against the list as it is on this attempt: only the
-    //    ids this run erased leave it, whatever another device wrote in between.
-    const ids = new Set(going.map((e) => e.id));
-    const result = await applyToList(session, (current) => {
-        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
-        return still.length === 0 ? null : { op: "purge", ids: still };
+    const outcome = await eraseFiles({ ...session, accountProof }, plan, {
+        releaseStorage: options.releaseStorage === true,
     });
+    const { erased, releases } = outcome;
     if (options.json) {
-        say(JSON.stringify({ erased, files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })), releases, seq: result.seq }));
+        say(JSON.stringify({ erased, files: outcome.files, releases, seq: outcome.seq }));
         return 0;
     }
     say(`Erased ${erased} file${erased === 1 ? "" : "s"}. Their entries are out of the file list.`);
@@ -165,29 +96,3 @@ function feeLine(r) {
         ? `${credits} taken from that file's deposit — nothing came out of the balance`
         : `${credits} taken from the balance — that file had no deposit, so the fee is doubled`;
 }
-/** The three counts a release answers with, read defensively. */
-function counts(reply) {
-    const n = (name) => {
-        const v = typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
-        return typeof v === "number" ? v : 0;
-    };
-    return { released: n("released"), alreadyReleased: n("already_released"), failed: n("failed") };
-}
-/** What it cost, read the same defensive way. An older server says neither, which reads as 0. */
-function fee(reply) {
-    const at = (name) => typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
-    const charged = at("fee_credits");
-    return {
-        feeCredits: typeof charged === "number" ? charged : 0,
-        fromDeposit: at("from_deposit") === true,
-    };
-}
-/** One credit amount out of a refusal's details, or `?` when the server did not name it. */
-function amount(error, field) {
-    const value = error.details[field];
-    return typeof value === "number" ? String(value) : "?";
-}
-function uniqueById(list) {
-    const seen = new Set();
-    return list.filter((e) => (seen.has(e.id) ? false : (seen.add(e.id), true)));
-}

package/dist/drive-edit/errors.d.ts

@@ -0,0 +1,44 @@
+import { NmtsError } from "../errors.ts";
+/**
+ * What went wrong, in a word a program can branch on.
+ *
+ * ⚠ FIVE, AND THEY ARE ABOUT THE LIST. A server refusal arrives as `ServerError` with the server's
+ *   own code, and a lost compare-and-swap that never settles arrives as a plain `NmtsError`;
+ *   neither is a decision this file made.
+ */
+export type DriveEditCode = 
+/** No entry at that path — or a path that names two, which is the same "which one?" */
+"NOT_FOUND"
+/** Something else in that folder already answers to that name. */
+ | "NAME_TAKEN"
+/** The name itself cannot be used: empty, `.`, `..`, or a path pretending to be a name. */
+ | "BAD_NAME"
+/** A restore was asked for something that is not in the trash, or not in it on its own account. */
+ | "NOT_IN_TRASH"
+/** A folder was asked to move inside itself. */
+ | "INTO_ITSELF";
+/** A refusal about the list, with the sentence a person reads and the word a program reads. */
+export declare class DriveEditError extends NmtsError {
+    readonly code: DriveEditCode;
+    constructor(code: DriveEditCode, message: string, options?: {
+        exitCode?: number;
+        nextStep?: string | null;
+    });
+}
+/**
+ * Run a path lookup, and label whatever it refused as `NOT_FOUND`.
+ *
+ * ⛔ THE SENTENCE, THE EXIT CODE AND THE NEXT STEP ARE CARRIED THROUGH UNTOUCHED. `drive-paths.ts`
+ *    words three different failures — nothing there, it is in the trash, it names two things — and
+ *    each of them is better than anything this file could say about them. What is added is the one
+ *    thing it cannot carry: a code, so a program does not have to read English to know a path did
+ *    not resolve.
+ */
+export declare function resolving<T>(body: () => T): T;
+/**
+ * A new name is a name and not a path.
+ *
+ * ⛔ REFUSED RATHER THAN SPLIT. A name with a `/` in it is somebody asking for a move while typing
+ *    a rename, and quietly doing the move would put the file somewhere they did not look.
+ */
+export declare function requireNewName(name: string): string;

package/dist/drive-edit/errors.js

@@ -0,0 +1,65 @@
+// What the drive's own edits refuse with: a word a program branches on, and the one rule that
+// decides whether a new name is a name at all.
+//
+// ⛔ AND EVERY REFUSAL THIS FILE MAKES CARRIES A CODE. A terminal reads the sentence; a program
+//    reads `error.code` and branches on it. That is why `DriveEditError` EXTENDS the tool's own
+//    error rather than replacing it: the exit code and the next step are still there, `renderError`
+//    prints exactly what it printed before, and `error instanceof NmtsError` is still true.
+//
+// ⚠ THE ARGUMENT-SHAPE REFUSALS ARE NOT HERE. "`nmts rename` needs what to rename" is about a
+//   command line, and a library caller has no command line to be told about. What IS here is every
+//   refusal about the LIST, because that one is the same question whoever asked it.
+import { NmtsError } from "../errors.js";
+/** A refusal about the list, with the sentence a person reads and the word a program reads. */
+export class DriveEditError extends NmtsError {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.name = "DriveEditError";
+        this.code = code;
+    }
+}
+/**
+ * Run a path lookup, and label whatever it refused as `NOT_FOUND`.
+ *
+ * ⛔ THE SENTENCE, THE EXIT CODE AND THE NEXT STEP ARE CARRIED THROUGH UNTOUCHED. `drive-paths.ts`
+ *    words three different failures — nothing there, it is in the trash, it names two things — and
+ *    each of them is better than anything this file could say about them. What is added is the one
+ *    thing it cannot carry: a code, so a program does not have to read English to know a path did
+ *    not resolve.
+ */
+export function resolving(body) {
+    try {
+        return body();
+    }
+    catch (error) {
+        if (error instanceof NmtsError && !(error instanceof DriveEditError)) {
+            throw new DriveEditError("NOT_FOUND", error.message, {
+                exitCode: error.exitCode,
+                nextStep: error.nextStep,
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * A new name is a name and not a path.
+ *
+ * ⛔ REFUSED RATHER THAN SPLIT. A name with a `/` in it is somebody asking for a move while typing
+ *    a rename, and quietly doing the move would put the file somewhere they did not look.
+ */
+export function requireNewName(name) {
+    if (name.trim() === "") {
+        throw new DriveEditError("BAD_NAME", "A name cannot be empty.", {
+            exitCode: 2,
+            nextStep: "Nothing was renamed.",
+        });
+    }
+    if (name.includes("/")) {
+        throw new DriveEditError("BAD_NAME", `A name cannot contain "/" — that is what makes it a path.`, {
+            exitCode: 2,
+            nextStep: `To move it, use \`nmts mv\`. Nothing was renamed.`,
+        });
+    }
+    return name;
+}

package/dist/drive-edit/folders.d.ts

@@ -0,0 +1,29 @@
+import { type ListEditInput } from "../manifest-write.ts";
+/**
+ * Make a folder path, and every folder above it that is missing, for an account already opened.
+ *
+ * ⛔ 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. 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 a caller that has to discover the tree one
+ *   call at a time. Every folder made is named in the result, so it is never a surprise.
+ */
+export declare function ensureFolderPath(input: ListEditInput, wanted: string): Promise<{
+    parentId: string | null;
+    made: string[];
+}>;
+/** What making a folder did. `made` is empty when every folder in the path was already there. */
+export interface MadeFolder {
+    /** The path as the drive spells it — no leading slash, no trailing one. */
+    path: string;
+    /** The folder at the end of the path. Null only for the top of the drive, which is never made. */
+    parentId: string | null;
+    /** The folders this call actually made, outermost first. */
+    made: string[];
+}
+/** Make one folder path. A path that is already there is a success with nothing made. */
+export declare function makeFolder(input: ListEditInput, path: string): Promise<MadeFolder>;

package/dist/drive-edit/folders.js

@@ -0,0 +1,98 @@
+// Making a folder, and every folder above it that is missing.
+import { KIND_FOLDER, normaliseName, normalisePath } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { applyToList } from "../manifest-write.js";
+import { DriveEditError } from "./errors.js";
+/**
+ * Make a folder path, and every folder above it that is missing, for an account already opened.
+ *
+ * ⛔ 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. 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 a caller that has to discover the tree one
+ *   call at a time. Every folder made is named in the result, so it is never a surprise.
+ */
+export async function ensureFolderPath(input, 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 DriveEditError("BAD_NAME", `"${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;
+        // The global one, not `node:crypto`: the SDK's browser entry bundles this file.
+        const fresh = globalThis.crypto.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(input, (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 DriveEditError("NAME_TAKEN", `"${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 };
+}
+/** Make one folder path. A path that is already there is a success with nothing made. */
+export async function makeFolder(input, path) {
+    const wanted = normalisePath(path);
+    if (wanted === "") {
+        throw new DriveEditError("BAD_NAME", `"${path}" names the whole drive, not a folder in it.`, {
+            exitCode: 2,
+            nextStep: "Nothing was made.",
+        });
+    }
+    const { parentId, made } = await ensureFolderPath(input, wanted);
+    return { path: wanted, parentId, made };
+}

package/dist/drive-edit/move.d.ts

@@ -0,0 +1,66 @@
+import { type ListEditInput } from "../manifest-write.ts";
+/** One thing a move carried, with where it came from and where it landed. */
+export interface MovedThing {
+    id: string;
+    /** Its name, which a move never changes. */
+    name: string;
+    /** Its full path before the move. */
+    from: string;
+    /** Its full path after, or null if another device took it out of the list meanwhile. */
+    path: string | null;
+}
+/** What one run of moving did. */
+export interface MoveOutcome {
+    /** The things this run moved, in the order they were named. */
+    moved: MovedThing[];
+    /** The names that were already in the destination, so nothing was written for them. */
+    already: string[];
+    /** The destination folder id, or null for the top of the drive. */
+    parentId: string | null;
+    /** False when everything named was already there, so no list was written. */
+    changed: boolean;
+    /** True when the list was rebuilt because another device wrote first. */
+    reappliedAfterConflict: boolean;
+    /** The list version now current. */
+    seq: number;
+}
+/**
+ * Move things into a folder. An empty destination is 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 call,
+ *    would otherwise both be written — two entries at one path, which nothing can address
+ *    afterwards: every lookup 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.
+ */
+export declare function moveEntries(input: ListEditInput, paths: readonly string[], destination: string): Promise<MoveOutcome>;
+/** What renaming one thing did. */
+export interface RenameOutcome {
+    id: string;
+    /** The name it had. */
+    from: string;
+    /** The full path it had, which is what a person recognises it by. */
+    fromPath: string;
+    /** The name it has now. */
+    to: string;
+    /** False when it was already called that, so no list was written. */
+    changed: boolean;
+    reappliedAfterConflict: boolean;
+    seq: number;
+}
+/**
+ * Give one thing a new name. The path stays the same otherwise.
+ *
+ * ⛔ 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 choosing 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
+ *    nothing can address afterwards (2026-08-23).
+ */
+export declare function renameEntry(input: ListEditInput, path: string, name: string): Promise<RenameOutcome>;