@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/commands/mode.js

@@ -1,18 +1,24 @@
 // `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.
+// ⛔ A PERSON SWITCHES IT, AT A TERMINAL. Turning a mode on refuses when stdin is not a terminal —
+//    the way an agent's subprocess usually arrives — prints the whole explanation first, and takes
+//    one answer: y for the two auto modes, a typed sentence for skip-permissions. Turning it off is
+//    one line from anywhere. Short for the person, closed to the program: that is the shape the owner
+//    asked for (2026-09-06).
 //
-// ⛔ 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";
+// ⛔ `nmts mode explain <mode>` PRINTS THE EXPLANATION AND CHANGES NOTHING. It exists so an agent that
+//    recommends a mode can show the person exactly what it is, rather than its own summary.
+import { AUTONOMY_MODES, MODE_MEANS, SKIP_SENTENCE, currentMode, explain, modeFromStored, 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);
+import { promptLine, stdinIsATerminal } from "../prompt.js";
+/** A name a person may type, including the two older spellings. */
+function wantedMode(raw) {
+    if (raw === "off" || raw === "auto")
+        return modeFromStored(raw);
+    return AUTONOMY_MODES.includes(raw) ? raw : null;
 }
-export function mode(wanted, options = {}) {
+export async function mode(wanted, target, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const now = options.now ?? (() => new Date());
     if (wanted === undefined || wanted === "") {
@@ -22,33 +28,63 @@ export function mode(wanted, options = {}) {
             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}`);
+        say(`Change it, at a terminal: ${BINARY_NAME} mode <${AUTONOMY_MODES.join("|")}>`);
+        say(`Read one in full first:    ${BINARY_NAME} mode explain <mode>`);
         return 0;
     }
-    if (!isMode(wanted)) {
+    if (wanted === "explain") {
+        const which = target === undefined ? null : wantedMode(target);
+        if (which === null) {
+            throw new NmtsError(`Say which mode to explain.`, { exitCode: 2, nextStep: `One of: ${AUTONOMY_MODES.join(" · ")}` });
+        }
+        for (const line of explain(which))
+            say(line);
+        return 0;
+    }
+    const next = wantedMode(wanted);
+    if (next === null) {
         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  "),
+    // ⛔ OFF IS ONE LINE FROM ANYWHERE. Making the safe direction harder than the risky one is how
+    //    somebody leaves it on.
+    if (next === "default") {
+        setMode("default", VERSION, now());
+        say(`default — ${MODE_MEANS.default}`);
+        return 0;
+    }
+    if (options.readLine === undefined && !stdinIsATerminal()) {
+        throw new NmtsError(`A person switches modes, at a terminal — stdin here is not one.`, {
+            exitCode: 5,
+            nextStep: `If you are an agent: do not switch modes. You may recommend one — show the person ` +
+                `\`${BINARY_NAME} mode explain ${next}\` in full and let them decide.`,
         });
     }
-    setMode(wanted, VERSION, now());
-    say(wanted === "off" ? `off — ${MODE_MEANS.off}` : `${wanted} — ${MODE_MEANS[wanted]}`);
+    const ask = options.readLine ?? promptLine;
+    for (const line of explain(next))
+        say(line);
+    say(``);
+    if (next === "skip-permissions") {
+        const typed = (await ask(`Type exactly: ${SKIP_SENTENCE}\n> `)).trim();
+        if (typed !== SKIP_SENTENCE) {
+            say(`Nothing was changed.`);
+            return 1;
+        }
+    }
+    else {
+        const answer = (await ask(`Turn ${next} on? [y/N] `)).trim();
+        if (answer !== "y" && answer !== "Y") {
+            say(`Nothing was changed.`);
+            return 1;
+        }
+    }
+    setMode(next, VERSION, now());
+    say(`${next} — ${MODE_MEANS[next]}`);
     return 0;
 }

package/dist/commands/on-collision.d.ts

@@ -0,0 +1,6 @@
+export interface OnCollisionOptions {
+    json?: boolean;
+    write?: (line: string) => void;
+    now?: () => Date;
+}
+export declare function onCollision(wanted: string | undefined, options?: OnCollisionOptions): number;

package/dist/commands/organise.d.ts

@@ -0,0 +1,46 @@
+import { openSession } from "../session.ts";
+export interface OrganiseOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+/**
+ * Make a folder, and any folder above it that is missing.
+ *
+ * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience. A folder costs
+ *   nothing, holds nothing and can be moved to the trash, so the failure mode of creating one too
+ *   many is a tidy-up; the failure mode of refusing is an agent that has to discover the tree one
+ *   command at a time. Every folder made is named in the output, so it is never a surprise.
+ */
+/**
+ * Make a folder path, and every folder above it that is missing, under an OPEN session.
+ *
+ * ⛔ SPLIT OUT SO AN UPLOAD OF A WHOLE DIRECTORY CAN USE IT. The rules below are the ones a second
+ *    copy would get subtly wrong: a folder that is already there IS the folder asked for (never a
+ *    numbered one), the decision is taken inside each attempt so a lost race cannot make two, and
+ *    what was made before a failure is named rather than silently kept.
+ */
+export declare function ensureFolderPath(session: Awaited<ReturnType<typeof openSession>>, wanted: string): Promise<{
+    parentId: string | null;
+    made: string[];
+}>;
+export declare function mkdir(path: string | undefined, options?: OrganiseOptions): Promise<number>;
+/**
+ * Move things into a folder. Every operand but the last is something to move; the last is where
+ * they go, and an empty one means the top of the drive.
+ *
+ * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named. The list is rewritten whole on
+ *    every save, so a second thing costs nothing extra — while a second WRITE is a second chance
+ *    to lose the compare-and-swap, and losing it half way through a run leaves some things moved
+ *    and some not, which is a state the caller cannot tell apart from the one it asked for.
+ *
+ * ⛔ AND THE NAME CHECK RUNS AGAINST WHAT THIS RUN HAS ALREADY MOVED, not against the list as it
+ *    was read. Two files called `notes.txt` in two folders, moved into one folder by one command,
+ *    would otherwise both be written — two entries at one path, which no command in this tool can
+ *    address afterwards: every one of them answers "names 2 things in this account". So the loop
+ *    folds each move onto a working copy and asks the working copy the next question.
+ */
+export declare function mv(operands: readonly string[], options?: OrganiseOptions): Promise<number>;
+/** Give one thing a new name. The path stays the same otherwise. */
+export declare function rename(path: string | undefined, name: string | undefined, options?: OrganiseOptions): Promise<number>;

package/dist/commands/padding.d.ts

@@ -0,0 +1,7 @@
+export interface PaddingOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function padding(wanted: string | undefined, options?: PaddingOptions): Promise<number>;

package/dist/commands/padding.js

@@ -0,0 +1,114 @@
+// `nmts padding` — how coarsely a file's stored size is rounded up before it is uploaded.
+//
+// ⛔ IT IS NOT A SETTING ABOUT ENCRYPTION. The bytes are sealed either way; what this decides is
+//    how much blank space goes inside the seal, and therefore what SIZE the storage network can be
+//    seen holding. A size is the one property of a stored piece that is public no matter what, so
+//    the choice is between two rules for hiding it — or `off`, which hides nothing and stores the
+//    file at its exact size. Walrus itself stores a blob at whatever size it is handed, so this
+//    tool has to be able to as well (2026-09-06); the sentence it prints is what makes it a
+//    choice rather than a trap, and no agent gets there without asking (the act is still tiered).
+//
+// ⛔ IT LIVES IN THE SEALED FILE LIST, NOT ON THIS MACHINE. The server must not learn it — a
+//    per-account padding rule is a fingerprint a server could keep — and it follows the ACCOUNT,
+//    so a phone and a laptop pad the same way. That is why reading it costs a list read and
+//    setting it costs a list write, where `nmts on-collision` costs neither.
+//
+// ⚠ AND IT APPLIES TO WHAT IS UPLOADED NEXT. Bytes already on the storage network cannot be
+//   re-padded: they were sealed at the size they were sealed at, and nothing re-uploads them. Every
+//   sentence this command prints about a change says so.
+import { NmtsError } from "../errors.js";
+import { readFileList } from "../manifest.js";
+import { applyManyToList } from "../manifest-write.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+/**
+ * What a person types, and what the sealed list spells it as.
+ *
+ * ⚠ THE TWO VOCABULARIES ARE NOT THE SAME AND THAT IS DELIBERATE. The list's default rule is
+ *   called Padmé inside the format (`"padme"`), which is the name of an algorithm and not
+ *   something to put in front of somebody choosing a setting. On the command line the default is
+ *   `standard`, and the format's own spelling never reaches the screen.
+ */
+const WORDS = ["standard", "pow2", "off"];
+/** What each one is called in a sentence. */
+const CALLED = {
+    standard: "standard",
+    pow2: "powers of two",
+    off: "off (exact size)",
+};
+/** The word the sealed list spells each answer as. The two vocabularies never meet on screen. */
+const SPELT = {
+    standard: "padme",
+    pow2: "pow2",
+    off: "none",
+};
+function isWord(value) {
+    return WORDS.includes(value);
+}
+export async function padding(wanted, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    // ⛔ BEFORE THE NETWORK. A misspelled rule is a command line to fix, not a question to ask the
+    //    server, and rounding `pow-2` down to the default would look like it worked.
+    if (wanted !== undefined && wanted !== "" && !isWord(wanted)) {
+        throw new NmtsError(`\`${BINARY_NAME} padding\` takes standard, pow2 or off, not "${wanted}".`, {
+            exitCode: 2,
+            nextStep: `Run \`${BINARY_NAME} padding\` with no argument to see which one this account uses.`,
+        });
+    }
+    const session = await openSession({ server: options.server, network: options.network });
+    if (wanted === undefined || wanted === "") {
+        const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+        // ⛔ ANYTHING THIS BUILD DOES NOT KNOW IS THE DEFAULT, which is the same rule the uploader and
+        //    the browser read it by. A rule this build does not know is not guessed at: padding by one
+        //    nothing here can undo would give a file a size no reader can account for.
+        const stored = list.manifest?.settings?.paddingMode;
+        const at = stored === "pow2" ? "pow2" : stored === "none" ? "off" : "standard";
+        if (options.json === true) {
+            say(JSON.stringify({ padding: at }));
+            return 0;
+        }
+        if (at === "off") {
+            say(`File sizes are not hidden: a stored piece states the file's exact length.`);
+            say(`Anyone can read the size of a piece stored on the storage network, and with padding off ` +
+                `that size is the file's own.`);
+            return 0;
+        }
+        say(at === "pow2"
+            ? `File sizes are hidden with powers of two: a stored size shows as one value per doubling.`
+            : `File sizes are hidden the standard way: a stored size shows as one of a few fixed values per doubling.`);
+        say(`Anyone can read the size of a piece stored on the storage network; the blank bytes make it ` +
+            `one of a set of fixed values instead of the exact number.`);
+        return 0;
+    }
+    // ⛔ THE WRITE DECIDES WHETHER ANYTHING CHANGED, rather than a read before it. Two reads with a
+    //    write between them is a race with every other device on the account; the one write already
+    //    knows whether the setting it landed on was the one that was there.
+    const mode = SPELT[wanted];
+    // ⛔ NO LIST, NO SETTING. The mode lives inside the sealed list, and an account that has never
+    //    uploaded has no list. Writing an empty one just to hold a setting would make a first `ls`
+    //    say "a list exists" about an account nothing was ever put in — refuse instead, and say why.
+    const before = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (before.manifest === null) {
+        throw new NmtsError(`This account has no file list yet; the setting lives in the list, and there is nothing to write it into.`, { exitCode: 4, nextStep: `Upload once (\`${BINARY_NAME} put\`) and set it after.` });
+    }
+    const result = await applyManyToList(session, () => [], { paddingMode: mode });
+    if (options.json === true) {
+        say(JSON.stringify({ padding: wanted }));
+        return 0;
+    }
+    if (!result.changed) {
+        say(`Already ${CALLED[wanted]}. Nothing changed.`);
+        return 0;
+    }
+    // ⛔ TURNING IT OFF SAYS WHAT IT COSTS, not that it was set. Nothing else here gives anything
+    //    away, and a person who chose this has to be told in the same breath what is now legible —
+    //    that sentence is the confirmation, which is why there is no second question (owner: safety must not shackle the person).
+    if (wanted === "off") {
+        say(`Uploads from now on are stored at their exact size: the file's length is visible to the ` +
+            `network and to anyone who reads the blob. About 1 % less storage.`);
+        return 0;
+    }
+    say(`Set to ${CALLED[wanted]}. It applies to what is uploaded next, from every device; files ` +
+        `already uploaded keep the size they were stored at.`);
+    return 0;
+}

package/dist/commands/public-code.d.ts

@@ -0,0 +1,9 @@
+export interface PublicCodeOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Publish it, so other accounts can send to it. Permanent. */
+    publish?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function publicCode(options?: PublicCodeOptions): Promise<number>;

package/dist/commands/public-code.js

@@ -14,13 +14,13 @@
 //    says whether it can be sent to, and names the flag; `--publish` is the deliberate act.
 //
 // ⛔ WHAT "PERMANENT" DOES AND DOES NOT MEAN HERE. The record cannot be withdrawn or replaced. It
-//    is also not a choice: the code and the identity behind it are derived from the account code,
-//    so the same account code produces the same bytes on any device, and the server refuses a
+//    is also not a choice: the code and the identity behind it are derived from the NMTS key,
+//    so the same NMTS key produces the same bytes on any device, and the server refuses a
 //    bundle whose claimed value is not the fingerprint of its own root. The only way to publish a
-//    wrong one is to be holding a different account code. That is worth saying plainly rather than
+//    wrong one is to be holding a different NMTS key. That is worth saying plainly rather than
 //    warning vaguely — a warning that cannot be acted on just teaches people to click through.
 //
-// ⚠ IT IS NOT THE ACCOUNT CODE. That one opens every file in the account and must never be given
+// ⚠ IT IS NOT THE NMTS KEY. That one opens every file in the account and must never be given
 //   to anybody; this one is meant to be given away, and on its own it opens nothing.
 import { request } from "../api.js";
 import { NmtsError } from "../errors.js";
@@ -45,13 +45,13 @@ export async function publicCode(options = {}) {
     let published = isRecord(seen) && seen["published"] === true;
     // ⛔ IF THE SERVER ALREADY HOLDS A DIFFERENT ONE, STOP. Publishing is first-writer-wins and the
     //    server would refuse the write anyway, but the useful thing to report is not "the write
-    //    failed" — it is that the account code this machine is holding is not the one this account
+    //    failed" — it is that the NMTS key this machine is holding is not the one this account
     //    was made with, which is a much bigger fact than a failed request.
     const held = isRecord(seen) ? seen["share_address"] : null;
     if (typeof held === "string" && held !== mine) {
         throw new NmtsError("This account already publishes a different public code.", {
             exitCode: 4,
-            nextStep: "The public code is derived from the account code, so a different one means this machine " +
+            nextStep: "The public code is derived from the NMTS key, so a different one means this machine " +
                 "is holding a different account's code than the key beside it. Check which account you meant.",
         });
     }
@@ -73,7 +73,7 @@ export async function publicCode(options = {}) {
     if (published) {
         say(`             published — another account can send files to it`);
         say(``);
-        say(`Give it to whoever is sending. ⛔ It is NOT your account code — that one opens`);
+        say(`Give it to whoever is sending. ⛔ It is NOT your NMTS key — that one opens`);
         say(`every file you have and is never given to anybody. This one opens nothing.`);
         return 0;
     }
@@ -81,7 +81,7 @@ export async function publicCode(options = {}) {
     say(``);
     say(`Publishing writes it on the server so a sender can find the key to seal to.`);
     say(`It is permanent: it cannot be withdrawn or changed afterwards. It is also not a`);
-    say(`choice — it comes from your account code, so the same account code always gives`);
+    say(`choice — it comes from your NMTS key, so the same NMTS key always gives`);
     say(`the same public code, on this machine or any other.`);
     say(``);
     say(`  ${BINARY_NAME} public-code --publish`);

package/dist/commands/pull.d.ts

@@ -0,0 +1,27 @@
+export interface PullOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Where the tree goes. Defaults to the working directory. */
+    out?: string | undefined;
+    /** Replace files that are already there. Without it they are skipped and counted. */
+    force?: boolean;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function pull(target: string | undefined, options?: PullOptions): Promise<number>;
+/**
+ * Join a drive path onto a local directory, refusing anything that would leave it.
+ *
+ * ⛔ THE NAMES COME FROM THE SEALED LIST, which is written by whoever holds the account — including
+ *    an account somebody else set up. A name with a separator in it, or one made of dots, would
+ *    otherwise write outside the directory that was asked for, which is a file appearing somewhere
+ *    nobody chose.
+ */
+/**
+ * Where one drive path lands under `base`, or a refusal.
+ *
+ * ⚠ `platform` exists so the Windows branch can be exercised from any machine. Without it the
+ *   ordering below is only ever checked by the Windows runner, and it was wrong there for one
+ *   release.
+ */
+export declare function safeJoin(base: string, drivePath: string, platform?: NodeJS.Platform): string;

package/dist/commands/push-wallet.d.ts

@@ -0,0 +1,19 @@
+import type { OnCollision } from "../collision.ts";
+import type { openSession } from "../session.ts";
+import type { PaddingRule } from "../shared/lib/crypto/size-padding.ts";
+import type { AccountSettings } from "../shared/lib/drive/manifest-settings.ts";
+import { type PlannedFile, type PushOptions } from "./push.ts";
+/** The wallet rail, one file at a time, stopping at the first failure as the credit rail does. */
+export declare function pushWithWallet(session: Awaited<ReturnType<typeof openSession>>, options: PushOptions, run: {
+    todo: PlannedFile[];
+    already: PlannedFile[];
+    found: number;
+    bytes: number;
+    partSize: number;
+    rule: PaddingRule;
+    asked: OnCollision | undefined;
+    /** The sealed list's account settings, read once by `push.ts` — the standing tip lives in them. */
+    settings: AccountSettings | undefined;
+    folderIds: Map<string, string | null>;
+    say: (line: string) => void;
+}): Promise<number>;

package/dist/commands/push-wallet.js

@@ -0,0 +1,69 @@
+// `nmts push <directory> --pay wallet` — the wallet rail of `push`: each file priced, agreed to and
+// signed for on its own by `put-wallet.ts`, stopping at the first failure as the credit rail does.
+//
+// ⛔ SPLIT OUT OF `push.ts` FOR THE LENGTH GATE, and along the one seam that was already there:
+//    `push.ts` decides WHICH files go and where; this decides how the wallet pays for each.
+import { loadCrypto } from "../crypto.js";
+import { NmtsError } from "../errors.js";
+import { resolveNetwork } from "../network.js";
+import { Progress, silentSink, stderrSink } from "../progress.js";
+import { folderFor } from "./push.js";
+/** The wallet rail, one file at a time, stopping at the first failure as the credit rail does. */
+export async function pushWithWallet(session, options, run) {
+    const { say } = run;
+    const { uploadOneWithWallet } = await import("./put-wallet.js");
+    const ctx = {
+        code: session.code,
+        apiKey: session.apiKey,
+        server: session.server,
+        // ⛔ Narrowed, not asserted: the session carries the name as text and the rail types it.
+        network: resolveNetwork(session.server, session.network),
+        accountId: session.accountId,
+        crypt: await loadCrypto(),
+        partSize: run.partSize,
+        rule: run.rule,
+        onCollision: run.asked,
+        settings: run.settings,
+        progress: new Progress(options.json === true ? silentSink() : stderrSink(), "uploading"),
+        say,
+        json: options.json === true,
+    };
+    if (!options.json) {
+        say(`${run.todo.length} file${run.todo.length === 1 ? "" : "s"}  ${run.bytes} bytes  →  paid from the wallet, one file at a time`);
+        if (run.already.length > 0)
+            say(`  ${run.already.length} already there, not sent again`);
+    }
+    const uploaded = [];
+    try {
+        for (const one of run.todo) {
+            // ⛔ On a dry run no folder is made either: the destination is resolved only when the
+            //    upload is really going to happen, exactly as the credit rail does it.
+            const parentId = options.dryRun === true ? null : await folderFor(session, run.folderIds, one.folder);
+            if (!options.json)
+                say(`  ${one.folder}/${one.name}`);
+            const done = await uploadOneWithWallet(ctx, { localPath: one.local, size: one.size, name: one.name, parentId, destination: one.folder }, { ...options, dryRun: options.dryRun === true });
+            if (done !== null)
+                uploaded.push(`${one.folder}/${done.savedAs}`);
+        }
+    }
+    catch (error) {
+        ctx.progress.done();
+        const because = error instanceof NmtsError ? error : null;
+        throw new NmtsError(error instanceof Error ? error.message : String(error), {
+            exitCode: because?.exitCode ?? 1,
+            nextStep: uploaded.length === 0
+                ? (because?.nextStep ?? "Nothing was uploaded.")
+                : `${uploaded.length} file${uploaded.length === 1 ? " is" : "s are"} uploaded and signed for. Running the same command again sends only what is missing.`,
+        });
+    }
+    finally {
+        ctx.progress.done();
+    }
+    if (options.json) {
+        say(JSON.stringify({ files: run.found, uploaded: uploaded.length, skipped: run.already.length, bytes: run.bytes, paidFrom: "wallet", dryRun: options.dryRun === true }));
+        return 0;
+    }
+    say(``);
+    say(options.dryRun === true ? `  Nothing was signed and nothing was sent.` : `${uploaded.length} sent · ${run.already.length} already there`);
+    return 0;
+}

package/dist/commands/push.d.ts

@@ -0,0 +1,47 @@
+import { openSession } from "../session.ts";
+export interface PushOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Where the tree goes in the drive. The top of the drive when absent. */
+    to?: string | undefined;
+    /** Say what it would cost and stop. Nothing is sealed, sent, or charged. */
+    dryRun?: boolean;
+    /** Include entries whose name begins with a dot. */
+    hidden?: boolean;
+    partSize?: string | number | undefined;
+    /** What THIS run does about a name already in use. Absent = this machine's setting. */
+    onCollision?: string | undefined;
+    /** Credits EACH file in this run sets aside as a deposit, 0 to 64. Absent = the account's own. */
+    deposit?: string | number | undefined;
+    /** Who pays: `credits` (absent) or `wallet`. See `put.ts`. */
+    pay?: string | undefined;
+    /** `--pay wallet`: how many epochs to buy for every file. */
+    epochs?: string | number | undefined;
+    /** ⛔ Refused here: a held resource holds ONE blob, and a directory is many. */
+    storage?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /**
+     * Send ONE file. The real one seals, buys, uploads and records it.
+     *
+     * ⛔ A SEAM, NOT A CONVENIENCE. What is worth testing here is the decisions AROUND the upload —
+     *    which files are skipped, what is priced, and what a run says after it stops half way — and
+     *    every one of those needs a failure that costs no money to produce.
+     */
+    send?: (one: PlannedFile, parentId: string | null) => Promise<string>;
+}
+/** One local file, and where it goes in the drive. */
+export interface PlannedFile {
+    /** Absolute path on this machine. */
+    local: string;
+    /** Folder path inside the drive. */
+    folder: string;
+    name: string;
+    size: number;
+}
+export declare function push(target: string | undefined, options?: PushOptions): Promise<number>;
+/** The folder id for a drive path, made if it is not there yet. Remembered for the next file. */
+export declare function folderFor(session: Awaited<ReturnType<typeof openSession>>, known: Map<string, string | null>, folder: string): Promise<string | null>;
+export { walk as filesUnderDirectory };
+/** Every file under a local directory, with the drive folder each one belongs in. */
+declare function walk(dir: string, driveFolder: string, hidden: boolean): PlannedFile[];