agent-relay 4.0.31 → 4.0.33

package/node_modules/@relayfile/local-mount/README.md

@@ -0,0 +1,215 @@
+# @relayfile/local-mount
+
+Create a temporary mounted mirror of a project directory, enforce `.agentignore` and `.agentreadonly` rules inside that mount, run an agent or CLI there, then sync writable changes back to the real project on exit.
+
+This package is useful when you want an agent to work in a constrained workspace without giving it direct write access to every file in the source tree.
+
+## Install
+
+```bash
+npm install @relayfile/local-mount
+```
+
+## What it exports
+
+### `createSymlinkMount(projectDir, mountDir, options)`
+
+Builds a mounted copy of `projectDir` at `mountDir` and returns a handle:
+
+```ts
+interface SymlinkMountHandle {
+  mountDir: string;
+  syncBack(): Promise<number>;
+  startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
+  cleanup(): void;
+}
+```
+
+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
+- 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
+
+### `readAgentDotfiles(projectDir, options?)`
+
+Reads project-local permission dotfiles and returns compiled pattern lists:
+
+- `.agentignore`
+- `.agentreadonly`
+- `.{agentName}.agentignore` (optional)
+- `.{agentName}.agentreadonly` (optional)
+
+Blank lines and `#` comments are ignored.
+
+```ts
+const { ignoredPatterns, readonlyPatterns } = readAgentDotfiles(projectDir, {
+  agentName: 'reviewer',
+});
+```
+
+### `launchOnMount(options)`
+
+High-level helper that:
+1. creates a mount,
+2. starts bidirectional auto-sync (see below, controllable via `autoSync`),
+3. runs a CLI inside the mount,
+4. forwards `SIGINT` and `SIGTERM`,
+5. stops auto-sync and runs a final sync-back pass after the child exits,
+6. cleans up the mount directory.
+
+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.
+
+### 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()`.
+
+```ts
+interface AutoSyncOptions {
+  /** Full-reconcile interval as a safety net. Default: 10_000 ms. */
+  scanIntervalMs?: number;
+  /** chokidar `awaitWriteFinish` stability threshold. Default: 200 ms. */
+  writeFinishMs?: number;
+  /** Invoked on sync errors. Defaults to swallowing them. */
+  onError?: (err: Error) => void;
+}
+
+interface AutoSyncHandle {
+  stop(): Promise<void>;
+  reconcile(): Promise<number>;
+  totalChanges(): number;
+  ready(): Promise<void>;
+}
+```
+
+Control it from `launchOnMount`:
+
+```ts
+// Disable entirely — only the final sync-back pass runs.
+launchOnMount({ /* ... */, autoSync: false });
+
+// Tune it.
+launchOnMount({ /* ... */, autoSync: { scanIntervalMs: 5_000, writeFinishMs: 100 } });
+```
+
+How it works:
+- chokidar watches both the mount and the project tree
+- 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
+
+Conflict and delete rules:
+- both sides changed since last sync → **mount wins**
+- only one side changed → propagate that change
+- one side deleted and the other unchanged since last sync → propagate the delete
+- one side deleted and the other changed since last sync → recreate the missing file from the changed side
+- 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
+
+## Dotfile semantics
+
+`@relayfile/local-mount` uses glob-style patterns, powered by [`ignore`](https://www.npmjs.com/package/ignore).
+
+### `.agentignore`
+
+Files matching these patterns are omitted from the mount entirely.
+
+Example:
+
+```gitignore
+secrets/
+.env
+coverage/
+```
+
+### `.agentreadonly`
+
+Files matching these patterns are copied into the mount, but made read-only.
+Changes to those files are not synced back.
+
+Example:
+
+```gitignore
+package.json
+docs/**
+*.lock
+```
+
+### Per-agent overrides
+
+If you pass `agentName`, the package also reads:
+
+- `.{agentName}.agentignore`
+- `.{agentName}.agentreadonly`
+
+Those patterns are appended to the generic ones.
+
+## Practical example
+
+```ts
+import { launchOnMount, readAgentDotfiles } from '@relayfile/local-mount';
+import path from 'node:path';
+import os from 'node:os';
+
+const projectDir = '/projects/acme-api';
+const mountDir = path.join(os.tmpdir(), 'acme-api-agent-mount');
+
+const { ignoredPatterns, readonlyPatterns } = readAgentDotfiles(projectDir, {
+  agentName: 'reviewer',
+});
+
+const result = await launchOnMount({
+  cli: 'claude',
+  args: ['--print', 'Review the codebase and update TODOs if needed.'],
+  projectDir,
+  mountDir,
+  ignoredPatterns,
+  readonlyPatterns,
+  excludeDirs: ['dist'],
+  agentName: 'reviewer',
+  onBeforeLaunch: async (dir) => {
+    // Add extra instructions or scratch files inside the mount if needed.
+    console.log(`Mount ready at ${dir}`);
+  },
+  onAfterSync: async (count) => {
+    console.log(`Synced ${count} writable file(s) back to the project`);
+  },
+});
+
+console.log(result.exitCode);
+```
+
+## Sync-back behavior
+
+`syncBack()` is the one-shot, mount-only sweep used as a final pass (and available on its own if you disable auto-sync). It only writes files that are safe and writable:
+
+- changed writable files are copied back
+- new writable files created in the mount are copied back
+- unchanged files are skipped
+- ignored files are skipped
+- read-only matches are skipped
+- symlinks inside the mount are skipped
+
+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.
+
+## Safety constraints
+
+The implementation is intentionally conservative about `mountDir`:
+
+- `mountDir` must be different from `projectDir`
+- `mountDir` cannot be a filesystem root
+- `mountDir` cannot overlap the source project directory in either direction
+- if `mountDir` already exists, it must contain the `.relayfile-local-mount` marker file from a previous mount created by this package
+
+These checks help prevent accidental deletion of unrelated directories during mount recreation and cleanup.
+
+## Notes
+
+- Requires Node.js 18+
+- The current implementation copies files into the mount rather than creating filesystem-level FUSE mounts
+- Source symlinks are only copied when they resolve to regular files inside the source project
+
+## License
+
+MIT

package/node_modules/@relayfile/local-mount/dist/auto-sync.d.ts

@@ -0,0 +1,31 @@
+export interface AutoSyncContext {
+    realMountDir: string;
+    realProjectDir: string;
+    isExcluded: (relPosix: string) => boolean;
+    /**
+     * 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.
+     */
+    isIgnored: (relPosix: string, isDirectory?: boolean) => boolean;
+    isReadonly: (relPosix: string) => boolean;
+    isReservedFile: (relPosix: string) => boolean;
+}
+export interface AutoSyncOptions {
+    /** Full-reconcile interval as a safety net. Default: 10_000ms. */
+    scanIntervalMs?: number;
+    /** chokidar awaitWriteFinish stabilityThreshold in ms. Default: 200. */
+    writeFinishMs?: number;
+    /** Invoked on errors during sync — logged by default consumer. */
+    onError?: (err: Error) => void;
+}
+export interface AutoSyncHandle {
+    stop(): Promise<void>;
+    /** Force a reconcile now; returns number of files copied/deleted. */
+    reconcile(): Promise<number>;
+    /** Cumulative files changed (copied or deleted) since autosync started. */
+    totalChanges(): number;
+    /** Resolves once both watchers have completed their initial scan. */
+    ready(): Promise<void>;
+}
+export declare function startAutoSync(ctx: AutoSyncContext, opts?: AutoSyncOptions): AutoSyncHandle;

package/node_modules/@relayfile/local-mount/dist/auto-sync.js

@@ -0,0 +1,466 @@
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
+import path from 'node:path';
+import chokidar from 'chokidar';
+export function startAutoSync(ctx, opts = {}) {
+    const scanIntervalMs = opts.scanIntervalMs ?? 10_000;
+    const writeFinishMs = opts.writeFinishMs ?? 200;
+    const onError = opts.onError ?? (() => { });
+    const state = new Map();
+    primeState(state, ctx);
+    let syncing = false;
+    let pending = false;
+    let totalChanges = 0;
+    const runReconcile = async () => {
+        if (syncing) {
+            pending = true;
+            return 0;
+        }
+        syncing = true;
+        let count = 0;
+        try {
+            count = reconcile(state, ctx, onError);
+        }
+        catch (err) {
+            onError(err);
+        }
+        finally {
+            syncing = false;
+        }
+        if (pending) {
+            pending = false;
+            try {
+                count += reconcile(state, ctx, onError);
+            }
+            catch (err) {
+                onError(err);
+            }
+        }
+        totalChanges += count;
+        return count;
+    };
+    const syncPathFromRoot = (root, absPath) => {
+        const rel = path.relative(root, absPath);
+        if (rel === '' || rel.startsWith('..'))
+            return;
+        const relPosix = rel.split(path.sep).join('/');
+        if (!isSyncCandidate(relPosix, ctx))
+            return;
+        try {
+            const changed = syncOneFile(relPosix, state, ctx);
+            if (changed)
+                totalChanges += 1;
+        }
+        catch (err) {
+            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 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 interval = setInterval(() => {
+        void runReconcile();
+    }, scanIntervalMs);
+    // Do not keep the event loop alive just because of our scan timer.
+    interval.unref?.();
+    return {
+        async stop() {
+            clearInterval(interval);
+            await Promise.all([mountWatcher.close(), projectWatcher.close()]);
+            // Drain any pending work so callers can rely on "stopped means quiesced".
+            await runReconcile();
+        },
+        reconcile: runReconcile,
+        totalChanges: () => totalChanges,
+        ready: async () => {
+            await watchersReady;
+        },
+    };
+}
+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
+    // no prev entry and picks a winner via the content-based resolution path.
+    walk(ctx.realMountDir, ctx, (abs) => {
+        const rel = toRelPosix(abs, ctx);
+        if (rel === null)
+            return;
+        if (!isSyncCandidate(rel, ctx))
+            return;
+        const mountStat = safeFileStat(abs);
+        if (!mountStat)
+            return;
+        const projectAbs = path.join(ctx.realProjectDir, rel);
+        const projectStat = safeFileStat(projectAbs);
+        if (!projectStat)
+            return;
+        if (!sameContent(abs, projectAbs))
+            return;
+        state.set(rel, {
+            mountMtimeMs: mountStat.mtimeMs,
+            projectMtimeMs: projectStat.mtimeMs,
+        });
+    });
+}
+function reconcile(state, ctx, onError) {
+    const seen = new Set();
+    let count = 0;
+    const visit = (relPosix) => {
+        if (seen.has(relPosix))
+            return;
+        seen.add(relPosix);
+        if (!isSyncCandidate(relPosix, ctx))
+            return;
+        try {
+            const changed = syncOneFile(relPosix, state, ctx);
+            if (changed)
+                count += 1;
+        }
+        catch (err) {
+            onError(err);
+        }
+    };
+    walk(ctx.realMountDir, ctx, (abs) => {
+        const rel = toRelPosix(abs, ctx);
+        if (rel !== null)
+            visit(rel);
+    });
+    walk(ctx.realProjectDir, ctx, (abs) => {
+        const rel = toRelPosixFromProject(abs, ctx);
+        if (rel !== null)
+            visit(rel);
+    });
+    // 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())) {
+        if (!seen.has(rel)) {
+            const mountAbs = path.join(ctx.realMountDir, rel);
+            const projectAbs = path.join(ctx.realProjectDir, rel);
+            if (!existsSync(mountAbs) && !existsSync(projectAbs)) {
+                state.delete(rel);
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Sync a single relPath and return true if a copy or delete actually happened.
+ *
+ * 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).
+ * - Only project changed → project→mount.
+ * - One side missing:
+ *   • Other side changed since last sync → recreate the missing side.
+ *   • Otherwise → propagate the delete.
+ */
+function syncOneFile(relPosix, state, ctx) {
+    const mountAbs = path.join(ctx.realMountDir, relPosix);
+    const projectAbs = path.join(ctx.realProjectDir, relPosix);
+    const mountStat = safeFileStat(mountAbs);
+    const projectStat = safeFileStat(projectAbs);
+    const prev = state.get(relPosix);
+    const readonly = ctx.isReadonly(relPosix);
+    if (!mountStat && !projectStat) {
+        state.delete(relPosix);
+        return false;
+    }
+    if (!prev) {
+        // First time we've seen this path.
+        if (mountStat && projectStat) {
+            if (sameContent(mountAbs, projectAbs)) {
+                state.set(relPosix, {
+                    mountMtimeMs: mountStat.mtimeMs,
+                    projectMtimeMs: projectStat.mtimeMs,
+                });
+                return false;
+            }
+            // Differ with no history: arbitrary tiebreak → mount wins.
+            if (readonly) {
+                // Readonly can't accept mount-side writes; 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.
+                return false;
+            }
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        if (!mountStat && projectStat) {
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+    }
+    // Use strict inequality rather than `>`: on filesystems with coarse mtime
+    // resolution, or after a backdated touch, a real content change can land
+    // with a non-greater mtime.
+    const mountChanged = mountStat
+        ? prev?.mountMtimeMs === undefined || mountStat.mtimeMs !== prev.mountMtimeMs
+        : false;
+    const projectChanged = projectStat
+        ? prev?.projectMtimeMs === undefined || projectStat.mtimeMs !== prev.projectMtimeMs
+        : false;
+    if (mountStat && projectStat) {
+        if (!mountChanged && !projectChanged)
+            return false;
+        if (mountChanged && !readonly) {
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        if (projectChanged) {
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+        return false;
+    }
+    if (mountStat && !projectStat) {
+        if (mountChanged && !readonly) {
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        // Project deleted externally and mount hasn't been touched since → mirror.
+        return doDeleteMount(relPosix, state, mountAbs);
+    }
+    if (!mountStat && projectStat) {
+        if (projectChanged) {
+            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.
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+        return doDeleteProject(relPosix, state, projectAbs);
+    }
+    return false;
+}
+function doMountToProject(relPosix, state, ctx, mountAbs, projectAbs) {
+    const target = resolveSafeWriteTarget(ctx.realProjectDir, projectAbs);
+    if (!target)
+        return false;
+    if (isSymlinkTarget(target))
+        return false;
+    if (existsSync(target) && sameContent(mountAbs, target)) {
+        updateState(state, relPosix, mountAbs, target);
+        return false;
+    }
+    copyFileSync(mountAbs, target);
+    updateState(state, relPosix, mountAbs, target);
+    return true;
+}
+function doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly) {
+    const target = resolveSafeWriteTarget(ctx.realMountDir, mountAbs);
+    if (!target)
+        return false;
+    if (isSymlinkTarget(target))
+        return false;
+    if (existsSync(target) && sameContent(projectAbs, target)) {
+        updateState(state, relPosix, target, projectAbs);
+        return false;
+    }
+    // The mount copy of a readonly file has mode 0o444, which blocks
+    // copyFileSync from overwriting it. Temporarily restore write permission.
+    if (existsSync(target)) {
+        try {
+            chmodSync(target, 0o644);
+        }
+        catch { /* best effort */ }
+    }
+    copyFileSync(projectAbs, target);
+    if (readonly) {
+        try {
+            chmodSync(target, 0o444);
+        }
+        catch { /* best effort */ }
+    }
+    else {
+        const mode = safeFileStat(projectAbs)?.mode;
+        if (mode !== undefined) {
+            try {
+                chmodSync(target, mode & 0o777);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    updateState(state, relPosix, target, projectAbs);
+    return true;
+}
+function doDeleteMount(relPosix, state, mountAbs) {
+    try {
+        rmSync(mountAbs, { force: true });
+    }
+    catch {
+        return false;
+    }
+    state.delete(relPosix);
+    return true;
+}
+function doDeleteProject(relPosix, state, projectAbs) {
+    try {
+        rmSync(projectAbs, { force: true });
+    }
+    catch {
+        return false;
+    }
+    state.delete(relPosix);
+    return true;
+}
+function updateState(state, relPosix, mountAbs, projectAbs) {
+    const mountStat = safeFileStat(mountAbs);
+    const projectStat = safeFileStat(projectAbs);
+    state.set(relPosix, {
+        mountMtimeMs: mountStat?.mtimeMs,
+        projectMtimeMs: projectStat?.mtimeMs,
+    });
+}
+function isSyncCandidate(relPosix, ctx) {
+    if (!relPosix || relPosix.startsWith('..'))
+        return false;
+    if (ctx.isReservedFile(relPosix))
+        return false;
+    if (ctx.isExcluded(relPosix))
+        return false;
+    if (ctx.isIgnored(relPosix))
+        return false;
+    return true;
+}
+function toRelPosix(absPath, ctx) {
+    const rel = path.relative(ctx.realMountDir, absPath);
+    if (rel === '' || rel.startsWith('..'))
+        return null;
+    return rel.split(path.sep).join('/');
+}
+function toRelPosixFromProject(absPath, ctx) {
+    const rel = path.relative(ctx.realProjectDir, absPath);
+    if (rel === '' || rel.startsWith('..'))
+        return null;
+    return rel.split(path.sep).join('/');
+}
+function safeFileStat(p) {
+    try {
+        const s = lstatSync(p);
+        if (s.isSymbolicLink())
+            return null;
+        if (!s.isFile())
+            return null;
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+function isSymlinkTarget(target) {
+    // If the target already exists as a symlink, writing through it would
+    // follow the link and potentially escape the mount/project root. Refuse.
+    try {
+        return lstatSync(target).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function sameContent(left, right) {
+    try {
+        const a = statSync(left);
+        const b = statSync(right);
+        if (a.size !== b.size)
+            return false;
+        return readFileSync(left).equals(readFileSync(right));
+    }
+    catch {
+        return false;
+    }
+}
+function resolveSafeWriteTarget(root, candidate) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedCandidate = path.resolve(candidate);
+    if (resolvedCandidate !== resolvedRoot &&
+        !resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`)) {
+        return null;
+    }
+    const parent = path.dirname(resolvedCandidate);
+    try {
+        mkdirSync(parent, { recursive: true });
+        const realParent = realpathSync(parent);
+        if (realParent !== resolvedRoot &&
+            !realParent.startsWith(`${resolvedRoot}${path.sep}`)) {
+            return null;
+        }
+        return path.join(realParent, path.basename(resolvedCandidate));
+    }
+    catch {
+        return null;
+    }
+}
+function walk(root, ctx, visit) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (!cur)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = path.join(cur, entry.name);
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel || rel.startsWith('..'))
+                continue;
+            if (ctx.isExcluded(rel) || ctx.isIgnored(rel, entry.isDirectory()))
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(abs);
+            }
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                visit(abs);
+            }
+        }
+    }
+}
+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);
+}