@better-fs-tools/just-bash 0.0.0-tegami-trusted-publish-setup → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Andrew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,122 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# @better-fs-tools/just-bash
+
+A `WritableFileSystem` over a [just-bash](https://www.npmjs.com/package/just-bash) `IFileSystem`, for the Better Read tool and the `edit`, `write`, and `apply_patch` tools in a just-bash sandbox.
+
+## Install
+
+```sh
+npm install @better-fs-tools/just-bash @better-fs-tools/read @better-fs-tools/write just-bash
+```
+
+`just-bash` is a required peer with the range `^3.4.2`. The tests run against 3.4.2.
+
+## Example
+
+```ts
+import { InMemoryFs } from "just-bash";
+import { readOnlyFileSystem } from "@better-fs-tools/fs";
+import { justBashFileSystem } from "@better-fs-tools/just-bash";
+import { createReadTool, textOf } from "@better-fs-tools/read";
+
+const bash = new InMemoryFs({ "/workspace/src/index.ts": "const a = 1;\n" });
+
+// readOnlyFileSystem drops the write methods, so no write tool can use this view.
+const read = createReadTool({
+  fs: readOnlyFileSystem(
+    justBashFileSystem(bash, {
+      id: "sandbox",
+      cwd: "/workspace",
+      allowedRoots: ["/workspace"],
+      maxBufferedBytes: 4 * 1024 * 1024,
+    }),
+  ),
+});
+
+console.log(textOf(await read({ path: "src/index.ts" })));
+// 1|const a = 1;
+```
+
+The same filesystem, with the write tools:
+
+```ts
+import { InMemoryFs } from "just-bash";
+import { justBashFileSystem } from "@better-fs-tools/just-bash";
+import { nodeDigest } from "@better-fs-tools/node";
+import { createReadTool, memoryStore, textOf } from "@better-fs-tools/read";
+import { createEditTool, memoryLocks } from "@better-fs-tools/write";
+
+const bash = new InMemoryFs({ "/workspace/src/index.ts": "const a = 1;\n" });
+const fs = justBashFileSystem(bash, {
+  id: "sandbox",
+  cwd: "/workspace",
+  allowedRoots: ["/workspace"],
+  maxBufferedBytes: 4 * 1024 * 1024,
+});
+const shared = { fs, state: memoryStore(), digest: nodeDigest() };
+const read = createReadTool(shared);
+const edit = createEditTool({ ...shared, locks: memoryLocks() });
+
+await read({ path: "src/index.ts" });
+console.log(textOf(await edit({ path: "src/index.ts", edits: [{ oldText: "1", newText: "2" }] })));
+// Edited src/index.ts: 1 replacement at line 1.
+console.log(await bash.readFile("/workspace/src/index.ts")); // const a = 2;
+```
+
+## What the filesystem does
+
+- `justBashFileSystem(fs, options)` takes the shared `FileSystemRootOptions` and `maxBufferedBytes` from `@better-fs-tools/fs`. It checks each path against `allowedRoots` and `denyRoots` before it touches the backend, and again after `realpath()`. `cwd` must be absolute and defaults to `/`.
+- `id` defaults to `"just-bash"`. It namespaces versions, so two backends that share one state store need two ids.
+- `maxBufferedBytes` defaults to 16 MiB. `just-bash` returns whole buffers, so reads are buffered. A larger file gives `too-large`, which the tools report as `TOO_LARGE`.
+- Reads are buffered inside `open()`, so the whole file has left the backend before the read tool's `authorize` runs. The core still passes no byte to a classifier, a converter, or the model until `authorize` allows it. If a denied read must not reach the backend, deny it in the adapter with `denyRoots` or `allowedRoots`.
+- `identity` defaults to `"none"`: change detection compares size and modification time. With `identity: "required"`, the backend's `stat()` must give an identity or a device and inode for every file. A file without one is refused as `UNSUPPORTED_BACKEND`.
+- `symlinks` defaults to `"reject"`, which refuses a symlink in any component of the path, as in the Node and Cloudflare adapters. `"follow-within-roots"` follows links, and the real path must still be inside the roots.
+- The resolved options are on the filesystem as `cwd`, `allowedRoots`, `denyRoots`, `maxBufferedBytes`, `identity`, and `symlinks`.
+- For a read-only view, wrap it: `readOnlyFileSystem(justBashFileSystem(bash, options))` from `@better-fs-tools/fs` drops the write methods.
+- Backend errors are reduced to a POSIX code and a phase. Raw messages, which can contain paths, are not passed on.
+- `list()` lists directories, so suggestions and `directoryListing()` work.
+
+## How it writes
+
+`write()` needs `writeFile`, `mkdir`, `chmod`, and `utimes` on the backend, and `remove()` needs `rm`. They are checked when a write runs, not when the filesystem is built, so a backend without them still serves reads. A write to such a backend gives `unsupported`, which the tools report as `UNSUPPORTED_BACKEND`. The `fs` parameter has the type `JustBashBackend`: `lstat`, `realpath`, `stat`, `readFileBuffer`, and `readdir` are required, and `readdirWithFileTypes` and the write methods are optional. A full `IFileSystem` fits it, and so does a read-only backend, with no cast.
+
+- Writes apply the same roots, deny roots, and symlink policy as `open()`. Under `"reject"`, a symlink anywhere on the path is refused. Under `"follow-within-roots"`, a link inside the roots is followed to its real path and the link stays. A link out of the roots and a dangling link are refused.
+- `writeCapabilities` is `{ compareAndSwap: false }`. A write is `writeFile` and then `chmod`, so it is not atomic. `IFileSystem` has no version check, so the adapter checks the precondition with a fresh stat just before the write.
+- `InMemoryFs` resets the mode to `0o644` on every write, so a replace calls `chmod` with the old mode.
+- `InMemoryFs` keeps `mtime` when two writes fall in one millisecond. When a replace leaves `mtime` where it was, the adapter moves it on by one millisecond with `utimes`, so every write through the adapter changes the version.
+- `identity: "required"` makes the write tools trust the version, which is the identity, size, and `mtime`. Another writer that changes a file to the same size inside the same millisecond is then not seen. With the default, `identity: "none"`, the write tools also compare the content hash of what the model read.
+- There is no `stage()`. `apply_patch` writes each file in turn, and undoes them on a failure.
+- `EEXIST` gives `exists`, `EROFS` gives `read-only`, and `ENOSPC` and `EDQUOT` give `no-space`.
+
+## Bash runner
+
+`justBashCommandRunner(bash)` runs the `bash` tool from [`@better-fs-tools/shell`](https://www.npmjs.com/package/@better-fs-tools/shell) in a just-bash `Bash`. Nothing starts a process. stdin is empty, the tool's environment replaces the shell's own, and the cwd is set for the call only.
+
+```ts
+import { Bash } from "just-bash";
+import { justBashCommandRunner } from "@better-fs-tools/just-bash";
+import { createBashTool, shellEnv, textOf } from "@better-fs-tools/shell";
+
+// An emulated shell over an in-memory filesystem. Nothing starts a process.
+// executionLimits stop a busy loop, because no timer fires while one runs.
+const shell = new Bash({
+  files: { "/workspace/notes.txt": "one\ntwo\n" },
+  cwd: "/workspace",
+  executionLimits: { maxCommandCount: 100_000 },
+});
+
+// shellEnv() gives defaultShellEnv only: the emulated shell sees no host variables.
+const bash = createBashTool({ runner: justBashCommandRunner(shell), env: shellEnv() });
+
+console.log(textOf(await bash({ command: "wc -l notes.txt" })));
+// Exit code 0 · 0 s
+// 2 notes.txt
+```
+
+just-bash buffers output, so stdout arrives whole before stderr, after the command ends. A stop aborts at the next statement boundary. A busy loop does not yield to the event loop, so no timer fires while it runs: set `executionLimits` as the backstop. Under Bun, just-bash 3.4.2 cannot apply its defense-in-depth patches and throws on `exec()`. Pass `defenseInDepth: false` there. Node runs the default.
+
+## Links
+
+- `docs/hosts.md` in [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write): the defaults of every host and bundle, and what each backend can do
+- [`@better-fs-tools/read`](https://www.npmjs.com/package/@better-fs-tools/read): every read option
+- [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write): the write tools
+- [`@better-fs-tools/fs`](https://www.npmjs.com/package/@better-fs-tools/fs): the filesystem contract

package/dist/command-runner.d.ts

@@ -0,0 +1,18 @@
+import type { Bash } from "just-bash";
+import type { CommandRunner } from "@better-fs-tools/shell";
+/** The part of just-bash's Bash class this runner uses. */
+export type JustBashShell = Pick<Bash, "exec" | "getCwd" | "fs">;
+export interface JustBashCommandRunnerOptions {
+    /** Default "just-bash (emulated)". The bash tool description shows it. */
+    readonly id?: string;
+    /** Default bash.getCwd() when the runner is made. */
+    readonly cwd?: string;
+}
+/**
+ * Runs each command with bash.exec() in an emulated shell, without starting a
+ * process. stdin is empty, the environment replaces the shell's own, and the
+ * cwd applies to the call only. Output arrives after the command ends, stdout
+ * before stderr. A stop takes effect at the next statement, and no timeout
+ * fires during a busy loop, so set just-bash's executionLimits to bound loops.
+ */
+export declare function justBashCommandRunner(bash: JustBashShell, options?: JustBashCommandRunnerOptions): CommandRunner;

package/dist/command-runner.js

@@ -0,0 +1,68 @@
+/**
+ * Runs each command with bash.exec() in an emulated shell, without starting a
+ * process. stdin is empty, the environment replaces the shell's own, and the
+ * cwd applies to the call only. Output arrives after the command ends, stdout
+ * before stderr. A stop takes effect at the next statement, and no timeout
+ * fires during a busy loop, so set just-bash's executionLimits to bound loops.
+ */
+export function justBashCommandRunner(bash, options = {}) {
+    if (bash === null || typeof bash !== "object" || typeof bash.exec !== "function") {
+        throw new TypeError("justBashCommandRunner needs a just-bash Bash instance");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("justBashCommandRunner options must be an object");
+    }
+    const { id = "just-bash (emulated)", cwd = bash.getCwd() } = options;
+    if (typeof id !== "string" || id === "")
+        throw new TypeError("id must be a non-empty string");
+    if (typeof cwd !== "string" || !cwd.startsWith("/")) {
+        throw new TypeError("cwd must be an absolute path: just-bash has no process cwd");
+    }
+    return Object.freeze({ id, cwd, run: (request) => run(bash, request) });
+}
+function run(bash, request) {
+    const chunks = [];
+    const exit = (async () => {
+        const problem = await checkCwd(bash, request.cwd);
+        if (problem !== null)
+            return { code: null, signal: null, error: { reason: problem } };
+        try {
+            const result = await bash.exec(request.command, {
+                cwd: request.cwd,
+                env: { ...request.env },
+                replaceEnv: true,
+                stdin: "",
+                signal: request.signal,
+            });
+            const encoder = new TextEncoder();
+            if (result.stdout !== "")
+                chunks.push({ stream: "stdout", bytes: encoder.encode(result.stdout) });
+            if (result.stderr !== "")
+                chunks.push({ stream: "stderr", bytes: encoder.encode(result.stderr) });
+            if (request.signal.aborted)
+                return { code: null, signal: "SIGTERM" };
+            return { code: result.exitCode, signal: null };
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                return { code: null, signal: "SIGTERM" };
+            const detail = error instanceof Error ? error.message : String(error);
+            return { code: null, signal: null, error: { reason: "spawn-failed", detail } };
+        }
+    })();
+    const output = {
+        async *[Symbol.asyncIterator]() {
+            await exit;
+            yield* chunks;
+        },
+    };
+    return { output, exit };
+}
+async function checkCwd(bash, cwd) {
+    try {
+        return (await bash.fs.stat(cwd)).isDirectory ? null : "cwd-not-a-directory";
+    }
+    catch {
+        return "cwd-not-found";
+    }
+}

package/dist/contract.d.ts

@@ -0,0 +1,31 @@
+import type { IFileSystem } from "just-bash";
+import type { BufferedFileSystemOptions, FileSystemRootOptions, FileSystemRootSettings, ListOptions, ListOutcome, MutateOptions, MutationOutcome, WritableFileSystem } from "@better-fs-tools/fs";
+/**
+ * The part of the just-bash `IFileSystem` this package needs. Reads need
+ * `lstat`, `realpath`, `stat`, `readFileBuffer`, and `readdir`, and use
+ * `readdirWithFileTypes` when it is there. The write methods are optional, so
+ * a read-only backend fits this type and still serves reads. A full
+ * `IFileSystem` fits too.
+ */
+export type JustBashBackend = Pick<IFileSystem, "lstat" | "realpath" | "stat" | "readFileBuffer" | "readdir"> & Partial<Pick<IFileSystem, "readdirWithFileTypes" | "writeFile" | "mkdir" | "chmod" | "utimes" | "rm">>;
+/**
+ * The shared root options, with virtual paths. `cwd` must be absolute and
+ * defaults to `/`; relative roots resolve against it. `id` defaults to
+ * `"just-bash"` and namespaces versions and identities, so give two backends
+ * that share one state store two ids. `symlinks` defaults to `"reject"`, which
+ * refuses a link in any component. `identity` defaults to `"none"`.
+ * `maxBufferedBytes` defaults to 16 MiB.
+ */
+export interface JustBashFileSystemOptions extends FileSystemRootOptions, BufferedFileSystemOptions {
+}
+/**
+ * `writeCapabilities` is `{ compareAndSwap: false }`.
+ * The write methods need `writeFile`, `mkdir`, `chmod`, `utimes`, and `rm` on
+ * the backend. They are checked when a write runs, so a backend without them
+ * still serves reads.
+ */
+export interface JustBashFileSystem extends WritableFileSystem, FileSystemRootSettings {
+    readonly maxBufferedBytes: number;
+    list(path: string, options: ListOptions): Promise<ListOutcome>;
+    remove(path: string, options: MutateOptions): Promise<MutationOutcome>;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { JustBashBackend, JustBashFileSystem, JustBashFileSystemOptions } from "./contract.ts";
+export { justBashCommandRunner } from "./command-runner.ts";
+export type { JustBashCommandRunnerOptions, JustBashShell } from "./command-runner.ts";
+export type { JustBashBackend, JustBashFileSystem, JustBashFileSystemOptions } from "./contract.ts";
+/**
+ * Wraps a just-bash `IFileSystem`, or any `JustBashBackend`, as a file system
+ * for the better-fs-tools tools.
+ *
+ * `open()` reads the whole file into memory. An abort cannot stop a backend
+ * call already in progress. The `limit` of `list()` bounds the entries
+ * returned, not the backend's own directory read.
+ *
+ * `stat`, `write` and `remove` keep the same roots, deny roots and symlink
+ * policy as `open()`. `writeCapabilities` is `{ compareAndSwap: false }`.
+ * There is no `stage()`. For a
+ * read-only view, wrap the result in `readOnlyFileSystem()` from
+ * `@better-fs-tools/fs`.
+ */
+export declare function justBashFileSystem(fs: JustBashBackend, options: JustBashFileSystemOptions): JustBashFileSystem;

package/dist/index.js

@@ -0,0 +1,234 @@
+import { posixPaths, resolvePosix } from "@better-fs-tools/fs";
+import { AdapterRefusal, authorizeCanonical, authorizeRequested, backendCall, canonicalPath, directoryEntry, display, fingerprint, inspect, invalid, refuse, refuseSymlinkComponents, requireRegularFile, requireStatKey, requireWithinCeiling, statType, toFileSystemError, validateDirent, validateEntryName, validateFileSystem, validateOptions, } from "./policy.js";
+import { JUST_BASH_WRITE_CAPABILITIES, justBashWrites } from "./write.js";
+export { justBashCommandRunner } from "./command-runner.js";
+/**
+ * Wraps a just-bash `IFileSystem`, or any `JustBashBackend`, as a file system
+ * for the better-fs-tools tools.
+ *
+ * `open()` reads the whole file into memory. An abort cannot stop a backend
+ * call already in progress. The `limit` of `list()` bounds the entries
+ * returned, not the backend's own directory read.
+ *
+ * `stat`, `write` and `remove` keep the same roots, deny roots and symlink
+ * policy as `open()`. `writeCapabilities` is `{ compareAndSwap: false }`.
+ * There is no `stage()`. For a
+ * read-only view, wrap the result in `readOnlyFileSystem()` from
+ * `@better-fs-tools/fs`.
+ */
+export function justBashFileSystem(fs, options) {
+    validateFileSystem(fs);
+    const configured = validateOptions(options);
+    return Object.freeze({
+        ...readMethods(fs, configured),
+        writeCapabilities: JUST_BASH_WRITE_CAPABILITIES,
+        ...justBashWrites(fs, configured),
+    });
+}
+function readMethods(fs, configured) {
+    const { id, cwd, allowedRoots, denyRoots, maxBufferedBytes, identity, symlinks } = configured;
+    return {
+        id,
+        capabilities: Object.freeze({ identity: identity === "required" }),
+        paths: posixPaths,
+        cwd,
+        allowedRoots,
+        denyRoots,
+        maxBufferedBytes,
+        identity,
+        symlinks,
+        async open(requested, callOptions = {}) {
+            const signal = callOptions.signal;
+            if (signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            try {
+                const lexical = authorizeRequested(cwd, requested, allowedRoots, denyRoots);
+                await inspect(fs, "lstat", lexical, signal);
+                if (symlinks === "reject")
+                    await refuseSymlinkComponents(fs, lexical, signal);
+                const resolved = await canonicalPath(fs, lexical, signal);
+                authorizeCanonical(resolved, allowedRoots, denyRoots);
+                const before = await inspect(fs, "stat", resolved, signal, "stat-before");
+                requireRegularFile(before, cwd, resolved);
+                requireWithinCeiling(before.size, maxBufferedBytes, "reported object");
+                const beforeKey = requireStatKey(before, identity);
+                const backendBytes = await backendCall(() => fs.readFileBuffer(resolved), "readFileBuffer", signal);
+                if (!(backendBytes instanceof Uint8Array)) {
+                    throw invalid("readFileBuffer returned a non-Uint8Array", "readFileBuffer");
+                }
+                requireWithinCeiling(backendBytes.byteLength, maxBufferedBytes, "returned object");
+                // InMemoryFs returns its stored buffer, not a copy.
+                const bytes = Uint8Array.from(backendBytes);
+                const after = await inspect(fs, "stat", resolved, signal, "stat-after");
+                requireRegularFile(after, cwd, resolved);
+                const afterKey = requireStatKey(after, identity);
+                const beforeFingerprint = fingerprint(id, resolved, beforeKey, before);
+                const openedFingerprint = fingerprint(id, resolved, afterKey, after);
+                if (beforeFingerprint !== openedFingerprint || bytes.byteLength !== after.size) {
+                    throw refuse({
+                        reason: "io",
+                        detail: "the path changed while opening the buffered snapshot",
+                        cause: { code: "OPEN_CHANGED", phase: "open-verify" },
+                    });
+                }
+                return {
+                    ok: true,
+                    file: justBashOpenFile({
+                        fs,
+                        id,
+                        cwd,
+                        lexical,
+                        resolved,
+                        allowedRoots,
+                        denyRoots,
+                        identity,
+                        symlinks,
+                        opened: after,
+                        openedFingerprint,
+                        bytes,
+                        ...(signal === undefined ? {} : { signal }),
+                    }),
+                };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+        async list(requested, listOptions) {
+            const signal = listOptions.signal;
+            if (signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const { limit } = listOptions;
+            if (!Number.isSafeInteger(limit) || limit <= 0) {
+                return {
+                    ok: false,
+                    error: { reason: "io", detail: "list limit must be a positive safe integer" },
+                };
+            }
+            try {
+                const lexical = authorizeRequested(cwd, requested, allowedRoots, denyRoots);
+                await inspect(fs, "lstat", lexical, signal);
+                if (symlinks === "reject")
+                    await refuseSymlinkComponents(fs, lexical, signal);
+                const resolved = await canonicalPath(fs, lexical, signal);
+                authorizeCanonical(resolved, allowedRoots, denyRoots);
+                const stat = await inspect(fs, "stat", resolved, signal);
+                if (!stat.isDirectory)
+                    throw refuse({ reason: "not-found", detail: "not a directory" });
+                if (typeof fs.readdirWithFileTypes === "function") {
+                    const readdirWithFileTypes = fs.readdirWithFileTypes;
+                    const raw = await backendCall(() => readdirWithFileTypes.call(fs, resolved), "readdirWithFileTypes", signal);
+                    if (!Array.isArray(raw)) {
+                        throw invalid("readdirWithFileTypes returned a non-array", "readdirWithFileTypes");
+                    }
+                    const entries = [];
+                    for (const value of raw.slice(0, limit)) {
+                        if (signal?.aborted)
+                            throw refuse({ reason: "aborted" });
+                        entries.push(directoryEntry(validateDirent(value)));
+                    }
+                    return { ok: true, entries, truncated: raw.length > limit };
+                }
+                const raw = await backendCall(() => fs.readdir(resolved), "readdir", signal);
+                if (!Array.isArray(raw))
+                    throw invalid("readdir returned a non-array", "readdir");
+                const names = raw.slice(0, limit).map((value) => validateEntryName(value, "readdir"));
+                const entries = [];
+                for (const name of names) {
+                    const child = resolvePosix(resolved, name);
+                    if (posixPaths.dirname(child) !== resolved) {
+                        throw invalid("readdir returned an entry outside the listed directory", "readdir");
+                    }
+                    const childStat = await inspect(fs, "lstat", child, signal, "list-lstat");
+                    entries.push({ name, type: statType(childStat) });
+                }
+                return { ok: true, entries, truncated: raw.length > limit };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+    };
+}
+function justBashOpenFile(context) {
+    let consumed = false;
+    let closed = false;
+    return {
+        info: {
+            resolvedPath: context.resolved,
+            displayPath: display(context.cwd, context.resolved),
+            size: context.bytes.byteLength,
+            mtimeMs: context.opened.mtimeMs,
+            identity: context.identity === "required" ? context.openedFingerprint : null,
+            mimeType: null,
+            version: context.openedFingerprint,
+        },
+        bytes() {
+            if (consumed)
+                throw new TypeError("just-bash byte source is single-use");
+            consumed = true;
+            let sent = closed || context.bytes.byteLength === 0;
+            return {
+                [Symbol.asyncIterator]() {
+                    return {
+                        async next() {
+                            if (sent || closed || context.signal?.aborted)
+                                return { done: true, value: undefined };
+                            sent = true;
+                            return { done: false, value: context.bytes };
+                        },
+                        async return() {
+                            sent = true;
+                            return { done: true, value: undefined };
+                        },
+                    };
+                },
+            };
+        },
+        async verify() {
+            try {
+                await inspect(context.fs, "lstat", context.lexical, context.signal, "verify-lstat");
+                if (context.symlinks === "reject") {
+                    try {
+                        await refuseSymlinkComponents(context.fs, context.lexical, context.signal);
+                    }
+                    catch (error) {
+                        if (error instanceof AdapterRefusal && error.error.reason === "denied") {
+                            return { ok: true, changed: true };
+                        }
+                        throw error;
+                    }
+                }
+                const currentResolved = await canonicalPath(context.fs, context.lexical, context.signal, "verify-realpath");
+                try {
+                    authorizeCanonical(currentResolved, context.allowedRoots, context.denyRoots);
+                }
+                catch (error) {
+                    if (error instanceof AdapterRefusal)
+                        return { ok: true, changed: true };
+                    throw error;
+                }
+                if (currentResolved !== context.resolved)
+                    return { ok: true, changed: true };
+                const current = await inspect(context.fs, "stat", currentResolved, context.signal, "verify-stat");
+                if (!current.isFile)
+                    return { ok: true, changed: true };
+                const key = requireStatKey(current, context.identity);
+                return {
+                    ok: true,
+                    changed: fingerprint(context.id, context.resolved, key, current) !== context.openedFingerprint,
+                };
+            }
+            catch (error) {
+                const mapped = toFileSystemError(error);
+                if (mapped.reason === "not-found")
+                    return { ok: true, changed: true };
+                return { ok: false, error: mapped };
+            }
+        },
+        async close() {
+            closed = true;
+            consumed = true;
+        },
+    };
+}

package/dist/policy.d.ts

@@ -0,0 +1,60 @@
+import type { FsStat } from "just-bash";
+import type { DirectoryEntry, FileSystemError, IdentityMode, SymlinkPolicy } from "@better-fs-tools/fs";
+import type { JustBashBackend, JustBashFileSystemOptions } from "./contract.ts";
+export interface ValidatedStat {
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+    readonly isSymbolicLink: boolean;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly identity?: string;
+    readonly dev?: number | bigint;
+    readonly ino?: number | bigint;
+    readonly mode?: number;
+}
+export interface ValidatedDirent {
+    readonly name: string;
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+    readonly isSymbolicLink: boolean;
+}
+export interface JustBashSettings {
+    readonly id: string;
+    readonly cwd: string;
+    readonly allowedRoots: readonly string[];
+    readonly denyRoots: readonly string[];
+    readonly maxBufferedBytes: number;
+    readonly identity: IdentityMode;
+    readonly symlinks: SymlinkPolicy;
+}
+export declare function validateOptions(options: JustBashFileSystemOptions): JustBashSettings;
+export declare function validateFileSystem(fs: JustBashBackend): void;
+export declare function validateAbsolutePath(value: unknown, label: string): string;
+export declare function validateConfiguredRoot(cwd: string, value: unknown): string;
+export declare function authorizeRequested(cwd: string, requested: unknown, allowedRoots: readonly string[], denyRoots: readonly string[]): string;
+export declare function authorizeCanonical(target: string, allowedRoots: readonly string[], denyRoots: readonly string[]): void;
+export declare function canonicalPath(fs: JustBashBackend, lexical: string, signal?: AbortSignal, phase?: string): Promise<string>;
+export declare const SYMLINK_REJECTED = "a path component is a symbolic link and this adapter refuses symlinks";
+export declare function refuseSymlinkComponents(fs: JustBashBackend, lexical: string, signal?: AbortSignal): Promise<void>;
+export declare function display(cwd: string, target: string): string;
+export declare function inspect(fs: JustBashBackend, method: "stat" | "lstat", path: string, signal?: AbortSignal, phase?: string): Promise<ValidatedStat>;
+export declare function validateStat(value: FsStat, phase: string): ValidatedStat;
+export declare function validateInodePart(value: unknown, field: "dev" | "ino", phase: string): void;
+export declare function validateDirent(value: unknown): ValidatedDirent;
+export declare function validateEntryName(value: unknown, phase: string): string;
+export declare function directoryEntry(entry: ValidatedDirent): DirectoryEntry;
+export declare function statType(stat: ValidatedStat): DirectoryEntry["type"];
+export declare function requireRegularFile(stat: ValidatedStat, cwd: string, resolved: string): void;
+export declare function requireWithinCeiling(size: number, ceiling: number, subject: string): void;
+export declare function requireStatKey(stat: ValidatedStat, mode: IdentityMode): string;
+export declare function fingerprint(id: string, path: string, key: string, stat: ValidatedStat): string;
+export declare function backendCall<T>(operation: () => Promise<T> | T, phase: string, signal?: AbortSignal): Promise<T>;
+export declare function mapBackendError(error: unknown, phase: string): FileSystemError;
+export declare function portableCode(error: unknown): string;
+export declare class AdapterRefusal extends Error {
+    readonly error: FileSystemError;
+    constructor(error: FileSystemError);
+}
+export declare function refuse(error: FileSystemError): AdapterRefusal;
+export declare function invalid(detail: string, phase: string): AdapterRefusal;
+export declare function toFileSystemError(error: unknown): FileSystemError;

package/dist/policy.js

@@ -0,0 +1,341 @@
+import { containsPosix, DEFAULT_MAX_BUFFERED_BYTES, posixPaths, resolvePosix, } from "@better-fs-tools/fs";
+const MAX_IDENTITY_LENGTH = 1_024;
+export function validateOptions(options) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("justBashFileSystem options must be an object");
+    }
+    const id = options.id ?? "just-bash";
+    if (typeof id !== "string" || id === "" || id.includes("\0")) {
+        throw new TypeError("id must be a non-empty string without NUL");
+    }
+    const cwd = validateAbsolutePath(options.cwd ?? "/", "cwd");
+    if (!Array.isArray(options.allowedRoots) || options.allowedRoots.length === 0) {
+        throw new TypeError("allowedRoots must be a non-empty array");
+    }
+    const allowedRoots = Object.freeze(options.allowedRoots.map((root) => validateConfiguredRoot(cwd, root)));
+    if (options.denyRoots !== undefined && !Array.isArray(options.denyRoots)) {
+        throw new TypeError("denyRoots must be an array");
+    }
+    const denyRoots = Object.freeze((options.denyRoots ?? []).map((root) => validateConfiguredRoot(cwd, root)));
+    const maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+    if (!Number.isSafeInteger(maxBufferedBytes) || maxBufferedBytes <= 0) {
+        throw new TypeError("maxBufferedBytes must be a positive safe integer");
+    }
+    const identity = options.identity ?? "none";
+    if (identity !== "required" && identity !== "none") {
+        throw new TypeError('identity must be "required" or "none"');
+    }
+    const symlinks = options.symlinks ?? "reject";
+    if (symlinks !== "reject" && symlinks !== "follow-within-roots") {
+        throw new TypeError('symlinks must be "reject" or "follow-within-roots"');
+    }
+    return { id, cwd, allowedRoots, denyRoots, maxBufferedBytes, identity, symlinks };
+}
+export function validateFileSystem(fs) {
+    if (fs === null || typeof fs !== "object" || Array.isArray(fs)) {
+        throw new TypeError("justBashFileSystem needs an IFileSystem object");
+    }
+    const readMethods = ["lstat", "realpath", "stat", "readFileBuffer", "readdir"];
+    for (const method of readMethods) {
+        if (typeof fs[method] !== "function")
+            throw new TypeError(`the IFileSystem must implement ${method}()`);
+    }
+    if (fs.readdirWithFileTypes !== undefined && typeof fs.readdirWithFileTypes !== "function") {
+        throw new TypeError("IFileSystem readdirWithFileTypes must be a function when present");
+    }
+}
+export function validateAbsolutePath(value, label) {
+    if (typeof value !== "string" || value === "" || !value.startsWith("/") || value.includes("\0")) {
+        throw new TypeError(`${label} must be an absolute POSIX path without NUL`);
+    }
+    return resolvePosix("/", value);
+}
+export function validateConfiguredRoot(cwd, value) {
+    if (typeof value !== "string" || value === "" || value.includes("\0")) {
+        throw new TypeError("filesystem roots must be non-empty POSIX paths without NUL");
+    }
+    return resolvePosix(cwd, value);
+}
+export function authorizeRequested(cwd, requested, allowedRoots, denyRoots) {
+    if (typeof requested !== "string" || requested === "") {
+        throw refuse({ reason: "io", detail: "the requested path must be a non-empty string" });
+    }
+    if (requested.includes("\0")) {
+        throw refuse({ reason: "dangerous-path", detail: "the path contains NUL" });
+    }
+    const target = resolvePosix(cwd, requested);
+    authorizeCanonical(target, allowedRoots, denyRoots);
+    return target;
+}
+export function authorizeCanonical(target, allowedRoots, denyRoots) {
+    const denied = denyRoots.find((root) => containsPosix(root, target));
+    if (denied !== undefined)
+        throw refuse({ reason: "dangerous-path", detail: denied });
+    if (!allowedRoots.some((root) => containsPosix(root, target))) {
+        throw refuse({ reason: "outside-allowed-roots" });
+    }
+}
+export async function canonicalPath(fs, lexical, signal, phase = "realpath") {
+    const value = await backendCall(() => fs.realpath(lexical), phase, signal);
+    if (typeof value !== "string" || value === "" || !value.startsWith("/") || value.includes("\0")) {
+        throw invalid("realpath returned an invalid absolute POSIX path", phase);
+    }
+    return resolvePosix("/", value);
+}
+export const SYMLINK_REJECTED = "a path component is a symbolic link and this adapter refuses symlinks";
+export async function refuseSymlinkComponents(fs, lexical, signal) {
+    let current = "";
+    for (const segment of lexical.split("/")) {
+        if (segment === "")
+            continue;
+        current = `${current}/${segment}`;
+        let stat;
+        try {
+            stat = await inspect(fs, "lstat", current, signal, "lstat-component");
+        }
+        catch (error) {
+            if (error instanceof AdapterRefusal && error.error.reason === "not-found")
+                return;
+            throw error;
+        }
+        if (stat.isSymbolicLink)
+            throw refuse({ reason: "denied", detail: SYMLINK_REJECTED });
+    }
+}
+export function display(cwd, target) {
+    if (!containsPosix(cwd, target))
+        return target;
+    if (target === cwd)
+        return posixPaths.basename(target) || "/";
+    const relative = target.slice(cwd === "/" ? 1 : cwd.length + 1);
+    return relative === "" ? posixPaths.basename(target) || "/" : relative;
+}
+export async function inspect(fs, method, path, signal, phase = method) {
+    const value = await backendCall(() => fs[method](path), phase, signal);
+    return validateStat(value, phase);
+}
+export function validateStat(value, phase) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw invalid(`${phase} returned a non-object`, phase);
+    }
+    const stat = value;
+    for (const field of ["isFile", "isDirectory", "isSymbolicLink"]) {
+        if (typeof stat[field] !== "boolean")
+            throw invalid(`${phase} returned an invalid ${field}`, phase);
+    }
+    if ([stat.isFile, stat.isDirectory, stat.isSymbolicLink].filter(Boolean).length > 1) {
+        throw invalid(`${phase} returned conflicting entry types`, phase);
+    }
+    if (!Number.isSafeInteger(stat.size) || stat.size < 0) {
+        throw invalid(`${phase} returned an unusable size`, phase);
+    }
+    if (!(stat.mtime instanceof Date) || !Number.isFinite(stat.mtime.getTime())) {
+        throw invalid(`${phase} returned an unusable modification time`, phase);
+    }
+    if (stat.identity !== undefined &&
+        (typeof stat.identity !== "string" ||
+            stat.identity === "" ||
+            stat.identity.length > MAX_IDENTITY_LENGTH)) {
+        throw invalid(`${phase} returned an unusable identity`, phase);
+    }
+    validateInodePart(stat.dev, "dev", phase);
+    validateInodePart(stat.ino, "ino", phase);
+    return {
+        isFile: stat.isFile,
+        isDirectory: stat.isDirectory,
+        isSymbolicLink: stat.isSymbolicLink,
+        size: stat.size,
+        mtimeMs: stat.mtime.getTime(),
+        ...(typeof stat.identity === "string" ? { identity: stat.identity } : {}),
+        ...(typeof stat.dev === "number" || typeof stat.dev === "bigint" ? { dev: stat.dev } : {}),
+        ...(typeof stat.ino === "number" || typeof stat.ino === "bigint" ? { ino: stat.ino } : {}),
+        ...permissionBitsIfUsable(stat.mode),
+    };
+}
+function permissionBitsIfUsable(mode) {
+    return Number.isSafeInteger(mode) && mode >= 0
+        ? { mode: mode & 0o7777 }
+        : {};
+}
+export function validateInodePart(value, field, phase) {
+    if (value === undefined)
+        return;
+    if (typeof value === "bigint") {
+        if (value >= 0n)
+            return;
+    }
+    else if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+        return;
+    }
+    throw invalid(`${phase} returned an unusable ${field}`, phase);
+}
+export function validateDirent(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw invalid("readdirWithFileTypes returned a non-object entry", "readdirWithFileTypes");
+    }
+    const entry = value;
+    const name = validateEntryName(entry.name, "readdirWithFileTypes");
+    for (const field of ["isFile", "isDirectory", "isSymbolicLink"]) {
+        if (typeof entry[field] !== "boolean") {
+            throw invalid(`readdirWithFileTypes returned an invalid ${field}`, "readdirWithFileTypes");
+        }
+    }
+    const flags = [entry.isFile, entry.isDirectory, entry.isSymbolicLink].filter(Boolean).length;
+    if (flags > 1)
+        throw invalid("readdirWithFileTypes returned conflicting entry types", "readdirWithFileTypes");
+    return {
+        name,
+        isFile: entry.isFile,
+        isDirectory: entry.isDirectory,
+        isSymbolicLink: entry.isSymbolicLink,
+    };
+}
+export function validateEntryName(value, phase) {
+    if (typeof value !== "string" ||
+        value === "" ||
+        value === "." ||
+        value === ".." ||
+        value.includes("/") ||
+        value.includes("\0")) {
+        throw invalid(`${phase} returned an invalid entry name`, phase);
+    }
+    return value;
+}
+export function directoryEntry(entry) {
+    return {
+        name: entry.name,
+        type: entry.isFile ? "file" : entry.isDirectory ? "directory" : "other",
+    };
+}
+export function statType(stat) {
+    return stat.isFile ? "file" : stat.isDirectory ? "directory" : "other";
+}
+export function requireRegularFile(stat, cwd, resolved) {
+    if (stat.isFile)
+        return;
+    const error = {
+        reason: "not-a-file",
+        kind: stat.isDirectory ? "directory" : "other",
+        target: { resolvedPath: resolved, displayPath: display(cwd, resolved) },
+    };
+    throw refuse(error);
+}
+export function requireWithinCeiling(size, ceiling, subject) {
+    if (size > ceiling) {
+        throw refuse({
+            reason: "too-large",
+            limit: ceiling,
+            size,
+            detail: `the ${subject} exceeds the ${ceiling}-byte buffered ceiling`,
+        });
+    }
+}
+export function requireStatKey(stat, mode) {
+    if (mode === "none")
+        return `weak:${stat.size}:${stat.mtimeMs}`;
+    if (stat.identity !== undefined)
+        return `identity:${stat.identity}`;
+    if (stat.dev !== undefined && stat.ino !== undefined) {
+        return `inode:${String(stat.dev)}:${String(stat.ino)}`;
+    }
+    throw refuse({
+        reason: "unsupported",
+        detail: "the backend did not provide stable file identity",
+        cause: { code: "IDENTITY_UNAVAILABLE", phase: "stat-key" },
+    });
+}
+export function fingerprint(id, path, key, stat) {
+    return JSON.stringify([id, path, key, stat.size, stat.mtimeMs]);
+}
+export async function backendCall(operation, phase, signal) {
+    if (signal?.aborted)
+        throw refuse({ reason: "aborted", cause: { code: "ABORT_ERR", phase } });
+    try {
+        const value = await operation();
+        if (signal?.aborted)
+            throw refuse({ reason: "aborted", cause: { code: "ABORT_ERR", phase } });
+        return value;
+    }
+    catch (error) {
+        if (error instanceof AdapterRefusal)
+            throw error;
+        if (signal?.aborted)
+            throw refuse({ reason: "aborted", cause: { code: "ABORT_ERR", phase } });
+        throw refuse(mapBackendError(error, phase));
+    }
+}
+export function mapBackendError(error, phase) {
+    const code = portableCode(error);
+    const cause = { code, phase };
+    if (code === "ABORT_ERR")
+        return { reason: "aborted", cause };
+    if (code === "ENOENT" || code === "ENOTDIR")
+        return { reason: "not-found", cause };
+    if (code === "EISDIR")
+        return { reason: "not-a-file", kind: "directory", target: null, cause };
+    if (code === "EACCES")
+        return { reason: "permission-denied", cause };
+    if (code === "EPERM" || code === "ELOOP" || code === "EFBIG" || code === "ENAMETOOLONG") {
+        return { reason: "denied", cause };
+    }
+    if (code === "ENOSYS" || code === "ENOTSUP" || code === "EOPNOTSUPP") {
+        return { reason: "unsupported", cause };
+    }
+    return { reason: "io", detail: phase, cause };
+}
+// Backend messages can contain paths, so only a short error code is kept.
+export function portableCode(error) {
+    if (error !== null && typeof error === "object") {
+        try {
+            if (Object.prototype.hasOwnProperty.call(error, "code")) {
+                const code = error.code;
+                if (typeof code === "string" && /^[A-Za-z0-9_.-]{1,40}$/u.test(code))
+                    return code;
+            }
+        }
+        catch {
+            /* A hostile accessor is an unknown backend error, never a reason to leak it. */
+        }
+    }
+    try {
+        if (error instanceof Error) {
+            const message = typeof error.message === "string" ? error.message.slice(0, 64) : "";
+            const match = /^(E[A-Z]{2,12}):/u.exec(message);
+            if (match?.[1] !== undefined)
+                return match[1];
+            if (error.name === "AbortError")
+                return "ABORT_ERR";
+        }
+    }
+    catch {
+        /* Error subclasses and proxies do not get to make error mapping throw. */
+    }
+    return "UNKNOWN";
+}
+export class AdapterRefusal extends Error {
+    error;
+    constructor(error) {
+        super(error.reason);
+        this.error = error;
+        this.name = "AdapterRefusal";
+    }
+}
+export function refuse(error) {
+    return new AdapterRefusal(error);
+}
+export function invalid(detail, phase) {
+    return new AdapterRefusal({
+        reason: "io",
+        detail,
+        cause: { code: "INVALID_BACKEND_RESULT", phase },
+    });
+}
+export function toFileSystemError(error) {
+    if (error instanceof AdapterRefusal)
+        return error.error;
+    return {
+        reason: "io",
+        detail: "the just-bash adapter failed",
+        cause: { code: portableCode(error) },
+    };
+}

package/dist/write.d.ts

@@ -0,0 +1,10 @@
+import type { MutateOptions, MutationOutcome, OpenOptions, StatOutcome, WriteCapabilities, WriteOptions } from "@better-fs-tools/fs";
+import type { JustBashBackend } from "./contract.ts";
+import type { JustBashSettings } from "./policy.ts";
+export declare const JUST_BASH_WRITE_CAPABILITIES: WriteCapabilities;
+export interface JustBashWrites {
+    stat(path: string, options?: OpenOptions): Promise<StatOutcome>;
+    write(path: string, bytes: Uint8Array, options: WriteOptions): Promise<MutationOutcome>;
+    remove(path: string, options: MutateOptions): Promise<MutationOutcome>;
+}
+export declare function justBashWrites(fs: JustBashBackend, settings: JustBashSettings): JustBashWrites;

package/dist/write.js

@@ -0,0 +1,240 @@
+import { posixPaths } from "@better-fs-tools/fs";
+import { AdapterRefusal, authorizeCanonical, authorizeRequested, backendCall, canonicalPath, display, fingerprint, inspect, refuse, refuseSymlinkComponents, requireRegularFile, requireStatKey, toFileSystemError, } from "./policy.js";
+export const JUST_BASH_WRITE_CAPABILITIES = Object.freeze({
+    compareAndSwap: false,
+});
+export function justBashWrites(fs, settings) {
+    const { id, cwd, allowedRoots, denyRoots, maxBufferedBytes, identity, symlinks } = settings;
+    const lstatOrNull = async (path, signal) => {
+        try {
+            return await inspect(fs, "lstat", path, signal);
+        }
+        catch (error) {
+            if (error instanceof AdapterRefusal && error.error.reason === "not-found")
+                return null;
+            throw error;
+        }
+    };
+    const existing = async (resolved, signal) => {
+        const stat = await inspect(fs, "stat", resolved, signal);
+        requireRegularFile(stat, cwd, resolved);
+        const version = fingerprint(id, resolved, requireStatKey(stat, identity), stat);
+        return { exists: true, resolved, stat, version };
+    };
+    const locate = async (requested, signal) => {
+        const lexical = authorizeRequested(cwd, requested, allowedRoots, denyRoots);
+        if (symlinks === "reject")
+            await refuseSymlinkComponents(fs, lexical, signal);
+        const leaf = await lstatOrNull(lexical, signal);
+        if (leaf !== null) {
+            let resolved;
+            try {
+                resolved = await canonicalPath(fs, lexical, signal);
+            }
+            catch (error) {
+                if (error instanceof AdapterRefusal && error.error.reason === "not-found") {
+                    throw refuse({ reason: "denied", detail: "the path is a dangling symbolic link" });
+                }
+                throw error;
+            }
+            authorizeCanonical(resolved, allowedRoots, denyRoots);
+            return existing(resolved, signal);
+        }
+        return locateThroughNearestAncestor(lexical, signal);
+    };
+    const locateThroughNearestAncestor = async (lexical, signal) => {
+        const missing = [posixPaths.basename(lexical)];
+        let ancestor = posixPaths.dirname(lexical);
+        while ((await lstatOrNull(ancestor, signal)) === null) {
+            if (ancestor === "/")
+                throw refuse({ reason: "not-found", detail: "no ancestor exists" });
+            missing.unshift(posixPaths.basename(ancestor));
+            ancestor = posixPaths.dirname(ancestor);
+        }
+        const base = await canonicalPath(fs, ancestor, signal);
+        authorizeCanonical(base, allowedRoots, denyRoots);
+        if (!(await inspect(fs, "stat", base, signal)).isDirectory) {
+            throw refuse({ reason: "not-found", detail: "a path component is not a directory" });
+        }
+        const paths = [];
+        for (const name of missing)
+            paths.push(posixPaths.join(paths.at(-1) ?? base, name));
+        const resolved = paths.at(-1) ?? base;
+        authorizeCanonical(resolved, allowedRoots, denyRoots);
+        return { exists: false, resolved, missingDirectories: paths.slice(0, -1) };
+    };
+    const fileStat = (located) => located.exists
+        ? {
+            exists: true,
+            resolvedPath: located.resolved,
+            displayPath: display(cwd, located.resolved),
+            size: located.stat.size,
+            mtimeMs: located.stat.mtimeMs,
+            identity: identity === "required" ? located.version : null,
+            version: located.version,
+            mode: located.stat.mode ?? null,
+            hardLinks: null,
+        }
+        : {
+            exists: false,
+            resolvedPath: located.resolved,
+            displayPath: display(cwd, located.resolved),
+            missingDirectories: located.missingDirectories,
+        };
+    const makeDirectories = async (writable, directories) => {
+        const created = [];
+        for (const directory of directories) {
+            await mutate(() => writable.mkdir(directory, { recursive: true }), "mkdir");
+            const entry = await lstatOrNull(directory);
+            if (entry?.isDirectory !== true) {
+                throw refuse({ reason: "denied", detail: "a created parent is not a directory" });
+            }
+            created.push(directory);
+        }
+        return created;
+    };
+    const mutated = (resolved, after, created) => ({
+        resolvedPath: resolved,
+        displayPath: display(cwd, resolved),
+        version: after?.exists === true ? after.version : null,
+        identity: after?.exists === true && identity === "required" ? after.version : null,
+        size: after?.exists === true ? after.stat.size : null,
+        createdDirectories: created,
+    });
+    return {
+        async stat(requested, options = {}) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            try {
+                return { ok: true, stat: fileStat(await locate(requested, options.signal)) };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+        async write(requested, bytes, options) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            try {
+                const writable = requireWriteMethods(fs, WRITE_METHODS);
+                if (bytes.byteLength > maxBufferedBytes) {
+                    throw new WriteRefusal({
+                        reason: "too-large",
+                        limit: maxBufferedBytes,
+                        size: bytes.byteLength,
+                        detail: `the object exceeds the ${maxBufferedBytes}-byte buffered ceiling`,
+                    });
+                }
+                const located = await locate(requested, options.signal);
+                refuseConflict(located, options.precondition);
+                if (!located.exists && located.missingDirectories.length > 0 && !options.createParents) {
+                    throw refuse({ reason: "not-found", detail: "the parent directory does not exist" });
+                }
+                if (options.signal?.aborted)
+                    throw refuse({ reason: "aborted" });
+                const { resolved } = located;
+                const created = located.exists
+                    ? []
+                    : await makeDirectories(writable, located.missingDirectories);
+                await mutate(() => writable.writeFile(resolved, bytes), "writeFile");
+                // InMemoryFs writeFile resets the mode to 0o644.
+                const mode = located.exists ? located.stat.mode : options.mode;
+                if (mode !== undefined)
+                    await mutate(() => writable.chmod(resolved, mode), "chmod");
+                if (located.exists) {
+                    const after = await inspect(fs, "stat", resolved);
+                    // InMemoryFs keeps mtime for two writes in one millisecond.
+                    if (after.mtimeMs <= located.stat.mtimeMs) {
+                        const mtime = new Date(located.stat.mtimeMs + 1);
+                        await mutate(() => writable.utimes(resolved, mtime, mtime), "utimes");
+                    }
+                }
+                return { ok: true, file: mutated(resolved, await existing(resolved), created) };
+            }
+            catch (error) {
+                return { ok: false, error: toMutationError(error) };
+            }
+        },
+        async remove(requested, options) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            try {
+                const writable = requireWriteMethods(fs, ["rm"]);
+                const located = await locate(requested, options.signal);
+                refuseConflict(located, options.precondition);
+                if (!located.exists)
+                    throw refuse({ reason: "not-found" });
+                if (options.signal?.aborted)
+                    throw refuse({ reason: "aborted" });
+                await mutate(() => writable.rm(located.resolved), "rm");
+                return { ok: true, file: mutated(located.resolved, null, []) };
+            }
+            catch (error) {
+                return { ok: false, error: toMutationError(error) };
+            }
+        },
+    };
+}
+const WRITE_METHODS = ["writeFile", "mkdir", "chmod", "utimes"];
+function requireWriteMethods(fs, methods) {
+    for (const method of methods) {
+        if (typeof fs[method] !== "function") {
+            throw new WriteRefusal({
+                reason: "unsupported",
+                detail: `the IFileSystem has no ${method}(), so this backend cannot write`,
+            });
+        }
+    }
+    return fs;
+}
+function refuseConflict(located, precondition) {
+    switch (precondition.kind) {
+        case "absent":
+            if (located.exists)
+                throw new WriteRefusal({ reason: "exists" });
+            return;
+        case "version":
+            if (!located.exists || located.version !== precondition.version) {
+                throw new WriteRefusal({ reason: "changed" });
+            }
+            return;
+        case "any":
+            return;
+        default:
+            throw refuse({ reason: "io", detail: "unknown precondition" });
+    }
+}
+class WriteRefusal extends Error {
+    error;
+    constructor(error) {
+        super(error.reason);
+        this.error = error;
+        this.name = "WriteRefusal";
+    }
+}
+async function mutate(operation, phase) {
+    try {
+        return await backendCall(operation, phase);
+    }
+    catch (error) {
+        if (!(error instanceof AdapterRefusal))
+            throw error;
+        const code = error.error.cause?.code;
+        const cause = { code: code ?? "UNKNOWN", phase };
+        if (code === "EEXIST")
+            throw new WriteRefusal({ reason: "exists", cause });
+        if (code === "EROFS")
+            throw new WriteRefusal({ reason: "read-only", cause });
+        if (code === "ENOSPC" || code === "EDQUOT") {
+            throw new WriteRefusal({ reason: "no-space", cause });
+        }
+        throw error;
+    }
+}
+function toMutationError(error) {
+    if (error instanceof WriteRefusal)
+        return error.error;
+    if (error instanceof AdapterRefusal)
+        return error.error;
+    return toFileSystemError(error);
+}

package/package.json

@@ -1,5 +1,43 @@
 {
   "name": "@better-fs-tools/just-bash",
-  "version": "0.0.0-tegami-trusted-publish-setup",
-  "description": "Placeholder published by Tegami for npm trusted publishing setup."
+  "version": "0.2.0",
+  "description": "A readable and writable filesystem and a bash command runner over just-bash.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gingerhendrix/better-fs-tools.git",
+    "directory": "packages/just-bash"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "access": "public"
+  },
+  "dependencies": {
+    "@better-fs-tools/fs": "^0.2.0",
+    "@better-fs-tools/shell": "^0.2.0"
+  },
+  "devDependencies": {
+    "@better-fs-tools/read": "^0.2.0",
+    "@better-fs-tools/write": "^0.2.0",
+    "just-bash": "3.4.2"
+  },
+  "peerDependencies": {
+    "just-bash": "^3.4.2"
+  }
 }