@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/commands/create-link.js

@@ -0,0 +1,232 @@
+// `nmts create` without a key: the code is made here, and a PERSON finishes the account in a
+// browser.
+//
+// ⛔ WHY THIS PATH EXISTS. The other one needs an API key whose account had a person pass the
+//    human check — which is fine once somebody has an account, and impossible for the first one.
+//    So the tool makes the NMTS key on this machine, buys a one-time address with a proof of
+//    work, and prints it. A person opens that address, types the code this printed, passes the
+//    check, and the account is made at that moment. Nothing here can do it for them, and that is
+//    the point rather than a limitation.
+//
+// ⛔ THE CODE NEVER GOES TO THE SERVER, NOT EVEN HASHED. What is sent is the account id — a public
+//    identifier derived one-way from the code — and nothing else. The pair that proves ownership
+//    is derived IN THE BROWSER from what the person types there.
+//
+// ⛔ THE FILE IS WRITTEN BEFORE THE ADDRESS IS ASKED FOR, the same rule the key path keeps: a full
+//    disk must fail while there is nothing to lose. ⚠ Unlike that path, a refusal afterwards does
+//    NOT remove the file — nothing has been created yet, so the code is not "the key to an account
+//    that may exist"; it is simply a code nobody has registered, and running again makes another.
+//    Removing it would be deleting a file a person may already have copied somewhere.
+//
+// ⛔ NOTHING IS STORED ON THIS MACHINE. `nmts login` is what puts a code here, and it is a separate
+//    act on purpose — see the header of `create.ts`.
+import { createHash } from "node:crypto";
+import { request } from "../api.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { newAccountCode, registrationProofOf } from "../registration.js";
+import { codeFileTarget, jsonNeedsAFile, writeCodeFile } from "./create-code-file.js";
+/** How often the status of a link is asked about, in milliseconds. */
+const POLL_EVERY_MS = 3_000;
+/** How long this waits before giving up on a person, in milliseconds. Matches the link's own life. */
+const WAIT_FOR_MS = 30 * 60 * 1000;
+/** Say "this is working" only if the work actually takes a moment. */
+const QUIET_FOR_MS = 1_000;
+/** Hashes between clock reads while solving. Small enough to notice a second; large enough to cost nothing. */
+const CHECK_EVERY = 4_096;
+export async function createThroughLink(options) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const { server, network } = options;
+    // ⛔ EVERY REFUSAL THAT DOES NOT NEED THE NETWORK HAPPENS FIRST.
+    const codeFile = codeFileTarget(options.out);
+    if (options.json === true && codeFile === null)
+        throw jsonNeedsAFile();
+    const puzzle = await askForWork(server);
+    const code = await newAccountCode();
+    const proof = await registrationProofOf(code);
+    if (codeFile !== null)
+        writeCodeFile(codeFile, code);
+    const nonce = solve(puzzle.challenge, proof.accountId, puzzle.bits, say);
+    const answer = await request(server, "/v1/accounts/registration-links", {
+        method: "POST",
+        body: { account_id: proof.accountId, challenge: puzzle.challenge, nonce },
+    });
+    const url = stringField(answer, "url");
+    const expiresAt = stringField(answer, "expires_at");
+    if (url === null)
+        throw unexpected("an address");
+    const linkId = url.slice(url.lastIndexOf("/") + 1);
+    const statusUrl = `${server}/v1/accounts/registration-links/${linkId}`;
+    if (options.json === true && codeFile !== null) {
+        // ⛔ NO `account_code` FIELD, AND THERE NEVER WILL BE — see `create.ts`. ⚠ And no waiting:
+        //    machine-readable output is one object, and the address is worth nothing to the program
+        //    reading it until it has handed it to a person. `status_url` is how it finds out what
+        //    happened next.
+        say(JSON.stringify({ url, expires_at: expiresAt, code_file: codeFile, status_url: statusUrl }));
+        return 0;
+    }
+    sayTheAddress(say, url, expiresAt, server, network);
+    await sayTheQr(say, url);
+    if (options.noWait === true) {
+        say(``);
+        say(`Not waiting. To find out whether it was used:`);
+        say(``);
+        say(`  ${statusUrl}`);
+        say(``);
+        say(`It answers {"status":"pending"}, {"status":"done"} or {"status":"expired"}.`);
+        sayWhereTheCodeIs(say, codeFile, code);
+        return 0;
+    }
+    say(``);
+    say(`Waiting. This stops on its own when the address runs out.`);
+    const finished = await waitForAPerson(server, linkId);
+    if (!finished)
+        throw nobodyCame(statusUrl);
+    say(``);
+    say(`Registered. The account exists now.`);
+    sayWhereTheCodeIs(say, codeFile, code);
+    sayWhatIsNext(say);
+    return 0;
+}
+async function askForWork(server) {
+    const answer = await request(server, "/v1/accounts/registration-challenge");
+    const challenge = stringField(answer, "challenge");
+    const bits = isRecord(answer) ? answer["difficulty_bits"] : null;
+    if (challenge === null || typeof bits !== "number" || !Number.isFinite(bits) || bits < 0) {
+        throw unexpected("a challenge");
+    }
+    return { challenge, bits };
+}
+/**
+ * Find a nonce whose digest under this challenge starts with `bits` zero bits.
+ *
+ * ⛔ THE RULE IS `SHA-256(challenge ‖ account_id ‖ nonce)` OVER THE THREE STRINGS' UTF-8 BYTES, IN
+ *    THAT ORDER, WITH NOTHING BETWEEN THEM. The server computes the same digest and refuses
+ *    anything else, so this sentence is the contract between the two — a separator nobody wrote
+ *    down is how two implementations of one rule stop agreeing. The account id is in it so that
+ *    one piece of work buys an address for one id and nothing else.
+ *
+ * ⚠ IT BLOCKS. At the difficulty this service sets it is about a million digests and well under a
+ *   couple of seconds; there is nothing else for this command to be doing meanwhile, and a
+ *   progress bar over a number nobody can act on is noise. One line, and only if it is slow.
+ */
+function solve(challenge, accountId, bits, say) {
+    const started = Date.now();
+    let said = false;
+    for (let n = 0;; n += 1) {
+        const nonce = String(n);
+        const digest = createHash("sha256").update(challenge).update(accountId).update(nonce).digest();
+        if (leadingZeroBits(digest) >= bits) {
+            return nonce;
+        }
+        if (n % CHECK_EVERY === 0 && !said && Date.now() - started > QUIET_FOR_MS) {
+            say(`Preparing…`);
+            said = true;
+        }
+    }
+}
+function leadingZeroBits(digest) {
+    let seen = 0;
+    for (const byte of digest) {
+        seen += Math.clz32(byte) - 24;
+        if (byte !== 0)
+            break;
+    }
+    return seen;
+}
+/**
+ * Ask the server, every few seconds, whether somebody has used the address.
+ *
+ * ⚠ `expired` ENDS THE WAIT. The link's life and this deadline are the same thirty minutes, so a
+ *   server that says "expired" is telling us the person did not come — waiting past that would be
+ *   waiting for something that can no longer happen.
+ */
+async function waitForAPerson(server, linkId) {
+    const deadline = Date.now() + WAIT_FOR_MS;
+    for (;;) {
+        const answer = await request(server, `/v1/accounts/registration-links/${linkId}`);
+        const status = stringField(answer, "status");
+        if (status === "done")
+            return true;
+        if (status === "expired")
+            return false;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((done) => setTimeout(done, POLL_EVERY_MS));
+    }
+}
+function sayTheAddress(say, url, expiresAt, server, network) {
+    say(`A person has to finish this in a browser. Nothing on this machine can.`);
+    say(``);
+    say(`  ${url}`);
+    say(``);
+    say(expiresAt === null
+        ? `Opening it asks for the NMTS key below, and for the check that says a person is here.`
+        : `It works until ${expiresAt}. Opening it asks for the NMTS key below, and for the ` +
+            `check that says a person is here.`);
+    say(`The account will exist on ${server} (${network}) the moment they finish.`);
+}
+/**
+ * The address again, as something a phone can read.
+ *
+ * ⚠ The same settings the browser's own codes use (`wallet address --qr`): medium error correction
+ *   and a two-module quiet zone, without which many scanners see nothing at all.
+ */
+async function sayTheQr(say, url) {
+    const { renderUnicodeCompact } = await import("uqr");
+    say(``);
+    for (const row of renderUnicodeCompact(url, { ecc: "M", border: 2 }).split("\n"))
+        say(`  ${row}`);
+}
+/**
+ * The code, last, with the one thing that has to be understood before it.
+ *
+ * ⛔ NOTHING FOLLOWS IT BUT WHAT TO DO WITH IT. A screen of next steps under an NMTS key is how
+ *    a person scrolls past the only copy of it.
+ */
+function sayWhereTheCodeIs(say, codeFile, code) {
+    say(``);
+    say(`⛔ THIS IS THE ONLY COPY OF THE NMTS KEY THAT WILL EVER EXIST.`);
+    say(`   NMTS keeps a verifier and never the NMTS key. It cannot be reset, resent or replaced.`);
+    say(`   Lose it and the account and every file in it are gone — for you and for NMTS.`);
+    say(``);
+    say(`   ${codeFile ?? code}`);
+    say(``);
+    say(codeFile === null
+        ? `It is what the browser asks for, and what \`${BINARY_NAME} login\` stores on a machine.`
+        : `That file holds it, readable by you alone. It is what the browser asks for.`);
+}
+/**
+ * The key is what makes the server answer this tool, and since 2026-09-05 the NMTS key this
+ * machine already holds is enough to make one — no browser, no person at the account screen.
+ */
+function sayWhatIsNext(say) {
+    say(``);
+    say(`Next: \`${BINARY_NAME} key new\` makes this machine's API key out of that NMTS key and stores it.`);
+    say(`Nothing else is needed before the first \`${BINARY_NAME} put\`.`);
+}
+function nobodyCame(statusUrl) {
+    return new NmtsError(`The address ran out before anybody used it.`, {
+        // ⛔ 5 — "waiting on the person". Nothing went wrong and nothing is malformed; what is missing
+        //    is an act only a person can perform.
+        exitCode: 5,
+        nextStep: [
+            `No account was created, and the NMTS key that was made for it is now good for nothing.`,
+            `Running \`${BINARY_NAME} create\` again makes a NEW NMTS key and a NEW address; it does not`,
+            `resume this one.`,
+            ``,
+            `If somebody is finishing it right now, this says so: ${statusUrl}`,
+        ].join("\n"),
+    });
+}
+function unexpected(what) {
+    return new NmtsError(`The server did not answer with ${what}.`, {
+        exitCode: 1,
+        nextStep: `Nothing was created. This tool may be older than the server it is talking to.`,
+    });
+}
+function stringField(answer, field) {
+    const value = isRecord(answer) ? answer[field] : null;
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,20 @@
+export interface CreateOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    /** A file to write the new NMTS key into, instead of printing it. Never overwritten. */
+    out?: string | undefined;
+    /** The Terms of Service version a PERSON read and accepts for the new account. */
+    acceptTerms?: string | undefined;
+    /** The Privacy Policy version accepted in the same act. */
+    acceptPrivacy?: string | undefined;
+    /**
+     * Link path only: print the address and stop, instead of waiting for a person to use it.
+     *
+     * ⚠ IT DOES NOTHING ON THE KEY PATH, because there is nothing to wait for there — the account
+     *   exists by the time that path prints anything.
+     */
+    noWait?: boolean | undefined;
+    write?: (line: string) => void;
+}
+export declare function create(options?: CreateOptions): Promise<number>;

package/dist/commands/create.js

@@ -16,7 +16,7 @@
 //
 // ⛔ WITH `--json` THE CODE DOES NOT GO INTO THE OUTPUT. Machine-readable output is read by a
 //    program, which means it lands in a pipe, a file, a CI log or an agent's transcript — the
-//    exact places `credentials.ts` spends its whole header keeping the account code out of. So
+//    exact places `credentials.ts` spends its whole header keeping the NMTS key out of. So
 //    `--json` is refused unless `--out <file>` names somewhere for the code to go, and the JSON
 //    then carries the PATH and not the value. That is the same shape this tool already recommends
 //    for handing a secret to a container (`NMTS_ACCOUNT_CODE_FILE` — a variable holding a
@@ -29,38 +29,56 @@
 //    server has created the account would mean an account exists whose only key we are about to
 //    drop. If the creation then fails, the file is removed again — no account, no code, no trace.
 //
-// ⛔ THE FIRST DOOR OF `POST /v1/accounts` IS NOT AVAILABLE TO THIS TOOL AND NEVER WILL BE. The
-//    server takes either a solved human check with no credential, or an API key whose account had
-//    a PERSON pass that check within four of its weeks. A machine cannot solve the first, so this
-//    command works only for a caller that already has an account and a verified key — and it says
-//    that plainly, before it makes anything, rather than failing with a message about scopes.
-import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+// ⛔⭐ THERE ARE TWO PATHS, AND WHICH ONE RUNS IS DECIDED BY WHAT THIS MACHINE HOLDS (2026-09-05).
+//    `POST /v1/accounts` takes either a solved human check — which no machine can produce
+//    — or an API key whose account had a PERSON pass that check within four of its weeks. That
+//    second door is this file, and it is only open to a caller that ALREADY has an account.
+//    ▶ With no such key, the command does not refuse any more: it makes the code here, buys a
+//    one-time address with a proof of work, and prints it for a PERSON to open (`create-link.ts`).
+//    The person types the code in a browser and the account is made there. ⚠ The person is not
+//    optional in either path — what changes is whether they are being asked to pass a check for an
+//    account they already have, or to finish one that does not exist yet.
+import { rmSync } from "node:fs";
 import { request, ServerError } from "../api.js";
-import { readCredentialsFile } from "../credentials.js";
+import { readCredentialsFile, resolveApiKey } from "../credentials.js";
 import { NmtsError } from "../errors.js";
 import { isRecord } from "../guards.js";
-import { askAPersonToVerify, humanCheck } from "../human-check.js";
+import { humanCheck } from "../human-check.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME, HOME_URL } from "../product.js";
 import { newAccountCode, registrationProofOf } from "../registration.js";
 import { resolveServer } from "../server.js";
-import { requireApiKey } from "../session.js";
-import { STDOUT_TARGET } from "../stdout.js";
+import { codeFileTarget, jsonNeedsAFile, writeCodeFile } from "./create-code-file.js";
 export async function create(options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
-    const apiKey = requireApiKey();
+    const held = resolveApiKey();
     const stored = readCredentialsFile();
     const server = resolveServer(options.server ?? stored?.server);
     const network = resolveNetwork(server, options.network ?? stored?.network);
+    // ⛔ THE KEY PATH IS TAKEN ONLY WHEN IT WOULD ACTUALLY WORK. A key whose account has no live
+    //    human check cannot create anything (the server refuses it), and refusing here instead
+    //    would leave the caller with no way to make a first account at all — which is the wall this
+    //    tool used to end at. ⚠ A key that is revoked or unreadable still fails LOUDLY: `humanCheck`
+    //    throws for those, and falling through to the other path would hide a broken credential
+    //    behind a flow that happens to work.
+    const check = held === null ? null : await humanCheck(server, held.key);
+    if (held === null || check === null || !check.live) {
+        const { createThroughLink } = await import("./create-link.js");
+        return await createThroughLink({
+            server,
+            network,
+            out: options.out,
+            json: options.json === true,
+            noWait: options.noWait,
+            write: options.write,
+        });
+    }
+    const apiKey = held.key;
     // ⛔ EVERY REFUSAL THAT DOES NOT NEED THE NETWORK HAPPENS FIRST, so a run that was never going
     //    to work does not spend one of the creator's two accounts for the day finding that out.
     const codeFile = codeFileTarget(options.out);
     if (options.json === true && codeFile === null)
         throw jsonNeedsAFile();
-    const check = await humanCheck(server, apiKey);
-    if (!check.live)
-        throw askAPersonToVerify("No account can be created");
     const inForce = await termsInForce(server, apiKey);
     const accepted = inForce === null ? null : acceptanceOffered(inForce, options);
     const code = await newAccountCode();
@@ -114,74 +132,6 @@ export async function create(options = {}) {
         sayWhereTheCodeWent(say, codeFile);
     return 0;
 }
-/**
- * Where the code goes, or `null` for the screen.
- *
- * ⛔ `-` IS REFUSED, WHICH IS THE OPPOSITE OF WHAT IT MEANS EVERYWHERE ELSE IN THIS TOOL. In
- *    `get` and `listfile` it means "hand the bytes to whatever is reading stdout", and that is
- *    right for a file somebody already has. Here it would mean putting the only copy of an
- *    account code into the same stream a program is parsing — which is the one place this command
- *    exists to keep it out of.
- */
-function codeFileTarget(out) {
-    if (out === undefined || out === "")
-        return null;
-    if (out === STDOUT_TARGET) {
-        throw new NmtsError("The new account code will not be sent to stdout.", {
-            exitCode: 2,
-            nextStep: `Nothing was created. stdout is what a program reads and a log keeps, and this is the ` +
-                `only copy of the code. Name a file — \`--out ./account-code.txt\` — or leave --out off ` +
-                `and read it off the screen.`,
-        });
-    }
-    const path = isAbsolute(out) ? out : resolve(process.cwd(), out);
-    let existing = null;
-    try {
-        existing = statSync(path);
-    }
-    catch {
-        // Not there is exactly what this wants.
-    }
-    if (existing !== null) {
-        // ⛔ NO `--force` HERE, DELIBERATELY. Everywhere else in this tool --force replaces a file
-        //    that can be fetched again. The file this would replace may be the only copy of ANOTHER
-        //    account's code, and overwriting it destroys that account with no way back.
-        throw new NmtsError(`${path} is already there.`, {
-            exitCode: 4,
-            nextStep: existing.isDirectory()
-                ? `--out names the FILE the code goes into, not a directory.`
-                : `Nothing was created. That file is not replaced, whatever --force says: it may hold ` +
-                    `the only copy of another account's code. Name one that does not exist.`,
-        });
-    }
-    return path;
-}
-/**
- * Write the code where the caller pointed, readable by nobody else.
- *
- * ⚠ `wx` FAILS IF THE NAME APPEARED SINCE THE CHECK ABOVE, which is the point of using it rather
- *   than trusting that check: between the two, something else may have written there.
- *
- * ⚠ ON WINDOWS THE MODE IS IGNORED and the file inherits the folder's permissions — the same
- *   limit `credentials.ts` documents, and claiming otherwise would be claiming a guarantee the
- *   platform does not give.
- */
-function writeCodeFile(path, code) {
-    const dir = resolve(path, "..");
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    try {
-        writeFileSync(path, `${code}\n`, { mode: 0o600, flag: "wx" });
-    }
-    catch (error) {
-        // ⛔ THE CAUSE IS NAMED BUT THE CODE IS NOT. `writeFileSync`'s errno line carries the path and
-        //    never the contents, so it is safe to pass on; the code itself appears in no message here.
-        throw new NmtsError(`The account code could not be written to ${path}.`, {
-            exitCode: 1,
-            nextStep: `Nothing was created — the file is written before the account is asked for, so that a ` +
-                `failure here costs nothing. Cause: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-}
 /** What documents this server is enforcing, read from the one route a key may ask. */
 async function termsInForce(server, apiKey) {
     const answer = await request(server, "/v1/account/summary", { token: apiKey });
@@ -228,7 +178,7 @@ function termsRefusal(inForce, named) {
         //    command line is not malformed. What is missing is a decision only a person can take.
         exitCode: 5,
         nextStep: [
-            `Nothing was created and no account code was made.`,
+            `Nothing was created and no NMTS key was made.`,
             ``,
             `In force now:`,
             `  Terms of Service  ${inForce.terms}`,
@@ -293,7 +243,7 @@ function uncertain(path, cause) {
     return new NmtsError(`The server did not answer, so whether the account was created is not known here.`, {
         exitCode: 1,
         nextStep: [
-            `${path} was KEPT, and it holds the only code that account would have.`,
+            `${path} was KEPT, and it holds the only NMTS key that account would have.`,
             ``,
             `Keep it until you know. Nothing on this machine can tell the two cases apart, and the`,
             `cost of being wrong is one small file against an account nobody could ever open.`,
@@ -303,15 +253,6 @@ function uncertain(path, cause) {
         ].join("\n"),
     });
 }
-function jsonNeedsAFile() {
-    return new NmtsError("--json needs --out, because the account code will not go into the output.", {
-        exitCode: 2,
-        nextStep: `Nothing was created. Machine-readable output is read by a program and kept by a log, and ` +
-            `the code is the only key this account will ever have. \`--out ./account-code.txt\` writes ` +
-            `it to a file only you can read; the JSON then names that file. Without --json the code is ` +
-            `printed on the screen for a person to keep.`,
-    });
-}
 /** One field of the answer's `account` object, or null. The server's shape, not ours. */
 function accountField(answer, field) {
     const account = isRecord(answer) ? answer["account"] : null;
@@ -325,19 +266,19 @@ function sayCreated(say, accountId, server, network) {
     say(``);
     say(`  account id  ${accountId}`);
     say(``);
-    say(`Nothing on this machine changed. The account code you were signed in as is still the one`);
+    say(`Nothing on this machine changed. The NMTS key you were signed in as is still the one`);
     say(`this tool uses; this new account is not stored, and not switched to.`);
     say(``);
 }
 /**
  * The code, last, with the one thing that has to be understood before it.
  *
- * ⛔ NOTHING FOLLOWS IT BUT THE COMMAND THAT STORES IT. A screen of next steps under an account
- *    code is how a person scrolls past the only copy of it.
+ * ⛔ NOTHING FOLLOWS IT BUT THE COMMAND THAT STORES IT. A screen of next steps under an NMTS
+ *    key is how a person scrolls past the only copy of it.
  */
 function sayTheCode(say, code) {
-    say(`⛔ THIS IS THE ONLY COPY OF THE ACCOUNT CODE THAT WILL EVER EXIST.`);
-    say(`   NMTS keeps a verifier and never the code. It cannot be reset, resent or replaced.`);
+    say(`⛔ THIS IS THE ONLY COPY OF THE NMTS KEY THAT WILL EVER EXIST.`);
+    say(`   NMTS keeps a verifier and never the NMTS key. It cannot be reset, resent or replaced.`);
     say(`   Lose it and the account and every file in it are gone — for you and for NMTS.`);
     say(``);
     say(`   ${code}`);
@@ -345,8 +286,8 @@ function sayTheCode(say, code) {
     say(`To use this machine as that account: \`${BINARY_NAME} logout\`, then \`${BINARY_NAME} login\`.`);
 }
 function sayWhereTheCodeWent(say, path) {
-    say(`⛔ THE ONLY COPY OF THE ACCOUNT CODE IS NOW IN ONE FILE, AND NOWHERE ELSE.`);
-    say(`   NMTS keeps a verifier and never the code. It cannot be reset, resent or replaced.`);
+    say(`⛔ THE ONLY COPY OF THE NMTS KEY IS NOW IN ONE FILE, AND NOWHERE ELSE.`);
+    say(`   NMTS keeps a verifier and never the NMTS key. It cannot be reset, resent or replaced.`);
     say(`   Lose that file and the account and every file in it are gone.`);
     say(``);
     say(`   ${path}`);

package/dist/commands/credits.d.ts

@@ -0,0 +1,9 @@
+export interface CreditsOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    /** `--to`: which account receives, base64url, as `nmts whoami` prints it for that account. */
+    to?: string | undefined;
+    write?: (line: string) => void;
+}
+export declare function credits(action: string | undefined, amount: string | undefined, options?: CreditsOptions): Promise<number>;

package/dist/commands/credits.js

@@ -0,0 +1,110 @@
+// `nmts credits transfer --to <account-id> <credits>` — move credits to another account of the
+// same family.
+//
+// ⛔ THE FAMILY IS THE WHOLE RANGE, AND THIS COMMAND CANNOT WIDEN IT. A family is the account a
+//    person made and every account under it; the server refuses anything else and answers an
+//    account that does not exist exactly the same way, so nothing here can be used to find out
+//    which account identifiers are real. There is no price, no fee and no third party — this is
+//    not a market, and it does not reopen what "credits cannot be transferred" was written for.
+//
+// ⛔ WHY IT EXISTS. The free trial, the human check and the ceilings belong to the whole family:
+//    one week's place for the tree, not one each. Without a way to move credits that place lands
+//    on ONE account and the account that needs it cannot be given it.
+//
+// ⛔ IT ASKS ABOUT THE PERSON'S CHECK FIRST, for the reason `commands/trial.ts` sets out at
+//    length: the server decides scope before it looks at the check, so a caller can be told "the
+//    key was not given permission" when what is actually missing is a person — which sends an
+//    agent off making another key, the one remedy that cannot help.
+//
+// ⚠ NOTHING IS RETRIED HERE. Every refusal this can meet is decided by the request itself (name
+//   another account, send less, send some), and `api.ts` already carries the advice for each.
+import { request } from "../api.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { askAPersonToVerify, humanCheck } from "../human-check.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { requireApiKey } from "../session.js";
+/** The one word this command takes. */
+const TRANSFER = "transfer";
+export async function credits(action, amount, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (action !== TRANSFER) {
+        throw new NmtsError(`\`${BINARY_NAME} credits\` takes \`${TRANSFER}\`, and nothing else.`, {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} credits ${TRANSFER} --to <account identifier> <credits>\` moves credits ` +
+                `to another account of your own. \`${BINARY_NAME} balance\` is what reads them.`,
+        });
+    }
+    // ⛔ BOTH OPERANDS ARE CHECKED BEFORE THE NETWORK. A missing recipient and an amount nobody
+    //    could have meant are command lines to fix, not questions to ask the server — and an amount
+    //    clamped into range here would move a number nobody typed.
+    const to = (options.to ?? "").trim();
+    if (to === "")
+        throw needsTo();
+    const moving = parseAmount(amount);
+    const apiKey = requireApiKey();
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    const check = await humanCheck(server, apiKey);
+    if (!check.live)
+        throw askAPersonToVerify("Credits cannot be moved");
+    const moved = read(await request(server, "/v1/credits/transfer", {
+        method: "POST",
+        token: apiKey,
+        body: { to, credits: moving },
+    }));
+    if (options.json === true) {
+        // The server's own spelling for its three numbers, plus the recipient this run named — so a
+        // reader that has seen the wire and then this is not converting between two sets of names.
+        say(JSON.stringify({ to, ...moved }));
+        return 0;
+    }
+    say(`Sent ${plural(moved.credits)} to ${to}.`);
+    say(``);
+    say(`  this account   ${plural(moved.from_balance)}`);
+    say(`  that account   ${plural(moved.to_balance)}`);
+    say(``);
+    say(`  They keep the date they were already going to lapse on: moving credits does not renew`);
+    say(`  them. \`${BINARY_NAME} balance\` reads the ledger of whichever account holds the key.`);
+    return 0;
+}
+function plural(n) {
+    return `${n} ${n === 1 ? "credit" : "credits"}`;
+}
+/** The amount, refused in this command's own words. ⚠ Whole and above zero: the server has its own
+ *  code for a transfer of nothing, and this end can say so without spending a request on it. */
+function parseAmount(raw) {
+    const n = raw === undefined ? Number.NaN : Number(raw);
+    if (!Number.isSafeInteger(n) || n < 1) {
+        throw new NmtsError(`\`${BINARY_NAME} credits ${TRANSFER}\` takes a whole number of credits above zero, not ` +
+            `"${raw ?? ""}".`, {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} credits ${TRANSFER} --to <account identifier> 5\` moves five. ` +
+                `\`${BINARY_NAME} balance\` says how many this account can spend.`,
+        });
+    }
+    return n;
+}
+function needsTo() {
+    return new NmtsError(`\`--to\` is required: it names the account that receives.`, {
+        exitCode: 2,
+        nextStep: `It takes an account identifier — what \`${BINARY_NAME} whoami\` prints for that account, ` +
+            `and what the account screen lists for an AI account. It has to be an account of your own ` +
+            `family: your account, or one made under it.`,
+    });
+}
+function read(answer) {
+    const credits = isRecord(answer) ? answer["credits"] : null;
+    const from = isRecord(answer) ? answer["from_balance"] : null;
+    const to = isRecord(answer) ? answer["to_balance"] : null;
+    if (typeof credits !== "number" || typeof from !== "number" || typeof to !== "number") {
+        throw new NmtsError("The server moved the credits and described it in a shape this version cannot read.", {
+            exitCode: 1,
+            nextStep: `The move happened whatever this printed — \`${BINARY_NAME} balance\` reads the ledger. ` +
+                `Update this tool.`,
+        });
+    }
+    return { credits, from_balance: from, to_balance: to };
+}

package/dist/commands/delete-account.d.ts

@@ -0,0 +1,11 @@
+/** The sentence the browser's erase dialog asks for — the same words, so the act is one act. */
+export declare const CONFIRM_SENTENCE = "I UNDERSTAND THIS IS PERMANENT";
+export interface DeleteAccountOptions {
+    server?: string | undefined;
+    write?: ((line: string) => void) | undefined;
+    /** Injected in tests: answers the one typed line. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+    /** Under skip-permissions only: the tier gate's answer, given with a `--reason`. */
+    yes?: boolean;
+}
+export declare function deleteAccount(options?: DeleteAccountOptions): Promise<number>;