@needmoretruth/nmts-cli 0.17.2

package/dist/manifest-write.js

@@ -0,0 +1,244 @@
+// Writing the sealed file list — the step that turns a stored file into a visible one.
+//
+// ⛔ A FILE THAT IS NOT IN THIS LIST DOES NOT EXIST TO ITS OWNER. The server knows a file was
+//    committed and charges for it; the NAME, the folder and the key that opens it live only here,
+//    sealed under a key the server does not have. So this is the last step of an upload and the
+//    one that must not be skipped after the money moved.
+//
+// ⛔ THE WHOLE LIST IS REWRITTEN EVERY TIME. There is no "append" on the wire — the blob is sealed
+//    as one piece. That is why this re-reads immediately before writing: the version it builds on
+//    has to be the current one, and anything another device added since must be carried forward,
+//    not overwritten.
+//
+// ⛔ WHAT PROTECTS AGAINST BUILDING ON A STALE LIST. Three things, and none of them alone:
+//      · this machine's own record refuses a list older than one it already saw;
+//      · the server's compare-and-swap on `base_seq` refuses a write built on a version it has
+//        already moved past — which is what catches an ordinary race between two devices;
+//      · the `prev` link inside the blob makes a fork visible to the NEXT reader on any device.
+//    The account's own settings ride along for the same reason: they live in this blob or nowhere,
+//    so rewriting the list without them would silently clear them.
+import { request, ServerError } from "./api.js";
+import { AAD, DERIVED, loadCrypto } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+import { readFileList, recordWrittenList } from "./manifest.js";
+import { encodeManifest } from "./shared/lib/drive/manifest-codec.js";
+import { buildIndex, entryAt, isLive, KIND_FILE, namesIn, normaliseName } from "./drive-paths.js";
+import { decide } from "./collision.js";
+import { applyIntents } from "./shared/lib/drive/manifest-ops.js";
+import { uniqueFileName } from "./shared/lib/drive/unique-name.js";
+/** How many times a lost compare-and-swap is re-applied before giving up. */
+const CONFLICT_RETRIES = 3;
+/**
+ * Apply one intent to the account's sealed file list.
+ *
+ * ⛔ THE INTENT IS WHAT IS RETRIED, NEVER FINISHED BYTES. On a lost compare-and-swap the list is
+ *    read again and the intent is applied to the NEW one, so both edits survive. That is why the
+ *    caller passes a function rather than an intent: an intent computed once against the old list
+ *    could name a folder id, or a free name, that the new list no longer has.
+ *
+ * ⛔ AND THE INTENTS COME FROM THE BROWSER'S OWN MODULE, copied here byte-for-byte by
+ *    `deploy/gen-cli-shared.mjs`. Re-implementing "send to the trash" would look trivial and be
+ *    wrong in the small places: a re-trashed item must keep its ORIGINAL instant (it is the start
+ *    of the 30-day window the product promises), and trashing a folder must not stamp its
+ *    children (that would reset each child's own clock).
+ *
+ * `make` returning null means there is nothing to do; nothing is written and `changed` is false.
+ */
+export async function applyToList(input, make) {
+    // ⛔ ONE COMPARE-AND-SWAP LOOP IN THIS FILE, and this is the one-intent door into it. A second
+    //    copy would be a second place for "decide again on every attempt" to be got right, and the
+    //    copy nobody re-reads is the one that quietly re-applies a stale decision.
+    return applyManyToList(input, (entries) => {
+        const intent = make(entries);
+        return intent === null ? [] : [intent];
+    });
+}
+/**
+ * Apply a RUN of intents to the account's sealed file list — as ONE write.
+ *
+ * ⛔ ONE WRITE, NOT ONE PER TARGET. A command naming five things and writing five times is five
+ *    chances to lose the compare-and-swap, and losing it half way leaves a drive nobody asked
+ *    for: three things moved, two not, and one error that names neither half. The whole list is
+ *    rewritten on every save anyway (see the header), so five edits cost exactly what one costs.
+ *
+ * ⛔ AND `make` DECIDES THE WHOLE RUN AGAIN ON EVERY ATTEMPT. A free name, an existing folder and
+ *    a live target are all facts about the version that was READ, and a retry happens against a
+ *    version somebody else has just written. A `make` that folds its own intents onto a working
+ *    copy as it goes must start that fold from the list it is handed each time — never from the
+ *    working copy it built on the attempt before.
+ *
+ * An empty run means there is nothing to do; nothing is written and `changed` is false.
+ */
+export async function applyManyToList(input, make) {
+    const crypt = await loadCrypto();
+    const [from, to] = DERIVED.fileListKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(input.code));
+    const key = derived.slice(from, to);
+    derived.fill(0);
+    try {
+        let conflicted = false;
+        for (let attempt = 0; attempt <= CONFLICT_RETRIES; attempt += 1) {
+            const current = await readFileList(input.server, input.apiKey, input.code, input.accountId);
+            const entries = current.manifest ? current.manifest.entries : [];
+            const intents = make(entries);
+            // ⛔ A no-op is a SUCCESS, not a failure. Renaming a file to the name it already has, or
+            //    trashing something already in the trash, must not cost a version bump every other
+            //    device then has to download.
+            if (intents.length === 0) {
+                return { seq: current.seq ?? 0, reappliedAfterConflict: conflicted, changed: false, entries };
+            }
+            const next = applyIntents(entries, intents);
+            if (next === entries) {
+                return { seq: current.seq ?? 0, reappliedAfterConflict: conflicted, changed: false, entries };
+            }
+            const body = await encodeManifest(next, (current.seq ?? 0) + 1, current.fingerprint, current.manifest?.settings);
+            const sealed = crypt.envelope_seal(key, new TextEncoder().encode(AAD.fileList), body);
+            body.fill(0);
+            const ct = Buffer.from(sealed).toString("base64url");
+            try {
+                const answer = await request(input.server, "/v1/manifest", {
+                    method: "PUT",
+                    token: input.apiKey,
+                    body: { base_seq: current.seq ?? null, ct },
+                });
+                const seq = seqOf(answer);
+                await recordWrittenList(input.accountId, seq, ct);
+                return { seq, reappliedAfterConflict: conflicted, changed: true, entries: next };
+            }
+            catch (error) {
+                // ⛔ A version conflict is an ORDINARY outcome, not a failure: another device wrote first.
+                //    Anything else is not, and must not be retried into a second attempt at the same edit.
+                if (!(error instanceof ServerError) || error.code !== "VERSION_CONFLICT")
+                    throw error;
+                conflicted = true;
+            }
+        }
+        throw new NmtsError(`The file list was rewritten by something else ${CONFLICT_RETRIES + 1} times in a row.`, {
+            nextStep: "Nothing about this edit was lost — running the same command again applies it to the " +
+                "list as it now stands.",
+        });
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/**
+ * The entries a run of typed paths names, in the order they were typed.
+ *
+ * ⛔ HERE, BESIDE THE BATCH WRITE, so every command that takes many paths answers "the same thing
+ *    named twice" the same way: once. `nmts rm a.txt a.txt` is not two deletions, and a repeated
+ *    id inside one intent would make the count in the message disagree with the list written.
+ *
+ * ⛔ AND A PATH THAT DOES NOT RESOLVE REFUSES THE WHOLE RUN, because it throws from here before
+ *    anything is composed. That is the decision every batch command in this tool makes: nothing
+ *    is half-done. Moving the four paths that resolved and skipping the fifth would exit 0 on a
+ *    command that did not do what it was told, and the caller would have to diff the drive to
+ *    find out which one. A path already IN the state being asked for is not this case — that is
+ *    a no-op, and each command names it in its own words.
+ *
+ * ⚠ Call it INSIDE `make`. A path is a question about the list, and the answer changes when
+ *   another device writes first.
+ */
+export function batchTargets(entries, paths, options = {}) {
+    const out = [];
+    const seen = new Set();
+    for (const path of paths) {
+        const found = entryAt(entries, path, options);
+        if (seen.has(found.id))
+            continue;
+        seen.add(found.id);
+        out.push(found);
+    }
+    return out;
+}
+/**
+ * Decide what adding this entry does — the whole of the collision rule, with no server in it.
+ *
+ * ⛔ IT IS RE-RUN ON EVERY COMPARE-AND-SWAP ATTEMPT, so everything it looks at has to come from
+ *    the `entries` it is handed. A free name, a live holder and a folder id are all facts about
+ *    the version that was READ, and a retry happens against a version somebody else just wrote.
+ *
+ * ⛔ ONLY A LIVE FILE IS DISPLACED. A folder can hold the name, and replacing one would mean
+ *    deleting it and everything under it in order to store a single file. A trashed file holds its
+ *    name too, and displacing THAT would destroy something already on its way out for a name the
+ *    person can no longer see. Both are renamed around, with no answer consulted — which is what
+ *    happened to every collision before anything could be answered at all.
+ */
+export function planAddition(entries, entry, 
+/**
+ * The ANSWER, already settled — not what a run asked for.
+ *
+ * ⛔ WHO IS ALLOWED TO SAY "OVERWRITE" IS `collision.ts`'s JOB, not this one's. It weighs the
+ *    machine's stored answer, what the run asked for, and whether a mode lets an agent decide
+ *    for itself. Re-deriving any of that here would be a second place for the owner's rule to
+ *    live, and the copy nobody re-reads is the one that quietly disagrees.
+ */
+choice, now = Date.now()) {
+    // ⛔ An id already in the list is not added twice: the account would show two rows for one file
+    //    and the second would be unreachable. It is also how a re-run of an interrupted upload finds
+    //    its own work already done.
+    const existing = entries.find((e) => e.id === entry.id);
+    if (existing !== undefined)
+        return { name: existing.name, alreadyThere: existing.name, intents: [] };
+    const folded = normaliseName(entry.name);
+    const index = buildIndex(entries);
+    const holder = entries.find((e) => e.parentId === entry.parentId &&
+        e.kind === KIND_FILE &&
+        normaliseName(e.name) === folded &&
+        isLive(index, e));
+    if (holder !== undefined && choice === "overwrite") {
+        return {
+            name: entry.name,
+            replaced: { id: holder.id, name: holder.name },
+            intents: [
+                { op: "trash", ids: [holder.id], at: now },
+                { op: "add", entry },
+            ],
+        };
+    }
+    const name = uniqueFileName(entry.name, namesIn(entries, entry.parentId));
+    return { name, intents: [{ op: "add", entry: { ...entry, name } }] };
+}
+/**
+ * Add one entry to the account's sealed file list.
+ *
+ * ⛔ THE NAME IS CHOSEN AGAINST THE LIST AS IT IS ON THIS ATTEMPT. That is the reason this passes
+ *    a function to `applyManyToList`: after a lost compare-and-swap the free names have changed,
+ *    and a name picked against the old list could land on top of what the other device just added.
+ *    The collision is judged again on every attempt for the same reason.
+ *
+ * ⛔ ONLY A LIVE FILE IS DISPLACED. A folder can hold the name, and replacing one would mean
+ *    deleting it and everything under it in order to store a single file. Those are renamed, with
+ *    no answer consulted, exactly as every collision was before anything could be answered at all.
+ */
+export async function addEntry(input) {
+    let name = input.entry.name;
+    let alreadyThere = null;
+    let replaced;
+    // ⛔ SETTLED ONCE, OUTSIDE THE RETRY LOOP. What the machine is set to and whether a mode is on
+    //    are facts about this run, not about the list version a compare-and-swap happened to read.
+    const choice = decide(input.onCollision).choice;
+    const result = await applyManyToList(input, (entries) => {
+        const plan = planAddition(entries, input.entry, choice);
+        alreadyThere = plan.alreadyThere ?? null;
+        name = plan.name;
+        replaced = plan.replaced;
+        return plan.intents;
+    });
+    return {
+        seq: result.seq,
+        name: alreadyThere ?? name,
+        reappliedAfterConflict: result.reappliedAfterConflict,
+        ...(replaced ? { replaced } : {}),
+    };
+}
+function seqOf(answer) {
+    if (typeof answer === "object" && answer !== null) {
+        const seq = Reflect.get(answer, "seq");
+        if (typeof seq === "number" && Number.isSafeInteger(seq) && seq >= 1)
+            return seq;
+    }
+    throw new NmtsError("The file list was written but the server did not say which version it is now.", {
+        nextStep: "The entry is saved. Run `nmts ls` to see it.",
+    });
+}

package/dist/manifest.js

@@ -0,0 +1,213 @@
+// Reading the sealed file list: fetch it, open it, and notice when the server hands back an old one.
+//
+// ⛔ THE SERVER CAN LIE ABOUT THE VERSION, AND THAT IS DESIGNED FOR. The version number lives in a
+//    server column AND inside the sealed blob (NCF-3 §6.1). The sealed one is authenticated; the
+//    column is not. So the column is read as a hint and the sealed one is what is believed, and
+//    when they disagree this module says so rather than picking one quietly.
+//
+// ⛔ WHAT A SINGLE READ CANNOT SEE. "Never go backwards" is only checkable against something this
+//    machine already saw. A first run has nothing to compare to and is therefore trusting; every
+//    run after it is not. That is why the last version and the blob's fingerprint are written down
+//    — a tool that forgets cannot tell a rollback from a fresh start, and it would never say so.
+//
+// ⚠ THE RECORD IS NOT A SECRET. It holds an account id, a version number and a hash of ciphertext.
+//    It is still written 0600, because it sits beside a file that IS a secret and one mode is
+//    easier to keep right than two.
+//
+// ⛔ AND THE SEALED BYTES THEMSELVES ARE KEPT, beside that record. The record alone is a detector:
+//    it can tell that a list went backwards, and it cannot hand anybody a list. The blob can — it
+//    is the account's names, folders and file keys, sealed with the account code, and a copy of it
+//    on this machine is one of the two things a person needs when the server has nothing to give
+//    them. A tool that read the list on every run and then threw it away left an account used only
+//    from a terminal with neither. It is written with the record, by the one function that writes
+//    either, so the two can never describe different versions.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { request } from "./api.js";
+import { AAD, DERIVED, loadCrypto } from "./crypto.js";
+import { configDir } from "./credentials.js";
+import { NmtsError } from "./errors.js";
+import { decodeManifest } from "./shared/lib/drive/manifest-codec.js";
+function asResponse(value) {
+    if (typeof value !== "object" || value === null)
+        throw new NmtsError("The server's answer was not an object.");
+    const v = value;
+    if (v["state"] === "absent")
+        return { state: "absent" };
+    if (v["state"] === "present" &&
+        typeof v["seq"] === "number" &&
+        typeof v["ct"] === "string" &&
+        typeof v["updated_at"] === "string") {
+        return { state: "present", seq: v["seq"], ct: v["ct"], updated_at: v["updated_at"] };
+    }
+    throw new NmtsError("The server answered with a file list this version cannot read.", {
+        nextStep: "Update this tool, or open the account in a browser to see what is there.",
+    });
+}
+/** base64url SHA-256 of a sealed blob — the value a later list carries as its `prev`. */
+async function fingerprint(ct) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(ct));
+    return Buffer.from(digest).toString("base64url");
+}
+function statePath() {
+    return join(configDir(), "file-list-state.json");
+}
+/**
+ * Where this machine keeps one account's sealed file list.
+ *
+ * ⛔ AN ACCOUNT ID BECOMES PART OF A PATH HERE, so it is CHECKED rather than trusted. Every id this
+ *    tool has comes from its own derivation and is base64url, but a value that reaches a path join
+ *    unchecked is how `..` becomes a write somewhere else, and the check costs one line.
+ */
+function keptListPath(accountId) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(accountId)) {
+        throw new NmtsError("That is not an account id this tool derived.", {
+            nextStep: "Nothing was written. This is a fault in the tool rather than in the account.",
+        });
+    }
+    return join(configDir(), `file-list-${accountId}.json`);
+}
+function isKeptList(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return (typeof Reflect.get(value, "seq") === "number" &&
+        typeof Reflect.get(value, "savedAt") === "string" &&
+        typeof Reflect.get(value, "ct") === "string");
+}
+/**
+ * The copy this machine holds for an account, or null when it holds none.
+ *
+ * ⚠ A COPY THAT CANNOT BE READ IS REPORTED AS NO COPY, on purpose. There is nothing to salvage
+ *   from a truncated one, the next read of the list replaces it, and a command that refused to
+ *   write out a good copy because an old one is unreadable would be refusing the very thing it is
+ *   for.
+ */
+export function readKeptList(accountId) {
+    try {
+        const parsed = JSON.parse(readFileSync(keptListPath(accountId), "utf8"));
+        return isKeptList(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Keep these sealed bytes as this machine's copy.
+ *
+ * ⛔ NEWER ONLY. A copy is replaced when the version landing is at least the one already kept, and
+ *    never when it is older: this machine's record of what it has seen can be lost or cleared, and
+ *    a run that then read an older list from the server must not overwrite the newest copy with
+ *    it. The record refuses a lower version while it exists; this is what holds when it does not.
+ */
+function writeKept(accountId, seq, ct) {
+    const held = readKeptList(accountId);
+    if (held !== null && held.seq > seq)
+        return;
+    const copy = { seq, savedAt: new Date().toISOString(), ct };
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(keptListPath(accountId), `${JSON.stringify(copy, null, 2)}\n`, { mode: 0o600 });
+}
+function readSeen() {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath(), "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        // A missing or unreadable record means "nothing to compare against", which is the same
+        // position a first run is in. It is not an error and must not stop a listing.
+        return {};
+    }
+}
+/**
+ * Write down what this machine has seen: the version, the fingerprint, and the bytes.
+ *
+ * ⛔ ONE FUNCTION FOR BOTH. The detector and the copy describe the same blob, and two functions
+ *    would be two chances for a caller to update one and not the other — after which the machine
+ *    would hold a copy of one version while claiming to have seen another.
+ */
+function writeSeen(accountId, seq, fp, ct) {
+    const all = readSeen();
+    all[accountId] = { seq, fingerprint: fp };
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(statePath(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    // The record goes first: it is the safety device, and a machine that failed to keep a copy must
+    // still refuse an older list afterwards.
+    writeKept(accountId, seq, ct);
+}
+/**
+ * Record a version this machine WROTE, so the server cannot serve an older one back afterwards.
+ *
+ * ⛔ ONLY AFTER THE SERVER ACCEPTED IT. Recording a version that lost the compare-and-swap would
+ *    leave this machine believing in a list that never existed — and then refusing the real one as
+ *    a rollback.
+ */
+export async function recordWrittenList(accountId, seq, ct) {
+    writeSeen(accountId, seq, await fingerprint(ct), ct);
+}
+/** True when this machine has a record for the account — i.e. a rollback would be visible. */
+export function hasSeenBefore(accountId) {
+    return existsSync(statePath()) && accountId in readSeen();
+}
+/**
+ * Fetch and open the account's file list.
+ *
+ * `accountCode` is used here and not kept: the file-list key is derived, used, and zeroed. The
+ * derivation output holds every other key in the account, so it does not outlive this call.
+ */
+export async function readFileList(base, apiKey, accountCode, accountId) {
+    const answer = asResponse(await request(base, "/v1/manifest", { token: apiKey }));
+    const first = !hasSeenBefore(accountId);
+    if (answer.state === "absent")
+        return { manifest: null, firstTimeOnThisMachine: first };
+    const seen = readSeen()[accountId];
+    if (seen !== undefined && answer.seq < seen.seq) {
+        throw new NmtsError(`The server offered file-list version ${answer.seq}; this machine already saw ${seen.seq}.`, {
+            nextStep: "Nothing was changed. A list that goes backwards means an older copy is being served, " +
+                "so files added since could be missing from it. Open the account in a browser and " +
+                "compare before writing anything.",
+        });
+    }
+    // ⛔ The same version must be the same bytes. Two different blobs at one version number is a
+    //    FORK — two devices shown different histories — and it is the one fork check an occasional
+    //    reader can actually make. (The chain link inside the list, `prev`, names the blob its
+    //    author continued from; between two runs of this tool a browser may have written several
+    //    versions, so `prev` will legitimately name a blob this machine never saw. Comparing it
+    //    would cry wolf on ordinary use, which is worse than not comparing it.)
+    const fp = await fingerprint(answer.ct);
+    if (seen !== undefined && answer.seq === seen.seq && fp !== seen.fingerprint) {
+        throw new NmtsError(`The server offered a different file list at the same version (${answer.seq}).`, {
+            nextStep: "Nothing was changed. One version number can only have one list, so this machine is " +
+                "being shown a different history than it was before. Open the account in a browser " +
+                "and compare before writing anything.",
+        });
+    }
+    const crypt = await loadCrypto();
+    const [from, to] = DERIVED.fileListKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(accountCode));
+    const key = derived.slice(from, to);
+    derived.fill(0);
+    let body;
+    try {
+        body = crypt.envelope_open(key, new TextEncoder().encode(AAD.fileList), Buffer.from(answer.ct, "base64url"));
+    }
+    catch {
+        throw new NmtsError("The file list did not open with this account's key.", {
+            nextStep: "Either the code belongs to a different account, or the stored bytes are not what this " +
+                "account sealed. Nothing was changed.",
+        });
+    }
+    finally {
+        key.fill(0);
+    }
+    const manifest = await decodeManifest(body);
+    body.fill(0);
+    const out = { manifest, seq: manifest.seq, fingerprint: fp, firstTimeOnThisMachine: first };
+    // ⛔ The sealed number is the authenticated one, so it is what gets recorded and what a later
+    //    run compares against. The column is reported when it differs and otherwise ignored.
+    if (manifest.seq !== answer.seq)
+        out.serverSeqDisagreed = answer.seq;
+    // ⛔ THE VERSION THAT IS KEPT IS THE SEALED ONE, and so are the bytes it came out of. Believing
+    //    the server's column here would let it decide which copy this machine keeps.
+    writeSeen(accountId, manifest.seq, fp, answer.ct);
+    return out;
+}

package/dist/mark-render.js

@@ -0,0 +1,45 @@
+// How the three marks a person puts on their own files are SHOWN, in one place — so `ls` and the
+// commands that set them cannot end up disagreeing about what "starred" looks like.
+//
+// ⛔ THE MARKS LIVE ONLY IN THE SEALED FILE LIST. The server is never told that a file is starred,
+//    what a label is called, or how many there are: it holds the blob and cannot open it. So
+//    nothing here asks a server anything — it reads the list this account has already opened.
+//
+// ⛔ A SUFFIX, NOT A COLUMN. `ls` pads one width for the path and puts `[trash, …]` after the
+//    size; a marks column would need a second computed width and would print an empty one on
+//    every account that uses no marks, which is most of them. The table is for a person glancing
+//    down it, and the field an agent parses is in `--json`, where it is always present.
+/**
+ * The marks on one entry — always all three.
+ *
+ * ⚠ ABSENT IS `false` HERE AND ABSENCE IN THE LIST, and the difference is deliberate. The format
+ *   writes a mark only when it is on, because the whole list is re-sealed on every change and
+ *   re-downloaded on every cold start. A reader parsing this needs the opposite: a field that is
+ *   always there, so "this file is not starred" cannot be mistaken for "this output does not say".
+ */
+export function marksOf(entry) {
+    return {
+        favorite: entry.favorite === true,
+        pinned: entry.pinned === true,
+        labels: entry.labels ?? [],
+    };
+}
+/**
+ * What `ls` puts after a row, or an empty string when the entry wears no mark.
+ *
+ * ⚠ It carries its own leading spaces, exactly like the trash suffix beside it, so a row with no
+ *   marks is byte-for-byte the row that was printed before marks existed.
+ */
+export function markSuffix(marks) {
+    const parts = [];
+    if (marks.favorite)
+        parts.push("starred");
+    if (marks.pinned)
+        parts.push("pinned");
+    // ⚠ QUOTED, because a label is free text somebody typed. One label called `work, home` and two
+    //   labels called `work` and `home` would otherwise print as the same line.
+    if (marks.labels.length > 0) {
+        parts.push(`labels: ${marks.labels.map((l) => `"${l}"`).join(", ")}`);
+    }
+    return parts.length === 0 ? "" : `  [${parts.join(", ")}]`;
+}

package/dist/mcp-args.js

@@ -0,0 +1,154 @@
+// Checking a tool call's arguments against the schema the tool advertised.
+//
+// ⛔ WHY THIS EXISTS: THE SCHEMA WAS DECORATION. Every tool declares an `inputSchema` and the
+//    protocol hands it to the model, but nothing on this side ever compared a call against it. The
+//    transport coerced anything that was not an object to `{}` and passed the rest straight
+//    through, so `required`, the declared types and `additionalProperties: false` were all
+//    advertised and none of them held. Each tool then hand-checked the one string it could not do
+//    without, and checked booleans with `=== true` — which means a model sending `"dry_run": "true"`
+//    (the string, which is what a model that has been told to send JSON text produces) got a real,
+//    paid upload while believing it had asked for a price. That is the failure this file exists to
+//    stop, and it is worth a file: the alternative is the same four checks written again inside
+//    every tool, where the twentieth one will forget.
+//
+// ⛔ IT REFUSES; IT DOES NOT REPAIR. A wrong argument is answered with a message naming what was
+//    wrong, never with a guess at what was meant. Coercing `"true"` to `true` would be deciding on
+//    the caller's behalf that they wanted the branch that spends money, which is exactly the
+//    decision that must not be made here. The model can read the refusal and call again.
+//
+// ⚠ IT UNDERSTANDS THE SUBSET THIS TOOL USES, AND SAYS SO WHEN IT DOES NOT. The schemas here are
+//   flat objects of scalars and arrays of scalars. A keyword outside that subset is not silently
+//   ignored: `unsupported()` lists what a schema asked for that this checker cannot judge, so a
+//   schema that grows past it fails a test rather than quietly losing its guarantee.
+import { isRecord } from "./guards.js";
+/** The JSON types a declared property may have. */
+const KNOWN_TYPES = ["string", "number", "integer", "boolean", "array", "object"];
+/** Keywords this checker actually enforces. Anything else in a schema is reported, not ignored. */
+const HANDLED_ROOT = ["type", "properties", "required", "additionalProperties", "description"];
+const HANDLED_PROPERTY = ["type", "description", "items", "enum"];
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** What a value actually is, in the vocabulary the schema uses. */
+function actualType(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (value === null)
+        return "null";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+}
+function typeMatches(declared, value) {
+    switch (declared) {
+        case "string":
+            return typeof value === "string";
+        case "boolean":
+            return typeof value === "boolean";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+    }
+}
+function declaredType(property) {
+    if (!isRecord(property))
+        return null;
+    const t = property["type"];
+    return KNOWN_TYPES.find((k) => k === t) ?? null;
+}
+/**
+ * Keywords a schema uses that this checker does not enforce.
+ *
+ * ⛔ THE POINT IS THAT IT IS NOT EMPTY-BY-ASSUMPTION. A checker that silently skips what it does
+ *    not understand still returns "no problems", and a schema that grew a `minimum` or a `oneOf`
+ *    would go on being advertised while nothing held it. A test compares this against the real
+ *    tool table, so growing a schema past this file turns something red.
+ */
+export function unsupported(schema) {
+    if (!isRecord(schema))
+        return ["the schema is not an object"];
+    const found = [];
+    for (const key of Object.keys(schema)) {
+        if (!HANDLED_ROOT.includes(key))
+            found.push(key);
+    }
+    const properties = schema["properties"];
+    if (isRecord(properties)) {
+        for (const [name, property] of Object.entries(properties)) {
+            if (!isRecord(property)) {
+                found.push(`${name} (not an object)`);
+                continue;
+            }
+            if (declaredType(property) === null)
+                found.push(`${name}.type`);
+            for (const key of Object.keys(property)) {
+                if (!HANDLED_PROPERTY.includes(key))
+                    found.push(`${name}.${key}`);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Compare one call's arguments against the schema its tool advertised.
+ *
+ * Returns the problems, most important first: a missing required argument before a wrong type,
+ * because a caller that forgot one is usually about to be told about the other for the same reason.
+ * An empty array means the call may proceed.
+ */
+export function checkArgs(schema, args) {
+    if (!isRecord(args)) {
+        return [`arguments must be an object, and this call sent ${actualType(args)}`];
+    }
+    if (!isRecord(schema))
+        return [];
+    const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+    const required = stringList(schema["required"]);
+    const closed = schema["additionalProperties"] === false;
+    const problems = [];
+    for (const name of required) {
+        if (!(name in args) || args[name] === undefined)
+            problems.push(`\`${name}\` is required`);
+    }
+    for (const [name, value] of Object.entries(args)) {
+        // ⚠ `undefined` cannot come off the wire — JSON has no such value — so a key holding it was
+        //   built locally and means "not given". Treating it as given would refuse calls the caller
+        //   made correctly.
+        if (value === undefined)
+            continue;
+        const property = properties[name];
+        if (property === undefined) {
+            if (closed)
+                problems.push(`\`${name}\` is not an argument this tool takes`);
+            continue;
+        }
+        const type = declaredType(property);
+        if (type === null)
+            continue;
+        if (!typeMatches(type, value)) {
+            problems.push(`\`${name}\` must be ${type}, and this call sent ${actualType(value)}`);
+            continue;
+        }
+        if (type === "array" && Array.isArray(value) && isRecord(property) && isRecord(property["items"])) {
+            const itemType = declaredType(property["items"]);
+            if (itemType !== null) {
+                const wrong = value.findIndex((item) => !typeMatches(itemType, item));
+                if (wrong !== -1) {
+                    problems.push(`\`${name}\` must hold ${itemType} values, and item ${wrong + 1} is ${actualType(value[wrong])}`);
+                }
+            }
+        }
+        if (isRecord(property)) {
+            const allowed = stringList(property["enum"]);
+            if (allowed.length > 0 && typeof value === "string" && !allowed.includes(value)) {
+                problems.push(`\`${name}\` must be one of ${allowed.join(", ")} — this call sent ${value}`);
+            }
+        }
+    }
+    return problems;
+}