@legit-sdk/core 0.4.4 → 0.4.5

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { fileSave, FileWithHandle } from 'browser-fs-access';
 import * as nodeFs from 'node:fs';
 import { MakeDirectoryOptions, Mode } from 'node:fs';
 import * as memfs_lib_node_types_misc_js from 'memfs/lib/node/types/misc.js';
-import { IDir, TFileHandleReadResult, TData, TMode, IStats, TTime, TFileHandleWriteResult, TFileHandleWritevResult, TFileHandleReadvResult, IFileHandle, TDataOut, IDirent, PathLike } from 'memfs/lib/node/types/misc.js';
+import { IDir, PathLike, TFileHandleReadResult, TData, TMode, IStats, TTime, TFileHandleWriteResult, TFileHandleWritevResult, TFileHandleReadvResult, IFileHandle, TDataOut, IDirent } from 'memfs/lib/node/types/misc.js';
 import { IAppendFileOptions, IStatOptions, IReadFileOptions, IWriteFileOptions, IReadableWebStreamOptions } from 'memfs/lib/node/types/options.js';
 import { PathLike as PathLike$1 } from 'fs';
 import { IFs } from 'memfs';
@@ -28,6 +28,117 @@ type LegitAuth = {
 
 type CompositeSubFsDir = Pick<IDir, "path" | "close" | "read" | typeof Symbol.asyncIterator>;
 
+/**
+ * Context information for filesystem operations
+ * This context is provided by CompositeFs when routing to a specific SubFS
+ */
+interface FsOperationContext {
+    /** The full original path that was requested */
+    fullPath: string;
+    /** Extracted route parameters (e.g., { branchName: 'main', filePath: 'path/to/file' }) */
+    params: Record<string, string>;
+    /** Static siblings from route matching */
+    staticSiblings: {
+        segment: string;
+        type: 'folder' | 'file';
+    }[];
+}
+
+declare abstract class BaseCompositeSubFs implements CompositeSubFs {
+    /** Reference to the parent CompositeFs instance - late init */
+    compositeFs: CompositeFs;
+    /** Context for the current filesystem operation */
+    context?: FsOperationContext;
+    newContext?: FsOperationContext;
+    fsType: FsType;
+    /**
+     * Unique instance ID that persists across contextual instances
+     * This allows us to check if two contextual instances wrap the same base SubFS
+     */
+    readonly rootInstanceId: string;
+    name: string;
+    rootPath: string;
+    constructor({ name, rootPath }: {
+        name: string;
+        rootPath: string;
+    });
+    attach(compositFs: CompositeFs): void;
+    /**
+     * Create a new instance with context bound to it
+     * This creates a shallow copy where all mutable state (like open file handles)
+     * is shared between the original and the contextual instance, but the context
+     * is unique to this instance.
+     *
+     * Each operation gets its own contextual instance, ensuring that concurrent
+     * operations don't interfere with each other's context.
+     */
+    withContext(context: FsOperationContext): this;
+    abstract responsible(filePath: string): Promise<boolean>;
+    abstract fileType(): number;
+    open(path: PathLike, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    access(path: PathLike, mode?: number): Promise<void>;
+    stat(path: PathLike, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    stat(path: PathLike, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    stat(path: PathLike, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    lstat(path: PathLike, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    lstat(path: PathLike, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    lstat(path: PathLike, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    opendir(path: PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeSubFsDir>;
+    link(existingPath: PathLike, newPath: PathLike): Promise<void>;
+    mkdir(path: PathLike, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
+    readDirFiltering?(path: PathLike, entries: IDir[] | string[]): Promise<string[]>;
+    readdir(path: PathLike, options?: (nodeFs.ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    }) | BufferEncoding | null): Promise<string[]>;
+    readdir(path: PathLike, options?: {
+        encoding: 'buffer';
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    } | 'buffer' | null): Promise<Buffer[]>;
+    readdir(path: PathLike, options?: (nodeFs.ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    }) | BufferEncoding | null): Promise<string[] | Buffer[]>;
+    readdir(path: PathLike, options: nodeFs.ObjectEncodingOptions & {
+        withFileTypes: true;
+        recursive?: boolean | undefined;
+    }): Promise<nodeFs.Dirent[]>;
+    readlink(path: PathLike, ...args: any[]): Promise<any>;
+    unlink(path: PathLike): Promise<void>;
+    rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
+    rmdir(path: PathLike, ...args: any[]): Promise<void>;
+    symlink(target: PathLike, path: PathLike, type?: string | null): Promise<void>;
+    lookup(filePath: string): Promise<number>;
+    resolvePath(fd: number): string;
+    close(fh: CompositFsFileHandle): Promise<void>;
+    dataSync(fh: CompositFsFileHandle): Promise<void>;
+    read(fh: CompositFsFileHandle, buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
+    appendFile(fh: CompositFsFileHandle, data: TData, options?: IAppendFileOptions | string): Promise<void>;
+    fchmod(fh: CompositFsFileHandle, mode: TMode): Promise<void>;
+    fchown(fh: CompositFsFileHandle, uid: number, gid: number): Promise<void>;
+    ftruncate(fh: CompositFsFileHandle, len?: number): Promise<void>;
+    fstat(fh: CompositFsFileHandle, options?: IStatOptions): Promise<IStats>;
+    futimes(fh: CompositFsFileHandle, atime: TTime, mtime: TTime): Promise<void>;
+    write(fh: CompositFsFileHandle, buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
+    writev(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleWritevResult>;
+    readv(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
+    readFile(path: PathLike | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    writeFile(path: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
+}
+
 type FileHandleDelegate = {
     name: string;
     fileType: () => number;
@@ -49,9 +160,24 @@ type FileHandleDelegate = {
     readv(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
 };
 
+type FsType = 'folder' | 'file' | 'fs';
 type CompositeSubFs = Pick<typeof nodeFs.promises, 'access' | 'link' | 'readdir' | 'readlink' | 'unlink' | 'rename' | 'rmdir' | 'symlink'> & {
     name: string;
-    readFile(path: nodeFs.PathLike | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    /**
+     * Explicit declaration of the filesystem type.
+     * - 'folder': This SubFS only handles directories
+     * - 'file': This SubFS only handles files
+     * - 'fs': This SubFS handles both files and folders (default)
+     */
+    fsType: FsType;
+    context?: FsOperationContext;
+    newContext?: FsOperationContext;
+    readonly rootInstanceId: string;
+    compositeFs: CompositeFs;
+    withContext(context: FsOperationContext): BaseCompositeSubFs;
+    attach(compositFs: CompositeFs): void;
+    readDirFiltering?(path: nodeFs.PathLike, entries: string[]): Promise<string[]>;
+    readFile(path: nodeFs.PathLike, options?: IReadFileOptions | string): Promise<TDataOut>;
     stat(path: nodeFs.PathLike, opts?: IStatOptions & {
         bigint?: false;
     }): Promise<IStats<number>>;
@@ -162,17 +288,138 @@ declare const createFsOperationFileLogger: (fs: {
     operationArgs: any;
 }) => Promise<void>;
 
+/**
+ * Routes filesystem paths to appropriate SubFS handlers using a pattern-based system.
+ *
+ * The PathRouter supports a flexible pattern syntax for defining dynamic routes:
+ *
+ * | Pattern        | Description           | Example           | Matches                                              |
+ * |----------------|-----------------------|-------------------|------------------------------------------------------|
+ * | `static`       | Static segment        | `branches`        | `branches` only                                      |
+ * | `[param]`      | Dynamic segment       | `[branchName]`    | `main`, `dev`, etc. (single segment)                 |
+ * | `[[...param]]` | Optional catch-all    | `[[...filePath]]` | matches zero or more segments                        |
+ * | `.`            | Folder index handler  | `{ '.': handler }`| handles the folder itself                            |
+ *
+ * Priority is given to more specific routes (static > dynamic > catch-all).
+ *
+ * ## Static Sibling Union
+ *
+ * When multiple route patterns match at the same parent path level, their static siblings
+ * are merged (union operation). For example, if both `.legit` and `[[...filePath]]/.legit`
+ * match at root, the static siblings from both routes are combined.
+ *
+ * @example
+ * ```typescript
+ * const router = new PathRouter({
+ *   '[[...filePath]]': {
+ *     '.': catchAllHandler,
+ *     '.legit': { changes: changesHandler }
+ *   },
+ *   '.legit': {
+ *     '.': legitHandler,
+ *     head: headHandler,
+ *     branches: { ... }
+ *   }
+ * }, '/root');
+ *
+ * // Match with highest priority handler and union of all static siblings
+ * const result = router.match('/root/.legit');
+ * // result.handler === legitHandler (higher priority)
+ * // result.staticSiblings === [
+ * //   { segment: 'head', type: 'file' },      // from .legit route
+ * //   { segment: 'branches', type: 'folder' }, // from .legit route
+ * //   { segment: 'changes', type: 'file' }     // from [[...filePath]]/.legit
+ * // ]
+ * ```
+ */
+
+type MatchResult = {
+    handler: CompositeSubFs;
+    matchingPattern: string;
+    staticSiblings: {
+        segment: string;
+        type: 'folder' | 'file';
+    }[];
+    params: Record<string, string>;
+};
+interface LegitRouteFolder {
+    [key: string]: PathRouteDescription;
+}
+type PathRouteDescription = CompositeSubFs | LegitRouteFolder;
+/**
+ * PathRouter matches filesystem paths to SubFS handlers using pattern-based routing.
+ *
+ * The router evaluates all compiled patterns twice:
+ * 1. To find the highest-priority matching handler for the requested path
+ * 2. To find all patterns that match the parent path, merging their static siblings (union)
+ *
+ * This allows dynamic routes like `[[...filePath]]/.legit` to contribute siblings
+ * that are visible when matching the static `.legit` route.
+ *
+ * @example
+ * ```typescript
+ * const router = new PathRouter({
+ *   '[[...filePath]]': {
+ *     '.': catchAllHandler,
+ *     '.legit': { changes: changesHandler }
+ *   },
+ *   '.legit': {
+ *     '.': legitHandler,
+ *     head: headHandler,
+ *   }
+ * }, '/root');
+ *
+ * const result = router.match('/root/.legit');
+ * // Returns:
+ * // {
+ * //   handler: legitHandler,  // highest priority match
+ * //   params: {},
+ * //   staticSiblings: [
+ * //     { segment: 'head', type: 'file' },
+ * //     { segment: 'changes', type: 'file' }  // merged from catchall route!
+ * //   ]
+ * // }
+ * ```
+ */
+declare class PathRouter {
+    routes: LegitRouteFolder;
+    private rootPath;
+    private compiledRoutes;
+    /**
+     * Creates a new PathRouter with the given route configuration.
+     *
+     * @param routes - The route tree defining all possible paths
+     * @param rootPath - The root path to strip from incoming paths (e.g., '/root')
+     */
+    constructor(routes: LegitRouteFolder, rootPath: string);
+    /**
+     * Matches a path against all route patterns and returns the best match.
+     *
+     * The matching algorithm:
+     * 1. Normalizes the path by removing the root prefix
+     * 2. Finds all route patterns that match the path (by priority order)
+     * 3. Returns the highest-priority match
+     * 4. For static siblings, evaluates ALL patterns against the parent path
+     *    and merges their siblings (union operation)
+     *
+     * @param path - The full filesystem path to match
+     * @returns Match result with handler, params, and union of static siblings, or undefined if no match
+     */
+    match(path: string): MatchResult | undefined;
+}
+
 /**
  *
  * The CompositFs handles distribution of file operations to its sub filesystems and keeps track of open file handles.
- * open returns a CompositFsFileHandle that wraps the real filehandle from the responsible SubFs and allows
+ *
+ * open() returns a CompositFsFileHandle that wraps the real filehandle from the responsible SubFs and allows
  * to forward operations
  *
  * Each SubFs determines if it is responsible for a given path. The Composite fs probes each subsystem for responsibility.
  *
  * The responisbility is probed in the following order:
  *
- * hiddenFilesFileSystem -> ephemeralFilesFileSystem -> other subFs in order of addition -> passThroughFileSystem
+ * hiddenFilesFileSystem -> ephemeralFilesFileSystem -> other subFs in order of addition
  *
  * Composit fs consists of two special sub filesystems:
  *
@@ -223,52 +470,42 @@ declare class CompositeFs {
         writeFile: (file: nodeFs.PathOrFileDescriptor, data: string | Buffer | Uint8Array, options?: any) => Promise<void>;
         getFilehandle: (fd: number) => CompositFsFileHandle | undefined;
     };
-    gitRoot: string;
-    ephemeralFilesFileSystem: CompositeSubFs | undefined;
-    hiddenFilesFileSystem: CompositeSubFs | undefined;
-    passThroughFileSystem: CompositeSubFs;
-    subFilesystems: CompositeSubFs[];
+    filterLayers: CompositeSubFs[];
+    router: PathRouter;
     parentFs: CompositeFs | undefined;
     name: string;
-    defaultBranch: string;
-    gitCache: any;
+    rootPath: string;
     pathToFileDescriptors: Map<
     /** path */
     string, number[]>;
     openFileHandles: Map<number, CompositFsFileHandle>;
     logOperation: FsOperationLogger | undefined;
     private getNextFileDescriptor;
-    constructor({ name, storageFs, gitRoot, defaultBranch, }: {
+    constructor({ name, filterLayers, routes, rootPath, }: {
         name: string;
-        storageFs: typeof nodeFs;
-        gitRoot: string;
-        defaultBranch?: string;
+        filterLayers: CompositeSubFs[];
+        routes: LegitRouteFolder;
+        rootPath: string;
     });
     setLoggger(logger: FsOperationLogger | undefined): void;
     logOperationOnFileDescsriptor(fd: CompositFsFileHandle, operation: string, args: any): Promise<void>;
     getFilehandle(fd: number): CompositFsFileHandle | undefined;
-    setEphemeralFilesSubFs(subFs: CompositeSubFs): void;
-    setHiddenFilesSubFs(subFs: CompositeSubFs): void;
-    addSubFs(subFs: CompositeSubFs): void;
     /**
-     * helper function that takes a filePath and returns the fs that is responsible Sub filesystem for it
+     * Helper function that takes a filePath and returns the sub fs that is responsible for it.
+     *
+     * Order is:
+     * hidden -> if hidden no more questions - hide it!
+     *
+     * ephemeral -> file is marked as ephemeral *.DS_STORE and lock files - ignore if versioned at some point - always handle it as ephemeral
+     * versioned ->
+     * nonVersioned -> files
+     *
+     * other subFs in order of addition -> passThrough
      * @param filePath
-     * @returns
+     * @returns A contextual SubFS instance with route information bound to it
      */
     private getResponsibleFs;
     access(filePath: string, mode?: number): Promise<void>;
-    opendir(dirPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeFsDir>;
-    mkdir(dirPath: string, options?: any): Promise<void>;
-    /**
-     * Read dir needs to check if one subfs takes control.
-     *
-     * @param dirPath
-     * @param options
-     * @returns
-     */
-    readdir(dirPath: nodeFs.PathLike, options?: any): Promise<string[]>;
-    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
-    close(fh: CompositFsFileHandle): Promise<void>;
     stat(path: nodeFs.PathLike, opts?: {
         bigint?: false;
     }): Promise<nodeFs.Stats>;
@@ -287,11 +524,23 @@ declare class CompositeFs {
     lstat(path: nodeFs.PathLike, opts?: {
         bigint?: boolean;
     }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    unlink(filePath: nodeFs.PathLike): Promise<void>;
+    mkdir(dirPath: string, options?: any): Promise<void>;
+    rmdir(dirPath: nodeFs.PathLike, options?: nodeFs.RmDirOptions): Promise<void>;
+    opendir(dirPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeFsDir>;
+    /**
+     * Read dir needs to check if one subfs takes control.
+     *
+     * @param dirPath
+     * @param options
+     * @returns
+     */
+    readdir(dirPath: nodeFs.PathLike, options?: any): Promise<string[]>;
+    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    close(fh: CompositFsFileHandle): Promise<void>;
     link(existingPath: nodeFs.PathLike, newPath: nodeFs.PathLike): Promise<void>;
     readlink(path: nodeFs.PathLike, options?: nodeFs.ObjectEncodingOptions | BufferEncoding | null): Promise<void>;
-    unlink(filePath: nodeFs.PathLike): Promise<void>;
     rename(oldPath: nodeFs.PathLike, newPath: nodeFs.PathLike): Promise<void>;
-    rmdir(dirPath: nodeFs.PathLike, options?: nodeFs.RmDirOptions): Promise<void>;
     symlink(target: nodeFs.PathLike, path: nodeFs.PathLike, type?: string | null): Promise<void>;
     readFile(path: nodeFs.PathOrFileDescriptor, options?: {
         encoding?: null;
@@ -317,6 +566,7 @@ declare function openLegitFsWithMemoryFs(props?: Parameters<typeof openLegitFs>[
         loadBranch: (branch: string) => Promise<void>;
         sequentialPush: (branchesToPush: string[]) => Promise<void>;
     };
+    _storageFs: CompositeFs;
     setLogger(logger: FsOperationLogger | undefined): void;
     push: (branches: string[]) => Promise<void>;
     shareCurrentBranch: () => Promise<string>;
@@ -326,7 +576,7 @@ declare function openLegitFsWithMemoryFs(props?: Parameters<typeof openLegitFs>[
 /**
  * Creates and configures a LegitFs instance with CompositeFs, GitSubFs, HiddenFileSubFs, and EphemeralSubFs.
  */
-declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFiles, initialAuthor, serverUrl, publicKey, claudeHandler, }: {
+declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFiles, initialAuthor, serverUrl, publicKey, ephemaralGitConfig, additionalFilterLayers, }: {
     storageFs: typeof nodeFs;
     gitRoot: string;
     anonymousBranch?: string;
@@ -334,7 +584,8 @@ declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFile
     initialAuthor?: LegitUser;
     serverUrl?: string;
     publicKey?: string;
-    claudeHandler?: boolean;
+    ephemaralGitConfig?: boolean;
+    additionalFilterLayers?: CompositeSubFs[];
 }): Promise<CompositeFs & {
     auth: LegitAuth;
     sync: {
@@ -344,6 +595,7 @@ declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFile
         loadBranch: (branch: string) => Promise<void>;
         sequentialPush: (branchesToPush: string[]) => Promise<void>;
     };
+    _storageFs: CompositeFs;
     setLogger(logger: FsOperationLogger | undefined): void;
     push: (branches: string[]) => Promise<void>;
     shareCurrentBranch: () => Promise<string>;
@@ -358,81 +610,6 @@ declare function getLegitFsAccess(legitFs: Awaited<ReturnType<typeof openLegitFs
     openFile: (filePath: string) => Promise<FileWithHandle>;
 }>;
 
-declare abstract class BaseCompositeSubFs implements CompositeSubFs {
-    protected toStr(p: any): string;
-    protected compositFs: CompositeFs;
-    protected gitRoot: string;
-    name: string;
-    constructor({ name, parentFs, gitRoot, }: {
-        name: string;
-        parentFs: CompositeFs;
-        gitRoot: string;
-    });
-    abstract responsible(filePath: string): Promise<boolean>;
-    abstract fileType(): number;
-    open(path: PathLike, flags: string, mode?: number): Promise<CompositFsFileHandle>;
-    access(path: PathLike, mode?: number): Promise<void>;
-    stat(path: PathLike, opts?: {
-        bigint?: false;
-    }): Promise<nodeFs.Stats>;
-    stat(path: PathLike, opts: {
-        bigint: true;
-    }): Promise<nodeFs.BigIntStats>;
-    stat(path: PathLike, opts?: {
-        bigint?: boolean;
-    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
-    lstat(path: PathLike, opts?: {
-        bigint?: false;
-    }): Promise<nodeFs.Stats>;
-    lstat(path: PathLike, opts: {
-        bigint: true;
-    }): Promise<nodeFs.BigIntStats>;
-    lstat(path: PathLike, opts?: {
-        bigint?: boolean;
-    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
-    opendir(path: PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeSubFsDir>;
-    link(existingPath: PathLike, newPath: PathLike): Promise<void>;
-    mkdir(path: PathLike, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
-    readdir(path: PathLike, options?: (nodeFs.ObjectEncodingOptions & {
-        withFileTypes?: false | undefined;
-        recursive?: boolean | undefined;
-    }) | BufferEncoding | null): Promise<string[]>;
-    readdir(path: PathLike, options?: {
-        encoding: 'buffer';
-        withFileTypes?: false | undefined;
-        recursive?: boolean | undefined;
-    } | 'buffer' | null): Promise<Buffer[]>;
-    readdir(path: PathLike, options?: (nodeFs.ObjectEncodingOptions & {
-        withFileTypes?: false | undefined;
-        recursive?: boolean | undefined;
-    }) | BufferEncoding | null): Promise<string[] | Buffer[]>;
-    readdir(path: PathLike, options: nodeFs.ObjectEncodingOptions & {
-        withFileTypes: true;
-        recursive?: boolean | undefined;
-    }): Promise<nodeFs.Dirent[]>;
-    readlink(path: PathLike, ...args: any[]): Promise<any>;
-    unlink(path: PathLike): Promise<void>;
-    rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
-    rmdir(path: PathLike, ...args: any[]): Promise<void>;
-    symlink(target: PathLike, path: PathLike, type?: string | null): Promise<void>;
-    lookup(filePath: string): Promise<number>;
-    resolvePath(fd: number): string;
-    close(fh: CompositFsFileHandle): Promise<void>;
-    dataSync(fh: CompositFsFileHandle): Promise<void>;
-    read(fh: CompositFsFileHandle, buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
-    appendFile(fh: CompositFsFileHandle, data: TData, options?: IAppendFileOptions | string): Promise<void>;
-    fchmod(fh: CompositFsFileHandle, mode: TMode): Promise<void>;
-    fchown(fh: CompositFsFileHandle, uid: number, gid: number): Promise<void>;
-    ftruncate(fh: CompositFsFileHandle, len?: number): Promise<void>;
-    fstat(fh: CompositFsFileHandle, options?: IStatOptions): Promise<IStats>;
-    futimes(fh: CompositFsFileHandle, atime: TTime, mtime: TTime): Promise<void>;
-    write(fh: CompositFsFileHandle, buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
-    writev(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleWritevResult>;
-    readv(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
-    readFile(path: PathLike | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
-    writeFile(path: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
-}
-
 /**
  * FS utilized to hide files, it is responsible for files found in hiddenFiles
  *
@@ -440,11 +617,10 @@ declare abstract class BaseCompositeSubFs implements CompositeSubFs {
  */
 declare class HiddenFileSubFs extends BaseCompositeSubFs {
     private ig;
-    constructor({ name, parentFs, gitRoot, hiddenFiles, }: {
+    constructor({ name, hiddenFiles, rootPath, }: {
         name: string;
-        parentFs: CompositeFs;
-        gitRoot: string;
         hiddenFiles: string[];
+        rootPath: string;
     });
     responsible(filePath: string): Promise<boolean>;
     fileType(): number;
@@ -456,6 +632,7 @@ declare class HiddenFileSubFs extends BaseCompositeSubFs {
     opendir(path: PathLike$1): Promise<any>;
     link(existingPath: PathLike$1): Promise<void>;
     mkdir(path: PathLike$1): Promise<any>;
+    readDirFiltering?(path: PathLike$1, entries: string[]): Promise<string[]>;
     readdir(path: PathLike$1): Promise<any>;
     readlink(path: PathLike$1): Promise<any>;
     unlink(path: PathLike$1): Promise<void>;
@@ -479,10 +656,9 @@ declare class EphemeralSubFs extends BaseCompositeSubFs {
     private ig;
     patterns: string[];
     private normalizePath;
-    constructor({ name, parentFs, gitRoot, ephemeralPatterns, }: {
+    constructor({ name, rootPath, ephemeralPatterns, }: {
         name: string;
-        parentFs: CompositeFs;
-        gitRoot: string;
+        rootPath: string;
         ephemeralPatterns: string[];
     });
     responsible(filePath: string): Promise<boolean>;
@@ -533,6 +709,88 @@ declare class EphemeralSubFs extends BaseCompositeSubFs {
     writeFile(filePath: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
 }
 
+/**
+ * Copy-on-Write filesystem implementation
+ *
+ * This SubFs provides copy-on-write semantics:
+ * - Reads check copyToFs first, then fall back to sourceFs
+ * - Writes always go to copyToFs (creating a copy if needed)
+ * - Configured with patterns to determine which files to track
+ * - Original files in sourceFs are never modified
+ */
+declare class CopyOnWriteSubFs extends BaseCompositeSubFs {
+    private openFh;
+    private sourceFs;
+    private copyToFs;
+    private copyPath;
+    private ig;
+    patterns: string[];
+    constructor({ name, sourceFs, copyToFs, copyToRootPath, rootPath, patterns, }: {
+        name: string;
+        sourceFs: any;
+        copyToFs: any;
+        copyToRootPath: string;
+        rootPath: string;
+        patterns: string[];
+    });
+    private normalizeCopyPath;
+    private normalizePath;
+    responsible(filePath: string): Promise<boolean>;
+    fileType(): number;
+    /**
+     * Check if a file has been copied (exists in copyToFs)
+     */
+    private isCopied;
+    /**
+     * Copy a file from sourceFs to copyToFs
+     */
+    private copyFromSource;
+    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    access(filePath: PathLike$1, mode?: number): Promise<void>;
+    stat(statPath: PathLike$1, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    stat(statPath: PathLike$1, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    stat(statPath: PathLike$1, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    lstat(lstatPath: PathLike$1, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    lstat(lstatPath: PathLike$1, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    lstat(lstatPath: PathLike$1, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    opendir(folderPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeSubFsDir>;
+    link(existingPath: PathLike$1, newPath: PathLike$1): Promise<void>;
+    mkdir(dirPath: PathLike$1, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
+    readdir(readdirPath: PathLike$1, ...args: any[]): Promise<any>;
+    readlink(readlinkPath: PathLike$1): Promise<any>;
+    unlink(unlinkPath: PathLike$1): Promise<void>;
+    rename(oldPath: PathLike$1, newPath: PathLike$1): Promise<void>;
+    rmdir(rmdirPath: PathLike$1, options?: nodeFs.RmDirOptions): Promise<void>;
+    symlink(target: PathLike$1, linkPath: PathLike$1, type?: string | null): Promise<void>;
+    lookup(filePath: string): Promise<number>;
+    resolvePath(fd: number): string;
+    close(fh: CompositFsFileHandle): Promise<void>;
+    dataSync(fh: CompositFsFileHandle): Promise<void>;
+    read(fh: CompositFsFileHandle, buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
+    fchmod(fh: CompositFsFileHandle, mode: TMode): Promise<void>;
+    fchown(fh: CompositFsFileHandle, uid: number, gid: number): Promise<void>;
+    write(fh: CompositFsFileHandle, buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
+    ftruncate(fh: CompositFsFileHandle, len?: number): Promise<void>;
+    fstat(fh: CompositFsFileHandle, options?: IStatOptions): Promise<IStats>;
+    futimes(fh: CompositFsFileHandle, atime: TTime, mtime: TTime): Promise<void>;
+    writev(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleWritevResult>;
+    readv(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
+    readFile(filePath: PathLike$1 | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    writeFile(filePath: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
+}
+
 /**
  * FS utilized to provide pass-through access to the underlying filesystem
  */
@@ -540,10 +798,10 @@ declare class PassThroughSubFs extends BaseCompositeSubFs {
     private openFh;
     private memFs;
     private targetFs;
-    constructor({ name, parentFs, gitRoot, }: {
+    constructor({ name, parentFs, rootPath, }: {
         name: string;
         parentFs: CompositeFs;
-        gitRoot: string;
+        rootPath: string;
     });
     responsible(filePath: string): Promise<boolean>;
     fileType(): number;
@@ -619,6 +877,14 @@ interface VirtualFileArgs {
         timezoneOffset: number;
     };
 }
+/**
+ * Definition of a virtual file in the Git subsystem
+ *
+ *  ->
+ *
+ * writeFile -> writes the whole file
+ * readFile -> writes the whole file
+ */
 type VirtualFileDefinition = {
     type: string;
     rootType: 'folder' | 'file';
@@ -639,73 +905,52 @@ type VirtualFileDefinition = {
     rmdir?: (args: VirtualFileArgs) => Promise<void>;
 };
 
-interface LegitRouteFolder {
-    [key: string]: LegitRouteDescriptor;
-}
-type LegitRouteDescriptor = VirtualFileDefinition | LegitRouteFolder;
-
-/**
- * Topics to discuss:
- * # Ref space polution
- *  - Local vs Remote (we dont push all refs all the time)
- *  - required refs (what are the miniumum refs required to keep the repo healthy)
- *  - ref branch concept (branch pointing to oids to keep refs alive withouth poluting refs)
- *
- * # Performance (we tackle whens appear)
- *  - Git operations (especially history traversal) can be expensive
- *  - Current memfs caching might not scale for large repos
- *  - Consider lazy loading and bounded caches
- */
 /**
- * Git-backed CompositeSubFs implementation.
+ * CompositeSubFsAdapter - Adapts a virtual file handler to work as a SubFS
  *
+ * This class adapts a single VirtualFileDefinition to work as a CompositeSubFs.
+ * It receives routing context (extracted parameters) from CompositeFs, eliminating the need for internal routing.
  *
- * docx file
- *  - we unpack the docx and store xml files as blobs in git
- * mpeg file
- *  - we chunk the file and sstsore chunks as blobs in git
- **/
-declare class GitSubFs extends BaseCompositeSubFs implements CompositeSubFs {
-    private static readonly LEGIT_DIR;
-    private pathRouter;
+ * Each virtual file type (branch file, commit file, etc.) gets its own adapter instance.
+ */
+declare class CompositeSubFsAdapter extends BaseCompositeSubFs implements CompositeSubFs {
     private memFs;
     private openFh;
     storageFs: any;
+    protected gitRoot: string;
+    /**
+     * The virtual file handler for this adapter
+     * This defines how to read/write/stat the virtual file
+     */
+    handler: VirtualFileDefinition;
     getAuthor(): Promise<{
         name: string;
         email: string;
         date: number;
         timezoneOffset: number;
     }>;
-    constructor({ name, parentFs, gitStorageFs, gitRoot, routerConfig, }: {
+    constructor({ name, gitStorageFs, gitRoot, handler, rootPath, }: {
         name: string;
-        parentFs: CompositeFs;
         gitStorageFs: any;
         gitRoot: string;
-        routerConfig: LegitRouteFolder;
+        handler: VirtualFileDefinition;
+        rootPath: string;
     });
     responsible(filePath: string): Promise<boolean>;
-    private getRouteHandler;
     /**
-     * Opens a virtual file from the Git-based virtual file system.
-     *
-     * This method retrieves a virtual file descriptor for the given `filePath`, checks if the file is writable
-     * based on its type and the provided `flags`, and ensures that write operations are only allowed for
-     * certain file types (e.g., "branch-file", "branch-head", "branch-tip"). It then loads the file's content
-     * into the in-memory file system (`memFs`), ensures parent directories exist, and finally opens the file,
-     * returning a `CompositFsFileHandle` for further operations.
+     * Get route parameters from the operation context
+     * CompositeFs sets this context when routing to this adapter
+     */
+    private getRouteParams;
+    /**
+     * Get static siblings from the operation context
+     * These are static entries that should appear in directory listings
+     */
+    private getStaticSiblings;
+    /**
+     * Opens a virtual file using the configured handler.
      *
-     * @param filePath - The path to the virtual file to open.
-     * @param flags - The file system flags indicating the desired open mode (e.g., "r" for read, "w" for write, "a" for append, "x" for exclusive creation).
-     *   - "r": Open file for reading. An exception occurs if the file does not exist.
-     *   - "w": Open file for writing. The file is created (if it does not exist) or truncated (if it exists).
-     *   - "a": Open file for appending. The file is created if it does not exist.
-     *   - "x": Exclusive flag. Used with "w" or "a" to fail if the file exists.
-     *   - Combinations like "wx", "ax", etc., are also supported.
-     * @param mode - Optional file mode (permission and sticky bits) to use if creating a file.
-     * @returns A promise that resolves to a `CompositFsFileHandle` for the opened file.
-     * @throws If the file is not a virtual legit file, if write operations are not allowed for the file type,
-     *         or if the file does not exist.
+     * The handler receives route parameters via context set by CompositeFs.
      */
     open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
     mkdir(path: PathLike, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
@@ -782,7 +1027,24 @@ type Operation = {
     message: string;
     originBranchOid?: string;
 };
-declare const gitBranchOperationsVirtualFile: VirtualFileDefinition;
+/**
+ * Creates a CompositeSubFsAdapter for branch operations history
+ *
+ * This adapter handles reading the history of branch operations.
+ *
+ * @example
+ * ```ts
+ * const adapter = createBranchOperationsAdapter({
+ *   gitStorageFs: memFs,
+ *   gitRoot: '/my-repo',
+ * });
+ * ```
+ */
+declare function createBranchOperationsAdapter({ gitStorageFs, gitRoot, rootPath, }: {
+    gitStorageFs: any;
+    gitRoot: string;
+    rootPath?: string;
+}): CompositeSubFsAdapter;
 
 declare const createLegitSyncService: ({ fs, gitRepoPath, serverUrl, auth, anonymousBranch, authHeaderPrefix, }: {
     fs: FsClient;
@@ -812,5 +1074,5 @@ type HistoryItem = {
     author: User;
 };
 
-export { CompositeFs, EphemeralSubFs, GitSubFs, HiddenFileSubFs, PassThroughSubFs, createFsOperationFileLogger, createLegitSyncService, getLegitFsAccess, gitBranchOperationsVirtualFile, openLegitFs, openLegitFsWithMemoryFs };
+export { CompositeFs, CompositeSubFsAdapter, CopyOnWriteSubFs, EphemeralSubFs, HiddenFileSubFs, PassThroughSubFs, createBranchOperationsAdapter, createFsOperationFileLogger, createLegitSyncService, getLegitFsAccess, openLegitFs, openLegitFsWithMemoryFs };
 export type { FsOperationLogger, HistoryItem, Operation, User };