@relayfile/local-mount 0.7.17 → 0.7.19

package/README.md

@@ -74,8 +74,10 @@ By default, `launchOnMount` keeps the mount and project directory in sync contin
 
 ```ts
 interface AutoSyncOptions {
-  /** Full-reconcile interval as a safety net. Default: 10_000 ms. */
+  /** Degraded-watcher full-reconcile interval. Default: 10_000 ms. 0/Infinity disables periodic scans. */
   scanIntervalMs?: number;
+  /** Healthy-watcher full-reconcile interval. Default: 60_000 ms, or scanIntervalMs when set. */
+  healthyScanIntervalMs?: number;
   /** Per-path event debounce in ms. Default: 50 ms. */
   debounceMs?: number;
   /** Invoked on sync errors. Defaults to swallowing them. */
@@ -100,12 +102,16 @@ Control it from `launchOnMount`:
 launchOnMount({ /* ... */, autoSync: false });
 
 // Tune it.
-launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 5_000, debounceMs: 100 } });
+launchOnMount({ /* ... */, autoSync: { healthyScanIntervalMs: 120_000, debounceMs: 100 } });
+
+// Disable periodic full reconciles and rely on watcher events.
+launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 0 } });
 ```
 
 How it works:
 - [@parcel/watcher](https://www.npmjs.com/package/@parcel/watcher) watches both the mount and the project tree using native FSEvents/inotify/ReadDirectoryChangesW
-- every `scanIntervalMs`, a full reconcile walks both trees as a safety net for missed events
+- every `healthyScanIntervalMs` while watchers are healthy, a full reconcile walks both trees as a low-frequency safety net for missed events
+- if watcher setup fails or a watcher reports an error, full reconciles fall back to `scanIntervalMs`
 - watcher events are tracked as dirty paths, so shutdown can flush pending path-level work and make the final sync-back proportional to the number of mount-side changes when the watcher state stayed healthy
 - `stop({ signal })` still closes watchers if aborted, but skips the final draining reconcile
 - per-file `mtime` is tracked at the last sync, so the scan skips files that haven't changed

package/dist/auto-sync.d.ts

@@ -32,8 +32,17 @@ export interface AutoSyncContext {
     isReservedFile: (relPosix: string) => boolean;
 }
 export interface AutoSyncOptions {
-    /** Full-reconcile interval as a safety net. Default: 10_000ms. */
+    /**
+     * Degraded-watcher full-reconcile interval as a safety net. Default: 10_000ms.
+     * Set to 0 or Infinity to disable periodic full reconciles.
+     */
     scanIntervalMs?: number;
+    /**
+     * Full-reconcile interval while both watcher subscriptions are healthy.
+     * Default: 60_000ms, or `scanIntervalMs` when that option is explicitly set.
+     * Set to 0 or Infinity to disable healthy-watcher full reconciles.
+     */
+    healthyScanIntervalMs?: number;
     /**
      * Per-path event debounce in ms. Rapid watcher events for the same path
      * are coalesced into a single sync. Default: 50.

package/dist/auto-sync.js

@@ -2,8 +2,21 @@ import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync,
 import path from 'node:path';
 import watcher from '@parcel/watcher';
 const STOP_EVENT_SETTLE_MS = 250;
+const DEFAULT_SCAN_INTERVAL_MS = 10_000;
+const DEFAULT_HEALTHY_SCAN_INTERVAL_MS = 60_000;
+const MAX_SCAN_INTERVAL_MS = 2_147_483_647;
+function normalizeScanInterval(name, value, fallback) {
+    const interval = value ?? fallback;
+    if (interval === 0 || interval === Infinity)
+        return null;
+    if (!Number.isFinite(interval) || interval < 0 || interval > MAX_SCAN_INTERVAL_MS) {
+        throw new RangeError(`${name} must be between 0 and ${MAX_SCAN_INTERVAL_MS}, or Infinity`);
+    }
+    return interval;
+}
 export function startAutoSync(ctx, opts = {}) {
-    const scanIntervalMs = opts.scanIntervalMs ?? 10_000;
+    const scanIntervalMs = normalizeScanInterval('scanIntervalMs', opts.scanIntervalMs, DEFAULT_SCAN_INTERVAL_MS);
+    const healthyScanIntervalMs = normalizeScanInterval('healthyScanIntervalMs', opts.healthyScanIntervalMs, opts.scanIntervalMs === undefined ? DEFAULT_HEALTHY_SCAN_INTERVAL_MS : opts.scanIntervalMs);
     const debounceMs = opts.debounceMs ?? 50;
     const onError = opts.onError ?? (() => { });
     const state = new Map();
@@ -19,10 +32,6 @@ export function startAutoSync(ctx, opts = {}) {
     const pendingDebounces = new Map();
     const dirtyMountPaths = new Set();
     const watchersHealthy = () => watchersReadySettled && !watcherDegraded;
-    const markWatcherDegraded = (err) => {
-        watcherDegraded = true;
-        onError(err);
-    };
     const clearPendingDebounces = () => {
         for (const t of pendingDebounces.values())
             clearTimeout(t);
@@ -104,6 +113,47 @@ export function startAutoSync(ctx, opts = {}) {
         totalChanges += count;
         return count;
     };
+    let periodicTimer;
+    let periodicReconcileRunning = false;
+    const clearPeriodicReconcile = () => {
+        if (periodicTimer) {
+            clearTimeout(periodicTimer);
+            periodicTimer = undefined;
+        }
+    };
+    const nextScanInterval = () => {
+        return watchersHealthy() ? healthyScanIntervalMs : scanIntervalMs;
+    };
+    const schedulePeriodicReconcile = () => {
+        clearPeriodicReconcile();
+        if (stopping || stopped)
+            return;
+        const delay = nextScanInterval();
+        if (delay === null)
+            return;
+        periodicTimer = setTimeout(() => {
+            periodicTimer = undefined;
+            periodicReconcileRunning = true;
+            void runReconcile().finally(() => {
+                periodicReconcileRunning = false;
+                schedulePeriodicReconcile();
+            });
+        }, delay);
+        periodicTimer.unref?.();
+    };
+    const reschedulePeriodicReconcile = () => {
+        if (periodicReconcileRunning)
+            return;
+        schedulePeriodicReconcile();
+    };
+    const markWatcherDegraded = (err) => {
+        const alreadyDegraded = watcherDegraded;
+        watcherDegraded = true;
+        if (!alreadyDegraded) {
+            reschedulePeriodicReconcile();
+        }
+        onError(err);
+    };
     const flushPending = async (opts) => {
         if (opts?.signal?.aborted) {
             return 0;
@@ -178,10 +228,12 @@ export function startAutoSync(ctx, opts = {}) {
             projectSub = projectResult.value;
         if (mountResult.status === 'fulfilled' && projectResult.status === 'fulfilled') {
             watchersReadySettled = true;
+            reschedulePeriodicReconcile();
             return;
         }
         watchersReadySettled = true;
         watcherDegraded = true;
+        reschedulePeriodicReconcile();
         await Promise.allSettled([
             mountSub?.unsubscribe(),
             projectSub?.unsubscribe(),
@@ -196,11 +248,7 @@ export function startAutoSync(ctx, opts = {}) {
     // rejection. stop() still awaits the same promise and will observe the
     // rejection after the cleanup above has already run.
     watchersReady.catch((err) => markWatcherDegraded(err));
-    const interval = setInterval(() => {
-        void runReconcile();
-    }, scanIntervalMs);
-    // Do not keep the event loop alive just because of our scan timer.
-    interval.unref?.();
+    schedulePeriodicReconcile();
     return {
         async stop(opts) {
             try {
@@ -214,7 +262,7 @@ export function startAutoSync(ctx, opts = {}) {
                 await new Promise((resolve) => setTimeout(resolve, STOP_EVENT_SETTLE_MS));
             }
             stopping = true;
-            clearInterval(interval);
+            clearPeriodicReconcile();
             clearPendingDebounces();
             await Promise.allSettled([
                 mountSub?.unsubscribe(),

package/dist/mount.d.ts

@@ -36,8 +36,9 @@ export interface MountHandle {
     }): Promise<number>;
     /**
      * Start bidirectional auto-sync: watches both the mount and project trees
-     * via @parcel/watcher and runs a full reconcile every `scanIntervalMs`
-     * as a safety net. Returns a handle you must `stop()` before teardown.
+     * via @parcel/watcher and runs periodic full reconciles as a safety net,
+     * with a slower cadence while watchers are healthy. Returns a handle you
+     * must `stop()` before teardown.
      */
     startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
     cleanup(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/local-mount",
-  "version": "0.7.17",
+  "version": "0.7.19",
   "description": "Create a symlink/copy mount of a project directory with .agentignore/.agentreadonly semantics, then launch a CLI inside it and sync writable changes back on exit",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",