@alwith/module-fs

A transport-independent filesystem contract and operation coordinator. The core has no React, DOM or Tauri dependency. Adapters enforce permissions; JavaScript capabilities only describe the UI's available actions.

Use

import { createFileSystem } from "@alwith/module-fs"
import { createMemoryAdapter } from "@alwith/module-fs/testing"
const fs = createFileSystem({
  adapter: createMemoryAdapter({ "/project/readme.md": "# Hello" }),
  reportError: error => console.error(error)
})
const stop = fs.subscribe(event => console.log(event))
await fs.writeFile("/project/readme.md", new TextEncoder().encode("# Changed"), { mode: "replace" })
stop()

Contract

• FsAdapter implements stat, byte reads/writes, directory listing, mkdir, move, copy and remove. stat returns null only for an absent path; all other errors propagate.
• WriteOptions.mode distinguishes create-only, replace-existing and upsert. expectedVersion rejects stale saves. Adapters must enforce both, not treat them as advisory.
• createFileSystem serializes mutations and transaction calls in one instance. A transaction receives a non-queuing writer; never call the outer service's mutation methods from inside a transaction or guard.
• beforeMutation can cancel move/remove/copy/mkdir. Editor controllers use it to protect unsaved deleted documents. A cancellation rejects with MutationCancelledError. A guard may return { allow, release } to hold an operation lease until commit/failure; releases always run and cannot change the disk result.
• subscribe reports committed operations. Native/watch observations have a separate source: "watch"; they are invalidations, not proof a particular UI operation committed. reportError must not throw.
• watch is optional. Hosts own and release the returned subscription. No polling or network access is started by importing the package.
• Path helpers understand POSIX, Windows drive and UNC roots. joinPath accepts a single filename and rejects traversal. Helpers are lexical; adapters still must enforce canonical/symlink boundaries. Path identity is case-sensitive; native adapters must provide consistent canonical identities.

Native distribution

Native access is the Tauri plugin alwith-fs (crates.io); the implementation is a private library shipped in this package under native/, staged by the application.

.plugin(alwith_fs::init(alwith_fs::Config { development_directory, ..Default::default() }))

Grant alwith-fs:default (open, list, stat, read, watch) and, as needed, alwith-fs:workspace-write, alwith-fs:patches, alwith-fs:git (branch, file statuses, upstream sync summary, recent commits and changed files of an opened workspace, read with gix in the library, no system git), alwith-fs:exec (workspace_exec_bash: run a typed shell command in an opened workspace with the user's login shell, killed after five minutes; not sandboxed) and alwith-fs:capability in src-tauri/capabilities/*.json. @alwith/module-fs/commands holds the generated typed commands and the workspace:change event; @alwith/module-fs/tauri builds an FsAdapter over them from a root returned by commands.workspaceOpen.

Applications that synchronize files pass a Coordinator in Config: every mutation, with its canonical write and removed paths, runs inside it one at a time; reads never wait. Rust code uses FileSystem, watch, validate_patch_path, apply_patches, the Git readers current_branch, file_statuses, sync_status, recent_commits and changed_files (blocking) and exec_bash (async), which also work without a webview after alwith_native_client::configure_host or ALWITH_NATIVE_DIRECTORY, and shares authorization and ordering through app.state::<Workspace>() (open, root, lock).

The library limits reads/writes to 16 MiB, preserves binary bytes, checks versions, uses same-directory temporary writes, rejects root mutation and mutation of terminal symbolic links, and refuses existing copy/move destinations. A recursive copy is staged before exposing the destination. Patches are validated in full (paths, symlinks, .git, hunks, size) before the first change and applied with Git without touching the index. Version checks do not provide an OS-wide transaction against arbitrary external writers. Watch errors are reported explicitly.

Develop

From the repository root: bun run --cwd packages/fs build and bun test packages/fs/src; in rust/, cargo test (bindings current; UPDATE_BINDINGS=1 regenerates them) and, with the library built, ALWITH_NATIVE_DIRECTORY=<target/debug> cargo test -- --ignored. Publish authorization is separate.