@legit-sdk/core 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -198,7 +198,14 @@ declare class CompositeFs {
         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[]>;
+        readdir: {
+            (dirPath: nodeFs.PathLike, options?: string | {
+                withFileTypes?: false;
+            }): Promise<string[]>;
+            (dirPath: nodeFs.PathLike, options: {
+                withFileTypes: true;
+            }): Promise<nodeFs.Dirent[]>;
+        };
         open: (filePath: string, flags: string, mode?: number) => Promise<CompositFsFileHandle>;
         stat: (path: nodeFs.PathLike, opts?: {
             bigint?: boolean;
@@ -224,16 +231,16 @@ declare class CompositeFs {
     parentFs: CompositeFs | undefined;
     name: string;
     defaultBranch: string;
+    gitCache: any;
     pathToFileDescriptors: Map<
     /** path */
     string, number[]>;
     openFileHandles: Map<number, CompositFsFileHandle>;
     logOperation: FsOperationLogger | undefined;
     private getNextFileDescriptor;
-    constructor({ name, parentFs, storageFs, gitRoot, defaultBranch, }: {
+    constructor({ name, storageFs, gitRoot, defaultBranch, }: {
         name: string;
-        parentFs: CompositeFs | undefined;
-        storageFs: typeof nodeFs | undefined;
+        storageFs: typeof nodeFs;
         gitRoot: string;
         defaultBranch?: string;
     });
@@ -255,8 +262,6 @@ declare class CompositeFs {
     /**
      * Read dir needs to check if one subfs takes control.
      *
-     * TODO also implement the option to return stats
-     *
      * @param dirPath
      * @param options
      * @returns
@@ -321,7 +326,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, }: {
+declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFiles, initialAuthor, serverUrl, publicKey, claudeHandler, }: {
     storageFs: typeof nodeFs;
     gitRoot: string;
     anonymousBranch?: string;
@@ -329,6 +334,7 @@ declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFile
     initialAuthor?: LegitUser;
     serverUrl?: string;
     publicKey?: string;
+    claudeHandler?: boolean;
 }): Promise<CompositeFs & {
     auth: LegitAuth;
     sync: {
@@ -595,7 +601,7 @@ type VirtualFile = {
     size?: number;
 } | {
     type: 'directory';
-    content: string[];
+    content: nodeFs.Dirent[];
     oid?: string | undefined;
     mode?: number;
 };
@@ -603,6 +609,7 @@ interface VirtualFileArgs {
     cacheFs: IFs;
     filePath: string;
     gitRoot: string;
+    userSpaceFs: CompositeFs;
     nodeFs?: any;
     pathParams: any;
     author: {
@@ -614,6 +621,7 @@ interface VirtualFileArgs {
 }
 type VirtualFileDefinition = {
     type: string;
+    rootType: 'folder' | 'file';
     getFile: (args: VirtualFileArgs) => Promise<VirtualFile | undefined>;
     getStats: (args: VirtualFileArgs) => Promise<nodeFs.Stats>;
     onFileChanged?: (args: VirtualFileArgs) => Promise<void>;
@@ -631,128 +639,52 @@ type VirtualFileDefinition = {
     rmdir?: (args: VirtualFileArgs) => 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
+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.
+ *
+ *
+ * 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 static pathRouter;
+    private pathRouter;
     private memFs;
     private openFh;
-    private virtualFiles;
-    private legitFileNames;
-    storageFs: CompositeFs;
+    storageFs: any;
     getAuthor(): Promise<{
         name: string;
         email: string;
         date: number;
         timezoneOffset: number;
     }>;
-    constructor({ name, parentFs, gitStorageFs, gitRoot, virtualFiles, }: {
+    constructor({ name, parentFs, gitStorageFs, gitRoot, routerConfig, }: {
         name: string;
         parentFs: CompositeFs;
-        gitStorageFs: CompositeFs;
+        gitStorageFs: any;
         gitRoot: string;
-        virtualFiles?: VirtualFileDefinition[];
+        routerConfig: LegitRouteFolder;
     });
     responsible(filePath: string): Promise<boolean>;
-    private isLegitPath;
     private getRouteHandler;
     /**
      * Opens a virtual file from the Git-based virtual file system.