@rljson/fs-agent 0.0.14 → 0.0.15

package/dist/fs-agent.d.ts

@@ -107,6 +107,12 @@ export interface TimeoutConfig {
 }
 /** Filename for sync error log written to the sync folder */
 export declare const SYNC_ERROR_FILE = ".sync-errors.log";
+/**
+ * Filename prefix for the staging files used by atomic writes. The scanner
+ * ignores anything starting with this so the transient temp + rename never
+ * pollutes the tree or churns the watcher.
+ */
+export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
@@ -167,6 +173,31 @@ export declare class FsAgent {
      * @returns A message string.
      */
     private static _errMessage;
+    /**
+     * Retries an async operation up to `attempts` times with exponential backoff
+     * (each delay doubles from `baseDelayMs`). For transient failures — a file
+     * briefly locked by antivirus or a save-and-rename editor, a peer briefly
+     * unreachable. Non-final failures are logged once at warn level so retry
+     * pressure is visible without log-spam.
+     * @param fn - The operation to run
+     * @param attempts - Maximum number of attempts
+     * @param baseDelayMs - Initial backoff delay (doubles each retry)
+     * @param label - Human-readable label for log messages
+     * @returns The operation's resolved value
+     */
+    private static _withRetry;
+    /**
+     * Atomically writes a file: stages the content in a sibling `.<rand>.tmp`,
+     * then renames over the target. The rename is atomic, so a crash mid-write
+     * leaves only the temp behind — never a half-written target file. (We do not
+     * `fsync` the temp: it adds significant per-file latency under bursty
+     * restores, and durability-on-power-loss is secondary here since the content
+     * is replicated and re-synced.) The random suffix keeps concurrent restores
+     * of the same path from trampling each other.
+     * @param filePath - Destination path
+     * @param content - Bytes to write
+     */
+    private static _atomicWriteFile;
     /**
      * Wraps a promise with a timeout.
      * Rejects with a descriptive error if the promise does not settle
@@ -217,6 +248,14 @@ export declare class FsAgent {
      * @param options - Restore options
      */
     restore(tree: FsTree, targetPath?: string, options?: RestoreOptions): Promise<void>;
+    /**
+     * Recursively collects the absolute paths of all files under `currentDir`.
+     * Used to snapshot the pre-restore file set for prune race-protection.
+     * @param currentDir - Directory to walk
+     * @param out - Accumulator set (created if omitted)
+     * @returns The set of absolute file paths
+     */
+    private _collectAllFiles;
     /**
      * Recursively restores a tree node and its children
      * @param treeHash - Hash of the tree node to restore
@@ -284,10 +323,13 @@ export declare class FsAgent {
      */
     private _collectExpectedPaths;
     /**
-     * Remove files/dirs not present in the expected sets
+     * Remove files/dirs not present in the expected sets, preserving any file
+     * that appeared *during* the restore (not in `preRestore`) — a fresh user
+     * write that must not be clobbered.
      * @param currentDir - Directory currently being inspected
      * @param expectedDirs - Allowed directory paths
      * @param expectedFiles - Allowed file paths
+     * @param preRestore - Files present before the restore (prune candidates)
      */
     private _pruneExtraneous;
     /**

package/dist/fs-agent.js

@@ -1,7 +1,7 @@
 import { BsMem } from "@rljson/bs";
 import { Route, createTreesTableCfg } from "@rljson/rljson";
 import { watch, appendFileSync } from "fs";
-import { stat, readFile, mkdir, writeFile, readdir, utimes, rm } from "fs/promises";
+import { stat, readFile, mkdir, writeFile, readdir, rename, unlink, utimes, rm } from "fs/promises";
 import { dirname, join } from "path";
 import { hip } from "@rljson/hash";
 import { Db } from "@rljson/db";
@@ -422,6 +422,10 @@ class FsScanner {
   _bs;
   _paused = false;
   _missedChangesDuringPause = false;
+  /** Periodic full-rescan timer that catches events the native watcher drops. */
+  _safetyTimer = null;
+  /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
+  _stopRequested = false;
   constructor(rootPath, options = {}) {
     this._rootPath = rootPath;
     this._options = {
@@ -591,18 +595,102 @@ class FsScanner {
     if (!this._tree) {
       await this.scan();
     }
-    this._watcher = watch(
-      this._rootPath,
-      { recursive: true },
-      /* v8 ignore next -- @preserve */
-      async (eventType, filename) => {
-        if (!filename) return;
-        if (this._shouldIgnore(filename)) {
-          return;
+    const onEvent = async (eventType, filename) => {
+      if (!filename) return;
+      if (this._shouldIgnore(filename)) {
+        return;
+      }
+      await this._handleFileChange(eventType, filename);
+    };
+    const onError = (err) => {
+      console.warn(
+        `[fs-scanner] watcher error: ${FsScanner._errMessage(err)} — reinstalling`
+      );
+      try {
+        this._watcher?.close();
+      } catch {
+      }
+      this._watcher = null;
+      setTimeout(() => {
+        if (this._stopRequested) return;
+        try {
+          this._watcher = watch(this._rootPath, { recursive: true }, onEvent);
+          if (FsScanner._isWindows) this._watcher.on("error", onError);
+        } catch (e) {
+          console.warn(
+            `[fs-scanner] watcher reinstall failed: ${FsScanner._errMessage(e)}`
+          );
         }
-        await this._handleFileChange(eventType, filename);
+      }, 500);
+    };
+    this._stopRequested = false;
+    this._watcher = watch(this._rootPath, { recursive: true }, onEvent);
+    if (FsScanner._isWindows) this._watcher.on("error", onError);
+    if (!this._safetyTimer) {
+      this._safetyTimer = setInterval(() => {
+        void this._runSafetyRescan();
+      }, 3e4);
+      this._safetyTimer.unref?.();
+    }
+  }
+  /**
+   * One safety-rescan pass: rescans the tree and, if its content differs from
+   * the previous scan (the native watcher dropped an event), emits a sync
+   * notification so syncToDb reconciles the drift. Paused/stopped scanners and
+   * scan failures are no-ops.
+   */
+  async _runSafetyRescan() {
+    if (this._paused || this._stopRequested) return;
+    const prevKey = this._tree ? this._safetyContentKey(this._tree) : null;
+    try {
+      await this.scan();
+    } catch (err) {
+      console.warn(
+        `[fs-scanner] safety rescan failed: ${FsScanner._errMessage(err)}`
+      );
+      return;
+    }
+    if (this._paused || this._stopRequested) return;
+    const nextKey = this._tree ? this._safetyContentKey(this._tree) : null;
+    if (prevKey !== nextKey) {
+      console.warn(
+        `[fs-scanner] safety rescan detected drift on ${this._rootPath} — notifying`
+      );
+      await this._notifyChange({ type: "safety-rescan", path: "." });
+    }
+  }
+  /**
+   * Path+blobId content fingerprint used by the safety rescan to detect drift
+   * the native watcher missed (mtime-independent, same idea as the agent's
+   * content key but local to the scanner).
+   * @param tree - The tree to fingerprint
+   * @returns A stable content key
+   */
+  _safetyContentKey(tree) {
+    const parts = [];
+    for (const [, node] of tree.trees) {
+      const meta = node.meta;
+      if (!meta) continue;
+      if (meta.type === "file") {
+        parts.push(`${meta.relativePath}:${meta.blobId ?? ""}`);
+      } else if (meta.type === "directory" && meta.relativePath !== ".") {
+        parts.push(`d:${meta.relativePath}`);
       }
-    );
+    }
+    parts.sort();
+    return parts.join("\n");
+  }
+  /**
+   * Extracts a readable message from a thrown value.
+   * @param err - The caught value
+   * @returns A message string
+   */
+  static _errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  /** Whether the host is Windows — gates Windows-specific watcher hardening. */
+  static get _isWindows() {
+    return process.platform === "win32";
   }
   async _handleFileChange(_eventType, filename) {
     if (this._paused) {
@@ -610,23 +698,35 @@ class FsScanner {
       return;
     }
     const relativePath = filename.replace(/\\/g, "/");
+    const fullPath = join(this._rootPath, filename);
+    let exists = false;
+    if (FsScanner._isWindows) {
+      for (let i = 0; i < 4; i++) {
+        try {
+          await stat(fullPath);
+          exists = true;
+          break;
+        } catch {
+          if (i < 3) await new Promise((r) => setTimeout(r, 80 + i * 80));
+        }
+      }
+    } else {
+      try {
+        await stat(fullPath);
+        exists = true;
+      } catch {
+      }
+    }
     try {
-      await stat(join(this._rootPath, filename));
-      const existingTree = this._findTreeByPath(relativePath);
-      if (!existingTree) {
+      if (exists) {
+        const existingTree = this._findTreeByPath(relativePath);
         await this.scan();
         await this._notifyChange({
-          type: "added",
-          path: relativePath
-        });
-      } else {
-        await this.scan();
-        await this._notifyChange({
-          type: "modified",
+          type: existingTree ? "modified" : "added",
           path: relativePath
         });
+        return;
       }
-    } catch {
       let rootExists = false;
       try {
         await stat(this._rootPath);
@@ -635,15 +735,10 @@ class FsScanner {
         this.stopWatch();
       }
       if (rootExists) {
-        try {
-          await this.scan();
-          await this._notifyChange({
-            type: "deleted",
-            path: relativePath
-          });
-        } catch {
-        }
+        await this.scan();
+        await this._notifyChange({ type: "deleted", path: relativePath });
       }
+    } catch {
     }
   }
   _findTreeByPath(relativePath) {
@@ -673,6 +768,11 @@ class FsScanner {
     );
   }
   stopWatch() {
+    this._stopRequested = true;
+    if (this._safetyTimer) {
+      clearInterval(this._safetyTimer);
+      this._safetyTimer = null;
+    }
     if (this._watcher) {
       this._watcher.close();
       this._watcher = null;
@@ -754,6 +854,7 @@ const DEFAULT_TIMEOUTS = {
   recoveryRetries: 10
 };
 const SYNC_ERROR_FILE = ".sync-errors.log";
+const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 class FsAgent {
   _scanner;
   _adapter;
@@ -785,7 +886,7 @@ class FsAgent {
     this._resolveConflicts = options.resolveConflicts ?? false;
     this._scanner = new FsScanner(rootPath, {
       ...options,
-      ignore: [...options.ignore || [], SYNC_ERROR_FILE],
+      ignore: [...options.ignore || [], SYNC_ERROR_FILE, ATOMIC_TMP_PREFIX],
       bs: this._bs
     });
     this._adapter = new FsBlobAdapter(this._bs);
@@ -852,6 +953,68 @@ ${err.stack}` : String(err);
   static _errMessage(err) {
     return err instanceof Error ? err.message : String(err);
   }
+  /**
+   * Retries an async operation up to `attempts` times with exponential backoff
+   * (each delay doubles from `baseDelayMs`). For transient failures — a file
+   * briefly locked by antivirus or a save-and-rename editor, a peer briefly
+   * unreachable. Non-final failures are logged once at warn level so retry
+   * pressure is visible without log-spam.
+   * @param fn - The operation to run
+   * @param attempts - Maximum number of attempts
+   * @param baseDelayMs - Initial backoff delay (doubles each retry)
+   * @param label - Human-readable label for log messages
+   * @returns The operation's resolved value
+   */
+  static async _withRetry(fn, attempts, baseDelayMs, label) {
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastErr = err;
+        if (i === attempts - 1) {
+          break;
+        }
+        const delay = baseDelayMs * Math.pow(2, i);
+        console.warn(
+          `[FsAgent] ${label} attempt ${i + 1}/${attempts} failed: ${FsAgent._errMessage(err)} — retry in ${delay}ms`
+        );
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+    throw lastErr;
+  }
+  /**
+   * Atomically writes a file: stages the content in a sibling `.<rand>.tmp`,
+   * then renames over the target. The rename is atomic, so a crash mid-write
+   * leaves only the temp behind — never a half-written target file. (We do not
+   * `fsync` the temp: it adds significant per-file latency under bursty
+   * restores, and durability-on-power-loss is secondary here since the content
+   * is replicated and re-synced.) The random suffix keeps concurrent restores
+   * of the same path from trampling each other.
+   * @param filePath - Destination path
+   * @param content - Bytes to write
+   */
+  static async _atomicWriteFile(filePath, content) {
+    if (process.platform !== "win32") {
+      await writeFile(filePath, content);
+      return;
+    }
+    const rnd = `${Date.now().toString(36)}-${Math.floor(
+      Math.random() * 1e9
+    ).toString(36)}`;
+    const tmp = join(dirname(filePath), `${ATOMIC_TMP_PREFIX}${rnd}`);
+    try {
+      await writeFile(tmp, content);
+      await rename(tmp, filePath);
+    } catch (err) {
+      try {
+        await unlink(tmp);
+      } catch {
+      }
+      throw err;
+    }
+  }
   /**
    * Wraps a promise with a timeout.
    * Rejects with a descriptive error if the promise does not settle
@@ -891,11 +1054,18 @@ ${err.stack}` : String(err);
     if (this._resolveConflicts) {
       connector.setPredecessors(predecessorRefs ?? []);
     }
-    if (connector.syncConfig?.requireAck) {
-      await connector.sendWithAck(ref);
-    } else {
-      connector.send(ref);
-    }
+    await FsAgent._withRetry(
+      async () => {
+        if (connector.syncConfig?.requireAck) {
+          await connector.sendWithAck(ref);
+        } else {
+          connector.send(ref);
+        }
+      },
+      3,
+      100,
+      `sendRef(${ref.slice(0, 12)}…)`
+    );
   }
   /**
    * Starts automatic syncing to database
@@ -958,10 +1128,41 @@ ${err.stack}` : String(err);
       tree,
       target
     );
+    const preRestore = options?.cleanTarget ? await this._collectAllFiles(target) : /* @__PURE__ */ new Set();
     await this._restoreTree(tree.rootHash, tree.trees, target);
     if (options?.cleanTarget) {
-      await this._pruneExtraneous(target, expectedDirs, expectedFiles);
+      await this._pruneExtraneous(
+        target,
+        expectedDirs,
+        expectedFiles,
+        preRestore
+      );
+    }
+  }
+  /**
+   * Recursively collects the absolute paths of all files under `currentDir`.
+   * Used to snapshot the pre-restore file set for prune race-protection.
+   * @param currentDir - Directory to walk
+   * @param out - Accumulator set (created if omitted)
+   * @returns The set of absolute file paths
+   */
+  async _collectAllFiles(currentDir, out) {
+    const result = out ?? /* @__PURE__ */ new Set();
+    let entries;
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return result;
+    }
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await this._collectAllFiles(fullPath, result);
+      } else {
+        result.add(fullPath);
+      }
     }
+    return result;
   }
   /**
    * Recursively restores a tree node and its children
@@ -995,7 +1196,7 @@ ${err.stack}` : String(err);
           );
         }
         await mkdir(dirname(filePath), { recursive: true });
-        await writeFile(filePath, fileBlob.content);
+        await FsAgent._atomicWriteFile(filePath, fileBlob.content);
         if (meta.mtime) {
           const mtime = new Date(meta.mtime);
           await utimes(filePath, mtime, mtime);
@@ -1189,25 +1390,38 @@ ${err.stack}` : String(err);
     return { expectedDirs, expectedFiles };
   }
   /**
-   * Remove files/dirs not present in the expected sets
+   * Remove files/dirs not present in the expected sets, preserving any file
+   * that appeared *during* the restore (not in `preRestore`) — a fresh user
+   * write that must not be clobbered.
    * @param currentDir - Directory currently being inspected
    * @param expectedDirs - Allowed directory paths
    * @param expectedFiles - Allowed file paths
+   * @param preRestore - Files present before the restore (prune candidates)
    */
-  async _pruneExtraneous(currentDir, expectedDirs, expectedFiles) {
-    const entries = await readdir(currentDir, { withFileTypes: true });
+  async _pruneExtraneous(currentDir, expectedDirs, expectedFiles, preRestore) {
+    let entries;
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
     for (const entry of entries) {
       const fullPath = join(currentDir, entry.name);
       if (entry.isDirectory()) {
+        await this._pruneExtraneous(
+          fullPath,
+          expectedDirs,
+          expectedFiles,
+          preRestore
+        );
         if (!expectedDirs.has(fullPath)) {
-          await rm(fullPath, { recursive: true, force: true });
-          continue;
-        }
-        await this._pruneExtraneous(fullPath, expectedDirs, expectedFiles);
-      } else {
-        if (!expectedFiles.has(fullPath)) {
-          await rm(fullPath, { force: true });
+          const remaining = await readdir(fullPath);
+          if (remaining.length === 0) {
+            await rm(fullPath, { recursive: true, force: true });
+          }
         }
+      } else if (!expectedFiles.has(fullPath) && preRestore.has(fullPath)) {
+        await rm(fullPath, { force: true });
       }
     }
   }
@@ -1266,10 +1480,15 @@ ${err.stack}` : String(err);
               treeKey,
               parentRef ? [parentRef] : void 0
             );
-            const ref = await FsAgent._withTimeout(
-              dbAdapter.storeFsTree(tree, { ...options, previous }),
-              this._timeouts.fetchTree,
-              `syncToDb → storeFsTree(${treeKey})`
+            const ref = await FsAgent._withRetry(
+              () => FsAgent._withTimeout(
+                dbAdapter.storeFsTree(tree, { ...options, previous }),
+                this._timeouts.fetchTree,
+                `syncToDb → storeFsTree(${treeKey})`
+              ),
+              3,
+              200,
+              `syncToDb storeFsTree(${treeKey})`
             );
             this._currentRef = ref;
             if (ref === this._lastSentRef) {
@@ -1481,7 +1700,7 @@ ${err.stack}` : String(err);
       writeFileAt: async (relativePath, content) => {
         const filePath = join(this._rootPath, relativePath);
         await mkdir(dirname(filePath), { recursive: true });
-        await writeFile(filePath, content);
+        await FsAgent._atomicWriteFile(filePath, content);
       },
       deleteFileAt: async (relativePath) => {
         await rm(join(this._rootPath, relativePath), {

package/dist/fs-scanner.d.ts

@@ -39,7 +39,7 @@ export interface FsTree {
 /**
  * Type of file system change
  */
-export type FsChangeType = 'added' | 'modified' | 'deleted';
+export type FsChangeType = 'added' | 'modified' | 'deleted' | 'safety-rescan';
 /**
  * File system change event
  */
@@ -80,6 +80,10 @@ export declare class FsScanner {
     private _bs;
     private _paused;
     private _missedChangesDuringPause;
+    /** Periodic full-rescan timer that catches events the native watcher drops. */
+    private _safetyTimer;
+    /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
+    private _stopRequested;
     constructor(rootPath: string, options?: FsScanOptions);
     get tree(): FsTree | null;
     get rootPath(): string;
@@ -88,6 +92,29 @@ export declare class FsScanner {
     private _scanDirectory;
     private _shouldIgnore;
     watch(): Promise<void>;
+    /**
+     * One safety-rescan pass: rescans the tree and, if its content differs from
+     * the previous scan (the native watcher dropped an event), emits a sync
+     * notification so syncToDb reconciles the drift. Paused/stopped scanners and
+     * scan failures are no-ops.
+     */
+    private _runSafetyRescan;
+    /**
+     * Path+blobId content fingerprint used by the safety rescan to detect drift
+     * the native watcher missed (mtime-independent, same idea as the agent's
+     * content key but local to the scanner).
+     * @param tree - The tree to fingerprint
+     * @returns A stable content key
+     */
+    private _safetyContentKey;
+    /**
+     * Extracts a readable message from a thrown value.
+     * @param err - The caught value
+     * @returns A message string
+     */
+    private static _errMessage;
+    /** Whether the host is Windows — gates Windows-specific watcher hardening. */
+    private static get _isWindows();
     private _handleFileChange;
     private _findTreeByPath;
     private _notifyChange;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",