@needmoretruth/nmts-cli 0.17.2

package/dist/commands/push.js

@@ -0,0 +1,278 @@
+// `nmts push <directory>` — a whole directory, with its shape, paid for with credits.
+//
+// ⛔ IT STOPS AT THE FIRST FAILURE, and that is the opposite of what `pull` does. Pulling costs
+//    nothing, so carrying on past one bad file saves the nineteen good ones. Pushing SPENDS: a
+//    failure that is really "this account cannot pay any more" would, if carried past, keep asking
+//    to pay for every remaining file. So the run stops, says what is already uploaded — those
+//    files are real and paid for — and says that running it again does the rest.
+//
+// ⛔ AND IT SKIPS WHAT IS ALREADY THERE, which is what makes running it again safe. Without that,
+//    a second run would upload every file a second time and the drive would fill with numbered
+//    copies: this tool never replaces a file, so the second `notes.txt` becomes `notes (2).txt`
+//    and the account pays for both.
+//
+// ⛔ NOTHING HIDDEN IS SENT. Entries whose name begins with a dot are left alone unless they are
+//    asked for: a directory of source code carries credentials in exactly those files, and an
+//    upload goes to a public storage network. `--hidden` includes them.
+import { readdirSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { requireConsent } from "../consent.js";
+import { DERIVED, loadCrypto } from "../crypto.js";
+import { normaliseName, normalisePath } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { addEntry } from "../manifest-write.js";
+import { parseAsked } from "../collision.js";
+import { setTrashed } from "../item-trash.js";
+import { readFileList } from "../manifest.js";
+import { BINARY_NAME } from "../product.js";
+import { Progress, silentSink, stderrSink } from "../progress.js";
+import { openSession } from "../session.js";
+import { fileSource, partKeysOf, uploadFile } from "../upload-file.js";
+import { createUploadApi } from "../upload-api.js";
+import { clearItemRecord, clearReservation } from "../upload-store.js";
+import { CREDIT_BYTES, partSizeFor, planAndPrice, UPLOAD_EPOCHS } from "../upload-price.js";
+import { createBlobProtocol, readCurrentEpoch } from "../walrus-write.js";
+import { ensureFolderPath } from "./organise.js";
+export async function push(target, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (target === undefined || target === "") {
+        throw new NmtsError("Say which directory to push.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} push <directory>\` — a directory on this machine.`,
+        });
+    }
+    const root = resolve(target);
+    let rootStat;
+    try {
+        rootStat = statSync(root);
+    }
+    catch {
+        throw new NmtsError(`There is nothing at ${root}.`, { exitCode: 4 });
+    }
+    if (!rootStat.isDirectory()) {
+        throw new NmtsError(`${root} is a file.`, {
+            exitCode: 4,
+            nextStep: `Nothing was sent. \`${BINARY_NAME} put\` uploads one file.`,
+        });
+    }
+    const under = normalisePath(options.to ?? "");
+    const base = under === "" ? basename(root) : `${under}/${basename(root)}`;
+    const found = walk(root, base, options.hidden === true);
+    if (found.length === 0) {
+        if (options.json) {
+            say(JSON.stringify({ files: 0, uploaded: 0, skipped: 0, credits: 0 }));
+            return 0;
+        }
+        say(`${root} holds no files to send.`);
+        return 0;
+    }
+    const session = await openSession({ server: options.server, network: options.network });
+    const partSize = partSizeFor(options.partSize);
+    // ⛔ READ BEFORE ANYTHING IS SEALED OR PAID FOR — a typo must not surface after the money.
+    const asked = parseAsked(options.onCollision);
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    const rule = list.manifest?.settings?.paddingMode === "pow2" ? "pow2" : "padme";
+    // ⛔ WHAT IS ALREADY THERE IS DECIDED BEFORE ANYTHING IS PRICED, so the number printed is what
+    //    this run will actually spend rather than what a first run would have.
+    const entries = list.manifest?.entries ?? [];
+    const taken = new Set(entries
+        .filter((e) => e.deletedAt === undefined)
+        .map((e) => `${e.parentId ?? ""} ${normaliseName(e.name)}`));
+    const folderIds = new Map();
+    const already = [];
+    const todo = [];
+    for (const one of found) {
+        const parentId = knownFolderId(entries, one.folder);
+        if (parentId !== undefined)
+            folderIds.set(one.folder, parentId);
+        const there = parentId !== undefined && taken.has(`${parentId ?? ""} ${normaliseName(one.name)}`);
+        (there ? already : todo).push(one);
+    }
+    const credits = todo.reduce((sum, one) => sum + planAndPrice(one.size, partSize, rule).credits, 0);
+    const bytes = todo.reduce((sum, one) => sum + one.size, 0);
+    if (options.dryRun === true) {
+        if (options.json) {
+            say(JSON.stringify({
+                files: found.length,
+                toSend: todo.length,
+                skipped: already.length,
+                bytes,
+                credits,
+                epochs: UPLOAD_EPOCHS,
+            }));
+            return 0;
+        }
+        say(`${todo.length} file${todo.length === 1 ? "" : "s"}  ${bytes} bytes  →  ${credits} credit${credits === 1 ? "" : "s"}`);
+        if (already.length > 0) {
+            say(`  ${already.length} already in the drive, which this would not send again`);
+        }
+        say(``);
+        say(`  Nothing was sent and nothing was charged.`);
+        return 0;
+    }
+    requireConsent("spend");
+    const progress = new Progress(options.json === true ? silentSink() : stderrSink(), "uploading");
+    const crypt = await loadCrypto();
+    // ⛔ READ ONCE, AND ONLY IF SOMETHING IS ACTUALLY SENT. It is a chain read: a run whose files are
+    //    all already in the drive should not need a storage network to be reachable to say so.
+    let epoch;
+    const currentEpoch = async () => {
+        if (epoch === undefined)
+            epoch = await readCurrentEpoch(session.network);
+        return epoch;
+    };
+    if (!options.json) {
+        say(`${todo.length} file${todo.length === 1 ? "" : "s"}  →  ${credits} credit${credits === 1 ? "" : "s"}`);
+        if (already.length > 0)
+            say(`  ${already.length} already there, not sent again`);
+    }
+    const uploaded = [];
+    try {
+        for (const one of todo) {
+            const parentId = await folderFor(session, folderIds, one.folder);
+            if (!options.json)
+                say(`  ${one.folder}/${one.name}`);
+            const send = options.send ??
+                (async (file, into) => sendOne(session, crypt, file, {
+                    ...(asked !== undefined ? { onCollision: asked } : {}),
+                    parentId: into,
+                    partSize,
+                    rule,
+                    currentEpoch: await currentEpoch(),
+                    progress,
+                }));
+            uploaded.push(`${one.folder}/${await send(one, parentId)}`);
+        }
+    }
+    catch (error) {
+        progress.done();
+        // ⛔ WHAT IS UPLOADED IS REAL AND PAID FOR. Saying so is the difference between somebody
+        //    running this again — which sends only the rest — and somebody assuming it all failed.
+        const because = error instanceof Error ? error.message : String(error);
+        throw new NmtsError(because, {
+            exitCode: 1,
+            nextStep: uploaded.length === 0
+                ? "Nothing was uploaded."
+                : `${uploaded.length} file${uploaded.length === 1 ? " is" : "s are"} uploaded and paid ` +
+                    `for. Running the same command again sends only what is missing.`,
+        });
+    }
+    finally {
+        progress.done();
+    }
+    if (options.json) {
+        say(JSON.stringify({ files: found.length, uploaded: uploaded.length, skipped: already.length, bytes, credits }));
+        return 0;
+    }
+    say(``);
+    say(`${uploaded.length} sent · ${already.length} already there`);
+    return 0;
+}
+/** Seal, buy, upload and record ONE file. The account's data key does not outlive it. */
+async function sendOne(session, crypt, one, ctx) {
+    const derived = crypt.kdf_derive(crypt.account_code_parse(session.code));
+    const dataKey = derived.slice(DERIVED.dataKey[0], DERIVED.dataKey[1]);
+    derived.fill(0);
+    const protocol = createBlobProtocol(session.network, one.size, (sent, total) => ctx.progress.update(sent, total));
+    try {
+        const result = await uploadFile({
+            api: createUploadApi(session.server, session.apiKey),
+            protocol,
+            crypt,
+            dataKey,
+            source: fileSource(one.local, one.size),
+            name: one.name,
+            parentId: ctx.parentId,
+            destination: one.folder,
+            relayUrl: protocol.relayUrl,
+            epochs: UPLOAD_EPOCHS,
+            currentEpoch: ctx.currentEpoch,
+            partSize: ctx.partSize,
+            padding: { rule: ctx.rule, unitBytes: CREDIT_BYTES },
+        });
+        const now = Date.now();
+        // ⛔ FROM THE RESULT, NOT FROM THIS RUN. The key that opens the stored bytes is the key they
+        //    were sealed with, which on a resume belongs to the run that sealed them.
+        const added = await addEntry({
+            server: session.server,
+            apiKey: session.apiKey,
+            code: session.code,
+            accountId: session.accountId,
+            ...(ctx.onCollision !== undefined ? { onCollision: ctx.onCollision } : {}),
+            entry: {
+                id: result.itemId,
+                parentId: ctx.parentId,
+                kind: 1,
+                name: result.entry.name,
+                size: result.entry.plaintextLen,
+                createdAt: now,
+                updatedAt: now,
+                dekWrapped: result.entry.dekWrapped,
+                contentHashCt: result.entry.contentHashCt,
+            },
+        });
+        // ⛔ ONLY NOW. Until the entry is in the list the file is paid for and invisible.
+        clearItemRecord(result.fileKey);
+        for (const record of partKeysOf(result.fileKey, result.parts))
+            clearReservation(record);
+        // The file this one displaced goes to the server's trash last — see the same note in `put.ts`.
+        if (added.replaced)
+            await setTrashed(session.server, session.apiKey, added.replaced.id, true);
+        return added.name;
+    }
+    finally {
+        dataKey.fill(0);
+    }
+}
+/** The folder id for a drive path, made if it is not there yet. Remembered for the next file. */
+async function folderFor(session, known, folder) {
+    const held = known.get(folder);
+    if (held !== undefined)
+        return held;
+    const { parentId } = await ensureFolderPath(session, folder);
+    known.set(folder, parentId);
+    return parentId;
+}
+/** The id of a drive folder path that ALREADY exists, or undefined when it does not. */
+function knownFolderId(entries, folder) {
+    if (folder === "")
+        return null;
+    let parentId = null;
+    for (const name of folder.split("/")) {
+        const there = entries.find((e) => e.parentId === parentId &&
+            e.kind === 0 &&
+            e.deletedAt === undefined &&
+            normaliseName(e.name) === normaliseName(name));
+        if (there === undefined)
+            return undefined;
+        parentId = there.id;
+    }
+    return parentId;
+}
+export { walk as filesUnderDirectory };
+/** Every file under a local directory, with the drive folder each one belongs in. */
+function walk(dir, driveFolder, hidden) {
+    const out = [];
+    const items = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const item of items) {
+        if (!hidden && item.name.startsWith("."))
+            continue;
+        const local = join(dir, item.name);
+        // ⛔ SYMBOLIC LINKS ARE NOT FOLLOWED. One pointing at a parent directory would walk forever,
+        //    and one pointing outside would upload a file nobody meant to send.
+        if (item.isSymbolicLink())
+            continue;
+        if (item.isDirectory()) {
+            out.push(...walk(local, `${driveFolder}/${item.name}`, hidden));
+            continue;
+        }
+        if (!item.isFile())
+            continue;
+        const size = statSync(local).size;
+        // An empty file has nothing to store, and the storage network would refuse the reservation.
+        if (size === 0)
+            continue;
+        out.push({ local, folder: driveFolder, name: item.name, size });
+    }
+    return out;
+}

package/dist/commands/put.js

@@ -0,0 +1,282 @@
+// `nmts put <file>` — one file in, sealed on this machine, paid for with credits.
+//
+// ⛔ THE ONLY COMMAND IN THIS TOOL THAT SPENDS. Everything about it is arranged so that is never a
+//   surprise: `--dry-run` says the price without paying it, the price is printed before the work
+//   starts, and a failure says whether the money already moved. The machinery that keeps a half
+//   finished upload from becoming money that bought nothing is in `upload.ts`.
+//
+// ⛔ THE PLAINTEXT NEVER LEAVES THIS PROCESS. What goes to the storage network is the sealed
+//   stream; what goes to the server is its length, and a name that is itself inside the account's
+//   sealed file list. Nothing in this file sends a file name anywhere but into that list.
+import { basename, resolve } from "node:path";
+import { identityOf } from "../account.js";
+import { requireAccountCode } from "../code-access.js";
+import { API_KEY_ENV_VAR, CODE_ENV_VAR, readCredentialsFile, resolveApiKey } from "../credentials.js";
+import { parseAsked } from "../collision.js";
+import { requireConsent } from "../consent.js";
+import { DERIVED, loadCrypto } from "../crypto.js";
+import { buildIndex, fullPathOf, isLive, KIND_FOLDER, normalisePath } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { Progress, silentSink, stderrSink } from "../progress.js";
+import { setTrashed } from "../item-trash.js";
+import { addEntry } from "../manifest-write.js";
+import { readFileList } from "../manifest.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { clearItemRecord, clearReservation } from "../upload-store.js";
+import { createUploadApi } from "../upload-api.js";
+import { fileSource, partKeysOf, uploadFile } from "../upload-file.js";
+import { CREDIT_BYTES, creditsFor, measureLocal, partSizeFor, planAndPrice, UPLOAD_EPOCHS, } from "../upload-price.js";
+import { createBlobProtocol, readCurrentEpoch } from "../walrus-write.js";
+/**
+ * The folder id `--to` names, or null for the root. Refuses rather than guessing.
+ *
+ * ⛔ IT IS THE SAME LOOKUP EVERY OTHER COMMAND USES. This had its own walk and its own
+ *    `e.deletedAt` test, which meant it would happily accept a folder whose PARENT was in the
+ *    trash and put a paid-for upload somewhere the drive does not show (2026-08-23).
+ */
+export function folderIdFor(wanted, entries) {
+    if (wanted === undefined)
+        return null;
+    const target = normalisePath(wanted);
+    if (target === "")
+        return null;
+    const index = buildIndex(entries);
+    const matches = entries.filter((e) => e.kind === KIND_FOLDER && isLive(index, e) && normalisePath(fullPathOf(index, e)) === target);
+    const folder = matches[0];
+    if (folder === undefined) {
+        throw new NmtsError(`No folder at "${target}".`, {
+            exitCode: 4,
+            nextStep: `Nothing was sent and nothing was charged. Make it first with ` +
+                `\`${BINARY_NAME} mkdir "${target}"\`, or leave --to off to put the file at the top of the drive.`,
+        });
+    }
+    if (matches.length > 1) {
+        throw new NmtsError(`"${target}" names ${matches.length} folders in this account.`, {
+            exitCode: 4,
+            nextStep: `Nothing was sent. Rename one of them with \`${BINARY_NAME} rename\`, then try again.`,
+        });
+    }
+    return folder.id;
+}
+export async function put(target, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (target === undefined || target === "") {
+        throw new NmtsError("Say which file to put.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} put <file>\` — a path on this machine.`,
+        });
+    }
+    const resolved = await requireAccountCode();
+    const key = resolveApiKey();
+    if (key === null) {
+        throw new NmtsError("This account has no API key on this machine, and the server needs one.", {
+            exitCode: 3,
+            nextStep: `Make a key on the account screen at nmts.me and put it in ${API_KEY_ENV_VAR}, or store ` +
+                `it with \`${BINARY_NAME} login\`.`,
+        });
+    }
+    const localPath = resolve(target);
+    const size = measureLocal(localPath);
+    const partSize = partSizeFor(options.partSize);
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const identity = await identityOf(resolved.code);
+    const crypt = await loadCrypto();
+    const [from, to] = DERIVED.dataKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(resolved.code));
+    const dataKey = derived.slice(from, to);
+    derived.fill(0);
+    const name = options.name ?? basename(localPath);
+    // The destination AS TYPED, so the reservation key can be worked out before any network call.
+    const destination = (options.to ?? "").replace(/^\.?\//, "").replace(/\/$/, "");
+    // ⛔ THE ACCOUNT'S OWN LIST IS READ BEFORE THE PRICE IS QUOTED, and that is why `--dry-run` needs
+    //    the network. The rounding rule that hides a file's true size lives in the sealed list, it
+    //    changes how many bytes are stored, and therefore it changes the price. A quote worked out
+    //    without it would be right for one account and wrong for the other, which is worse than
+    //    being slower.
+    // ⛔ READ BEFORE ANYTHING IS SEALED OR PAID FOR. A misspelt answer that surfaced after the upload
+    //    would have cost real money to produce a message about a typo.
+    const asked = parseAsked(options.onCollision);
+    const list = await readFileList(server, key.key, resolved.code, identity.accountId);
+    const rule = list.manifest?.settings?.paddingMode === "pow2" ? "pow2" : "padme";
+    // ⛔ THE PRICE IS ARITHMETIC, NOT A MEASUREMENT: quoting it by sealing would mean reading and
+    //    encrypting a very large file to answer `--dry-run`. Every part rounds up to a whole credit
+    //    on its own, exactly as the server charges each reservation, so a file in several parts is
+    //    quoted the way it will actually be billed.
+    //
+    // ⚠ ONLY THE LAST PART IS ROUNDED UP. The earlier ones are exactly the part size, which is what
+    //   lets a reader work out where the padding is.
+    const { plan, sealedBytes, credits } = planAndPrice(size, partSize, rule);
+    if (options.dryRun === true) {
+        // ⛔ Nothing above this line touched the network and nothing below it runs. The file was not
+        //    even read — the price is arithmetic on its size, and the server does the same arithmetic.
+        if (options.json) {
+            say(JSON.stringify({
+                dryRun: true,
+                name,
+                bytes: size,
+                sealedBytes,
+                parts: plan.length,
+                partSize,
+                credits,
+                epochs: UPLOAD_EPOCHS,
+            }));
+            return 0;
+        }
+        say(`${name}  ${size} bytes  →  ${credits} credit${credits === 1 ? "" : "s"}`);
+        if (plan.length > 1)
+            say(`  in ${plan.length} parts of up to ${partSize} bytes`);
+        say(``);
+        say(`  Nothing was sent and nothing was charged. Run the same command without --dry-run`);
+        say(`  to upload it.`);
+        return 0;
+    }
+    // ⛔ ASKED AFTER THE PRICE IS KNOWN AND BEFORE ANYTHING LEAVES. Working the price out is local
+    //    and free, so doing it first costs nothing and lets the refusal name a real number instead
+    //    of a warning about spending in general. `--dry-run` returns above this line and never asks.
+    requireConsent("spend");
+    // ⛔ Resolved from the list read above — which happened BEFORE the money moves, so a rolled-back
+    //    or forked list stops the upload rather than being discovered after it is paid for.
+    const parentId = folderIdFor(options.to, list.manifest?.entries ?? []);
+    // ⛔ `--json` promises one JSON document and nothing else, so it gets a reporter that says
+    //    nothing. Everything else reports to STDERR, where it cannot land in a redirected answer.
+    const progress = new Progress(options.json === true ? silentSink() : stderrSink(), "uploading");
+    const protocol = createBlobProtocol(network, sealedBytes, (sent, total) => progress.update(sent, total));
+    const currentEpoch = await readCurrentEpoch(network);
+    if (!options.json) {
+        say(`${name}  ${size} bytes  →  ${credits} credit${credits === 1 ? "" : "s"}`);
+        if (plan.length > 1) {
+            say(`  in ${plan.length} parts — each one is bought separately and can be finished later`);
+        }
+    }
+    const steps = [];
+    const onStep = (step) => {
+        steps.push(step.step);
+        if (options.json)
+            return;
+        if (step.step === "planning")
+            return;
+        if (step.step === "hashing") {
+            say(`  reading ${size} bytes`);
+            return;
+        }
+        // ⚠ Only said for a file that HAS several parts. On a one-part file the number is noise.
+        const where = step.parts > 1 ? `  [${step.partIndex + 1}/${step.parts}]` : "";
+        if (step.step === "sealing")
+            say(`  sealing${where} ${step.bytes} bytes`);
+        if (step.step === "resuming")
+            say(`  picking up reservation ${step.ledgerId} (${step.state})${where}`);
+        if (step.step === "encoding")
+            say(`  preparing${where} ${step.bytes} sealed bytes`);
+        if (step.step === "reserving")
+            say(`  buying storage${where}`);
+        if (step.step === "uploading")
+            say(`  uploading${where} ${step.bytes} bytes to ${step.relayUrl}`);
+        if (step.step === "certifying") {
+            // The live line is finished before anything else prints, or the next line lands on top of it.
+            progress.done();
+            say(`  certifying${where}`);
+        }
+        if (step.step === "committing")
+            say(`  saving to the drive`);
+    };
+    let result;
+    try {
+        result = await uploadFile({
+            api: createUploadApi(server, key.key),
+            protocol,
+            crypt,
+            dataKey,
+            source: fileSource(localPath, size),
+            name,
+            parentId,
+            destination,
+            relayUrl: protocol.relayUrl,
+            epochs: UPLOAD_EPOCHS,
+            currentEpoch,
+            partSize,
+            padding: { rule, unitBytes: CREDIT_BYTES },
+            onStep,
+        });
+    }
+    finally {
+        // ⛔ Also on the way out of a failure. A half-written progress line would otherwise sit in
+        //    front of the error message, which is the one line that must be readable.
+        progress.done();
+        dataKey.fill(0);
+    }
+    const now = Date.now();
+    // ⛔ FROM `result.entry`, NOT FROM THIS RUN. The key that opens the stored bytes is the key they
+    //    were sealed with, which on a resume belongs to the run that sealed them. Writing this run's
+    //    key would produce a file that is paid for, present, correctly named and impossible to open.
+    const added = await addEntry({
+        server,
+        apiKey: key.key,
+        code: resolved.code,
+        accountId: identity.accountId,
+        ...(asked !== undefined ? { onCollision: asked } : {}),
+        entry: {
+            id: result.itemId,
+            // ⚠ The FRESHLY resolved folder, not the record's. The reservation key already covers the
+            //   destination as typed, so both runs asked for the same path — and if that folder has
+            //   since been removed, resolving again is what says so instead of writing into a folder id
+            //   that no longer exists.
+            parentId,
+            kind: 1,
+            name: result.entry.name,
+            size: result.entry.plaintextLen,
+            createdAt: now,
+            updatedAt: now,
+            dekWrapped: result.entry.dekWrapped,
+            contentHashCt: result.entry.contentHashCt,
+        },
+    });
+    // ⛔ ONLY NOW, AND EVERY PART. Until the entry is in the list the file is paid for and invisible,
+    //    and the records are the only thing that lets a second run finish the job without spending
+    //    again. Clearing the file-level one first would leave a run able to commit a second time.
+    clearItemRecord(result.fileKey);
+    for (const record of partKeysOf(result.fileKey, result.parts))
+        clearReservation(record);
+    // ⛔ THE DISPLACED FILE IS TOLD TO THE SERVER ONLY NOW, and only after the new one is in the
+    //    list. Until this line the person still had the file they started with.
+    // ⚠ A failure here leaves it hidden in this account's trash while the server still counts it as
+    //   live. That is the harmless direction: it stays restorable, it still expires on its own, and
+    //   `nmts rm` on it again finishes the job. The other order — server first — would show a live
+    //   file the server has already trashed, which is the one state a person cannot act on.
+    if (added.replaced)
+        await setTrashed(server, key.key, added.replaced.id, true);
+    if (options.json) {
+        say(JSON.stringify({
+            id: result.itemId,
+            name: added.name,
+            bytes: size,
+            sealedBytes,
+            parts: plan.length,
+            credits: result.resumed ? 0 : credits,
+            resumed: result.resumed,
+            renamed: added.name !== name,
+            ...(added.replaced ? { replacedIntoTrash: added.replaced.id } : {}),
+            fileListVersion: added.seq,
+        }));
+        return 0;
+    }
+    say(`  saved as ${added.name}`);
+    if (added.replaced) {
+        say(``);
+        say(`  A file called ${name} was already there. It is in the trash now — ${BINARY_NAME} restore`);
+        say(`  brings it back for 30 days. This machine is set to overwrite: ${BINARY_NAME} on-collision`);
+    }
+    else if (added.name !== name) {
+        say(``);
+        say(`  A file called ${name} was already there, so this one was numbered rather than`);
+        say(`  replacing it. This machine is set to rename: ${BINARY_NAME} on-collision`);
+    }
+    if (result.resumed) {
+        say(``);
+        say(`  This finished an upload a previous run had already paid for. Nothing was charged now.`);
+    }
+    return 0;
+}