@rljson/fs-agent 0.0.2

package/dist/README.trouble.md

@@ -0,0 +1,23 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.

package/dist/client-server/client-server-setup.d.ts

@@ -0,0 +1,17 @@
+export interface ClientServerSetupOptions {
+    baseDir?: string;
+    treeKey?: string;
+}
+export interface ClientServerSetupResult {
+    baseDir: string;
+    folderA: string;
+    folderB: string;
+    contentB: string;
+    cleanup: () => Promise<void>;
+}
+/**
+ * One-shot client/server setup that writes a file in folder A, stores it to a
+ * shared Db, loads into folder B, and returns the synced content.
+ * @param opts - Optional overrides (baseDir, treeKey)
+ */
+export declare function runClientServerSetup(opts?: ClientServerSetupOptions): Promise<ClientServerSetupResult>;

package/dist/client-server/live-client-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example.d.ts

@@ -0,0 +1 @@
+export declare const example: () => Promise<void>;

package/dist/fs-agent.d.ts

@@ -0,0 +1,178 @@
+import { Bs } from '@rljson/bs';
+import { FsBlobAdapter } from './fs-blob-adapter.ts';
+import { StoreFsTreeOptions } from './fs-db-adapter.ts';
+import { FsScanner, FsTree } from './fs-scanner.ts';
+import { Connector, Db } from '@rljson/db';
+/**
+ * Options for FsAgent operations
+ */
+export interface FsAgentOptions {
+    /** Ignore patterns for scanning */
+    ignore?: string[];
+    /** Maximum depth for directory traversal */
+    maxDepth?: number;
+    /** Follow symlinks (default: false) */
+    followSymlinks?: boolean;
+    /** Database instance for automatic syncing */
+    db?: Db;
+    /** Tree key for database storage */
+    treeKey?: string;
+    /** Storage options for database operations */
+    storageOptions?: StoreFsTreeOptions;
+    /** Enable bidirectional sync (both fs→db and db→fs) */
+    bidirectional?: boolean;
+    /** Restore options applied when syncing from DB */
+    restoreOptions?: RestoreOptions;
+}
+/** Restore options */
+export interface RestoreOptions {
+    /** Remove files/dirs on target that are not present in the tree */
+    cleanTarget?: boolean;
+}
+/**
+ * Orchestrates filesystem operations with tree structures and blob storage
+ */
+export declare class FsAgent {
+    private _scanner;
+    private _adapter;
+    private _rootPath;
+    private _bs;
+    private _db?;
+    private _treeKey?;
+    private _stopSync?;
+    private _stopSyncFromDb?;
+    private _lastSentRef?;
+    constructor(rootPath: string, bs?: Bs, options?: FsAgentOptions);
+    /**
+     * Gets the root path
+     */
+    get rootPath(): string;
+    /**
+     * Gets the blob storage instance
+     */
+    get bs(): Bs;
+    /**
+     * Gets the scanner instance
+     */
+    get scanner(): FsScanner;
+    /**
+     * Gets the adapter instance
+     */
+    get adapter(): FsBlobAdapter;
+    /**
+     * Starts automatic syncing to database
+     * Note: Auto-sync requires Connector which is not available in constructor.
+     * Consider using syncToDb() directly instead of constructor options.
+     */
+    private _startAutoSync;
+    /**
+     * Starts automatic syncing from database
+     * @param bidirectional - Whether bidirectional sync is enabled
+     * Note: Auto-sync requires Connector which is not available in constructor.
+     * Consider using syncFromDb() directly instead of constructor options.
+     */
+    private _startAutoSyncFromDb;
+    /**
+     * Stops automatic syncing and cleans up resources
+     */
+    dispose(): void;
+    /**
+     * Extracts filesystem into tree structure with file content in blobs
+     * File content is stored in Bs, tree structure returned with blobIds embedded
+     * @returns Tree structure with blobIds in file metadata
+     */
+    extract(): Promise<FsTree>;
+    /**
+     * Restores filesystem from tree structure and blob storage
+     * @param tree - Tree structure with blobIds in file metadata
+     * @param targetPath - Optional target path (defaults to rootPath)
+     * @param options - Restore options
+     */
+    restore(tree: FsTree, targetPath?: string, options?: RestoreOptions): Promise<void>;
+    /**
+     * Recursively restores a tree node and its children
+     * @param treeHash - Hash of the tree node to restore
+     * @param trees - Map of all tree nodes
+     * @param targetPath - Target directory path
+     */
+    private _restoreTree;
+    /**
+     * Gets the current tree structure
+     */
+    getTree(): FsTree | null;
+    /**
+     * Checks if a blob exists in storage
+     * @param blobId - Blob ID to check
+     */
+    hasBlob(blobId: string): Promise<boolean>;
+    /**
+     * Gets file content from blob storage
+     * @param blobId - Blob ID
+     */
+    getFileContent(blobId: string): Promise<Buffer>;
+    /**
+     * Extracts and stores filesystem tree in database
+     * Reads from filesystem, stores trees in DB and blobs in Bs
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param options - Storage options
+     * @returns The root tree reference
+     */
+    storeInDb(db: Db, treeKey: string, options?: StoreFsTreeOptions): Promise<string>;
+    /**
+     * Recursively fetches all tree nodes starting from a root hash
+     * Trees are stored as separate rows with parent-child relationships
+     * This method follows the tree structure and fetches all related nodes
+     * @param db - Database instance
+     * @param route - Route to tree table
+     * @param treeKey - Tree table key
+     * @param rootHash - Hash of the root node to start fetching from
+     * @returns Array of all tree nodes in the tree
+     */
+    private _fetchTreeRecursively;
+    /**
+     * Loads tree from database and restores to filesystem
+     * Writes to filesystem from DB trees and Bs blobs
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param rootRef - Root tree reference (hash)
+     * @param targetPath - Optional target path (defaults to rootPath)
+     * @param options - Restore options
+     */
+    loadFromDb(db: Db, treeKey: string, rootRef: string, targetPath?: string, options?: RestoreOptions): Promise<void>;
+    /**
+     * Collects expected file and directory paths for cleanup
+     * @param tree - Tree structure to evaluate
+     * @param target - Filesystem root where the tree will be restored
+     */
+    private _collectExpectedPaths;
+    /**
+     * Remove files/dirs not present in the expected sets
+     * @param currentDir - Directory currently being inspected
+     * @param expectedDirs - Allowed directory paths
+     * @param expectedFiles - Allowed file paths
+     */
+    private _pruneExtraneous;
+    /**
+     * Watches filesystem for changes and syncs to database
+     * Uses Connector for socket-based broadcast
+     * @param db - Database instance
+     * @param connector - Connector instance for socket-based sync
+     * @param treeKey - Tree table key
+     * @param options - Storage options (e.g., notify)
+     * @returns Function to stop watching
+     */
+    syncToDb(db: Db, connector: Connector, treeKey: string, options?: StoreFsTreeOptions): Promise<() => void>;
+    /**
+     * Watches database for tree changes and syncs to filesystem
+     * Uses Connector for socket-based notifications
+     * @param db - Database instance
+     * @param connector - Connector instance for socket-based sync
+     * @param treeKey - Tree table key
+     * @param restoreOptions - Restore options (e.g., cleanTarget)
+     * @returns Function to stop watching
+     */
+    syncFromDb(db: Db, connector: Connector, treeKey: string, restoreOptions?: RestoreOptions): Promise<() => void>;
+    /** Example instance for test purposes */
+    static get example(): FsAgent;
+}