@needmoretruth/nmts-cli 0.36.3 → 0.38.1

package/dist/commands/s3.js

@@ -13,17 +13,13 @@
 //    machine -- and a gateway cannot ask, because its caller is a program and its stdin is not a
 //    terminal. So the agreement has to exist before it starts: without it the drive is served read
 //    only and every write is refused with the sentence naming the command that grants it.
-import { createWriteStream } from "node:fs";
-import { mkdir as makeDir, rm as removeFile, stat } from "node:fs/promises";
+import { rm as removeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { pipeline } from "node:stream/promises";
 import { randomUUID } from "node:crypto";
-import { createStaging } from "../s3/staging.js";
-import { refusalFor, verdictForKey } from "../s3/same-file.js";
-import { fetchFile } from "../download.js";
+import { createDriveSource, fetchObject, LIST_CACHE_MS } from "../s3/drive.js";
 import { NmtsError } from "../errors.js";
-import { ensureFolderPath } from "./organise.js";
+import { ensureFolderPath } from "../drive-edit.js";
 import { put } from "./put.js";
 import { rm } from "./trash.js";
 import { readFileList } from "../manifest.js";
@@ -34,16 +30,6 @@ import { BUCKET } from "../s3/listing.js";
 import { BIND_ADDRESS, createGateway, newCredential } from "../s3/server.js";
 /** MinIO's port, which is what most S3 tools already have in their examples. */
 export 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 const LIST_CACHE_MS = 5_000;
 function portOf(raw) {
     if (raw === undefined)
         return DEFAULT_PORT;
@@ -59,16 +45,6 @@ export async function s3(options = {}) {
     const session = await openSession({ server: options.server, network: options.network });
     const chain = resolveNetwork(session.server, session.network);
     const credential = newCredential();
-    let cached = [];
-    let cachedAt = 0;
-    const entries = async () => {
-        if (Date.now() - cachedAt < LIST_CACHE_MS)
-            return cached;
-        const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-        cached = list.manifest === null ? [] : list.manifest.entries;
-        cachedAt = Date.now();
-        return cached;
-    };
     /**
      * Where the pieces of a multipart upload wait until they are one file.
      *
@@ -78,109 +54,58 @@ export async function s3(options = {}) {
      *    takes and afterwards.
      */
     const stagingRoot = join(tmpdir(), `nmts-s3-${randomUUID()}`);
-    /**
-     * Store one local file at a drive key, making the folders above it if they are missing.
-     *
-     * ⛔ THE SAME-FILE QUESTION IS ANSWERED HERE AND NOWHERE ELSE.
-     *    Both ways of uploading — one PUT, or pieces staged and joined — end in this
-     *    function, so a rule written here cannot disagree with itself; written in the protocol layer
-     *    it would have to be written twice, once for each, and the two would differ the first time
-     *    one of them changed. What is compared is the plaintext's SHA-256 against the one this
-     *    account sealed when the file was first stored.
-     *
-     * ⛔ IDENTICAL CONTENT IS NOT AN ERROR. Nothing is sent and nothing is charged, and the caller
-     *    is told the upload finished — because the statement it was making, "that file is at that
-     *    key", is true. Answering 409 there is what made every backup run fail on every file it had
-     *    already stored, and a sync tool writes 409 down as a failure.
-     */
-    const storeFile = async (key, path) => {
-        const at = key.lastIndexOf("/");
-        const folder = at < 0 ? undefined : key.slice(0, at);
-        const name = at < 0 ? key : key.slice(at + 1);
-        const verdict = await verdictForKey(await entries(), key, session.code, path);
-        // ⭐ Already there, byte for byte. This is the whole point: an unchanged file costs nothing to
-        //    re-offer, so a backup that runs nightly stops paying for the nights nothing changed.
-        if (verdict === "same") {
-            say(`same ${key} — already stored, nothing sent`);
-            return;
-        }
-        if (verdict !== "free")
-            throw refusalFor(verdict, key);
-        if (folder !== undefined && folder !== "")
-            await ensureFolderPath(session, folder);
-        await put(path, {
-            server: options.server,
-            network: options.network,
-            ...(folder === undefined || folder === "" ? {} : { to: folder }),
-            name,
-            write: () => undefined,
-        });
-        cachedAt = 0;
-    };
     // ⛔ THE QUESTION WAS ANSWERED BEFORE THIS STARTED. A gateway cannot ask: its caller is a program
     //    and its stdin is not a terminal. `s3` is a medium act (`risk.ts`) — uploads through it spend
     //    credits — so the tier gate asked at the start, or the mode waved it through, and every write
     //    from here on is what was agreed to.
     const writable = true;
-    const server = createGateway({
-        credential,
-        source: {
-            entries,
-            ...(writable
-                ? {
-                    write: {
-                        // ⛔ THE BODY IS SPOOLED TO A FILE FIRST, 0600, and deleted whatever happens. The
-                        //    upload path reserves storage, cuts parts and seals them from a file, and giving
-                        //    it a socket instead would mean either holding whole uploads in memory or
-                        //    writing a second upload path — and a second upload path is a second place for
-                        //    "what if the reservation succeeds and the part fails" to be got right.
-                        put: async (key, body, size) => {
-                            await makeDir(stagingRoot, { recursive: true, mode: 0o700 });
-                            const spool = join(stagingRoot, randomUUID());
-                            try {
-                                await pipeline(body, createWriteStream(spool, { mode: 0o600 }));
-                                const written = (await stat(spool)).size;
-                                if (written !== size) {
-                                    throw new NmtsError(`The upload said ${size} bytes and ${written} arrived. Nothing was stored.`);
-                                }
-                                await storeFile(key, spool);
-                            }
-                            finally {
-                                await removeFile(spool, { force: true });
-                            }
-                        },
-                        multipart: createStaging(stagingRoot, storeFile),
-                        trash: async (object) => {
-                            await rm([`/${object.key}`], {
-                                server: options.server,
-                                network: options.network,
-                                write: () => undefined,
-                            });
-                            cachedAt = 0;
-                        },
-                    },
-                }
-                : {}),
-            // The real reader. The gateway takes it as a function so its own tests can be driven by a
-            // real S3 client without an account, a network or anybody's credits.
-            fetch: async (object, sink) => {
-                const wrapped = object.entry.dekWrapped;
-                if (wrapped === undefined)
-                    throw new NmtsError("That entry has no key in the file list.");
-                await fetchFile({
-                    base: session.server,
-                    apiKey: session.apiKey,
-                    accountCode: session.code,
-                    itemId: object.entry.id,
-                    size: object.size,
-                    dekWrapped: wrapped,
-                    contentHashCt: object.entry.contentHashCt,
-                    chain,
-                    sink,
+    /**
+     * This account, as the shared drive module takes it.
+     *
+     * ⛔ THE SIX FUNCTIONS ARE THE ONLY THING THIS COMMAND CONTRIBUTES. What an upload DOES — the
+     *    same-file verdict, the folders above the key, forgetting the cached list — lives in
+     *    `s3/drive.ts`, so that the gateway a business runs from the SDK and the one a person runs
+     *    here cannot come to disagree about it.
+     */
+    const source = createDriveSource({
+        stagingRoot,
+        writable,
+        onAlreadyStored: (key) => say(`same ${key} — already stored, nothing sent`),
+        account: {
+            readList: async () => {
+                const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+                return list.manifest === null ? [] : list.manifest.entries;
+            },
+            // The command holds the code for its whole run: a person started it and is standing there.
+            withCode: (use) => use(session.code),
+            makeFolder: async (folder) => {
+                await ensureFolderPath(session, folder);
+            },
+            store: async (path, name, folder) => {
+                await put(path, {
+                    server: options.server,
+                    network: options.network,
+                    ...(folder === undefined ? {} : { to: folder }),
+                    name,
+                    write: () => undefined,
                 });
             },
+            trash: async (path) => {
+                await rm([path], {
+                    server: options.server,
+                    network: options.network,
+                    write: () => undefined,
+                });
+            },
+            fetch: (object, sink) => fetchObject({ server: session.server, bearer: session.apiKey, code: session.code, chain }, object, sink),
         },
     });
+    const server = createGateway({
+        credentials: [credential],
+        // One name, one drive — which is what a bucket is for a person serving their own account.
+        bucketOf: (name) => (name === BUCKET ? source : null),
+        bucketNames: () => [BUCKET],
+    });
     await new Promise((resolve, reject) => {
         server.once("error", (error) => {
             reject(error.code === "EADDRINUSE"

package/dist/commands/trash.d.ts

@@ -1,4 +1,3 @@
-import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
 export interface TrashOptions {
     server?: string | undefined;
     network?: string | undefined;
@@ -7,11 +6,3 @@ export interface TrashOptions {
 }
 export declare function rm(paths: readonly string[], options?: TrashOptions): Promise<number>;
 export declare function restore(paths: readonly string[], options?: TrashOptions): Promise<number>;
-/**
- * Every file at or under one entry.
- *
- * ⚠ Trashed descendants are INCLUDED HERE, and the CALLER filters. Somebody who trashed one file
- *   last week and then trashes its folder expects the folder to be gone from the server too — so
- *   `rm` takes this set whole. `restore` cannot: see the note at the call site.
- */
-export declare function filesUnder(entries: readonly ManifestEntry[], rootId: string): ManifestEntry[];

package/dist/commands/trash.js

@@ -1,5 +1,10 @@
 // `nmts rm` and `nmts restore` — the two halves of the trash.
 //
+// ⛔ WHAT THEY DO IS IN `drive-edit.ts`; WHAT IS HERE IS THE TERMINAL. The server rows, the list
+//    write and every refusal about the list moved out the day the SDK needed the same two verbs
+//    without one — and the order of the two (row first, list second) is the rule a second copy
+//    would be most likely to get backwards.
+//
 // ⛔ NEITHER OF THESE 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 no command here can reach it.
@@ -18,25 +23,9 @@
 //   said no verb without an undo would ever live in this tool; that stopped being true the day
 //   the sweep arrived, and a header that goes on describing the world before a change is the way
 //   the next reader is misled.
-//
-// ⛔ THE SERVER ROW GOES FIRST, AND "ALREADY DONE" COUNTS AS DONE. The order is not arbitrary and
-//    neither is the forgiveness:
-//      · A trashed item's bytes cannot be fetched — `GET /v1/items/{id}/parts` requires
-//        `deleted_at IS NULL`. So the state to avoid above all others is a drive 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, which is the state a person can act on.
-//      · And a 404 from the server means the row is already in the state being asked for, which
-//        is what an interrupted run leaves behind. Treating it as a failure would make the retry
-//        of a half-finished command impossible — the one moment the retry is needed.
-import { setTrashed } from "../item-trash.js";
-import { buildIndex, fullPathOf, isLive, KIND_FILE } from "../drive-paths.js";
+import { trashPaths } from "../drive-edit.js";
 import { NmtsError } from "../errors.js";
-import { readFileList } from "../manifest.js";
-import { applyManyToList, batchTargets } from "../manifest-write.js";
 import { openSession } from "../session.js";
-import { applyIntent } from "../shared/lib/drive/manifest-ops.js";
 export async function rm(paths, options = {}) {
     return run("rm", paths, options);
 }
@@ -52,150 +41,30 @@ async function run(verb, paths, options) {
         });
     }
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    const entries = list.manifest?.entries ?? [];
-    // ⛔ `rm` REFUSES what is already in the trash rather than quietly doing nothing, so the caller
-    //    learns nothing was needed; `restore` has to be able to SEE the trash to act on it. That is
-    //    why the two lookups differ. (The comment that used to sit here claimed a shared lookup would
-    //    make `rm` say "no such path" — it would not: the refusal below names the trash either way.
-    //    A reason that does not hold teaches the next reader to keep the wrong branch.)
-    //
-    // ⛔ 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 exiting 0 is worse than
-    //    trashing none: the run reads as done, and finding the odd one out means diffing the drive.
-    const index = buildIndex(entries);
-    const found = batchTargets(entries, paths, {
-        ...(verb === "restore" ? { includeTrashed: true } : {}),
-        nothingHappened: "Nothing changed.",
-    });
-    const acting = [];
-    const skipped = [];
-    for (const entry of found) {
-        const at = fullPathOf(index, entry);
-        if (verb === "restore" && isLive(index, entry)) {
-            // Already in the state being asked for. Not a refusal — named, and left alone.
-            skipped.push(at);
-            continue;
-        }
-        if (verb === "restore" && entry.deletedAt === undefined) {
-            // In the trash, but only because something above it is. Restoring this row would clear a
-            // `deletedAt` it does not have and leave the person exactly where they were.
-            throw new NmtsError(`"${at}" is in the trash because a folder above it is.`, {
-                exitCode: 4,
-                nextStep: `Nothing changed. Restore that folder instead — \`nmts ls --all\` shows which one carries the trash.`,
-            });
-        }
-        acting.push({ entry, path: at });
-    }
-    // ⛔ NAMING A FOLDER AND SOMETHING INSIDE IT IS NAMING ONE TRASHING TWICE, and only for `rm` is
-    //    that a problem worth solving here: stamping the child as well would give it a thirty-day
-    //    clock of its own, and then restoring the folder would leave it behind — the person would
-    //    have to remember they had also named it to ever find it again. Its bytes are covered
-    //    either way, because the rows are read from the folder. `restore` is the opposite case: a
-    //    child with its own instant needs its own clearing, so nothing is dropped there.
-    const named = new Set(acting.map((t) => t.entry.id));
-    const covered = verb === "rm" ? acting.filter((t) => hasNamedAncestor(entries, t.entry, named)) : [];
-    const targets = acting.filter((t) => !covered.includes(t));
-    for (const t of covered)
-        skipped.push(t.path);
-    if (targets.length === 0) {
-        // Everything named was already where it was asked to be. A no-op is a success: writing the
-        // list would cost every other device a download for nothing.
-        return nothingToDo(say, options, verb, skipped, list.seq ?? 0);
-    }
-    // Every FILE at or under the targets — a folder holds no bytes and has no server row, so the
-    // rows to move are its file descendants.
-    //
-    // ⛔ THE ROWS TO MOVE ARE THE ONES THE EDIT WILL MAKE REACHABLE, so the set is read off a
-    //    PREVIEW of the list rather than guessed (2026-08-23). `rm` is easy — everything
-    //    under the target loses its bytes. `restore` is not: a file the person deleted separately
-    //    last week keeps its own `deletedAt`, stays in the trash after the folder comes back, and
-    //    its row must stay deleted with it. Restoring that row would cancel its own thirty-day
-    //    sweep, go on costing storage, and leave the list saying "trashed" while the server says
-    //    "live" — after which `rm` refuses to put it back and the tool has no way out.
-    const at = Date.now();
-    const ids = targets.map((t) => t.entry.id);
-    const preview = buildIndex(applyIntent(entries, intentFor(verb, ids, at)));
-    const under = uniqueById(targets.flatMap((t) => filesUnder(entries, t.entry.id)));
-    // ⚠ Judged on the PREVIEW's own row, not on the one in hand: `applyIntent` returns new objects,
-    //   so asking the preview about the old object reads the old `deletedAt` and answers "still
-    //   trashed" for the very thing being restored.
-    const files = verb === "rm"
-        ? under
-        : under.filter((f) => {
-            const after = preview.byId.get(f.id);
-            return after !== undefined && isLive(preview, after);
-        });
-    let done = 0;
-    try {
-        for (const file of files) {
-            await tellServer(session.server, session.apiKey, verb, file.id);
-            done += 1;
-        }
-    }
-    catch (error) {
-        // ⛔ A HALF-FINISHED RUN MUST NAME ITSELF. Without this the agent sees six words of stderr and
-        //    the tool's own guidance ("a refusal is not a transient error, do not retry in a loop")
-        //    steers it away from the one thing that fixes this — running the same command again.
-        const because = error instanceof Error ? error.message : "the server refused";
-        throw new NmtsError(because, {
-            exitCode: 1,
-            nextStep: `${done} of ${files.length} file rows were moved before this stopped, and the file list was ` +
-                `not written. Running \`nmts ${verb}\` on the same paths again finishes the job — nothing is lost.`,
-        });
-    }
-    // ⛔ THE IDS ARE DECIDED AGAIN ON EVERY ATTEMPT, and this is not ceremony. Between the read
-    //    above and the write below another device can put one of these targets in the trash — by
-    //    trashing it, or by moving it under a folder that already is. Re-applying the intent we
-    //    built earlier would then stamp `deletedAt` on something that is ALREADY in the trash by
-    //    inheritance, giving it a clock of its own and quietly detaching it from the folder it came
-    //    with: restoring that folder afterwards would leave it behind. An id that has left the list
-    //    entirely is dropped for the reason `manifest-ops.ts` gives — the other device removing it
-    //    is newer information than our edit, and putting it back would undo a deletion somebody
-    //    made on purpose.
-    const result = await applyManyToList(session, (now) => {
-        const nowIndex = buildIndex(now);
-        const still = ids.filter((id) => {
-            const live = nowIndex.byId.get(id);
-            if (live === undefined)
-                return false;
-            return verb === "rm" ? isLive(nowIndex, live) : live.deletedAt !== undefined;
-        });
-        return still.length === 0 ? [] : [intentFor(verb, still, at)];
-    });
-    const shown = targets.map((t) => t.path);
+    // ⛔ WITHOUT `strict`. A person gets a line saying what was already out of the trash and keeps
+    //    the rest of their run; a program gets a refusal, because it cannot read the line. The
+    //    difference is spelled once, where the option is declared.
+    const outcome = await trashPaths(session, verb, paths);
+    // ⚠ The outcome's own field order IS this output. Nothing is assembled here, so the two can
+    //   never drift into saying different things about the same run.
     if (options.json) {
-        say(JSON.stringify({
-            paths: shown,
-            ids,
-            files: files.length,
-            // Named, and nothing was written for them: already out of the trash, or already covered
-            // by a folder in the same run.
-            skipped,
-            changed: result.changed,
-            // ⚠ The one signal that another writer intervened. It was printed in prose and left out of
-            //   the JSON, which is the half an agent is told to read (2026-08-23).
-            reappliedAfterConflict: result.reappliedAfterConflict,
-            seq: result.seq,
-        }));
+        say(JSON.stringify(outcome));
         return 0;
     }
-    const moved = files.length === 1 ? "1 file" : `${files.length} files`;
-    const names = shown.map((s) => `"${s}"`).join(", ");
+    if (outcome.paths.length === 0)
+        return nothingToDo(say, verb, outcome.skipped);
+    const moved = outcome.files === 1 ? "1 file" : `${outcome.files} files`;
+    const names = outcome.paths.map((s) => `"${s}"`).join(", ");
     say(verb === "rm"
-        ? `Moved ${names} to the trash (${moved}). ${shown.length === 1 ? "It" : "They"} can be restored for 30 days.`
+        ? `Moved ${names} to the trash (${moved}). ${outcome.paths.length === 1 ? "It" : "They"} can be restored for 30 days.`
         : `Restored ${names} (${moved}).`);
-    if (skipped.length > 0)
-        say(`  ${skippedLine(verb, skipped)}`);
-    if (result.reappliedAfterConflict) {
+    if (outcome.skipped.length > 0)
+        say(`  ${skippedLine(verb, outcome.skipped)}`);
+    if (outcome.reappliedAfterConflict) {
         say(`  Another device wrote the file list first, so this was applied to that version.`);
     }
     return 0;
 }
-/** The one intent either verb writes. Built in two places, so it is spelled in one. */
-function intentFor(verb, ids, at) {
-    return verb === "rm" ? { op: "trash", ids, at } : { op: "restore", ids, at };
-}
 /** What was named but not acted on, in the words that say why. */
 function skippedLine(verb, skipped) {
     const names = skipped.map((s) => `"${s}"`).join(", ");
@@ -204,85 +73,16 @@ function skippedLine(verb, skipped) {
         : `${names} was not in the trash.`;
 }
 /**
- * The run had nothing to do. Says so in whichever form the caller asked for.
+ * The run had nothing to do.
  *
  * ⚠ In practice this is the `restore` case — everything named was already out of the trash.
  *   `rm` reaches it only if every path it resolved was inside another path it resolved, which
  *   cannot happen while the outermost one is always kept.
  */
-function nothingToDo(say, options, verb, skipped, seq) {
-    if (options.json) {
-        say(JSON.stringify({ paths: [], ids: [], files: 0, skipped, changed: false, reappliedAfterConflict: false, seq }));
-        return 0;
-    }
+function nothingToDo(say, verb, skipped) {
     const names = skipped.map((s) => `"${s}"`).join(", ");
     say(verb === "restore"
         ? `${names} ${skipped.length === 1 ? "is" : "are"} not in the trash. Nothing changed.`
         : `Nothing was left to move to the trash. Nothing changed.`);
     return 0;
 }
-/** Is any ancestor of this entry in the set? Used to drop a target a named folder already covers. */
-function hasNamedAncestor(entries, entry, named) {
-    const byId = buildIndex(entries).byId;
-    const seen = new Set([entry.id]);
-    let at = entry.parentId;
-    while (at !== null && !seen.has(at)) {
-        if (named.has(at))
-            return true;
-        seen.add(at);
-        at = byId.get(at)?.parentId ?? null;
-    }
-    return false;
-}
-/** One entry per id, keeping the first. Two named folders can hold the same file only once. */
-function uniqueById(files) {
-    const byId = new Map();
-    for (const file of files)
-        if (!byId.has(file.id))
-            byId.set(file.id, file);
-    return [...byId.values()];
-}
-/**
- * Every file at or under one entry.
- *
- * ⚠ Trashed descendants are INCLUDED HERE, and the CALLER filters. Somebody who trashed one file
- *   last week and then trashes its folder expects the folder to be gone from the server too — so
- *   `rm` takes this set whole. `restore` cannot: see the note at the call site.
- */
-export function filesUnder(entries, rootId) {
-    const root = entries.find((e) => e.id === rootId);
-    if (root === undefined)
-        return [];
-    if (root.kind === KIND_FILE)
-        return [root];
-    const childrenOf = new Map();
-    for (const e of entries) {
-        const list = childrenOf.get(e.parentId);
-        if (list === undefined)
-            childrenOf.set(e.parentId, [e]);
-        else
-            list.push(e);
-    }
-    const out = [];
-    const seen = new Set([rootId]);
-    const queue = [rootId];
-    while (queue.length > 0) {
-        const id = queue.pop();
-        if (id === undefined)
-            break;
-        for (const child of childrenOf.get(id) ?? []) {
-            if (seen.has(child.id))
-                continue;
-            seen.add(child.id);
-            if (child.kind === KIND_FILE)
-                out.push(child);
-            else
-                queue.push(child.id);
-        }
-    }
-    return out;
-}
-/** ⛔ 404 is "already in the state you asked for", which is what a half-finished run leaves. */
-async function tellServer(base, apiKey, verb, id) {
-    await setTrashed(base, apiKey, id, verb === "rm");
-}

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>;