@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/extend-budget.js

@@ -0,0 +1,81 @@
+// What the wallet holds against what this extension costs — worked out BEFORE the agreement is
+// asked for and before anything is signed.
+//
+// ⛔ WHY IT IS BEFORE THE AGREEMENT. The agreement ladder exists so that a program cannot sign
+//    with somebody's wallet until a person has said so on this machine. Learning that the wallet
+//    is short is a read, and a person should not have to grant the one key that matters in order
+//    to be told there is nothing to spend. So a shortfall is refused first, with the two numbers,
+//    and the agreement is asked for only when the purchase can go through.
+//
+// ⛔ AN UNREAD BALANCE IS NOT A SHORTFALL. `wallet.ts` prints an unreadable balance as that and
+//    never as zero, and this file keeps the rule where it costs the most: a zero here would refuse
+//    a purchase the wallet can afford. An unread balance is SAID, and the run goes on — the chain
+//    refuses the signature itself if the money is not there, exactly as it did before this file.
+//
+// ⛔ THE FEE IS MEASURED, NOT ASSUMED. It is a dry run of the exact transaction that would be
+//    signed (`extend-chain.ts`), and when the chain cannot measure it the answer is `null` and the
+//    words say so. A plausible number in its place would be indistinguishable from a measured one.
+import { BINARY_NAME } from "./product.js";
+import { coinAmount } from "./wallet.js";
+function held(coin) {
+    return coin.read ? coin.baseUnits : null;
+}
+/** Read the wallet and measure the fee, then say whether the known numbers cover the purchase. */
+export async function readBudget(reads, input) {
+    const { address, objectIds, epochs, priceFrost } = input;
+    const [purse, feeMist] = await Promise.all([
+        reads.readWallet(address),
+        reads.estimateGas({ sender: address, objectIds, epochs }),
+    ]);
+    const walFrost = held(purse.wal);
+    const suiMist = held(purse.sui);
+    const unread = [];
+    if (!purse.wal.read)
+        unread.push(`WAL: ${purse.wal.why}`);
+    if (!purse.sui.read)
+        unread.push(`SUI: ${purse.sui.why}`);
+    let shortfall = null;
+    if (walFrost !== null && walFrost < priceFrost) {
+        shortfall =
+            `The wallet holds ${coinAmount(walFrost)} WAL and this extension costs ` +
+                `${coinAmount(priceFrost)} WAL.`;
+    }
+    else if (suiMist !== null && feeMist !== null && suiMist < feeMist) {
+        shortfall =
+            `The wallet holds ${coinAmount(suiMist)} SUI and the chain fee for this extension is ` +
+                `about ${coinAmount(feeMist)} SUI.`;
+    }
+    return { address, priceFrost, walFrost, suiMist, feeMist, unread, shortfall };
+}
+/** The budget as the machine-readable answer carries it. ⚠ Base units are strings — see `Facts`. */
+export function budgetFacts(b) {
+    return {
+        wallet: b.address,
+        walletWal: b.walFrost === null ? null : coinAmount(b.walFrost),
+        walletSui: b.suiMist === null ? null : coinAmount(b.suiMist),
+        feeMist: b.feeMist === null ? null : b.feeMist.toString(),
+        feeSui: b.feeMist === null ? null : coinAmount(b.feeMist),
+    };
+}
+/** The next step when the wallet is short: where to send what, said once. */
+export function shortfallNextStep(b) {
+    const coin = b.walFrost !== null && b.walFrost < b.priceFrost ? "WAL" : "SUI";
+    return (`Nothing was signed and nothing was charged. Send ${coin} to ${b.address} — ` +
+        `\`${BINARY_NAME} wallet\` shows the address and both balances — and run this again.`);
+}
+/** The fee and the wallet, for a person, after the price. */
+export function describeBudget(say, b) {
+    if (b.feeMist === null) {
+        say(`  The chain fee (SUI) could not be measured just now; it is charged with the signature.`);
+    }
+    else {
+        say(`  Chain fee about ${coinAmount(b.feeMist)} SUI, measured by a dry run just now — the amount ` +
+            `charged is fixed when the transaction executes.`);
+    }
+    const wal = b.walFrost === null ? "WAL not read" : `${coinAmount(b.walFrost)} WAL`;
+    const sui = b.suiMist === null ? "SUI not read" : `${coinAmount(b.suiMist)} SUI`;
+    say(`  Wallet ${b.address} holds ${wal} and ${sui}.`);
+    for (const why of b.unread) {
+        say(`  A balance could not be read — ${why}. That is not zero: the chain decides at signing.`);
+    }
+}

package/dist/extend-chain.d.ts

@@ -0,0 +1,43 @@
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import type { BlobLease, ExtendReads } from "./extend-plan.ts";
+/** How long one chain question gets. A read that stalls is a read that failed. */
+export declare const EXTEND_READ_TIMEOUT_MS = 20000;
+/**
+ * A Walrus-aware client for one network.
+ *
+ * ⛔ THE NETWORK NAME REACHES THE SDK AS WELL AS THE URL, exactly as it does for an upload. A
+ *    mirror pointed at the wrong chain would otherwise be discovered as a refusal from the storage
+ *    contract — after a transaction had been signed.
+ */
+export declare function walrusClient(network: string): ReturnType<typeof build>;
+declare function build(network: string): import("@mysten/sui/client").ClientWithExtensions<{
+    walrus: import("@mysten/walrus").WalrusClient;
+}, SuiJsonRpcClient>;
+/**
+ * One blob's lease, read from the Blob object itself.
+ *
+ * ⛔ NARROWED FROM `unknown`, NOT FROM THE SDK'S TYPE. `MoveStruct` is a three-way union whose
+ *    members do not all carry an index signature, so reading a field off it means asserting — and
+ *    an assertion compiles whether or not the check above it is right. What matters is the shape
+ *    on the wire, and the predicate in `guards.ts` is what carries that narrowing.
+ */
+export declare function readBlobLease(client: ReturnType<typeof build>, objectId: string): Promise<BlobLease>;
+/**
+ * The reads one `nmts extend` run needs, bound to one network.
+ *
+ * ⚠ THE WINDOW IS `null` RATHER THAN A GUESS when the network cannot be read, exactly as it is for
+ *   `nmts expiring`: the caller stops. An unread clock and a file in no danger look identical from
+ *   outside and are the opposite of each other.
+ */
+export declare function extendReads(network: string): ExtendReads;
+/**
+ * What a transaction actually costs in MIST: computation plus storage, less the rebate for storage
+ * it freed. Clamped at zero — a rebate can exceed the rest and the chain does not pay the sender.
+ * The browser app's `netGasFeeBaseUnits` is the same arithmetic.
+ */
+export declare function netGasFee(gasUsed: {
+    computationCost: string;
+    storageCost: string;
+    storageRebate: string;
+}): bigint;
+export {};

package/dist/extend-chain.js

@@ -2,7 +2,7 @@
 // what more epochs cost.
 //
 // ⛔ EVERYTHING HERE IS A READ. Nothing in this file builds a transaction, holds a key or moves an
-//    asset — the signature lives next door in `extend-sign.ts`, alone, so that the file which can
+//    asset — the signature lives next door in `wallet-sign.ts`, alone, so that the file which can
 //    spend is the smallest one in this tool. What is shared is the client builder below, because
 //    the two must talk to the same chain: a quote read from one network and a payment made on
 //    another is a payment for nothing.
@@ -21,7 +21,10 @@ import { NmtsError } from "./errors.js";
 import { epochClock } from "./expiry.js";
 import { isRecord } from "./guards.js";
 import { epochStartedMs } from "./walrus-write.js";
-import { suiRpcHost } from "./walrus.js";
+import { suiRpcTransport } from "./sui-rpc.js";
+import { readBalances, walCoinType } from "./wallet.js";
+import { chainReader } from "./wallet-chain.js";
+import { Transaction } from "@mysten/sui/transactions";
 /** How long one chain question gets. A read that stalls is a read that failed. */
 export const EXTEND_READ_TIMEOUT_MS = 20_000;
 /**
@@ -37,7 +40,7 @@ export function walrusClient(network) {
 function build(network) {
     return new SuiJsonRpcClient({
         network: network === "mainnet" ? "mainnet" : "testnet",
-        url: suiRpcHost(network),
+        transport: suiRpcTransport(network),
     }).$extend(walrus({}));
 }
 /** A number off the wire, whether it arrived as a number or as one of Sui's 64-bit strings. */
@@ -133,5 +136,39 @@ export function extendReads(network) {
             const costs = await Promise.all(leases.map((lease) => client.walrus.storageCost(lease.size, epochs)));
             return costs.reduce((sum, cost) => sum + BigInt(cost.storageCost), 0n);
         },
+        async readWallet(address) {
+            const net = network === "mainnet" ? "mainnet" : "testnet";
+            return readBalances(chainReader(net, address), walCoinType(net));
+        },
+        async estimateGas({ sender, objectIds, epochs }) {
+            // ⛔ THE SAME TRANSACTION `wallet-sign.ts` SIGNS — sender, de-duplicated ids, one fragment per
+            //    blob — so the fee measured is the fee of what would actually be approved. A different
+            //    shape here would print a number no transaction ever pays.
+            try {
+                const tx = new Transaction();
+                tx.setSender(sender);
+                for (const blobObjectId of [...new Set(objectIds)]) {
+                    tx.add(client.walrus.extendBlob({ blobObjectId, epochs }));
+                }
+                const bytes = await tx.build({ client });
+                const { effects } = await client.dryRunTransactionBlock({ transactionBlock: bytes });
+                if (effects.status.status !== "success")
+                    return null;
+                return netGasFee(effects.gasUsed);
+            }
+            catch {
+                // Not a number, and not zero: "could not measure" is a different fact from "free".
+                return null;
+            }
+        },
     };
 }
+/**
+ * What a transaction actually costs in MIST: computation plus storage, less the rebate for storage
+ * it freed. Clamped at zero — a rebate can exceed the rest and the chain does not pay the sender.
+ * The browser app's `netGasFeeBaseUnits` is the same arithmetic.
+ */
+export function netGasFee(gasUsed) {
+    const fee = BigInt(gasUsed.computationCost) + BigInt(gasUsed.storageCost) - BigInt(gasUsed.storageRebate);
+    return fee > 0n ? fee : 0n;
+}

package/dist/extend-plan.d.ts

@@ -0,0 +1,148 @@
+import type { EpochClock } from "./expiry.ts";
+import type { WalletBalances } from "./wallet.ts";
+/**
+ * The longest extension the NMTS server will RECORD, in epochs.
+ *
+ * ⛔ IT IS THE SERVER'S NUMBER AND IT IS CHECKED HERE ANYWAY, before the money moves. `api`'s
+ *    `MAX_EXTEND_EPOCHS` (routes/storage.rs) refuses to record anything longer — and the recording
+ *    happens AFTER the signature, so a length the chain would happily sell and the server would
+ *    refuse to write down produces the worst outcome this command has: storage that is really
+ *    extended, paid for, and a drive that goes on saying the old date.
+ *
+ * ⚠ A SECOND COPY, deliberately. The alternative is discovering the limit from a 400 after
+ *   spending. `check:cli-routes` holds the addresses level; nothing holds this number level, so it
+ *   is named with its origin and the refusal it produces says what the server would have said.
+ */
+export declare const MAX_RECORDABLE_EPOCHS = 104;
+/**
+ * How long an extension is when nobody says.
+ *
+ * The same term one credit buys on the upload rail (`upload-price.ts`, `UPLOAD_EPOCHS`) and the
+ * cheapest rung the browser's picker offers. ⚠ It is a number of EPOCHS, not of days: two epochs
+ * is two days on testnet and twenty-eight on mainnet, so every surface that prints it prints the
+ * days beside it, read from the network's own clock.
+ */
+export declare const DEFAULT_EXTEND_EPOCHS = 2;
+/** One blob an extension would name, as the NMTS server describes it. */
+export interface ExtendTarget {
+    /** The Sui object id of the blob — the argument the extend transaction takes. */
+    objectId: string;
+    /**
+     * How many of this account's files ride on this blob, trash included.
+     *
+     * 1 for a file with a blob to itself; more for a quilt, where ONE payment extends the whole
+     * cohort. It is printed rather than used: somebody paying for one file deserves to know the
+     * payment reaches five.
+     */
+    sharedItems: number;
+}
+/** What `GET /v1/items/{id}/extend-preview` says, narrowed rather than trusted. */
+export interface ExtendPreview {
+    targets: ExtendTarget[];
+    /** Parts on treasury-paid storage — not this account's to extend. */
+    treasuryParts: number;
+    /** Parts with no recorded Sui object id (pre-0010): nothing to name on-chain. */
+    untrackedParts: number;
+}
+/**
+ * The preview, or a refusal.
+ *
+ * ⛔ A TARGET THIS CANNOT READ IS A REFUSAL, NOT A TARGET TO SKIP. Skipping one would produce a
+ *    transaction that extends some of a file's blobs and leaves the others to expire — and the
+ *    file is unreadable if any single one of them goes, so the money would buy nothing.
+ */
+export declare function asExtendPreview(value: unknown): ExtendPreview;
+/** One blob's lease, as the chain currently has it. */
+export interface BlobLease {
+    objectId: string;
+    /** Unencoded size in bytes — what the storage price is computed from. */
+    size: number;
+    /** The epoch the lease runs out at. THE authoritative expiry. */
+    endEpoch: number;
+}
+/**
+ * When the file actually runs out: the SOONEST end epoch across the blobs it rides on.
+ *
+ * ⛔ SOONEST, NOT FURTHEST. One expired blob is enough to make the file unreadable, so the file's
+ *    deadline is the first of them. Null when there is no lease to read, which is a real state
+ *    (every part on treasury-paid storage) and is never drawn as "now".
+ */
+export declare function soonestEnd(leases: readonly BlobLease[]): number | null;
+/**
+ * The largest number of epochs these leases can ALL be extended by.
+ *
+ * The ceiling is per-blob — a lease may not end more than `maxAhead` epochs past the current one —
+ * so the blob that already reaches furthest into the future is the binding one. 0 is a real
+ * answer ("already paid as far ahead as the network allows"), not a failure.
+ */
+export declare function headroom(leases: readonly BlobLease[], current: number, maxAhead: number): number;
+/**
+ * How many epochs to buy: what was asked for, or the default, checked against both ceilings.
+ *
+ * ⛔ IT REFUSES RATHER THAN CLAMPS. Quietly buying fewer epochs than somebody asked for spends
+ *    their money on something they did not ask for, and quietly buying more spends more of it.
+ *    Each refusal names the ceiling that produced it, because the two have different remedies:
+ *    the network's is a wait, the server's is a shorter extension repeated later.
+ */
+export declare function chooseEpochs(asked: string | number | undefined, available: number): number;
+/** Where the storage network's clock stands, and how far ahead it will sell. */
+export interface ExtendWindow {
+    clock: EpochClock;
+    /**
+     * How many epochs past the current one a lease may reach — the protocol's own ceiling, read from
+     * the chain. ⛔ Never a constant: too high and the last length offered is refused on-chain after
+     * the transaction is signed; too low and this tool refuses to buy what the network would sell.
+     */
+    maxAhead: number;
+}
+/**
+ * The chain, as this command needs it to READ.
+ *
+ * ⛔ A SEAM, NOT AN OPTION. No flag reaches it and nothing on a command line can supply one. It
+ *    exists because the alternative is a test that talks to a live storage network — which cannot
+ *    run offline, answers differently every fortnight, and can never be asked to be at its own
+ *    ceiling on demand, which is most of what this command has to get right.
+ */
+export interface ExtendReads {
+    /** The clock and the ceiling, or null when the network could not be read at all. */
+    readWindow(): Promise<ExtendWindow | null>;
+    /** Each blob's own lease, in the order asked for. Rejects rather than guessing. */
+    readLeases(objectIds: readonly string[]): Promise<BlobLease[]>;
+    /** What extending all of them by `epochs` costs, in FROST (WAL base units). */
+    quote(leases: readonly BlobLease[], epochs: number): Promise<bigint>;
+    /**
+     * What the wallet that would sign holds right now, each coin answering for itself.
+     *
+     * ⛔ A BALANCE THAT COULD NOT BE READ COMES BACK AS THAT, never as zero — `wallet.ts` states the
+     *    rule and this is where it matters most: a zero here would refuse a purchase the wallet can
+     *    afford, and an unread balance drawn as enough would sign a transaction that fails.
+     */
+    readWallet(address: string): Promise<WalletBalances>;
+    /**
+     * The chain fee of THIS extension in MIST (SUI base units), measured by dry-running the exact
+     * transaction that would be signed — or `null` when the chain could not measure it (an empty
+     * wallet has no gas coin to dry-run with; a node can be down). ⛔ NEVER ZERO FOR "UNKNOWN".
+     */
+    estimateGas(input: {
+        sender: string;
+        objectIds: readonly string[];
+        epochs: number;
+    }): Promise<bigint | null>;
+}
+/**
+ * The one thing in this tool that signs.
+ *
+ * ⛔ IT IS A SEPARATE SEAM FROM THE READS ON PURPOSE. A test can then prove what matters most
+ *    about this command — that `--dry-run` and a missing agreement both stop BEFORE this function
+ *    is reached — by handing it one that records being called and fails the test if it ever is.
+ *    Folded into `ExtendReads`, "did it sign" would be a question about which method ran.
+ *
+ * Returns the transaction digest, which is what the server records as the replay guard.
+ */
+export type SignExtension = (input: {
+    network: string;
+    /** ⛔ The NMTS key. It never leaves this machine: it derives the wallet and nothing else. */
+    code: string;
+    objectIds: readonly string[];
+    epochs: number;
+}) => Promise<string>;

package/dist/extend-plan.js

@@ -3,7 +3,7 @@
 // ⛔ NO NETWORK, NO SDK, NO KEY. Everything here is arithmetic over numbers somebody else read, so
 //    `node --test` can drive every branch — including the ones a live storage network only reaches
 //    by being at its ceiling, or by having sold a lease that already ran out. The reads live in
-//    `extend-chain.ts`, the signature in `extend-sign.ts`, and neither can be reached from here.
+//    `extend-chain.ts`, the signature in `wallet-sign.ts`, and neither can be reached from here.
 //
 // ⛔ THE CHAIN IS THE AUTHORITY ON WHEN A LEASE ENDS, not the server's `expiry_epoch`. That column
 //    is client-reported and advisory — it is what `nmts expiring` ranks by, because ranking is all

package/dist/gate.d.ts

@@ -0,0 +1,18 @@
+import { type Autonomy } from "./autonomy.ts";
+import type { ParsedArgs } from "./args.ts";
+import { CONSENTS } from "./consent.ts";
+import { type ActId } from "./risk.ts";
+export interface GateIo {
+    write?: ((line: string) => void) | undefined;
+    /** Injected in tests: answers the y/N. Its presence stands in for a terminal. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+    now?: (() => Date) | undefined;
+}
+export interface Passage {
+    /** The command must still get a yes in its own words — a review and --yes, a typed sentence. */
+    ask: boolean;
+    mode: Autonomy;
+}
+/** Whether the unlock behind an act is open right now. */
+export declare function unlocked(key: keyof typeof CONSENTS, now: Date): Promise<boolean>;
+export declare function gate(act: ActId, args: ParsedArgs, io?: GateIo): Promise<Passage>;

package/dist/gate.js

@@ -0,0 +1,100 @@
+// The one place a tier meets a mode: refuse, ask, or wave through.
+//
+// ⛔ EVERY COMMAND PASSES HERE BEFORE IT RUNS (`main.ts`), with the act `risk.ts` names for its
+//    command line. What it decides, in this order and nowhere else:
+//      1. none runs.
+//      2. skip-permissions runs everything — an ultra-high act with a written --reason, kept in the
+//         run log.
+//      3. ultra-high: a person at the terminal (mode default) may go on to the command's own typed
+//         sentence; an auto mode is refused, unlocked or not.
+//      4. high sits behind an unlock. Locked is refused with the one command that unlocks it, which
+//         only a person at a terminal can run.
+//      5. A yes is needed for high in every mode, and for low and medium in default. An act that
+//         asks itself is told so and asks in its own words; anything else is asked here — y/N at a
+//         terminal, or exit 5 with the sentence an agent shows the person, answered by --yes.
+//
+// ⛔ WHAT `--yes` PROVES: nothing. No command-line tool can tell whether a person or a program typed
+//    it. The instructions say an agent passes it only after the person said yes; this file makes the
+//    stop impossible to miss and the question the same every time. Saying more would be a claim.
+import { currentMode } from "./autonomy.js";
+import { CONSENTS, isGranted } from "./consent.js";
+import { NmtsError } from "./errors.js";
+import { BINARY_NAME } from "./product.js";
+import { promptLine, stdinIsATerminal } from "./prompt.js";
+import { ACTS } from "./risk.js";
+/** Whether the unlock behind an act is open right now. */
+export async function unlocked(key, now) {
+    if (key === "wallet") {
+        // ⚠ Loaded here, not at the top: the wallet module reaches the chain SDK, and this file
+        //    runs on every command (`check:cli-startup`).
+        const { readWalletGrant, walletGrantState } = await import("./wallet-grant.js");
+        return walletGrantState(readWalletGrant(), now) === "active";
+    }
+    return isGranted(key);
+}
+export async function gate(act, args, io = {}) {
+    const a = ACTS[act];
+    const mode = currentMode();
+    const now = io.now ?? (() => new Date());
+    if (a.tier === "none")
+        return { ask: false, mode };
+    if (mode === "skip-permissions") {
+        if (a.tier === "ultra-high" && (args.reason === undefined || args.reason.trim() === "")) {
+            throw new NmtsError(`${a.what} This is permanent, and skip-permissions still wants the reason written down.`, {
+                exitCode: 5,
+                nextStep: `Think it through first — is this really what the person would want done right now, and ` +
+                    `why? Then run the same command with --reason "<that, in a sentence>". The reason is kept ` +
+                    `in this machine's run log.`,
+            });
+        }
+        return { ask: false, mode };
+    }
+    if (a.tier === "ultra-high") {
+        if (mode !== "default") {
+            throw new NmtsError(`${a.what} Not from an agent, in any auto mode.`, {
+                exitCode: 5,
+                nextStep: `A person does this at the terminal (mode default). Tell them what you wanted and stop; ` +
+                    `there is no unlock for it.`,
+            });
+        }
+        return { ask: true, mode };
+    }
+    if ("lock" in a && !(await unlocked(a.lock, now()))) {
+        const c = CONSENTS[a.lock];
+        throw new NmtsError(`${a.what} This is locked until a person unlocks it on this machine.`, {
+            exitCode: 5,
+            nextStep: [
+                c.risk,
+                "",
+                c.limit,
+                "",
+                `To unlock, at a terminal, once:  ${BINARY_NAME} unlock ${a.lock}`,
+                `To see what is unlocked:         ${BINARY_NAME} unlock`,
+                "",
+                `⛔ If a program is reading this on somebody's behalf: show it to them and let them decide.`,
+                `   Do not run the unlock command yourself.`,
+            ].join("\n"),
+        });
+    }
+    const needsYes = a.tier === "high" ? !("standing" in a) : mode === "default";
+    if (!needsYes)
+        return { ask: false, mode };
+    if ("asksItself" in a)
+        return { ask: !args.yes, mode };
+    if (args.yes)
+        return { ask: false, mode };
+    const say = io.write ?? ((line) => process.stderr.write(`${line}\n`));
+    if (io.readLine !== undefined || stdinIsATerminal()) {
+        const ask = io.readLine ?? promptLine;
+        say(a.what ?? act);
+        const answer = (await ask(`Go ahead? [y/N] `)).trim();
+        if (answer === "y" || answer === "Y")
+            return { ask: false, mode };
+        throw new NmtsError(`Nothing was done.`, { exitCode: 1, nextStep: null });
+    }
+    throw new NmtsError(a.what ?? act, {
+        exitCode: 5,
+        nextStep: `This needs the person's yes. Tell them, in plain words, what this does and what it costs; ` +
+            `if they say yes, run the same command with --yes. Nothing was done.`,
+    });
+}

package/dist/guards.d.ts

@@ -0,0 +1,2 @@
+/** True for a plain JSON object: not null, not an array. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/help.d.ts

@@ -0,0 +1,20 @@
+export declare function helpText(version: string): string;
+/**
+ * `nmts help <command>`: the document for one command, from `docs/commands/`, or the list of
+ * documents when the name matches none.
+ *
+ * ⚠ The directory is read only here, so `--help` itself pays nothing for it (`check:cli-startup`).
+ *   Each document names the commands it covers on its `Commands:` line; that line is the index.
+ */
+export declare function helpFor(topic: string): Promise<{
+    text: string;
+    found: boolean;
+}>;
+/**
+ * What `--help`, a bare run, `help`, and `help <command>` print, and the exit code.
+ * ⛔ `support` has help of its own: it is READ before deciding, not scanned for an option name.
+ */
+export declare function printHelp(args: {
+    command: string | null;
+    operands: readonly string[];
+}, write: (text: string) => void): Promise<number>;