@statewalker/webrun-files-composite 0.7.1 → 0.8.1

package/src/guarded-files-api.ts

@@ -0,0 +1,131 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { normalizePath } from "@statewalker/webrun-files";
+import type { FileGuard, FileOperation } from "./types.js";
+
+/**
+ * `FilesApi` decorator that runs every call through an ordered list of
+ * {@link FileGuard}s. A guard fires when its `operations` set intersects the
+ * effective operation(s) for the current call. The first guard whose
+ * `check` returns `false` aborts the call by throwing an `Error` with that
+ * guard's `message` (defaulting to `"Access denied"`) followed by the
+ * normalized path.
+ *
+ * Effective operations per call:
+ *
+ * | Method        | Operations checked                                  |
+ * | ------------- | --------------------------------------------------- |
+ * | `read`        | `read`                                              |
+ * | `write`       | `write`                                             |
+ * | `mkdir`       | `mkdir`                                             |
+ * | `remove`      | `remove`                                            |
+ * | `list`        | `list` on the path AND on each directory entry      |
+ * | `stats`       | `list` (a stat reveals existence like a tiny list)  |
+ * | `exists`      | `read` (existence is a read of metadata)            |
+ * | `move(s, t)`  | `move`+`read` on source; `move`+`write` on target   |
+ * | `copy(s, t)`  | `copy`+`read` on source; `copy`+`write` on target   |
+ *
+ * The expanded checks for `move`/`copy` mean a guard that blocks `read` on
+ * a path also prevents move/copy *from* that path, and a `write`-blocking
+ * guard prevents move/copy *to* it. Likewise, an `exists` call respects any
+ * read guard, and `stats` respects any list guard.
+ *
+ * @example
+ * ```ts
+ * const api = new GuardedFilesApi(source, [
+ *   {
+ *     operations: ["write", "remove", "move", "mkdir"],
+ *     check: (p) => !p.startsWith("/.system/"),
+ *     message: "system folder is read-only",
+ *   },
+ * ]);
+ * await api.write("/.system/cfg", data); // throws "system folder is read-only: /.system/cfg"
+ * ```
+ */
+export class GuardedFilesApi implements FilesApi {
+  private readonly source: FilesApi;
+  private readonly guards: FileGuard[];
+
+  /**
+   * @param source The underlying `FilesApi` whose calls will be policed.
+   *   Allowed operations delegate straight through.
+   * @param guards Ordered list of access policies. The wrapper takes a
+   *   defensive copy, so mutating the array afterwards has no effect.
+   *   An empty list disables every check (the wrapper becomes a passthrough).
+   */
+  constructor(source: FilesApi, guards: FileGuard[]) {
+    this.source = source;
+    this.guards = [...guards];
+  }
+
+  private checkGuard(path: string, ...operations: FileOperation[]): void {
+    const normalized = normalizePath(path);
+    for (const guard of this.guards) {
+      if (!operations.some((op) => guard.operations.includes(op))) continue;
+      if (!guard.check(normalized)) {
+        const msg = guard.message ?? "Access denied";
+        throw new Error(`${msg}: ${normalized}`);
+      }
+    }
+  }
+
+  read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    this.checkGuard(path, "read");
+    return this.source.read(path, options);
+  }
+
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    this.checkGuard(path, "write");
+    return this.source.write(path, content);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    this.checkGuard(path, "mkdir");
+    return this.source.mkdir(path);
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    this.checkGuard(path, "list");
+    for await (const info of this.source.list(path, options)) {
+      if (info.kind === "directory") {
+        this.checkGuard(info.path, "list");
+      }
+      yield info;
+    }
+  }
+
+  stats(path: string): Promise<FileStats | undefined> {
+    this.checkGuard(path, "list");
+    return this.source.stats(path);
+  }
+
+  exists(path: string): Promise<boolean> {
+    this.checkGuard(path, "read");
+    return this.source.exists(path);
+  }
+
+  async remove(path: string): Promise<boolean> {
+    this.checkGuard(path, "remove");
+    return this.source.remove(path);
+  }
+
+  async move(source: string, target: string): Promise<boolean> {
+    this.checkGuard(source, "move", "read");
+    this.checkGuard(target, "move", "write");
+    return this.source.move(source, target);
+  }
+
+  async copy(source: string, target: string): Promise<boolean> {
+    this.checkGuard(source, "copy", "read");
+    this.checkGuard(target, "copy", "write");
+    return this.source.copy(source, target);
+  }
+}

package/src/index.ts

@@ -1,2 +1,16 @@
 export { CompositeFilesApi } from "./composite-files-api.js";
+export type { CowOptions } from "./cow-files-api.js";
+export { cow } from "./cow-files-api.js";
+export type { PathFilter } from "./filtered-files-api.js";
+export {
+  FilteredFilesApi,
+  newGlobPathFilter,
+  newPathFilter,
+  newRegexpPathFilter,
+} from "./filtered-files-api.js";
+export type { GlobToRegExpOptions } from "./glob-to-regexp.js";
+export { globToRegExp } from "./glob-to-regexp.js";
+export { GuardedFilesApi } from "./guarded-files-api.js";
+export { overlay } from "./overlay-files-api.js";
+export { readOnly } from "./read-only-files-api.js";
 export type { FileGuard, FileOperation } from "./types.js";

package/src/overlay-files-api.ts

@@ -0,0 +1,121 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { normalizePath } from "@statewalker/webrun-files";
+
+/**
+ * Read-only union of several `FilesApi` layers. A path is resolved
+ * **top → bottom**: the first layer that has it wins for
+ * `read` / `stats` / `exists`, and its entry (including `kind`) wins any
+ * name clash in `list`. Listings merge and dedupe across every layer.
+ *
+ * The union never writes — every mutating call throws. Use
+ * {@link overlay} to construct one.
+ */
+class OverlayFilesApi implements FilesApi {
+  private readonly layers: FilesApi[];
+
+  constructor(layers: FilesApi[]) {
+    this.layers = layers;
+  }
+
+  private deny(op: string, path: string): never {
+    throw new Error(`overlay is read-only (${op}): ${normalizePath(path)}`);
+  }
+
+  async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    for (const layer of this.layers) {
+      if (await layer.exists(path)) {
+        yield* layer.read(path, options);
+        return;
+      }
+    }
+  }
+
+  async stats(path: string): Promise<FileStats | undefined> {
+    for (const layer of this.layers) {
+      const stats = await layer.stats(path);
+      if (stats) return stats;
+    }
+    return undefined;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    for (const layer of this.layers) {
+      if (await layer.exists(path)) return true;
+    }
+    return false;
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+  }
+
+  private async *listDir(dir: string, recursive: boolean): AsyncIterable<FileInfo> {
+    const stats = await this.stats(dir);
+    if (stats?.kind !== "directory") return;
+    for (const entry of await this.mergeChildren(dir)) {
+      yield entry;
+      if (recursive && entry.kind === "directory") {
+        yield* this.listDir(entry.path, true);
+      }
+    }
+  }
+
+  /** Direct children of `dir`, deduped by name with the topmost layer winning. */
+  private async mergeChildren(dir: string): Promise<FileInfo[]> {
+    const merged = new Map<string, FileInfo>();
+    for (const layer of this.layers) {
+      if ((await layer.stats(dir))?.kind !== "directory") continue;
+      for await (const entry of layer.list(dir)) {
+        if (!merged.has(entry.name)) merged.set(entry.name, entry);
+      }
+    }
+    return [...merged.values()];
+  }
+
+  async write(path: string): Promise<void> {
+    this.deny("write", path);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    this.deny("mkdir", path);
+  }
+
+  async remove(path: string): Promise<boolean> {
+    return this.deny("remove", path);
+  }
+
+  async move(source: string): Promise<boolean> {
+    return this.deny("move", source);
+  }
+
+  async copy(source: string): Promise<boolean> {
+    return this.deny("copy", source);
+  }
+}
+
+/**
+ * Builds a **read-only** union view over `top` and any number of `lower`
+ * layers. Reads resolve top → bottom (first layer that has the path wins);
+ * `list` merges and dedupes across all layers with `top` winning a clash
+ * (including a file-vs-directory `kind` clash). Every write is denied.
+ *
+ * @param top The highest-priority layer; its entries shadow the rest.
+ * @param lower Additional layers, consulted in order after `top`.
+ * @returns A read-only `FilesApi` union.
+ *
+ * @example
+ * ```ts
+ * const view = overlay(userFiles, defaultFiles);
+ * await view.read("/config.json"); // userFiles if present, else defaultFiles
+ * await view.write("/x", data);    // throws (read-only)
+ * ```
+ */
+export function overlay(top: FilesApi, ...lower: FilesApi[]): FilesApi {
+  return new OverlayFilesApi([top, ...lower]);
+}

package/src/read-only-files-api.ts

@@ -0,0 +1,30 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import { GuardedFilesApi } from "./guarded-files-api.js";
+
+/**
+ * Wraps a `FilesApi` in a read-only view: every mutating operation
+ * (`write`, `mkdir`, `remove`, `move`, `copy`) throws, while reads
+ * (`read`, `list`, `stats`, `exists`) pass straight through to `api`.
+ *
+ * Implemented as a {@link GuardedFilesApi} with a single deny-all guard on
+ * the mutating operations, so `move`/`copy` are blocked on either endpoint.
+ *
+ * @param api The underlying `FilesApi` to expose read-only.
+ * @returns A `FilesApi` that never mutates `api`.
+ *
+ * @example
+ * ```ts
+ * const ro = readOnly(sourceFiles);
+ * await ro.read("/a.txt");          // ok
+ * await ro.write("/a.txt", data);   // throws "read-only: /a.txt"
+ * ```
+ */
+export function readOnly(api: FilesApi): FilesApi {
+  return new GuardedFilesApi(api, [
+    {
+      operations: ["write", "mkdir", "remove", "move", "copy"],
+      check: () => false,
+      message: "read-only",
+    },
+  ]);
+}

package/src/types.ts

@@ -1,10 +1,59 @@
+/**
+ * Filesystem operations a {@link FileGuard} can intercept.
+ *
+ * - `read` — reading file content (`FilesApi.read`). Also implicitly checked
+ *   on the source side of `move`/`copy`, and on every `exists` call.
+ * - `write` — writing file content (`FilesApi.write`). Also implicitly
+ *   checked on the target side of `move`/`copy`.
+ * - `mkdir` — creating directories (`FilesApi.mkdir`).
+ * - `list` — listing directory contents (`FilesApi.list`). Also implicitly
+ *   checked on every `stats` call and on each directory entry encountered
+ *   while iterating a listing.
+ * - `remove` — deleting files or directories (`FilesApi.remove`).
+ * - `move` — relocating a file or directory (`FilesApi.move`).
+ * - `copy` — copying a file or directory (`FilesApi.copy`).
+ *
+ * Only the operations listed in a guard's {@link FileGuard.operations} array
+ * trigger that guard's predicate.
+ */
 export type FileOperation = "read" | "write" | "remove" | "move" | "copy" | "list" | "mkdir";
 
+/**
+ * Per-operation, per-path access policy applied by `GuardedFilesApi`.
+ *
+ * Guards are evaluated in the order they are passed to the wrapper, and the
+ * first guard whose `check` returns `false` for a matching operation aborts
+ * the call by throwing an `Error` carrying its `message`.
+ *
+ * @example
+ * ```ts
+ * const guard: FileGuard = {
+ *   operations: ["write", "remove", "move"],
+ *   check: (path) => !path.startsWith("/.system/"),
+ *   message: "system folder is read-only",
+ * };
+ * ```
+ */
 export interface FileGuard {
-  /** Which filesystem operations this guard intercepts. */
+  /**
+   * Filesystem operations this guard applies to. The guard's `check` is
+   * invoked only for calls whose effective operation set intersects this
+   * list (e.g. a guard listing `"read"` also fires on `move`/`copy` source
+   * paths and on every `exists` call).
+   */
   operations: FileOperation[];
-  /** Returns true to allow, false to deny. */
+
+  /**
+   * Predicate invoked with the **normalized** path (single leading slash, no
+   * trailing slash, collapsed `.` segments and double slashes). Returning
+   * `true` allows the operation; returning `false` denies it and the wrapper
+   * throws an `Error` with this guard's {@link message}.
+   */
   check: (path: string) => boolean;
-  /** Error message when access is denied. */
+
+  /**
+   * Optional message used as the prefix of the thrown `Error`. The wrapper
+   * appends `: <normalized-path>`. Defaults to `"Access denied"`.
+   */
   message?: string;
 }