@statewalker/webrun-files-composite 0.7.1 → 0.8.0

package/src/filtered-files-api.ts

@@ -0,0 +1,257 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { normalizePath } from "@statewalker/webrun-files";
+import { globToRegExp } from "./glob-to-regexp.js";
+
+/**
+ * Predicate evaluated against a **normalized** path (single leading slash,
+ * no trailing slash) by `FilteredFilesApi` to decide visibility.
+ *
+ * - `true` → the path is visible (the wrapped operation runs).
+ * - `false` → the path is hidden (the wrapper short-circuits as if the path
+ *   did not exist).
+ *
+ * The predicate may be synchronous or return a `Promise<boolean>`. When
+ * async, it is awaited on each call — so prefer pure / cheap checks.
+ */
+export type PathFilter = (path: string) => boolean | Promise<boolean>;
+
+/**
+ * Builds a {@link PathFilter} that hides any path whose normalized form
+ * equals one of the provided prefixes or lives under `${prefix}/`.
+ *
+ * Prefixes are normalized through `normalizePath` (so `"foo"`, `"/foo"`, and
+ * `"/foo/"` are equivalent). Empty / root entries are dropped — they would
+ * otherwise hide every path.
+ *
+ * Matching is **boundary-aware**: the prefix `"/priv"` does not match the
+ * path `"/private"` because there is no `/` boundary between them.
+ *
+ * @param pathPrefixes Path prefixes whose contents (and the prefix itself)
+ *   should be hidden. Pass none to hide nothing.
+ *
+ * @example
+ * ```ts
+ * const filter = newPathFilter("/.git", "/node_modules");
+ * filter("/src/index.ts"); // true
+ * filter("/.git");         // false
+ * filter("/.git/HEAD");    // false
+ * filter("/notgit");       // true (boundary-aware, no false match)
+ * ```
+ */
+export function newPathFilter(...pathPrefixes: string[]): PathFilter {
+  const normalized = pathPrefixes.map((p) => normalizePath(p)).filter((p) => p !== "/");
+  return (path: string) => {
+    const target = normalizePath(path);
+    for (const prefix of normalized) {
+      if (target === prefix) return false;
+      if (target.startsWith(`${prefix}/`)) return false;
+    }
+    return true;
+  };
+}
+
+/**
+ * Builds a {@link PathFilter} that hides any path whose normalized form
+ * matches at least one of the provided regular expressions.
+ *
+ * The path is normalized through `normalizePath` before matching, so a
+ * regexp anchored on `^/` always sees a leading slash and never a trailing
+ * one. The regexp's `lastIndex` is irrelevant — the filter calls `test`
+ * via a fresh evaluation each time, but stateful (`/g`, `/y`) regexps
+ * still mutate `lastIndex` across calls; pass non-stateful regexps unless
+ * you know what you are doing.
+ *
+ * @param pathRegexps Regular expressions whose match means "hide this
+ *   path". Pass none to hide nothing.
+ *
+ * @example
+ * ```ts
+ * // Hide every dotfile and every *.log file
+ * const filter = newRegexpPathFilter(/\/\.[^/]+$/, /\.log$/);
+ * filter("/src/index.ts"); // true
+ * filter("/.env");         // false (matches /\/\.[^/]+$/)
+ * filter("/build.log");    // false (matches /\.log$/)
+ * ```
+ */
+export function newRegexpPathFilter(...pathRegexps: RegExp[]): PathFilter {
+  return (path: string) => {
+    const target = normalizePath(path);
+    for (const regexp of pathRegexps) {
+      if (regexp.test(target)) return false;
+    }
+    return true;
+  };
+}
+
+/**
+ * Builds a {@link PathFilter} that hides any path whose normalized form
+ * matches at least one of the provided glob patterns.
+ *
+ * Each glob is compiled with `extended: true` and `globstar: true`, the
+ * standard "filesystem-style" mode:
+ *
+ * - `*` matches any number of characters within a single path segment
+ *   (does **not** cross `/`).
+ * - `**` between slashes matches zero or more whole path segments.
+ * - `?` matches exactly one character.
+ * - `[abc]` / `[a-z]` matches a single character in the set / range.
+ * - `{a,b,c}` matches one of the alternatives.
+ *
+ * Because matching is done on the **normalized** path (which always starts
+ * with `/`), patterns that should match anywhere in the tree need a
+ * leading `**​/`, e.g. `**​/*.log` to hide every `.log` file at any depth.
+ *
+ * Gotcha: `/foo/**` matches descendants of `/foo` but **not** `/foo`
+ * itself, because the glob requires a `/` after `foo` before `**` can
+ * match. To hide both the directory and its contents, list both prefixes:
+ * `newGlobPathFilter("/foo", "/foo/**")`. {@link newPathFilter} doesn't
+ * have this problem and may be a better fit for prefix-only hiding.
+ *
+ * @param pathGlobs Glob patterns whose match means "hide this path". Pass
+ *   none to hide nothing.
+ *
+ * @example
+ * ```ts
+ * const filter = newGlobPathFilter("**​/*.log", "/.git", "/.git/**");
+ * filter("/src/index.ts"); // true
+ * filter("/build.log");    // false (matches **​/*.log)
+ * filter("/.git");         // false (matches /.git)
+ * filter("/.git/HEAD");    // false (matches /.git/**)
+ * ```
+ */
+export function newGlobPathFilter(...pathGlobs: string[]): PathFilter {
+  const regexps = pathGlobs.map((glob) => globToRegExp(glob, { extended: true, globstar: true }));
+  return newRegexpPathFilter(...regexps);
+}
+
+/**
+ * `FilesApi` decorator that hides every path the supplied {@link PathFilter}
+ * rejects. Hidden paths are treated as if they do not exist:
+ *
+ * - `read` / `list` yield empty iterables.
+ * - `stats` returns `undefined`; `exists` returns `false`.
+ * - `remove` returns `false` (no error, nothing changed).
+ * - `move` / `copy` return `false` if either endpoint is hidden.
+ * - `write` / `mkdir` reject with an `Error` (since silently dropping a
+ *   write would lose data).
+ * - `list` recursively skips entries whose paths are hidden, so iterating a
+ *   visible parent never reveals a hidden child.
+ *
+ * Wrap any `FilesApi` to scope its visibility without changing the
+ * underlying storage; the wrapped instance still holds the data, it is just
+ * not reachable through this decorator.
+ *
+ * Pair with one of the built-in {@link PathFilter} factories
+ * ({@link newPathFilter}, {@link newRegexpPathFilter},
+ * {@link newGlobPathFilter}) or pass any predicate of shape
+ * `(path) => boolean | Promise<boolean>`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   FilteredFilesApi,
+ *   newGlobPathFilter,
+ *   newPathFilter,
+ *   newRegexpPathFilter,
+ * } from "@statewalker/webrun-files-composite";
+ *
+ * // Hide by path prefix
+ * const noVcs = new FilteredFilesApi(sourceFiles, newPathFilter("/.git", "/.cache"));
+ * await noVcs.exists("/.git");        // false
+ * await noVcs.write("/.git/x", data); // throws "Path is hidden"
+ *
+ * // Hide by regexp
+ * const noLogs = new FilteredFilesApi(sourceFiles, newRegexpPathFilter(/\.log$/));
+ *
+ * // Hide by glob (extended + globstar mode)
+ * const noJunk = new FilteredFilesApi(
+ *   sourceFiles,
+ *   newGlobPathFilter("**​/*.log", "/.git", "/.git/**"),
+ * );
+ * ```
+ */
+export class FilteredFilesApi implements FilesApi {
+  private readonly source: FilesApi;
+  private readonly pathFilter: PathFilter;
+
+  /**
+   * @param source The underlying `FilesApi` whose paths will be selectively
+   *   hidden. Operations always delegate to this instance; the decorator
+   *   only adds the visibility check.
+   * @param pathFilter Predicate that decides per-call whether a normalized
+   *   path is visible. See {@link PathFilter}.
+   */
+  constructor(source: FilesApi, pathFilter: PathFilter) {
+    this.source = source;
+    this.pathFilter = pathFilter;
+  }
+
+  protected async isHidden(path: string): Promise<boolean> {
+    return (await this.pathFilter(normalizePath(path))) === false;
+  }
+
+  async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    if (await this.isHidden(path)) return;
+    yield* this.source.read(path, options);
+  }
+
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    if (await this.isHidden(path)) {
+      throw new Error(`Path is hidden: ${path}`);
+    }
+    await this.source.write(path, content);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    if (await this.isHidden(path)) {
+      throw new Error(`Path is hidden: ${path}`);
+    }
+    await this.source.mkdir(path);
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    if (await this.isHidden(path)) return;
+    for await (const entry of this.source.list(path, options)) {
+      if (await this.isHidden(entry.path)) continue;
+      yield entry;
+    }
+  }
+
+  async stats(path: string): Promise<FileStats | undefined> {
+    if (await this.isHidden(path)) return undefined;
+    return this.source.stats(path);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    if (await this.isHidden(path)) return false;
+    return this.source.exists(path);
+  }
+
+  async remove(path: string): Promise<boolean> {
+    if (await this.isHidden(path)) return false;
+    return this.source.remove(path);
+  }
+
+  async move(source: string, target: string): Promise<boolean> {
+    if ((await this.isHidden(source)) || (await this.isHidden(target))) {
+      return false;
+    }
+    return this.source.move(source, target);
+  }
+
+  async copy(source: string, target: string): Promise<boolean> {
+    if ((await this.isHidden(source)) || (await this.isHidden(target))) {
+      return false;
+    }
+    return this.source.copy(source, target);
+  }
+}

package/src/glob-to-regexp.ts

@@ -0,0 +1,182 @@
+/**
+ * Glob → RegExp compiler.
+ *
+ * TypeScript port of `glob-to-regexp` by Nick Fitzgerald.
+ *
+ * Upstream:
+ *   - https://github.com/fitzgen/glob-to-regexp
+ *   - source: https://raw.githubusercontent.com/fitzgen/glob-to-regexp/master/index.js
+ *   - tests:  https://raw.githubusercontent.com/fitzgen/glob-to-regexp/master/test.js
+ *
+ * The original is published under the BSD 2-Clause license — see the
+ * upstream repository for the full text. This port preserves the original
+ * semantics; only the surface API has been re-typed for TypeScript.
+ */
+
+export interface GlobToRegExpOptions {
+  /**
+   * Enable bash-style extended globs. When `true`:
+   *
+   * - `?` matches exactly one character.
+   * - `[abc]` / `[a-z]` matches a single character in the set / range.
+   * - `{foo,bar}` matches one of the alternatives.
+   *
+   * When `false` (default), each of these characters is treated literally
+   * (they are escaped in the output regexp).
+   */
+  extended?: boolean;
+
+  /**
+   * Enable bash-style globstar semantics for `*` and `**`.
+   *
+   * - With `globstar: false` (default), every run of `*`s is translated to
+   *   `.*` — so `*` matches any number of characters, including `/`.
+   * - With `globstar: true`, a single `*` only matches within one path
+   *   segment (`[^/]*`), and a `**` segment (`**` between `/`s, or at the
+   *   start/end of the pattern) matches zero or more whole segments.
+   */
+  globstar?: boolean;
+
+  /**
+   * RegExp flags passed to the `RegExp` constructor. When `flags` includes
+   * `"g"`, the produced regexp is **not** anchored with `^…$`, so the glob
+   * matches anywhere in the string instead of the whole string.
+   */
+  flags?: string;
+}
+
+/**
+ * Compiles a glob pattern into a `RegExp`.
+ *
+ * @example
+ * ```ts
+ * globToRegExp("*.js");                       // /^.*\.js$/
+ * globToRegExp("*.js", { globstar: true });   // /^([^/]*)\.js$/
+ * globToRegExp("/foo/**", { globstar: true }) // /^\/foo\/((?:[^/]*(?:\/|$))*)$/
+ * globToRegExp("foo{bar,baz}", { extended: true }); // /^foo(bar|baz)$/
+ * ```
+ */
+export function globToRegExp(glob: string, opts: GlobToRegExpOptions = {}): RegExp {
+  if (typeof glob !== "string") {
+    throw new TypeError("Expected a string");
+  }
+
+  const str = String(glob);
+
+  // The regexp we are building, as a string.
+  let reStr = "";
+
+  // Whether we are matching so called "extended" globs (like bash) and
+  // should support single character matching, matching ranges of
+  // characters, group matching, etc.
+  const extended = !!opts.extended;
+
+  // Globstar semantics for `*` / `**`.
+  // - false: '/foo/*' becomes '^/foo/.*$' (matches '/foo/bar' AND '/foo/bar/baz')
+  // - true:  '/foo/*' becomes '^/foo/[^/]*$' (matches '/foo/bar' only)
+  //          '/foo/**' (with globstar=true) means "any depth under /foo".
+  const globstar = !!opts.globstar;
+
+  // True while inside an extended `{a,b}` group. Used to translate `,`.
+  let inGroup = false;
+
+  // RegExp flags passed straight through to the RegExp constructor.
+  const flags = typeof opts.flags === "string" ? opts.flags : "";
+
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+
+    switch (c) {
+      case "/":
+      case "$":
+      case "^":
+      case "+":
+      case ".":
+      case "(":
+      case ")":
+      case "=":
+      case "!":
+      case "|":
+        reStr += `\\${c}`;
+        break;
+
+      case "?":
+        reStr += extended ? "." : `\\${c}`;
+        break;
+
+      case "[":
+      case "]":
+        reStr += extended ? c : `\\${c}`;
+        break;
+
+      case "{":
+        if (extended) {
+          inGroup = true;
+          reStr += "(";
+        } else {
+          reStr += `\\${c}`;
+        }
+        break;
+
+      case "}":
+        if (extended) {
+          inGroup = false;
+          reStr += ")";
+        } else {
+          reStr += `\\${c}`;
+        }
+        break;
+
+      case ",":
+        if (inGroup) {
+          reStr += "|";
+        } else {
+          reStr += `\\${c}`;
+        }
+        break;
+
+      case "*": {
+        // Coalesce consecutive "*"s and remember the surrounding chars so
+        // we can decide whether this run is a "globstar" segment.
+        const prevChar = str[i - 1];
+        let starCount = 1;
+        while (str[i + 1] === "*") {
+          starCount++;
+          i++;
+        }
+        const nextChar = str[i + 1];
+
+        if (!globstar) {
+          // globstar disabled: any number of "*" maps to ".*".
+          reStr += ".*";
+        } else {
+          const isGlobstar =
+            starCount > 1 && // multiple "*"s
+            (prevChar === "/" || prevChar === undefined) && // segment start
+            (nextChar === "/" || nextChar === undefined); // segment end
+
+          if (isGlobstar) {
+            // Match zero or more whole path segments.
+            reStr += "((?:[^/]*(?:\\/|$))*)";
+            i++; // consume the trailing "/"
+          } else {
+            // Match within one path segment only.
+            reStr += "([^/]*)";
+          }
+        }
+        break;
+      }
+
+      default:
+        reStr += c;
+    }
+  }
+
+  // When the "g" flag is set, leave the regexp un-anchored so the caller
+  // can match the glob anywhere within a longer string.
+  if (!flags?.includes("g")) {
+    reStr = `^${reStr}$`;
+  }
+
+  return new RegExp(reStr, flags);
+}

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,12 @@
 export { CompositeFilesApi } from "./composite-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 type { FileGuard, FileOperation } from "./types.js";

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;
 }