@needmoretruth/nmts-cli 0.17.2

package/dist/commands/update.js

@@ -0,0 +1,169 @@
+// `nmts update` — install the newest published release of this tool.
+//
+// ⛔ TYPING THE VERB IS THE AGREEMENT. Everything else in this tool that cannot be taken back
+//    stops and waits for `--yes`, because the destructive part is a side effect of asking for
+//    something else: `sweep` is asked for a tidy-up and erases rows, `rebuild` is asked for a file
+//    list and replaces one. Here the thing that happens IS the thing that was typed. A command
+//    called `update` that refuses to update until it is asked twice has not made anybody safer;
+//    it has taught them to type `--yes` without reading, which is the habit that matters.
+//
+// ⛔ IT NAMES A RELEASE, NEVER "LATEST". The version is resolved once, printed, and then installed
+//    from the address of THAT release. Handing the installer "latest" would mean the thing on the
+//    screen and the thing on the disk are two separate answers to one question, and a release
+//    published in between makes them different.
+//
+// ⛔ IT REFUSES WHEN THIS COPY IS NOT THE ONE IT WOULD REPLACE. Run from a source checkout, or
+//    from a copy somebody put somewhere by hand, installing would not update anything — it would
+//    put a SECOND copy on the PATH, and which one runs afterwards depends on the order of
+//    directories in an environment variable. That is the kind of confusion somebody debugs for an
+//    hour, so it is a refusal that says what to run instead.
+//
+// ⛔ IT ASKS THE SOURCE-HOSTING SITE, NOT NMTS. No account code, no API key, no session; the
+//    command works signed out, and it is one of the two places in this tool that talk to a host
+//    other than the NMTS server and the storage network. The other is `nmts recovery`.
+import { spawnSync } from "node:child_process";
+import { NmtsError } from "../errors.js";
+import { BINARY_NAME, SOURCE_URL, VERSION } from "../product.js";
+import { lookupLatest } from "../update-check.js";
+import { compareVersions, installCommand, installCommandLine, isNewer, releasePageUrl, } from "../update-source.js";
+/**
+ * Was this copy put here by the installer that would replace it?
+ *
+ * The test is the one thing that is actually true of every such copy and of nothing else: it
+ * lives in a directory named for the package, inside a `node_modules`.
+ *
+ * ⛔ BOTH SEPARATORS, AND THAT IS NOT DEFENSIVENESS. Windows accepts either, and Node hands out
+ *    either: a path that came through a file URL arrives as `D:/a/…` while `import.meta.filename`
+ *    gives `D:\a\…`. Splitting on the platform's own separator found nothing in the first shape,
+ *    so an installed copy on Windows was told it was not installed and `update` refused to run —
+ *    green on Linux and macOS, red only on the platform this repository tests last.
+ */
+export function installedAsPackage(moduleFile) {
+    const parts = moduleFile.split(/[\\/]/);
+    const at = parts.lastIndexOf("node_modules");
+    return at >= 0 && parts[at + 1] === BINARY_NAME;
+}
+/**
+ * Run the installer.
+ *
+ * ⛔ NO SHELL. The address is built from a version that has already been refused unless it is
+ *    three numbers, so there is nothing in this command line a shell could find to interpret —
+ *    and asking one to look would be inviting exactly the question this avoids. On Windows the
+ *    installer is a `.cmd`, which is why its name differs there: naming it directly is what makes
+ *    the shell unnecessary.
+ */
+function runInstaller(command, json) {
+    const [, ...rest] = command;
+    const binary = process.platform === "win32" ? "npm.cmd" : "npm";
+    // ⛔ Under --json the installer's own output cannot go to stdout: something is parsing that.
+    const result = spawnSync(binary, rest, {
+        stdio: json ? ["ignore", "pipe", "pipe"] : "inherit",
+        encoding: "utf8",
+    });
+    if (result.error !== undefined) {
+        return { code: 1, unstartable: result.error.message };
+    }
+    const outcome = { code: result.status ?? 1 };
+    if (json) {
+        const said = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+        if (said.length > 0)
+            outcome.output = said.slice(-2000);
+    }
+    return outcome;
+}
+export async function update(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const running = options.running ?? VERSION;
+    const moduleFile = options.moduleFile ?? import.meta.filename;
+    const found = await (options.lookup ?? lookupLatest)();
+    if ("failed" in found)
+        throw couldNotAsk(found.failed);
+    const latest = found.version;
+    if (!isNewer(latest, running)) {
+        const ahead = compareVersions(running, latest) === 1;
+        if (options.json) {
+            say(JSON.stringify({ running, latest, newerAvailable: false, installed: false, ahead }));
+            return 0;
+        }
+        say(ahead
+            ? `This is ${running}. The newest published release is ${latest}, which is older.`
+            : `This is ${running}, which is the newest published release.`);
+        return 0;
+    }
+    const command = installCommand(latest);
+    const line = installCommandLine(latest);
+    const page = releasePageUrl(latest);
+    // Unreachable while `lookupLatest` only returns shape-checked versions, and a refusal rather
+    // than a cast: the value came off the network, and this is the last place that can say no.
+    if (command === null || line === null || page === null) {
+        throw couldNotAsk(`the newest release is named ${latest}, which this version cannot install`);
+    }
+    const isPackage = installedAsPackage(moduleFile);
+    // ⛔ A DRY RUN THAT REFUSED WOULD BE REPORTING A FAILURE THAT DID NOT HAPPEN. It was asked to
+    //    say what it would do and it said it, whichever copy this is — so it ends at 0. The refusal
+    //    below belongs to the run that would actually have installed something.
+    const stopping = options.dryRun === true || !isPackage;
+    if (stopping) {
+        const code = options.dryRun === true ? 0 : 4;
+        if (options.json) {
+            say(JSON.stringify({
+                running,
+                latest,
+                newerAvailable: true,
+                installed: false,
+                installedAsPackage: isPackage,
+                command: line,
+                releasePage: page,
+            }));
+            return code;
+        }
+        say(`${running} is running. ${latest} is published:  ${page}`);
+        say(``);
+        if (!isPackage) {
+            say(`This copy was not installed by the installer, so installing would leave two:`);
+            say(`  this one    ${moduleFile}`);
+            say(`  the new one wherever the installer puts it, which may come first on your PATH.`);
+            say(``);
+            say(`Update this copy where it came from — or, to install alongside it anyway:`);
+            say(``);
+        }
+        say(`  ${line}`);
+        return code;
+    }
+    if (!options.json) {
+        say(`${running} → ${latest}   ${page}`);
+        say(``);
+        say(`  ${line}`);
+        say(``);
+    }
+    const outcome = (options.install ?? runInstaller)(command, options.json === true);
+    if (outcome.unstartable !== undefined) {
+        throw new NmtsError(`The installer could not be started: ${outcome.unstartable}`, {
+            exitCode: 1,
+            nextStep: `Nothing was changed. \`npm\` has to be on the PATH for this command to install ` +
+                `anything. Once it is, this does the same thing:\n\n  ${line}`,
+        });
+    }
+    if (outcome.code !== 0) {
+        throw new NmtsError(`The installer stopped with code ${outcome.code}.`, {
+            exitCode: 1,
+            nextStep: (outcome.output !== undefined ? `${outcome.output}\n\n` : "") +
+                `${running} is still what runs. A global install writes outside your home directory on ` +
+                `some setups and needs the rights to do it; running the same command yourself shows the ` +
+                `whole reason:\n\n  ${line}`,
+        });
+    }
+    if (options.json) {
+        say(JSON.stringify({ running, latest, newerAvailable: true, installed: true, command: line }));
+        return 0;
+    }
+    say(`${latest} is installed. \`${BINARY_NAME} --version\` says which one runs.`);
+    return 0;
+}
+function couldNotAsk(why) {
+    return new NmtsError(`Could not find out which release is newest: ${why}.`, {
+        exitCode: 1,
+        nextStep: `Nothing was changed. This asks the site the releases are published on, not NMTS — the ` +
+            `releases are readable in a browser at:\n\n  ${SOURCE_URL}/releases/latest`,
+    });
+}

package/dist/commands/usage.js

@@ -0,0 +1,84 @@
+// `nmts usage` — how much this account is holding, added up from the sealed file list.
+//
+// ⚠ IT ANSWERS FROM THE LIST, LIKE `ls`. The list is what every device reads to know what exists,
+//   so its counts are the account's counts. It still proves nothing about whether the bytes behind
+//   any one entry are fetchable, and it is not a bill: the storage network holds more bytes than
+//   the files contain, and what was paid for is a chain fact this command never reads.
+//
+// ⛔ THE TRASH GETS ITS OWN LINE AND IS NOT IN THE TOTAL. "I deleted 4 GB and nothing changed" and
+//    "I deleted 4 GB and it is gone" are both wrong, and one number cannot say the true thing,
+//    which is that the bytes are out of the drive and still stored. So there are two numbers, and
+//    the trash one carries the two commands that act on it.
+//
+// ⛔ IT IS ITS OWN COMMAND RATHER THAN A LINE UNDER `ls`. `ls` prints a table whose length is the
+//    drive's, and an agent that only wants "am I near my limit" would have to fetch and parse all
+//    of it. This answers that in one small object, and both read the same list the same way.
+import { buildIndex } from "../drive-paths.js";
+import { readFileList } from "../manifest.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { humanSize } from "../units.js";
+import { computeUsage } from "../usage-report.js";
+/** An account that has never been written to. Nothing is unknown here — nothing was uploaded. */
+const NOTHING = {
+    files: 0,
+    folders: 0,
+    bytes: 0,
+    trashedFiles: 0,
+    trashedBytes: 0,
+    biggest: [],
+};
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+export async function usage(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const session = await openSession({ server: options.server, network: options.network });
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (list.manifest === null) {
+        // ⛔ ZEROS, NOT A MISSING FIELD. An agent asking how much the account holds gets an answer it
+        //    can compare against a number; making it special-case an absent shape is how "no list yet"
+        //    turns into an unhandled branch on somebody's first run.
+        if (options.json) {
+            say(JSON.stringify({ state: "absent", ...NOTHING }));
+            return 0;
+        }
+        say(`This account has no file list yet. Nothing has been uploaded from any device.`);
+        return 0;
+    }
+    const report = computeUsage(buildIndex(list.manifest.entries));
+    if (options.json) {
+        say(JSON.stringify({ state: "present", seq: list.seq, ...report }));
+        return 0;
+    }
+    if (report.files === 0 && report.folders === 0 && report.trashedFiles === 0) {
+        say(`This account's file list is empty.`);
+        return 0;
+    }
+    say(`${plural(report.files, "file", "files")} · ` +
+        `${plural(report.folders, "folder", "folders")} · ` +
+        `${humanSize(report.bytes)}`);
+    if (report.biggest.length > 0) {
+        say(``);
+        say(`Largest`);
+        for (const file of report.biggest) {
+            say(`  ${humanSize(file.size).padStart(9)}  ${file.path}`);
+        }
+    }
+    say(``);
+    if (report.trashedFiles === 0) {
+        say(`Nothing is in the trash.`);
+    }
+    else {
+        say(`In the trash: ${plural(report.trashedFiles, "file", "files")} · ` +
+            `${humanSize(report.trashedBytes)}. That is still stored and still paid for, and it is not`);
+        say(`counted above. \`${BINARY_NAME} ls --all\` lists it; \`${BINARY_NAME} sweep\` drops the ` +
+            `entries whose 30 days have run out.`);
+    }
+    say(``);
+    say(`  Sizes are the plaintext the files hold, counted from this account's own list — the server`);
+    say(`  was asked for nothing but the sealed blob, and it could not have answered this anyway.`);
+    say(`  What the storage network holds is larger: sealing adds bytes, and storage is bought in`);
+    say(`  fixed units. This is not what the account was charged.`);
+    return 0;
+}

package/dist/commands/verify.js

@@ -0,0 +1,331 @@
+// `nmts verify` — the one thing this tool needs done that it cannot do itself.
+//
+// ⛔ WHY THERE IS A COMMAND FOR SOMETHING THIS TOOL CANNOT DO. An API key makes the server answer,
+//    and that is the whole of what it does. Behind the key the server keeps a second question —
+//    has anybody checked lately that a person is behind this account — and when the answer is no
+//    it does not stop the account, it makes it slower and closes the routes that hand out
+//    something for nothing. The only way to answer that question is for a person to open a page
+//    and type a short code. So this command asks the server for the code, prints it, and waits:
+//    the doing is theirs, the waiting is ours, and saying it any other way would be a lie about
+//    what a program can do.
+//
+// ⛔ THE CODE IS PRINTED ON PURPOSE, AND IT IS NOT THE ACCOUNT CODE. Everything else in this tool
+//    refuses to put a credential on the screen. This one is minted to be read out: it is single
+//    use, it stops working within minutes, the server keeps only a hash of it, and by itself it
+//    opens nothing — a person still has to pass the check on the page. The account code is a
+//    different thing entirely and still never appears here, which the text says out loud so that
+//    nobody reads "type this code" and reaches for the wrong one.
+//
+// ⛔ IT PRINTS THE MOMENT THE CHECK ENDS, NOT A NUMBER OF DAYS. The window is counted in the
+//    server's own weeks, so it ends on a week boundary rather than a fixed span after the code was
+//    typed: somebody who verifies ten minutes before that boundary gets ten minutes. There is no
+//    special case for that in the server and there should not be one here — a second clock is how
+//    two answers to one question start. The honest thing is the absolute moment, and then whoever
+//    is reading decides.
+//
+// ⚠ IT NEEDS THE API KEY AND NOT THE ACCOUNT CODE. Nothing here opens a file, so demanding the
+//   code would refuse a run over a credential the command never uses.
+import { request } from "../api.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { requireApiKey } from "../session.js";
+/**
+ * How long to wait between asks when the server does not say.
+ *
+ * ⛔ AND THE BOUNDS AROUND WHAT IT DOES SAY. The interval arrives from the server, which makes it
+ *    data — and a loop that takes its own timing from data is a loop somebody else controls. Zero
+ *    would be a hot loop against the server; an hour would outlive the code and look like a hang.
+ */
+const DEFAULT_POLL_SECS = 5;
+const MIN_POLL_MS = 1_000;
+const MAX_POLL_MS = 60_000;
+export async function verify(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const quiet = options.json === true;
+    const human = (line) => {
+        if (!quiet)
+            say(line);
+    };
+    const apiKey = requireApiKey();
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    // ⛔ THE QUESTION IS ASKED BEFORE ANY CODE IS MADE, and that ordering is the point. Minting is
+    //    not free: it spends a small daily allowance, it replaces whatever code was outstanding, and
+    //    above all it interrupts a person. An agent that runs this command whenever a request was
+    //    refused would otherwise fetch a human being for an account that is already verified.
+    const standing = await ask(server, apiKey);
+    if (options.status === true) {
+        if (quiet) {
+            say(JSON.stringify({ verified: standing.verified, roundKey: standing.roundKey, verifiedUntil: standing.until?.iso ?? null }));
+            return 0;
+        }
+        sayStanding(say, standing);
+        return 0;
+    }
+    if (standing.verified) {
+        if (quiet) {
+            sayResult(say, standing, false);
+            return 0;
+        }
+        say(`Already verified${standing.until === null ? "" : ` until ${standing.until.iso} (${inWords(standing.until.ms - Date.now())})`}.`);
+        say(``);
+        say(`  No code was made and nobody has to be interrupted. Run this again after that`);
+        say(`  moment to renew the check.`);
+        return 0;
+    }
+    // ⛔ THE ADDRESS IS WRITTEN OUT AT EVERY CALL RATHER THAN HELD IN A CONSTANT, and that is the
+    //    opposite of the usual advice for a reason: the gate that checks this tool's addresses
+    //    against the server's own routes reads the literal in the call. A constant here compiles,
+    //    reads better, and makes that check silently stop looking at this command — which is worse
+    //    than the repetition. The two halves of this share one address, told apart by the method.
+    const minted = readMinted(await request(server, "/v1/agent/verify", { method: "POST", token: apiKey, body: {} }));
+    if (quiet) {
+        say(JSON.stringify({ event: "code", code: minted.code, verifyUrl: minted.verifyUrl, expiresAt: minted.expiresAt.iso, pollAfterSecs: Math.round(minted.pollMs / 1000) }));
+    }
+    // ⚠ ADDRESSED TO WHOEVER IS RUNNING THIS, WHICH IS OFTEN A PROGRAM. It says what has to happen
+    //   and who has to do it, and it does not pretend that the tool has any way to do it instead.
+    human(`A person has to finish this at a browser. Nothing here can do it for them — what`);
+    human(`is being checked is that somebody is there.`);
+    human(``);
+    human(`  Ask the person to open   ${minted.verifyUrl}`);
+    human(`  and to type this code    ${minted.code}`);
+    human(``);
+    human(`This is not the account code. It works once, and it stops working at`);
+    human(`${minted.expiresAt.iso} (${inWords(minted.expiresAt.ms - Date.now())}).`);
+    human(``);
+    human(`Waiting here until it is used. Ctrl-C stops the waiting, not the code.`);
+    const wait = options.sleep ?? waitFor;
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    // ⛔ THE INTERRUPT KEY IS CAUGHT RATHER THAN LEFT TO END THE PROCESS. This command is the one
+    //    that waits, so it is the one where somebody presses Ctrl-C — and what they get for it
+    //    should be the tool's own cancelled code and a line saying the code they were given is still
+    //    good, not a killed process and no explanation. The handler is removed again below: a
+    //    listener that outlives the wait would swallow the next interrupt too.
+    process.on("SIGINT", stop);
+    if (options.signal !== undefined) {
+        if (options.signal.aborted)
+            controller.abort();
+        else
+            options.signal.addEventListener("abort", stop, { once: true });
+    }
+    try {
+        while (Date.now() < minted.expiresAt.ms) {
+            // Never sleep past the moment the code dies: the last ask belongs to the person who typed
+            // it with seconds to spare.
+            const left = minted.expiresAt.ms - Date.now();
+            await wait(Math.min(minted.pollMs, Math.max(left, 0)), controller.signal);
+            stopIfCancelled(controller.signal, minted.expiresAt);
+            const now = await askDuring(server, apiKey, controller.signal, minted.expiresAt);
+            if (now.verified) {
+                if (quiet) {
+                    sayResult(say, now, false);
+                }
+                else {
+                    say(``);
+                    sayVerified(say, now);
+                }
+                return 0;
+            }
+        }
+    }
+    finally {
+        process.off("SIGINT", stop);
+        // The caller's signal is the caller's: nothing of ours stays attached to it after this returns.
+        options.signal?.removeEventListener("abort", stop);
+    }
+    if (quiet)
+        sayResult(say, standing, true);
+    throw new NmtsError(`The code stopped working before anybody used it.`, {
+        exitCode: 1,
+        nextStep: `Nothing was verified and nothing was spent. Run \`${BINARY_NAME} verify\` again when the ` +
+            `person is ready to open the page and type the code it prints.`,
+    });
+}
+/** ⛔ ONE PLACE DECIDES WHAT CANCELLING MEANS, whichever await was interrupted. */
+function stopIfCancelled(signal, expiresAt) {
+    if (!signal.aborted)
+        return;
+    throw new NmtsError(`Cancelled.`, {
+        exitCode: 130,
+        nextStep: `The code is still good until ${expiresAt.iso}, so a person who types it after this still ` +
+            `passes the check. \`${BINARY_NAME} verify --status\` says whether they did.`,
+    });
+}
+/** Ask the server about the standing check. */
+async function ask(server, apiKey) {
+    return readStanding(await request(server, "/v1/agent/verify", { token: apiKey }));
+}
+/**
+ * The same ask, made while a wait can be cancelled.
+ *
+ * ⛔ AN ABORTED REQUEST IS NOT A BROKEN SERVER. Without this, pressing Ctrl-C mid-request surfaces
+ *    as "the server did not answer" — a message that sends a reader to look at the network for a
+ *    thing they did themselves.
+ */
+async function askDuring(server, apiKey, signal, expiresAt) {
+    try {
+        return readStanding(await request(server, "/v1/agent/verify", { token: apiKey, signal }));
+    }
+    catch (error) {
+        stopIfCancelled(signal, expiresAt);
+        throw error;
+    }
+}
+function sayStanding(say, standing) {
+    if (standing.verified) {
+        sayVerified(say, standing);
+        return;
+    }
+    say(`Not verified.`);
+    say(``);
+    say(`  Until somebody passes the check, this account's key works under tighter limits and`);
+    say(`  some requests are refused outright.`);
+    say(``);
+    say(`  \`${BINARY_NAME} verify\` prints a short code for a person to type at a browser.`);
+    say(`  Nothing here can pass the check without them.`);
+}
+function sayVerified(say, standing) {
+    const week = standing.roundKey === null ? `` : ` Week ${standing.roundKey}.`;
+    if (standing.until === null) {
+        say(`Verified.${week}`);
+        return;
+    }
+    say(`Verified until ${standing.until.iso} (${inWords(standing.until.ms - Date.now())}).${week}`);
+    say(``);
+    say(`  That moment is a boundary of the server's own weeks, not a fixed span from now, so`);
+    say(`  a check passed just before one ends is a short one.`);
+}
+/** The machine-readable end of a run that waited. `codeExpired` says which of the two ways it ended. */
+function sayResult(say, standing, codeExpired) {
+    say(JSON.stringify({
+        event: "result",
+        verified: standing.verified,
+        roundKey: standing.roundKey,
+        verifiedUntil: standing.until?.iso ?? null,
+        codeExpired,
+    }));
+}
+/** One field of a server answer, or null when it is absent or the wrong type. */
+function stringField(source, field) {
+    if (typeof source !== "object" || source === null)
+        return null;
+    const value = Reflect.get(source, field);
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function numberField(source, field) {
+    if (typeof source !== "object" || source === null)
+        return null;
+    const value = Reflect.get(source, field);
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function booleanField(source, field) {
+    if (typeof source !== "object" || source === null)
+        return null;
+    const value = Reflect.get(source, field);
+    return typeof value === "boolean" ? value : null;
+}
+/**
+ * An instant, normalised to UTC.
+ *
+ * ⛔ UTC AND NOTHING ELSE. The window is decided in the server's calendar; printing a local time
+ *    would make two machines in different places disagree about when the same moment is.
+ */
+function momentOf(raw) {
+    if (raw === null)
+        return null;
+    const ms = Date.parse(raw);
+    if (Number.isNaN(ms))
+        return null;
+    return { iso: new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z"), ms };
+}
+/**
+ * The address a person will be told to open — refused unless it is one a browser can trust.
+ *
+ * ⛔ THIS IS THE ONE PLACE THIS TOOL ASKS A HUMAN BEING TO GO SOMEWHERE. Everything else it prints
+ *    is about files. The address arrives from whatever server `--server` names, so a run pointed
+ *    at the wrong host by a stale config or a helpful agent could hand somebody a link to type a
+ *    code into — and the person reading it has no way to tell it apart from ours. `https` is the
+ *    floor; loopback over plain http is allowed because that is the development stack and it is
+ *    not somewhere a stranger can stand.
+ */
+function trustedUrl(raw) {
+    if (raw === null)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol === "https:")
+        return raw;
+    const loopback = parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost" || parsed.hostname === "[::1]";
+    return parsed.protocol === "http:" && loopback ? raw : null;
+}
+function readMinted(answer) {
+    const code = stringField(answer, "code");
+    const verifyUrl = trustedUrl(stringField(answer, "verify_url"));
+    const expiresAt = momentOf(stringField(answer, "expires_at"));
+    if (code === null || verifyUrl === null || expiresAt === null) {
+        throw brokenAnswer("a code, an address a browser can trust to type it at, and when it stops working");
+    }
+    // ⛔ A MISSING INTERVAL IS NOT A REASON TO REFUSE — there is a sane one here. A missing DEADLINE
+    //    is, because without it the waiting has no end and a hang is worse than a failure.
+    const seconds = numberField(answer, "poll_after_secs") ?? DEFAULT_POLL_SECS;
+    const pollMs = Math.min(Math.max(seconds * 1000, MIN_POLL_MS), MAX_POLL_MS);
+    return { code, verifyUrl, expiresAt, pollMs };
+}
+function readStanding(answer) {
+    const verified = booleanField(answer, "verified");
+    if (verified === null)
+        throw brokenAnswer("whether this account is verified");
+    return {
+        verified,
+        roundKey: stringField(answer, "round_key"),
+        until: momentOf(stringField(answer, "verified_until")),
+    };
+}
+/** ⚠ The answer's own contents are never quoted back: it came from the network, and it goes in a log. */
+function brokenAnswer(wanted) {
+    return new NmtsError(`The server's answer did not carry ${wanted}.`, {
+        exitCode: 1,
+        nextStep: `This version of \`${BINARY_NAME}\` and that server do not agree about this. Update the tool, or check --server.`,
+    });
+}
+/**
+ * A gap in words, coarse on purpose.
+ *
+ * ⚠ Rounded, because the number beside it is exact. The absolute moment is what somebody acts on;
+ *   this is only there so nobody has to subtract two timestamps in their head.
+ */
+function inWords(ms) {
+    if (ms <= 0)
+        return "already past";
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 1)
+        return "in under a minute";
+    if (minutes < 60)
+        return `in ${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.round(ms / 3_600_000);
+    if (hours < 48)
+        return `in ${hours} hour${hours === 1 ? "" : "s"}`;
+    return `in ${Math.round(ms / 86_400_000)} days`;
+}
+/** The default wait: a timer that gives up quietly the moment the run is cancelled. */
+function waitFor(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}