framer-code-link 0.1.0

package/src/helpers/connection.ts

@@ -0,0 +1,95 @@
+/**
+ * WebSocket connection helper
+ *
+ * Thin wrapper around ws.Server that normalizes handshake and surfaces
+ * simple callbacks. Keeps raw socket API localized.
+ */
+
+import { WebSocketServer, WebSocket } from "ws"
+import type { IncomingMessage, OutgoingMessage } from "../types.js"
+import { info, error } from "../utils/logging.js"
+
+export interface ConnectionCallbacks {
+  onHandshake: (
+    client: WebSocket,
+    message: { projectId: string; projectName: string }
+  ) => void
+  onMessage: (message: IncomingMessage) => void
+  onDisconnect: () => void
+}
+
+export interface Connection {
+  on(event: "handshake", handler: ConnectionCallbacks["onHandshake"]): void
+  on(event: "message", handler: ConnectionCallbacks["onMessage"]): void
+  on(event: "disconnect", handler: ConnectionCallbacks["onDisconnect"]): void
+  close(): void
+}
+
+/**
+ * Initializes a WebSocket server and returns a connection interface
+ */
+export function initConnection(port: number): Connection {
+  const wss = new WebSocketServer({ port })
+  const handlers: Partial<ConnectionCallbacks> = {}
+
+  info(`WebSocket server listening on port ${port}`)
+
+  wss.on("connection", (ws: WebSocket) => {
+    info("Client connected")
+
+    ws.on("message", (data: Buffer) => {
+      try {
+        const message = JSON.parse(data.toString()) as IncomingMessage
+
+        // Special handling for handshake
+        if (message.type === "handshake") {
+          handlers.onHandshake?.(ws, message)
+        } else {
+          handlers.onMessage?.(message)
+        }
+      } catch (err) {
+        error("Failed to parse message:", err)
+      }
+    })
+
+    ws.on("close", () => {
+      info("Client disconnected")
+      handlers.onDisconnect?.()
+    })
+
+    ws.on("error", (err) => {
+      error("WebSocket error:", err)
+    })
+  })
+
+  return {
+    on(event: "handshake" | "message" | "disconnect", handler: any): void {
+      if (event === "handshake") {
+        handlers.onHandshake = handler
+      } else if (event === "message") {
+        handlers.onMessage = handler
+      } else if (event === "disconnect") {
+        handlers.onDisconnect = handler
+      }
+    },
+
+    close(): void {
+      wss.close()
+    },
+  }
+}
+
+/**
+ * Sends a message to a connected socket
+ */
+export function sendMessage(
+  socket: WebSocket,
+  message: OutgoingMessage
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    socket.send(JSON.stringify(message), (err) => {
+      if (err) reject(err)
+      else resolve()
+    })
+  })
+}

package/src/helpers/files.test.ts

@@ -0,0 +1,117 @@
+import fs from "fs/promises"
+import os from "os"
+import path from "path"
+import { describe, it, expect } from "vitest"
+import { autoResolveConflicts, detectConflicts } from "./files.js"
+import type { Conflict } from "../types.js"
+import { hashFileContent } from "../utils/state-persistence.js"
+
+function makeConflict(overrides: Partial<Conflict> = {}): Conflict {
+  return {
+    fileName: overrides.fileName ?? "Test.tsx",
+    localContent: overrides.localContent ?? "local",
+    remoteContent: overrides.remoteContent ?? "remote",
+    localModifiedAt: overrides.localModifiedAt ?? Date.now(),
+    remoteModifiedAt: overrides.remoteModifiedAt ?? Date.now(),
+    lastSyncedAt: overrides.lastSyncedAt ?? Date.now(),
+    localClean: overrides.localClean,
+  }
+}
+
+describe("autoResolveConflicts", () => {
+  it("classifies conflicts as local when remote unchanged and local changed", () => {
+    const conflict = makeConflict({
+      lastSyncedAt: 5_000,
+      localClean: false,
+    })
+
+    const result = autoResolveConflicts(
+      [conflict],
+      [{ fileName: conflict.fileName, latestRemoteVersionMs: 5_000 }]
+    )
+
+    expect(result.autoResolvedLocal).toHaveLength(1)
+    expect(result.autoResolvedRemote).toHaveLength(0)
+    expect(result.remainingConflicts).toHaveLength(0)
+  })
+
+  it("classifies conflicts as remote when local is clean and remote changed", () => {
+    const conflict = makeConflict({
+      lastSyncedAt: 5_000,
+      localClean: true,
+    })
+
+    const result = autoResolveConflicts(
+      [conflict],
+      [{ fileName: conflict.fileName, latestRemoteVersionMs: 10_000 }]
+    )
+
+    expect(result.autoResolvedRemote).toHaveLength(1)
+    expect(result.autoResolvedLocal).toHaveLength(0)
+  })
+
+  it("keeps conflicts that have both sides changed", () => {
+    const conflict = makeConflict({
+      lastSyncedAt: 5_000,
+      localClean: false,
+    })
+
+    const result = autoResolveConflicts(
+      [conflict],
+      [{ fileName: conflict.fileName, latestRemoteVersionMs: 7_500 }]
+    )
+
+    expect(result.remainingConflicts).toHaveLength(1)
+    expect(result.autoResolvedLocal).toHaveLength(0)
+    expect(result.autoResolvedRemote).toHaveLength(0)
+  })
+
+  it("keeps conflicts when version data is missing", () => {
+    const conflict = makeConflict({
+      lastSyncedAt: 5_000,
+      localClean: true,
+    })
+
+    const result = autoResolveConflicts([conflict], [])
+
+    expect(result.remainingConflicts).toHaveLength(1)
+  })
+})
+
+describe("detectConflicts", () => {
+  it("marks conflicts as localClean when local matches persisted state", async () => {
+    const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "cl-test-"))
+    try {
+      const filesDir = path.join(tmpRoot, "files")
+      await fs.mkdir(filesDir, { recursive: true })
+
+      const localContent = "local content"
+      await fs.writeFile(path.join(filesDir, "Test.tsx"), localContent, "utf-8")
+
+      const persistedState = new Map([
+        [
+          "Test.tsx",
+          { contentHash: hashFileContent(localContent), timestamp: 1_000 },
+        ],
+      ])
+
+      const result = await detectConflicts(
+        [
+          {
+            name: "Test.tsx",
+            content: "remote content",
+            modifiedAt: 2_000,
+          },
+        ],
+        filesDir,
+        { persistedState }
+      )
+
+      expect(result.writes).toHaveLength(0)
+      expect(result.conflicts).toHaveLength(1)
+      expect(result.conflicts[0]?.localClean).toBe(true)
+    } finally {
+      await fs.rm(tmpRoot, { recursive: true, force: true })
+    }
+  })
+})

package/src/helpers/files.ts

@@ -0,0 +1,378 @@
+/**
+ * File operations helper
+ *
+ * Single place that understands disk + conflicts. Provides:
+ * - listFiles: returns current filesystem state
+ * - detectConflicts: compares remote vs local and returns conflicts + safe writes
+ * - writeRemoteFiles: applies writes/deletes from remote
+ * - deleteLocalFile: removes a file from disk
+ *
+ * Controller decides WHEN to call these, but never computes conflicts itself.
+ */
+
+import fs from "fs/promises"
+import path from "path"
+import type {
+  FileInfo,
+  ConflictResolution,
+  Conflict,
+  ConflictVersionData,
+} from "../types.js"
+import type { HashTracker } from "../utils/hashing.js"
+import { normalizePath, sanitizeFilePath } from "@code-link/shared"
+import { info, warn, debug } from "../utils/logging.js"
+import {
+  hashFileContent,
+  type PersistedFileState,
+} from "../utils/state-persistence.js"
+
+const SUPPORTED_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".json"]
+const DEFAULT_EXTENSION = ".tsx"
+const DEFAULT_REMOTE_DRIFT_MS = 2000
+
+/**
+ * Lists all supported files in the files directory
+ */
+export async function listFiles(filesDir: string): Promise<FileInfo[]> {
+  const files: FileInfo[] = []
+
+  async function walk(currentDir: string): Promise<void> {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const entryPath = path.join(currentDir, entry.name)
+
+      if (entry.isDirectory()) {
+        await walk(entryPath)
+        continue
+      }
+
+      if (!isSupportedExtension(entry.name)) continue
+
+      const relativePath = path.relative(filesDir, entryPath)
+      const normalizedPath = normalizePath(relativePath)
+      // Don't capitalize when listing existing files - preserve their actual names
+      const sanitizedPath = sanitizeFilePath(normalizedPath, false).path
+
+      try {
+        const [content, stats] = await Promise.all([
+          fs.readFile(entryPath, "utf-8"),
+          fs.stat(entryPath),
+        ])
+
+        files.push({
+          name: sanitizedPath,
+          content,
+          modifiedAt: stats.mtimeMs,
+        })
+      } catch (err) {
+        warn(`Failed to read ${entryPath}:`, err)
+      }
+    }
+  }
+
+  try {
+    await walk(filesDir)
+  } catch (err) {
+    warn("Failed to list files:", err)
+  }
+
+  return files
+}
+
+/**
+ * Detects conflicts between remote files and local filesystem
+ * Returns conflicts that need user resolution and safe writes that can be applied
+ */
+export interface ConflictDetectionOptions {
+  preferRemote?: boolean
+  detectConflicts?: boolean
+  persistedState?: Map<string, PersistedFileState>
+}
+
+export async function detectConflicts(
+  remoteFiles: FileInfo[],
+  filesDir: string,
+  options: ConflictDetectionOptions = {}
+): Promise<ConflictResolution> {
+  const conflicts: Conflict[] = []
+  const writes: FileInfo[] = []
+  const localOnly: FileInfo[] = []
+  const detect = options.detectConflicts ?? true
+  const preferRemote = options.preferRemote ?? false
+  const persistedState = options.persistedState
+
+  debug(`Detecting conflicts for ${remoteFiles.length} remote files`)
+
+  // Build a snapshot of all local files
+  const localFiles = await listFiles(filesDir)
+  const localFileMap = new Map(localFiles.map((f) => [f.name, f]))
+
+  // Track which files we've processed
+  const processedFiles = new Set<string>()
+
+  // Process remote files (remote-only or both sides)
+  for (const remote of remoteFiles) {
+    const normalized = resolveRemoteReference(filesDir, remote.name)
+    const local = localFileMap.get(normalized.relativePath)
+    processedFiles.add(normalized.relativePath)
+
+    const persisted = persistedState?.get(normalized.relativePath)
+    const localHash = local ? hashFileContent(local.content) : null
+    const localMatchesPersisted =
+      !!persisted && !!local && localHash === persisted.contentHash
+
+    if (!local) {
+      // Remote-only: download
+      writes.push({
+        name: normalized.relativePath,
+        content: remote.content,
+        modifiedAt: remote.modifiedAt,
+      })
+      continue
+    }
+
+    if (local.content === remote.content) {
+      // No change needed
+      continue
+    }
+
+    if (!detect || preferRemote) {
+      writes.push({
+        name: normalized.relativePath,
+        content: remote.content,
+        modifiedAt: remote.modifiedAt,
+      })
+      continue
+    }
+
+    // Check if local file is "clean" (matches last persisted state)
+    // If so, we can safely overwrite it with remote changes
+    // Both sides have the file with different content -> conflict
+    const localClean = persisted ? localMatchesPersisted : undefined
+    conflicts.push({
+      fileName: normalized.relativePath,
+      localContent: local.content,
+      remoteContent: remote.content,
+      localModifiedAt: local.modifiedAt,
+      remoteModifiedAt: remote.modifiedAt,
+      lastSyncedAt: persisted?.timestamp,
+      localClean,
+    })
+  }
+
+  // Process local-only files (not present in remote)
+  for (const local of localFiles) {
+    if (!processedFiles.has(local.name)) {
+      // Local-only: upload later
+      localOnly.push({
+        name: local.name,
+        content: local.content,
+        modifiedAt: local.modifiedAt,
+      })
+    }
+  }
+
+  return { conflicts, writes, localOnly }
+}
+
+export interface AutoResolveResult {
+  autoResolvedLocal: Conflict[]
+  autoResolvedRemote: Conflict[]
+  remainingConflicts: Conflict[]
+}
+
+export function autoResolveConflicts(
+  conflicts: Conflict[],
+  versions: ConflictVersionData[],
+  options: { remoteDriftMs?: number } = {}
+): AutoResolveResult {
+  const versionMap = new Map(
+    versions.map((version) => [version.fileName, version.latestRemoteVersionMs])
+  )
+  const remoteDriftMs = options.remoteDriftMs ?? DEFAULT_REMOTE_DRIFT_MS
+
+  const autoResolvedLocal: Conflict[] = []
+  const autoResolvedRemote: Conflict[] = []
+  const remainingConflicts: Conflict[] = []
+
+  for (const conflict of conflicts) {
+    const latestRemoteVersionMs = versionMap.get(conflict.fileName)
+    const lastSyncedAt = conflict.lastSyncedAt
+
+    info(`[AUTO-RESOLVE] Checking ${conflict.fileName}...`)
+
+    if (!latestRemoteVersionMs) {
+      info(`-> No remote version data, keeping conflict`)
+      remainingConflicts.push(conflict)
+      continue
+    }
+
+    if (!lastSyncedAt) {
+      info(`-> No last sync timestamp, keeping conflict`)
+      remainingConflicts.push(conflict)
+      continue
+    }
+
+    info(
+      `-> Latest remote: ${new Date(latestRemoteVersionMs).toISOString()} (${latestRemoteVersionMs})`
+    )
+    info(
+      `-> Last synced: ${new Date(lastSyncedAt).toISOString()} (${lastSyncedAt})`
+    )
+
+    const remoteUnchanged =
+      latestRemoteVersionMs <= lastSyncedAt + remoteDriftMs
+    const localClean = conflict.localClean === true
+
+    if (remoteUnchanged && !localClean) {
+      info(`  -> Remote unchanged, local changed. Auto-applying LOCAL.`)
+      autoResolvedLocal.push(conflict)
+    } else if (localClean && !remoteUnchanged) {
+      info(`  -> Local unchanged, remote changed. Auto-applying REMOTE.`)
+      autoResolvedRemote.push(conflict)
+    } else if (remoteUnchanged && localClean) {
+      info(`  -> Both unchanged. Skipping (no conflict).`)
+    } else {
+      info(`  -> Both sides changed. Real conflict.`)
+      remainingConflicts.push(conflict)
+    }
+  }
+
+  return {
+    autoResolvedLocal,
+    autoResolvedRemote,
+    remainingConflicts,
+  }
+}
+
+/**
+ * Writes remote files to disk and updates hash tracker to prevent echoes
+ * CRITICAL: Update hashTracker BEFORE writing to disk
+ */
+export async function writeRemoteFiles(
+  files: FileInfo[],
+  filesDir: string,
+  hashTracker: HashTracker,
+  installer?: { process: (fileName: string, content: string) => void }
+): Promise<void> {
+  info(`Writing ${files.length} remote files`)
+
+  for (const file of files) {
+    try {
+      const normalized = resolveRemoteReference(filesDir, file.name)
+      const fullPath = normalized.absolutePath
+
+      // Ensure directory exists
+      await fs.mkdir(path.dirname(fullPath), { recursive: true })
+
+      // CRITICAL ORDER: Update hash tracker FIRST (in memory)
+      hashTracker.remember(normalized.relativePath, file.content)
+
+      // THEN write to disk
+      await fs.writeFile(fullPath, file.content, "utf-8")
+
+      debug(`Wrote file: ${normalized.relativePath}`)
+
+      // Trigger type installer if available
+      installer?.process(normalized.relativePath, file.content)
+    } catch (err) {
+      warn(`Failed to write file ${file.name}:`, err)
+    }
+  }
+}
+
+/**
+ * Deletes a local file from disk
+ */
+export async function deleteLocalFile(
+  fileName: string,
+  filesDir: string,
+  hashTracker: HashTracker
+): Promise<void> {
+  const normalized = resolveRemoteReference(filesDir, fileName)
+
+  try {
+    // CRITICAL ORDER: Mark delete FIRST (in memory) to prevent echo
+    hashTracker.markDelete(normalized.relativePath)
+
+    // THEN delete from disk
+    await fs.unlink(normalized.absolutePath)
+
+    // Clear the hash immediately
+    hashTracker.forget(normalized.relativePath)
+
+    info(`Deleted file: ${normalized.relativePath}`)
+  } catch (err) {
+    const nodeError = err as NodeJS.ErrnoException
+
+    if (nodeError?.code === "ENOENT") {
+      // Treat missing files as already deleted to keep hash tracker in sync
+      hashTracker.forget(normalized.relativePath)
+      info(`File already deleted: ${normalized.relativePath}`)
+      return
+    }
+
+    // Clear pending delete marker immediately on failure
+    hashTracker.clearDelete(normalized.relativePath)
+    warn(`Failed to delete file ${fileName}:`, err)
+  }
+}
+
+/**
+ * Reads a single file from disk (safe, returns null on error)
+ */
+export async function readFileSafe(
+  fileName: string,
+  filesDir: string
+): Promise<string | null> {
+  const normalized = resolveRemoteReference(filesDir, fileName)
+
+  try {
+    return await fs.readFile(normalized.absolutePath, "utf-8")
+  } catch {
+    return null
+  }
+}
+
+async function readLocalSnapshot(absolutePath: string) {
+  try {
+    const [content, stats] = await Promise.all([
+      fs.readFile(absolutePath, "utf-8"),
+      fs.stat(absolutePath),
+    ])
+    return { content, modifiedAt: stats.mtimeMs }
+  } catch {
+    return null
+  }
+}
+
+function resolveRemoteReference(filesDir: string, rawName: string) {
+  const normalized = sanitizeRelativePath(rawName)
+  const absolutePath = path.join(filesDir, normalized.relativePath)
+  return { ...normalized, absolutePath }
+}
+
+function sanitizeRelativePath(relativePath: string) {
+  const trimmed = normalizePath(relativePath.trim())
+  const hasExtension = SUPPORTED_EXTENSIONS.some((ext) =>
+    trimmed.toLowerCase().endsWith(ext)
+  )
+  const candidate = hasExtension ? trimmed : `${trimmed}${DEFAULT_EXTENSION}`
+  // Don't capitalize when processing remote files - preserve exact casing from Framer
+  const sanitized = sanitizeFilePath(candidate, false)
+  const normalized = normalizePath(sanitized.path)
+
+  return {
+    relativePath: normalized,
+    extension:
+      sanitized.extension || path.extname(normalized) || DEFAULT_EXTENSION,
+  }
+}
+
+function isSupportedExtension(fileName: string) {
+  const lower = fileName.toLowerCase()
+  return SUPPORTED_EXTENSIONS.some((ext) => lower.endsWith(ext))
+}
+
+// Removed ensureSanitizedFileOnDisk as we want to trust user file names