@statewalker/webrun-files-composite 0.7.1 → 0.8.0

package/dist/filtered-files-api.d.ts

@@ -0,0 +1,167 @@
+import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
+/**
+ * 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 declare function newPathFilter(...pathPrefixes: string[]): PathFilter;
+/**
+ * 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 declare function newRegexpPathFilter(...pathRegexps: RegExp[]): PathFilter;
+/**
+ * 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 declare function newGlobPathFilter(...pathGlobs: string[]): PathFilter;
+/**
+ * `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 declare class FilteredFilesApi implements FilesApi {
+    private readonly source;
+    private readonly 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);
+    protected isHidden(path: string): Promise<boolean>;
+    read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+    write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    stats(path: string): Promise<FileStats | undefined>;
+    exists(path: string): Promise<boolean>;
+    remove(path: string): Promise<boolean>;
+    move(source: string, target: string): Promise<boolean>;
+    copy(source: string, target: string): Promise<boolean>;
+}
+//# sourceMappingURL=filtered-files-api.d.ts.map

package/dist/filtered-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtered-files-api.d.ts","sourceRoot":"","sources":["../src/filtered-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,UAAU,CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;OAMG;gBACS,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU;cAKpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAKrE,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAOV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAQnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAM7D"}

package/dist/glob-to-regexp.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 declare function globToRegExp(glob: string, opts?: GlobToRegExpOptions): RegExp;
+//# sourceMappingURL=glob-to-regexp.d.ts.map

package/dist/glob-to-regexp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-to-regexp.d.ts","sourceRoot":"","sources":["../src/glob-to-regexp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,MAAM,CA2HjF"}

package/dist/guarded-files-api.d.ts

@@ -0,0 +1,64 @@
+import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
+import type { FileGuard } 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 declare class GuardedFilesApi implements FilesApi {
+    private readonly source;
+    private readonly guards;
+    /**
+     * @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[]);
+    private checkGuard;
+    read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+    write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    stats(path: string): Promise<FileStats | undefined>;
+    exists(path: string): Promise<boolean>;
+    remove(path: string): Promise<boolean>;
+    move(source: string, target: string): Promise<boolean>;
+    copy(source: string, target: string): Promise<boolean>;
+}
+//# sourceMappingURL=guarded-files-api.d.ts.map

package/dist/guarded-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-files-api.d.ts","sourceRoot":"","sources":["../src/guarded-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;;;OAMG;gBACS,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE;IAKjD,OAAO,CAAC,UAAU;IAWlB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAK9D,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAKV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAUzE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAKnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAK7D"}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -1,10 +1,57 @@
+/**
+ * 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7F,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,4CAA4C;IAC5C,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7F;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,UAAU,EAAE,aAAa,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAEjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-composite",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "description": "Composite FilesApi with mount points and access guards",

package/src/composite-files-api.ts

@@ -6,7 +6,6 @@ import type {
   ReadOptions,
 } from "@statewalker/webrun-files";
 import { joinPath, normalizePath } from "@statewalker/webrun-files";
-import type { FileGuard, FileOperation } from "./types.js";
 
 interface MountEntry {
   prefix: string;
@@ -14,14 +13,63 @@ interface MountEntry {
   basePath: string;
 }
 
+/**
+ * Composite `FilesApi` that routes calls to one of several backends based
+ * on a path prefix. Mounts are matched by **longest prefix wins**, so a
+ * mount at `/a/b` takes precedence over a mount at `/a` for paths under
+ * `/a/b/...`. The mount point itself appears in listings as a synthetic
+ * directory and cannot be removed.
+ *
+ * Each backend can use a sub-directory of its own filesystem as the mount
+ * root via `fsPath` (constructor `rootPath` for the implicit root mount,
+ * `fsPath` argument for additional mounts). Cross-mount `move` is
+ * implemented as copy-then-delete; there is no atomicity guarantee.
+ *
+ * Access control and visibility filtering are intentionally **not** part of
+ * this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
+ * (or both) instead.
+ *
+ * @example
+ * ```ts
+ * const fs = new CompositeFilesApi(localFs, "/projects")
+ *   .mount("/docs", s3Fs, "/documentation")
+ *   .mount("/cache", memFs);
+ * await fs.write("/readme.md", data); // → localFs:/projects/readme.md
+ * await fs.write("/docs/api.md", data); // → s3Fs:/documentation/api.md
+ * ```
+ */
 export class CompositeFilesApi implements FilesApi {
   private mounts: MountEntry[];
-  private guards: FileGuard[] = [];
 
+  /**
+   * @param root Default backend used for any path that does not match a
+   *   more specific mount. All paths are routed here unless `mount()`
+   *   intercepts them.
+   * @param rootPath Optional sub-directory of the root backend to use as
+   *   the composite filesystem's `/`. For example, `rootPath = "/projects"`
+   *   makes the composite path `/readme.md` resolve to `/projects/readme.md`
+   *   in the root backend. Defaults to `"/"` (no remapping).
+   */
   constructor(root: FilesApi, rootPath?: string) {
     this.mounts = [{ prefix: "/", api: root, basePath: normalizePath(rootPath ?? "/") }];
   }
 
+  /**
+   * Attaches a backend to handle every composite path under `path`. The
+   * mount prefix is normalized; paths under it are resolved against the
+   * mount's `fsPath` sub-directory (defaulting to `"/"`).
+   *
+   * @param path Composite-namespace prefix (e.g. `"/docs"`). Mounting at
+   *   `"/"` is forbidden — use the constructor `root` argument instead.
+   * @param api The backend `FilesApi` to delegate to for paths under
+   *   `path`. Wrap it in {@link FilteredFilesApi} / {@link GuardedFilesApi}
+   *   first if you want mount-local filtering or guards.
+   * @param fsPath Sub-directory of the mounted backend used as its mount
+   *   root, e.g. `mount("/docs", s3, "/documentation")` makes
+   *   `/docs/api.md` resolve to `/documentation/api.md` on `s3`.
+   * @returns `this`, for chaining.
+   * @throws If `path` normalizes to `"/"`.
+   */
   mount(path: string, api: FilesApi, fsPath?: string): this {
     const prefix = normalizePath(path);
     if (prefix === "/") {
@@ -33,11 +81,6 @@ export class CompositeFilesApi implements FilesApi {
     return this;
   }
 
-  guard(operations: FileOperation[], check: (path: string) => boolean, message?: string): this {
-    this.guards.push({ operations, check, message });
-    return this;
-  }
-
   // --- Mount resolution ---
 
   private resolve(path: string): { api: FilesApi; resolvedPath: string } {
@@ -78,23 +121,9 @@ export class CompositeFilesApi implements FilesApi {
     return result;
   }
 
-  // --- Guard checking ---
-
-  private checkGuard(operation: FileOperation, path: string): void {
-    const normalized = normalizePath(path);
-    for (const guard of this.guards) {
-      if (!guard.operations.includes(operation)) continue;
-      if (!guard.check(normalized)) {
-        const msg = guard.message ?? "Access denied";
-        throw new Error(`${msg}: ${normalized}`);
-      }
-    }
-  }
-
   // --- FilesApi implementation ---
 
   read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
-    this.checkGuard("read", path);
     const { api, resolvedPath } = this.resolve(path);
     return api.read(resolvedPath, options);
   }
@@ -103,19 +132,16 @@ export class CompositeFilesApi implements FilesApi {
     path: string,
     content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
   ): Promise<void> {
-    this.checkGuard("write", path);
     const { api, resolvedPath } = this.resolve(path);
     return api.write(resolvedPath, content);
   }
 
   async mkdir(path: string): Promise<void> {
-    this.checkGuard("mkdir", path);
     const { api, resolvedPath } = this.resolve(path);
     return api.mkdir(resolvedPath);
   }
 
   async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
-    this.checkGuard("list", path);
     const normalized = normalizePath(path);
     const { api, resolvedPath } = this.resolve(path);
 
@@ -184,14 +210,11 @@ export class CompositeFilesApi implements FilesApi {
     if (this.isMountPoint(normalized)) {
       throw new Error(`Cannot remove mount point: ${normalized}`);
     }
-    this.checkGuard("remove", path);
     const { api, resolvedPath } = this.resolve(path);
     return api.remove(resolvedPath);
   }
 
   async move(source: string, target: string): Promise<boolean> {
-    this.checkGuard("move", source);
-    this.checkGuard("move", target);
     const src = this.resolve(source);
     const tgt = this.resolve(target);
 
@@ -209,8 +232,6 @@ export class CompositeFilesApi implements FilesApi {
   }
 
   async copy(source: string, target: string): Promise<boolean> {
-    this.checkGuard("copy", source);
-    this.checkGuard("copy", target);
     const src = this.resolve(source);
     const tgt = this.resolve(target);