@relayfile/local-mount 0.3.2 → 0.5.0

package/README.md

@@ -19,7 +19,7 @@ Builds a mounted copy of `projectDir` at `mountDir` and returns a handle:
 ```ts
 interface SymlinkMountHandle {
   mountDir: string;
-  syncBack(): Promise<number>;
+  syncBack(opts?: { signal?: AbortSignal }): Promise<number>;
   startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
   cleanup(): void;
 }
@@ -62,6 +62,8 @@ High-level helper that:
 
 It resolves with the child process exit code. `onAfterSync(count)` receives the sum of files changed by auto-sync plus the final sync-back pass.
 
+`launchOnMount({ shutdownSignal })` threads an optional `AbortSignal` into the shutdown phase only. It does not cancel the spawned CLI. If shutdown is aborted, `onAfterSync` still fires with the partial count gathered so far and the mount directory is still cleaned up.
+
 ### Auto-sync
 
 By default, `launchOnMount` keeps the mount and project directory in sync continuously while the CLI is running, rather than only at exit. The same machinery is available standalone via `handle.startAutoSync()`.
@@ -70,15 +72,15 @@ 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;
 }
 
 interface AutoSyncHandle {
-  stop(): Promise<void>;
-  reconcile(): Promise<number>;
+  stop(opts?: { signal?: AbortSignal }): Promise<void>;
+  reconcile(opts?: { signal?: AbortSignal }): Promise<number>;
   totalChanges(): number;
   ready(): Promise<void>;
 }
@@ -91,12 +93,13 @@ 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
+- `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
 
 Conflict and delete rules:
@@ -154,6 +157,7 @@ import os from 'node:os';
 
 const projectDir = '/projects/acme-api';
 const mountDir = path.join(os.tmpdir(), 'acme-api-agent-mount');
+const abortController = new AbortController();
 
 const { ignoredPatterns, readonlyPatterns } = readAgentDotfiles(projectDir, {
   agentName: 'reviewer',
@@ -172,6 +176,7 @@ const result = await launchOnMount({
     // Add extra instructions or scratch files inside the mount if needed.
     console.log(`Mount ready at ${dir}`);
   },
+  shutdownSignal: abortController.signal,
   onAfterSync: async (count) => {
     console.log(`Synced ${count} writable file(s) back to the project`);
   },
@@ -193,6 +198,10 @@ console.log(result.exitCode);
 
 The returned number is the count of files written back to `projectDir` in that pass. `syncBack()` never deletes — delete propagation is handled by auto-sync.
 
+`syncBack({ signal })` checks for aborts between files. If the signal aborts during shutdown, it returns the partial count accumulated so far instead of throwing, which lets callers report a partial sync and still run cleanup.
+
+`reconcile({ signal })` and the internal tree walk also poll for aborts between file visits so an in-flight draining scan can stop cooperatively.
+
 ## Safety constraints
 
 The implementation is intentionally conservative about `mountDir`:

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,15 +15,22 @@ 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;
 }
 export interface AutoSyncHandle {
-    stop(): Promise<void>;
+    stop(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /** Force a reconcile now; returns number of files copied/deleted. */
-    reconcile(): Promise<number>;
+    reconcile(opts?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
     /** Cumulative files changed (copied or deleted) since autosync started. */
     totalChanges(): number;
     /** Resolves once both watchers have completed their initial scan. */

package/dist/auto-sync.js

@@ -1,16 +1,22 @@
 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 runReconcile = async () => {
+    const pendingDebounces = new Map();
+    const runReconcile = async (opts) => {
+        const signal = opts?.signal;
+        if (signal?.aborted) {
+            return 0;
+        }
         if (syncing) {
             pending = true;
             return 0;
@@ -18,7 +24,7 @@ export function startAutoSync(ctx, opts = {}) {
         syncing = true;
         let count = 0;
         try {
-            count = reconcile(state, ctx, onError);
+            count = reconcile(state, ctx, onError, signal);
         }
         catch (err) {
             onError(err);
@@ -26,10 +32,10 @@ export function startAutoSync(ctx, opts = {}) {
         finally {
             syncing = false;
         }
-        if (pending) {
+        if (pending && !signal?.aborted) {
             pending = false;
             try {
-                count += reconcile(state, ctx, onError);
+                count += reconcile(state, ctx, onError, signal);
             }
             catch (err) {
                 onError(err);
@@ -54,43 +60,101 @@ 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);
     // Do not keep the event loop alive just because of our scan timer.
     interval.unref?.();
     return {
-        async stop() {
+        async stop(opts) {
+            // 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();
+            if (opts?.signal?.aborted) {
+                return;
+            }
             // Drain any pending work so callers can rely on "stopped means quiesced".
-            await runReconcile();
+            await runReconcile(opts);
         },
         reconcile: runReconcile,
         totalChanges: () => totalChanges,
@@ -99,6 +163,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
@@ -124,7 +205,7 @@ function primeState(state, ctx) {
         });
     });
 }
-function reconcile(state, ctx, onError) {
+function reconcile(state, ctx, onError, signal) {
     const seen = new Set();
     let count = 0;
     const visit = (relPosix) => {
@@ -143,15 +224,25 @@ function reconcile(state, ctx, onError) {
         }
     };
     walk(ctx.realMountDir, ctx, (abs) => {
+        if (signal?.aborted)
+            return;
         const rel = toRelPosix(abs, ctx);
         if (rel !== null)
             visit(rel);
-    });
+    }, signal);
+    if (signal?.aborted) {
+        return count;
+    }
     walk(ctx.realProjectDir, ctx, (abs) => {
+        if (signal?.aborted)
+            return;
         const rel = toRelPosixFromProject(abs, ctx);
         if (rel !== null)
             visit(rel);
-    });
+    }, signal);
+    if (signal?.aborted) {
+        return count;
+    }
     // Tombstone sweep: any path in state we didn't visit had both sides absent,
     // so it's fully gone.
     for (const rel of Array.from(state.keys())) {
@@ -414,9 +505,11 @@ function resolveSafeWriteTarget(root, candidate) {
         return null;
     }
 }
-function walk(root, ctx, visit) {
+function walk(root, ctx, visit, signal) {
     const stack = [root];
     while (stack.length > 0) {
+        if (signal?.aborted)
+            return;
         const cur = stack.pop();
         if (!cur)
             continue;
@@ -428,6 +521,8 @@ function walk(root, ctx, visit) {
             continue;
         }
         for (const entry of entries) {
+            if (signal?.aborted)
+                return;
             const abs = path.join(cur, entry.name);
             const rel = path.relative(root, abs).split(path.sep).join('/');
             if (!rel || rel.startsWith('..'))
@@ -443,24 +538,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/launch.d.ts

@@ -18,6 +18,14 @@ export interface LaunchOnMountOptions {
     env?: NodeJS.ProcessEnv;
     /** Optional agent name, used in the _MOUNT_README.md "Agent:" line. */
     agentName?: string;
+    /**
+     * Optional signal used during shutdown work after the child exits.
+     * It is passed to both autosync shutdown and the final mount→project sync-back.
+     * If aborted, autosync stop may skip its draining reconcile and sync-back
+     * returns the partial count accumulated so far, so fewer changes may be
+     * propagated than during an uninterrupted shutdown.
+     */
+    shutdownSignal?: AbortSignal;
     /**
      * Invoked after the mount is created but before the CLI is spawned.
      * Useful for writing additional files into the mount (overrides, extra docs).

package/dist/launch.js

@@ -23,11 +23,11 @@ export async function launchOnMount(opts) {
         try {
             let autoSyncChanges = 0;
             if (autoSync) {
-                await autoSync.stop();
+                await autoSync.stop({ signal: opts.shutdownSignal });
                 autoSyncChanges = autoSync.totalChanges();
                 autoSync = undefined;
             }
-            const finalSynced = await handle.syncBack();
+            const finalSynced = await handle.syncBack({ signal: opts.shutdownSignal });
             syncedCount = autoSyncChanges + finalSynced;
             if (opts.onAfterSync) {
                 await opts.onAfterSync(syncedCount);

package/dist/symlink-mount.d.ts

@@ -11,11 +11,13 @@ export interface SymlinkMountOptions {
 }
 export interface SymlinkMountHandle {
     mountDir: string;
-    syncBack(): Promise<number>;
+    syncBack(opts?: {
+        signal?: AbortSignal;
+    }): 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/dist/symlink-mount.js

@@ -46,13 +46,21 @@ export function createSymlinkMount(projectDir, mountDir, options) {
     };
     return {
         mountDir: resolvedMountDir,
-        async syncBack() {
+        async syncBack(opts) {
             let synced = 0;
             const realProjectDir = realpathSync(resolvedProjectDir);
             const realMountDir = realpathSync(resolvedMountDir);
             const files = listFiles(realMountDir);
+            const signal = opts?.signal;
             for (const sourceFile of files) {
-                synced += syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher);
+                if (signal?.aborted) {
+                    break;
+                }
+                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher);
+                synced += syncedForFile;
+                if (signal && syncedForFile > 0 && !signal.aborted) {
+                    await new Promise((resolve) => setImmediate(resolve));
+                }
             }
             return synced;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/local-mount",
-  "version": "0.3.2",
+  "version": "0.5.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": {