@relayfile/local-mount 0.4.0 → 0.5.1

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()`.
@@ -77,8 +79,8 @@ interface AutoSyncOptions {
 }
 
 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>;
 }
@@ -97,6 +99,7 @@ launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 5_000, debounceMs: 100 }
 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
+- `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

@@ -24,9 +24,13 @@ export interface AutoSyncOptions {
     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

@@ -12,7 +12,11 @@ export function startAutoSync(ctx, opts = {}) {
     let stopped = false;
     let totalChanges = 0;
     const pendingDebounces = new Map();
-    const runReconcile = async () => {
+    const runReconcile = async (opts) => {
+        const signal = opts?.signal;
+        if (signal?.aborted) {
+            return 0;
+        }
         if (syncing) {
             pending = true;
             return 0;
@@ -20,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);
@@ -28,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);
@@ -124,7 +128,7 @@ export function startAutoSync(ctx, opts = {}) {
     // 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;
@@ -146,8 +150,11 @@ export function startAutoSync(ctx, opts = {}) {
             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,
@@ -198,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) => {
@@ -217,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())) {
@@ -488,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;
@@ -502,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('..'))

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,7 +11,9 @@ 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
      * via @parcel/watcher and runs a full reconcile every `scanIntervalMs`

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.4.0",
+  "version": "0.5.1",
   "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",