@needmoretruth/nmts-cli 0.38.0 → 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,14 @@
 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`

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.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.38.0    # 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.38.0";
+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/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>;

package/dist/drive-edit/move.js

@@ -0,0 +1,119 @@
+// Moving things into a folder, and giving one thing a new name where it is.
+import { buildIndex, entryAt, folderIdFor, fullPathOf, namesIn, normaliseName, } from "../drive-paths.js";
+import { readFileList } from "../manifest.js";
+import { applyManyToList, applyToList, batchTargets } from "../manifest-write.js";
+import { applyIntent } from "../shared/lib/drive/manifest-ops.js";
+import { DriveEditError, requireNewName, resolving } from "./errors.js";
+import { isUnder } from "./tree.js";
+/**
+ * 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 async function moveEntries(input, paths, destination) {
+    const at = Date.now();
+    let moved = [];
+    let already = [];
+    let 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 caller was told the move had been made.
+    const result = await applyManyToList(input, (now) => {
+        const targets = resolving(() => batchTargets(now, paths, { nothingHappened: "Nothing was moved." }));
+        const into = resolving(() => folderIdFor(destination, now, "Nothing was moved."));
+        const index = buildIndex(now);
+        const intents = [];
+        const carried = [];
+        const there = [];
+        let working = now;
+        for (const target of targets) {
+            if (into !== null && (into === target.id || isUnder(working, into, target.id))) {
+                throw new DriveEditError("INTO_ITSELF", `A folder cannot be moved inside itself.`, {
+                    exitCode: 4,
+                    nextStep: "Nothing was moved.",
+                });
+            }
+            if (into === target.parentId) {
+                there.push(target.name);
+                continue;
+            }
+            if (namesIn(working, into).has(normaliseName(target.name))) {
+                throw new DriveEditError("NAME_TAKEN", `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);
+            carried.push({ id: target.id, name: target.name, from: fullPathOf(index, target) });
+        }
+        moved = carried;
+        already = there;
+        parentId = into;
+        return intents;
+    });
+    // ⚠ Read off the list AS WRITTEN, not off the intents: an id another device took out of the list
+    //   meanwhile has no path any more, and claiming one would name a place nothing is at.
+    const after = buildIndex(result.entries);
+    return {
+        moved: moved.map((m) => {
+            const live = result.entries.find((e) => e.id === m.id);
+            return { id: m.id, name: m.name, from: m.from, path: live === undefined ? null : fullPathOf(after, live) };
+        }),
+        already,
+        parentId,
+        changed: result.changed,
+        reappliedAfterConflict: result.reappliedAfterConflict,
+        seq: result.seq,
+    };
+}
+/**
+ * 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 async function renameEntry(input, path, name) {
+    requireNewName(name);
+    const list = await readFileList(input.server, input.apiKey, input.code, input.accountId);
+    const entries = list.manifest?.entries ?? [];
+    const target = resolving(() => entryAt(entries, path, { nothingHappened: "Nothing was renamed." }));
+    const at = Date.now();
+    const fromPath = fullPathOf(buildIndex(entries), target);
+    const result = await applyToList(input, (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 DriveEditError("NAME_TAKEN", `Something called "${name}" is already in that folder.`, {
+                exitCode: 4,
+                nextStep: "Nothing was renamed.",
+            });
+        }
+        return { op: "rename", id: target.id, name, at };
+    });
+    return {
+        id: target.id,
+        from: target.name,
+        fromPath,
+        to: name,
+        changed: result.changed,
+        reappliedAfterConflict: result.reappliedAfterConflict,
+        seq: result.seq,
+    };
+}

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

@@ -0,0 +1,53 @@
+import { type ListEditInput } from "../manifest-write.ts";
+/**
+ * What one run of the trash did — and, in this order, exactly what `nmts rm --json` prints.
+ *
+ * ⛔ THE ORDER OF THESE FIELDS IS THE COMMAND'S JSON. The command hands this object straight to
+ *    `JSON.stringify`, so a field added in the middle changes what an agent reading that output
+ *    sees. Add at the end, or not at all.
+ */
+export interface TrashOutcome {
+    /** The paths acted on. Empty when everything named was already where it was asked to be. */
+    paths: string[];
+    /** Their ids, in the same order. */
+    ids: string[];
+    /** How many server rows were moved. A folder has none of its own; its files have one each. */
+    files: number;
+    /** Named, and nothing written for them: already out of the trash, or covered by a named folder. */
+    skipped: string[];
+    changed: boolean;
+    reappliedAfterConflict: boolean;
+    seq: number;
+}
+export interface TrashEditOptions {
+    /**
+     * Refuse what the command-line tool names and carries on with.
+     *
+     * ⛔ OFF FOR THE COMMANDS AND ON FOR A LIBRARY, and the difference is who is reading. A person
+     *    who typed `nmts restore a.txt b.txt` and had already restored `a.txt` wants `b.txt` back and
+     *    a line saying the first was not in the trash; a program calling `restore` wants to know that
+     *    what it asked for was not what it got, and the only way it learns that is a refusal.
+     *
+     * It adds two: a path that is not in the trash (`NOT_IN_TRASH`) and a restore whose old name has
+     * been taken since (`NAME_TAKEN`).
+     */
+    strict?: boolean;
+}
+/**
+ * Move things to the trash, or bring them back.
+ *
+ * ⛔ NEITHER HALF DESTROYS ANYTHING. `rm` moves everything it is given to the trash, where it stays
+ *    restorable for thirty days; the endpoint that erases a stored row for good is closed to an API
+ *    key and stays closed, so nothing here can reach it.
+ *
+ * ⛔ THE SERVER ROW GOES FIRST, AND "ALREADY DONE" COUNTS AS DONE. A trashed item's bytes cannot be
+ *    fetched, so the state to avoid above all others is a list that shows a file as live when the
+ *    server has already trashed it: the person sees it, asks for it, and is told it does not exist.
+ *    Writing the list only after the server agreed means a failed server call leaves the drive
+ *    exactly as it was — the state a caller can act on.
+ *
+ * ⛔ AND ONE PATH THAT WILL NOT RESOLVE REFUSES THE WHOLE RUN, before a single server row is
+ *    touched. Trashing four of the five things somebody named and answering success is worse than
+ *    trashing none: the run reads as done, and finding the odd one out means diffing the drive.
+ */
+export declare function trashPaths(input: ListEditInput, verb: "rm" | "restore", paths: readonly string[], options?: TrashEditOptions): Promise<TrashOutcome>;