@better-fs-tools/cloudflare-computer 0.0.0-tegami-trusted-publish-setup → 0.1.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,70 @@
-# 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/cloudflare-computer
+
+A `WritableFileSystem` over a [Cloudflare Computer](https://www.npmjs.com/package/@cloudflare/computer) workspace filesystem, for the Better Read tool and the `edit`, `write`, and `apply_patch` tools.
+
+This package is experimental. Cloudflare Computer is preview software, and this adapter follows the `@cloudflare/computer` 0.2.1 declarations.
+
+## Install
+
+```sh
+npm install @better-fs-tools/cloudflare-computer @better-fs-tools/read @better-fs-tools/write
+```
+
+The package has no peers. It declares the filesystem methods that it uses as a structural type, so `Workspace["fs"]` and `WorkspaceFilesystemStub` from `@cloudflare/computer` 0.2.1 fit without an import. It imports no `node:` module.
+
+## Example
+
+```ts
+import type { Workspace } from "@cloudflare/computer";
+import { cloudflareComputerFileSystem } from "@better-fs-tools/cloudflare-computer";
+import { createReadTool } from "@better-fs-tools/read";
+
+export function computerReadTool(workspace: Workspace) {
+  return createReadTool({
+    fs: cloudflareComputerFileSystem(workspace.fs, { allowedRoots: ["/workspace"] }),
+  });
+}
+```
+
+With the write tools. `createFsTools()` from `@better-fs-tools/write` gives them and the read tool one store, one digest, and one lock manager. Its default digest, `sha256Digest()`, is plain JavaScript, so it runs in a Worker:
+
+```ts
+import type { Workspace } from "@cloudflare/computer";
+import { cloudflareComputerFileSystem } from "@better-fs-tools/cloudflare-computer";
+import { createFsTools } from "@better-fs-tools/write";
+
+// One store, one sha256Digest(), and one lock manager. createFsTools needs no
+// Node module, so it runs in a Worker.
+export function computerTools(workspace: Workspace) {
+  const fs = cloudflareComputerFileSystem(workspace.fs, { allowedRoots: ["/workspace"] });
+  const { read, edit, write } = createFsTools({ fs });
+  return { read, edit, write };
+}
+```
+
+## What the filesystem does
+
+- `cloudflareComputerFileSystem(workspace.fs, options)` takes the shared `FileSystemRootOptions` from `@better-fs-tools/fs`: `allowedRoots` (required), `denyRoots`, `cwd`, `id`, `symlinks`, and `identity`. It refuses every path outside the allowed roots, or inside a deny root, before it calls the workspace. A deny root gives `dangerous-path`, as in every adapter.
+- `cwd` must be absolute and defaults to the first allowed root. Relative paths and relative roots resolve against it. Display paths are relative to `cwd`, and absolute outside it. `id` defaults to `"cloudflare-computer"`. `symlinks` can only be `"reject"` and `identity` only `"none"`. Reads stream, so there is no `maxBufferedBytes`.
+- The filesystem exposes the resolved `cwd`, `allowedRoots`, `denyRoots`, `symlinks`, and `identity`.
+- It walks each path with `lstat` from `/`, so a symlink above the root, a symlinked root, parent, or file is refused before any byte is read.
+- It streams the file that `readFile` returns. `open()` starts the `readFile` stream, so the request reaches the backend before the read tool's `authorize` runs, but no chunk is read until `authorize` allows it. If a denied read must not reach the backend, deny it in the adapter with `denyRoots` or `allowedRoots`.
+- `verify()` compares size and modification time, so results have a `weak-identity` note.
+- `list()` lists directories, so suggestions and `directoryListing()` work.
+
+## How it writes
+
+- `stat()`, `write()`, and `remove()` use `lstat`, `writeFile`, `mkdir`, and `rm`. They check the roots and refuse every symlink on the path before any write, as `open()` does.
+- `writeFile`, `mkdir`, and `rm` are optional in `CloudflareComputerFileSystemLike`. They are checked when a write runs, not when the filesystem is built. A read-only wrapper backs the read tool, and a write to it gives `unsupported`, which the tools report as `UNSUPPORTED_BACKEND`.
+- `writeCapabilities` is `{ atomic: true, compareAndSwap: false, preserveMode: true }`. `writeFile` runs in one transaction. It has no version check, so the adapter checks the precondition with a fresh `lstat` just before the write, and the write tools add a `no-compare-and-swap` note. A create passes `exclusive: true`, so two creators cannot both win.
+- `writeFile` sets the mode to `0o644` unless it gets one, also on a replace. The adapter passes the mode that `lstat` reported, so a replace keeps it. `stat()` reports the mode.
+- There is no `stage()`: Computer has no rename. `apply_patch` writes each file in turn, and undoes them on a failure.
+- The version is the size and the modification time in milliseconds. The write tools also compare the content hash of what the model read, so a same-size change after the read is still `STALE`.
+- `EEXIST` gives `exists`, `EROFS` gives `read-only`, and `ENOSPC` and `EDQUOT` give `no-space`.
+
+## 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/contract.d.ts

@@ -0,0 +1,70 @@
+import type { FileSystemRootOptions, FileSystemRootSettings, ListOptions, ListOutcome, MutateOptions, MutationOutcome, WritableFileSystem } from "@better-fs-tools/fs";
+/**
+ * A file's metadata as Computer's `stat` and `lstat` return it. A structural
+ * subset of `WorkspaceStatResult`.
+ */
+export interface CloudflareComputerStat {
+    name: string;
+    /** Epoch milliseconds. */
+    mtime: number;
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    /** Permission bits. When absent, `stat()` reports a `null` mode. */
+    mode?: number;
+}
+/** A structural subset of Computer's `WorkspaceDirentResult`. */
+export interface CloudflareComputerDirent {
+    name: string;
+    parentPath: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+/**
+ * The filesystem methods this adapter uses. `WorkspaceFilesystem` and
+ * `WorkspaceFilesystemStub` from `@cloudflare/computer@0.2.1` both satisfy it.
+ *
+ * The write methods are optional: a filesystem without them still serves
+ * reads, and a write reports `unsupported`.
+ */
+export interface CloudflareComputerFileSystemLike {
+    readFile(path: string): Promise<ReadableStream<Uint8Array>>;
+    stat(path: string): Promise<CloudflareComputerStat>;
+    lstat(path: string): Promise<CloudflareComputerStat>;
+    readdir(path: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<CloudflareComputerDirent[]>;
+    /** With `exclusive`, fails with `EEXIST` when the file exists. */
+    writeFile?(path: string, content: Uint8Array, options?: {
+        mode?: number;
+        exclusive?: boolean;
+    }): Promise<void>;
+    mkdir?(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    rm?(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+}
+/**
+ * The shared root options, with workspace paths. `allowedRoots` holds absolute
+ * paths, or paths relative to `cwd`. `cwd` must be absolute and defaults to the
+ * first allowed root. `symlinks` can only be `"reject"` and `identity` only
+ * `"none"`. `id` defaults to `"cloudflare-computer"`. Reads stream, so there is
+ * no `maxBufferedBytes`.
+ */
+export interface CloudflareComputerFileSystemOptions extends FileSystemRootOptions<"reject", "none"> {
+}
+/**
+ * A writable filesystem over a Cloudflare Computer workspace. Writes are atomic
+ * and keep the file mode. There is no compare-and-swap and no `stage()`.
+ */
+export interface CloudflareComputerFileSystem extends WritableFileSystem, FileSystemRootSettings<"reject", "none"> {
+    list(path: string, options: ListOptions): Promise<ListOutcome>;
+    remove(path: string, options: MutateOptions): Promise<MutationOutcome>;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { CloudflareComputerFileSystem, CloudflareComputerFileSystemLike, CloudflareComputerFileSystemOptions } from "./contract.ts";
+export type { CloudflareComputerDirent, CloudflareComputerFileSystem, CloudflareComputerFileSystemLike, CloudflareComputerFileSystemOptions, CloudflareComputerStat, } from "./contract.ts";
+/**
+ * Adapt a Cloudflare Computer workspace filesystem to the filesystem contract.
+ *
+ * @experimental Cloudflare Computer is preview software and this adapter is
+ * pinned to the `0.2.1` declarations.
+ */
+export declare function cloudflareComputerFileSystem(workspaceFs: CloudflareComputerFileSystemLike, options: CloudflareComputerFileSystemOptions): CloudflareComputerFileSystem;

package/dist/index.js

@@ -0,0 +1,211 @@
+import { posixPaths } from "@better-fs-tools/fs";
+import { authorize, call, cancelWithoutWaiting, pathsFromSlashToTarget, displayPath, inspect, invalid, notAFile, refuse, resolveRoots, toFileSystemError, validateDirent, validateFileSystem, validateStream, } from "./policy.js";
+import { COMPUTER_WRITE_CAPABILITIES, computerVersion, computerWrites } from "./write.js";
+/**
+ * Adapt a Cloudflare Computer workspace filesystem to the filesystem contract.
+ *
+ * @experimental Cloudflare Computer is preview software and this adapter is
+ * pinned to the `0.2.1` declarations.
+ */
+export function cloudflareComputerFileSystem(workspaceFs, options) {
+    validateFileSystem(workspaceFs);
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("cloudflareComputerFileSystem options must be an object");
+    }
+    const roots = resolveRoots(options);
+    const { cwd } = roots;
+    const id = options.id ?? "cloudflare-computer";
+    if (typeof id !== "string" || id === "")
+        throw new TypeError("id must be a non-empty string");
+    const refuseSymlinksAlongPath = async (target) => {
+        for (const component of pathsFromSlashToTarget(target)) {
+            const stat = await inspect(workspaceFs, "lstat", component, component !== target);
+            if (stat.isSymbolicLink) {
+                throw refuse({
+                    reason: "denied",
+                    detail: component === target
+                        ? "the path is a symbolic link and this adapter refuses symlinks"
+                        : "a path component is a symbolic link and this adapter refuses symlinks",
+                });
+            }
+            if (component !== target && !stat.isDirectory) {
+                throw refuse({ reason: "not-found", detail: "a path component is not a directory" });
+            }
+            if (component === target)
+                return stat;
+        }
+        throw refuse(notAFile("directory", cwd, target));
+    };
+    return Object.freeze({
+        id,
+        capabilities: Object.freeze({ streaming: true, identity: false }),
+        paths: posixPaths,
+        cwd,
+        allowedRoots: roots.allowedRoots,
+        denyRoots: roots.denyRoots,
+        symlinks: "reject",
+        identity: "none",
+        writeCapabilities: COMPUTER_WRITE_CAPABILITIES,
+        ...computerWrites(workspaceFs, roots),
+        async open(requested, callOptions = {}) {
+            const signal = callOptions.signal;
+            if (signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            try {
+                const { target } = authorize(roots, requested);
+                await refuseSymlinksAlongPath(target);
+                const stat = await inspect(workspaceFs, "stat", target, false);
+                if (!stat.isFile) {
+                    throw refuse(notAFile(stat.isDirectory ? "directory" : "other", cwd, target));
+                }
+                if (signal?.aborted)
+                    throw refuse({ reason: "aborted" });
+                /* Exactly one argument: other overloads buffer or return a string. */
+                const stream = await call(workspaceFs.readFile(target), "readFile");
+                validateStream(stream);
+                if (signal?.aborted) {
+                    cancelWithoutWaiting(stream);
+                    throw refuse({ reason: "aborted" });
+                }
+                return { ok: true, file: computerOpenFile(workspaceFs, cwd, target, stat, stream) };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+        async list(requested, listOptions) {
+            if (listOptions.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const limit = listOptions.limit;
+            if (!Number.isSafeInteger(limit) || limit <= 0) {
+                return {
+                    ok: false,
+                    error: { reason: "io", detail: "list limit must be a positive safe integer" },
+                };
+            }
+            try {
+                const { target } = authorize(roots, requested);
+                const stat = target === "/" ? null : await refuseSymlinksAlongPath(target);
+                if (stat !== null && !stat.isDirectory) {
+                    throw refuse({ reason: "not-found", detail: "not a directory" });
+                }
+                const oneMoreThanLimit = limit + 1;
+                const listed = await call(workspaceFs.readdir(target, { limit: oneMoreThanLimit, offset: 0 }), "readdir");
+                if (!Array.isArray(listed))
+                    throw invalid("readdir returned a non-array", "readdir");
+                const entries = [];
+                for (const value of listed.slice(0, limit)) {
+                    entries.push(validateDirent(value, target));
+                }
+                return { ok: true, entries, truncated: listed.length > limit };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+    });
+}
+function computerOpenFile(workspaceFs, cwd, target, stat, stream) {
+    let consumed = false;
+    let closed = false;
+    let reader = null;
+    /* Not awaited: an RPC stub's cancel() may never settle once its peer is gone. */
+    const release = () => {
+        closed = true;
+        const held = reader;
+        reader = null;
+        try {
+            if (held === null) {
+                void Promise.resolve(stream.cancel()).catch(() => { });
+                return;
+            }
+            void Promise.resolve(held.cancel()).catch(() => { });
+            /* A spec-compliant reader releases on cancel, an RPC stub may not. */
+            try {
+                held.releaseLock();
+            }
+            catch {
+                /* Best effort. */
+            }
+        }
+        catch {
+            /* Best effort. */
+        }
+    };
+    return {
+        info: {
+            resolvedPath: target,
+            displayPath: displayPath(cwd, target),
+            size: stat.size,
+            mtimeMs: stat.mtime,
+            identity: null,
+            mimeType: null,
+            version: computerVersion(stat),
+        },
+        bytes() {
+            if (consumed)
+                throw new TypeError("cloudflare computer byte source is single-use");
+            consumed = true;
+            return {
+                [Symbol.asyncIterator]() {
+                    return {
+                        async next() {
+                            if (closed)
+                                return { done: true, value: undefined };
+                            const active = reader ?? (reader = acquireValidReader(stream));
+                            const item = await active.read();
+                            if (item === null || typeof item !== "object" || typeof item.done !== "boolean") {
+                                throw new TypeError("Cloudflare Computer's reader returned an invalid result");
+                            }
+                            if (item.done) {
+                                release();
+                                return { done: true, value: undefined };
+                            }
+                            if (!(item.value instanceof Uint8Array)) {
+                                throw new TypeError("Cloudflare Computer's stream yielded a non-Uint8Array chunk");
+                            }
+                            return { done: false, value: item.value };
+                        },
+                        async return() {
+                            release();
+                            return { done: true, value: undefined };
+                        },
+                    };
+                },
+            };
+        },
+        async verify() {
+            try {
+                const current = await inspect(workspaceFs, "lstat", target, false);
+                const changed = current.isFile !== stat.isFile ||
+                    current.isDirectory !== stat.isDirectory ||
+                    current.isSymbolicLink !== stat.isSymbolicLink ||
+                    current.size !== stat.size ||
+                    current.mtime !== stat.mtime;
+                return { ok: true, changed };
+            }
+            catch (error) {
+                const mapped = toFileSystemError(error);
+                if (mapped.reason === "not-found")
+                    return { ok: true, changed: true };
+                return { ok: false, error: mapped };
+            }
+        },
+        async close() {
+            consumed = true;
+            if (closed)
+                return;
+            release();
+        },
+    };
+}
+function acquireValidReader(stream) {
+    const reader = stream.getReader();
+    if (reader === null ||
+        typeof reader !== "object" ||
+        typeof reader.read !== "function" ||
+        typeof reader.cancel !== "function") {
+        throw new TypeError("Cloudflare Computer's stream returned an unusable reader");
+    }
+    return reader;
+}

package/dist/policy.d.ts

@@ -0,0 +1,32 @@
+import type { DirectoryEntry, FileSystemError, FileSystemRootOptions, NotAFileError } from "@better-fs-tools/fs";
+import type { CloudflareComputerFileSystemLike, CloudflareComputerStat } from "./contract.ts";
+export interface Roots {
+    readonly cwd: string;
+    readonly allowedRoots: readonly string[];
+    readonly denyRoots: readonly string[];
+}
+export declare function resolveRoots(options: FileSystemRootOptions<"reject", "none">): Roots;
+export declare function pathsFromSlashToTarget(target: string): string[];
+export declare function authorize(roots: Roots, requested: unknown): {
+    readonly root: string;
+    readonly target: string;
+};
+export declare function displayPath(cwd: string, target: string): string;
+export declare function notAFile(kind: NotAFileError["kind"], cwd: string, target: string): NotAFileError;
+export declare function inspect(workspaceFs: CloudflareComputerFileSystemLike, method: "stat" | "lstat", path: string, isAncestorComponent: boolean): Promise<CloudflareComputerStat>;
+export declare function validateStat(value: unknown, path: string, phase: string): CloudflareComputerStat;
+export declare function validateDirent(value: unknown, parent: string): DirectoryEntry;
+export declare function typeFlags(entry: Record<string, unknown>, phase: string): [boolean, boolean, boolean];
+export declare function validateStream(value: unknown): asserts value is ReadableStream<Uint8Array>;
+export declare function cancelWithoutWaiting(stream: ReadableStream<Uint8Array>): void;
+export declare function call<T>(pending: Promise<T> | T, phase: string): Promise<T>;
+export declare function mapBackendError(error: unknown, phase: string): FileSystemError;
+export declare function boundedCode(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;
+export declare function validateFileSystem(workspaceFs: CloudflareComputerFileSystemLike): void;

package/dist/policy.js

@@ -0,0 +1,259 @@
+import { containsPosix, posixPaths, resolvePosix } from "@better-fs-tools/fs";
+export function resolveRoots(options) {
+    const base = options.cwd === undefined ? "/" : absolutePath(options.cwd, "cwd");
+    const allowed = options.allowedRoots;
+    if (!Array.isArray(allowed) || allowed.length === 0) {
+        throw new TypeError("allowedRoots must be a non-empty array");
+    }
+    const allowedRoots = Object.freeze(allowed.map((root) => configuredRoot(base, 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) => configuredRoot(base, root)));
+    if (options.symlinks !== undefined && options.symlinks !== "reject") {
+        throw new TypeError('symlinks must be "reject": this adapter refuses every symbolic link');
+    }
+    if (options.identity !== undefined && options.identity !== "none") {
+        throw new TypeError('identity must be "none": a Computer inode is not a stable identity');
+    }
+    return { cwd: options.cwd === undefined ? allowedRoots[0] : base, allowedRoots, denyRoots };
+}
+function absolutePath(value, label) {
+    if (typeof value !== "string" || !value.startsWith("/") || value.includes("\0")) {
+        throw new TypeError(`${label} must be an absolute POSIX path without NUL`);
+    }
+    return resolvePosix("/", value);
+}
+function configuredRoot(base, value) {
+    if (typeof value !== "string" || value === "" || value.includes("\0")) {
+        throw new TypeError("filesystem roots must be non-empty POSIX paths without NUL");
+    }
+    return resolvePosix(base, value);
+}
+export function pathsFromSlashToTarget(target) {
+    const found = [];
+    let current = "";
+    for (const segment of target.split("/")) {
+        if (segment === "")
+            continue;
+        current = `${current}/${segment}`;
+        found.push(current);
+    }
+    return found;
+}
+export function authorize(roots, requested) {
+    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(roots.cwd, requested);
+    const denied = roots.denyRoots.find((root) => containsPosix(root, target));
+    if (denied !== undefined)
+        throw refuse({ reason: "dangerous-path", detail: denied });
+    const innermostRoot = innermostAllowedRoot(roots, target);
+    if (innermostRoot === null)
+        throw refuse({ reason: "outside-allowed-roots" });
+    return { root: innermostRoot, target };
+}
+function innermostAllowedRoot(roots, target) {
+    let root = null;
+    for (const candidate of roots.allowedRoots) {
+        if (containsPosix(candidate, target) && (root === null || candidate.length > root.length)) {
+            root = candidate;
+        }
+    }
+    return root;
+}
+export function displayPath(cwd, target) {
+    if (!containsPosix(cwd, target))
+        return target;
+    if (target === cwd)
+        return posixPaths.basename(target) || "/";
+    return target.slice(cwd === "/" ? 1 : cwd.length + 1);
+}
+export function notAFile(kind, cwd, target) {
+    return {
+        reason: "not-a-file",
+        kind,
+        target: { resolvedPath: target, displayPath: displayPath(cwd, target) },
+    };
+}
+export async function inspect(workspaceFs, method, path, isAncestorComponent) {
+    let value;
+    try {
+        value = await call(workspaceFs[method](path), method);
+    }
+    catch (error) {
+        if (isAncestorComponent &&
+            error instanceof AdapterRefusal &&
+            error.error.reason === "not-found") {
+            throw refuse({ ...error.error, detail: "a path component does not exist" });
+        }
+        throw error;
+    }
+    return validateStat(value, path, method);
+}
+export function validateStat(value, path, phase) {
+    if (value === null || value === undefined || typeof value !== "object" || Array.isArray(value)) {
+        throw invalid(`${phase} did not return an entry`, phase);
+    }
+    const entry = value;
+    if (typeof entry.name !== "string" || entry.name === "" || entry.name.includes("\0")) {
+        throw invalid(`${phase} returned an entry without a usable name`, phase);
+    }
+    /* Computer's name for the root "/" is unconfirmed, so it is not compared. */
+    const expected = path === "/" ? null : posixPaths.basename(path);
+    if (expected !== null && entry.name !== expected) {
+        throw invalid(`${phase} returned an entry for a different path`, phase);
+    }
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
+        throw invalid(`${phase} returned an unusable size`, phase);
+    }
+    if (typeof entry.mtime !== "number" || !Number.isFinite(entry.mtime)) {
+        throw invalid(`${phase} returned an unusable modification time`, phase);
+    }
+    const [isFile, isDirectory, isSymbolicLink] = typeFlags(entry, phase);
+    /* An unusable mode is dropped, not refused, so reads keep working. */
+    const mode = Number.isSafeInteger(entry.mode) && entry.mode >= 0
+        ? entry.mode & 0o7777
+        : undefined;
+    return {
+        name: entry.name,
+        size: entry.size,
+        mtime: entry.mtime,
+        isFile,
+        isDirectory,
+        isSymbolicLink,
+        ...(mode === undefined ? {} : { mode }),
+    };
+}
+export function validateDirent(value, parent) {
+    if (value === null || value === undefined || typeof value !== "object" || Array.isArray(value)) {
+        throw invalid("readdir returned an entry that is not an object", "readdir");
+    }
+    const entry = value;
+    if (typeof entry.parentPath !== "string" || resolvePosix("/", entry.parentPath) !== parent) {
+        throw invalid("readdir returned an entry outside the listed directory", "readdir");
+    }
+    const name = entry.name;
+    if (typeof name !== "string" ||
+        name === "" ||
+        name === "." ||
+        name === ".." ||
+        name.includes("/") ||
+        name.includes("\0")) {
+        throw invalid("readdir returned an entry without a usable name", "readdir");
+    }
+    const [isFile, isDirectory] = typeFlags(entry, "readdir");
+    return { name, type: isFile ? "file" : isDirectory ? "directory" : "other" };
+}
+export function typeFlags(entry, phase) {
+    for (const flag of ["isFile", "isDirectory", "isSymbolicLink"]) {
+        if (typeof entry[flag] !== "boolean") {
+            throw invalid(`${phase} returned an unusable ${flag} flag`, phase);
+        }
+    }
+    const flags = [
+        entry.isFile,
+        entry.isDirectory,
+        entry.isSymbolicLink,
+    ];
+    if (flags.filter(Boolean).length !== 1) {
+        throw invalid(`${phase} did not identify exactly one entry type`, phase);
+    }
+    return flags;
+}
+export function validateStream(value) {
+    if (value === null ||
+        typeof value !== "object" ||
+        typeof value.getReader !== "function" ||
+        typeof value.cancel !== "function") {
+        throw invalid("readFile did not return a ReadableStream", "readFile");
+    }
+}
+export function cancelWithoutWaiting(stream) {
+    try {
+        void Promise.resolve(stream.cancel()).catch(() => { });
+    }
+    catch {
+        /* Best effort. */
+    }
+}
+export async function call(pending, phase) {
+    try {
+        return await pending;
+    }
+    catch (error) {
+        if (error instanceof AdapterRefusal)
+            throw error;
+        throw refuse(mapBackendError(error, phase));
+    }
+}
+export function mapBackendError(error, phase) {
+    const code = boundedCode(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" || code === "EPERM")
+        return { reason: "permission-denied", cause };
+    if (code === "ELOOP")
+        return { reason: "denied", detail: "too many symbolic links", cause };
+    if (code === "EINVAL") {
+        return { reason: "dangerous-path", detail: "the backend rejected the path", cause };
+    }
+    return { reason: "io", detail: phase, cause };
+}
+export function boundedCode(error) {
+    if (error !== null && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        if (typeof code === "string" && /^[A-Za-z0-9_.-]{1,40}$/u.test(code))
+            return code;
+    }
+    if (error instanceof Error && error.name === "AbortError")
+        return "ABORT_ERR";
+    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 Cloudflare Computer filesystem adapter failed",
+        cause: { code: boundedCode(error) },
+    };
+}
+export function validateFileSystem(workspaceFs) {
+    if (workspaceFs === null || typeof workspaceFs !== "object" || Array.isArray(workspaceFs)) {
+        throw new TypeError("cloudflareComputerFileSystem needs a Cloudflare Computer workspace filesystem");
+    }
+    const methods = ["readFile", "stat", "lstat", "readdir"];
+    for (const method of methods) {
+        if (typeof workspaceFs[method] !== "function") {
+            throw new TypeError(`the Computer workspace filesystem must implement ${method}()`);
+        }
+    }
+}

package/dist/write.d.ts

@@ -0,0 +1,11 @@
+import type { MutateOptions, MutationOutcome, OpenOptions, StatOutcome, WriteCapabilities, WriteOptions } from "@better-fs-tools/fs";
+import type { CloudflareComputerFileSystemLike, CloudflareComputerStat } from "./contract.ts";
+import type { Roots } from "./policy.ts";
+export declare const COMPUTER_WRITE_CAPABILITIES: WriteCapabilities;
+export interface ComputerWrites {
+    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 computerVersion(entry: CloudflareComputerStat): string;
+export declare function computerWrites(workspaceFs: CloudflareComputerFileSystemLike, roots: Roots): ComputerWrites;

package/dist/write.js

@@ -0,0 +1,223 @@
+import { containsPosix } from "@better-fs-tools/fs";
+import { AdapterRefusal, authorize, boundedCode, pathsFromSlashToTarget, displayPath, inspect, mapBackendError, notAFile, refuse, toFileSystemError, } from "./policy.js";
+export const COMPUTER_WRITE_CAPABILITIES = Object.freeze({
+    atomic: true,
+    compareAndSwap: false,
+    preserveMode: true,
+});
+export function computerVersion(entry) {
+    return `computer:${entry.size}:${entry.mtime}`;
+}
+export function computerWrites(workspaceFs, roots) {
+    const { cwd } = roots;
+    const locate = async (root, target) => {
+        const missing = [];
+        for (const component of pathsFromSlashToTarget(target)) {
+            if (missing.length > 0) {
+                missing.push(component);
+                continue;
+            }
+            const entry = await lstatOrNull(component);
+            if (entry === null) {
+                if (containsPosix(component, root)) {
+                    throw refuse({ reason: "not-found", detail: "the root does not exist" });
+                }
+                missing.push(component);
+                continue;
+            }
+            if (entry.isSymbolicLink) {
+                throw refuse({
+                    reason: "denied",
+                    detail: component === target
+                        ? "the path is a symbolic link and this adapter refuses symlinks"
+                        : "a path component is a symbolic link and this adapter refuses symlinks",
+                });
+            }
+            if (component === target) {
+                if (!entry.isFile) {
+                    throw refuse(notAFile(entry.isDirectory ? "directory" : "other", cwd, target));
+                }
+                return { exists: true, entry };
+            }
+            if (!entry.isDirectory) {
+                throw refuse({ reason: "not-found", detail: "a path component is not a directory" });
+            }
+        }
+        if (missing.length === 0)
+            throw refuse(notAFile("directory", cwd, target));
+        return { exists: false, missingDirectories: missing.slice(0, -1) };
+    };
+    const lstatOrNull = async (path) => {
+        try {
+            return await inspect(workspaceFs, "lstat", path, false);
+        }
+        catch (error) {
+            if (error instanceof AdapterRefusal && error.error.reason === "not-found")
+                return null;
+            throw error;
+        }
+    };
+    const fileStat = (target, located) => located.exists
+        ? {
+            exists: true,
+            resolvedPath: target,
+            displayPath: displayPath(cwd, target),
+            size: located.entry.size,
+            mtimeMs: located.entry.mtime,
+            identity: null,
+            version: computerVersion(located.entry),
+            mode: located.entry.mode ?? null,
+            hardLinks: null,
+        }
+        : {
+            exists: false,
+            resolvedPath: target,
+            displayPath: displayPath(cwd, target),
+            missingDirectories: located.missingDirectories,
+        };
+    const makeDirectories = async (mkdir, directories) => {
+        const created = [];
+        for (const directory of directories) {
+            await mutate(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 = (target, entry, created) => ({
+        resolvedPath: target,
+        displayPath: displayPath(cwd, target),
+        version: entry === null ? null : computerVersion(entry),
+        identity: null,
+        size: entry?.size ?? null,
+        createdDirectories: created,
+        atomic: COMPUTER_WRITE_CAPABILITIES.atomic,
+    });
+    return {
+        async stat(requested, options = {}) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            try {
+                const { root, target } = authorize(roots, requested);
+                return { ok: true, stat: fileStat(target, await locate(root, target)) };
+            }
+            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 writeFile = requireMethod(workspaceFs, "writeFile");
+                const mkdir = requireMethod(workspaceFs, "mkdir");
+                const { root, target } = authorize(roots, requested);
+                const located = await locate(root, target);
+                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 created = located.exists
+                    ? []
+                    : await makeDirectories(mkdir, located.missingDirectories);
+                /* Computer's writeFile resets the mode on every call unless one is passed. */
+                const mode = located.exists ? located.entry.mode : options.mode;
+                await mutate(writeFile(target, bytes, {
+                    ...(mode === undefined ? {} : { mode }),
+                    ...(options.precondition.kind === "absent" ? { exclusive: true } : {}),
+                }), "writeFile");
+                const after = await lstatOrNull(target);
+                if (after?.isFile !== true) {
+                    throw refuse({ reason: "io", detail: "the file was not there after the write" });
+                }
+                return { ok: true, file: mutated(target, after, 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 rm = requireMethod(workspaceFs, "rm");
+                const { root, target } = authorize(roots, requested);
+                const located = await locate(root, target);
+                refuseConflict(located, options.precondition);
+                if (!located.exists)
+                    throw refuse({ reason: "not-found" });
+                if (options.signal?.aborted)
+                    throw refuse({ reason: "aborted" });
+                await mutate(rm(target), "rm");
+                return { ok: true, file: mutated(target, null, []) };
+            }
+            catch (error) {
+                return { ok: false, error: toMutationError(error) };
+            }
+        },
+    };
+}
+function requireMethod(workspaceFs, method) {
+    const found = workspaceFs[method];
+    if (typeof found !== "function") {
+        throw new WriteRefusal({
+            reason: "unsupported",
+            detail: `the Computer workspace filesystem has no ${method}(), so this backend cannot write`,
+        });
+    }
+    return found.bind(workspaceFs);
+}
+function refuseConflict(located, precondition) {
+    switch (precondition.kind) {
+        case "absent":
+            if (located.exists)
+                throw new WriteRefusal({ reason: "exists" });
+            return;
+        case "version":
+            if (!located.exists || computerVersion(located.entry) !== 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(pending, phase) {
+    try {
+        return await pending;
+    }
+    catch (error) {
+        const code = boundedCode(error);
+        const cause = { code, 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 refuse(mapBackendError(error, phase));
+    }
+}
+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,39 @@
 {
   "name": "@better-fs-tools/cloudflare-computer",
-  "version": "0.0.0-tegami-trusted-publish-setup",
-  "description": "Placeholder published by Tegami for npm trusted publishing setup."
+  "version": "0.1.0",
+  "description": "A readable and writable filesystem over a Cloudflare Computer workspace (experimental).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gingerhendrix/better-fs-tools.git",
+    "directory": "packages/cloudflare-computer"
+  },
+  "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.1.0"
+  },
+  "devDependencies": {
+    "@better-fs-tools/read": "^0.1.0",
+    "@better-fs-tools/write": "^0.1.0",
+    "@cloudflare/computer": "0.2.1"
+  }
 }