@relayfile/local-mount 0.6.14 → 0.7.0

package/README.md

@@ -14,9 +14,11 @@ npm install @relayfile/local-mount
 
 ### `createMount(projectDir, mountDir, options)`
 
-Builds a mounted copy of `projectDir` at `mountDir` and returns a handle:
+Builds a mounted copy of `projectDir` at `mountDir` and resolves with a handle:
 
 ```ts
+const handle = await createMount(projectDir, mountDir, options);
+
 interface MountHandle {
   mountDir: string;
   syncBack(opts?: { signal?: AbortSignal }): Promise<number>;
@@ -25,11 +27,13 @@ interface MountHandle {
 }
 ```
 
+`createMount` returns `Promise<MountHandle>`. The walker yields the event loop between directory entries so consumer-side timers (e.g. an `ora` spinner driven by `setInterval`) keep firing while the mount is being built.
+
 Behavior:
 - Copies regular files into the mount
 - Applies ignore rules from `ignoredPatterns`
 - Marks read-only matches as mode `0o444`
-- Excludes `.git`, `node_modules`, and `.npm-cache` by default. Pass `includeGit: true` to opt the project's `.git` directory back in (see [Including `.git`](#including-git))
+- Excludes `.git`, `node_modules`, `.npm-cache`, and common build/cache output directories by default. Pass `includeGit: true` to opt the project's `.git` directory back in (see [Including `.git`](#including-git))
 - Writes `_MOUNT_README.md` and `.relayfile-local-mount` into the mount
 - Skips syncing `_MOUNT_README.md`, `.relayfile-local-mount`, ignored files, read-only files, and symlinks back to the source project
 
@@ -110,6 +114,47 @@ Conflict and delete rules:
 - readonly paths never flow mount→project; project-side edits still flow into the mount (the mount copy is re-chmodded `0o444`)
 - `_MOUNT_README.md`, `.relayfile-local-mount`, ignored paths, and excluded directories never cross
 
+## Default Excludes
+
+By default, mounts skip directories and files that are usually large generated output
+or local caches. These names match at any path depth:
+
+```txt
+.git
+node_modules
+.npm-cache
+__pycache__
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.gradle
+.nyc_output
+.turbo
+.cache
+.DS_Store
+```
+
+These more generic names match only at the project root so source paths such as
+`src/build/` or `packages/env/` are still mounted:
+
+```txt
+target
+.next
+dist
+build
+out
+.venv
+venv
+env
+coverage
+```
+
+Pass `includeDefaultExcludeDirs: false` to opt out of the broad build/cache list.
+For safety, `.git` stays excluded unless you also pass `includeGit: true`.
+`excludeDirs` still appends to whichever default set is active; bare caller entries
+retain the historical any-depth behavior, while path-style entries are root-relative
+prefixes.
+
 ## Including `.git`
 
 By default, the project's `.git` directory is excluded from the mount, which means git commands inside the mount fail with `fatal: not a git repository`. Pass `includeGit: true` (on `createMount` or `launchOnMount`) to copy `.git` into the mount with **one-way project→mount sync**:
@@ -192,7 +237,7 @@ const result = await launchOnMount({
   mountDir,
   ignoredPatterns,
   readonlyPatterns,
-  excludeDirs: ['dist'],
+  excludeDirs: ['vendor-cache'],
   agentName: 'reviewer',
   onBeforeLaunch: async (dir) => {
     // Add extra instructions or scratch files inside the mount if needed.

package/dist/auto-sync.d.ts

@@ -3,14 +3,17 @@ export interface AutoSyncContext {
     realProjectDir: string;
     isExcluded: (relPosix: string) => boolean;
     /**
-     * The exact set of normalized directory names/prefixes that drive
-     * `isExcluded` (i.e., {@link MountOptions.excludeDirs} merged with the
-     * library defaults). Used purely to hint `@parcel/watcher` which subtrees
-     * to skip subscribing to. The in-handler `isSyncCandidate` filter remains
-     * authoritative; this is just a perf hint that keeps the watcher from
-     * recursing into heavy trees like `node_modules` or `.npm-cache`.
+     * Normalized directory names that drive any-depth `isExcluded` matches.
+     * Used purely to hint `@parcel/watcher` which subtrees to skip subscribing
+     * to. The in-handler `isSyncCandidate` filter remains authoritative.
      */
-    excludedNames: readonly string[];
+    excludedAnyDepthNames: readonly string[];
+    /**
+     * Root-anchored excluded names/prefixes such as `build` or `packages/cache`.
+     * These are matched only from the watch root to avoid hiding legitimate
+     * nested source directories like `src/build`.
+     */
+    excludedRootPrefixes: readonly string[];
     /**
      * Directory-only ignore patterns (ending in `/`) must only match when the
      * path is a directory. Callers that know the path's type pass `isDirectory`;

package/dist/auto-sync.js

@@ -170,23 +170,21 @@ function buildIgnoreGlobs(ctx, watchRoot) {
     // `isExcludedPath`'s semantics, so a watcher-suppressed event never differs
     // from what the in-handler filter would have rejected.
     //
-    //   - Bare directory names (e.g. `node_modules`) match at any depth, so
-    //     emit `**/<name>` plus `**/<name>/**`. picomatch turns both into
-    //     depth-agnostic regexes that catch the dir and its descendants.
-    //   - Path-style entries (e.g. `build/cache`) are root-anchored prefixes
+    //   - Any-depth names (e.g. `node_modules`) emit `**/<name>` plus
+    //     `**/<name>/**`. picomatch turns both into depth-agnostic regexes
+    //     that catch the dir and its descendants.
+    //   - Root prefixes (e.g. `build` or `build/cache`) are root-anchored
     //     in `isExcludedPath` — they only match `<root>/build/cache`, NOT
     //     `<root>/src/build/cache`. Emit absolute patterns rooted at the
     //     watch dir so the watcher hides the same set: a literal absolute
     //     path (which the wrapper routes to ignorePaths) plus an anchored
     //     descendant glob.
     const globs = [];
-    for (const name of ctx.excludedNames) {
-        if (name.includes('/')) {
-            globs.push(`${watchRoot}/${name}`, `${watchRoot}/${name}/**`);
-        }
-        else {
-            globs.push(`**/${name}`, `**/${name}/**`);
-        }
+    for (const name of ctx.excludedAnyDepthNames) {
+        globs.push(`**/${name}`, `**/${name}/**`);
+    }
+    for (const prefix of ctx.excludedRootPrefixes) {
+        globs.push(`${watchRoot}/${prefix}`, `${watchRoot}/${prefix}/**`);
     }
     return globs;
 }

package/dist/launch.d.ts

@@ -14,6 +14,11 @@ export interface LaunchOnMountOptions {
     readonlyPatterns?: string[];
     /** Extra directory names to exclude from the mount on top of defaults. */
     excludeDirs?: string[];
+    /**
+     * Include the built-in cache/build exclusion list. Defaults to true. `.git`
+     * remains excluded unless `includeGit` is true.
+     */
+    includeDefaultExcludeDirs?: boolean;
     /**
      * Include the project's `.git` directory inside the mount with one-way
      * project→mount sync. Defaults to false. See {@link MountOptions.includeGit}

package/dist/launch.js

@@ -7,13 +7,7 @@ import { createMount } from './mount.js';
  * exit code.
  */
 export async function launchOnMount(opts) {
-    const handle = createMount(opts.projectDir, opts.mountDir, {
-        ignoredPatterns: opts.ignoredPatterns ?? [],
-        readonlyPatterns: opts.readonlyPatterns ?? [],
-        excludeDirs: opts.excludeDirs ?? [],
-        agentName: opts.agentName,
-        includeGit: opts.includeGit,
-    });
+    let handle;
     let syncedCount = 0;
     let finalized = false;
     let autoSync;
@@ -28,6 +22,8 @@ export async function launchOnMount(opts) {
                 autoSyncChanges = autoSync.totalChanges();
                 autoSync = undefined;
             }
+            if (!handle)
+                return;
             const finalSynced = await handle.syncBack({ signal: opts.shutdownSignal });
             syncedCount = autoSyncChanges + finalSynced;
             if (opts.onAfterSync) {
@@ -35,10 +31,18 @@ export async function launchOnMount(opts) {
             }
         }
         finally {
-            handle.cleanup();
+            handle?.cleanup();
         }
     };
     try {
+        handle = await createMount(opts.projectDir, opts.mountDir, {
+            ignoredPatterns: opts.ignoredPatterns ?? [],
+            readonlyPatterns: opts.readonlyPatterns ?? [],
+            excludeDirs: opts.excludeDirs ?? [],
+            agentName: opts.agentName,
+            includeGit: opts.includeGit,
+            includeDefaultExcludeDirs: opts.includeDefaultExcludeDirs,
+        });
         if (opts.onBeforeLaunch) {
             await opts.onBeforeLaunch(handle.mountDir);
         }
@@ -50,9 +54,10 @@ export async function launchOnMount(opts) {
             ...process.env,
             ...(opts.env ?? {}),
         };
+        const mountCwd = handle.mountDir;
         const exitCode = await new Promise((resolve, reject) => {
             const child = spawn(opts.cli, opts.args, {
-                cwd: handle.mountDir,
+                cwd: mountCwd,
                 stdio: 'inherit',
                 env: envVars,
             });

package/dist/mount.d.ts

@@ -21,6 +21,12 @@ export interface MountOptions {
      *   are discarded with the mount on cleanup. Push to a remote to keep them.
      */
     includeGit?: boolean;
+    /**
+     * Include the built-in list of large cache/build output directories in
+     * the mount exclusion set. Default: true. The `.git` directory remains
+     * excluded unless `includeGit` is true, even when this is false.
+     */
+    includeDefaultExcludeDirs?: boolean;
 }
 export interface MountHandle {
     mountDir: string;
@@ -35,4 +41,4 @@ export interface MountHandle {
     startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
     cleanup(): void;
 }
-export declare function createMount(projectDir: string, mountDir: string, options: MountOptions): MountHandle;
+export declare function createMount(projectDir: string, mountDir: string, options: MountOptions): Promise<MountHandle>;

package/dist/mount.js

@@ -2,11 +2,35 @@ import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync,
 import ignore from 'ignore';
 import path from 'node:path';
 import { startAutoSync, } from './auto-sync.js';
-const DEFAULT_EXCLUDED_DIRS = ['.git', 'node_modules', '.npm-cache'];
+const DEFAULT_ANY_DEPTH_EXCLUDES = [
+    '.git',
+    'node_modules',
+    '.npm-cache',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.ruff_cache',
+    '.gradle',
+    '.nyc_output',
+    '.turbo',
+    '.cache',
+    '.DS_Store',
+];
+const DEFAULT_ROOT_EXCLUDES = [
+    'target',
+    '.next',
+    'dist',
+    'build',
+    'out',
+    '.venv',
+    'venv',
+    'env',
+    'coverage',
+];
 const MOUNT_README_FILENAME = '_MOUNT_README.md';
 const MOUNT_MARKER_FILENAME = '.relayfile-local-mount';
 const MOUNT_MARKER_CONTENT = 'This directory is managed by @relayfile/local-mount. Do not place unrelated files here; the directory will be deleted when the mount is torn down.\n';
-export function createMount(projectDir, mountDir, options) {
+export async function createMount(projectDir, mountDir, options) {
     const resolvedProjectDir = realpathSync(projectDir);
     const resolvedMountDir = path.resolve(mountDir);
     const readonlyPatterns = [...options.readonlyPatterns];
@@ -14,16 +38,12 @@ export function createMount(projectDir, mountDir, options) {
     const includeGit = options.includeGit === true;
     const readonlyMatcher = createPathMatcher(readonlyPatterns);
     const ignoredMatcher = createPathMatcher(ignoredPatterns);
-    // `.git` is in DEFAULT_EXCLUDED_DIRS so the mount stays small and git
+    const includeDefaultExcludeDirs = options.includeDefaultExcludeDirs !== false;
+    // `.git` is in the default any-depth excludes so the mount stays small and git
     // operations don't accidentally cross-mutate the host repo. When the caller
     // opts in via `includeGit`, drop it from the defaults and instead route it
     // through the noSyncBack matcher below so it stays one-way.
-    const defaultExcludes = includeGit
-        ? DEFAULT_EXCLUDED_DIRS.filter((d) => d !== '.git')
-        : DEFAULT_EXCLUDED_DIRS;
-    const excludeSet = new Set([...defaultExcludes, ...options.excludeDirs]
-        .map((entry) => normalizeRelativePosix(entry).replace(/^\/+|\/+$/g, ''))
-        .filter(Boolean));
+    const excludeRules = createExcludeRules(options.excludeDirs, includeGit, includeDefaultExcludeDirs);
     const noSyncBackPatterns = includeGit ? ['.git', '.git/**'] : [];
     const noSyncBackMatcher = createPathMatcher(noSyncBackPatterns);
     // Guard against mountDir === projectDir. We compare both the realpath'd
@@ -40,7 +60,7 @@ export function createMount(projectDir, mountDir, options) {
     mkdirSync(resolvedMountDir, { recursive: true });
     const realMountDir = realpathSync(resolvedMountDir);
     writeFileSync(path.join(realMountDir, MOUNT_MARKER_FILENAME), MOUNT_MARKER_CONTENT, 'utf8');
-    walkProjectTree(resolvedProjectDir, resolvedProjectDir, realMountDir, excludeSet, readonlyMatcher, ignoredMatcher);
+    await walkProjectTree(resolvedProjectDir, resolvedProjectDir, realMountDir, realMountDir, excludeRules, readonlyMatcher, ignoredMatcher);
     const readmePath = resolveSafeCopyTarget(realMountDir, path.join(realMountDir, MOUNT_README_FILENAME));
     if (!readmePath) {
         throw new Error('Failed to create mount readme inside mountDir');
@@ -49,8 +69,9 @@ export function createMount(projectDir, mountDir, options) {
     const autoSyncContext = {
         realMountDir,
         realProjectDir: resolvedProjectDir,
-        isExcluded: (relPosix) => isExcludedPath(relPosix, excludeSet),
-        excludedNames: [...excludeSet],
+        isExcluded: (relPosix) => isExcludedPath(relPosix, excludeRules),
+        excludedAnyDepthNames: [...excludeRules.anyDepthNames],
+        excludedRootPrefixes: [...excludeRules.rootPrefixes],
         isIgnored: (relPosix, isDir) => isPathMatched(relPosix, ignoredMatcher, isDir),
         isReadonly: (relPosix) => isPathMatched(relPosix, readonlyMatcher),
         isNoSyncBack: (relPosix) => isPathMatched(relPosix, noSyncBackMatcher),
@@ -68,7 +89,7 @@ export function createMount(projectDir, mountDir, options) {
                 if (signal?.aborted) {
                     break;
                 }
-                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher);
+                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, (relPosix) => isExcludedPath(relPosix, excludeRules));
                 synced += syncedForFile;
                 if (signal && syncedForFile > 0 && !signal.aborted) {
                     await new Promise((resolve) => setImmediate(resolve));
@@ -122,9 +143,19 @@ function assertMountDirSafeToRemove(mountDir, projectDir) {
             `Only directories previously created by createMount can be reused as mountDir.`);
     }
 }
-function walkProjectTree(projectDir, currentDir, mountDir, excludeSet, readonlyMatcher, ignoredMatcher) {
+// Yield often enough that a consumer's setInterval (e.g. an `ora` spinner) can
+// tick during init even on flat directories with thousands of entries. The
+// goal is not throughput; it is keeping the parent event loop unblocked.
+const WALK_YIELD_EVERY = 64;
+async function walkProjectTree(projectDir, currentDir, mountDir, currentMountDir, excludeRules, readonlyMatcher, ignoredMatcher) {
+    await yieldToEventLoop();
     const entries = readdirSync(currentDir, { withFileTypes: true });
+    let processed = 0;
     for (const entry of entries) {
+        if (processed > 0 && processed % WALK_YIELD_EVERY === 0) {
+            await yieldToEventLoop();
+        }
+        processed += 1;
         const absolutePath = path.join(currentDir, entry.name);
         const relativePath = normalizeRelativePosix(path.relative(projectDir, absolutePath));
         if (!relativePath || relativePath.startsWith('..')) {
@@ -133,18 +164,19 @@ function walkProjectTree(projectDir, currentDir, mountDir, excludeSet, readonlyM
         if (isPathWithinRoot(absolutePath, mountDir)) {
             continue;
         }
-        if (isExcludedPath(relativePath, excludeSet)) {
+        if (isExcludedPath(relativePath, excludeRules)) {
             continue;
         }
         if (isPathMatched(relativePath, ignoredMatcher, entry.isDirectory())) {
             continue;
         }
-        const mountPath = path.join(mountDir, relativePath);
+        const mountPath = path.join(currentMountDir, entry.name);
         if (entry.isDirectory()) {
-            if (!ensureDirectoryWithinRoot(mountDir, mountPath)) {
+            const safeMountDir = ensureDirectoryWithinRoot(mountDir, mountPath);
+            if (!safeMountDir) {
                 continue;
             }
-            walkProjectTree(projectDir, absolutePath, mountDir, excludeSet, readonlyMatcher, ignoredMatcher);
+            await walkProjectTree(projectDir, absolutePath, mountDir, safeMountDir, excludeRules, readonlyMatcher, ignoredMatcher);
             continue;
         }
         if (entry.isSymbolicLink()) {
@@ -157,6 +189,9 @@ function walkProjectTree(projectDir, currentDir, mountDir, excludeSet, readonlyM
         copyMountedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher);
     }
 }
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
 function copySymlinkedFile(projectDir, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher) {
     let realSource;
     let resolvedStat;
@@ -194,15 +229,15 @@ function ensureDirectory(pathValue) {
 }
 function ensureDirectoryWithinRoot(rootPath, dirPath) {
     if (!isPathWithinRoot(dirPath, rootPath)) {
-        return false;
+        return null;
     }
     try {
         ensureDirectory(dirPath);
         const realDir = realpathSync(dirPath);
-        return isPathWithinRoot(realDir, rootPath);
+        return isPathWithinRoot(realDir, rootPath) ? realDir : null;
     }
     catch {
-        return false;
+        return null;
     }
 }
 function listFiles(baseDir) {
@@ -231,6 +266,38 @@ function normalizeRelativePosix(filePath) {
 function createPathMatcher(patterns) {
     return ignore().add(patterns.map((pattern) => pattern.trim()).filter((pattern) => pattern !== '' && !pattern.startsWith('#')));
 }
+function createExcludeRules(excludeDirs, includeGit, includeDefaultExcludeDirs) {
+    const anyDepthNames = new Set();
+    const rootPrefixes = new Set();
+    if (includeDefaultExcludeDirs) {
+        addExcludeEntries(anyDepthNames, rootPrefixes, DEFAULT_ANY_DEPTH_EXCLUDES, 'any-depth');
+        addExcludeEntries(anyDepthNames, rootPrefixes, DEFAULT_ROOT_EXCLUDES, 'root-prefix');
+    }
+    else if (!includeGit) {
+        addExcludeEntries(anyDepthNames, rootPrefixes, ['.git'], 'any-depth');
+    }
+    if (includeGit) {
+        anyDepthNames.delete('.git');
+    }
+    // Preserve caller-supplied excludeDirs semantics: bare names match at any
+    // depth, while path-style entries are root-anchored prefixes.
+    addExcludeEntries(anyDepthNames, rootPrefixes, excludeDirs, 'legacy');
+    return { anyDepthNames, rootPrefixes };
+}
+function addExcludeEntries(anyDepthNames, rootPrefixes, entries, mode) {
+    for (const entry of entries) {
+        const normalized = normalizeRelativePosix(entry).replace(/^\/+|\/+$/g, '');
+        if (!normalized) {
+            continue;
+        }
+        if (mode === 'root-prefix' || (mode === 'legacy' && normalized.includes('/'))) {
+            rootPrefixes.add(normalized);
+        }
+        else {
+            anyDepthNames.add(normalized);
+        }
+    }
+}
 function isPathMatched(relPath, matcher, isDirectory = false) {
     const normalized = normalizeRelativePosix(relPath);
     return matcher.ignores(normalized) || (isDirectory && matcher.ignores(`${normalized}/`));
@@ -254,8 +321,8 @@ function hasSameContent(left, right) {
         return false;
     }
 }
-function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher) {
-    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher);
+function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, isExcluded) {
+    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, isExcluded);
     if (!relative)
         return 0;
     const safeTargetPath = resolveVerifiedSyncTarget(projectDir, relative);
@@ -267,7 +334,7 @@ function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher,
     copyFileSync(sourceFile, safeTargetPath);
     return 1;
 }
-function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher) {
+function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher, isExcluded) {
     const relative = path.relative(mountDir, sourceFile);
     if (relative === '' || relative.startsWith('..'))
         return null;
@@ -276,7 +343,8 @@ function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredM
         return null;
     if (relativePosix === MOUNT_MARKER_FILENAME)
         return null;
-    if (isPathMatched(relative, readonlyMatcher) ||
+    if (isExcluded(relativePosix) ||
+        isPathMatched(relative, readonlyMatcher) ||
         isPathMatched(relative, ignoredMatcher) ||
         isPathMatched(relative, noSyncBackMatcher))
         return null;
@@ -311,14 +379,14 @@ function resolveVerifiedSyncTarget(projectDir, relativePath) {
         return null;
     }
 }
-function isExcludedPath(relativePath, excludeSet) {
+function isExcludedPath(relativePath, excludeRules) {
     const normalized = normalizeRelativePosix(relativePath).replace(/^\/+|\/+$/g, '');
     if (!normalized)
         return false;
     const segments = normalized.split('/');
     return segments.some((segment, index) => {
         const prefix = segments.slice(0, index + 1).join('/');
-        return excludeSet.has(segment) || excludeSet.has(prefix);
+        return excludeRules.anyDepthNames.has(segment) || excludeRules.rootPrefixes.has(prefix);
     });
 }
 function isPathWithinRoot(candidatePath, rootPath) {
@@ -331,19 +399,11 @@ function resolveSafeCopyTarget(rootPath, candidatePath) {
         return null;
     }
     const parentPath = path.dirname(candidatePath);
-    if (!ensureDirectoryWithinRoot(rootPath, parentPath)) {
-        return null;
-    }
-    try {
-        const realParent = realpathSync(parentPath);
-        if (!isPathWithinRoot(realParent, rootPath)) {
-            return null;
-        }
-        return path.join(realParent, path.basename(candidatePath));
-    }
-    catch {
+    const realParent = ensureDirectoryWithinRoot(rootPath, parentPath);
+    if (!realParent) {
         return null;
     }
+    return path.join(realParent, path.basename(candidatePath));
 }
 function resolveVerifiedFilePath(rootPath, candidatePath) {
     try {

package/package.json

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