@relayfile/local-mount 0.1.0

package/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/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/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createSymlinkMount, type SymlinkMountOptions, type SymlinkMountHandle, } from './symlink-mount.js';
+export { readAgentDotfiles, type ReadAgentDotfilesOptions, type AgentDotfilePatterns, } from './dotfiles.js';
+export { launchOnMount, type LaunchOnMountOptions, type LaunchOnMountResult, } from './launch.js';

package/dist/index.js

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

package/dist/launch.d.ts

@@ -0,0 +1,40 @@
+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 number of
+     * files that were written back to the project directory.
+     */
+    onAfterSync?: (syncedFileCount: number) => void | Promise<void>;
+}
+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/dist/launch.js

@@ -0,0 +1,117 @@
+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;
+    const finalize = async () => {
+        if (finalized)
+            return;
+        finalized = true;
+        try {
+            syncedCount = await handle.syncBack();
+            if (opts.onAfterSync) {
+                await opts.onAfterSync(syncedCount);
+            }
+        }
+        finally {
+            handle.cleanup();
+        }
+    };
+    try {
+        if (opts.onBeforeLaunch) {
+            await opts.onBeforeLaunch(handle.mountDir);
+        }
+        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/dist/symlink-mount.d.ts

@@ -0,0 +1,16 @@
+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>;
+    cleanup(): void;
+}
+export declare function createSymlinkMount(projectDir: string, mountDir: string, options: SymlinkMountOptions): SymlinkMountHandle;

package/dist/symlink-mount.js

@@ -0,0 +1,360 @@
+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'];
+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);
+    const readonlyPatterns = [...options.readonlyPatterns];
+    const ignoredPatterns = [...options.ignoredPatterns];
+    const readonlyMatcher = createPathMatcher(readonlyPatterns);
+    const ignoredMatcher = createPathMatcher(ignoredPatterns);
+    const excludeSet = new Set([...DEFAULT_EXCLUDED_DIRS, ...options.excludeDirs]
+        .map((entry) => normalizeRelativePosix(entry).replace(/^\/+|\/+$/g, ''))
+        .filter(Boolean));
+    // 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 readmePath = resolveSafeCopyTarget(realMountDir, path.join(realMountDir, MOUNT_README_FILENAME));
+    if (!readmePath) {
+        throw new Error('Failed to create mount readme inside mountDir');
+    }
+    writeFileSync(readmePath, buildMountReadme(options.agentName, readonlyPatterns, ignoredPatterns), 'utf8');
+    return {
+        mountDir: resolvedMountDir,
+        async syncBack() {
+            let synced = 0;
+            const realProjectDir = realpathSync(resolvedProjectDir);
+            const realMountDir = realpathSync(resolvedMountDir);
+            const files = listFiles(realMountDir);
+            for (const sourceFile of files) {
+                synced += syncMountedFileBack(sourceFile, realMountDir, realProjectDir, readonlyMatcher, ignoredMatcher);
+            }
+            return synced;
+        },
+        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) {
+        const absolutePath = path.join(currentDir, entry.name);
+        const relativePath = normalizeRelativePosix(path.relative(projectDir, absolutePath));
+        if (!relativePath || relativePath.startsWith('..')) {
+            continue;
+        }
+        if (isPathWithinRoot(absolutePath, mountDir)) {
+            continue;
+        }
+        if (isExcludedPath(relativePath, excludeSet)) {
+            continue;
+        }
+        if (isPathMatched(relativePath, ignoredMatcher, entry.isDirectory())) {
+            continue;
+        }
+        const mountPath = path.join(mountDir, relativePath);
+        if (entry.isDirectory()) {
+            if (!ensureDirectoryWithinRoot(mountDir, mountPath)) {
+                continue;
+            }
+            walkProjectTree(projectDir, absolutePath, mountDir, excludeSet, readonlyMatcher, ignoredMatcher);
+            continue;
+        }
+        if (entry.isSymbolicLink()) {
+            copySymlinkedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        copyMountedFile(projectDir, mountDir, absolutePath, mountPath, relativePath, readonlyMatcher);
+    }
+}
+function copySymlinkedFile(projectDir, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher) {
+    let realSource;
+    let resolvedStat;
+    try {
+        realSource = realpathSync(sourcePath);
+        resolvedStat = statSync(sourcePath);
+    }
+    catch {
+        return;
+    }
+    if (!isPathWithinRoot(realSource, projectDir) || !resolvedStat.isFile()) {
+        return;
+    }
+    copyMountedFile(projectDir, mountDir, realSource, mountPath, relativePath, readonlyMatcher, resolvedStat.mode);
+}
+function copyMountedFile(sourceRoot, mountDir, sourcePath, mountPath, relativePath, readonlyMatcher, sourceMode) {
+    const safeMountPath = resolveSafeCopyTarget(mountDir, mountPath);
+    if (!safeMountPath) {
+        return;
+    }
+    const safeSourcePath = resolveVerifiedFilePath(sourceRoot, sourcePath);
+    if (!safeSourcePath) {
+        return;
+    }
+    copyFileSync(safeSourcePath, safeMountPath);
+    if (isPathMatched(relativePath, readonlyMatcher)) {
+        chmodSync(safeMountPath, 0o444);
+        return;
+    }
+    const mode = sourceMode ?? statSync(safeSourcePath).mode;
+    chmodSync(safeMountPath, mode & 0o777);
+}
+function ensureDirectory(pathValue) {
+    mkdirSync(pathValue, { recursive: true });
+}
+function ensureDirectoryWithinRoot(rootPath, dirPath) {
+    if (!isPathWithinRoot(dirPath, rootPath)) {
+        return false;
+    }
+    try {
+        ensureDirectory(dirPath);
+        const realDir = realpathSync(dirPath);
+        return isPathWithinRoot(realDir, rootPath);
+    }
+    catch {
+        return false;
+    }
+}
+function listFiles(baseDir) {
+    const files = [];
+    const stack = [baseDir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(entryPath);
+            }
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                files.push(entryPath);
+            }
+        }
+    }
+    return files;
+}
+function normalizeRelativePosix(filePath) {
+    return filePath.split(path.sep).join('/');
+}
+function createPathMatcher(patterns) {
+    return ignore().add(patterns.map((pattern) => pattern.trim()).filter((pattern) => pattern !== '' && !pattern.startsWith('#')));
+}
+function isPathMatched(relPath, matcher, isDirectory = false) {
+    const normalized = normalizeRelativePosix(relPath);
+    return matcher.ignores(normalized) || (isDirectory && matcher.ignores(`${normalized}/`));
+}
+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);
+    }
+    catch {
+        return false;
+    }
+}
+function syncMountedFileBack(sourceFile, mountDir, projectDir, readonlyMatcher, ignoredMatcher) {
+    const relative = resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher);
+    if (!relative)
+        return 0;
+    const safeTargetPath = resolveVerifiedSyncTarget(projectDir, relative);
+    if (!safeTargetPath)
+        return 0;
+    if (existsSync(safeTargetPath) && hasSameContent(sourceFile, safeTargetPath)) {
+        return 0;
+    }
+    copyFileSync(sourceFile, safeTargetPath);
+    return 1;
+}
+function resolveSyncRelativePath(sourceFile, mountDir, readonlyMatcher, ignoredMatcher) {
+    const relative = path.relative(mountDir, sourceFile);
+    if (relative === '' || relative.startsWith('..'))
+        return null;
+    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;
+    try {
+        if (lstatSync(sourceFile).isSymbolicLink())
+            return null;
+        const realSource = realpathSync(sourceFile);
+        if (!isPathWithinRoot(realSource, mountDir))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return relative;
+}
+function resolveVerifiedSyncTarget(projectDir, relativePath) {
+    const targetPath = path.resolve(projectDir, relativePath);
+    if (!isPathWithinRoot(targetPath, projectDir))
+        return null;
+    const safeTargetPath = resolveSafeCopyTarget(projectDir, targetPath);
+    if (!safeTargetPath || !existsSync(safeTargetPath)) {
+        return safeTargetPath;
+    }
+    try {
+        const targetStat = lstatSync(safeTargetPath);
+        if (targetStat.isSymbolicLink())
+            return null;
+        const realTarget = realpathSync(safeTargetPath);
+        return isPathWithinRoot(realTarget, projectDir) ? safeTargetPath : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isExcludedPath(relativePath, excludeSet) {
+    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);
+    });
+}
+function isPathWithinRoot(candidatePath, rootPath) {
+    const resolvedCandidate = path.resolve(candidatePath);
+    const resolvedRoot = path.resolve(rootPath);
+    return resolvedCandidate === resolvedRoot || resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`);
+}
+function resolveSafeCopyTarget(rootPath, candidatePath) {
+    if (!isPathWithinRoot(candidatePath, rootPath)) {
+        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 {
+        return null;
+    }
+}
+function resolveVerifiedFilePath(rootPath, candidatePath) {
+    try {
+        const realCandidate = realpathSync(candidatePath);
+        const candidateStat = statSync(candidatePath);
+        if (!candidateStat.isFile()) {
+            return null;
+        }
+        return isPathWithinRoot(realCandidate, rootPath) ? realCandidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+function removeMountDir(mountDir) {
+    if (!existsSync(mountDir)) {
+        return;
+    }
+    try {
+        rmSync(mountDir, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+}
+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 a mounted mirror of the project directory.
+File access is controlled by project-local .agentignore and .agentreadonly.
+
+## Read-only files (cannot be modified)
+${readonlyList}
+
+## Hidden files (not available in this workspace)
+${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 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}`;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@relayfile/local-mount",
+  "version": "0.1.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",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ignore": "^7.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentWorkforce/relayfile",
+    "directory": "packages/local-mount"
+  },
+  "license": "MIT",
+  "keywords": [
+    "relayfile",
+    "mount",
+    "symlink",
+    "agent",
+    "sandbox",
+    "agentignore",
+    "agentreadonly"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}