@legit-sdk/core 0.1.7

package/dist/index.d.ts

@@ -0,0 +1,780 @@
+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 { IAppendFileOptions, IStatOptions, IReadFileOptions, IWriteFileOptions, IReadableWebStreamOptions } from 'memfs/lib/node/types/options.js';
+import { PathLike as PathLike$1 } from 'fs';
+import { IFs } from 'memfs';
+import { FsClient } from 'isomorphic-git';
+import { fileSave, FileWithHandle } from 'browser-fs-access';
+
+type CompositeSubFsDir = Pick<IDir, "path" | "close" | "read" | typeof Symbol.asyncIterator>;
+
+type FileHandleDelegate = {
+    fileType: () => number;
+    open: (filePath: string, flags: string, mode?: number) => Promise<CompositFsFileHandle>;
+    /**
+     * @returns a unique number per subfs
+     */
+    close: (fh: CompositFsFileHandle) => 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>;
+};
+
+type CompositeSubFs = Pick<typeof nodeFs.promises, 'access' | 'link' | 'readdir' | 'readlink' | 'unlink' | 'rename' | 'rmdir' | 'symlink'> & {
+    readFile(path: nodeFs.PathLike | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    stat(path: nodeFs.PathLike, opts?: IStatOptions & {
+        bigint?: false;
+    }): Promise<IStats<number>>;
+    stat(path: nodeFs.PathLike, opts: IStatOptions & {
+        bigint: true;
+    }): Promise<IStats<bigint>>;
+    stat(path: nodeFs.PathLike, opts?: IStatOptions): Promise<IStats<number> | IStats<bigint>>;
+    lstat(path: nodeFs.PathLike, opts?: IStatOptions & {
+        bigint?: false;
+    }): Promise<IStats<number>>;
+    lstat(path: nodeFs.PathLike, opts: IStatOptions & {
+        bigint: true;
+    }): Promise<IStats<bigint>>;
+    lstat(path: nodeFs.PathLike, opts?: IStatOptions): Promise<IStats<number> | IStats<bigint>>;
+    mkdir: (path: nodeFs.PathLike, options?: MakeDirectoryOptions | Mode | null) => Promise<void>;
+    fileType: () => number;
+    writeFile: (path: string, data: TData, options: IWriteFileOptions | string) => Promise<void>;
+    opendir(dirPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeSubFsDir>;
+    lookup: (path: string) => Promise<number>;
+    responsible(filePath: string): Promise<boolean>;
+    resolvePath: (fd: number) => string;
+} & FileHandleDelegate;
+
+interface ICompositFsFileHandle {
+    subFsFileDescriptor: number;
+    fsType: number;
+    fd: number;
+    appendFile(data: TData, options?: IAppendFileOptions | string): Promise<void>;
+    chmod(mode: TMode): Promise<void>;
+    chown(uid: number, gid: number): Promise<void>;
+    close(): Promise<void>;
+    datasync(): Promise<void>;
+    readableWebStream(options?: IReadableWebStreamOptions): ReadableStream;
+    read(buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
+    readv(buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
+    stat(options?: IStatOptions): Promise<IStats>;
+    truncate(len?: number): Promise<void>;
+    utimes(atime: TTime, mtime: TTime): Promise<void>;
+    write(buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
+    writev(buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleWritevResult>;
+    sync(): Promise<void>;
+}
+/**
+ * While a filehandle in node env usually is an independent (from its fs) entity to keep fs operatons colocated per type (vritual, managed... files) we
+ * wrap the filehandle in a SubFsFileHandle and forward all operations to there origin filesystem
+ */
+declare class CompositFsFileHandle implements ICompositFsFileHandle {
+    private delegate;
+    get fsType(): number;
+    private _subFsFileDescriptor;
+    get subFsFileDescriptor(): number;
+    handleType: string;
+    private _compositFsFileDescriptor;
+    get fd(): number;
+    realize(compositeFd: number): void;
+    constructor(args: {
+        fs: FileHandleDelegate;
+        subFsFileDescriptor: number;
+        parentFsFileDescriptors: number[];
+    });
+    readableWebStream(options?: IReadableWebStreamOptions): ReadableStream;
+    appendFile(data: TData, options?: IAppendFileOptions | string): Promise<void>;
+    chmod(mode: TMode): Promise<void>;
+    chown(uid: number, gid: number): Promise<void>;
+    close(): Promise<void>;
+    datasync(): Promise<void>;
+    read(buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
+    readv(buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
+    stat(options?: IStatOptions): Promise<IStats>;
+    truncate(len?: number): Promise<void>;
+    utimes(atime: TTime, mtime: TTime): Promise<void>;
+    write(buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
+    writev(buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleWritevResult>;
+    sync(): Promise<void>;
+}
+
+declare class CompositeFsDir {
+    private entries;
+    private currentIndex;
+    private closed;
+    private compositFs;
+    private dirPath;
+    private initialized;
+    constructor(compositFs: CompositeFs, dirPath: string);
+    private initialize;
+    [Symbol.asyncIterator](): AsyncIterableIterator<IDirent>;
+    read(): Promise<nodeFs.Dirent | null>;
+    close(): Promise<void>;
+    get path(): string;
+}
+
+/**
+ *
+ * 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
+ * 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
+ *
+ * Composit fs consists of two special sub filesystems:
+ *
+ * HiddenFilesSubFs - a filesystem that makes files inaccessible from the user
+ *   -> this is useful if you want to protect files like .git from being accessed or modified by the user
+ *
+ * EphemeralFilesSubFs - a filesystem that provides files that only exist in memory and are not persisted
+ *   -> this is usefull when you mount the compositfs as a Network drive for example via NFS to provide a space OS specific User files like .DS_
+ *
+ * Beyond those special subsystems additional systems cann be plugged in - the order matters
+ * and "the other" sub systems added via addSubFs
+ *
+ 
+ *
+ * Renames over subfs bounderies are are managed by this fs
+ *
+ * writeFile and readFile open a short living filehandle to execute the operations
+ *
+ *
+ */
+declare class CompositeFs {
+    promises: {
+        access: (filePath: string, mode?: number) => Promise<void>;
+        opendir: (dirPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions) => Promise<CompositeFsDir>;
+        mkdir: (dirPath: string, options?: any) => Promise<void>;
+        readdir: (dirPath: nodeFs.PathLike, options?: any) => Promise<string[]>;
+        open: (filePath: string, flags: string, mode?: number) => Promise<CompositFsFileHandle>;
+        stat: (path: nodeFs.PathLike, opts?: {
+            bigint?: boolean;
+        }) => Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+        lstat: (path: nodeFs.PathLike, opts?: {
+            bigint?: boolean;
+        }) => Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+        link: (existingPath: nodeFs.PathLike, newPath: nodeFs.PathLike) => Promise<void>;
+        readlink: (path: nodeFs.PathLike, options?: nodeFs.ObjectEncodingOptions | BufferEncoding | null) => Promise<any>;
+        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: (typeof nodeFs.promises)['readFile'];
+        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[];
+    parentFs: CompositeFs | undefined;
+    name: string;
+    pathToFileDescriptors: Map<
+    /** path */
+    string, number[]>;
+    openFileHandles: Map<number, CompositFsFileHandle>;
+    private getNextFileDescriptor;
+    constructor({ name, parentFs, storageFs, gitRoot, }: {
+        name: string;
+        parentFs: CompositeFs | undefined;
+        storageFs: typeof nodeFs | undefined;
+        gitRoot: string;
+    });
+    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
+     * @param filePath
+     * @returns
+     */
+    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.
+     *
+     * TODO also implement the option to return stats
+     *
+     * @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>;
+    stat(path: nodeFs.PathLike, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    stat(path: nodeFs.PathLike, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    lstat(path: nodeFs.PathLike, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    lstat(path: nodeFs.PathLike, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    lstat(path: nodeFs.PathLike, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    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;
+        flag?: string;
+    } | null): Promise<Buffer>;
+    readFile(path: nodeFs.PathOrFileDescriptor, options: {
+        encoding: BufferEncoding;
+        flag?: string;
+    } | BufferEncoding): Promise<string>;
+    writeFile(file: nodeFs.PathOrFileDescriptor, data: string | Buffer | Uint8Array, options?: {
+        encoding?: BufferEncoding;
+        mode?: number;
+        flag?: string;
+    } | BufferEncoding | null): Promise<void>;
+}
+
+declare abstract class BaseCompositeSubFs implements CompositeSubFs {
+    protected toStr(p: any): string;
+    protected compositFs: CompositeFs;
+    protected gitRoot: string;
+    constructor({ parentFs, gitRoot, }: {
+        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
+ *
+ * For those files it fails on open, close etc.
+ */
+declare class HiddenFileSubFs extends BaseCompositeSubFs {
+    private ig;
+    constructor({ parentFs, gitRoot, hiddenFiles, }: {
+        parentFs: CompositeFs;
+        gitRoot: string;
+        hiddenFiles: string[];
+    });
+    responsible(filePath: string): Promise<boolean>;
+    fileType(): number;
+    private error;
+    open(path: PathLike$1, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    access(path: PathLike$1): Promise<void>;
+    stat(path: PathLike$1): Promise<any>;
+    lstat(path: PathLike$1): Promise<any>;
+    opendir(path: PathLike$1): Promise<any>;
+    link(existingPath: PathLike$1): Promise<void>;
+    mkdir(path: PathLike$1): Promise<any>;
+    readdir(path: PathLike$1): Promise<any>;
+    readlink(path: PathLike$1): Promise<any>;
+    unlink(path: PathLike$1): Promise<void>;
+    rename(oldPath: PathLike$1): Promise<void>;
+    rmdir(path: PathLike$1): Promise<void>;
+    symlink(_target: PathLike$1, path: PathLike$1): 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<any>;
+}
+
+/**
+ * FS utilized to provide ephemeral storage using in-memory filesystem
+ * Files matching ephemeralPatterns are stored in memory and lost on restart
+ */
+declare class EphemeralSubFs extends BaseCompositeSubFs {
+    private openFh;
+    private memFs;
+    private ig;
+    patterns: string[];
+    private normalizePath;
+    constructor({ parentFs, gitRoot, ephemeralPatterns, }: {
+        parentFs: CompositeFs;
+        gitRoot: string;
+        ephemeralPatterns: string[];
+    });
+    responsible(filePath: string): Promise<boolean>;
+    fileType(): number;
+    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    access(filePath: PathLike$1, mode?: number): Promise<void>;
+    stat(path: PathLike$1, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    stat(path: PathLike$1, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    stat(path: PathLike$1, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    lstat(path: PathLike$1, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    lstat(path: PathLike$1, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    lstat(path: PathLike$1, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    opendir(folderPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<memfs_lib_node_types_misc_js.IDir>;
+    link(existingPath: PathLike$1, newPath: PathLike$1): Promise<void>;
+    mkdir(dirPath: PathLike$1, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
+    readdir(path: PathLike$1, ...args: any[]): Promise<any>;
+    readlink(path: PathLike$1): Promise<any>;
+    unlink(path: PathLike$1): Promise<void>;
+    rename(oldPath: PathLike$1, newPath: PathLike$1): Promise<void>;
+    rmdir(path: PathLike$1, options?: nodeFs.RmDirOptions): Promise<void>;
+    symlink(target: PathLike$1, path: PathLike$1, type?: string | null): Promise<void>;
+    lookup(filePath: string): Promise<number>;
+    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>;
+    resolvePath(fd: number): string;
+    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(path: 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
+ */
+declare class PassThroughSubFs extends BaseCompositeSubFs {
+    private openFh;
+    private memFs;
+    private targetFs;
+    constructor({ parentFs, gitRoot, }: {
+        parentFs: CompositeFs;
+        gitRoot: string;
+    });
+    responsible(filePath: string): Promise<boolean>;
+    fileType(): number;
+    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    access(filePath: PathLike$1, mode?: number): Promise<void>;
+    stat(path: PathLike$1, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    stat(path: PathLike$1, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    stat(path: PathLike$1, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    lstat(path: PathLike$1, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    lstat(path: PathLike$1, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    lstat(path: PathLike$1, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    opendir(folderPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeFsDir>;
+    link(existingPath: PathLike$1, newPath: PathLike$1): Promise<void>;
+    mkdir(dirPath: PathLike$1, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
+    readdir(path: PathLike$1, ...args: any[]): Promise<any>;
+    readlink(path: PathLike$1, ...args: any[]): Promise<any>;
+    unlink(path: PathLike$1): Promise<void>;
+    rename(oldPath: PathLike$1, newPath: PathLike$1): Promise<void>;
+    rmdir(path: PathLike$1, options?: nodeFs.RmDirOptions): Promise<void>;
+    symlink(target: PathLike$1, path: PathLike$1, type?: string | null): Promise<void>;
+    lookup(filePath: string): Promise<number>;
+    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>;
+    resolvePath(fd: number): string;
+    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(path: PathLike$1 | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    writeFile(path: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
+}
+
+type VirtualFile = {
+    type: 'file';
+    content?: string | Buffer;
+    oid?: string | undefined;
+    mode?: number;
+    size?: number;
+} | {
+    type: 'directory';
+    content: string[];
+    oid?: string | undefined;
+    mode?: number;
+};
+interface VirtualFileArgs {
+    cacheFs: IFs;
+    filePath: string;
+    fs: CompositeFs;
+    gitRoot: string;
+    nodeFs?: any;
+    pathParams: any;
+}
+type VirtualFileDefinition = {
+    type: string;
+    getFile: (args: VirtualFileArgs) => Promise<VirtualFile | undefined>;
+    getStats: (args: VirtualFileArgs) => Promise<nodeFs.Stats>;
+    onFileChanged?: (args: VirtualFileArgs) => Promise<void>;
+    writeFile?: (args: VirtualFileArgs & {
+        content: Buffer | string;
+    }) => Promise<void>;
+    unlink?: (args: VirtualFileArgs) => Promise<void>;
+    rename: (args: VirtualFileArgs & {
+        newPath: string;
+        newPathParams: any;
+    }) => Promise<void>;
+    mkdir: (args: VirtualFileArgs & {
+        options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null;
+    }) => Promise<void>;
+};
+
+/**
+ * 1. Path Structure Complexity
+  - Your nested .legit paths (e.g., /.legit/branch/my-branch-name/.legit/head) create redundancy
+  - Consider flattening: /.legit/branches/my-branch-name/head vs /.legit/branch/my-branch-name/.legit/head
+
+Reason for the concept: i need to distinguish .legit files from other folders, therefore i wanted to introduce .letgit as a reserved folder independent from the depth or if repeated
+Any problems you see with this?
+
+
+  2. Write Operations on Historical Data
+  - Writing to /.legit/history/commits/... paths is conceptually problematic - commits are immutable
+  - Consider read-only for historical data, write-only for branch operations
+
+  100% with you commits should be read only folders
+
+  3. Branch Head Management
+  - Using git tags for head tracking (my-branch-name_legithead) pollutes the tag namespace
+  - Alternative: Use a dedicated ref namespace like refs/legit/heads/my-branch-name
+
+Reason for the concept: i see the point with pollution of tag namespace BUT this will help existing tools to display the concept - i would start with tags and move refs to a later point in time
+ - what speaks against this?
+
+  4. Conflict with Existing Virtual Files
+  - Current implementation has .status.gitbox, .branch.gitbox files
+  - Need strategy to migrate or maintain compatibility
+
+Context: the hole thing is a non published poc so no need to migrate - just an implementation change needed
+
+  Architectural Challenges
+
+  1. Performance
+  - Git operations (especially history traversal) can be expensive
+  - Current memfs caching might not scale for large repos
+  - Consider lazy loading and bounded caches
+
+   Future problem - lets not premature optimation or clear doubts?
+
+  2. Consistency
+  - Multiple write paths (working copy, branches) need careful coordination
+  - Race conditions between git operations and filesystem operations
+
+  Lets postpone this for now
+
+  3. Error Handling
+  - Git operations can fail (conflicts, invalid commits)
+  - Need clear error propagation through the FS layer
+
+  Lets discuss this deeper - dont understand the problem here.
+
+  Implementation Approach
+
+  Phase 1: Read-Only Git Views
+  // Start with immutable views
+  /.legit/status                    // Current git status
+  /.legit/commits/{sha}/path/to/file // Historical file access
+  /.legit/branches/                  // List branches
+  /.legit/refs/heads/{branch}/path   // Branch file access
+
+  Phase 2: Branch Operations
+  // Add write capabilities
+  /.legit/refs/heads/{branch}/.meta/head  // Track branch head
+  /.legit/refs/heads/{branch}/path        // Write to branch
+
+  Phase 3: Advanced Features
+  // Commit creation, branch management
+  /.legit/stage/                    // Staging area
+  /.legit/commit                    // Trigger commit
+
+  Plan sounds good!
+
+
+  Next Steps
+
+  1. Refine the path structure - Simplify and avoid nested .legit directories
+    - no please take my points into consideratio
+   
+  2. Create a proof-of-concept - Start with read-only status and commit access
+ - sounds good
+
+  3. Build test infrastructure - Set up git fixture creation and FS testing utilities
+- absolutly
+
+  4. Implement incrementally - Phase approach to reduce complexity
+
+  alreight
+
+  The architecture supports your vision, but consider starting simpler and evolving based on real usage patterns.
+
+
+
+  /.legit/status                              // Git status info
+  /.legit/commits/{sha(0,1)}/{sha(2..20)}/path/to/file  // Historical files
+  /.legit/branches/                            // List branches
+  /.legit/branches/{name}/path/to/file     // Branch files (read/write)
+  /.legit/branches/{name}/.legit/head // read/write of the head commit of the branch {name}
+  /.legit/branches/{name}/.legit/tip // read/write of the tip of the branch {name} - keeping this allows undo redo ops
+
+  
+ */
+declare class GitSubFs extends BaseCompositeSubFs implements CompositeSubFs {
+    private static readonly LEGIT_DIR;
+    private static pathRouter;
+    private memFs;
+    private openFh;
+    private virtualFiles;
+    private legitFileNames;
+    constructor({ parentFs, gitRoot, virtualFiles, }: {
+        parentFs: CompositeFs;
+        gitRoot: string;
+        virtualFiles?: VirtualFileDefinition[];
+    });
+    responsible(filePath: string): Promise<boolean>;
+    private isLegitPath;
+    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.
+     *
+     * @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.
+     */
+    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    mkdir(path: PathLike, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
+    access(path: PathLike, mode?: number): Promise<void>;
+    futimes(fh: CompositFsFileHandle, atime: TTime, mtime: TTime): Promise<void>;
+    fstat(fh: CompositFsFileHandle, options?: IStatOptions): Promise<IStats>;
+    ftruncate(fh: CompositFsFileHandle, len?: 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>;
+    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[]>;
+    read(fh: CompositFsFileHandle, buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
+    /**
+     *
+     * Writes (parts) of a buffer to a specific position in the file
+     *
+     * - a write leads to a new commit and on flush since the point in time a flush may occur may vary a read operation may
+     *  not see changed done on the read lays.
+     *
+     *
+     * @param fh
+     * @param buffer
+     * @param offset
+     * @param length
+     * @param position
+     * @returns
+     */
+    write(fh: CompositFsFileHandle, buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
+    close(fh: CompositFsFileHandle): Promise<void>;
+    dataSync(fh: CompositFsFileHandle): Promise<void>;
+    readFile(path: PathLike | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    writeFile(path: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
+    rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
+    fchmod(fh: CompositFsFileHandle, mode: TMode): Promise<void>;
+    unlink(path: PathLike): Promise<void>;
+    fileType(): number;
+}
+
+type Operation = {
+    oid: string;
+    parentOids: string[];
+    message: string;
+};
+declare const gitBranchOperationsVirtualFile: VirtualFileDefinition;
+
+declare function initLegitFs(storageFs: typeof nodeFs, gitRoot: string): Promise<CompositeFs>;
+/**
+ * Creates and configures a LegitFs instance with CompositeFs, GitSubFs, HiddenFileSubFs, and EphemeralSubFs.
+ */
+declare function openLegitFs(storageFs: typeof nodeFs, gitRoot: string): CompositeFs;
+
+declare const createGitSyncService: ({ fs, gitRepoPath, originPrefix, corsProxy, user, password, }: {
+    fs: FsClient;
+    gitRepoPath: string;
+    originPrefix: string;
+    corsProxy?: string | undefined;
+    user: string;
+    password: string;
+}) => {
+    clone: (url: string) => Promise<void>;
+    start: () => void;
+    stop: () => void;
+};
+
+type FileAccess = {
+    fileSave: typeof fileSave;
+};
+declare function getLegitFsAccess(legitFs: ReturnType<typeof openLegitFs>): Promise<FileAccess & {
+    openFile: (filePath: string) => Promise<FileWithHandle>;
+}>;
+
+type User = {
+    name: string;
+    email: string;
+    timestamp: number;
+};
+
+type HistoryItem = {
+    oid: string;
+    message: string;
+    parent: string[];
+    author: User;
+};
+
+export { CompositeFs, EphemeralSubFs, GitSubFs, HiddenFileSubFs, PassThroughSubFs, createGitSyncService, getLegitFsAccess, gitBranchOperationsVirtualFile, initLegitFs, openLegitFs };
+export type { HistoryItem, Operation, User };