@needmoretruth/nmts-cli 0.17.2

package/dist/commands/organise.js

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

package/dist/commands/public-code.js

@@ -0,0 +1,89 @@
+// `nmts public-code` — the value other accounts send files to, and publishing it so they can.
+//
+// ⛔ IT IS CALLED THE PUBLIC CODE HERE BECAUSE THAT IS WHAT THE PRODUCT CALLS IT. The browser's
+//    screens say "public code", and this program used to say "address" for the same value — two
+//    names for one thing, which is the mistake a locked wording decision exists to stop. It also
+//    printed it in a different encoding than the browser shows, so somebody copying from one and
+//    pasting into the other had two ways to be wrong about one value. Both are fixed here: one
+//    name, and the same grouped form a person sees on the screen.
+//
+// ⛔ WHY PUBLISHING IS A SEPARATE STEP AND NOT SOMETHING THIS COMMAND JUST DOES. Sending a file
+//    already publishes the sender's code as a side effect, because a share cannot exist without
+//    one and the person has already decided to hand something over. RECEIVING is the other way
+//    round: nothing has been decided yet, and the record is permanent. So the plain command reads,
+//    says whether it can be sent to, and names the flag; `--publish` is the deliberate act.
+//
+// ⛔ WHAT "PERMANENT" DOES AND DOES NOT MEAN HERE. The record cannot be withdrawn or replaced. It
+//    is also not a choice: the code and the identity behind it are derived from the account code,
+//    so the same account code produces the same bytes on any device, and the server refuses a
+//    bundle whose claimed value is not the fingerprint of its own root. The only way to publish a
+//    wrong one is to be holding a different account code. That is worth saying plainly rather than
+//    warning vaguely — a warning that cannot be acted on just teaches people to click through.
+//
+// ⚠ IT IS NOT THE ACCOUNT CODE. That one opens every file in the account and must never be given
+//   to anybody; this one is meant to be given away, and on its own it opens nothing.
+import { request } from "../api.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { loadCrypto } from "../crypto.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { shareKeysOf } from "../share.js";
+function b64(bytes) {
+    return Buffer.from(bytes).toString("base64url");
+}
+export async function publicCode(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const session = await openSession({ server: options.server, network: options.network });
+    const crypt = await loadCrypto();
+    const keys = shareKeysOf(crypt, session.code);
+    const mine = b64(keys.address);
+    const shown = keys.display;
+    const seen = await request(session.server, "/v1/account/share-identity", {
+        token: session.apiKey,
+    });
+    let published = isRecord(seen) && seen["published"] === true;
+    // ⛔ IF THE SERVER ALREADY HOLDS A DIFFERENT ONE, STOP. Publishing is first-writer-wins and the
+    //    server would refuse the write anyway, but the useful thing to report is not "the write
+    //    failed" — it is that the account code this machine is holding is not the one this account
+    //    was made with, which is a much bigger fact than a failed request.
+    const held = isRecord(seen) ? seen["share_address"] : null;
+    if (typeof held === "string" && held !== mine) {
+        throw new NmtsError("This account already publishes a different public code.", {
+            exitCode: 4,
+            nextStep: "The public code is derived from the account code, so a different one means this machine " +
+                "is holding a different account's code than the key beside it. Check which account you meant.",
+        });
+    }
+    if (options.publish === true && !published) {
+        await request(session.server, "/v1/account/share-identity", {
+            token: session.apiKey,
+            method: "PUT",
+            body: { share_public_key: b64(keys.identity), share_address: mine },
+        });
+        published = true;
+    }
+    if (options.json === true) {
+        // ⚠ BOTH FORMS. `code` is what a person reads and types; `raw` is what the wire carries.
+        //   A reader that has only one of them ends up converting, and that is a second place to be wrong.
+        say(JSON.stringify({ code: shown, raw: mine, published }));
+        return 0;
+    }
+    say(`public code  ${shown}`);
+    if (published) {
+        say(`             published — another account can send files to it`);
+        say(``);
+        say(`Give it to whoever is sending. ⛔ It is NOT your account code — that one opens`);
+        say(`every file you have and is never given to anybody. This one opens nothing.`);
+        return 0;
+    }
+    say(`             NOT published — nobody can send to it yet`);
+    say(``);
+    say(`Publishing writes it on the server so a sender can find the key to seal to.`);
+    say(`It is permanent: it cannot be withdrawn or changed afterwards. It is also not a`);
+    say(`choice — it comes from your account code, so the same account code always gives`);
+    say(`the same public code, on this machine or any other.`);
+    say(``);
+    say(`  ${BINARY_NAME} public-code --publish`);
+    return 0;
+}

package/dist/commands/pull.js

@@ -0,0 +1,185 @@
+// `nmts pull <folder>` — a whole folder, or a whole account, onto this machine.
+//
+// ⛔ ONE BAD FILE MUST NOT LOSE NINETEEN GOOD ONES. A single `get` refuses rather than writing a
+//    half-right file, and that is right for one file. Applied to two hundred it would mean one
+//    unreadable file throws away every file downloaded before it. So each file is attempted on its
+//    own, what failed is named at the end, and the exit code says whether anything did.
+//
+// ⛔ AND A FILE THAT FAILED LEAVES NOTHING — not even the part of it that had already arrived. Each
+//    file streams into a temporary name beside where it is going and is renamed into place only
+//    once its digest matches, so a pull that stops half way through a large file does not leave
+//    something that looks finished. A second run fetches what is missing (`download-sink.ts`).
+//
+// ⛔ AND NOTHING IS OVERWRITTEN BY DEFAULT. A pull into a directory that already holds files is
+//    ordinary — a second run, a resumed transfer — and silently replacing what is there is the one
+//    outcome nobody can undo. An existing file is SKIPPED and counted; `--force` replaces.
+//
+// ⛔ THE TREE IS THE ACCOUNT'S, AND IT IS BUILT UNDER THE DESTINATION AND NOWHERE ELSE. A name in
+//    the sealed list is written by whoever holds the account, so it is not to be trusted with a
+//    path: a name containing a separator, or dots that climb, would otherwise write outside the
+//    directory that was asked for. Every segment is checked before anything is created.
+import { mkdirSync, existsSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fetchFile } from "../download.js";
+import { fileSink } from "../download-sink.js";
+import { buildIndex, entryAt, fullPathOf, isLive, KIND_FILE, KIND_FOLDER, normalisePath, underPrefix, } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { readFileList } from "../manifest.js";
+import { resolveNetwork } from "../network.js";
+import { refuseUnwritableName } from "../safe-path.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+export async function pull(target, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const session = await openSession({ server: options.server, network: options.network });
+    const chain = resolveNetwork(session.server, session.network);
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (list.manifest === null) {
+        throw new NmtsError("This account has no file list, so there is nothing to pull.", { exitCode: 4 });
+    }
+    const entries = list.manifest.entries;
+    const index = buildIndex(entries);
+    // ⚠ No target means the WHOLE account. It is the same walk from the root, said as its own case
+    //   so that `nmts pull` cannot be read as "pull something and I will guess what".
+    const root = target === undefined || target === "" || target === "/" ? null : entryAt(entries, normalisePath(target), { nothingHappened: "Nothing was written." });
+    if (root !== null && root.kind !== KIND_FOLDER) {
+        throw new NmtsError(`"${fullPathOf(index, root)}" is a file.`, {
+            exitCode: 4,
+            nextStep: `Nothing was written. \`${BINARY_NAME} get\` fetches one file.`,
+        });
+    }
+    const base = resolve(options.out ?? ".");
+    const wanted = filesUnder(index, entries, root?.id ?? null);
+    if (wanted.length === 0) {
+        if (options.json) {
+            say(JSON.stringify({ files: 0, written: 0, skipped: 0, failed: 0, out: base }));
+            return 0;
+        }
+        say(`Nothing to pull${root === null ? "" : ` from "${fullPathOf(index, root)}"`}.`);
+        return 0;
+    }
+    const prefix = root === null ? "" : fullPathOf(index, root);
+    const outcomes = [];
+    for (const entry of wanted) {
+        const drivePath = fullPathOf(index, entry);
+        const local = safeJoin(base, underPrefix(prefix, drivePath));
+        if (existsSync(local) && options.force !== true) {
+            outcomes.push({ path: drivePath, bytes: entry.size, state: "skipped" });
+            continue;
+        }
+        if (!options.json)
+            say(`  ${drivePath}`);
+        try {
+            if (entry.dekWrapped === undefined)
+                throw new NmtsError("the file list holds no key for it");
+            // ⛔ THE DIRECTORY IS MADE BEFORE THE DOWNLOAD, because the file is now written as it is
+            //    decrypted: its temporary name lives beside the destination, so the destination's
+            //    directory has to exist before the first byte arrives rather than after the last.
+            mkdirSync(join(local, ".."), { recursive: true });
+            const fetched = await fetchFile({
+                base: session.server,
+                apiKey: session.apiKey,
+                accountCode: session.code,
+                itemId: entry.id,
+                size: entry.size,
+                dekWrapped: entry.dekWrapped,
+                ...(entry.contentHashCt === undefined ? {} : { contentHashCt: entry.contentHashCt }),
+                chain,
+                sink: fileSink(local, { force: options.force === true }),
+            });
+            outcomes.push({ path: drivePath, bytes: fetched.byteCount, state: "written" });
+        }
+        catch (error) {
+            // ⛔ COUNTED AND CARRIED ON. See the module note: refusing the whole pull over one file is
+            //    what makes somebody run it twenty times and lose the same nineteen files each time.
+            outcomes.push({
+                path: drivePath,
+                bytes: entry.size,
+                state: "failed",
+                why: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const written = outcomes.filter((o) => o.state === "written");
+    const skipped = outcomes.filter((o) => o.state === "skipped");
+    const failed = outcomes.filter((o) => o.state === "failed");
+    if (options.json) {
+        say(JSON.stringify({ files: outcomes.length, written: written.length, skipped: skipped.length, failed: failed.map((f) => ({ path: f.path, why: f.why })), out: base }));
+        return failed.length === 0 ? 0 : 1;
+    }
+    say(``);
+    say(`${written.length} written · ${skipped.length} already there · ${failed.length} failed`);
+    if (skipped.length > 0) {
+        say(``);
+        say(`  What was already there was left alone. --force replaces it, which cannot be undone.`);
+    }
+    if (failed.length > 0) {
+        say(``);
+        for (const one of failed)
+            say(`  ${one.path}: ${one.why ?? "failed"}`);
+        say(``);
+        say(`  Everything else was written. Running this again retries only what is missing.`);
+        return 1;
+    }
+    return 0;
+}
+/** Every live file at or under `parentId`, in path order. */
+function filesUnder(index, entries, parentId) {
+    const under = (entry) => {
+        if (parentId === null)
+            return true;
+        let at = entry;
+        const seen = new Set();
+        while (at !== undefined) {
+            if (at.parentId === parentId)
+                return true;
+            if (at.parentId === null || seen.has(at.parentId))
+                return false;
+            seen.add(at.parentId);
+            at = index.byId.get(at.parentId);
+        }
+        return false;
+    };
+    return entries
+        .filter((e) => e.kind === KIND_FILE && isLive(index, e) && under(e))
+        .sort((a, b) => fullPathOf(index, a).localeCompare(fullPathOf(index, b)));
+}
+/**
+ * Join a drive path onto a local directory, refusing anything that would leave it.
+ *
+ * ⛔ THE NAMES COME FROM THE SEALED LIST, which is written by whoever holds the account — including
+ *    an account somebody else set up. A name with a separator in it, or one made of dots, would
+ *    otherwise write outside the directory that was asked for, which is a file appearing somewhere
+ *    nobody chose.
+ */
+/**
+ * Where one drive path lands under `base`, or a refusal.
+ *
+ * ⚠ `platform` exists so the Windows branch can be exercised from any machine. Without it the
+ *   ordering below is only ever checked by the Windows runner, and it was wrong there for one
+ *   release.
+ */
+export function safeJoin(base, drivePath, platform = process.platform) {
+    const segments = drivePath.split("/").filter((s) => s !== "");
+    for (const segment of segments) {
+        // ⛔ THE ORDER OF THESE TWO IS LOAD-BEARING. A segment that climbs — `..` — also ends in a dot,
+        //    which is one of the shapes Windows will not keep, so putting the platform check first made
+        //    a path-traversal attempt report itself as a naming problem, and only on Windows. The
+        //    reason a refusal gives has to be the same reason on every machine.
+        if (segment === "." || segment === ".." || segment.includes(sep) || isAbsolute(segment)) {
+            throw new NmtsError(`"${drivePath}" cannot be written to a path on this machine.`, {
+                exitCode: 4,
+                nextStep: "Nothing was written. Rename it in the drive, then pull again.",
+            });
+        }
+        // A name this machine cannot hold is refused BEFORE anything is fetched — on Windows some of
+        // them are accepted by the operating system and then keep nothing (see `safe-path.ts`).
+        refuseUnwritableName(segment, platform);
+    }
+    const full = resolve(base, ...segments);
+    const inside = relative(base, full);
+    if (inside.startsWith("..") || isAbsolute(inside)) {
+        throw new NmtsError(`"${drivePath}" would be written outside the destination.`, { exitCode: 4 });
+    }
+    return full;
+}