@mod-computer/cli 0.1.0 → 0.2.1

package/dist/daemon/file-sync.js

@@ -0,0 +1,985 @@
+// glassware[type="implementation", id="cli-file-sync--2133c3ea", requirements="requirement-cli-files-app-2--6765b2c1,requirement-cli-files-app-3--552aece6,requirement-cli-files-app-4--c5ef157e,requirement-cli-files-app-5--89893346,requirement-cli-files-folder-4--4a430204,requirement-cli-files-folder-5--5eeb9173"]
+// glassware[type="implementation", id="impl-file-sync-distributed--049867a6", specifications="specification-spec-explicit-find--6f6cb47d,specification-spec-workspace-first--957d888f,specification-spec-load-all-files--ce785102,specification-spec-write-to-filesystem--e5c4ecac,specification-spec-file-watch--ec0b56ec,specification-spec-file-to-doc--00985bce,specification-spec-doc-to-file--2cfa261a"]
+// glassware[type="implementation", id="impl-file-sync-content-hash--864987f0", requirements="requirement-cli-sync-content-hash--cc8aff1f"]
+// glassware[type="implementation", id="impl-file-sync-conflict--f8fde34d", requirements="requirement-cli-sync-conflict-lww--626f73f4,requirement-cli-sync-conflict-log--7ac92a94"]
+// glassware[type="implementation", id="impl-file-sync-branch--a4e5b6c7", specifications="specification-spec-apply-override--5ca6c6cb,specification-spec-resolve-file--abf4f572,specification-spec-get-tree--0de14051,specification-spec-cow-inherit--35d6d54a,specification-spec-cow-automatic--2f90e325"]
+/**
+ * File sync service - syncs local files to workspace Automerge documents.
+ * Creates hierarchical folder structure matching local directory structure.
+ * Supports bidirectional sync: local→remote and remote→local.
+ *
+ * Features:
+ * - Content hash: Skip syncing unchanged files
+ * - Conflict resolution: Last-write-wins with conflict logging
+ */
+import fs from 'fs';
+import path from 'path';
+import { createModWorkspace, detectMimeType, shouldIgnore, getTextContent, setTextContent, GitBranchService, mimeTypeToCanvasType } from '@mod/mod-core';
+import { addWorkspaceToSharePolicy, addFilesToSharePolicy, addFileToSharePolicy, removeFileFromSharePolicy } from './share-policy.js';
+import { computeContentHash } from './content-hash.js';
+import { ConflictResolver } from './conflict-resolution.js';
+// glassware[type="implementation", id="impl-file-sync-binary-size--ce349854", requirements="requirement-cli-sync-content-binary--5f017e47"]
+const MAX_INLINE_BINARY_SIZE = 5 * 1024 * 1024; // 5MB
+// Timeout for pending writes - how long to ignore chokidar events after a remote write
+const PENDING_WRITE_TIMEOUT_MS = 2000;
+// Text-syncable MIME type prefixes
+const TEXT_MIME_PREFIXES = [
+    'text/',
+    'application/json',
+    'application/javascript',
+    'application/typescript',
+    'application/xml',
+    'application/yaml',
+    'application/x-yaml',
+];
+/**
+ * Initialize file sync context for a workspace connection.
+ */
+export async function createFileSyncContext(repo, connection, gitBranch, log = console.log) {
+    const modWorkspace = createModWorkspace(repo);
+    const workspace = await modWorkspace.openWorkspace(connection.workspaceId);
+    // Initialize git integration if this is a git repo
+    // Use GitBranchService for initialization, then workspace.gitBranch for operations
+    let gitBranchService = null;
+    if (gitBranch) {
+        try {
+            // Initialize git state via GitBranchService (one-time setup)
+            gitBranchService = new GitBranchService(repo);
+            await gitBranchService.ensureGitState(connection.workspaceId, {
+                seedBranch: gitBranch,
+                defaultBranch: gitBranch
+            });
+            // glassware[type="implementation", id="impl-cli-acknowledge--c13c825c", specifications="specification-spec-acknowledge--de7ee6ef"]
+            // Record branch detection via workspace.gitBranch API (RFC 0003)
+            const clientId = connection.workspaceId.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 20);
+            const sourceId = `cli:${clientId}`;
+            await workspace.gitBranch.acknowledge(sourceId, gitBranch);
+            log(`[file-sync] Git integration enabled for branch: ${gitBranch}`);
+        }
+        catch (error) {
+            log(`[file-sync] Failed to initialize git state: ${error?.message || error}`);
+            gitBranchService = null;
+        }
+    }
+    // Build folder cache from existing folders
+    const folderCache = new Map();
+    const existingFolders = await workspace.folder.list();
+    const existingFolderDocIds = [];
+    for (const folder of existingFolders) {
+        if (folder.path) {
+            folderCache.set(folder.path, folder.id);
+        }
+        // Add both logical ID and documentId to share policy
+        existingFolderDocIds.push(folder.id);
+        if (folder.documentId) {
+            existingFolderDocIds.push(folder.documentId);
+        }
+    }
+    // Register workspace with sharePolicy
+    addWorkspaceToSharePolicy(connection.workspaceId);
+    // Register existing folders with sharePolicy
+    if (existingFolderDocIds.length > 0) {
+        addFilesToSharePolicy(existingFolderDocIds);
+        log(`[file-sync] Added ${existingFolders.length} existing folders to share policy`);
+    }
+    // Build file path caches - forward (path -> docId) and reverse (docId -> path)
+    const filePathCache = new Map();
+    const docIdToPathCache = new Map();
+    const existingFiles = await workspace.file.list();
+    // Register existing file IDs with sharePolicy
+    const existingFileIds = existingFiles.map(f => f.id);
+    if (existingFileIds.length > 0) {
+        addFilesToSharePolicy(existingFileIds);
+    }
+    for (const fileRef of existingFiles) {
+        try {
+            const handle = await workspace.file.get(fileRef.id);
+            if (handle) {
+                const doc = handle.doc();
+                // Try to get path from multiple locations:
+                // 1. doc.metadata.path (CLI-created files)
+                // 2. doc.path (legacy)
+                // 3. fileRef.path (workspace reference)
+                // 4. fileRef.name (fallback to filename only)
+                const filePath = doc?.metadata?.path ||
+                    doc?.path ||
+                    fileRef?.path ||
+                    fileRef?.name ||
+                    null;
+                if (filePath && typeof filePath === 'string') {
+                    filePathCache.set(filePath, fileRef.id);
+                    docIdToPathCache.set(fileRef.id, filePath);
+                    log(`[file-sync] Cached file: ${fileRef.id} -> ${filePath}`);
+                }
+                else {
+                    log(`[file-sync] No path found for file: ${fileRef.id} (name: ${fileRef?.name || 'unknown'})`);
+                }
+            }
+        }
+        catch (error) {
+            // Skip files we can't load
+        }
+    }
+    // 3. Map NEW files to current git branch (only files not already in branch tree)
+    // Skip files that are inherited from parent branches to avoid incorrectly marking them as overrides
+    if (gitBranch && filePathCache.size > 0) {
+        let mappedCount = 0;
+        let skippedInherited = 0;
+        // Get the current branch tree to check which files already exist
+        const branchTree = await workspace.gitBranch.listTree({ branch: gitBranch });
+        const existingPaths = new Set([
+            ...Object.keys(branchTree.overrides ?? {}),
+            ...Object.keys(branchTree.inherited ?? {})
+        ]);
+        for (const [relativePath, docId] of filePathCache.entries()) {
+            // Skip .git directory files - they shouldn't be in the branch tree
+            if (relativePath.startsWith('.git/') || relativePath === '.git') {
+                continue;
+            }
+            // Skip files that already exist in the branch tree (either as override or inherited)
+            // This prevents incorrectly marking inherited files as overrides
+            if (existingPaths.has(relativePath)) {
+                skippedInherited++;
+                continue;
+            }
+            try {
+                await workspace.gitBranch.applyOverride(gitBranch, relativePath, docId);
+                mappedCount++;
+            }
+            catch (error) {
+                // Silently skip - file may already be mapped
+            }
+        }
+        log(`[file-sync] Mapped ${mappedCount} new files to branch: ${gitBranch} (skipped ${skippedInherited} existing, ${filePathCache.size - mappedCount - skippedInherited} .git files)`);
+    }
+    return {
+        repo,
+        connection,
+        workspace,
+        gitBranch,
+        gitBranchService,
+        folderCache,
+        filePathCache,
+        docIdToPathCache,
+        pendingWrites: new Map(),
+        subscriptionCleanups: [],
+        log,
+        contentHashCache: new Map(),
+        lastSyncCache: new Map(),
+        conflictResolver: new ConflictResolver(log),
+    };
+}
+/**
+ * Check if a file is text-based (syncable as text content).
+ */
+function isTextFile(mimeType) {
+    return TEXT_MIME_PREFIXES.some(prefix => mimeType.startsWith(prefix));
+}
+// glassware[type="implementation", id="impl-file-sync-binary-skip--a894dca3", requirements="requirement-cli-sync-binary-skip-limit--9b0b0cef"]
+function shouldSkipLargeBinary(isText, size, relativePath, log) {
+    if (isText || size <= MAX_INLINE_BINARY_SIZE)
+        return false;
+    log(`[file-sync] Skipping large binary file (${size} bytes): ${relativePath}`);
+    return true;
+}
+/**
+ * Normalize a file path to forward slashes (for cross-platform consistency).
+ */
+function normalizePath(absolutePath, connectionRoot) {
+    const relative = path.relative(connectionRoot, absolutePath);
+    return relative.split(path.sep).join('/');
+}
+/**
+ * Get the parent folder path from a file path.
+ */
+function getParentPath(relativePath) {
+    const parts = relativePath.split('/');
+    parts.pop(); // Remove filename
+    return parts.length > 0 ? parts.join('/') : null;
+}
+/**
+ * Get directory components from a file path.
+ */
+function getDirectoryParts(relativePath) {
+    const parts = relativePath.split('/');
+    parts.pop(); // Remove filename
+    return parts;
+}
+/**
+ * Ensure folder hierarchy exists for a file path.
+ * Creates folders as needed with proper parent-child relationships.
+ * Returns the containing folder's logical ID.
+ */
+async function ensureFolderHierarchy(ctx, relativePath) {
+    const dirParts = getDirectoryParts(relativePath);
+    if (dirParts.length === 0) {
+        return null; // File is in root
+    }
+    let currentPath = '';
+    let parentFolderId = null;
+    let folderId = null;
+    for (const folderName of dirParts) {
+        currentPath = currentPath ? `${currentPath}/${folderName}` : folderName;
+        // Check cache first
+        const cachedId = ctx.folderCache.get(currentPath);
+        if (cachedId) {
+            parentFolderId = cachedId;
+            folderId = cachedId;
+            continue;
+        }
+        // Create folder with parent relationship
+        const folderRef = await ctx.workspace.folder.create(currentPath, {
+            name: folderName,
+            parentFolderId: parentFolderId, // Set parent for nested folders
+        });
+        // Cache the new folder
+        ctx.folderCache.set(currentPath, folderRef.id);
+        // CRITICAL: Add BOTH the logical ID and documentId to share policy
+        // The logical ID is used for folder operations, documentId for sync
+        ctx.log(`[file-sync] Created folder: ${currentPath} (id: ${folderRef.id}, docId: ${folderRef.documentId})`);
+        addFileToSharePolicy(folderRef.id);
+        if (folderRef.documentId) {
+            addFileToSharePolicy(folderRef.documentId);
+        }
+        // Update parent for next iteration
+        parentFolderId = folderRef.id;
+        folderId = folderRef.id;
+    }
+    return folderId;
+}
+/**
+ * Handle file creation - create FileDocument and add to folder hierarchy.
+ */
+export async function handleFileCreate(ctx, absolutePath) {
+    const relativePath = normalizePath(absolutePath, ctx.connection.path);
+    const fileName = path.basename(absolutePath);
+    // Check if file already exists in cache
+    if (ctx.filePathCache.has(relativePath)) {
+        // File already synced, treat as change
+        return handleFileChange(ctx, absolutePath);
+    }
+    // Read file content
+    let rawContent;
+    try {
+        rawContent = fs.readFileSync(absolutePath);
+    }
+    catch (error) {
+        if (error.code === 'EACCES') {
+            console.log(`[file-sync] Permission denied: ${relativePath}`);
+            return;
+        }
+        throw error;
+    }
+    const mimeType = detectMimeType(fileName, rawContent);
+    const isText = isTextFile(mimeType);
+    if (shouldSkipLargeBinary(isText, rawContent.length, relativePath, ctx.log)) {
+        return;
+    }
+    // Ensure folder hierarchy exists - returns folder's logical ID
+    const folderId = await ensureFolderHierarchy(ctx, relativePath);
+    const now = new Date().toISOString();
+    const textContent = isText ? rawContent.toString('utf-8') : '';
+    const canvasType = mimeTypeToCanvasType(mimeType);
+    const isCodeFile = canvasType === 'code';
+    // Create file document matching web app's expected structure
+    // Code files: Store plain text directly (no prosemirror formatting)
+    // Text/markdown files: Create with empty text first, then apply setTextContent for proper formatting
+    // Binary files: { binary: base64, metadata: {...} }
+    const fileData = isText
+        ? {
+            text: isCodeFile ? textContent : '', // Code files get content directly, text files use setTextContent
+            metadata: {
+                type: 'text',
+                name: fileName,
+                description: `Synced from ${relativePath}`,
+                createdAt: now,
+                updatedAt: now,
+                path: relativePath,
+                mimeType,
+                size: rawContent.length,
+                gitBranch: ctx.gitBranch,
+                createdBy: 'cli',
+            },
+        }
+        : {
+            binary: rawContent.toString('base64'),
+            metadata: {
+                type: 'binary',
+                name: fileName,
+                description: `Synced from ${relativePath}`,
+                createdAt: now,
+                updatedAt: now,
+                path: relativePath,
+                mimeType,
+                size: rawContent.length,
+                gitBranch: ctx.gitBranch,
+                createdBy: 'cli',
+            },
+        };
+    const fileHandle = await ctx.workspace.file.create(fileData, {
+        name: fileName,
+        mimeType,
+        folderId: folderId ? folderId : undefined,
+    });
+    // Apply proper richtext formatting for text/markdown files using setTextContent
+    // This converts markdown to automerge-prosemirror spans/marks format
+    // Code files should NOT use setTextContent - they need plain text for CodeMirror
+    if (isText && !isCodeFile && textContent.length > 0) {
+        await setTextContent(fileHandle, ['text'], textContent);
+    }
+    // Wait for document to sync to server
+    // The sync server needs time to:
+    // 1. Receive the workspace update with fileRef
+    // 2. Subscribe to the new file document
+    // 3. Request and receive the file content from CLI
+    console.log(`[file-sync] Waiting for document sync: ${fileHandle.documentId}`);
+    // Trigger a find() to ensure the document is in the repo's handles
+    // This can help the sync protocol recognize the document
+    try {
+        const docHandle = await ctx.repo.find(fileHandle.documentId);
+        if (docHandle) {
+            // Wait for the document to have heads (meaning it has content)
+            let attempts = 0;
+            const maxAttempts = 20; // 20 * 200ms = 4 seconds max
+            while (attempts < maxAttempts) {
+                const heads = docHandle.heads();
+                if (heads && heads.length > 0) {
+                    console.log(`[file-sync] Document has heads after ${attempts * 200}ms: ${heads[0]?.slice(0, 12)}`);
+                    break;
+                }
+                await new Promise(resolve => setTimeout(resolve, 200));
+                attempts++;
+            }
+        }
+    }
+    catch (error) {
+        console.log(`[file-sync] Could not verify document sync: ${error}`);
+    }
+    // Additional wait for network propagation
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    // Cache the new file
+    ctx.filePathCache.set(relativePath, fileHandle.documentId);
+    ctx.docIdToPathCache.set(fileHandle.documentId, relativePath);
+    // Register file with sharePolicy
+    addFileToSharePolicy(fileHandle.documentId);
+    // Also register folder if it was created
+    if (folderId) {
+        addFileToSharePolicy(folderId);
+    }
+    // Map file to current git branch via workspace.gitBranch API (RFC 0003)
+    if (ctx.gitBranch && !relativePath.startsWith('.git/') && relativePath !== '.git') {
+        try {
+            ctx.log(`[file-sync] Applying override: branch=${ctx.gitBranch}, path=${relativePath}, docId=${fileHandle.documentId}`);
+            await ctx.workspace.gitBranch.applyOverride(ctx.gitBranch, relativePath, fileHandle.documentId);
+            ctx.log(`[file-sync] Override applied successfully: ${relativePath}`);
+        }
+        catch (error) {
+            ctx.log(`[file-sync] Failed to apply override: ${relativePath} - ${error?.message || error}`);
+        }
+    }
+    else {
+        ctx.log(`[file-sync] Skipping applyOverride: gitBranch=${ctx.gitBranch}, path=${relativePath}`);
+    }
+    console.log(`[file-sync] Created: ${relativePath} (id: ${fileHandle.documentId})`);
+}
+/**
+ * Handle file change - update existing FileDocument.
+ * Uses content hash to skip syncing unchanged files.
+ * Implements copy-on-write for inherited files (spec-cow-first-edit--wip).
+ */
+// glassware[type="implementation", id="impl-file-change-cow--0a222408", specifications="specification-spec-cow-first-edit--08a99329,specification-spec-cow-transparent--15f0b363"]
+export async function handleFileChange(ctx, absolutePath) {
+    const relativePath = normalizePath(absolutePath, ctx.connection.path);
+    const fileName = path.basename(absolutePath);
+    // Read file content
+    let rawContent;
+    try {
+        rawContent = fs.readFileSync(absolutePath);
+    }
+    catch (error) {
+        if (error.code === 'EACCES') {
+            ctx.log(`[file-sync] Permission denied: ${relativePath}`);
+            return;
+        }
+        if (error.code === 'ENOENT') {
+            // File was deleted before we could read it
+            return;
+        }
+        throw error;
+    }
+    const mimeType = detectMimeType(fileName, rawContent);
+    const isText = isTextFile(mimeType);
+    if (shouldSkipLargeBinary(isText, rawContent.length, relativePath, ctx.log)) {
+        return;
+    }
+    // Check content hash - skip if unchanged
+    const newHash = computeContentHash(rawContent);
+    const existingHash = ctx.contentHashCache.get(relativePath);
+    if (existingHash && existingHash === newHash) {
+        ctx.log(`[file-sync] Skipping unchanged file (hash match): ${relativePath}`);
+        return;
+    }
+    // Check cache for existing file
+    let existingFileId = ctx.filePathCache.get(relativePath);
+    if (!existingFileId) {
+        // File doesn't exist in cache, create it
+        // Remove from cache first to avoid infinite loop
+        ctx.filePathCache.delete(relativePath);
+        return handleFileCreate(ctx, absolutePath);
+    }
+    // BD-8: Check if file needs copy-on-write (inherited from parent branch)
+    if (ctx.gitBranch && !relativePath.startsWith('.git/') && relativePath !== '.git') {
+        try {
+            const cowResult = await ctx.workspace.gitBranch.checkCopyOnWrite(relativePath, { branch: ctx.gitBranch });
+            if (cowResult.needsCopyOnWrite && cowResult.sourceDocId) {
+                ctx.log(`[file-sync] Copy-on-write needed for inherited file: ${relativePath}`);
+                // Create a new document with the updated content
+                const parentDir = path.dirname(relativePath);
+                const folderId = await ensureFolderHierarchy(ctx, relativePath);
+                const textContent = isText ? rawContent.toString('utf-8') : '';
+                const cowCanvasType = mimeTypeToCanvasType(mimeType);
+                const cowIsCodeFile = cowCanvasType === 'code';
+                // Code files: Store plain text directly
+                // Text/markdown files: Create with empty text, then apply setTextContent
+                const fileData = isText
+                    ? { text: cowIsCodeFile ? textContent : '' }
+                    : { binary: rawContent.toString('base64') };
+                const newFileHandle = await ctx.workspace.file.create({
+                    ...fileData,
+                    metadata: {
+                        path: relativePath,
+                        mimeType,
+                        size: rawContent.length,
+                        gitBranch: ctx.gitBranch,
+                        createdBy: 'cli',
+                        contentHash: newHash,
+                    },
+                }, {
+                    name: fileName,
+                    mimeType,
+                    folderId: folderId ? folderId : undefined,
+                });
+                // Apply proper richtext formatting for text/markdown files only (not code files)
+                if (isText && !cowIsCodeFile && textContent.length > 0) {
+                    await setTextContent(newFileHandle, ['text'], textContent);
+                }
+                // Apply the override to track the branch-specific document
+                await ctx.workspace.gitBranch.applyOverride(ctx.gitBranch, relativePath, newFileHandle.documentId);
+                // Update caches with new document
+                ctx.filePathCache.set(relativePath, newFileHandle.documentId);
+                ctx.docIdToPathCache.delete(existingFileId);
+                ctx.docIdToPathCache.set(newFileHandle.documentId, relativePath);
+                existingFileId = newFileHandle.documentId;
+                // Register with sharePolicy
+                addFileToSharePolicy(newFileHandle.documentId);
+                ctx.log(`[file-sync] Copy-on-write complete: ${relativePath} -> ${newFileHandle.documentId}`);
+                // Update caches
+                ctx.contentHashCache.set(relativePath, newHash);
+                ctx.lastSyncCache.set(relativePath, new Date().toISOString());
+                return; // Done - new document created with content
+            }
+        }
+        catch (error) {
+            ctx.log(`[file-sync] Copy-on-write check failed: ${error?.message || error}`);
+            // Fall through to normal update
+        }
+    }
+    // Update file content
+    const now = new Date().toISOString();
+    const updateCanvasType = mimeTypeToCanvasType(mimeType);
+    const updateIsCodeFile = updateCanvasType === 'code';
+    if (isText) {
+        const textContent = rawContent.toString('utf-8');
+        const handle = await ctx.workspace.file.get(existingFileId);
+        if (handle) {
+            if (updateIsCodeFile) {
+                // Code files: Use simple text update (no prosemirror formatting)
+                await ctx.workspace.file.update(existingFileId, {
+                    text: textContent,
+                    metadata: {
+                        updatedAt: now,
+                        size: rawContent.length,
+                        contentHash: newHash,
+                    },
+                });
+                ctx.log(`[file-sync] Updated (code): ${relativePath}`);
+            }
+            else {
+                // Text/markdown files: Use setTextContent for automerge-prosemirror format
+                await setTextContent(handle, ['text'], textContent);
+                // Update metadata separately with content hash
+                await ctx.workspace.file.update(existingFileId, {
+                    metadata: {
+                        updatedAt: now,
+                        size: rawContent.length,
+                        contentHash: newHash,
+                    },
+                });
+                ctx.log(`[file-sync] Updated (richtext): ${relativePath}`);
+            }
+        }
+        else {
+            ctx.log(`[file-sync] Could not get handle for: ${relativePath}`);
+        }
+    }
+    else {
+        // Binary files use simple update
+        await ctx.workspace.file.update(existingFileId, {
+            binary: rawContent.toString('base64'),
+            metadata: {
+                updatedAt: now,
+                size: rawContent.length,
+                contentHash: newHash,
+            },
+        });
+        ctx.log(`[file-sync] Updated (binary): ${relativePath}`);
+    }
+    // Update caches
+    ctx.contentHashCache.set(relativePath, newHash);
+    ctx.lastSyncCache.set(relativePath, now);
+}
+/**
+ * Handle file deletion - soft-delete FileDocument.
+ * For branch-scoped files, marks as deleted on the current branch (spec-mark-deleted--wip).
+ */
+// glassware[type="implementation", id="impl-file-delete-branch--caf49639", specifications="specification-spec-mark-deleted--4b162505"]
+export async function handleFileDelete(ctx, absolutePath) {
+    const relativePath = normalizePath(absolutePath, ctx.connection.path);
+    // Check cache for existing file
+    const existingFileId = ctx.filePathCache.get(relativePath);
+    if (!existingFileId) {
+        return; // File wasn't synced
+    }
+    // For git-enabled workspaces, mark the file as deleted on the current branch
+    // This preserves the file on parent branches while hiding it on this branch
+    if (ctx.gitBranch && !relativePath.startsWith('.git/') && relativePath !== '.git') {
+        try {
+            await ctx.workspace.gitBranch.markDeleted(ctx.gitBranch, relativePath);
+            ctx.log(`[file-sync] Marked deleted on branch ${ctx.gitBranch}: ${relativePath}`);
+        }
+        catch (error) {
+            ctx.log(`[file-sync] Could not mark deleted on branch: ${error?.message || error}`);
+        }
+    }
+    // Delete file document
+    await ctx.workspace.file.delete(existingFileId);
+    // Remove from cache
+    ctx.filePathCache.delete(relativePath);
+    ctx.docIdToPathCache.delete(existingFileId);
+    // Remove from sharePolicy
+    removeFileFromSharePolicy(existingFileId);
+    console.log(`[file-sync] Deleted: ${relativePath}`);
+}
+/**
+ * Perform initial sync of all files in connected directory.
+ */
+export async function performInitialSync(ctx, ignorePatterns) {
+    const stats = { synced: 0, skipped: 0 };
+    async function walkDirectory(dirPath) {
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            const relativePath = normalizePath(fullPath, ctx.connection.path);
+            // Check ignore patterns
+            if (shouldIgnore(relativePath, ignorePatterns)) {
+                ctx.log(`[initial-sync] Skipping ignored: ${relativePath}`);
+                stats.skipped++;
+                continue;
+            }
+            if (entry.isDirectory()) {
+                ctx.log(`[initial-sync] Entering directory: ${relativePath}`);
+                await walkDirectory(fullPath);
+            }
+            else if (entry.isFile()) {
+                // Check if file already exists in workspace to prevent duplicates
+                if (ctx.filePathCache.has(relativePath)) {
+                    ctx.log(`[initial-sync] Skipping existing file: ${relativePath}`);
+                    stats.skipped++;
+                    continue;
+                }
+                ctx.log(`[initial-sync] Importing file: ${relativePath}`);
+                try {
+                    await handleFileCreate(ctx, fullPath);
+                    stats.synced++;
+                }
+                catch (error) {
+                    ctx.log(`[initial-sync] Error syncing ${relativePath}: ${error}`);
+                    stats.skipped++;
+                }
+            }
+        }
+    }
+    ctx.log(`[initial-sync] Starting directory walk from ${ctx.connection.path}`);
+    await walkDirectory(ctx.connection.path);
+    ctx.log(`[initial-sync] Directory walk complete: ${stats.synced} synced, ${stats.skipped} skipped`);
+    return stats;
+}
+// shouldIgnore and matchPattern imported from @mod/mod-core
+/**
+ * Check if a file path has a pending write (to avoid circular updates).
+ */
+export function isPendingWrite(ctx, relativePath) {
+    const expiry = ctx.pendingWrites.get(relativePath);
+    if (!expiry)
+        return false;
+    if (Date.now() > expiry) {
+        // Expired, clean up
+        ctx.pendingWrites.delete(relativePath);
+        return false;
+    }
+    return true;
+}
+/**
+ * Mark a file as having a pending write (to avoid circular updates).
+ */
+function markPendingWrite(ctx, relativePath) {
+    ctx.pendingWrites.set(relativePath, Date.now() + PENDING_WRITE_TIMEOUT_MS);
+}
+/**
+ * Write remote file content to local filesystem.
+ * Uses conflict resolution to handle concurrent local/remote edits.
+ * @param ctx File sync context
+ * @param doc The file document from Automerge
+ * @param relativePath The relative path of the file
+ */
+async function writeRemoteFileToFilesystem(ctx, doc, relativePath) {
+    const absolutePath = path.join(ctx.connection.path, relativePath);
+    // Check if file was deleted
+    if (doc.metadata?.deletedAt) {
+        if (fs.existsSync(absolutePath)) {
+            ctx.log(`[file-sync] Remote delete: ${relativePath}`);
+            markPendingWrite(ctx, relativePath);
+            fs.unlinkSync(absolutePath);
+        }
+        return;
+    }
+    // Ensure directory exists
+    const dirPath = path.dirname(absolutePath);
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+    // Determine content - use getTextContent which handles automerge-prosemirror spans
+    let content = null;
+    // Try text content first (handles both plain text and automerge-prosemirror spans)
+    const textContent = getTextContent(doc, ['text']);
+    if (textContent) {
+        content = textContent;
+    }
+    else if (doc.content?.text !== undefined) {
+        // ModFile structure with content.text
+        const nestedTextContent = getTextContent(doc, ['content', 'text']);
+        if (nestedTextContent) {
+            content = nestedTextContent;
+        }
+    }
+    // Binary content
+    if (!content) {
+        if (doc.binary) {
+            content = Buffer.from(doc.binary, 'base64');
+        }
+        else if (doc.content?.binary) {
+            content = Buffer.from(doc.content.binary, 'base64');
+        }
+    }
+    if (content === null) {
+        ctx.log(`[file-sync] No content found for remote file: ${relativePath}`);
+        return;
+    }
+    const remoteContent = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content;
+    const remoteHash = computeContentHash(remoteContent);
+    // Check for conflicts with local file
+    if (fs.existsSync(absolutePath)) {
+        try {
+            const localContent = fs.readFileSync(absolutePath);
+            // If content is identical, skip
+            if (localContent.equals(remoteContent)) {
+                // Update hash cache to track this state
+                ctx.contentHashCache.set(relativePath, remoteHash);
+                return;
+            }
+            // Check for conflict using conflict resolver
+            const localStat = fs.statSync(absolutePath);
+            const localHash = computeContentHash(localContent);
+            const cachedHash = ctx.contentHashCache.get(relativePath);
+            const lastSyncTime = ctx.lastSyncCache.get(relativePath) || '1970-01-01T00:00:00Z';
+            // Build state for conflict resolution
+            const localState = {
+                path: relativePath,
+                modified: cachedHash !== undefined && cachedHash !== localHash, // Changed since last sync
+                localMtime: localStat.mtime.toISOString(),
+                lastSyncedAt: lastSyncTime,
+                contentHash: localHash,
+            };
+            const remoteState = {
+                path: relativePath,
+                updatedAt: doc.metadata?.updatedAt || new Date().toISOString(),
+                contentHash: remoteHash,
+            };
+            // Resolve conflict
+            const { resolution, reason, isConflict } = ctx.conflictResolver.checkAndResolve(localState, remoteState);
+            if (isConflict) {
+                ctx.log(`[file-sync] Conflict detected for ${relativePath}: ${reason}`);
+            }
+            if (resolution === 'use-local') {
+                ctx.log(`[file-sync] Keeping local version: ${relativePath}`);
+                return;
+            }
+            // resolution === 'use-remote', proceed with write
+            ctx.log(`[file-sync] Using remote version: ${relativePath}`);
+        }
+        catch (error) {
+            // Can't read local file, proceed with write
+        }
+    }
+    ctx.log(`[file-sync] Writing remote change: ${relativePath}`);
+    markPendingWrite(ctx, relativePath);
+    if (typeof content === 'string') {
+        fs.writeFileSync(absolutePath, content, 'utf-8');
+    }
+    else {
+        fs.writeFileSync(absolutePath, content);
+    }
+    // Update caches after successful write
+    ctx.contentHashCache.set(relativePath, remoteHash);
+    ctx.lastSyncCache.set(relativePath, new Date().toISOString());
+}
+/**
+ * Subscribe to remote changes for all files in the workspace.
+ * Writes remote changes back to the local filesystem.
+ * Also watches the workspace document for new files added remotely.
+ */
+export async function subscribeToRemoteChanges(ctx) {
+    ctx.log(`[file-sync] Setting up remote change subscriptions...`);
+    // Subscribe to existing files
+    const existingFiles = await ctx.workspace.file.list();
+    const subscribedFileIds = new Set();
+    for (const fileRef of existingFiles) {
+        try {
+            await subscribeToFileChanges(ctx, fileRef.id);
+            subscribedFileIds.add(fileRef.id);
+        }
+        catch (error) {
+            ctx.log(`[file-sync] Failed to subscribe to file ${fileRef.id}: ${error?.message || error}`);
+        }
+    }
+    ctx.log(`[file-sync] Subscribed to ${ctx.subscriptionCleanups.length} file documents`);
+    // Subscribe to workspace document changes to detect new files added remotely
+    await subscribeToWorkspaceChanges(ctx, subscribedFileIds);
+}
+/**
+ * Subscribe to workspace document changes to detect new files added by other clients.
+ * When a new file is detected, subscribe to it and write it to the local filesystem.
+ * Also detects deleted files and removes them from cache.
+ * Uses WorkspaceHandle's built-in subscription API for cleaner abstraction.
+ */
+async function subscribeToWorkspaceChanges(ctx, subscribedFileIds) {
+    ctx.log(`[file-sync] Setting up workspace subscription for new files...`);
+    try {
+        // Use WorkspaceHandle's on() method for file-added events
+        ctx.workspace.on('file-added', async (event) => {
+            const fileId = event.fileId;
+            const fileName = event.fileName;
+            if (!fileId || subscribedFileIds.has(fileId))
+                return;
+            ctx.log(`[file-sync] Detected new remote file: ${fileId} (${fileName || 'unnamed'})`);
+            subscribedFileIds.add(fileId);
+            try {
+                // Subscribe to the new file for future changes
+                await subscribeToFileChanges(ctx, fileId);
+                // Add to sharePolicy
+                addFilesToSharePolicy([fileId]);
+                // Immediately fetch and write the file to local filesystem
+                const fileHandle = await ctx.repo.find(fileId);
+                if (fileHandle) {
+                    await fileHandle.whenReady?.();
+                    const fileDoc = fileHandle.doc?.();
+                    if (fileDoc) {
+                        // Get file path from metadata
+                        const filePath = fileDoc.metadata?.path || fileName;
+                        if (filePath && typeof filePath === 'string') {
+                            // Cache the path mappings
+                            ctx.filePathCache.set(filePath, fileId);
+                            ctx.docIdToPathCache.set(fileId, filePath);
+                            // Write file to local filesystem
+                            ctx.log(`[file-sync] Writing new remote file to local: ${filePath}`);
+                            await writeRemoteFileToFilesystem(ctx, fileDoc, filePath);
+                        }
+                        else {
+                            ctx.log(`[file-sync] No path found for new file ${fileId}`);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                ctx.log(`[file-sync] Failed to process new file ${fileId}: ${error?.message || error}`);
+            }
+        });
+        ctx.log(`[file-sync] ✓ Subscribed to workspace file-added events`);
+        // Subscribe to file-removed events to clean up cache
+        ctx.workspace.on('file-removed', async (event) => {
+            const fileId = event.fileId;
+            ctx.log(`[file-sync] File removed remotely: ${fileId}`);
+            // Remove from tracking sets
+            subscribedFileIds.delete(fileId);
+            // Remove from caches
+            const filePath = ctx.docIdToPathCache.get(fileId);
+            if (filePath) {
+                ctx.filePathCache.delete(filePath);
+                ctx.docIdToPathCache.delete(fileId);
+                ctx.log(`[file-sync] Cleared cache for deleted file: ${filePath}`);
+            }
+            // Remove from share policy
+            removeFileFromSharePolicy(fileId);
+        });
+        // Also subscribe to change events to sync caches
+        ctx.workspace.on('change', (event) => {
+            const currentFileIds = new Set(event.fileRefs.map((f) => f.id));
+            const currentFolderIds = new Set(event.folderRefs.map((f) => f.id));
+            // Detect files that were in cache but no longer in workspace
+            for (const [filePath, fileId] of ctx.filePathCache.entries()) {
+                if (!currentFileIds.has(fileId)) {
+                    ctx.log(`[file-sync] Detected deleted file from cache sync: ${filePath}`);
+                    ctx.filePathCache.delete(filePath);
+                    ctx.docIdToPathCache.delete(fileId);
+                    subscribedFileIds.delete(fileId);
+                    removeFileFromSharePolicy(fileId);
+                }
+            }
+            // Detect folders that were deleted
+            for (const [folderPath, folderId] of ctx.folderCache.entries()) {
+                if (!currentFolderIds.has(folderId)) {
+                    ctx.log(`[file-sync] Detected deleted folder from cache sync: ${folderPath}`);
+                    ctx.folderCache.delete(folderPath);
+                    removeFileFromSharePolicy(folderId);
+                }
+            }
+            ctx.log(`[file-sync] Workspace changed: ${event.fileRefs?.length || 0} files, ${event.folderRefs?.length || 0} folders`);
+        });
+    }
+    catch (error) {
+        ctx.log(`[file-sync] Failed to subscribe to workspace changes: ${error?.message || error}`);
+    }
+}
+// Debounce delay for remote change events (ms)
+const REMOTE_CHANGE_DEBOUNCE_MS = 300;
+/**
+ * Subscribe to changes on a single file document.
+ */
+async function subscribeToFileChanges(ctx, fileId) {
+    // Get the raw Automerge handle
+    const handle = await ctx.repo.find(fileId);
+    if (!handle) {
+        ctx.log(`[file-sync] Could not find handle for ${fileId}`);
+        return;
+    }
+    // Wait for document to be ready
+    await handle.whenReady?.();
+    // Get initial doc info for logging - use cached path if doc doesn't have it
+    const initialDoc = handle.doc?.();
+    const initialPath = initialDoc?.metadata?.path ||
+        initialDoc?.path ||
+        ctx.docIdToPathCache.get(fileId) ||
+        'unknown';
+    ctx.log(`[file-sync] Subscribing to file: ${fileId} (path: ${initialPath})`);
+    // Track debounce timer for this file
+    let debounceTimer = null;
+    // Track if a write is in progress to avoid concurrent writes
+    let writeInProgress = false;
+    const processChange = async () => {
+        if (writeInProgress) {
+            ctx.log(`[file-sync] Write in progress for ${fileId}, scheduling retry`);
+            // Schedule another check after current write completes
+            debounceTimer = setTimeout(processChange, REMOTE_CHANGE_DEBOUNCE_MS);
+            return;
+        }
+        try {
+            // Get fresh document state after debounce
+            const doc = handle.doc?.();
+            if (!doc) {
+                ctx.log(`[file-sync] No doc in change event for ${fileId}`);
+                return;
+            }
+            // Get the relative path - try document metadata first, then fall back to cached path
+            let relativePath = doc.metadata?.path || doc.path;
+            // If not in doc, use the cached path from when we set up subscriptions
+            if (!relativePath || typeof relativePath !== 'string') {
+                relativePath = ctx.docIdToPathCache.get(fileId);
+            }
+            if (!relativePath || typeof relativePath !== 'string') {
+                ctx.log(`[file-sync] No valid path found for ${fileId} (not in doc or cache)`);
+                return;
+            }
+            // Skip if this is a pending write (we just wrote this file)
+            if (isPendingWrite(ctx, relativePath)) {
+                ctx.log(`[file-sync] Skipping pending write for ${relativePath}`);
+                return;
+            }
+            // Write to filesystem
+            ctx.log(`[file-sync] Processing remote change for ${relativePath}`);
+            writeInProgress = true;
+            try {
+                await writeRemoteFileToFilesystem(ctx, doc, relativePath);
+            }
+            finally {
+                writeInProgress = false;
+            }
+        }
+        catch (error) {
+            ctx.log(`[file-sync] Error handling remote change: ${error?.message || error}`);
+            writeInProgress = false;
+        }
+    };
+    const onChange = (payload) => {
+        ctx.log(`[file-sync] Change event received for ${fileId}`);
+        // Debounce: clear existing timer and set a new one
+        // This ensures we process changes after a quiet period, avoiding
+        // processing intermediate states during rapid sync updates
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(processChange, REMOTE_CHANGE_DEBOUNCE_MS);
+    };
+    // Subscribe to changes
+    if (typeof handle.on === 'function') {
+        handle.on('change', onChange);
+        ctx.log(`[file-sync] ✓ Subscribed to change events for ${fileId}`);
+    }
+    else {
+        ctx.log(`[file-sync] ✗ Handle has no .on() method for ${fileId}`);
+    }
+    // Store cleanup function
+    ctx.subscriptionCleanups.push(() => {
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        handle.off?.('change', onChange);
+    });
+}
+/**
+ * Subscribe to a newly created file for remote changes.
+ * Call this after creating a new file document.
+ */
+export async function subscribeToNewFile(ctx, fileId) {
+    try {
+        await subscribeToFileChanges(ctx, fileId);
+    }
+    catch (error) {
+        ctx.log(`[file-sync] Failed to subscribe to new file ${fileId}: ${error?.message || error}`);
+    }
+}
+/**
+ * Cleanup all remote change subscriptions.
+ */
+export function cleanupRemoteSubscriptions(ctx) {
+    ctx.log(`[file-sync] Cleaning up ${ctx.subscriptionCleanups.length} subscriptions...`);
+    for (const cleanup of ctx.subscriptionCleanups) {
+        try {
+            cleanup();
+        }
+        catch (error) {
+            // Ignore cleanup errors
+        }
+    }
+    ctx.subscriptionCleanups = [];
+    ctx.pendingWrites.clear();
+}