@needmoretruth/nmts-cli 0.38.0 → 0.39.0

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

package/dist/drive-edit/trash.js

@@ -0,0 +1,190 @@
+// The two halves of the trash: moving things into it, and bringing them back.
+import { buildIndex, fullPathOf, isLive, normaliseName } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { setTrashed } from "../item-trash.js";
+import { readFileList } from "../manifest.js";
+import { applyManyToList, batchTargets } from "../manifest-write.js";
+import { applyIntent } from "../shared/lib/drive/manifest-ops.js";
+import { DriveEditError, resolving } from "./errors.js";
+import { filesUnder, hasNamedAncestor, uniqueById } from "./tree.js";
+/**
+ * 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 async function trashPaths(input, verb, paths, options = {}) {
+    const list = await readFileList(input.server, input.apiKey, input.code, input.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.
+    const index = buildIndex(entries);
+    const found = resolving(() => 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. Named, and left alone — unless the caller is a
+            // program, which cannot read a line about it.
+            if (options.strict === true) {
+                throw new DriveEditError("NOT_IN_TRASH", `"${at}" is not in the trash.`, {
+                    exitCode: 4,
+                    nextStep: "Nothing changed. Only something in the trash can be restored.",
+                });
+            }
+            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 DriveEditError("NOT_IN_TRASH", `"${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 { paths: [], ids: [], files: 0, skipped, changed: false, reappliedAfterConflict: false, seq: 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 there is 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 setTrashed(input.server, input.apiKey, file.id, verb === "rm");
+            done += 1;
+        }
+    }
+    catch (error) {
+        // ⛔ A HALF-FINISHED RUN MUST NAME ITSELF. Without this an 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 writing = applyManyToList(input, (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;
+        });
+        if (verb === "restore" && options.strict === true)
+            refuseTakenNames(now, nowIndex.byId, still);
+        return still.length === 0 ? [] : [intentFor(verb, still, at)];
+    });
+    // ⛔ A STRICT RESTORE REFUSED HERE HAS ALREADY MOVED ITS ROWS. The name was free when the trash
+    //    was read and taken by the time the list was written, so the rows above are live while the
+    //    list still says trashed — the state the note on `files` calls no way out. Put the rows back
+    //    before the refusal leaves. If putting them back fails too, the refusal still leaves as it
+    //    is: restoring again after the rename moves the same rows and writes the list.
+    const result = await writing.catch(async (error) => {
+        if (verb === "restore" && error instanceof DriveEditError && error.code === "NAME_TAKEN") {
+            for (const file of files) {
+                await setTrashed(input.server, input.apiKey, file.id, true).catch(() => undefined);
+            }
+        }
+        throw error;
+    });
+    return {
+        paths: targets.map((t) => t.path),
+        ids,
+        files: files.length,
+        skipped,
+        changed: result.changed,
+        reappliedAfterConflict: result.reappliedAfterConflict,
+        seq: result.seq,
+    };
+}
+/**
+ * Refuse a restore that would land beside a live thing of the same name.
+ *
+ * ⛔ DECIDED INSIDE THE ATTEMPT like every other guard here: the name that was free when the trash
+ *    was read can be taken by the time the list is written, and two entries at one path is a state
+ *    no lookup can get out of.
+ */
+function refuseTakenNames(entries, byId, ids) {
+    const index = buildIndex(entries);
+    for (const id of ids) {
+        const entry = byId.get(id);
+        if (entry === undefined)
+            continue;
+        const holder = entries.find((e) => e.id !== id && e.parentId === entry.parentId && normaliseName(e.name) === normaliseName(entry.name) && isLive(index, e));
+        if (holder === undefined)
+            continue;
+        throw new DriveEditError("NAME_TAKEN", `Something called "${entry.name}" is already in that folder.`, {
+            exitCode: 4,
+            nextStep: "The file list was not changed. Rename the one that is there, then restore again.",
+        });
+    }
+}
+/** The one intent either half of the trash 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 };
+}

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

@@ -0,0 +1,15 @@
+import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
+/** Is `id` at or under `rootId`? Used to refuse moving a folder into its own subtree. */
+export declare function isUnder(entries: readonly ManifestEntry[], id: string | null, rootId: string): boolean;
+/** Is any ancestor of this entry in the set? Used to drop a target a named folder already covers. */
+export declare function hasNamedAncestor(entries: readonly ManifestEntry[], entry: ManifestEntry, named: ReadonlySet<string>): boolean;
+/** One entry per id, keeping the first. Two named folders can hold the same file only once. */
+export declare function uniqueById(files: readonly ManifestEntry[]): ManifestEntry[];
+/**
+ * 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/drive-edit/tree.js

@@ -0,0 +1,77 @@
+// Walking the list: the three questions the edits below ask about where an entry sits, and the one
+// that gathers the files a folder carries.
+import { buildIndex, KIND_FILE } from "../drive-paths.js";
+/** Is `id` at or under `rootId`? Used to refuse moving a folder into its own subtree. */
+export function isUnder(entries, id, rootId) {
+    const byId = buildIndex(entries).byId;
+    const seen = new Set();
+    let at = id;
+    while (at !== null && !seen.has(at)) {
+        if (at === rootId)
+            return true;
+        seen.add(at);
+        at = byId.get(at)?.parentId ?? null;
+    }
+    return false;
+}
+/** Is any ancestor of this entry in the set? Used to drop a target a named folder already covers. */
+export 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. */
+export 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;
+}

package/dist/drive-edit.d.ts

@@ -1,189 +1,9 @@
-import { NmtsError } from "./errors.ts";
-import { type ListEditInput } from "./manifest-write.ts";
-import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.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;
-    });
-}
-/**
- * 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;
-/**
- * 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>;
-/** 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>;
-/**
- * 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>;
-/**
- * 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[];
+export { DriveEditError, requireNewName } from "./drive-edit/errors.ts";
+export type { DriveEditCode } from "./drive-edit/errors.ts";
+export { ensureFolderPath, makeFolder } from "./drive-edit/folders.ts";
+export type { MadeFolder } from "./drive-edit/folders.ts";
+export { moveEntries, renameEntry } from "./drive-edit/move.ts";
+export type { MoveOutcome, MovedThing, RenameOutcome } from "./drive-edit/move.ts";
+export { trashPaths } from "./drive-edit/trash.ts";
+export type { TrashEditOptions, TrashOutcome } from "./drive-edit/trash.ts";
+export { filesUnder } from "./drive-edit/tree.ts";