@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.
- package/bin/muhkoo.js +0 -0
- package/package.json +8 -4
- package/src/commands/devices.js +58 -0
- package/src/commands/vcs.js +229 -0
- package/src/commands/vfs.js +425 -0
- package/src/index.js +9 -0
- package/src/lib/auth.js +2 -2
- package/src/lib/ignore.js +174 -0
- package/src/lib/mount.js +396 -0
- package/src/lib/syncPlan.js +54 -0
- package/src/lib/vfs.js +182 -0
package/src/lib/mount.js
ADDED
|
@@ -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
|
+
}
|