framer-code-link 0.1.0

package/src/controller.ts

@@ -0,0 +1,1212 @@
+/**
+ * Controller
+ * Single source of truth for all runtime state and orchestrates the sync lifecycle.
+ *
+ * Helpers are functions that provide data - they never hold control or callbacks.
+ */
+
+import fs from "fs/promises"
+import type { WebSocket } from "ws"
+import type {
+  Config,
+  IncomingMessage,
+  OutgoingMessage,
+  FileInfo,
+  Conflict,
+  WatcherEvent,
+  ConflictVersionData,
+} from "./types.js"
+import { initConnection, sendMessage } from "./helpers/connection.js"
+import { initWatcher } from "./helpers/watcher.js"
+import {
+  listFiles,
+  detectConflicts,
+  writeRemoteFiles,
+  deleteLocalFile,
+  readFileSafe,
+  autoResolveConflicts,
+} from "./helpers/files.js"
+import { Installer } from "./helpers/installer.js"
+import { createHashTracker } from "./utils/hashing.js"
+import { info, warn, error, success, debug } from "./utils/logging.js"
+import { hashFileContent } from "./utils/state-persistence.js"
+import {
+  FileMetadataCache,
+  type FileSyncMetadata,
+} from "./utils/file-metadata-cache.js"
+import { UserActionCoordinator } from "./helpers/user-actions.js"
+import { validateIncomingChange } from "./helpers/sync-validator.js"
+import { findOrCreateProjectDir } from "./utils/project.js"
+
+/**
+ * Explicit sync lifecycle modes
+ */
+export type SyncMode =
+  | "disconnected"
+  | "handshaking"
+  | "snapshot_processing"
+  | "conflict_resolution"
+  | "watching"
+
+/**
+ * Pending operation for echo suppression and replay
+ */
+type PendingOperation =
+  | { id: string; type: "write"; file: string; hash: string }
+  | { id: string; type: "delete"; file: string; previousHash?: string }
+
+/**
+ * Shared state that persists across all lifecycle modes
+ */
+interface SyncStateBase {
+  queuedDiffs: FileInfo[]
+  pendingOperations: Map<string, PendingOperation>
+  nextOperationId: number
+}
+
+type DisconnectedState = SyncStateBase & {
+  mode: "disconnected"
+  socket: null
+}
+
+type HandshakingState = SyncStateBase & {
+  mode: "handshaking"
+  socket: WebSocket
+}
+
+type SnapshotProcessingState = SyncStateBase & {
+  mode: "snapshot_processing"
+  socket: WebSocket
+}
+
+type ConflictResolutionState = SyncStateBase & {
+  mode: "conflict_resolution"
+  socket: WebSocket
+  pendingConflicts: Conflict[]
+}
+
+type WatchingState = SyncStateBase & {
+  mode: "watching"
+  socket: WebSocket
+}
+
+export type SyncState =
+  | DisconnectedState
+  | HandshakingState
+  | SnapshotProcessingState
+  | ConflictResolutionState
+  | WatchingState
+
+/**
+ * Events that drive state transitions
+ */
+type SyncEvent =
+  | {
+      type: "HANDSHAKE"
+      socket: WebSocket
+      projectInfo: { projectId: string; projectName: string }
+    }
+  | { type: "REQUEST_FILES" }
+  | { type: "FILE_LIST"; files: FileInfo[] }
+  | {
+      type: "CONFLICTS_DETECTED"
+      conflicts: Conflict[]
+      safeWrites: FileInfo[]
+      localOnly: FileInfo[]
+    }
+  | { type: "FILE_CHANGE"; file: FileInfo; fileMeta?: FileSyncMetadata }
+  | { type: "REMOTE_FILE_DELETE"; fileName: string }
+  | { type: "REMOTE_DELETE_CONFIRMED"; fileName: string }
+  | { type: "REMOTE_DELETE_CANCELLED"; fileName: string; content: string }
+  | {
+      type: "CONFLICTS_RESOLVED"
+      resolution: "local" | "remote"
+    }
+  | {
+      type: "FILE_SYNCED"
+      fileName: string
+      remoteModifiedAt: number
+    }
+  | { type: "DISCONNECT" }
+  | { type: "WATCHER_EVENT"; event: WatcherEvent }
+  | {
+      type: "CONFLICT_VERSION_RESPONSE"
+      versions: ConflictVersionData[]
+    }
+
+/**
+ * Side effects emitted by transitions
+ */
+type Effect =
+  | {
+      type: "INIT_WORKSPACE"
+      projectInfo: { projectId: string; projectName: string }
+    }
+  | { type: "LOAD_PERSISTED_STATE" }
+  | { type: "SEND_MESSAGE"; payload: OutgoingMessage }
+  | { type: "LIST_LOCAL_FILES" }
+  | { type: "DETECT_CONFLICTS"; remoteFiles: FileInfo[] }
+  | { type: "WRITE_FILES"; files: FileInfo[] }
+  | { type: "DELETE_LOCAL_FILES"; names: string[] }
+  | { type: "REQUEST_CONFLICT_DECISIONS"; conflicts: Conflict[] }
+  | { type: "REQUEST_CONFLICT_VERSIONS"; conflicts: Conflict[] }
+  | {
+      type: "REQUEST_DELETE_CONFIRMATION"
+      fileName: string
+      requireConfirmation: boolean
+    }
+  | {
+      type: "UPDATE_FILE_METADATA"
+      fileName: string
+      remoteModifiedAt: number
+    }
+  | {
+      type: "SEND_LOCAL_CHANGE"
+      fileName: string
+      content: string
+    }
+  | {
+      type: "REQUEST_LOCAL_DELETE_DECISION"
+      fileName: string
+      requireConfirmation: boolean
+    }
+  | { type: "PERSIST_STATE" }
+  | { type: "LOG"; level: "info" | "debug" | "warn"; message: string }
+
+/** One-liner log effect builder */
+function log(level: "info" | "debug" | "warn", message: string): Effect {
+  return { type: "LOG", level, message }
+}
+
+/**
+ * Pure state transition function
+ * Takes current state + event, returns new state + effects to execute
+ */
+function transition(
+  state: SyncState,
+  event: SyncEvent
+): { state: SyncState; effects: Effect[] } {
+  const effects: Effect[] = []
+
+  switch (event.type) {
+    case "HANDSHAKE": {
+      if (state.mode !== "disconnected") {
+        effects.push(
+          log("warn", `Received HANDSHAKE in mode ${state.mode}, ignoring`)
+        )
+        return { state, effects }
+      }
+
+      effects.push(
+        { type: "INIT_WORKSPACE", projectInfo: event.projectInfo },
+        { type: "LOAD_PERSISTED_STATE" },
+        { type: "SEND_MESSAGE", payload: { type: "request-files" } }
+      )
+
+      return {
+        state: {
+          ...state,
+          mode: "handshaking",
+          socket: event.socket,
+        },
+        effects,
+      }
+    }
+
+    case "FILE_SYNCED": {
+      // Remote confirms they received our local change
+      effects.push(log("info", `Remote confirmed sync: ${event.fileName}`), {
+        type: "UPDATE_FILE_METADATA",
+        fileName: event.fileName,
+        remoteModifiedAt: event.remoteModifiedAt,
+      })
+
+      return { state, effects }
+    }
+
+    case "DISCONNECT": {
+      effects.push(
+        { type: "PERSIST_STATE" },
+        log("info", "Disconnected, persisting state")
+      )
+
+      if (state.mode === "conflict_resolution") {
+        const { pendingConflicts: _discarded, ...rest } = state
+        return {
+          state: {
+            ...rest,
+            mode: "disconnected",
+            socket: null,
+          },
+          effects,
+        }
+      }
+
+      return {
+        state: {
+          ...state,
+          mode: "disconnected",
+          socket: null,
+        },
+        effects,
+      }
+    }
+
+    case "REQUEST_FILES": {
+      // Plugin is asking for our local file list
+      // Valid in any mode except disconnected
+      if (state.mode === "disconnected") {
+        effects.push(
+          log("warn", "Received REQUEST_FILES while disconnected, ignoring")
+        )
+        return { state, effects }
+      }
+
+      effects.push(log("info", "Plugin requested file list"), {
+        type: "LIST_LOCAL_FILES",
+      })
+
+      return { state, effects }
+    }
+
+    case "FILE_LIST": {
+      if (state.mode !== "handshaking") {
+        effects.push(
+          log("warn", `Received FILE_LIST in mode ${state.mode}, ignoring`)
+        )
+        return { state, effects }
+      }
+
+      effects.push(
+        log("info", `Received file list: ${event.files.length} files`)
+      )
+
+      // Detect conflicts between remote snapshot and local files
+      effects.push({
+        type: "DETECT_CONFLICTS",
+        remoteFiles: event.files,
+      })
+
+      // Transition to snapshot_processing - conflict detection effect will determine next mode
+      return {
+        state: {
+          ...state,
+          mode: "snapshot_processing",
+          queuedDiffs: event.files,
+        },
+        effects,
+      }
+    }
+
+    case "CONFLICTS_DETECTED": {
+      if (state.mode !== "snapshot_processing") {
+        effects.push(
+          log(
+            "warn",
+            `Received CONFLICTS_DETECTED in mode ${state.mode}, ignoring`
+          )
+        )
+        return { state, effects }
+      }
+
+      const { conflicts, safeWrites, localOnly } = event
+
+      // detectConflicts already did auto-resolution:
+      // - safeWrites = files we can apply (remote-only or local unchanged)
+      // - conflicts = files that need manual resolution (both sides changed)
+      // - localOnly = files to upload
+
+      // Apply safe writes
+      if (safeWrites.length > 0) {
+        effects.push(log("info", `Applying ${safeWrites.length} safe writes`), {
+          type: "WRITE_FILES",
+          files: safeWrites,
+        })
+      }
+
+      // Upload local-only files
+      if (localOnly.length > 0) {
+        effects.push(
+          log("info", `Uploading ${localOnly.length} local-only files`)
+        )
+        for (const file of localOnly) {
+          effects.push({
+            type: "SEND_MESSAGE",
+            payload: {
+              type: "file-change",
+              fileName: file.name,
+              content: file.content,
+            },
+          })
+        }
+      }
+
+      // If potential conflicts remain, request remote version data before surfacing to user
+      if (conflicts.length > 0) {
+        effects.push(
+          log(
+            "warn",
+            `${conflicts.length} conflicts require version verification`
+          ),
+          log(
+            "info",
+            "[CONFLICTS] Requesting remote version data from plugin..."
+          ),
+          { type: "REQUEST_CONFLICT_VERSIONS", conflicts }
+        )
+
+        return {
+          state: {
+            ...state,
+            mode: "conflict_resolution",
+            pendingConflicts: conflicts,
+          },
+          effects,
+        }
+      }
+
+      // No conflicts - transition to watching
+      effects.push(log("info", "Initial sync complete, entering watch mode"), {
+        type: "PERSIST_STATE",
+      })
+
+      return {
+        state: {
+          ...state,
+          mode: "watching",
+          queuedDiffs: [],
+        },
+        effects,
+      }
+    }
+
+    case "FILE_CHANGE": {
+      // Use helper to validate the incoming change
+      const validation = validateIncomingChange(
+        event.file,
+        event.fileMeta,
+        state.mode
+      )
+
+      if (validation.action === "queue") {
+        effects.push(
+          log(
+            "debug",
+            `Queueing file change: ${event.file.name} (${validation.reason})`
+          )
+        )
+
+        return {
+          state: {
+            ...state,
+            queuedDiffs: [...state.queuedDiffs, event.file],
+          },
+          effects,
+        }
+      }
+
+      if (validation.action === "reject") {
+        effects.push(
+          log(
+            "warn",
+            `Rejected file change: ${event.file.name} (${validation.reason})`
+          )
+        )
+        return { state, effects }
+      }
+
+      // Apply the change
+      effects.push(log("info", `Applying remote change: ${event.file.name}`), {
+        type: "WRITE_FILES",
+        files: [event.file],
+      })
+
+      return { state, effects }
+    }
+
+    case "REMOTE_FILE_DELETE": {
+      // Reject if not connected
+      if (state.mode === "disconnected") {
+        effects.push(
+          log("warn", `Rejected delete while disconnected: ${event.fileName}`)
+        )
+        return { state, effects }
+      }
+
+      // Remote deletes should always be applied immediately
+      // (the file is already gone from Framer)
+      effects.push(
+        log("info", `Remote delete applied: ${event.fileName}`),
+        { type: "DELETE_LOCAL_FILES", names: [event.fileName] },
+        { type: "PERSIST_STATE" }
+      )
+
+      return { state, effects }
+    }
+
+    case "REMOTE_DELETE_CONFIRMED": {
+      // User confirmed the delete - apply it
+      effects.push(
+        log("info", `Delete confirmed: ${event.fileName}`),
+        { type: "DELETE_LOCAL_FILES", names: [event.fileName] },
+        { type: "PERSIST_STATE" }
+      )
+
+      return { state, effects }
+    }
+
+    case "REMOTE_DELETE_CANCELLED": {
+      // User cancelled - restore the file
+      effects.push(log("info", `Delete cancelled: ${event.fileName}`))
+      effects.push({
+        type: "WRITE_FILES",
+        files: [
+          {
+            name: event.fileName,
+            content: event.content,
+            modifiedAt: Date.now(),
+          },
+        ],
+      })
+
+      return { state, effects }
+    }
+
+    case "CONFLICTS_RESOLVED": {
+      // Only valid in conflict_resolution mode
+      if (state.mode !== "conflict_resolution") {
+        effects.push(
+          log(
+            "warn",
+            `Received CONFLICTS_RESOLVED in mode ${state.mode}, ignoring`
+          )
+        )
+        return { state, effects }
+      }
+
+      // User picked one resolution for ALL conflicts
+      if (event.resolution === "remote") {
+        // Apply all remote versions
+        const remoteFiles = state.pendingConflicts.map((c) => ({
+          name: c.fileName,
+          content: c.remoteContent,
+          modifiedAt: c.remoteModifiedAt,
+        }))
+
+        effects.push(
+          log("info", `Applying ${remoteFiles.length} remote versions`),
+          { type: "WRITE_FILES", files: remoteFiles }
+        )
+      } else {
+        // Send all local versions
+        effects.push(
+          log(
+            "info",
+            `Applying ${state.pendingConflicts.length} local versions`
+          )
+        )
+        for (const conflict of state.pendingConflicts) {
+          effects.push({
+            type: "SEND_MESSAGE",
+            payload: {
+              type: "file-change",
+              fileName: conflict.fileName,
+              content: conflict.localContent,
+            },
+          })
+        }
+      }
+
+      // All conflicts resolved - transition to watching
+      effects.push(log("info", "All conflicts resolved, entering watch mode"), {
+        type: "PERSIST_STATE",
+      })
+
+      const { pendingConflicts: _discarded, ...rest } = state
+      return {
+        state: {
+          ...rest,
+          mode: "watching",
+        },
+        effects,
+      }
+    }
+
+    case "WATCHER_EVENT": {
+      // Local file system change detected
+      const { kind, relativePath, content } = event.event
+
+      // Only process changes in watching mode
+      if (state.mode !== "watching") {
+        effects.push(
+          log(
+            "debug",
+            `Ignoring watcher event in ${state.mode} mode: ${kind} ${relativePath}`
+          )
+        )
+        return { state, effects }
+      }
+
+      // No socket - skip (will diff on reconnect)
+      if (!state.socket) {
+        effects.push(
+          log(
+            "debug",
+            `Ignoring watcher event (disconnected): ${kind} ${relativePath}`
+          )
+        )
+        return { state, effects }
+      }
+
+      switch (kind) {
+        case "add":
+        case "change": {
+          if (content === undefined) {
+            effects.push(
+              log("warn", `Watcher event missing content: ${relativePath}`)
+            )
+            return { state, effects }
+          }
+
+          effects.push(log("info", `Local change detected: ${relativePath}`))
+          effects.push({
+            type: "SEND_LOCAL_CHANGE",
+            fileName: relativePath,
+            content,
+          })
+          break
+        }
+
+        case "delete": {
+          effects.push(log("info", `Local delete detected: ${relativePath}`), {
+            type: "REQUEST_LOCAL_DELETE_DECISION",
+            fileName: relativePath,
+            requireConfirmation: true, // Will be overridden by config in effect
+          })
+          break
+        }
+      }
+
+      return { state, effects }
+    }
+
+    case "CONFLICT_VERSION_RESPONSE": {
+      if (state.mode !== "conflict_resolution") {
+        effects.push(
+          log(
+            "warn",
+            `Received CONFLICT_VERSION_RESPONSE in mode ${state.mode}, ignoring`
+          )
+        )
+        return { state, effects }
+      }
+
+      const { autoResolvedLocal, autoResolvedRemote, remainingConflicts } =
+        autoResolveConflicts(state.pendingConflicts, event.versions)
+
+      if (autoResolvedLocal.length > 0) {
+        effects.push(
+          log(
+            "info",
+            `[AUTO-RESOLVE] Applying ${autoResolvedLocal.length} local changes`
+          )
+        )
+        for (const conflict of autoResolvedLocal) {
+          effects.push({
+            type: "SEND_LOCAL_CHANGE",
+            fileName: conflict.fileName,
+            content: conflict.localContent,
+          })
+        }
+      }
+
+      if (autoResolvedRemote.length > 0) {
+        effects.push(
+          log(
+            "info",
+            `[AUTO-RESOLVE] Applying ${autoResolvedRemote.length} remote changes`
+          ),
+          {
+            type: "WRITE_FILES",
+            files: autoResolvedRemote.map((conflict) => ({
+              name: conflict.fileName,
+              content: conflict.remoteContent,
+              modifiedAt: conflict.remoteModifiedAt ?? Date.now(),
+            })),
+          }
+        )
+      }
+
+      if (remainingConflicts.length > 0) {
+        effects.push(
+          log(
+            "warn",
+            `[AUTO-RESOLVE] ${remainingConflicts.length} conflicts require user resolution`
+          ),
+          { type: "REQUEST_CONFLICT_DECISIONS", conflicts: remainingConflicts }
+        )
+
+        return {
+          state: {
+            ...state,
+            pendingConflicts: remainingConflicts,
+          },
+          effects,
+        }
+      }
+
+      effects.push(log("info", "[AUTO-RESOLVE] All conflicts auto-resolved!"), {
+        type: "PERSIST_STATE",
+      })
+
+      const { pendingConflicts: _discarded, ...rest } = state
+      return {
+        state: {
+          ...rest,
+          mode: "watching",
+          queuedDiffs: [],
+        },
+        effects,
+      }
+    }
+
+    default: {
+      effects.push(log("warn", `Unhandled event type in transition`))
+      return { state, effects }
+    }
+  }
+}
+
+/**
+ * Effect executor - interprets effects and calls helpers
+ * Returns additional events that should be processed (e.g., CONFLICTS_DETECTED after DETECT_CONFLICTS)
+ */
+async function executeEffect(
+  effect: Effect,
+  context: {
+    config: Config
+    hashTracker: ReturnType<typeof createHashTracker>
+    installer: Installer | null
+    fileMetadataCache: FileMetadataCache
+    userActions: UserActionCoordinator
+    syncState: SyncState
+  }
+): Promise<SyncEvent[]> {
+  const {
+    config,
+    hashTracker,
+    installer,
+    fileMetadataCache,
+    userActions,
+    syncState,
+  } = context
+
+  switch (effect.type) {
+    case "INIT_WORKSPACE": {
+      // Initialize project directory if not already set
+      if (!config.projectDir) {
+        const projectName =
+          config.explicitName ?? effect.projectInfo.projectName
+        config.projectDir = await findOrCreateProjectDir(
+          config.projectHash,
+          projectName,
+          config.explicitDir
+        )
+        config.filesDir = `${config.projectDir}/files`
+        info(`Files directory: ${config.filesDir}`)
+
+        // Create files directory
+        await fs.mkdir(config.filesDir, { recursive: true })
+      }
+      return []
+    }
+
+    case "LOAD_PERSISTED_STATE": {
+      if (config.projectDir) {
+        await fileMetadataCache.initialize(config.projectDir)
+        info(`Loaded persisted metadata for ${fileMetadataCache.size()} files`)
+      }
+      return []
+    }
+
+    case "LIST_LOCAL_FILES": {
+      if (!config.filesDir) {
+        return []
+      }
+
+      // List all local files and send to plugin
+      const files = await listFiles(config.filesDir)
+
+      if (syncState.socket) {
+        await sendMessage(syncState.socket, {
+          type: "file-list",
+          files,
+        })
+      }
+
+      return []
+    }
+
+    case "DETECT_CONFLICTS": {
+      if (!config.filesDir) {
+        return []
+      }
+
+      // Use existing helper to detect conflicts
+      const { conflicts, writes, localOnly } = await detectConflicts(
+        effect.remoteFiles,
+        config.filesDir,
+        { persistedState: fileMetadataCache.getPersistedState() }
+      )
+
+      // Return CONFLICTS_DETECTED event to continue the flow
+      return [
+        {
+          type: "CONFLICTS_DETECTED",
+          conflicts,
+          safeWrites: writes,
+          localOnly,
+        },
+      ]
+    }
+
+    case "SEND_MESSAGE": {
+      if (syncState.socket) {
+        await sendMessage(syncState.socket, effect.payload)
+      }
+      return []
+    }
+
+    case "WRITE_FILES": {
+      if (config.filesDir) {
+        await writeRemoteFiles(
+          effect.files,
+          config.filesDir,
+          hashTracker,
+          installer ?? undefined
+        )
+        for (const file of effect.files) {
+          const remoteTimestamp = file.modifiedAt ?? Date.now()
+          fileMetadataCache.recordRemoteWrite(
+            file.name,
+            file.content,
+            remoteTimestamp
+          )
+        }
+      }
+      return []
+    }
+
+    case "DELETE_LOCAL_FILES": {
+      if (config.filesDir) {
+        for (const fileName of effect.names) {
+          await deleteLocalFile(fileName, config.filesDir, hashTracker)
+          fileMetadataCache.recordDelete(fileName)
+        }
+      }
+      return []
+    }
+
+    case "REQUEST_CONFLICT_DECISIONS": {
+      await userActions.requestConflictDecisions(
+        syncState.socket,
+        effect.conflicts
+      )
+
+      return []
+    }
+
+    case "REQUEST_CONFLICT_VERSIONS": {
+      if (!syncState.socket) {
+        warn("Cannot request conflict versions without active socket")
+        return []
+      }
+
+      const persistedState = fileMetadataCache.getPersistedState()
+      const versionRequests = effect.conflicts.map((conflict) => {
+        const persisted = persistedState.get(conflict.fileName)
+        return {
+          fileName: conflict.fileName,
+          lastSyncedAt: conflict.lastSyncedAt ?? persisted?.timestamp,
+        }
+      })
+
+      info(
+        `[CONFLICTS] Requesting remote version data for ${versionRequests.length} file(s)`
+      )
+
+      await sendMessage(syncState.socket, {
+        type: "conflict-version-request",
+        conflicts: versionRequests,
+      })
+
+      return []
+    }
+
+    case "REQUEST_DELETE_CONFIRMATION": {
+      if (syncState.socket) {
+        // Send delete request to plugin
+        await sendMessage(syncState.socket, {
+          type: "file-delete",
+          fileNames: [effect.fileName],
+          requireConfirmation: effect.requireConfirmation,
+        })
+      }
+      // Response will come via delete-confirmed or delete-cancelled message
+      return []
+    }
+
+    case "UPDATE_FILE_METADATA": {
+      if (!config.filesDir || !config.projectDir) {
+        return []
+      }
+
+      // Read current file content to compute hash
+      const currentContent = await readFileSafe(
+        effect.fileName,
+        config.filesDir
+      )
+
+      if (currentContent !== null) {
+        const contentHash = hashFileContent(currentContent)
+        fileMetadataCache.recordSyncedSnapshot(
+          effect.fileName,
+          contentHash,
+          effect.remoteModifiedAt
+        )
+      }
+
+      return []
+    }
+
+    case "SEND_LOCAL_CHANGE": {
+      // Echo prevention: skip if we just wrote this exact content
+      if (hashTracker.shouldSkip(effect.fileName, effect.content)) {
+        return []
+      }
+
+      try {
+        // Send change to plugin
+        if (syncState.socket) {
+          await sendMessage(syncState.socket, {
+            type: "file-change",
+            fileName: effect.fileName,
+            content: effect.content,
+          })
+        }
+
+        // Only remember hash after successful send (prevents re-sending on failure)
+        hashTracker.remember(effect.fileName, effect.content)
+
+        // Trigger type installer
+        if (installer) {
+          installer.process(effect.fileName, effect.content)
+        }
+      } catch (err) {
+        console.warn(
+          `Failed to push change for ${effect.fileName}, will re-sync on next diff:`,
+          err
+        )
+      }
+
+      return []
+    }
+
+    case "REQUEST_LOCAL_DELETE_DECISION": {
+      // Echo prevention: skip if this is a remote-initiated delete
+      const shouldSkip = hashTracker.shouldSkipDelete(effect.fileName)
+
+      if (shouldSkip) {
+        // Clear the delete marker now that we've caught the echo
+        hashTracker.clearDelete(effect.fileName)
+        return []
+      }
+
+      try {
+        const shouldDelete = await userActions.requestDeleteDecision(
+          syncState.socket,
+          {
+            fileName: effect.fileName,
+            requireConfirmation: !config.dangerouslyAutoDelete,
+          }
+        )
+
+        if (shouldDelete) {
+          hashTracker.forget(effect.fileName)
+          fileMetadataCache.recordDelete(effect.fileName)
+
+          if (syncState.socket) {
+            await sendMessage(syncState.socket, {
+              type: "file-delete",
+              fileNames: [effect.fileName],
+            })
+          }
+        }
+      } catch (err) {
+        console.warn(`Failed to handle deletion for ${effect.fileName}:`, err)
+      }
+
+      return []
+    }
+
+    case "PERSIST_STATE": {
+      await fileMetadataCache.flush()
+      return []
+    }
+
+    case "LOG": {
+      const logFn =
+        effect.level === "info" ? info : effect.level === "warn" ? warn : debug
+      logFn(effect.message)
+      return []
+    }
+  }
+}
+
+/**
+ * Starts the sync controller with the given configuration
+ */
+export async function start(config: Config): Promise<void> {
+  info("🚀 Starting Framer Code Link CLI (Next Gen)")
+  info(`Project: ${config.projectHash}`)
+  info(`Port: ${config.port} (auto-selected from project hash)`)
+
+  // State Initialization
+
+  // Note: We defer project directory creation until handshake if not already set
+  // This allows us to receive the project name from the plugin
+
+  const hashTracker = createHashTracker()
+  const fileMetadataCache = new FileMetadataCache()
+  let installer: Installer | null = null
+
+  // State machine state
+  const syncState: SyncState = {
+    mode: "disconnected",
+    socket: null,
+    queuedDiffs: [],
+    pendingOperations: new Map(),
+    nextOperationId: 1,
+  }
+
+  const userActions = new UserActionCoordinator()
+
+  // State Machine Execution Helper
+  // Process events through state machine and execute effects recursively
+  async function processEvent(event: SyncEvent) {
+    const result = transition(syncState, event)
+    Object.assign(syncState, result.state)
+
+    // Execute all effects and process any follow-up events
+    for (const effect of result.effects) {
+      const followUpEvents = await executeEffect(effect, {
+        config,
+        hashTracker,
+        installer,
+        fileMetadataCache,
+        userActions,
+        syncState,
+      })
+
+      // Recursively process follow-up events
+      for (const followUpEvent of followUpEvents) {
+        await processEvent(followUpEvent)
+      }
+    }
+  }
+
+  // WebSocket Connection
+  const connection = initConnection(config.port)
+
+  // Handle initial handshake
+  connection.on("handshake", async (client: WebSocket, message) => {
+    info("Received handshake from plugin")
+    info(`Project: ${message.projectName} (${message.projectId})`)
+
+    // Validate project hash
+    if (message.projectId !== config.projectHash) {
+      warn(
+        `Project ID mismatch: expected ${config.projectHash}, got ${message.projectId}`
+      )
+      client.close()
+      return
+    }
+
+    // Process handshake through state machine
+    await processEvent({
+      type: "HANDSHAKE",
+      socket: client,
+      projectInfo: {
+        projectId: message.projectId,
+        projectName: message.projectName,
+      },
+    })
+
+    // Initialize installer if needed
+    if (config.projectDir && !installer) {
+      installer = new Installer({ projectDir: config.projectDir })
+      await installer.initialize()
+      // Start file watcher now that we have a directory
+      startWatcher()
+    }
+
+    success("Handshake successful - connection established")
+  })
+
+  // Message Handler
+  async function handleMessage(message: IncomingMessage) {
+    // Ensure project is initialized before handling messages
+    if (!config.projectDir || !installer) {
+      warn("Received message before handshake completed - ignoring")
+      return
+    }
+
+    let event: SyncEvent | null = null
+
+    // Map incoming messages to state machine events
+    switch (message.type) {
+      case "request-files":
+        event = { type: "REQUEST_FILES" }
+        break
+
+      case "file-list":
+        event = { type: "FILE_LIST", files: message.files }
+        break
+
+      case "file-change":
+        event = {
+          type: "FILE_CHANGE",
+          file: {
+            name: message.fileName,
+            content: message.content,
+            modifiedAt: Date.now(),
+          },
+          fileMeta: fileMetadataCache.get(message.fileName),
+        }
+        break
+
+      case "file-delete": {
+        // Remote deletes are always applied immediately (file is already gone from Framer)
+        for (const fileName of message.fileNames) {
+          await processEvent({
+            type: "REMOTE_FILE_DELETE",
+            fileName,
+          })
+        }
+        return
+      }
+
+      case "delete-confirmed": {
+        const unmatched: string[] = []
+
+        for (const fileName of message.fileNames) {
+          const handled = userActions.handleConfirmation(
+            `delete:${fileName}`,
+            true
+          )
+
+          if (!handled) {
+            unmatched.push(fileName)
+          }
+        }
+
+        for (const fileName of unmatched) {
+          await processEvent({ type: "REMOTE_DELETE_CONFIRMED", fileName })
+        }
+
+        return
+      }
+
+      case "delete-cancelled": {
+        for (const file of message.files) {
+          userActions.handleConfirmation(`delete:${file.fileName}`, false)
+
+          await processEvent({
+            type: "REMOTE_DELETE_CANCELLED",
+            fileName: file.fileName,
+            content: file.content ?? "",
+          })
+        }
+
+        return
+      }
+
+      case "file-synced":
+        event = {
+          type: "FILE_SYNCED",
+          fileName: message.fileName,
+          remoteModifiedAt: message.remoteModifiedAt,
+        }
+        break
+
+      case "conflicts-resolved":
+        event = {
+          type: "CONFLICTS_RESOLVED",
+          resolution: message.resolution,
+        }
+        break
+
+      case "conflict-version-response":
+        event = {
+          type: "CONFLICT_VERSION_RESPONSE",
+          versions: message.versions,
+        }
+        break
+
+      default:
+        warn(`Unhandled message type: ${message.type}`)
+        return
+    }
+
+    if (event) {
+      await processEvent(event)
+    }
+  }
+
+  connection.on("message", async (message: IncomingMessage) => {
+    try {
+      await handleMessage(message)
+    } catch (err) {
+      error("Error handling message:", err)
+    }
+  })
+
+  connection.on("disconnect", async () => {
+    warn("Plugin disconnected")
+    await processEvent({ type: "DISCONNECT" })
+    userActions.cleanup()
+    info("Will perform full diff on reconnect")
+  })
+
+  // File Watcher Setup
+  // Note: Watcher will be initialized after handshake when filesDir is set
+
+  let watcher: ReturnType<typeof initWatcher> | null = null
+
+  const startWatcher = () => {
+    if (!config.filesDir || watcher) return
+    watcher = initWatcher(config.filesDir)
+
+    watcher.on("change", async (event) => {
+      await processEvent({ type: "WATCHER_EVENT", event })
+    })
+  }
+
+  // Lifecycle
+
+  info("✓ Controller initialized and ready")
+  info(`Waiting for plugin connection on port ${config.port}...`)
+
+  // Graceful shutdown
+  process.on("SIGINT", async () => {
+    info("\nShutting down gracefully...")
+    if (watcher) {
+      await watcher.close()
+    }
+    connection.close()
+    process.exit(0)
+  })
+}
+
+// Export for testing
+export { transition }