@needmoretruth/nmts-cli 0.17.2

package/dist/commands/marks.js

@@ -0,0 +1,176 @@
+// `nmts star`, `nmts pin`, `nmts label` and the three commands that take those marks off again.
+//
+// ⛔ A MARK IS A DESIRED STATE, NEVER A TOGGLE, and that is the whole reason there are six verbs
+//    rather than three with a switch. An edit that said "flip it" and was replayed onto a list
+//    another device wrote first would flip twice: two people starring one file would end with it
+//    unstarred, and neither of them did that. `star` means starred afterwards, whatever it was.
+//
+// ⛔ MARKS BELONG TO FILES. The drive lists starred FILES, counts labelled FILES, and lifts pinned
+//    rows to the top of a folder — a folder row carries no mark at all. Putting one on a folder
+//    would write a field into the sealed list that no screen anywhere draws, and the only way to
+//    ever take it off again would be this tool. So a folder is refused, in words that say why.
+//
+// ⛔ AND NOT ONE OF THEM TELLS THE SERVER ANYTHING. A mark exists only inside the sealed list, so
+//    there is no row to change and nothing to undo if the list write fails. What the server does
+//    see is a manifest write of a known size at a known moment — the same as a rename.
+//
+// ⛔ ONE WRITE PER RUN, HOWEVER MANY PATHS. The intents these build take a set of ids for exactly
+//    that reason. Writing once per path would be one lost compare-and-swap away from half a run.
+import { buildIndex, fullPathOf, KIND_FILE } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { applyToList, batchTargets } from "../manifest-write.js";
+import { openSession } from "../session.js";
+/** Star one or more files: they show in the drive's favourites as well as in their own folder. */
+export async function star(paths, options = {}) {
+    return run("star", paths, undefined, options);
+}
+/** Take the star off. */
+export async function unstar(paths, options = {}) {
+    return run("unstar", paths, undefined, options);
+}
+/** Hold one or more files at the top of the folder they are in. */
+export async function pin(paths, options = {}) {
+    return run("pin", paths, undefined, options);
+}
+/** Let them fall back into the ordinary order. */
+export async function unpin(paths, options = {}) {
+    return run("unpin", paths, undefined, options);
+}
+/**
+ * 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 async function label(name, paths, options = {}) {
+    return run("label", paths, name, options);
+}
+/** Take one label off one or more files. */
+export async function unlabel(name, paths, options = {}) {
+    return run("unlabel", paths, name, options);
+}
+async function run(verb, paths, name, options) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const on = !verb.startsWith("un");
+    const wantsLabel = verb === "label" || verb === "unlabel";
+    // ⚠ Trimmed HERE as well as inside the intent, so the label that is compared against what a
+    //   file already wears is the same text that gets stored. `  work  ` and `work` are one label.
+    const text = name === undefined ? "" : name.trim();
+    if (wantsLabel && text === "") {
+        throw new NmtsError(`\`nmts ${verb}\` needs the label first, then what to put it on.`, {
+            exitCode: 2,
+            nextStep: `For example: nmts ${verb} work notes.txt report.pdf`,
+        });
+    }
+    if (paths.length === 0) {
+        throw new NmtsError(`\`nmts ${verb}\` needs the path of at least one file.`, {
+            exitCode: 2,
+            nextStep: `\`nmts ls\` prints the paths as this expects them.`,
+        });
+    }
+    const session = await openSession(options);
+    const at = Date.now();
+    const outcome = { marked: [], already: [] };
+    // ⛔ WHICH FILES THESE PATHS NAME IS ASKED INSIDE THE ATTEMPT, not before it. On a lost
+    //    compare-and-swap the list is read again, and a path is a question about the list: the
+    //    winner may have renamed something, or moved it, or put it in the trash. Deciding once and
+    //    re-applying would mark whatever now happens to be sitting at that id.
+    const result = await applyToList(session, (now) => {
+        const index = buildIndex(now);
+        const targets = batchTargets(now, paths, { nothingHappened: "Nothing was marked." });
+        const marked = [];
+        const already = [];
+        for (const target of targets) {
+            if (target.kind !== KIND_FILE) {
+                throw new NmtsError(`"${fullPathOf(index, target)}" is a folder, and marks are for files.`, {
+                    exitCode: 4,
+                    nextStep: `Nothing was marked. A star, a pin and a label are shown on files; a folder that ` +
+                        `carried one would show it nowhere.`,
+                });
+            }
+            (wears(target, verb, text) === on ? already : marked).push(fullPathOf(index, target));
+        }
+        outcome.marked = marked;
+        outcome.already = already;
+        // ⛔ EVERY ID GOES IN, including the ones already like this. The intent is a desired state, so
+        //    the ones already in it change nothing — and when they are ALL already in it the whole
+        //    edit is a no-op, which costs no version bump and no download on anybody else's device.
+        return intentFor(verb, targets.map((t) => t.id), text, on, at);
+    });
+    if (options.json) {
+        say(JSON.stringify({
+            mark: wantsLabel ? "label" : verb === "star" || verb === "unstar" ? "favorite" : "pinned",
+            on,
+            label: wantsLabel ? text : null,
+            marked: outcome.marked,
+            already: outcome.already,
+            changed: result.changed,
+            reappliedAfterConflict: result.reappliedAfterConflict,
+            seq: result.seq,
+        }));
+        return 0;
+    }
+    // ⛔ THE FILES ARE NAMED, NOT COUNTED, like every other edit in this tool: "2 files starred"
+    //    cannot disagree with what was written, so it could never catch a run that marked something
+    //    the caller did not name.
+    const names = (list) => list.map((p) => `"${p}"`).join(", ");
+    if (outcome.marked.length > 0) {
+        say(`${did(verb, text)} ${names(outcome.marked)}.`);
+        if (outcome.already.length > 0) {
+            say(`  ${names(outcome.already)} ${outcome.already.length === 1 ? "was" : "were"} already ${state(verb, text)}.`);
+        }
+    }
+    else {
+        say(`Nothing changed: ${names(outcome.already)} ` +
+            `${outcome.already.length === 1 ? "is" : "are"} already ${state(verb, text)}.`);
+    }
+    if (result.changed && result.reappliedAfterConflict) {
+        say(`  Another device wrote the file list first, so this was applied to that version.`);
+    }
+    return 0;
+}
+/** The intent one verb writes. `on` is the state asked for, never a flip — see the header. */
+function intentFor(verb, ids, text, on, at) {
+    if (verb === "star" || verb === "unstar")
+        return { op: "favorite", ids, on, at };
+    if (verb === "pin" || verb === "unpin")
+        return { op: "pin", ids, on, at };
+    return { op: "label", ids, label: text, on, at };
+}
+/** Does this entry already carry the mark the verb is about? */
+function wears(entry, verb, text) {
+    if (verb === "star" || verb === "unstar")
+        return entry.favorite === true;
+    if (verb === "pin" || verb === "unpin")
+        return entry.pinned === true;
+    return (entry.labels ?? []).includes(text);
+}
+/** What the run did, as the first word of the sentence saying it. */
+function did(verb, text) {
+    if (verb === "star")
+        return "Starred";
+    if (verb === "unstar")
+        return "Took the star off";
+    if (verb === "pin")
+        return "Pinned";
+    if (verb === "unpin")
+        return "Unpinned";
+    if (verb === "label")
+        return `Put "${text}" on`;
+    return `Took "${text}" off`;
+}
+/** The state the verb asks for, for the sentence about what was already the case. */
+function state(verb, text) {
+    if (verb === "star")
+        return "starred";
+    if (verb === "unstar")
+        return "not starred";
+    if (verb === "pin")
+        return "pinned";
+    if (verb === "unpin")
+        return "not pinned";
+    if (verb === "label")
+        return `wearing "${text}"`;
+    return `without "${text}"`;
+}

package/dist/commands/mcp.js

@@ -0,0 +1,139 @@
+// `nmts mcp` — the same account, offered to an agent as tools instead of as a command line.
+//
+// ⛔ WHAT IT WILL AND WILL NOT DO. It offers most of what the command line offers: reading the
+//    account, fetching files, uploading them, rearranging them, and sharing one with another
+//    account. What it does NOT offer is not a gap to fill in later — a tool a model can call on
+//    its own is a different thing from a command a person typed, and this is the list of
+//    differences and why each one is there:
+//      · Making or revoking a key, signing in or out, and granting this tool's agreements. Those
+//        are the person's credentials and the person's consent, and a surface that could grant its
+//        own permissions has none.
+//      · Passing the human check. A machine cannot; that is what the check is.
+//      · Destroying anything permanently — emptying the trash, erasing a file for good. Putting
+//        something in the trash IS here, because it can be taken back.
+//      · Rebuilding a lost file list. It works, but every name it recovers is a placeholder, and
+//        somebody should see that happen rather than read about it afterwards.
+//      · Writing the account's disaster-recovery files, and downloading the separate recovery
+//        program. Those exist for the day this service is not there, and they are a person's to
+//        make and to keep.
+//    Nothing here can write outside the one directory the person named when they started it.
+//
+// ⛔ THE OUTPUT DIRECTORY IS CHOSEN BY THE PERSON, NEVER BY THE MODEL. Every tool that writes
+//    takes a path INSIDE THE ACCOUNT and lands under that directory. There is nowhere in any tool
+//    declaration to put a path on this disk, which is what keeps that true as tools are added: a
+//    model that asks for `../../.ssh/authorized_keys` gets a refusal, not a surprise.
+//
+// ⛔ NOTHING BUT PROTOCOL GOES TO STDOUT — and two things had to change for that to be true.
+//    Prompts now write to stderr, and this server refuses to prompt at all (`allowPrompt: false`),
+//    because its stdin IS the protocol: a passphrase prompt here consumed the client's first
+//    message as a guess and put its own question on the wire. Everything a person reads goes to stderr — a stray line
+//    on stdout is a parse error at the client and the tools disappear with no explanation.
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { identityOf } from "../account.js";
+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";
+// ⚠ 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 { 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";
+/**
+ * Which account this server is holding, answered without asking anything.
+ *
+ * ⛔ It is derived here, offline, from the code this process opened at startup. It says nothing
+ *    about whether that account exists on the server, whether it has credits, or whether the key
+ *    beside it belongs to the same account — a model that treats "whoami answered" as "I am signed
+ *    in and can spend" has been misled by its own tool.
+ */
+function whoami(ctx) {
+    return {
+        name: "nmts_whoami",
+        description: "Which NMTS account this machine holds the code 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() {
+            return [
+                `account id  ${ctx.accountId}`,
+                `server      ${ctx.server}`,
+                `network     ${ctx.network}`,
+                `files land  ${ctx.outDir}`,
+            ].join("\n");
+        },
+    };
+}
+/**
+ * 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 function mcpToolSchemas() {
+    const ctx = { server: "https://example.invalid", network: "testnet", outDir: "/", accountId: "-" };
+    const all = [whoami(ctx), ...readTools(ctx), ...fileTools(ctx), ...organiseTools(ctx), ...shareTools(ctx)];
+    return all.map((t) => ({ name: t.name, inputSchema: t.inputSchema }));
+}
+export async function mcp(options = {}) {
+    const note = options.note ?? ((line) => process.stderr.write(`${line}\n`));
+    // ⛔ NO PROMPT FROM HERE. stdin is the protocol; see `OpenOptions.allowPrompt`.
+    //
+    // ⚠ AND THE CODE IS HELD FOR AS LONG AS THIS SERVER RUNS. A passphrase on a sealed store is a
+    //   gate at startup, not a gate per request: once this process has the code it keeps it, and
+    //   every tool call it serves uses it without asking again. That is the only shape a server can
+    //   have — there is nobody to ask mid-session — and it is written down here because somebody
+    //   deciding whether to leave this running deserves to know it.
+    const resolved = await requireAccountCode({ allowPrompt: false });
+    const key = resolveApiKey();
+    if (key === null) {
+        throw new NmtsError("This account has no API key on this machine, and the server needs one.", {
+            exitCode: 3,
+            nextStep: `Make a key on the account screen at nmts.me and put it in ${API_KEY_ENV_VAR}, or store ` +
+                `it with \`${BINARY_NAME} login\`.`,
+        });
+    }
+    const stored = readCredentialsFile();
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const identity = await identityOf(resolved.code);
+    const outDir = resolve(options.out ?? process.cwd());
+    if (!existsSync(outDir))
+        mkdirSync(outDir, { recursive: true });
+    if (!statSync(outDir).isDirectory()) {
+        throw new NmtsError(`${outDir} is not a directory.`, { exitCode: 2 });
+    }
+    const ctx = { server, network, outDir, accountId: identity.accountId };
+    /**
+     * The whole surface, in one place.
+     *
+     * ⛔ THE ORDER IS THE ORDER A CLIENT SHOWS THEM IN, so it goes reads, then fetching, then
+     *    rearranging, then the one that hands a file to somebody else. A model scanning the list
+     *    meets the harmless ones first and the irreversible one last, which is the order it should
+     *    be thinking in.
+     */
+    const tools = [
+        whoami(ctx),
+        ...readTools(ctx),
+        ...fileTools(ctx),
+        ...organiseTools(ctx),
+        ...shareTools(ctx),
+    ];
+    // ⛔ 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}`);
+    note(`Tools: ${tools.map((t) => t.name).join(" · ")}`);
+    await serve({
+        input: options.input ?? process.stdin,
+        output: options.output ?? ((line) => process.stdout.write(`${line}\n`)),
+        tools,
+        info: { name: BINARY_NAME, version: VERSION },
+    });
+    return 0;
+}

package/dist/commands/mode.js

@@ -0,0 +1,54 @@
+// `nmts mode` — how much an agent driving this tool may decide without asking.
+//
+// ⛔ IT IS A COMMAND, FOR THE SAME REASON CONSENT IS. A question asked in the middle of another
+//    command cannot be answered by a container, a build step, or an agent's subprocess. A command
+//    can, its answer is recorded with a date, and it can be looked at afterwards.
+//
+// ⛔ TURNING ONE ON TAKES A FLAG THAT SAYS WHAT IT IS. `nmts mode auto` alone prints what the mode
+//    means and stops; adding the flag is the sentence nobody types by accident.
+import { AUTONOMY_MODES, MODE_MEANS, RISK_FLAG, currentMode, setAt, setMode, } from "../autonomy.js";
+import { NmtsError } from "../errors.js";
+import { BINARY_NAME, VERSION } from "../product.js";
+function isMode(value) {
+    return AUTONOMY_MODES.includes(value);
+}
+export function mode(wanted, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const now = options.now ?? (() => new Date());
+    if (wanted === undefined || wanted === "") {
+        const at = currentMode();
+        if (options.json === true) {
+            say(JSON.stringify({ mode: at, setAt: setAt(), means: MODE_MEANS[at] }));
+            return 0;
+        }
+        say(`${at} — ${MODE_MEANS[at]}`);
+        // ⛔ The way to change it is said HERE. Listing what exists without saying how to pick one
+        //    sends the reader back to the help text and leaves an agent to guess.
+        for (const other of AUTONOMY_MODES) {
+            if (other !== at)
+                say(`${other} — ${MODE_MEANS[other]}`);
+        }
+        say(`Change it: ${BINARY_NAME} mode <${AUTONOMY_MODES.join("|")}> ${RISK_FLAG}`);
+        return 0;
+    }
+    if (!isMode(wanted)) {
+        throw new NmtsError(`There is no mode called "${wanted}".`, {
+            exitCode: 2,
+            nextStep: `One of: ${AUTONOMY_MODES.join(" · ")}`,
+        });
+    }
+    // ⛔ Turning one OFF never needs the flag. Making the safe direction harder than the risky one
+    //    is how somebody leaves it on.
+    if (wanted !== "off" && options.accepted !== true) {
+        throw new NmtsError(MODE_MEANS[wanted], {
+            exitCode: 2,
+            nextStep: [
+                "You bear what an agent does with your files and your credits while this is on.",
+                `Turn it on: ${BINARY_NAME} mode ${wanted} ${RISK_FLAG}`,
+            ].join("\n  "),
+        });
+    }
+    setMode(wanted, VERSION, now());
+    say(wanted === "off" ? `off — ${MODE_MEANS.off}` : `${wanted} — ${MODE_MEANS[wanted]}`);
+    return 0;
+}

package/dist/commands/on-collision.js

@@ -0,0 +1,45 @@
+// `nmts on-collision` — what this machine does when an upload's name is already in use.
+//
+// ⛔ IT IS A COMMAND FOR THE SAME REASON `mode` IS. The answer is asked for once while somebody is
+//    signing in, but a machine that was set up by a script never saw that question, and a person
+//    who answered it once has to be able to change it without signing in again.
+//
+// ⛔ NO RISK FLAG HERE, unlike `mode`. This setting does not hand a decision to an agent — it
+//    records what a person wants — and the destructive answer is one word that says what it does.
+//    What the modes gate is the other case, an agent choosing overwrite for one run with nobody
+//    having said so, and that is enforced in `collision.ts` rather than by a flag on this command.
+import { COLLISION_CHOICES, COLLISION_MEANS, currentChoice, setChoice, } from "../collision.js";
+import { NmtsError } from "../errors.js";
+import { BINARY_NAME, VERSION } from "../product.js";
+function isChoice(value) {
+    return COLLISION_CHOICES.includes(value);
+}
+export function onCollision(wanted, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const now = options.now ?? (() => new Date());
+    if (wanted === undefined || wanted === "") {
+        const at = currentChoice();
+        if (options.json === true) {
+            say(JSON.stringify({ onCollision: at, means: COLLISION_MEANS[at] }));
+            return 0;
+        }
+        say(`${at} — ${COLLISION_MEANS[at]}`);
+        // The other one, and how to pick it. Listing what exists without saying how to choose sends
+        // the reader back to the help text.
+        for (const other of COLLISION_CHOICES) {
+            if (other !== at)
+                say(`${other} — ${COLLISION_MEANS[other]}`);
+        }
+        say(`Change it: ${BINARY_NAME} on-collision <${COLLISION_CHOICES.join("|")}>`);
+        return 0;
+    }
+    if (!isChoice(wanted)) {
+        throw new NmtsError(`There is no such answer: "${wanted}".`, {
+            exitCode: 2,
+            nextStep: `One of: ${COLLISION_CHOICES.join(" · ")}`,
+        });
+    }
+    setChoice(wanted, VERSION, now());
+    say(`${wanted} — ${COLLISION_MEANS[wanted]}`);
+    return 0;
+}