@relayfile/local-mount 0.3.1 → 0.4.0

package/README.md

@@ -70,8 +70,8 @@ By default, `launchOnMount` keeps the mount and project directory in sync contin
 interface AutoSyncOptions {
   /** Full-reconcile interval as a safety net. Default: 10_000 ms. */
   scanIntervalMs?: number;
-  /** chokidar `awaitWriteFinish` stability threshold. Default: 200 ms. */
-  writeFinishMs?: number;
+  /** Per-path event debounce in ms. Default: 50 ms. */
+  debounceMs?: number;
   /** Invoked on sync errors. Defaults to swallowing them. */
   onError?: (err: Error) => void;
 }
@@ -91,11 +91,11 @@ Control it from `launchOnMount`:
 launchOnMount({ /* ... */, autoSync: false });
 
 // Tune it.
-launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 5_000, writeFinishMs: 100 } });
+launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 5_000, debounceMs: 100 } });
 ```
 
 How it works:
-- chokidar watches both the mount and the project tree
+- [@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
 - per-file `mtime` is tracked at the last sync, so the scan skips files that haven't changed
 

package/dist/auto-sync.d.ts

@@ -5,7 +5,8 @@ export interface AutoSyncContext {
     /**
      * Directory-only ignore patterns (ending in `/`) must only match when the
      * path is a directory. Callers that know the path's type pass `isDirectory`;
-     * callers that don't (chokidar's prune filter) should check both forms.
+     * callers that don't should omit the second argument and fall back to the
+     * file-form check.
      */
     isIgnored: (relPosix: string, isDirectory?: boolean) => boolean;
     isReadonly: (relPosix: string) => boolean;
@@ -14,8 +15,11 @@ export interface AutoSyncContext {
 export interface AutoSyncOptions {
     /** Full-reconcile interval as a safety net. Default: 10_000ms. */
     scanIntervalMs?: number;
-    /** chokidar awaitWriteFinish stabilityThreshold in ms. Default: 200. */
-    writeFinishMs?: number;
+    /**
+     * Per-path event debounce in ms. Rapid watcher events for the same path
+     * are coalesced into a single sync. Default: 50.
+     */
+    debounceMs?: number;
     /** Invoked on errors during sync — logged by default consumer. */
     onError?: (err: Error) => void;
 }

package/dist/auto-sync.js

@@ -1,15 +1,17 @@
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
 import path from 'node:path';
-import chokidar from 'chokidar';
+import watcher from '@parcel/watcher';
 export function startAutoSync(ctx, opts = {}) {
     const scanIntervalMs = opts.scanIntervalMs ?? 10_000;
-    const writeFinishMs = opts.writeFinishMs ?? 200;
+    const debounceMs = opts.debounceMs ?? 50;
     const onError = opts.onError ?? (() => { });
     const state = new Map();
     primeState(state, ctx);
     let syncing = false;
     let pending = false;
+    let stopped = false;
     let totalChanges = 0;
+    const pendingDebounces = new Map();
     const runReconcile = async () => {
         if (syncing) {
             pending = true;
@@ -54,32 +56,68 @@ export function startAutoSync(ctx, opts = {}) {
             onError(err);
         }
     };
-    const makeWatcher = (root) => {
-        const watcher = chokidar.watch(root, {
-            ignoreInitial: true,
-            persistent: true,
-            followSymlinks: false,
-            awaitWriteFinish: {
-                stabilityThreshold: writeFinishMs,
-                pollInterval: 50,
-            },
-            ignored: (candidate, stats) => shouldChokidarIgnore(candidate, root, ctx, stats),
-        });
-        const onEvent = (p) => syncPathFromRoot(root, p);
-        watcher.on('add', onEvent);
-        watcher.on('change', onEvent);
-        watcher.on('unlink', onEvent);
-        watcher.on('error', (err) => onError(err));
-        const ready = new Promise((resolve) => {
-            watcher.once('ready', () => resolve());
-        });
-        return { watcher, ready };
+    const schedulePathSync = (root, absPath) => {
+        // Once stop() has begun, refuse to schedule new timers. Watcher
+        // callbacks can still fire during the unsubscribe await (native
+        // backends deliver queued events asynchronously); without this guard
+        // those events would create timers that outlive stop() and do file
+        // work against a mount the caller may have already cleaned up.
+        if (stopped)
+            return;
+        // Coalesce bursts of events for the same path. The reconcile path
+        // re-checks content via mtime+bytes, so a partial-write event that
+        // races a later write is harmless.
+        const existing = pendingDebounces.get(absPath);
+        if (existing)
+            clearTimeout(existing);
+        const t = setTimeout(() => {
+            pendingDebounces.delete(absPath);
+            syncPathFromRoot(root, absPath);
+        }, debounceMs);
+        pendingDebounces.set(absPath, t);
     };
-    const mount = makeWatcher(ctx.realMountDir);
-    const project = makeWatcher(ctx.realProjectDir);
-    const mountWatcher = mount.watcher;
-    const projectWatcher = project.watcher;
-    const watchersReady = Promise.all([mount.ready, project.ready]);
+    const ignoreGlobs = buildIgnoreGlobs(ctx);
+    const subscribeTo = (root) => watcher.subscribe(root, (err, events) => {
+        if (err) {
+            onError(err);
+            return;
+        }
+        for (const ev of events) {
+            schedulePathSync(root, ev.path);
+        }
+    }, { ignore: ignoreGlobs });
+    let mountSub;
+    let projectSub;
+    // Subscribe in parallel but track each outcome independently. With
+    // Promise.all, a failure on one side would reject before the other's
+    // assignment ran and leak the succeeded subscription. allSettled lets us
+    // tear down whichever fulfilled before re-throwing the first failure.
+    const watchersReady = (async () => {
+        const [mountResult, projectResult] = await Promise.allSettled([
+            subscribeTo(ctx.realMountDir),
+            subscribeTo(ctx.realProjectDir),
+        ]);
+        if (mountResult.status === 'fulfilled')
+            mountSub = mountResult.value;
+        if (projectResult.status === 'fulfilled')
+            projectSub = projectResult.value;
+        if (mountResult.status === 'fulfilled' && projectResult.status === 'fulfilled') {
+            return;
+        }
+        await Promise.allSettled([
+            mountSub?.unsubscribe(),
+            projectSub?.unsubscribe(),
+        ]);
+        mountSub = undefined;
+        projectSub = undefined;
+        throw mountResult.status === 'rejected'
+            ? mountResult.reason
+            : projectResult.reason;
+    })();
+    // If subscription setup fails, surface via onError rather than an unhandled
+    // rejection. stop() still awaits the same promise and will observe the
+    // rejection after the cleanup above has already run.
+    watchersReady.catch((err) => onError(err));
     const interval = setInterval(() => {
         void runReconcile();
     }, scanIntervalMs);
@@ -87,8 +125,27 @@ export function startAutoSync(ctx, opts = {}) {
     interval.unref?.();
     return {
         async stop() {
+            // Flip the flag first so any watcher callbacks delivered during the
+            // awaits below refuse to schedule new timers.
+            stopped = true;
             clearInterval(interval);
-            await Promise.all([mountWatcher.close(), projectWatcher.close()]);
+            try {
+                await watchersReady;
+            }
+            catch {
+                // Setup failed and already cleaned up any partial subscription;
+                // mountSub / projectSub were reset to undefined before the throw.
+            }
+            await Promise.allSettled([
+                mountSub?.unsubscribe(),
+                projectSub?.unsubscribe(),
+            ]);
+            // Clear debounces *after* unsubscribe resolves: any timer scheduled
+            // between stop() being called and the watcher actually quiescing is
+            // gathered here, so none fire after stop() returns.
+            for (const t of pendingDebounces.values())
+                clearTimeout(t);
+            pendingDebounces.clear();
             // Drain any pending work so callers can rely on "stopped means quiesced".
             await runReconcile();
         },
@@ -99,6 +156,23 @@ export function startAutoSync(ctx, opts = {}) {
         },
     };
 }
+function buildIgnoreGlobs(ctx) {
+    // @parcel/watcher matches globs against absolute paths via globset. For each
+    // excluded directory name, ignore both the directory itself and everything
+    // beneath it, anywhere under the watched root. The `isExcluded` predicate is
+    // driven by a Set of directory names, so we probe a small set of common
+    // exclusions rather than introspecting it. The in-handler `isSyncCandidate`
+    // filter is authoritative — this is just a perf hint so the watcher doesn't
+    // recurse into heavy trees like node_modules or .git.
+    const globs = [];
+    const candidates = ['.git', 'node_modules', 'dist', 'build', '.next', '.cache'];
+    for (const name of candidates) {
+        if (ctx.isExcluded(name)) {
+            globs.push(`**/${name}`, `**/${name}/**`);
+        }
+    }
+    return globs;
+}
 function primeState(state, ctx) {
     // Record current mtimes for every file that exists in both trees with the
     // same content. Files that differ are left out so the first reconcile sees
@@ -443,24 +517,3 @@ function walk(root, ctx, visit) {
         }
     }
 }
-function shouldChokidarIgnore(candidate, root, ctx, stats) {
-    if (candidate === root)
-        return false;
-    const rel = path.relative(root, candidate);
-    if (rel === '' || rel.startsWith('..'))
-        return false;
-    const relPosix = rel.split(path.sep).join('/');
-    if (ctx.isExcluded(relPosix))
-        return true;
-    if (ctx.isReservedFile(relPosix))
-        return true;
-    // chokidar calls this filter twice: first without stats (pre-stat prune),
-    // then again with stats once it knows the entry type. Only apply the
-    // directory-form match when we have stats confirming it's a directory,
-    // otherwise a directory-only pattern like `cache/` would wrongly prune a
-    // same-named file.
-    if (stats) {
-        return ctx.isIgnored(relPosix, stats.isDirectory());
-    }
-    return ctx.isIgnored(relPosix);
-}

package/dist/symlink-mount.d.ts

@@ -14,8 +14,8 @@ export interface SymlinkMountHandle {
     syncBack(): Promise<number>;
     /**
      * Start bidirectional auto-sync: watches both the mount and project trees
-     * with chokidar and runs a full reconcile every `scanIntervalMs` as a
-     * safety net. Returns a handle you must `stop()` before teardown.
+     * via @parcel/watcher and runs a full reconcile every `scanIntervalMs`
+     * as a safety net. 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.3.1",
+  "version": "0.4.0",
   "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",
@@ -15,7 +15,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "chokidar": "^4.0.3",
+    "@parcel/watcher": "^2.5.6",
     "ignore": "^7.0.5"
   },
   "devDependencies": {