@relayfile/local-mount 0.5.3 → 0.6.0

package/README.md

@@ -12,12 +12,12 @@ npm install @relayfile/local-mount
 
 ## What it exports
 
-### `createSymlinkMount(projectDir, mountDir, options)`
+### `createMount(projectDir, mountDir, options)`
 
 Builds a mounted copy of `projectDir` at `mountDir` and returns a handle:
 
 ```ts
-interface SymlinkMountHandle {
+interface MountHandle {
   mountDir: string;
   syncBack(opts?: { signal?: AbortSignal }): Promise<number>;
   startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
@@ -29,7 +29,7 @@ Behavior:
 - Copies regular files into the mount
 - Applies ignore rules from `ignoredPatterns`
 - Marks read-only matches as mode `0o444`
-- Excludes `.git` and `node_modules` by default
+- Excludes `.git` and `node_modules` 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 +110,28 @@ 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
 
+## 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**:
+
+- `.git` is copied on mount creation, so `git status`, `git log`, `git diff`, `git commit`, etc. all work inside the mount.
+- Project-side changes under `.git/**` flow into the mount (e.g. if a teammate's tooling moves `HEAD` while the agent is running).
+- Mount-side changes under `.git/**` are **not** synced back to the project. Branches, commits, or refs the agent creates in the mount stay sandboxed and are discarded on cleanup.
+
+If the agent needs its commits to survive, push to a remote from inside the mount. Source files outside `.git` continue to follow the normal bidirectional sync rules.
+
+```ts
+launchOnMount({
+  cli: 'claude',
+  args: ['--print', 'Inspect the diff and propose a fix.'],
+  projectDir,
+  mountDir,
+  includeGit: true,
+});
+```
+
+Note that `.git` can be sizable (hundreds of MB on long-lived repos); the initial mount creation copies the whole tree.
+
 ## Dotfile semantics
 
 `@relayfile/local-mount` uses glob-style patterns, powered by [`ignore`](https://www.npmjs.com/package/ignore).
@@ -213,6 +235,18 @@ The implementation is intentionally conservative about `mountDir`:
 
 These checks help prevent accidental deletion of unrelated directories during mount recreation and cleanup.
 
+## Why copy instead of symlink?
+
+The mount is built by copying files rather than symlinking them. Symlinks would break several of the package's guarantees:
+
+1. **`.agentreadonly` can't be enforced.** Read-only is implemented by `chmod 0o444` on the mount copy. `chmod` follows symlinks, so applying it to a symlink would mark the *source* file read-only, flipping the project's permissions instead of restricting the agent's view.
+2. **The auto-sync conflict model assumes two distinct files.** Rules like "both sides changed → mount wins", "one side deleted → propagate", and "readonly paths never flow mount→project but project-side edits still flow into the mount" only make sense if mount and source are separate bytes. Through a symlink they're the same inode — there's no mount-side copy to re-chmod `0o444` after a project-side edit.
+3. **Editor save-via-rename breaks symlinks anyway.** Most editors save by writing a temp file and renaming it over the target, which replaces the symlink with a regular file and severs the link. A "live view" via symlinks isn't reliable in practice.
+4. **Containment.** A copy gives you a checkpoint: if the agent destroys files or writes garbage, the source is untouched until `syncBack()` filters and copies back. With symlinks, every keystroke is live on the project.
+5. **`.agentignore` hiding works fine with symlinks** (just don't link), but the readonly and conflict semantics still need copies — so a hybrid would be more complex than just copying everything.
+
+Source-side symlinks that resolve to regular files inside the project *are* followed when building the mount; the resolved bytes are copied. Symlinks the agent creates inside the mount are skipped on sync-back.
+
 ## Notes
 
 - Requires Node.js 18+

package/dist/auto-sync.d.ts

@@ -10,6 +10,13 @@ export interface AutoSyncContext {
      */
     isIgnored: (relPosix: string, isDirectory?: boolean) => boolean;
     isReadonly: (relPosix: string) => boolean;
+    /**
+     * One-way project→mount paths. Project-side changes flow into the mount,
+     * but mount-side changes never flow back. Unlike readonly, the mount copy
+     * is left writable so tools (e.g. git) can mutate it locally; those
+     * mutations are simply discarded on cleanup.
+     */
+    isNoSyncBack: (relPosix: string) => boolean;
     isReservedFile: (relPosix: string) => boolean;
 }
 export interface AutoSyncOptions {

package/dist/auto-sync.js

@@ -262,11 +262,16 @@ function reconcile(state, ctx, onError, signal) {
  * Resolution rules ("mount wins"):
  * - If both sides changed since last sync → mount→project.
  * - Only mount changed → mount→project (unless mount-side change is disallowed
- *   for readonly files; then drop the mount change).
+ *   for readonly / noSyncBack files; then drop the mount change).
  * - Only project changed → project→mount.
  * - One side missing:
  *   • Other side changed since last sync → recreate the missing side.
  *   • Otherwise → propagate the delete.
+ *
+ * `readonly` and `noSyncBack` both forbid mount→project. The split exists so
+ * the chmod 0o444 only fires for true readonly entries (e.g. `.agentreadonly`
+ * matches), while noSyncBack entries (e.g. `.git/**` when `includeGit: true`)
+ * stay writable in the mount so tools can mutate them locally.
  */
 function syncOneFile(relPosix, state, ctx) {
     const mountAbs = path.join(ctx.realMountDir, relPosix);
@@ -275,6 +280,7 @@ function syncOneFile(relPosix, state, ctx) {
     const projectStat = safeFileStat(projectAbs);
     const prev = state.get(relPosix);
     const readonly = ctx.isReadonly(relPosix);
+    const noSyncBack = readonly || ctx.isNoSyncBack(relPosix);
     if (!mountStat && !projectStat) {
         state.delete(relPosix);
         return false;
@@ -290,15 +296,15 @@ function syncOneFile(relPosix, state, ctx) {
                 return false;
             }
             // Differ with no history: arbitrary tiebreak → mount wins.
-            if (readonly) {
-                // Readonly can't accept mount-side writes; fall back to project→mount.
+            if (noSyncBack) {
+                // Mount-side writes never flow back; fall back to project→mount.
                 return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
             }
             return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
         }
         if (mountStat && !projectStat) {
-            if (readonly) {
-                // New file in mount with a readonly pattern → cannot sync back.
+            if (noSyncBack) {
+                // New file in mount with a no-sync-back pattern → cannot sync back.
                 return false;
             }
             return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
@@ -319,7 +325,7 @@ function syncOneFile(relPosix, state, ctx) {
     if (mountStat && projectStat) {
         if (!mountChanged && !projectChanged)
             return false;
-        if (mountChanged && !readonly) {
+        if (mountChanged && !noSyncBack) {
             return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
         }
         if (projectChanged) {
@@ -328,7 +334,7 @@ function syncOneFile(relPosix, state, ctx) {
         return false;
     }
     if (mountStat && !projectStat) {
-        if (mountChanged && !readonly) {
+        if (mountChanged && !noSyncBack) {
             return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
         }
         // Project deleted externally and mount hasn't been touched since → mirror.
@@ -339,8 +345,8 @@ function syncOneFile(relPosix, state, ctx) {
             return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
         }
         // Mount deleted and project hasn't been touched since → mirror to project.
-        if (readonly) {
-            // Readonly deletes in mount don't sync back; recreate mount from project.
+        if (noSyncBack) {
+            // No-sync-back deletes in mount don't propagate; recreate from project.
             return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
         }
         return doDeleteProject(relPosix, state, projectAbs);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createSymlinkMount, type SymlinkMountOptions, type SymlinkMountHandle, } from './symlink-mount.js';
+export { createMount, type MountOptions, type MountHandle, } from './mount.js';
 export { type AutoSyncOptions, type AutoSyncHandle, } from './auto-sync.js';
 export { readAgentDotfiles, type ReadAgentDotfilesOptions, type AgentDotfilePatterns, } from './dotfiles.js';
 export { launchOnMount, type LaunchOnMountOptions, type LaunchOnMountResult, } from './launch.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { createSymlinkMount, } from './symlink-mount.js';
+export { createMount, } from './mount.js';
 export { readAgentDotfiles, } from './dotfiles.js';
 export { launchOnMount, } from './launch.js';

package/dist/launch.d.ts

@@ -14,6 +14,12 @@ export interface LaunchOnMountOptions {
     readonlyPatterns?: string[];
     /** Extra directory names to exclude from the mount on top of defaults. */
     excludeDirs?: string[];
+    /**
+     * Include the project's `.git` directory inside the mount with one-way
+     * project→mount sync. Defaults to false. See {@link MountOptions.includeGit}
+     * for details.
+     */
+    includeGit?: boolean;
     /** Extra env vars merged on top of `process.env`. */
     env?: NodeJS.ProcessEnv;
     /** Optional agent name, used in the _MOUNT_README.md "Agent:" line. */

package/dist/launch.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { createSymlinkMount } from './symlink-mount.js';
+import { createMount } from './mount.js';
 /**
  * Create a mount of `projectDir` at `mountDir`, spawn `cli` with `args` using
  * the mount as its cwd, forward SIGINT/SIGTERM to the child, sync writable
@@ -7,11 +7,12 @@ import { createSymlinkMount } from './symlink-mount.js';
  * exit code.
  */
 export async function launchOnMount(opts) {
-    const handle = createSymlinkMount(opts.projectDir, opts.mountDir, {
+    const handle = createMount(opts.projectDir, opts.mountDir, {
         ignoredPatterns: opts.ignoredPatterns ?? [],
         readonlyPatterns: opts.readonlyPatterns ?? [],
         excludeDirs: opts.excludeDirs ?? [],
         agentName: opts.agentName,
+        includeGit: opts.includeGit,
     });
     let syncedCount = 0;
     let finalized = false;

package/dist/mount.d.ts

@@ -0,0 +1,38 @@
+import { type AutoSyncHandle, type AutoSyncOptions } from './auto-sync.js';
+export interface MountOptions {
+    ignoredPatterns: string[];
+    readonlyPatterns: string[];
+    excludeDirs: string[];
+    /**
+     * Optional agent name used in the _MOUNT_README.md "Agent:" line.
+     * If omitted, the doc uses a generic "agent" value.
+     */
+    agentName?: string;
+    /**
+     * Include the project's `.git` directory inside the mount with one-way
+     * project→mount sync. Default: false (`.git` is excluded entirely, matching
+     * historical behavior).
+     *
+     * When true:
+     * - `.git` is copied into the mount on creation, so git commands work inside.
+     * - Project-side changes under `.git/**` flow into the mount.
+     * - Mount-side changes under `.git/**` do NOT flow back to the project, so
+     *   commits/branches the agent creates inside the mount stay sandboxed and
+     *   are discarded with the mount on cleanup. Push to a remote to keep them.
+     */
+    includeGit?: boolean;
+}
+export interface MountHandle {
+    mountDir: string;
+    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`
+     * as a safety net. Returns a handle you must `stop()` before teardown.
+     */
+    startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
+    cleanup(): void;
+}
+export declare function createMount(projectDir: string, mountDir: string, options: MountOptions): MountHandle;

package/dist/{symlink-mount.js → mount.js}

@@ -6,16 +6,26 @@ const DEFAULT_EXCLUDED_DIRS = ['.git', 'node_modules'];
 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 createSymlinkMount(projectDir, mountDir, options) {
+export function createMount(projectDir, mountDir, options) {
     const resolvedProjectDir = realpathSync(projectDir);
     const resolvedMountDir = path.resolve(mountDir);
     const readonlyPatterns = [...options.readonlyPatterns];
     const ignoredPatterns = [...options.ignoredPatterns];
+    const includeGit = options.includeGit === true;
     const readonlyMatcher = createPathMatcher(readonlyPatterns);
     const ignoredMatcher = createPathMatcher(ignoredPatterns);
-    const excludeSet = new Set([...DEFAULT_EXCLUDED_DIRS, ...options.excludeDirs]
+    // `.git` is in DEFAULT_EXCLUDED_DIRS 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 noSyncBackPatterns = includeGit ? ['.git', '.git/**'] : [];
+    const noSyncBackMatcher = createPathMatcher(noSyncBackPatterns);
     // Guard against mountDir === projectDir. We compare both the realpath'd
     // project dir and the plain resolved project dir so callers that pass the
     // same argument for both are caught even when the path is a symlink (e.g.
@@ -42,6 +52,7 @@ export function createSymlinkMount(projectDir, mountDir, options) {
         isExcluded: (relPosix) => isExcludedPath(relPosix, excludeSet),
         isIgnored: (relPosix, isDir) => isPathMatched(relPosix, ignoredMatcher, isDir),
         isReadonly: (relPosix) => isPathMatched(relPosix, readonlyMatcher),
+        isNoSyncBack: (relPosix) => isPathMatched(relPosix, noSyncBackMatcher),
         isReservedFile: (relPosix) => relPosix === MOUNT_README_FILENAME || relPosix === MOUNT_MARKER_FILENAME,
     };
     return {
@@ -56,7 +67,7 @@ export function createSymlinkMount(projectDir, mountDir, options) {
                 if (signal?.aborted) {
                     break;
                 }
-                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher);
+                const syncedForFile = syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher);
                 synced += syncedForFile;
                 if (signal && syncedForFile > 0 && !signal.aborted) {
                     await new Promise((resolve) => setImmediate(resolve));
@@ -107,7 +118,7 @@ function assertMountDirSafeToRemove(mountDir, projectDir) {
     const markerPath = path.join(resolved, MOUNT_MARKER_FILENAME);
     if (!existsSync(markerPath)) {
         throw new Error(`Refusing to remove ${resolved}: missing ${MOUNT_MARKER_FILENAME} marker. ` +
-            `Only directories previously created by createSymlinkMount can be reused as mountDir.`);
+            `Only directories previously created by createMount can be reused as mountDir.`);
     }
 }
 function walkProjectTree(projectDir, currentDir, mountDir, excludeSet, readonlyMatcher, ignoredMatcher) {
@@ -242,8 +253,8 @@ function hasSameContent(left, right) {
         return false;
     }
 }
-function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, ignoredMatcher) {
-    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher);
+function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher) {
+    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher);
     if (!relative)
         return 0;
     const safeTargetPath = resolveVerifiedSyncTarget(projectDir, relative);
@@ -255,7 +266,7 @@ function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher,
     copyFileSync(sourceFile, safeTargetPath);
     return 1;
 }
-function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher) {
+function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher, noSyncBackMatcher) {
     const relative = path.relative(mountDir, sourceFile);
     if (relative === '' || relative.startsWith('..'))
         return null;
@@ -264,7 +275,9 @@ function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredM
         return null;
     if (relativePosix === MOUNT_MARKER_FILENAME)
         return null;
-    if (isPathMatched(relative, readonlyMatcher) || isPathMatched(relative, ignoredMatcher))
+    if (isPathMatched(relative, readonlyMatcher) ||
+        isPathMatched(relative, ignoredMatcher) ||
+        isPathMatched(relative, noSyncBackMatcher))
         return null;
     try {
         if (lstatSync(sourceFile).isSymbolicLink())

package/package.json

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

package/dist/symlink-mount.d.ts

@@ -1,25 +0,0 @@
-import { type AutoSyncHandle, type AutoSyncOptions } from './auto-sync.js';
-export interface SymlinkMountOptions {
-    ignoredPatterns: string[];
-    readonlyPatterns: string[];
-    excludeDirs: string[];
-    /**
-     * Optional agent name used in the _MOUNT_README.md "Agent:" line.
-     * If omitted, the doc uses a generic "agent" value.
-     */
-    agentName?: string;
-}
-export interface SymlinkMountHandle {
-    mountDir: string;
-    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`
-     * as a safety net. Returns a handle you must `stop()` before teardown.
-     */
-    startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
-    cleanup(): void;
-}
-export declare function createSymlinkMount(projectDir: string, mountDir: string, options: SymlinkMountOptions): SymlinkMountHandle;