@muhkoo/cli 0.10.11-alpha.0 → 0.12.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,396 @@
1
+ /**
2
+ * `muhkoo vfs mount` — a local directory kept in step with your filesystem.
3
+ *
4
+ * Pulls a subtree to disk, then watches BOTH ends: local edits queue upward,
5
+ * remote changes arrive over the personal space's socket and land on disk.
6
+ *
7
+ * ## Why content hashes, not timestamps
8
+ *
9
+ * Every decision is made from the SHA-256 of file contents ({@link planSync}),
10
+ * never mtimes. Two reasons. Timestamps disagree across machines and survive
11
+ * round-trips badly. And hashing is what makes the echo problem disappear: when
12
+ * we write a file because the VFS changed, the resulting filesystem event
13
+ * hashes to what we just recorded, so it plans to "none" and the loop stops on
14
+ * its own. Suppression by flag or by timing window is the usual approach and it
15
+ * is fragile — an editor that rewrites the file 20ms late defeats it.
16
+ *
17
+ * ## What is deliberately not here
18
+ *
19
+ * No daemon. `mount` runs in the foreground until interrupted, like a dev
20
+ * server, because a background process needs supervision, log rotation and a
21
+ * story for "which mounts are running" that is worth more than a first version.
22
+ */
23
+
24
+ import { createHash } from "node:crypto";
25
+ import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
26
+ import { watch } from "node:fs";
27
+ import { dirname, join, relative, sep } from "node:path";
28
+
29
+ import { planSync } from "./syncPlan.js";
30
+ import { loadIgnores } from "./ignore.js";
31
+ import { info, ok, warn } from "./ui.js";
32
+
33
+ /**
34
+ * Last-resort deny-list, used only for the watcher's fast path.
35
+ *
36
+ * The real rules come from `.vcsignore` (see `./ignore.js`); this exists so a
37
+ * filesystem event under `node_modules` can be dropped without a scan.
38
+ */
39
+ const IGNORE = new Set(["node_modules", "dist", "build", "coverage", "target", "vendor", ".git"]);
40
+
41
+ /**
42
+ * Skip dot-entries by default.
43
+ *
44
+ * The first version listed known-bad names and synced everything else, which is
45
+ * backwards: the set of tool directories a machine accumulates is open-ended and
46
+ * grows without asking. It uploaded a session-tooling directory (`.remember`) to
47
+ * a user's project on first contact with a real repo — a name no deny-list would
48
+ * have contained, because it did not exist when the list was written.
49
+ *
50
+ * Dot-entries are machine state until proven otherwise. `--hidden` opts back in
51
+ * for a project that genuinely keeps source there.
52
+ */
53
+ const isHidden = (name) => name.startsWith(".");
54
+
55
+ /** Dot-files that describe the project rather than the machine. */
56
+ const KEEP_HIDDEN = new Set([".vcsignore", ".gitignore"]);
57
+
58
+ /**
59
+ * Skip anything enormous.
60
+ *
61
+ * The VFS chunks large files happily, but mounting a directory that happens to
62
+ * contain a disk image should not silently upload it. Named limit, loud skip.
63
+ */
64
+ const MAX_BYTES = 100 * 1024 * 1024;
65
+
66
+ /** Coalesce editor churn — a save is often several events in a few ms. */
67
+ const SETTLE_MS = 250;
68
+
69
+ const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
70
+
71
+ /** Where the last-synced view lives, inside the mount. */
72
+ const statePath = (dir) => join(dir, ".muhkoo", "mount.json");
73
+
74
+ /**
75
+ * The last-synced view, but ONLY if it describes the same remote root.
76
+ *
77
+ * State scoped to the directory alone is actively dangerous. It records "these
78
+ * paths were in sync", and `planSync` reads a path that is present locally and
79
+ * in the state but missing remotely as "deleted on the other side" — so pointing
80
+ * the same directory at a DIFFERENT root makes every local file look deleted,
81
+ * and with `--allow-delete` they would be. Re-rooting has to start from scratch.
82
+ */
83
+ async function loadState(dir, root) {
84
+ try {
85
+ const saved = JSON.parse(await readFile(statePath(dir), "utf8"));
86
+ // Pre-versioning files were a bare path→hash map with no root recorded.
87
+ // They cannot be shown to be about this root, so they are not trusted.
88
+ if (!saved || saved.v !== 1 || saved.root !== root) return {};
89
+ return saved.paths ?? {};
90
+ } catch {
91
+ return {}; // first sync, or someone cleared it — a full compare is safe
92
+ }
93
+ }
94
+
95
+ async function saveState(dir, root, paths) {
96
+ await mkdir(dirname(statePath(dir)), { recursive: true });
97
+ await writeFile(statePath(dir), JSON.stringify({ v: 1, root, paths }, null, 2) + "\n");
98
+ }
99
+
100
+ /** Hash every syncable file under `dir`, keyed by VFS-style relative path. */
101
+ async function scanLocal(dir, includeHidden = false, ignore = () => false) {
102
+ const out = {};
103
+ const walk = async (abs) => {
104
+ let entries;
105
+ try {
106
+ entries = await readdir(abs, { withFileTypes: true });
107
+ } catch {
108
+ return; // vanished mid-scan; the next pass will see it
109
+ }
110
+ for (const entry of entries) {
111
+ const child = join(abs, entry.name);
112
+ const rel = relative(dir, child).split(sep).join("/");
113
+ // Pruned at the directory, not per file: never descend into
114
+ // node_modules to decide, file by file, not to sync it.
115
+ if (ignore(rel, entry.isDirectory())) continue;
116
+ // `.vcsignore` and `.gitignore` describe the project and belong with
117
+ // it; every other dot-entry is machine state until asked for.
118
+ const keepDotfile = KEEP_HIDDEN.has(entry.name);
119
+ if (!includeHidden && !keepDotfile && isHidden(entry.name)) continue;
120
+ if (entry.isDirectory()) {
121
+ await walk(child);
122
+ continue;
123
+ }
124
+ if (!entry.isFile()) continue; // sockets, fifos, symlinks: not ours
125
+ try {
126
+ const info = await stat(child);
127
+ if (info.size > MAX_BYTES) {
128
+ warn(`skipping ${relative(dir, child)} — ${Math.round(info.size / 1e6)} MB is over the mount limit`);
129
+ continue;
130
+ }
131
+ out["/" + relative(dir, child).split(sep).join("/")] = sha(await readFile(child));
132
+ } catch {
133
+ // Raced with a delete or a permission change; ignore this pass.
134
+ }
135
+ }
136
+ };
137
+ await walk(dir);
138
+ return out;
139
+ }
140
+
141
+ /** Hash every file under the mounted VFS subtree. */
142
+ async function scanRemote(vfs, root) {
143
+ const out = {};
144
+ if (!(await vfs.exists(root))) return out;
145
+ for (const abs of await vfs.walk(root)) {
146
+ out[abs.slice(root.length) || "/" + abs.split("/").pop()] = sha(await vfs.readFile(abs));
147
+ }
148
+ return out;
149
+ }
150
+
151
+ /**
152
+ * Reconcile once, and return the new last-synced view.
153
+ *
154
+ * Applied sequentially rather than in parallel: writes touch one directory
155
+ * record each, and two concurrent writes to the same record would have one
156
+ * silently lose ([[VfsNamespace]] consistency note).
157
+ */
158
+ async function reconcile({ vfs, dir, root, state, opts = {} }) {
159
+ // Re-read every pass: editing `.vcsignore` should take effect on the next
160
+ // sync, not require a restart.
161
+ const { match } = await loadIgnores(dir, readFile);
162
+ const [local, remote] = await Promise.all([
163
+ scanLocal(dir, opts.hidden, match),
164
+ scanRemote(vfs, root),
165
+ ]);
166
+ const plan = planSync({ last: state, local, remote });
167
+ if (!plan.length) return state;
168
+
169
+ const next = { ...state };
170
+ for (const { path, action } of plan) {
171
+ const localAbs = join(dir, path.slice(1).split("/").join(sep));
172
+ const remoteAbs = root + path;
173
+ try {
174
+ switch (action) {
175
+ case "push": {
176
+ const bytes = await readFile(localAbs);
177
+ await vfs.writeFile(remoteAbs, new Uint8Array(bytes));
178
+ next[path] = sha(bytes);
179
+ info(`↑ ${path}`);
180
+ break;
181
+ }
182
+ case "pull": {
183
+ const bytes = await vfs.readFile(remoteAbs);
184
+ await mkdir(dirname(localAbs), { recursive: true });
185
+ await writeFile(localAbs, bytes);
186
+ next[path] = sha(bytes);
187
+ info(`↓ ${path}`);
188
+ break;
189
+ }
190
+ case "delete-remote":
191
+ // Deletes do NOT propagate unless asked for.
192
+ //
193
+ // Everything else this tool does is recoverable: an
194
+ // overwrite leaves the old version in `vfs history`. A
195
+ // delete is not — removing a file drops its history record
196
+ // along with it, so the safety net that justifies
197
+ // last-writer-wins does not cover this case. Losing a file
198
+ // to a directory you happened to clean up locally is too
199
+ // high a price for the convenience.
200
+ if (!opts.allowDelete) {
201
+ warn(
202
+ `${path} is gone locally but still in your filesystem — not deleting it.\n` +
203
+ ` Pass --allow-delete to propagate deletions, or remove it with: muhkoo vfs rm ${remoteAbs}`,
204
+ );
205
+ delete next[path]; // stop re-reporting it every pass
206
+ break;
207
+ }
208
+ await vfs.delete(remoteAbs).catch(() => {});
209
+ delete next[path];
210
+ info(`✕ ${path} (removed here)`);
211
+ break;
212
+ case "delete-local":
213
+ await rm(localAbs, { force: true });
214
+ delete next[path];
215
+ info(`✕ ${path} (removed there)`);
216
+ break;
217
+ case "forget":
218
+ delete next[path];
219
+ break;
220
+ case "conflict": {
221
+ // Local wins, because that is where the person is working —
222
+ // but say so, and say how to get the other version back. The
223
+ // VFS keeps history, so this is recoverable rather than lost,
224
+ // which is the only reason picking a winner is acceptable.
225
+ const bytes = await readFile(localAbs);
226
+ await vfs.writeFile(remoteAbs, new Uint8Array(bytes));
227
+ next[path] = sha(bytes);
228
+ warn(
229
+ `conflict on ${path} — kept your local copy.\n` +
230
+ ` The other version is still there: muhkoo vfs history ${remoteAbs}`,
231
+ );
232
+ break;
233
+ }
234
+ }
235
+ } catch (err) {
236
+ warn(`${path}: ${err?.message ?? err}`);
237
+ }
238
+ }
239
+ await saveState(dir, root, next);
240
+ return next;
241
+ }
242
+
243
+ /**
244
+ * Push a directory up once and stop — no watcher.
245
+ *
246
+ * The same scan, plan and reconcile `mount` uses, so the rules about what is
247
+ * skipped and what a delete means are defined in exactly one place. This is the
248
+ * command for "get this project into my filesystem"; `mount` is for "and keep it
249
+ * that way".
250
+ *
251
+ * One process means ONE vault unlock, which is the practical reason this exists
252
+ * rather than a shell loop over `vfs put`: unlocking per file trips the auth
253
+ * rate limiter well before a real project finishes uploading.
254
+ */
255
+ export async function importOnce({ client, dir, root, opts = {} }) {
256
+ const vfs = client.vfs;
257
+ const { match, source } = await loadIgnores(dir, readFile);
258
+ const [local, remote] = await Promise.all([
259
+ scanLocal(dir, opts.hidden, match),
260
+ scanRemote(vfs, root),
261
+ ]);
262
+ const state = await loadState(dir, root);
263
+ const plan = planSync({ last: state, local, remote });
264
+
265
+ // Say what will happen before spending metered bytes. A project directory
266
+ // is easy to point at the wrong place, and the bytes are billed either way.
267
+ //
268
+ // Sizes are stat'd here rather than carried out of `scanLocal`, which
269
+ // returns hashes — the scan is shared with `mount`, and widening its return
270
+ // shape to serve one caller's progress line is not worth the churn.
271
+ const pushes = plan.filter((p) => p.action === "push");
272
+ const bytes = (
273
+ await Promise.all(
274
+ pushes.map(async ({ path }) => {
275
+ try {
276
+ return (await stat(join(dir, path.slice(1).split("/").join(sep)))).size;
277
+ } catch {
278
+ return 0;
279
+ }
280
+ }),
281
+ )
282
+ ).reduce((n, size) => n + size, 0);
283
+
284
+ if (opts.dryRun) {
285
+ if (!plan.length) return ok(`${root} already matches ${dir}.`);
286
+ for (const { path, action } of plan) info(`${SIGN[action] ?? "?"} ${path}`);
287
+ info(`\n${plan.length} change(s); ${pushes.length} file(s) to upload, ${human(bytes)}.`);
288
+ return info(`Ignoring per ${describeSource(source)}.`);
289
+ }
290
+
291
+ if (!plan.length) return ok(`${root} already matches ${dir} — nothing to do.`);
292
+ info(`Importing ${dir} → ${root} (${pushes.length} file(s), ${human(bytes)}; ignoring per ${describeSource(source)})`);
293
+ await reconcile({ vfs, dir, root, state, opts });
294
+ ok(`Imported into ${root}.`);
295
+ await noteStateFile(dir);
296
+ }
297
+
298
+ /**
299
+ * Mention the state file, once, in a repository that is not ignoring it.
300
+ *
301
+ * `.muhkoo/mount.json` is what makes a later import or mount incremental, so it
302
+ * has to live in the directory — but appearing as an untracked directory with no
303
+ * explanation is the kind of thing people delete, or commit by accident. Saying
304
+ * it here beats editing someone's `.gitignore` for them.
305
+ */
306
+ async function noteStateFile(dir) {
307
+ try {
308
+ await stat(join(dir, ".git"));
309
+ } catch {
310
+ return; // not a repository; nothing to explain
311
+ }
312
+ try {
313
+ const ignores = await readFile(join(dir, ".gitignore"), "utf8");
314
+ if (/^\.muhkoo\/?$/m.test(ignores)) return;
315
+ } catch {
316
+ // no .gitignore: still worth mentioning
317
+ }
318
+ info(" Tracking state is in .muhkoo/ — add it to .gitignore.");
319
+ }
320
+
321
+ const SIGN = {
322
+ push: "\u2191", pull: "\u2193", conflict: "!",
323
+ "delete-remote": "\u2715", "delete-local": "\u2715", forget: "\u00b7",
324
+ };
325
+
326
+ function describeSource(source) {
327
+ if (source === "defaults") return "the built-in Node defaults (write a .vcsignore to change them)";
328
+ if (source === ".gitignore") return ".gitignore (add a .vcsignore to diverge from it)";
329
+ return source;
330
+ }
331
+
332
+ function human(bytes) {
333
+ if (bytes < 1024) return `${bytes} B`;
334
+ if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
335
+ return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
336
+ }
337
+
338
+ /**
339
+ * Mount `root` at `dir` and keep them in step until `signal` aborts.
340
+ */
341
+ export async function mount({ client, dir, root, signal, opts = {} }) {
342
+ const vfs = client.vfs;
343
+ await mkdir(dir, { recursive: true });
344
+
345
+ let state = await loadState(dir, root);
346
+ info(`Mounting ${root} → ${dir}`);
347
+ state = await reconcile({ vfs, dir, root, state, opts });
348
+ ok("In sync. Watching for changes — press Ctrl-C to stop.");
349
+
350
+ // One reconcile at a time, with a trailing pass if anything arrived while we
351
+ // were busy. Without the trailing pass a change landing mid-sync would wait
352
+ // for the NEXT unrelated event to be noticed.
353
+ let running = false;
354
+ let queued = false;
355
+ let timer = null;
356
+ const sync = async () => {
357
+ if (running) {
358
+ queued = true;
359
+ return;
360
+ }
361
+ running = true;
362
+ try {
363
+ state = await reconcile({ vfs, dir, root, state, opts });
364
+ } catch (err) {
365
+ warn(`sync failed: ${err?.message ?? err}`);
366
+ } finally {
367
+ running = false;
368
+ if (queued) {
369
+ queued = false;
370
+ void sync();
371
+ }
372
+ }
373
+ };
374
+ const schedule = () => {
375
+ clearTimeout(timer);
376
+ timer = setTimeout(() => void sync(), SETTLE_MS);
377
+ };
378
+
379
+ const watcher = watch(dir, { recursive: true }, (_event, filename) => {
380
+ // `filename` can be null on some platforms; a bare reconcile is correct
381
+ // either way, so this never has to trust it.
382
+ if (filename && filename.split(sep).some((part) => IGNORE.has(part))) return;
383
+ schedule();
384
+ });
385
+
386
+ const unwatchRemote = vfs.watch(() => schedule());
387
+
388
+ await new Promise((resolve) => {
389
+ signal.addEventListener("abort", resolve, { once: true });
390
+ });
391
+
392
+ clearTimeout(timer);
393
+ watcher.close();
394
+ unwatchRemote();
395
+ await saveState(dir, state);
396
+ }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * What to do about one path, given three views of it.
3
+ *
4
+ * Sync bugs are hard to see and expensive when they land — a wrong answer here
5
+ * silently deletes work — so the decision is a pure function of three content
6
+ * hashes and nothing else:
7
+ *
8
+ * last what we last synced (undefined: never synced)
9
+ * local what is on disk now (undefined: not there)
10
+ * remote what is in the VFS now (undefined: not there)
11
+ *
12
+ * `last` is what makes a DELETE distinguishable from a file that has simply
13
+ * never been seen. Without it, "missing on one side" is ambiguous and the only
14
+ * safe reading is to copy everything back forever.
15
+ */
16
+
17
+ /**
18
+ * @returns one of:
19
+ * "none" nothing to do
20
+ * "push" local → VFS
21
+ * "pull" VFS → local
22
+ * "delete-remote" removed locally; remove it there too
23
+ * "delete-local" removed remotely; remove it here too
24
+ * "forget" gone from both; drop it from state
25
+ * "conflict" changed on BOTH sides since the last sync
26
+ */
27
+ export function planPath({ last, local, remote }) {
28
+ if (local === undefined && remote === undefined) return last === undefined ? "none" : "forget";
29
+
30
+ if (local === undefined) {
31
+ // Only remote has it. If it matches what we last synced, the local copy
32
+ // was deleted; otherwise it is new (or changed) and should come down.
33
+ return last !== undefined && last === remote ? "delete-remote" : "pull";
34
+ }
35
+ if (remote === undefined) {
36
+ return last !== undefined && last === local ? "delete-local" : "push";
37
+ }
38
+ if (local === remote) return "none"; // identical, whatever the history
39
+
40
+ if (local === last) return "pull"; // only the remote moved
41
+ if (remote === last) return "push"; // only the local moved
42
+ return "conflict"; // both moved
43
+ }
44
+
45
+ /** Plan every path across the three views. Returns a list of {path, action}. */
46
+ export function planSync({ last, local, remote }) {
47
+ const paths = new Set([...Object.keys(last), ...Object.keys(local), ...Object.keys(remote)]);
48
+ const plan = [];
49
+ for (const path of [...paths].sort()) {
50
+ const action = planPath({ last: last[path], local: local[path], remote: remote[path] });
51
+ if (action !== "none") plan.push({ path, action });
52
+ }
53
+ return plan;
54
+ }
package/src/lib/vfs.js ADDED
@@ -0,0 +1,182 @@
1
+ /**
2
+ * Open `client.vfs` for the CLI.
3
+ *
4
+ * Uses the SDK, not raw HTTP, on purpose: the filesystem's on-disk format is
5
+ * encrypted directory records with keys chained from parent to child, and a
6
+ * second implementation over HTTP would be a second thing to keep byte-exact.
7
+ * `muhkoo vfs ls` and the IDE's file tree run the SAME code.
8
+ *
9
+ * Two things are needed: a SESSION (to authenticate the calls) and the master
10
+ * SEED (to derive the root key that decrypts the records). The session comes
11
+ * from `muhkoo login`; the seed comes from the stored key, or from a password
12
+ * prompt when there is none.
13
+ */
14
+
15
+ import { hostname, userInfo } from "node:os";
16
+
17
+ import { loadConfig, resolveBase, saveConfig } from "./config.js";
18
+ import { loadClient, downloadCircuits } from "./auth.js";
19
+ import { die, info, step, prompt, promptHidden } from "./ui.js";
20
+
21
+ /**
22
+ * Build a Client whose session and identity are both established.
23
+ *
24
+ * Returns the client so callers can reach `client.vfs` — and anything else the
25
+ * SDK offers — rather than a narrow wrapper that would drift from it.
26
+ */
27
+ export async function openClient(args) {
28
+ const cfg = await loadConfig();
29
+ const baseUrl = await resolveBase(args, cfg);
30
+ const token = args.token || process.env.MUHKOO_DEV_TOKEN || cfg.token;
31
+ if (!token) die("Not signed in. Run `muhkoo login` first.");
32
+
33
+ // Storing bytes is METERED, and the shard store attributes them to an app —
34
+ // so a write needs an app key even though the filesystem is the user's own.
35
+ // Reads do not, which is why ls and cat work with no app signed in at all.
36
+ const apiKey = resolveAppKey(args, cfg);
37
+
38
+ const Client = await loadClient();
39
+ const client = new Client({
40
+ baseUrl,
41
+ apiKey,
42
+ // Hand the SDK the session we already hold instead of logging in again.
43
+ sessionStore: {
44
+ load: () => ({ token, username: cfg.username ?? "", commitment: cfg.commitment ?? "" }),
45
+ save: () => {},
46
+ clear: () => {},
47
+ },
48
+ });
49
+
50
+ // Hydrate the session from the store BEFORE unlocking. `SessionState` loads
51
+ // its store asynchronously, so a freshly-constructed client has no commitment
52
+ // yet — and every personal-space call is addressed by commitment, so they all
53
+ // fail with "no session" until this runs. It also verifies the token, so an
54
+ // expired one says so here instead of surfacing later as a confusing
55
+ // filesystem error. Ordering matters: a failed verify clears session state,
56
+ // which would wipe a seed we had already put there.
57
+ const user = await client.auth.zk.restore();
58
+ if (!user) die("Your session has expired. Run `muhkoo login` and try again.");
59
+
60
+ await unlock({ args, cfg, baseUrl, client });
61
+
62
+ // Restore the working directory. A CLI is a fresh process each time, so `cd`
63
+ // only means anything if it survives between invocations — the same reason a
64
+ // shell keeps PWD. A directory that has since been deleted silently falls
65
+ // back to the root rather than making every later command fail.
66
+ if (cfg.vfsCwd && cfg.vfsCwd !== "/") {
67
+ await client.vfs.cd(cfg.vfsCwd).catch(async () => {
68
+ await saveConfig({ ...cfg, vfsCwd: "/" });
69
+ info(`Working directory ${cfg.vfsCwd} is gone — back to /.`);
70
+ });
71
+ }
72
+ return client;
73
+ }
74
+
75
+ /**
76
+ * Unlock the client's encryption identity.
77
+ *
78
+ * Prefers this machine's DEVICE PAIRING: the vault holds the master seed
79
+ * wrapped under a key that exists only here, so nothing on this disk IS the
80
+ * seed, and the pairing can be withdrawn from anywhere (`muhkoo devices rm`) —
81
+ * which a stored seed never could be, because nothing can reach out and
82
+ * un-store it.
83
+ *
84
+ * With no pairing, signs in once and pairs. `MUHKOO_SEED` stays supported for
85
+ * CI, where there is no interactive login to pair with.
86
+ */
87
+ async function unlock({ args, cfg, baseUrl, client }) {
88
+ if (process.env.MUHKOO_SEED) {
89
+ client.auth.zk.unlockWithSeed(process.env.MUHKOO_SEED);
90
+ return;
91
+ }
92
+
93
+ if (cfg.deviceFactorId && cfg.deviceKey && cfg.username) {
94
+ try {
95
+ await client.auth.zk.unlockWithDevice(cfg.username, cfg.deviceFactorId, cfg.deviceKey);
96
+ return;
97
+ } catch (err) {
98
+ const msg = err?.message ?? String(err);
99
+ // A REVOKED pairing is not something to retry through. Falling back to a
100
+ // password prompt would quietly re-pair a machine whose access was
101
+ // deliberately withdrawn.
102
+ if (/revoked|no longer paired/i.test(msg)) {
103
+ await saveConfig({ ...cfg, deviceFactorId: undefined, deviceKey: undefined });
104
+ die(msg);
105
+ }
106
+ info(`Stored device key did not work (${msg}) — signing in to re-pair.`);
107
+ }
108
+ }
109
+
110
+ await pairThisMachine({ args, cfg, baseUrl, client });
111
+ }
112
+
113
+ /** Sign in once, pair this machine, and unlock the passed client. */
114
+ async function pairThisMachine({ args, cfg, baseUrl, client }) {
115
+ info("This machine is not paired yet — signing in once to pair it.");
116
+ const username = args.username || cfg.username || (await prompt("Username: "));
117
+ const password = args.password || process.env.MUHKOO_PASSWORD || (await promptHidden("Password: "));
118
+ if (!username || !password) die("A username and password are required to pair this machine.");
119
+
120
+ step("Fetching ZK circuit assets…");
121
+ const circuits = await downloadCircuits(baseUrl);
122
+ const Client = await loadClient();
123
+ step("Proving identity…");
124
+ const authed = new Client({ baseUrl, circuits });
125
+ await authed.auth.zk.login(username, password);
126
+
127
+ const seed = authed.auth.zk.seedBase64;
128
+ if (!seed) die("Signed in, but no encryption key was recovered — the account may have no password factor.");
129
+
130
+ if (args.pair === false) {
131
+ client.auth.zk.unlockWithSeed(seed); // --no-pair: unlock now, store nothing
132
+ return;
133
+ }
134
+
135
+ const label = deviceLabel();
136
+ const { factorId, deviceKey } = await authed.auth.zk.enrollDevice(label);
137
+ // `seed: undefined` clears a seed left by an older CLI — the whole point is
138
+ // that it stops living on this disk.
139
+ await saveConfig({ ...cfg, username, deviceFactorId: factorId, deviceKey, seed: undefined });
140
+ client.auth.zk.unlockWithSeed(seed);
141
+ info(`Paired this machine as "${label}". Revoke it any time: muhkoo devices rm ${factorId}`);
142
+ }
143
+
144
+ /** A name the owner will recognise in `muhkoo devices ls`. */
145
+ function deviceLabel() {
146
+ return `${userInfo().username}@${hostname()}`;
147
+ }
148
+
149
+ /**
150
+ * The key to write as, from `--key`, the environment, or the app signed in with
151
+ * `muhkoo vfs use-app`.
152
+ *
153
+ * Absent is a legitimate state, not an error: reads work without one, so this
154
+ * returns undefined and lets the write itself fail with an explanation.
155
+ */
156
+ function resolveAppKey(args, cfg) {
157
+ if (args.key) return args.key;
158
+ if (process.env.MUHKOO_APP_KEY) return process.env.MUHKOO_APP_KEY;
159
+ const slug = args.app || cfg.vfsApp;
160
+ if (!slug) return undefined;
161
+ return (cfg.vfsApps ?? {})[slug];
162
+ }
163
+
164
+ /**
165
+ * Turn the shard store's 401 into an instruction.
166
+ *
167
+ * "API key required to store shards" is accurate and useless — it names a
168
+ * concept the person at the terminal has no reason to know, and says nothing
169
+ * about what to do next.
170
+ */
171
+ export function explainWriteFailure(err, cfg) {
172
+ const msg = err?.message ?? String(err);
173
+ if (!/API key required|store shards|401/.test(msg)) return msg;
174
+ const known = Object.keys(cfg?.vfsApps ?? {});
175
+ return (
176
+ "Writing stores bytes, which are metered to an app — so a write needs one signed in.\n" +
177
+ (known.length
178
+ ? `Try: muhkoo vfs use-app ${known[0]}`
179
+ : "Sign one in with: muhkoo vfs use-app <slug> --key <appKey>\n" +
180
+ "App keys are shown when an app is created (muhkoo apps create).")
181
+ );
182
+ }