@needmoretruth/nmts-cli 0.17.2

package/dist/stdout.js

@@ -0,0 +1,109 @@
+// Handing a file's bytes to whatever is reading this program's stdout, instead of to the disk.
+//
+// ⛔ THIS EXISTS SO THAT READING A FILE DOES NOT MEAN LEAVING ONE. Everything else in this tool
+//    works to keep plaintext in as few places as possible, and until this was here an agent that
+//    wanted to read one stored note had to write that note to the disk first — a copy nobody asked
+//    for, in a directory nobody chose, that outlives the read.
+//
+// ⛔ A WHOLE FILE OR NOTHING — AND ON THIS PATH THAT STILL MEANS HOLDING IT. The disk path no
+//    longer does: a download is written as it is decrypted, under a temporary name, and renamed
+//    into place only once the whole-file digest matches, so it is bounded by one part rather than
+//    by the file. A pipe has no rename. A byte handed to a reader cannot be taken back, and a
+//    reader that has already consumed half a file cannot be told afterwards that the half was
+//    wrong — so bytes still reach this module only after `download.ts` has proved the file whole,
+//    which is why this takes a buffer and not a stream. The ceiling that comes with that, and the
+//    refusal above it, are in `download-sink.ts` (`stdoutSink`).
+//
+// ⛔ A TERMINAL IS NOT A PIPE, AND THIS TELLS THEM APART. See `readableOnATerminal`.
+import { NmtsError } from "./errors.js";
+/** What `--out` is spelled as when the file goes to stdout. The spelling every tool shares. */
+export const STDOUT_TARGET = "-";
+/**
+ * Whether these bytes can go to a terminal without the terminal acting on them.
+ *
+ * ⛔ A TERMINAL EXECUTES WHAT IT IS SENT. An escape sequence stored in a file can retitle the
+ *    window, blank the screen, change what the reader's next keystrokes mean, and on terminals
+ *    that answer queries it can put text of its choosing into their next command line. So the
+ *    question is not "will this look like rubbish" — it is "does this contain instructions", and
+ *    the answer decides whether the bytes are refused or written. A pipe is a different question
+ *    and gets a different answer: a program reading this is expected to handle whatever it asked
+ *    for, and refusing binary there would make the whole option useless.
+ *
+ * ⚠ Tab, newline and carriage return are the three control characters that mean in a terminal
+ *   exactly what they mean in a text file, so they pass.
+ *
+ * ⚠ Bytes that are not well-formed UTF-8 fail too, and not for tidiness: what a terminal does with
+ *   a broken sequence is its own business, and this is somebody else's terminal.
+ */
+export function readableOnATerminal(bytes) {
+    for (const byte of bytes) {
+        if (byte === 0x09 || byte === 0x0a || byte === 0x0d)
+            continue;
+        if (byte < 0x20 || byte === 0x7f)
+            return false;
+    }
+    try {
+        // Checked after the scan above, which is cheap and turns away most binary before this
+        // allocates a string the size of the file.
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/** This program's own stdout, as a destination. */
+export function processStdout() {
+    return {
+        isTerminal: process.stdout.isTTY === true,
+        write: (bytes) => new Promise((resolve, reject) => {
+            // ⛔ WAITED FOR, NOT FIRED AND FORGOTTEN. On a pipe Node's stdout is asynchronous: a
+            //    caller that returned as soon as `write` did could not tell a full disk from a
+            //    finished write, and would report success for bytes that never arrived.
+            process.stdout.write(bytes, (error) => {
+                if (error === undefined || error === null)
+                    resolve();
+                else
+                    reject(error);
+            });
+        }),
+    };
+}
+/**
+ * Hand the whole file over, refusing rather than writing bytes a terminal would act on.
+ *
+ * Answers false when the program reading it closed the pipe before the file was done — `nmts get
+ * big.bin --out - | head -c 100` is an ordinary thing to do, and the reader that stopped listening
+ * is the one that decided it had enough. Every other failure throws: a caller must not be able to
+ * mistake "the disk filled up half way" for "handed over".
+ */
+export async function handOver(bytes, to) {
+    if (to.isTerminal && !readableOnATerminal(bytes)) {
+        throw new NmtsError("These bytes are not text and stdout is a terminal.", {
+            exitCode: 4,
+            nextStep: "Nothing was written. A terminal acts on some of what it is sent, so this refuses rather " +
+                "than sending it. Redirect it (`--out - > file`), pipe it into something that reads " +
+                "bytes, or pass `--out <name>` to write the file instead.",
+        });
+    }
+    try {
+        await to.write(bytes);
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? Reflect.get(error, "code") : null;
+        if (code === "EPIPE")
+            return false;
+        // ⛔ Named, and never reported as success. Some of the file may already have gone; what is
+        //    certain is that the whole file did not, and the exit code has to say so.
+        //
+        // ⚠ The cause is safe to interpolate, and that is worth saying because `errors.ts` explains
+        //   how it usually is not: a stream's failure is its own errno line (`write ENOSPC`), which
+        //   never quotes the bytes it was handed.
+        throw new NmtsError(`The file could not be handed over: ${error instanceof Error ? error.message : String(error)}`, {
+            exitCode: 1,
+            nextStep: "Whatever was reading this did not get the whole file. If it was redirected, what is " +
+                "there now is part of one.",
+        });
+    }
+    return true;
+}

package/dist/trash-sweep.js

@@ -0,0 +1,123 @@
+// The thirty days, on the half of the trash this tool owns.
+//
+// ⛔ THE KEY THAT OPENS A FILE EXISTS TWICE, AND EACH SIDE SWEEPS ITS OWN COPY. One copy is the
+//    item row on the server; the other is `dekWrapped` inside the sealed file list, which the
+//    server cannot read and therefore cannot edit. Erasing one and leaving the other is not a
+//    deletion — it is a deletion somebody was told about while a working key stayed behind. So the
+//    server sweeps its rows on a timer, and a signed-in client drops the matching list entries.
+//
+// ⛔ THIS TOOL CANNOT DO THE SERVER'S HALF, and that is a deliberate line rather than a gap: the
+//    endpoint that erases for good refuses an API key outright, because a soft delete is
+//    recoverable and an erase is not. What is left for this side is to drop list entries for
+//    things the server has ALREADY let go of — which is why the sweep asks what the server still
+//    holds before it writes anything, and holds back what it finds.
+//
+// ⛔ AND IT DROPS WHOLE BRANCHES OR NOTHING. Trashing a folder marks the folder alone; everything
+//    under it is trash by inheritance and shares the folder's instant. Drop the folder while one
+//    file under it is held back and that file's parent chain breaks — after which nothing carries
+//    a `deletedAt` above it any more, so it reads as LIVE, is never swept again, and `ls` prints
+//    it as a file the server has already erased the key for. That is the one state this tool is
+//    built to avoid, and it is reachable from an ordinary half-finished sweep, so the plan below
+//    keeps every ancestor of anything it keeps.
+//
+// PURE: no network and no clock of its own. The server's answer and the current time both arrive
+// as arguments, so `node --test` can put this in states a real account takes a month to reach.
+import { KIND_FILE, trashedAt } from "./drive-paths.js";
+const DAY_MS = 86_400_000;
+/**
+ * How long a trashed item stays restorable.
+ *
+ * ⛔ It must match the browser's `web/src/lib/drive/manifest-views.ts::TRASH_RETENTION_DAYS`, and
+ *    both of those describe the same promise the server enforces on its own rows. A tool that
+ *    counted to a different number would either drop an entry whose file the person could still
+ *    have restored, or leave one behind for a file whose key the server had already destroyed.
+ */
+export const TRASH_RETENTION_DAYS = 30;
+/**
+ * Whole days left of the thirty, counting up rather than down.
+ *
+ * Rounded UP so a row with four hours left says "1 day left" rather than "0 days left" — the
+ * number is what somebody decides whether to restore on, and rounding it to nothing reads as
+ * "already gone".
+ */
+export function daysLeftInTrash(trashedAtMs, nowMs) {
+    return Math.ceil((trashedAtMs + TRASH_RETENTION_DAYS * DAY_MS - nowMs) / DAY_MS);
+}
+/**
+ * Entries whose thirty days have run out.
+ *
+ * Measured from the INHERITED instant, so a file inside a trashed folder is measured from the
+ * moment the folder was thrown away — which is also the moment the server stamped on its row.
+ * Reading each entry's own `deletedAt` would leave every file under a swept folder in the list.
+ */
+export function expiredTrashEntries(index, nowMs) {
+    const out = [];
+    for (const entry of index.all) {
+        const at = trashedAt(index, entry);
+        if (at === null)
+            continue;
+        // ⚠ SUBTRACTION, NOT A DISTANCE. An instant in the FUTURE is a clock that was corrected
+        //   backwards rather than an expiry, and it falls out here because the difference goes
+        //   negative. Anything that measured how far apart the two are instead would sweep it, which
+        //   destroys a key thirty days early on a machine whose date is simply wrong.
+        if (nowMs - at >= TRASH_RETENTION_DAYS * DAY_MS)
+            out.push(entry);
+    }
+    return out;
+}
+/**
+ * Split the expired entries into what may go and what may not.
+ *
+ * `stillOnServer` is every item id the server still has a row for, live or trashed. An id in that
+ * set has a key the server has not destroyed, so dropping this side's copy would hide a file that
+ * is still stored and still being paid for.
+ *
+ * ⚠ Folder entries never appear in that set — the server holds no row for a folder — so a folder
+ *   is held back only by the branch rule below, which is exactly when it should be.
+ */
+export function planPurge(index, expired, stillOnServer) {
+    const going = new Set(expired.map((e) => e.id));
+    const waiting = [];
+    for (const entry of expired) {
+        if (!stillOnServer.has(entry.id))
+            continue;
+        going.delete(entry.id);
+        waiting.push(entry);
+    }
+    // ⛔ Everything ABOVE anything that stays has to stay as well — see the header. Walking up from
+    //    every entry that is not going covers it whatever order they come in: removing an ancestor
+    //    only ever adds to the set of things that stay, and the walk that removed it carries on to
+    //    the root, so the entries it removes on the way are covered by the same pass.
+    for (const entry of index.all) {
+        if (going.has(entry.id))
+            continue;
+        let parentId = entry.parentId;
+        const seen = new Set([entry.id]);
+        while (parentId !== null) {
+            if (seen.has(parentId))
+                break;
+            seen.add(parentId);
+            going.delete(parentId);
+            const parent = index.byId.get(parentId);
+            if (parent === undefined)
+                break;
+            parentId = parent.parentId;
+        }
+    }
+    const held = new Set(waiting.map((e) => e.id));
+    return {
+        drop: expired.filter((e) => going.has(e.id)),
+        waiting,
+        tangled: expired.filter((e) => !going.has(e.id) && !held.has(e.id)),
+    };
+}
+/**
+ * How many of the entries about to be dropped hold bytes.
+ *
+ * Said out loud before the write, because a count of ENTRIES reads as harmless — most of a trashed
+ * branch is folders, which hold nothing at all — and the number that matters is how many keys are
+ * being destroyed.
+ */
+export function filesAmong(entries) {
+    return entries.filter((e) => e.kind === KIND_FILE).length;
+}

package/dist/units.js

@@ -0,0 +1,19 @@
+// Numbers as a person reads them.
+//
+// WHY A MODULE FOR ONE FUNCTION. It began inside `ls`, and the second command that had to print a
+// size would have copied it — after which one table says "1.2 MB" and the other says "1.15 MiB"
+// for the same file, and nobody can tell which of the two is what the account is charged for.
+// Decimal units, because that is the unit storage is sold in.
+/** Bytes as a person reads them: 1 kB is 1,000 bytes, the way the storage is priced. */
+export function humanSize(bytes) {
+    if (bytes < 1000)
+        return `${bytes} B`;
+    const units = ["kB", "MB", "GB", "TB"];
+    let value = bytes / 1000;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit += 1;
+    }
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}

package/dist/update-check.js

@@ -0,0 +1,164 @@
+// Noticing that a newer `nmts` has been published, without getting in the way of the command.
+//
+// ⛔ WHY IT IS NOT A REQUEST PER RUN. An agent runs this tool in a loop; a network round trip
+//    added to every invocation is paid thousands of times, and paid to a host that has nothing to
+//    do with the command being run. So the answer is written down and re-read, and a fresh one is
+//    asked for at most once a day.
+//
+// ⛔ WHY THE NOTICE IS ONE RUN BEHIND. What this run prints comes from the file; what it looks up
+//    goes into the file for the next run. The alternative is making every command wait on a host
+//    that may be slow or unreachable before it can print its own answer, which trades the thing
+//    somebody asked for against a thing they did not.
+//
+// ⛔ STDERR, ALWAYS. The answer to `nmts ls --json` is on stdout and something is parsing it. A
+//    version notice is not part of any command's answer.
+//
+// ⛔ IT NEVER THROWS AND NEVER CHANGES AN EXIT CODE. A version check that can fail a command is a
+//    version check that eventually breaks somebody's script for a reason unrelated to what they
+//    asked for. ⚠ That is a swallowed failure, which this repository generally treats as a defect
+//    — so it is not swallowed silently: the reason is written into the file and `nmts env` prints
+//    it. Quiet where it is implicit, loud where it was asked for, and never invisible.
+//
+// ⛔ AND IT CAN BE TURNED OFF. This is the only thing in the tool that talks to a host other than
+//    the NMTS server and the storage network, so it says so in `nmts env` and in the help, and one
+//    environment variable stops it.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./credentials.js";
+import { isRecord } from "./guards.js";
+import { BINARY_NAME } from "./product.js";
+import { checkingIsOff, isNewer, isVersion, LATEST_RELEASE_URL, newerVersionLine, versionFromLocation, } from "./update-source.js";
+// ⛔ The switch lives in `update-source.ts` and is re-exported rather than re-declared: the help
+//    text needs its name, and importing this module to get it would make `nmts --help` load the
+//    file machinery to print one line.
+export { checkingIsOff, NO_CHECK_ENV_VAR } from "./update-source.js";
+/** How long an answer is kept before another is asked for. */
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long one lookup may take.
+ *
+ * ⚠ Short on purpose. This runs after a command has already done its work, so every millisecond
+ *   here is a millisecond somebody waits for a process that has nothing left to say. A host that
+ *   cannot answer in this long is treated as not having answered, and asked again tomorrow.
+ */
+const LOOKUP_TIMEOUT_MS = 2_000;
+export function checkPath() {
+    return join(configDir(), "update-check.json");
+}
+/** What is on disk, or null when there is nothing readable there. */
+export function readCheck() {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(checkPath(), "utf8"));
+    }
+    catch {
+        // ⛔ Unreadable counts as "never checked", which asks again. The other direction would let a
+        //    corrupt file switch the check off for good.
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const checkedAt = parsed["checkedAt"];
+    if (typeof checkedAt !== "string" || Number.isNaN(Date.parse(checkedAt)))
+        return null;
+    const record = { checkedAt };
+    const latest = parsed["latest"];
+    // ⛔ The version is shape-checked coming OUT of the file as well as going in. This file sits in
+    //    a directory anything running as you can write, and what it holds ends up in a printed line.
+    if (typeof latest === "string" && isVersion(latest))
+        record.latest = latest;
+    const failed = parsed["failed"];
+    if (typeof failed === "string" && failed.length > 0)
+        record.failed = failed.slice(0, 200);
+    return record;
+}
+/** Write the attempt down. Failing to write is itself ignored: there is nothing to fall back to. */
+export function writeCheck(record) {
+    try {
+        mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+        writeFileSync(checkPath(), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Nothing to do about it and nothing worth failing a command over. The next run simply asks
+        // again, which is the same behaviour as never having checked.
+    }
+}
+/** Is it time to ask again? Never having asked counts as due. */
+export function dueForCheck(record, nowMs) {
+    if (record === null)
+        return true;
+    const last = Date.parse(record.checkedAt);
+    if (Number.isNaN(last))
+        return true;
+    // A file stamped in the future is a clock that moved, not a check from tomorrow.
+    return nowMs - last >= CHECK_EVERY_MS || last > nowMs;
+}
+/**
+ * Ask which release is newest.
+ *
+ * ⛔ THE REDIRECT IS THE ANSWER, so it is not followed. `releases/latest` replies with the address
+ *    of the tagged page and an empty body; following it would download a page this has no use for.
+ */
+export async function lookupLatest(url = LATEST_RELEASE_URL) {
+    let response;
+    try {
+        response = await fetch(url, {
+            redirect: "manual",
+            signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return { failed: error instanceof Error ? error.message : "no answer" };
+    }
+    // The body of a redirect is not part of the answer; reading it releases the connection.
+    await response.arrayBuffer().catch(() => undefined);
+    if (response.status < 300 || response.status >= 400) {
+        return { failed: `the releases page answered ${response.status}` };
+    }
+    const location = response.headers.get("location");
+    if (location === null || location === "")
+        return { failed: "the releases page redirected to nowhere" };
+    const version = versionFromLocation(location);
+    if (version === null)
+        return { failed: "the newest release is not named in a shape this can read" };
+    return { version };
+}
+/**
+ * Print the notice this run has earned, then refresh the file for the next one.
+ *
+ * The order is deliberate: whatever is already known is said first, so a slow or unreachable host
+ * cannot delay it, and the run that pays for the lookup is not the run that reads its result.
+ */
+export async function noteUpdate(options) {
+    const env = options.env ?? process.env;
+    if (checkingIsOff(env))
+        return;
+    const say = options.say ?? ((line) => process.stderr.write(`${line}\n`));
+    const now = options.now ?? new Date();
+    try {
+        const record = readCheck();
+        if (record?.latest !== undefined && isNewer(record.latest, options.running)) {
+            say(newerVersionLine(record.latest, options.running, BINARY_NAME));
+        }
+        if (!dueForCheck(record, now.getTime()))
+            return;
+        const lookup = options.lookup ?? (() => lookupLatest());
+        const result = await lookup();
+        const written = { checkedAt: now.toISOString() };
+        if ("version" in result)
+            written.latest = result.version;
+        else {
+            // ⛔ A FAILED ATTEMPT STILL COUNTS AS AN ATTEMPT. Without the stamp, a machine that cannot
+            //    reach the host would try again on every single command — turning an unreachable host
+            //    into a request storm and a delay on every run.
+            written.failed = result.failed;
+            if (record?.latest !== undefined)
+                written.latest = record.latest;
+        }
+        writeCheck(written);
+    }
+    catch {
+        // Nothing a version check discovers is worth failing somebody's command over. The reason is
+        // in the file above where it can be read; there is nowhere else for it to go from here.
+    }
+}

package/dist/update-source.js

@@ -0,0 +1,143 @@
+// Where a newer `nmts` comes from, and what "newer" means.
+//
+// ⛔ THE RELEASES OF THIS TOOL'S OWN REPOSITORY, NOT A PACKAGE REGISTRY. That is where this tool
+//    is installed from today, so it is where "newest" is decided. Asking a registry it is not
+//    published to would answer a different question and answer it confidently — the worst shape a
+//    version check can have. If it is published to one as well, this file is where the two
+//    answers would have to be reconciled, and that will be a decision rather than a default.
+//
+// ⛔ NOTHING HERE READS A FILE OR THE NETWORK. The one hop across the network and the record it
+//    writes are in `update-check.ts`. What is here is what an answer MEANS — the shape it has to
+//    have, how two versions compare, the exact command that installs one, and whether any of it is
+//    switched on — so all of it is testable without a server.
+//
+// ⛔ AND THAT IS ALSO WHY THE SWITCH IS HERE. The help text has to name it, and the help text is
+//    what `nmts --help` prints: putting the name in the module that also opens files would make
+//    every run of the cheapest command load the file machinery to print one line. `check:cli-startup`
+//    measures exactly that, and it is how this was noticed.
+//
+// ⛔ NOTHING HERE PARSES A VERSION LOOSELY. A string that is not three numbers is not a version,
+//    and the answer to "is that one newer" is then "this cannot tell", never "yes". The direction
+//    matters: the failure of a loose parse is a tool that nags about an upgrade that does not
+//    exist, or worse, hands an unchecked string to a command line.
+import { SOURCE_URL } from "./product.js";
+/** Setting this to anything stops the lookup and the notice, both. */
+export const NO_CHECK_ENV_VAR = "NMTS_NO_UPDATE_CHECK";
+/** Is the version check switched off here? */
+export function checkingIsOff(env = process.env) {
+    return (env[NO_CHECK_ENV_VAR] ?? "").length > 0;
+}
+/**
+ * The address that names the newest release whatever it is called.
+ *
+ * It answers with a redirect to the tagged page, and the tag carries the version. That is one
+ * request with an empty body — cheaper than the release listing, and it needs no credential.
+ */
+export const LATEST_RELEASE_URL = `${SOURCE_URL}/releases/latest`;
+/** What that redirect must point at. Anything else is not an answer to the question asked. */
+const TAG_PREFIX = `${SOURCE_URL}/releases/tag/`;
+/**
+ * A version, exactly.
+ *
+ * ⛔ THREE NUMBERS AND NOTHING ELSE. Releases of this tool are tagged `v1.2.3`; a tag with a
+ *    suffix is not a release of it, and treating one as a version would put whatever it contains
+ *    into a URL and then onto a command line.
+ */
+const VERSION_SHAPE = /^(\d+)\.(\d+)\.(\d+)$/;
+/** The published file that carries a whole release, under a name that does not change. */
+const PACKAGE_ASSET = "nmts.tgz";
+/** Is this string a version this file is willing to reason about? */
+export function isVersion(value) {
+    return VERSION_SHAPE.test(value);
+}
+/**
+ * The version a `releases/latest` redirect landed on, or null.
+ *
+ * ⛔ THE ADDRESS IS CHECKED, NOT JUST READ. It arrives from the network, and a redirect that
+ *    pointed somewhere else entirely would otherwise decide what this tool calls the newest
+ *    release. It has to be the tag page of this repository, over an encrypted connection, and the
+ *    tag itself has to be a version.
+ */
+export function versionFromLocation(location) {
+    let resolved;
+    try {
+        resolved = new URL(location, LATEST_RELEASE_URL).toString();
+    }
+    catch {
+        return null;
+    }
+    if (!resolved.startsWith(TAG_PREFIX))
+        return null;
+    const tag = decodeURIComponent(resolved.slice(TAG_PREFIX.length));
+    const version = tag.startsWith("v") ? tag.slice(1) : tag;
+    return isVersion(version) ? version : null;
+}
+/**
+ * -1, 0 or 1 — or null when either side is not a version this can compare.
+ *
+ * ⚠ Null is not "equal". A caller that treats it as equal says nothing; one that treats it as
+ *   "newer" nags forever about a release that does not exist. Both callers here read it as
+ *   "no answer".
+ */
+export function compareVersions(left, right) {
+    const a = VERSION_SHAPE.exec(left);
+    const b = VERSION_SHAPE.exec(right);
+    if (a === null || b === null)
+        return null;
+    for (let part = 1; part <= 3; part += 1) {
+        const one = Number(a[part]);
+        const other = Number(b[part]);
+        if (one !== other)
+            return one > other ? 1 : -1;
+    }
+    return 0;
+}
+/** Is `candidate` a release later than the one running? Unanswerable counts as no. */
+export function isNewer(candidate, running) {
+    return compareVersions(candidate, running) === 1;
+}
+/** The page a person can read about one release on. */
+export function releasePageUrl(version) {
+    return isVersion(version) ? `${TAG_PREFIX}v${version}` : null;
+}
+/**
+ * Where one release's package is.
+ *
+ * ⛔ THE TAGGED ADDRESS, NEVER "LATEST". This is handed to another program to install, and
+ *    "latest" would install whatever is newest at the moment that program runs — which is not
+ *    necessarily the version this tool just named on the screen. Naming the release means what
+ *    was reported and what gets installed are the same thing.
+ */
+export function packageUrl(version) {
+    if (!isVersion(version))
+        return null;
+    return `${SOURCE_URL}/releases/download/v${version}/${PACKAGE_ASSET}`;
+}
+/**
+ * The exact command that installs one release, as an argument list.
+ *
+ * ⛔ A LIST AND NOT A STRING, because it is both printed and run. A string would have to be split
+ *    again to be run, and splitting a string is where a shell gets involved — the one thing a
+ *    command built partly from a value off the network must not touch. `packageUrl` has already
+ *    refused anything that is not three numbers, so nothing here can carry a space, a quote or a
+ *    semicolon, and it never needs to.
+ */
+export function installCommand(version) {
+    const url = packageUrl(version);
+    return url === null ? null : ["npm", "install", "--global", url];
+}
+/** The same command as one line, for printing. */
+export function installCommandLine(version) {
+    const parts = installCommand(version);
+    return parts === null ? null : parts.join(" ");
+}
+/**
+ * The one line printed when a newer release exists.
+ *
+ * ⛔ IT SAYS WHAT IS PUBLISHED AND WHAT IS RUNNING, AND NOTHING ABOUT WHETHER TO UPGRADE. What is
+ *    in a release is not known here, and a line that called it important, recommended or a fix
+ *    would be inventing a reason to act.
+ */
+export function newerVersionLine(latest, running, binary) {
+    return `${binary} ${latest} is published; this is ${running}. \`${binary} update\` installs it.`;
+}

package/dist/upload-api.js

@@ -0,0 +1,98 @@
+// The four server calls the credit-paid upload makes, narrowed to their shapes.
+//
+// ⛔ EACH ANSWER IS CHECKED, NOT CAST. These four replies decide whether money was spent and
+//    whether a file exists; believing a field that is not there would turn a server mistake into a
+//    silent one. What cannot be read is said so, in the caller's terms.
+import { request } from "./api.js";
+import { NmtsError } from "./errors.js";
+function object(value, what) {
+    if (typeof value !== "object" || value === null) {
+        throw new NmtsError(`The server's answer about ${what} was not an object.`);
+    }
+    return value;
+}
+function reserveReply(value) {
+    const v = object(value, "the reservation");
+    const ledgerId = v["ledger_id"];
+    const state = v["state"];
+    if (typeof ledgerId !== "number" || typeof state !== "string") {
+        throw new NmtsError("The server answered a reservation this version cannot read.", {
+            nextStep: "Nothing was uploaded. Check whether an upload was charged before trying again.",
+        });
+    }
+    const out = {
+        ledger_id: ledgerId,
+        state,
+        credits_spent: typeof v["credits_spent"] === "number" ? v["credits_spent"] : 0,
+    };
+    if (typeof v["blob_object_id"] === "string")
+        out.blob_object_id = v["blob_object_id"];
+    if (typeof v["register_tx_digest"] === "string")
+        out.register_tx_digest = v["register_tx_digest"];
+    return out;
+}
+function statusReply(value) {
+    const v = object(value, "the reservation");
+    const ledgerId = v["ledger_id"];
+    const state = v["state"];
+    if (typeof ledgerId !== "number" || typeof state !== "string") {
+        throw new NmtsError("The server answered a reservation this version cannot read.");
+    }
+    const out = { ledger_id: ledgerId, state };
+    if (typeof v["blob_object_id"] === "string")
+        out.blob_object_id = v["blob_object_id"];
+    if (typeof v["register_tx_digest"] === "string")
+        out.register_tx_digest = v["register_tx_digest"];
+    return out;
+}
+function itemReply(value) {
+    const v = object(value, "the committed file");
+    const id = v["id"];
+    if (typeof id !== "string" || id === "") {
+        throw new NmtsError("The file was committed but the server did not say under which id.", {
+            nextStep: "The bytes are stored and paid for. Running the same command again asks the server again " +
+                "and does not spend anything more.",
+        });
+    }
+    return { id };
+}
+/**
+ * How long the certify and commit calls get.
+ *
+ * Longer than an ordinary request because both reach the chain, and because a timeout on either
+ * leaves a paid upload unfinished — a slow answer is much better than a lost one.
+ */
+const CHAIN_TIMEOUT_MS = 120_000;
+/** Bind the four calls to one server and one credential. */
+export function createUploadApi(base, apiKey) {
+    return {
+        async reserve(body) {
+            return reserveReply(await request(base, "/v1/sponsored/reserve", {
+                method: "POST",
+                token: apiKey,
+                body,
+                timeoutMs: CHAIN_TIMEOUT_MS,
+            }));
+        },
+        async status(ledgerId) {
+            return statusReply(await request(base, `/v1/sponsored/${ledgerId}`, { token: apiKey }));
+        },
+        async uploaded(ledgerId, certificate) {
+            return request(base, `/v1/sponsored/${ledgerId}/uploaded`, {
+                method: "POST",
+                token: apiKey,
+                body: { certificate },
+                timeoutMs: CHAIN_TIMEOUT_MS,
+            });
+        },
+        async createItem(body, idempotencyKey) {
+            return itemReply(await request(base, "/v1/items", {
+                method: "POST",
+                token: apiKey,
+                body,
+                idempotencyKey,
+                timeoutMs: CHAIN_TIMEOUT_MS,
+            }));
+        },
+    };
+}