@rljson/fs-agent 0.0.2 → 0.0.4

package/README.architecture.md

@@ -447,3 +447,50 @@ This peer-to-peer pattern with server coordination enables:
 ✅ **Real-world deployment**: Works across networks, not just in-memory mocks
 
 **This is why clients must NEVER access server Io/Bs directly** - it would bypass the entire peer-to-peer mechanism and make the system only work in single-process scenarios.
+
+## Bounce-Back Prevention
+
+Bidirectional sync creates a potential infinite loop:
+
+```
+Client A writes file → syncToDb stores tree → broadcasts ref →
+Client B receives ref → syncFromDb restores file → fs watcher fires →
+syncToDb stores tree → broadcasts ref → Client A receives ref → ...
+```
+
+FsAgent uses three layers of deduplication to break the loop:
+
+1. **Ref-level dedup**: After `syncToDb` stores a tree, it compares the
+   resulting ref against `_lastSentRef`. If identical, no broadcast occurs.
+
+2. **Content-key dedup**: Even when refs differ (e.g. different mtimes produce
+   different hashes), `syncToDb` computes a content key from file paths +
+   blobIds. If the content key matches `_lastSentContentKey`, the broadcast
+   is skipped.
+
+3. **Content comparison before restore**: In `syncFromDb`, before restoring
+   an incoming tree, FsAgent compares its file content map against the current
+   filesystem. If they are equivalent, the restore is skipped entirely,
+   preventing the filesystem watcher from firing.
+
+Additionally, all sync callbacks are **debounced** (default 300ms) to coalesce
+rapid filesystem events (e.g. multi-file saves, editor autosave) into a single
+sync operation.
+
+## Known Constraints
+
+### macOS Finder Paste and Rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS). This works
+reliably for programmatic file operations (Node.js `writeFile`/`copyFile`,
+terminal commands, editor saves) but **not** for macOS Finder's paste-and-rename
+workflow.
+
+Finder generates rapid, non-atomic, multi-step event sequences (create temp →
+write → rename → delete temp) that FSEvents may coalesce, reorder, or split
+unpredictably. This causes intermediate filesystem states to be scanned and
+broadcast before the operation completes, leading to sync conflicts.
+
+**This is a known limitation and is not supported.** Use programmatic operations
+or terminal commands instead of Finder drag-and-drop or paste-and-rename for
+files in synced folders.

package/README.contributors.md

@@ -13,6 +13,10 @@ found in the LICENSE file in the root of this package.
 - [Administrate](#administrate)
 - [Fast Coding](#fast-coding)
 
+## ⚠️ Important: ESLint Version
+
+**Do NOT update ESLint to v10.x** - The package is pinned to `eslint ~9.39.2` because `eslint-plugin-tsdoc@0.5.0` is incompatible with ESLint v10's API changes (specifically `context.getSourceCode()` was removed). Updating to v10 will break the build.
+
 ## Prepare
 
 Read [prepare.md](doc/prepare.md)

package/README.public.md

@@ -21,9 +21,11 @@ found in the LICENSE file in the root of this package.
 - 💾 **Smart Storage**: Content-addressed blob storage eliminates duplicate file content
 - 📜 **Version History**: Every change is tracked with complete insert history
 - 🔁 **Bidirectional Sync**: Changes in either direction are automatically propagated
-- 🛡️ **Loop Prevention**: Intelligent pause/resume mechanism prevents infinite sync loops
+- 🛡️ **Loop Prevention**: Content-based dedup, ref tracking, and debounce prevent infinite sync loops
+- ⏱️ **Timeout Guards**: Every async operation is bounded to prevent silent hangs
+- 🎯 **Debounce**: Rapid filesystem events are coalesced into a single sync cycle
 - ✅ **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 🧪 **Battle-Tested**: 100% test coverage with 139 tests
+- 🧪 **Battle-Tested**: 100% test coverage with 204 tests (SocketMock + Socket.IO)
 - 🧹 **Target Cleanup**: Optional `cleanTarget` restore prunes stale files and directories
 
 ## Installation
@@ -700,6 +702,36 @@ try {
 }
 ```
 
+## Timeout & Debounce Configuration
+
+Every async operation in FsAgent is guarded by a timeout to prevent silent hangs.
+Rapid filesystem events are debounced to coalesce into a single sync cycle.
+
+```typescript
+const agent = new FsAgent('./my-project', bs, {
+  timeouts: {
+    dbQuery: 10_000,      // Single db.get() query (default: 10s)
+    fetchTree: 20_000,    // Fetching an entire tree from the DB (default: 20s)
+    extract: 15_000,      // Filesystem extract/scan (default: 15s)
+    restore: 15_000,      // Filesystem restore (default: 15s)
+    syncCallback: 25_000, // Overall syncFromDb callback (default: 25s)
+    debounceMs: 300,      // Coalesce rapid FS events (default: 300ms)
+  },
+});
+```
+
+## Bounce-Back Prevention
+
+Bidirectional sync can cause infinite loops when both clients detect each
+other's restores as changes. FsAgent prevents this with three layers:
+
+1. **Ref tracking** (`_lastSentRef`): Skips re-broadcast if the stored tree
+   produces the same ref as the last one we sent.
+2. **Content-key dedup** (`_lastSentContentKey`): Compares file paths + blobIds
+   (ignoring mtimes) to detect identical content with different tree hashes.
+3. **Content comparison before restore**: `syncFromDb` compares the incoming
+   tree's content with the current filesystem and skips restore if identical.
+
 ## Performance
 
 - **Efficient Scanning**: Only scans changed directories
@@ -707,6 +739,8 @@ try {
 - **Content-Addressed**: Fast lookups via hashes
 - **Optimized Watching**: Uses native filesystem events
 - **Smart Sync**: Only syncs when changes detected
+- **Debounced Events**: Rapid changes coalesced into single operations
+- **Bounded Operations**: All async operations time out to prevent hangs
 
 ## Troubleshooting
 
@@ -763,6 +797,29 @@ ignore: ['*'];
 ignore: ['node_modules', '*.log'];
 ```
 
+## Known Constraints
+
+### macOS Finder paste and rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS) to detect
+filesystem changes. This works reliably for **programmatic** file operations:
+
+- ✅ `writeFile`, `copyFile`, `rename` from Node.js or shell commands
+- ✅ Editor saves (VS Code, Vim, etc.)
+- ✅ Terminal commands (`echo`, `cp`, `mv`, `touch`, etc.)
+- ✅ Application-generated file changes
+
+However, **macOS Finder's paste-and-rename workflow** generates rapid,
+non-atomic, multi-step event sequences (create temporary file → write → rename →
+delete temporary) that FSEvents may coalesce, reorder, or split unpredictably.
+This can cause intermediate states to be scanned and broadcast before the
+operation completes, leading to sync conflicts.
+
+**This is a known limitation of filesystem watching on macOS and is not
+supported.** If you need to add or rename files in synced folders, use
+programmatic operations or terminal commands instead of Finder drag-and-drop or
+paste-and-rename.
+
 ## Related Packages
 
 - `@rljson/db` - RLJSON database

package/dist/README.architecture.md

@@ -447,3 +447,50 @@ This peer-to-peer pattern with server coordination enables:
 ✅ **Real-world deployment**: Works across networks, not just in-memory mocks
 
 **This is why clients must NEVER access server Io/Bs directly** - it would bypass the entire peer-to-peer mechanism and make the system only work in single-process scenarios.
+
+## Bounce-Back Prevention
+
+Bidirectional sync creates a potential infinite loop:
+
+```
+Client A writes file → syncToDb stores tree → broadcasts ref →
+Client B receives ref → syncFromDb restores file → fs watcher fires →
+syncToDb stores tree → broadcasts ref → Client A receives ref → ...
+```
+
+FsAgent uses three layers of deduplication to break the loop:
+
+1. **Ref-level dedup**: After `syncToDb` stores a tree, it compares the
+   resulting ref against `_lastSentRef`. If identical, no broadcast occurs.
+
+2. **Content-key dedup**: Even when refs differ (e.g. different mtimes produce
+   different hashes), `syncToDb` computes a content key from file paths +
+   blobIds. If the content key matches `_lastSentContentKey`, the broadcast
+   is skipped.
+
+3. **Content comparison before restore**: In `syncFromDb`, before restoring
+   an incoming tree, FsAgent compares its file content map against the current
+   filesystem. If they are equivalent, the restore is skipped entirely,
+   preventing the filesystem watcher from firing.
+
+Additionally, all sync callbacks are **debounced** (default 300ms) to coalesce
+rapid filesystem events (e.g. multi-file saves, editor autosave) into a single
+sync operation.
+
+## Known Constraints
+
+### macOS Finder Paste and Rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS). This works
+reliably for programmatic file operations (Node.js `writeFile`/`copyFile`,
+terminal commands, editor saves) but **not** for macOS Finder's paste-and-rename
+workflow.
+
+Finder generates rapid, non-atomic, multi-step event sequences (create temp →
+write → rename → delete temp) that FSEvents may coalesce, reorder, or split
+unpredictably. This causes intermediate filesystem states to be scanned and
+broadcast before the operation completes, leading to sync conflicts.
+
+**This is a known limitation and is not supported.** Use programmatic operations
+or terminal commands instead of Finder drag-and-drop or paste-and-rename for
+files in synced folders.

package/dist/README.contributors.md

@@ -13,6 +13,10 @@ found in the LICENSE file in the root of this package.
 - [Administrate](#administrate)
 - [Fast Coding](#fast-coding)
 
+## ⚠️ Important: ESLint Version
+
+**Do NOT update ESLint to v10.x** - The package is pinned to `eslint ~9.39.2` because `eslint-plugin-tsdoc@0.5.0` is incompatible with ESLint v10's API changes (specifically `context.getSourceCode()` was removed). Updating to v10 will break the build.
+
 ## Prepare
 
 Read [prepare.md](doc/prepare.md)

package/dist/README.public.md

@@ -21,9 +21,11 @@ found in the LICENSE file in the root of this package.
 - 💾 **Smart Storage**: Content-addressed blob storage eliminates duplicate file content
 - 📜 **Version History**: Every change is tracked with complete insert history
 - 🔁 **Bidirectional Sync**: Changes in either direction are automatically propagated
-- 🛡️ **Loop Prevention**: Intelligent pause/resume mechanism prevents infinite sync loops
+- 🛡️ **Loop Prevention**: Content-based dedup, ref tracking, and debounce prevent infinite sync loops
+- ⏱️ **Timeout Guards**: Every async operation is bounded to prevent silent hangs
+- 🎯 **Debounce**: Rapid filesystem events are coalesced into a single sync cycle
 - ✅ **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 🧪 **Battle-Tested**: 100% test coverage with 139 tests
+- 🧪 **Battle-Tested**: 100% test coverage with 204 tests (SocketMock + Socket.IO)
 - 🧹 **Target Cleanup**: Optional `cleanTarget` restore prunes stale files and directories
 
 ## Installation
@@ -700,6 +702,36 @@ try {
 }
 ```
 
+## Timeout & Debounce Configuration
+
+Every async operation in FsAgent is guarded by a timeout to prevent silent hangs.
+Rapid filesystem events are debounced to coalesce into a single sync cycle.
+
+```typescript
+const agent = new FsAgent('./my-project', bs, {
+  timeouts: {
+    dbQuery: 10_000,      // Single db.get() query (default: 10s)
+    fetchTree: 20_000,    // Fetching an entire tree from the DB (default: 20s)
+    extract: 15_000,      // Filesystem extract/scan (default: 15s)
+    restore: 15_000,      // Filesystem restore (default: 15s)
+    syncCallback: 25_000, // Overall syncFromDb callback (default: 25s)
+    debounceMs: 300,      // Coalesce rapid FS events (default: 300ms)
+  },
+});
+```
+
+## Bounce-Back Prevention
+
+Bidirectional sync can cause infinite loops when both clients detect each
+other's restores as changes. FsAgent prevents this with three layers:
+
+1. **Ref tracking** (`_lastSentRef`): Skips re-broadcast if the stored tree
+   produces the same ref as the last one we sent.
+2. **Content-key dedup** (`_lastSentContentKey`): Compares file paths + blobIds
+   (ignoring mtimes) to detect identical content with different tree hashes.
+3. **Content comparison before restore**: `syncFromDb` compares the incoming
+   tree's content with the current filesystem and skips restore if identical.
+
 ## Performance
 
 - **Efficient Scanning**: Only scans changed directories
@@ -707,6 +739,8 @@ try {
 - **Content-Addressed**: Fast lookups via hashes
 - **Optimized Watching**: Uses native filesystem events
 - **Smart Sync**: Only syncs when changes detected
+- **Debounced Events**: Rapid changes coalesced into single operations
+- **Bounded Operations**: All async operations time out to prevent hangs
 
 ## Troubleshooting
 
@@ -763,6 +797,29 @@ ignore: ['*'];
 ignore: ['node_modules', '*.log'];
 ```
 
+## Known Constraints
+
+### macOS Finder paste and rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS) to detect
+filesystem changes. This works reliably for **programmatic** file operations:
+
+- ✅ `writeFile`, `copyFile`, `rename` from Node.js or shell commands
+- ✅ Editor saves (VS Code, Vim, etc.)
+- ✅ Terminal commands (`echo`, `cp`, `mv`, `touch`, etc.)
+- ✅ Application-generated file changes
+
+However, **macOS Finder's paste-and-rename workflow** generates rapid,
+non-atomic, multi-step event sequences (create temporary file → write → rename →
+delete temporary) that FSEvents may coalesce, reorder, or split unpredictably.
+This can cause intermediate states to be scanned and broadcast before the
+operation completes, leading to sync conflicts.
+
+**This is a known limitation of filesystem watching on macOS and is not
+supported.** If you need to add or rename files in synced folders, use
+programmatic operations or terminal commands instead of Finder drag-and-drop or
+paste-and-rename.
+
 ## Related Packages
 
 - `@rljson/db` - RLJSON database

package/dist/client-server/example-from-client.d.ts

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

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

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

package/dist/fs-agent.d.ts

@@ -1,4 +1,5 @@
 import { Bs } from '@rljson/bs';
+import { ClientId, SyncConfig } from '@rljson/rljson';
 import { FsBlobAdapter } from './fs-blob-adapter.ts';
 import { StoreFsTreeOptions } from './fs-db-adapter.ts';
 import { FsScanner, FsTree } from './fs-scanner.ts';
@@ -23,12 +24,56 @@ export interface FsAgentOptions {
     bidirectional?: boolean;
     /** Restore options applied when syncing from DB */
     restoreOptions?: RestoreOptions;
+    /** Timeout configuration for async operations */
+    timeouts?: TimeoutConfig;
+    /**
+     * Centralized sync protocol configuration.
+     * When provided, this SyncConfig is forwarded to every Connector
+     * created by {@link FsAgent.fromClient}, and governs whether
+     * `sendWithAck()` (when `requireAck` is true) or `send()` is used
+     * in {@link FsAgent.syncToDb}.
+     *
+     * The same SyncConfig should also be passed to the Server and Client
+     * constructors so that every layer uses the same protocol settings.
+     */
+    syncConfig?: SyncConfig;
+    /**
+     * Stable client identity. When provided, it is forwarded to every
+     * Connector created by {@link FsAgent.fromClient}. When omitted but
+     * `syncConfig.includeClientIdentity` is true, each Connector
+     * auto-generates its own identity.
+     */
+    clientIdentity?: ClientId;
 }
 /** Restore options */
 export interface RestoreOptions {
     /** Remove files/dirs on target that are not present in the tree */
     cleanTarget?: boolean;
 }
+/**
+ * Timeout configuration for async operations (milliseconds).
+ * Every async operation in FsAgent is guarded by a timeout to prevent
+ * silent hangs in socket communication, filesystem I/O, or database queries.
+ */
+export interface TimeoutConfig {
+    /** Timeout for a single db.get() query. Default: 10 000 ms */
+    dbQuery?: number;
+    /** Timeout for fetching an entire tree from the DB. Default: 20 000 ms */
+    fetchTree?: number;
+    /** Timeout for a filesystem extract / scan. Default: 15 000 ms */
+    extract?: number;
+    /** Timeout for a filesystem restore. Default: 15 000 ms */
+    restore?: number;
+    /** Timeout for the overall syncFromDb callback. Default: 25 000 ms */
+    syncCallback?: number;
+    /**
+     * Debounce delay for sync callbacks (milliseconds). Default: 300 ms.
+     * Rapid filesystem events (e.g. macOS Finder "Keep Both" copy+rename)
+     * are coalesced into a single sync operation after this quiet period.
+     * Also applies to incoming database refs in syncFromDb.
+     */
+    debounceMs?: number;
+}
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
@@ -42,6 +87,9 @@ export declare class FsAgent {
     private _stopSync?;
     private _stopSyncFromDb?;
     private _lastSentRef?;
+    /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
+    private _lastSentContentKey?;
+    private _timeouts;
     constructor(rootPath: string, bs?: Bs, options?: FsAgentOptions);
     /**
      * Gets the root path
@@ -59,6 +107,27 @@ export declare class FsAgent {
      * Gets the adapter instance
      */
     get adapter(): FsBlobAdapter;
+    /**
+     * Gets the current timeout configuration
+     */
+    get timeouts(): Required<TimeoutConfig>;
+    /**
+     * Wraps a promise with a timeout.
+     * Rejects with a descriptive error if the promise does not settle
+     * within the given number of milliseconds.
+     * @param promise - The promise to guard
+     * @param ms - Maximum allowed time in milliseconds
+     * @param label - Human-readable label included in the error message
+     */
+    private static _withTimeout;
+    /**
+     * Sends a ref through the connector.
+     * Uses `sendWithAck()` when the connector has `requireAck` enabled,
+     * otherwise falls back to fire-and-forget `send()`.
+     * @param connector - The Connector to send through
+     * @param ref - The ref to broadcast
+     */
+    private _sendRef;
     /**
      * Starts automatic syncing to database
      * Note: Auto-sync requires Connector which is not available in constructor.
@@ -130,6 +199,15 @@ export declare class FsAgent {
      * @returns Array of all tree nodes in the tree
      */
     private _fetchTreeRecursively;
+    /**
+     * Fetches tree from database without restoring to filesystem.
+     * Separated from loadFromDb to allow content comparison before restore.
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param rootRef - Root tree reference (hash)
+     * @returns FsTree structure ready for restore
+     */
+    private _fetchTreeFromDb;
     /**
      * Loads tree from database and restores to filesystem
      * Writes to filesystem from DB trees and Bs blobs
@@ -159,10 +237,37 @@ export declare class FsAgent {
      * @param db - Database instance
      * @param connector - Connector instance for socket-based sync
      * @param treeKey - Tree table key
-     * @param options - Storage options (e.g., notify)
+     * @param options - Storage options (e.g., skipNotification)
      * @returns Function to stop watching
      */
     syncToDb(db: Db, connector: Connector, treeKey: string, options?: StoreFsTreeOptions): Promise<() => void>;
+    /**
+     * Builds a map of relativePath → blobId for all files in a tree.
+     * Used to compare trees by content rather than by hash (which includes mtime).
+     * @param tree - Tree structure to extract file content map from
+     */
+    private _getFileContentMap;
+    /**
+     * Derives a deterministic string key from a content map so that two trees
+     * with identical file paths + blobIds produce the same key regardless of
+     * mtime differences.
+     * @param map - Content map (relativePath → blobId)
+     */
+    private _contentKeyFromMap;
+    /**
+     * Derives a deterministic content key from an FsTree.
+     * @param tree - Tree structure to derive content key from
+     */
+    private _contentKeyFromTree;
+    /**
+     * Compares two trees by file content (relativePath + blobId).
+     * Ignores mtime differences — trees are equivalent if they have the same
+     * files with the same content. This prevents bounce-back restores from
+     * destroying locally-created files during bidirectional sync.
+     * @param a - First tree to compare
+     * @param b - Second tree to compare
+     */
+    private _treesHaveEquivalentContent;
     /**
      * Watches database for tree changes and syncs to filesystem
      * Uses Connector for socket-based notifications
@@ -173,6 +278,37 @@ export declare class FsAgent {
      * @returns Function to stop watching
      */
     syncFromDb(db: Db, connector: Connector, treeKey: string, restoreOptions?: RestoreOptions): Promise<() => void>;
+    /**
+     * Creates a fully configured FsAgent from a Client instance.
+     * This factory method provides a simplified API where sync methods don't require
+     * db, connector, and treeKey parameters - they are stored internally.
+     * @param filePath - Directory path to sync
+     * @param treeKey - Tree table key (route will be `/${treeKey}`)
+     * @param client - Client instance with io and bs properties
+     * @param socket - Socket instance for connector communication
+     * @param options - Optional FsAgent options (db and treeKey are set automatically).
+     *   `syncConfig` and `clientIdentity` from these options are forwarded to
+     *   the Connector so that a single config origin governs all layers.
+     * @returns Configured FsAgent instance with simplified sync API
+     * @example
+     * ```typescript
+     * const syncConfig: SyncConfig = { requireAck: true, maxDedupSetSize: 5000 };
+     * const agent = await FsAgent.fromClient(
+     *   './my-folder', 'sharedTree', client, socket, { syncConfig },
+     * );
+     * // Simplified sync methods - no db/connector/treeKey needed
+     * await agent.syncToDbSimple();
+     * await agent.syncFromDbSimple({ cleanTarget: true });
+     * // Original methods still work
+     * await agent.syncToDb(db, connector, treeKey);
+     * ```
+     */
+    static fromClient(filePath: string, treeKey: string, client: any, // Client type from \@rljson/server
+    socket: any, // Socket type from \@rljson/io
+    options?: Omit<FsAgentOptions, 'db' | 'treeKey'>): Promise<FsAgent & {
+        syncToDbSimple: (options?: StoreFsTreeOptions) => Promise<() => void>;
+        syncFromDbSimple: (options?: RestoreOptions) => Promise<() => void>;
+    }>;
     /** Example instance for test purposes */
     static get example(): FsAgent;
 }