agent-relay 4.0.31 → 4.0.33

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

@@ -0,0 +1,18 @@
+export interface ReadAgentDotfilesOptions {
+    /**
+     * If provided, also reads `.{agentName}.agentignore` and `.{agentName}.agentreadonly`
+     * from the project directory and merges the resulting patterns.
+     */
+    agentName?: string;
+}
+export interface AgentDotfilePatterns {
+    ignoredPatterns: string[];
+    readonlyPatterns: string[];
+}
+/**
+ * Read `.agentignore` and `.agentreadonly` dotfiles from a project directory
+ * and return the compiled pattern lists. If `agentName` is supplied, also
+ * reads `.{agentName}.agentignore` and `.{agentName}.agentreadonly` and
+ * appends their patterns.
+ */
+export declare function readAgentDotfiles(projectDir: string, options?: ReadAgentDotfilesOptions): AgentDotfilePatterns;

package/node_modules/@relayfile/local-mount/dist/dotfiles.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+function cleanPatterns(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !line.startsWith('#'));
+}
+function loadPatternsFromFile(filePath) {
+    if (!existsSync(filePath)) {
+        return [];
+    }
+    const content = readFileSync(filePath, 'utf8');
+    return cleanPatterns(content);
+}
+/**
+ * Read `.agentignore` and `.agentreadonly` dotfiles from a project directory
+ * and return the compiled pattern lists. If `agentName` is supplied, also
+ * reads `.{agentName}.agentignore` and `.{agentName}.agentreadonly` and
+ * appends their patterns.
+ */
+export function readAgentDotfiles(projectDir, options = {}) {
+    const resolvedProjectDir = path.resolve(projectDir);
+    const ignoredPatterns = [
+        ...loadPatternsFromFile(path.join(resolvedProjectDir, '.agentignore')),
+    ];
+    const readonlyPatterns = [
+        ...loadPatternsFromFile(path.join(resolvedProjectDir, '.agentreadonly')),
+    ];
+    if (options.agentName) {
+        const safeAgentName = sanitizeAgentName(options.agentName);
+        ignoredPatterns.push(...loadPatternsFromFile(path.join(resolvedProjectDir, `.${safeAgentName}.agentignore`)));
+        readonlyPatterns.push(...loadPatternsFromFile(path.join(resolvedProjectDir, `.${safeAgentName}.agentreadonly`)));
+    }
+    return { ignoredPatterns, readonlyPatterns };
+}
+const AGENT_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+function sanitizeAgentName(agentName) {
+    if (!AGENT_NAME_PATTERN.test(agentName) || path.basename(agentName) !== agentName) {
+        throw new Error(`Invalid agentName ${JSON.stringify(agentName)}: only [A-Za-z0-9_-] are allowed`);
+    }
+    return agentName;
+}

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

@@ -0,0 +1,4 @@
+export { createSymlinkMount, type SymlinkMountOptions, type SymlinkMountHandle, } from './symlink-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/node_modules/@relayfile/local-mount/dist/index.js

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

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

@@ -0,0 +1,50 @@
+import type { AutoSyncOptions } from './auto-sync.js';
+export interface LaunchOnMountOptions {
+    /** Binary name or absolute path to the CLI to spawn, e.g. 'claude'. */
+    cli: string;
+    /** The real project directory to mirror. */
+    projectDir: string;
+    /** Where to create the mount. Must differ from projectDir. */
+    mountDir: string;
+    /** Argv to pass to the CLI after its binary name. */
+    args: string[];
+    /** Glob-style ignore patterns (files excluded entirely from the mount). */
+    ignoredPatterns?: string[];
+    /** Glob-style readonly patterns (files copied with mode 0o444). */
+    readonlyPatterns?: string[];
+    /** Extra directory names to exclude from the mount on top of defaults. */
+    excludeDirs?: string[];
+    /** Extra env vars merged on top of `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Optional agent name, used in the _MOUNT_README.md "Agent:" line. */
+    agentName?: string;
+    /**
+     * Invoked after the mount is created but before the CLI is spawned.
+     * Useful for writing additional files into the mount (overrides, extra docs).
+     */
+    onBeforeLaunch?: (mountDir: string) => void | Promise<void>;
+    /**
+     * Invoked after sync-back completes, before cleanup. Receives the total
+     * number of file changes propagated during the run — the sum of autosync
+     * activity in both directions (including deletes) and the final mount→
+     * project syncBack. Use this as an "anything changed?" signal rather than
+     * a strict mount→project count.
+     */
+    onAfterSync?: (syncedFileCount: number) => void | Promise<void>;
+    /**
+     * Auto-sync behavior. By default, bidirectional auto-sync runs during the
+     * lifetime of the spawned CLI. Pass `false` to disable, or an options object
+     * to tune the scan interval / write-finish debounce.
+     */
+    autoSync?: boolean | AutoSyncOptions;
+}
+export interface LaunchOnMountResult {
+    exitCode: number;
+}
+/**
+ * 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
+ * changes back on exit, then clean up the mount. Resolves with the child's
+ * exit code.
+ */
+export declare function launchOnMount(opts: LaunchOnMountOptions): Promise<LaunchOnMountResult>;

package/node_modules/@relayfile/local-mount/dist/launch.js

@@ -0,0 +1,129 @@
+import { spawn } from 'node:child_process';
+import { createSymlinkMount } from './symlink-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
+ * changes back on exit, then clean up the mount. Resolves with the child's
+ * exit code.
+ */
+export async function launchOnMount(opts) {
+    const handle = createSymlinkMount(opts.projectDir, opts.mountDir, {
+        ignoredPatterns: opts.ignoredPatterns ?? [],
+        readonlyPatterns: opts.readonlyPatterns ?? [],
+        excludeDirs: opts.excludeDirs ?? [],
+        agentName: opts.agentName,
+    });
+    let syncedCount = 0;
+    let finalized = false;
+    let autoSync;
+    const finalize = async () => {
+        if (finalized)
+            return;
+        finalized = true;
+        try {
+            let autoSyncChanges = 0;
+            if (autoSync) {
+                await autoSync.stop();
+                autoSyncChanges = autoSync.totalChanges();
+                autoSync = undefined;
+            }
+            const finalSynced = await handle.syncBack();
+            syncedCount = autoSyncChanges + finalSynced;
+            if (opts.onAfterSync) {
+                await opts.onAfterSync(syncedCount);
+            }
+        }
+        finally {
+            handle.cleanup();
+        }
+    };
+    try {
+        if (opts.onBeforeLaunch) {
+            await opts.onBeforeLaunch(handle.mountDir);
+        }
+        if (opts.autoSync !== false) {
+            const autoSyncOpts = typeof opts.autoSync === 'object' ? opts.autoSync : undefined;
+            autoSync = handle.startAutoSync(autoSyncOpts);
+        }
+        const envVars = {
+            ...process.env,
+            ...(opts.env ?? {}),
+        };
+        const exitCode = await new Promise((resolve, reject) => {
+            const child = spawn(opts.cli, opts.args, {
+                cwd: handle.mountDir,
+                stdio: 'inherit',
+                env: envVars,
+            });
+            let resolvedExit = 0;
+            let cleanupInProgress;
+            const forwardAndCleanup = (signal) => {
+                if (!child.killed && child.exitCode === null) {
+                    try {
+                        child.kill(signal);
+                    }
+                    catch {
+                        // ignore; we'll rely on 'close' handler
+                    }
+                }
+                if (!cleanupInProgress) {
+                    cleanupInProgress = new Promise((r) => {
+                        if (child.exitCode !== null) {
+                            r();
+                            return;
+                        }
+                        const t = setTimeout(r, 2000);
+                        child.once('close', () => {
+                            clearTimeout(t);
+                            r();
+                        });
+                    });
+                }
+            };
+            const onSigint = () => forwardAndCleanup('SIGINT');
+            const onSigterm = () => forwardAndCleanup('SIGTERM');
+            process.once('SIGINT', onSigint);
+            process.once('SIGTERM', onSigterm);
+            child.on('error', (err) => {
+                process.removeListener('SIGINT', onSigint);
+                process.removeListener('SIGTERM', onSigterm);
+                reject(err);
+            });
+            child.on('close', (code, signal) => {
+                process.removeListener('SIGINT', onSigint);
+                process.removeListener('SIGTERM', onSigterm);
+                if (typeof code === 'number') {
+                    resolvedExit = code;
+                }
+                else if (signal === 'SIGINT') {
+                    resolvedExit = 130;
+                }
+                else if (signal === 'SIGTERM') {
+                    resolvedExit = 143;
+                }
+                else if (typeof signal === 'string') {
+                    // Conventional mapping: 128 + signal number. We don't have the
+                    // numeric signal handy, so fall back to 1 for unknown signals.
+                    resolvedExit = 1;
+                }
+                else {
+                    resolvedExit = 1;
+                }
+                if (cleanupInProgress) {
+                    cleanupInProgress.then(() => resolve(resolvedExit));
+                }
+                else {
+                    resolve(resolvedExit);
+                }
+            });
+        });
+        await finalize();
+        return { exitCode };
+    }
+    catch (err) {
+        await finalize().catch(() => {
+            // Already errored; swallow cleanup failure so the original error surfaces.
+        });
+        throw err;
+    }
+}

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

@@ -0,0 +1,23 @@
+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(): 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.
+     */
+    startAutoSync(opts?: AutoSyncOptions): AutoSyncHandle;
+    cleanup(): void;
+}
+export declare function createSymlinkMount(projectDir: string, mountDir: string, options: SymlinkMountOptions): SymlinkMountHandle;

package/{dist/src/cli/commands/on → node_modules/@relayfile/local-mount/dist}/symlink-mount.js

@@ -1,8 +1,11 @@
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import ignore from 'ignore';
 import path from 'node:path';
-const DEFAULT_EXCLUDED_DIRS = ['.git', 'node_modules', '.relay'];
-const PERMISSIONS_AGENT_NAME = 'local-agent';
+import { startAutoSync, } from './auto-sync.js';
+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) {
     const resolvedProjectDir = realpathSync(projectDir);
     const resolvedMountDir = path.resolve(mountDir);
@@ -13,18 +16,34 @@ export function createSymlinkMount(projectDir, mountDir, options) {
     const excludeSet = new Set([...DEFAULT_EXCLUDED_DIRS, ...options.excludeDirs]
         .map((entry) => normalizeRelativePosix(entry).replace(/^\/+|\/+$/g, ''))
         .filter(Boolean));
-    if (resolvedMountDir === resolvedProjectDir) {
+    // 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.
+    // /tmp → /private/tmp on macOS). The mountDir itself may not yet exist,
+    // so we cannot realpath it.
+    if (resolvedMountDir === resolvedProjectDir ||
+        resolvedMountDir === path.resolve(projectDir)) {
         throw new Error('mountDir must be different from projectDir');
     }
+    assertMountDirSafeToRemove(resolvedMountDir, resolvedProjectDir);
     removeMountDir(resolvedMountDir);
     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);
-    const permissionsDocPath = resolveSafeCopyTarget(realMountDir, path.join(realMountDir, '_PERMISSIONS.md'));
-    if (!permissionsDocPath) {
-        throw new Error('Failed to create permissions document inside mountDir');
+    const readmePath = resolveSafeCopyTarget(realMountDir, path.join(realMountDir, MOUNT_README_FILENAME));
+    if (!readmePath) {
+        throw new Error('Failed to create mount readme inside mountDir');
     }
-    writeFileSync(permissionsDocPath, buildPermissionDoc(PERMISSIONS_AGENT_NAME, readonlyPatterns, ignoredPatterns), 'utf8');
+    writeFileSync(readmePath, buildMountReadme(options.agentName, readonlyPatterns, ignoredPatterns), 'utf8');
+    const autoSyncContext = {
+        realMountDir,
+        realProjectDir: resolvedProjectDir,
+        isExcluded: (relPosix) => isExcludedPath(relPosix, excludeSet),
+        isIgnored: (relPosix, isDir) => isPathMatched(relPosix, ignoredMatcher, isDir),
+        isReadonly: (relPosix) => isPathMatched(relPosix, readonlyMatcher),
+        isReservedFile: (relPosix) => relPosix === MOUNT_README_FILENAME || relPosix === MOUNT_MARKER_FILENAME,
+    };
     return {
         mountDir: resolvedMountDir,
         async syncBack() {
@@ -37,11 +56,52 @@ export function createSymlinkMount(projectDir, mountDir, options) {
             }
             return synced;
         },
+        startAutoSync(opts) {
+            return startAutoSync(autoSyncContext, opts);
+        },
         cleanup() {
             removeMountDir(resolvedMountDir);
         },
     };
 }
+function assertMountDirSafeToRemove(mountDir, projectDir) {
+    const resolved = path.resolve(mountDir);
+    const parsed = path.parse(resolved);
+    // Refuse filesystem roots (posix '/' or a Windows drive root like 'C:\').
+    if (resolved === parsed.root) {
+        throw new Error(`Refusing to use filesystem root as mountDir: ${resolved}`);
+    }
+    // Refuse anything that would overlap the project directory (destroying the
+    // project would be catastrophic). `path.resolve(projectDir)` avoids following
+    // symlinks so both the symlink-target and the literal argument are rejected.
+    const resolvedProject = path.resolve(projectDir);
+    if (resolved === resolvedProject ||
+        resolved.startsWith(`${resolvedProject}${path.sep}`) ||
+        resolvedProject.startsWith(`${resolved}${path.sep}`)) {
+        throw new Error(`mountDir ${resolved} overlaps projectDir ${resolvedProject}`);
+    }
+    // If the directory already exists, require it to be a directory we created
+    // previously (identified by the mount marker file). Otherwise the caller
+    // pointed us at an unrelated directory and removing it would destroy data.
+    if (!existsSync(resolved)) {
+        return;
+    }
+    let stat;
+    try {
+        stat = lstatSync(resolved);
+    }
+    catch (err) {
+        throw new Error(`Failed to stat mountDir ${resolved}: ${err.message}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`mountDir ${resolved} exists and is not a directory`);
+    }
+    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.`);
+    }
+}
 function walkProjectTree(projectDir, currentDir, mountDir, excludeSet, readonlyMatcher, ignoredMatcher) {
     const entries = readdirSync(currentDir, { withFileTypes: true });
     for (const entry of entries) {
@@ -134,8 +194,6 @@ function listFiles(baseDir) {
             continue;
         const entries = readdirSync(current, { withFileTypes: true });
         for (const entry of entries) {
-            if (entry.name === '.relay')
-                continue;
             const entryPath = path.join(current, entry.name);
             if (entry.isDirectory()) {
                 stack.push(entryPath);
@@ -159,6 +217,15 @@ function isPathMatched(relPath, matcher, isDirectory = false) {
 }
 function hasSameContent(left, right) {
     try {
+        const leftStat = statSync(left);
+        const rightStat = statSync(right);
+        if (leftStat.size !== rightStat.size) {
+            return false;
+        }
+        // Same size: fall back to a full byte comparison. Buffer.equals short-
+        // circuits internally but we still read both files; for very large files
+        // callers may want a streaming approach, though in practice mounts are
+        // dominated by source code where this is cheap.
         const leftContent = readFileSync(left);
         const rightContent = readFileSync(right);
         return leftContent.equals(rightContent);
@@ -184,7 +251,10 @@ function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredM
     const relative = path.relative(mountDir, sourceFile);
     if (relative === '' || relative.startsWith('..'))
         return null;
-    if (relative === '.agent-relay' || normalizeRelativePosix(relative) === '_PERMISSIONS.md')
+    const relativePosix = normalizeRelativePosix(relative);
+    if (relativePosix === MOUNT_README_FILENAME)
+        return null;
+    if (relativePosix === MOUNT_MARKER_FILENAME)
         return null;
     if (isPathMatched(relative, readonlyMatcher) || isPathMatched(relative, ignoredMatcher))
         return null;
@@ -277,28 +347,26 @@ function removeMountDir(mountDir) {
         // Best-effort cleanup.
     }
 }
-function buildPermissionDoc(agentName, readonlyPatterns, ignoredPatterns) {
+function buildMountReadme(agentName, readonlyPatterns, ignoredPatterns) {
     const readonlyList = readonlyPatterns.length > 0 ? readonlyPatterns.join('\n') : '(none)';
     const ignoredList = ignoredPatterns.length > 0 ? ignoredPatterns.join('\n') : '(none)';
+    const agentLine = agentName ? `\nAgent: ${agentName}\n` : '';
     return `# Workspace Permissions
 
-This workspace is managed by the relay.
+This workspace is a mounted mirror of the project directory.
 File access is controlled by project-local .agentignore and .agentreadonly.
 
 ## Read-only files (cannot be modified)
-${readonlyList || '(none)'}
+${readonlyList}
 
 ## Hidden files (not available in this workspace)
-${ignoredList || '(none)'}
+${ignoredList}
 
 ## Writable files
 All other files can be read and modified freely.
 
 If you get "permission denied", the file is read-only.
-Changes to read-only files will be automatically reverted.
-Do not attempt to chmod files - permissions will be restored.
-
-Agent: ${agentName}
-`;
+Changes to read-only files are not synced back to the source project.
+Edits or permission changes to read-only files inside this mount may be discarded or overwritten when the mount is recreated.
+${agentLine}`;
 }
-//# sourceMappingURL=symlink-mount.js.map

package/node_modules/@relayfile/local-mount/node_modules/chokidar/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2012 Paul Miller (https://paulmillr.com), Elan Shanker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.