@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/commands/losses.js

@@ -0,0 +1,180 @@
+// `nmts losses` — the storage bought with this account's credits that the chain no longer knows.
+//
+// ⛔ IT REPORTS, IT DOES NOT REPAIR. Once the chain has stopped serving a storage object nothing
+//    this tool or the server does brings the bytes back, and the row is the record of a purchase
+//    that produced nothing. What the command is for is that somebody finds out from us rather
+//    than from a download that stops coming back.
+//
+// ⛔ THERE IS NO FILE NAME AND THERE CANNOT BE ONE. The answer names on-chain STORAGE OBJECTS; the
+//    pairing that would resolve one to a file is server-side, has no route, and the drive's own
+//    list is sealed with a key the server never sees. Printing a guessed name would be worse than
+//    printing none, so the line prints the public object id and says why that is all there is.
+//
+// ⚠ AN EMPTY LIST IS NOT "NOTHING IS GONE". The daily round samples fifty objects at random, so an
+//   object nobody has drawn yet has not been asked about. The route's own note says a client must
+//   not print the second sentence, and the wording here does not.
+//
+// ⛔ THE THREE ACTS ARE ONE COMMAND BECAUSE THEY ARE ONE SUBJECT, and exactly one of them runs per
+//    call. Re-checking asks the chain the same question the daily round asks, now. Dismissing is a
+//    person saying they have read the line — see the mode check below, which is the reason this
+//    command imports the autonomy module at all.
+import { request, ServerError } from "../api.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+/**
+ * The refusal for an id this account holds no line for.
+ *
+ * ⛔ ONE TEXT FOR BOTH ARMS. The server answers 404 to a re-check and to a dismiss for the same
+ *    reason — the account does not hold that loss — and two wordings for one cause is how a caller
+ *    ends up branching on which command it happened to run.
+ */
+function noSuchLine(id) {
+    return new NmtsError(`NMTS holds no loss line for ${id} on this account.`, {
+        exitCode: 4,
+        nextStep: `Run \`${BINARY_NAME} losses\` to see the lines that exist.`,
+    });
+}
+/** `unknown` off the wire, read as the rows the route declares. */
+function rowsOf(answer) {
+    const list = isRecord(answer) ? answer["losses"] : undefined;
+    if (!Array.isArray(list)) {
+        throw new NmtsError(`The server's answer did not carry a list of losses.`, {
+            exitCode: 1,
+            nextStep: `Nothing was changed. Report it rather than retrying — the shape, not the network, is wrong.`,
+        });
+    }
+    return list.map((row) => {
+        const id = isRecord(row) ? row["blob_object_id"] : undefined;
+        const seen = isRecord(row) ? row["first_seen"] : undefined;
+        const notice = isRecord(row) ? row["required_notice"] : undefined;
+        const restricted = isRecord(row) ? row["restricted"] : undefined;
+        if (typeof id !== "string" || typeof seen !== "string") {
+            throw new NmtsError(`The server listed a loss this version cannot read.`, {
+                exitCode: 1,
+                nextStep: `Nothing was changed. A newer version of this tool may understand it.`,
+            });
+        }
+        // ⚠ A flag that did not arrive as a boolean is read as false, and that is the only place here
+        //   where a missing field is filled in: both mean "this line carries no extra sentence", and
+        //   the sentences they add are additions to a line that is already correct without them.
+        return {
+            blob_object_id: id,
+            first_seen: seen,
+            required_notice: notice === true,
+            restricted: restricted === true,
+        };
+    });
+}
+/** The UTC day of an RFC 3339 instant, `YYYY-MM-DD`. */
+function utcDay(instant) {
+    const at = new Date(instant);
+    if (Number.isNaN(at.getTime())) {
+        throw new NmtsError(`The server dated a loss with something that is not a time.`, {
+            exitCode: 1,
+            nextStep: `Nothing was changed. Report it rather than retrying.`,
+        });
+    }
+    return at.toISOString().slice(0, 10);
+}
+export async function losses(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (options.recheck !== undefined && options.dismiss !== undefined) {
+        throw new NmtsError(`--recheck and --dismiss are two different acts, and one run does one.`, {
+            exitCode: 2,
+            nextStep: `Run one, read what it says, then run the other.`,
+        });
+    }
+    const session = await openSession({ server: options.server, network: options.network });
+    if (options.recheck !== undefined) {
+        const id = options.recheck;
+        let answer;
+        try {
+            answer = await request(session.server, "/v1/storage-loss/recheck", {
+                token: session.apiKey,
+                method: "POST",
+                body: { blob_object_id: id },
+            });
+        }
+        catch (error) {
+            if (error instanceof ServerError && error.status === 404)
+                throw noSuchLine(id);
+            throw error;
+        }
+        const result = isRecord(answer) ? answer["result"] : undefined;
+        if (result !== "found" && result !== "still_missing" && result !== "unread") {
+            throw new NmtsError(`The server answered the re-check with something this version cannot read.`, {
+                exitCode: 1,
+                nextStep: `Nothing was decided about the storage. A newer version of this tool may understand it.`,
+            });
+        }
+        const said = result;
+        if (options.json === true) {
+            say(JSON.stringify({ blob_object_id: id, result: said }));
+            return 0;
+        }
+        if (said === "found")
+            say(`The chain knows ${id} again. Its line came off.`);
+        else if (said === "still_missing")
+            say(`The chain still does not know ${id}. The line stays.`);
+        else
+            say(`The chain could not be read just now. Nothing changed.`);
+        return 0;
+    }
+    if (options.dismiss !== undefined) {
+        const id = options.dismiss;
+        try {
+            await request(session.server, `/v1/storage-loss/${encodeURIComponent(id)}`, {
+                token: session.apiKey,
+                method: "DELETE",
+            });
+        }
+        catch (error) {
+            if (error instanceof ServerError && error.status === 404)
+                throw noSuchLine(id);
+            throw error;
+        }
+        if (options.json === true) {
+            say(JSON.stringify({ blob_object_id: id, dismissed: true }));
+            return 0;
+        }
+        say(`Took the line for ${id} off. The incident stays in a record that names nobody; if the same ` +
+            `storage is found and lost again, it is shown again.`);
+        return 0;
+    }
+    const answer = await request(session.server, "/v1/storage-loss", { token: session.apiKey });
+    if (options.json === true) {
+        // ⛔ THE SERVER'S OBJECT, UNCHANGED. A reader of this arm is reading the route, and a shape
+        //    rewritten here would be a second wire to keep in step with the first.
+        say(JSON.stringify(answer));
+        return 0;
+    }
+    const rows = rowsOf(answer);
+    if (rows.length === 0) {
+        say(`The daily check has found nothing missing for this account.`);
+        say(`It samples the storage NMTS bought with your credits once a day and asks the chain whether ` +
+            `it is still there.`);
+        return 0;
+    }
+    say(rows.length === 1
+        ? `The chain no longer knows one storage object your credits paid for. That is what the ` +
+            `check measured; it did not try the download. The file may no longer come back, and ` +
+            `NMTS cannot restore it.`
+        : `The chain no longer knows ${rows.length} storage objects your credits paid for. That is ` +
+            `what the check measured; it did not try the download. Those files may no longer come ` +
+            `back, and NMTS cannot restore them.`);
+    say(``);
+    for (const row of rows) {
+        say(`${row.blob_object_id}  first missed ${utcDay(row.first_seen)}` +
+            (row.required_notice ? ` · shown because the law requires it` : ``) +
+            (row.restricted ? ` · kept but not used while you contest it` : ``));
+    }
+    say(``);
+    say(`The date is when a check first could not find it, not when the storage went. There is no ` +
+        `file name: the server cannot pair the object with a file, and NMTS cannot see inside files.`);
+    say(`\`${BINARY_NAME} losses --recheck <id>\` asks the chain again now. \`${BINARY_NAME} losses ` +
+        `--dismiss <id>\` takes a line off once you have read it; the incident stays in a record ` +
+        `that names nobody.`);
+    return 0;
+}

package/dist/commands/ls.d.ts

@@ -0,0 +1,23 @@
+export interface LsOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Machine-readable output. For an agent this is the shape to parse; the table is for a person. */
+    json?: boolean;
+    /** Include entries that are in the trash. */
+    all?: boolean;
+    /**
+     * Keep only files whose name contains this text, case-insensitively.
+     *
+     * Taken as plain text rather than a parsed key so this command owns the refusal for a query that
+     * cannot mean anything — see `list-view-find.ts` for what a query does and does not match.
+     */
+    find?: string | undefined;
+    /** `name`, `size` or `date`. Absent = the path order this command has always printed. */
+    sort?: string | undefined;
+    /** Reverse whichever order is in effect. */
+    desc?: boolean;
+    write?: (line: string) => void;
+    /** The instant the trash countdown is measured against. Passed in so one listing means one moment. */
+    now?: number;
+}
+export declare function ls(options?: LsOptions): Promise<number>;

package/dist/commands/marks-dispatch.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "../args.ts";
+export declare function runMarks(command: string, args: ParsedArgs): Promise<number>;

package/dist/commands/marks-dispatch.js

@@ -0,0 +1,51 @@
+// The six mark verbs, dispatched here rather than in `main.ts`.
+//
+// ⛔ WHY A SECOND SWITCH. `main.ts` is measured (`check:size`) and had no room for `nmts support`;
+//    these six cases were the one contiguous block that shares a file, an option shape and a
+//    reason to be read together — `label --rename` and `unlabel --all` are sweeps over the whole
+//    account wearing the verbs of a per-file mark, and the guard that keeps them from being
+//    reached by accident is the comment below, which moved with them.
+export async function runMarks(command, args) {
+    switch (command) {
+        case "star": {
+            const { star } = await import("./marks.js");
+            return await star(args.operands, { server: args.server, network: args.network, json: args.json });
+        }
+        case "unstar": {
+            const { unstar } = await import("./marks.js");
+            return await unstar(args.operands, { server: args.server, network: args.network, json: args.json });
+        }
+        case "pin": {
+            const { pin } = await import("./marks.js");
+            return await pin(args.operands, { server: args.server, network: args.network, json: args.json });
+        }
+        case "unpin": {
+            const { unpin } = await import("./marks.js");
+            return await unpin(args.operands, { server: args.server, network: args.network, json: args.json });
+        }
+        case "label": {
+            const options = { server: args.server, network: args.network, json: args.json };
+            // ⛔ `--rename` IS A DIFFERENT COMMAND WEARING THE SAME VERB, and it is dispatched here so
+            //    that the label sweep cannot be reached by accident: `label <name> <files>` puts a mark
+            //    on the files it names, and `label --rename <old> <new>` touches every file in the
+            //    account. One takes paths and the other refuses them.
+            if (args.rename !== undefined) {
+                const { labelRename } = await import("./marks.js");
+                return await labelRename(args.rename, args.operands[0], options);
+            }
+            const { label } = await import("./marks.js");
+            return await label(args.operands[0], args.operands.slice(1), options);
+        }
+        case "unlabel": {
+            const options = { server: args.server, network: args.network, json: args.json };
+            if (args.all) {
+                const { unlabelAll } = await import("./marks.js");
+                return await unlabelAll(args.operands[0], options);
+            }
+            const { unlabel } = await import("./marks.js");
+            return await unlabel(args.operands[0], args.operands.slice(1), options);
+        }
+        default:
+            throw new Error(`not a mark verb: ${command}`);
+    }
+}

package/dist/commands/marks.d.ts

@@ -0,0 +1,46 @@
+export interface MarkOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+/** Star one or more files: they show in the drive's favourites as well as in their own folder. */
+export declare function star(paths: readonly string[], options?: MarkOptions): Promise<number>;
+/** Take the star off. */
+export declare function unstar(paths: readonly string[], options?: MarkOptions): Promise<number>;
+/** Hold one or more files at the top of the folder they are in. */
+export declare function pin(paths: readonly string[], options?: MarkOptions): Promise<number>;
+/** Let them fall back into the ordinary order. */
+export declare function unpin(paths: readonly string[], options?: MarkOptions): Promise<number>;
+/**
+ * Put one label on one or more files.
+ *
+ * ⚠ A LABEL EXISTS EXACTLY AS LONG AS SOME FILE WEARS IT. There is no registry to add it to and
+ *   none to clean up: two devices inventing the same label converge on it instead of colliding,
+ *   and the last `unlabel` is what makes it stop existing.
+ */
+export declare function label(name: string | undefined, paths: readonly string[], options?: MarkOptions): Promise<number>;
+/** Take one label off one or more files. */
+export declare function unlabel(name: string | undefined, paths: readonly string[], options?: MarkOptions): Promise<number>;
+/**
+ * `nmts label --rename <old> <new>` — one label's name, changed on every file that wears it.
+ *
+ * ⛔ IT IS A SWEEP, AND IT NAMES NO PATHS. A label has no registry to rename it in (see `label`
+ *    above): it exists on the files, so renaming it means touching every file that wears it. That
+ *    is why this is a different entry point rather than a switch on `label` — one takes the files
+ *    it is given, and this one takes whatever the account holds.
+ *
+ * ⛔ RENAMING ONTO A LABEL THAT ALREADY EXISTS MERGES THE TWO. A file wearing both would otherwise
+ *    end up wearing one label twice, which shows a doubled row and counts the file twice. The
+ *    intent does that; it is written down here because it is the behaviour somebody has to be able
+ *    to predict before typing this.
+ */
+export declare function labelRename(from: string | undefined, to: string | undefined, options?: MarkOptions): Promise<number>;
+/**
+ * `nmts unlabel <name> --all` — one label, taken off every file that wears it.
+ *
+ * ⛔ THIS IS WHAT MAKES A LABEL STOP EXISTING, and it is the whole reason the sweep is worth a
+ *    flag: a label with no registry can only be removed by finding every file wearing it, and
+ *    doing that by hand is how one file keeps a label nobody can see any more.
+ */
+export declare function unlabelAll(name: string | undefined, options?: MarkOptions): Promise<number>;

package/dist/commands/marks.js

@@ -50,6 +50,86 @@ export async function label(name, paths, options = {}) {
 export async function unlabel(name, paths, options = {}) {
     return run("unlabel", paths, name, options);
 }
+/**
+ * `nmts label --rename <old> <new>` — one label's name, changed on every file that wears it.
+ *
+ * ⛔ IT IS A SWEEP, AND IT NAMES NO PATHS. A label has no registry to rename it in (see `label`
+ *    above): it exists on the files, so renaming it means touching every file that wears it. That
+ *    is why this is a different entry point rather than a switch on `label` — one takes the files
+ *    it is given, and this one takes whatever the account holds.
+ *
+ * ⛔ RENAMING ONTO A LABEL THAT ALREADY EXISTS MERGES THE TWO. A file wearing both would otherwise
+ *    end up wearing one label twice, which shows a doubled row and counts the file twice. The
+ *    intent does that; it is written down here because it is the behaviour somebody has to be able
+ *    to predict before typing this.
+ */
+export async function labelRename(from, to, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    // ⚠ Trimmed here as well as inside the intent, so the text compared against what a file wears
+    //   is the same text that gets stored. `  work  ` and `work` are one label.
+    const old = from === undefined ? "" : from.trim();
+    const fresh = to === undefined ? "" : to.trim();
+    if (old === "" || fresh === "") {
+        throw new NmtsError("`nmts label --rename` needs the label to rename, then its new name.", {
+            exitCode: 2,
+            nextStep: "For example: nmts label --rename work archive",
+        });
+    }
+    const session = await openSession(options);
+    const at = Date.now();
+    let files = 0;
+    // ⛔ COUNTED INSIDE THE ATTEMPT, like every other question about the list. On a lost
+    //    compare-and-swap the list is read again, and how many files wear a label is a fact about
+    //    the version that was read — another device may have added one since.
+    await applyToList(session, (now) => {
+        files = now.filter((e) => (e.labels ?? []).includes(old)).length;
+        return { op: "labelRename", from: old, to: fresh, at };
+    });
+    if (options.json) {
+        say(JSON.stringify({ label: old, renamed_to: fresh, files }));
+        return 0;
+    }
+    if (files === 0) {
+        say(`No file carries the label "${old}".`);
+        return 0;
+    }
+    say(`Renamed the label "${old}" to "${fresh}" on ${files} ${files === 1 ? "file" : "files"}.`);
+    return 0;
+}
+/**
+ * `nmts unlabel <name> --all` — one label, taken off every file that wears it.
+ *
+ * ⛔ THIS IS WHAT MAKES A LABEL STOP EXISTING, and it is the whole reason the sweep is worth a
+ *    flag: a label with no registry can only be removed by finding every file wearing it, and
+ *    doing that by hand is how one file keeps a label nobody can see any more.
+ */
+export async function unlabelAll(name, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const text = name === undefined ? "" : name.trim();
+    if (text === "") {
+        throw new NmtsError("`nmts unlabel --all` needs the label to take off.", {
+            exitCode: 2,
+            nextStep: "For example: nmts unlabel work --all",
+        });
+    }
+    const session = await openSession(options);
+    const at = Date.now();
+    let files = 0;
+    await applyToList(session, (now) => {
+        files = now.filter((e) => (e.labels ?? []).includes(text)).length;
+        return { op: "labelDelete", label: text, at };
+    });
+    if (options.json) {
+        say(JSON.stringify({ label: text, removed_from: files }));
+        return 0;
+    }
+    if (files === 0) {
+        say(`No file carries the label "${text}".`);
+        return 0;
+    }
+    say(`Took the label "${text}" off ${files} ${files === 1 ? "file" : "files"}.`);
+    return 0;
+}
 async function run(verb, paths, name, options) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const on = !verb.startsWith("un");

package/dist/commands/mcp.d.ts

@@ -0,0 +1,24 @@
+import { destinationFor } from "../safe-path.ts";
+export { destinationFor };
+export interface McpOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Where fetched files land. Defaults to the working directory the person started this in. */
+    out?: string | undefined;
+    /** Overridable so a test can drive both ends without pipes. */
+    input?: NodeJS.ReadableStream;
+    output?: (line: string) => void;
+    note?: (line: string) => void;
+}
+/**
+ * Every schema this program actually serves, for the gate that checks they can be enforced.
+ *
+ * ⛔ IT BUILDS THE REAL TABLE rather than restating it. A hand-kept list of tool names in a test is
+ *    a list that goes stale the day somebody adds a tool, and the failure is a tool nobody checks.
+ *    The context here is a placeholder — no tool reads it while its schema is being looked at.
+ */
+export declare function mcpToolSchemas(): {
+    name: string;
+    inputSchema: Record<string, unknown>;
+}[];
+export declare function mcp(options?: McpOptions): Promise<number>;

package/dist/commands/mcp.js

@@ -35,16 +35,21 @@ import { requireAccountCode } from "../code-access.js";
 import { API_KEY_ENV_VAR, CODE_ENV_VAR, readCredentialsFile, resolveApiKey } from "../credentials.js";
 import { NmtsError } from "../errors.js";
 import { serve } from "../mcp.js";
+import { describeSighting } from "../agent-host.js";
 // ⚠ Re-exported so callers that knew it here keep working; the rule itself lives one level up now.
 import { destinationFor } from "../safe-path.js";
 export { destinationFor };
 import { BINARY_NAME, PRODUCT_NAME, VERSION } from "../product.js";
 import { resolveNetwork } from "../network.js";
 import { resolveServer } from "../server.js";
+import { creditTools } from "../mcp-tools/credits.js";
 import { fileTools } from "../mcp-tools/files.js";
 import { organiseTools } from "../mcp-tools/organise.js";
 import { readTools } from "../mcp-tools/reads.js";
 import { shareTools } from "../mcp-tools/share.js";
+import { withTiers } from "../mcp-tools/tiers.js";
+import { supportTools } from "../mcp-tools/support.js";
+import { currentMode } from "../autonomy.js";
 /**
  * Which account this server is holding, answered without asking anything.
  *
@@ -56,7 +61,7 @@ import { shareTools } from "../mcp-tools/share.js";
 function whoami(ctx) {
     return {
         name: "nmts_whoami",
-        description: "Which NMTS account this machine holds the code for. Derived here, offline: it says " +
+        description: "Which NMTS account this machine holds the NMTS key for. Derived here, offline: it says " +
             "nothing about whether that account exists on the server or has credits.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
         async run() {
@@ -77,8 +82,22 @@ function whoami(ctx) {
  *    The context here is a placeholder — no tool reads it while its schema is being looked at.
  */
 export function mcpToolSchemas() {
-    const ctx = { server: "https://example.invalid", network: "testnet", outDir: "/", accountId: "-" };
-    const all = [whoami(ctx), ...readTools(ctx), ...fileTools(ctx), ...organiseTools(ctx), ...shareTools(ctx)];
+    const ctx = {
+        server: "https://example.invalid",
+        network: "testnet",
+        outDir: "/",
+        accountId: "-",
+        asker: () => null,
+    };
+    const all = [
+        whoami(ctx),
+        ...readTools(ctx),
+        ...fileTools(ctx),
+        ...organiseTools(ctx),
+        ...creditTools(ctx),
+        ...shareTools(ctx),
+        ...supportTools(ctx),
+    ];
     return all.map((t) => ({ name: t.name, inputSchema: t.inputSchema }));
 }
 export async function mcp(options = {}) {
@@ -109,7 +128,21 @@ export async function mcp(options = {}) {
     if (!statSync(outDir).isDirectory()) {
         throw new NmtsError(`${outDir} is not a directory.`, { exitCode: 2 });
     }
-    const ctx = { server, network, outDir, accountId: identity.accountId };
+    /**
+     * How this session asks the person a question, filled in when the client says whether it can.
+     *
+     * ⛔ IT STARTS AS "NO WAY TO ASK" AND THAT IS THE RIGHT STARTING POINT. A tool call cannot
+     *    arrive before `initialize`, so this is only ever read after the client has spoken; if a
+     *    client somehow skipped that, the tools that need an answer refuse rather than assume one.
+     */
+    let asker = null;
+    const ctx = {
+        server,
+        network,
+        outDir,
+        accountId: identity.accountId,
+        asker: () => asker,
+    };
     /**
      * The whole surface, in one place.
      *
@@ -123,8 +156,17 @@ export async function mcp(options = {}) {
         ...readTools(ctx),
         ...fileTools(ctx),
         ...organiseTools(ctx),
+        ...creditTools(ctx),
         ...shareTools(ctx),
+        // ⛔ LAST, AND NOT BECAUSE IT MATTERS LEAST. The order is the order a client shows them in,
+        //    and writing to the developer is the one thing here that is not about this account's
+        //    files at all — a model scanning the list should meet it after everything the work
+        //    itself needs.
+        ...supportTools(ctx),
     ];
+    // ⛔ THE TIER GATE, AROUND EVERY TOOL (`mcp-tools/tiers.ts`): the same table the command line
+    //    reads, asked over elicitation instead of a terminal.
+    const gated = withTiers(tools, ctx.asker);
     // ⛔ To stderr, deliberately. A person starting this by hand should see what it is; a client
     //    reading stdout must see nothing but protocol.
     note(`${PRODUCT_NAME} · ${identity.accountId} · ${network} · files land in ${outDir}`);
@@ -132,8 +174,31 @@ export async function mcp(options = {}) {
     await serve({
         input: options.input ?? process.stdin,
         output: options.output ?? ((line) => process.stdout.write(`${line}\n`)),
-        tools,
+        tools: gated,
         info: { name: BINARY_NAME, version: VERSION },
+        // ⛔ WHO CONNECTED, SAID ONCE, TO STDERR. It is the only moment this is knowable: the name
+        //    travels in `initialize` rather than in the environment, which is why it survives the
+        //    three hosts that clear the environment before starting a server. A person reading the
+        //    log of a server they did not start themselves has nowhere else to learn it.
+        onClient: (client) => {
+            if (client.host !== null)
+                note(`Client: ${describeSighting(client.host)}`);
+            else if (client.name !== null)
+                note(`Client: ${client.name} — not an agent this version knows by name`);
+        },
+        // ⛔ AND WHETHER IT CAN BE ASKED ANYTHING, said once for the same reason. A person watching
+        //    this log needs to know before the first share, not when it is refused.
+        onAsker: (built) => {
+            asker = built;
+            // ⚠ A MODE THAT IS ON DECIDES THIS, so it is read here rather than assumed. Saying "every
+            //   share will ask you" to somebody who turned a mode on would be telling them the opposite
+            //   of what their own setting does.
+            if (currentMode() !== "default")
+                return;
+            note(built === null
+                ? "This client cannot show you a question, so sharing is refused here. Share from a terminal."
+                : "This client can show you a question; every share will ask you first.");
+        },
     });
     return 0;
 }

package/dist/commands/mode.d.ts

@@ -0,0 +1,8 @@
+export interface ModeOptions {
+    json?: boolean;
+    write?: (line: string) => void;
+    now?: () => Date;
+    /** Injected in tests: answers the one question. Its presence also stands in for a terminal. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+}
+export declare function mode(wanted: string | undefined, target: string | undefined, options?: ModeOptions): Promise<number>;