Imported from pithings/mountx (AGENTS.md). Install upstream with npx skills add pithings/mountx. Copyright stays with the author.

mountx

Mount a JavaScript filesystem: one driver interface (a subset of node:fs/promises), multiple transports — FUSE, 9P, NFS (v3 and v4.1) — plus two that serve the same driver over HTTP instead of mounting it, an S3 gateway (mountx/s3) and a WebDAV server (mountx/webdav), both deliberately outside mountx/auto.

Conventions: pure JS/TS, zero runtime deps, pure-JS-first. Single package with subpath exports. Small conventional commits to main, pnpm test green before each commit. User-facing prose goes in docs/ (https://mountx.vercel.app), not in README.md, which is the npm/GitHub landing page and links there.

There is exactly one piece of native code (native/), and it exists for one reason: unprivileged FUSE mounting needs fusermount3 to hand /dev/fuse back over SCM_RIGHTS, and Node cannot recvmsg a descriptor.

Detail lives in .agents/ — start with .agents/architecture.md before changing an area you have not touched, and .agents/invariants.md for the reasoning behind any rule below that looks removable.

Layout

Every transport directory follows one shape: constants.ts (transcribed from the kernel header or RFC named in the file), protocol.ts (every message encoded and decoded), session.ts (protocol ↔ FsDriver), server.ts/mount.ts, probe.ts, index.ts.

Invariants (do not break)

Each line is the rule; .agents/invariants.md has the reasoning and the traps.

1. Zero runtime deps. unstorage is a type-only optional peer — check dist/drivers/unstorage.mjs has no import of it if that driver is touched.
2. The native addon is optional, lazy, and never on the root path. Root mounting opens /dev/fuse itself and touches no native code.
3. The embed is the only copy anything loads, and it is generated — regenerating native/prebuilt.mjs with pnpm build:native is part of any native/src/ change, not a follow-up.
4. FsDriver is a subset of node:fs/promises — const driver: FsDriver = await import("node:fs/promises") must compile with no cast.
5. Capabilities are declared-or-inferred, never faked — unmet answers ENOSYS/ENOTSUP.
6. The errno table is transcribed once, in src/errors.ts.
7. Wire constants are transcribed from the kernel headers and RFCs named in each file — never guessed, never read off host node:fs.
8. The wire's O_* and a driver's O_* are different namespaces. src/fuse/flags.ts is the one crossing; 9P imports it rather than copying it.
9. Exactly one reply per request (per COMPOUND on v4.1); handleMessage/handleCall never reject, and a thrown value becomes that transport's error reply.
10. A minor version other than 1 is refused with NFS4ERR_MINOR_VERS_MISMATCH, not guessed at.
11. No grace period on NFSv4.1 — every reclaim answers NFS4ERR_NO_GRACE, and RECLAIM_COMPLETE still gates ordinary locking.
12. The zero-copy contract. Sessions copy everything they keep before the first await; the reply path returns a view of a per-reply writer that is never written to again.
13. Decoders always copy the bytes they retain — slice is subarray. One documented exception: FuseRequest.payload.
14. No mount stacking, in either direction.
15. An unreadable mount table means "still mounted", never "gone".
16. Teardown has a deadline (unmountTimeout, default 10 s) and it is per phase over a shared Deadline, never per spawn; every spawned child is bounded and abandoned past it. Server shutdown is a step inside the phase.
17. Unmount is the transport's job to detect — no FUSE_DESTROY, no Tdestroy; EOF on /dev/fuse or on the 9P connection is the signal.
18. On macOS the umount escalation can be refused outright by the sandbox consent gate — name it (isConsentDenial/consentAdvice), never paper over it.
19. Unprivileged FUSE teardown is weaker, and says so — fusermount3 -u -z only.
20. Self-client hazard. Serving a mount and using it from the same process wedges (threadpool on FUSE, uv_spawn on both FUSE and 9P).
21. process.exit() does not work with a mount up — await unmount() and set process.exitCode.
22. Source stays NUL-free and grep-able (e.g. the cookie delimiter is "\0", the two-character string).
23. Golden fixtures give every field a distinct value — mirrored values pass with transposed encode/decode.
24. Published perf claims come only from .agents/benchmarks.md, carrying its host line.

Commands

Every Tier-2 file skips itself when the host cannot mount (nfsClientProbe(), p9ClientProbe(), rootlessProbe()) or when UV_THREADPOOL_SIZE has not been raised, so pnpm test never mounts anything. docs/ is its own project: pnpm install && pnpm dev from inside it.

More detail: .agents/*.md