framer-code-link 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-code-link",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "CLI tool for syncing Framer code components - controller-centric architecture",
   "main": "dist/index.js",
   "type": "module",
@@ -29,8 +29,8 @@
   "devDependencies": {
     "@types/node": "^22.19.2",
     "@types/ws": "^8.18.1",
-    "tsdown": "^0.17.3",
+    "tsdown": "^0.17.4",
     "tsx": "^4.21.0",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.15"
   }
 }

package/src/controller.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest"
-import { transition } from "./controller.js"
+import { filterEchoedFiles, transition } from "./controller.js"
+import { createHashTracker } from "./utils/hash-tracker.js"
 import type { WebSocket } from "ws"
 describe("State Machine", () => {
   describe("HANDSHAKE transition", () => {
@@ -848,4 +849,43 @@ describe("State Machine", () => {
       }
     })
   })
+
+  describe("echo prevention filter", () => {
+    it("skips inbound file-change that matches last local send", () => {
+      const hashTracker = createHashTracker()
+      hashTracker.remember("Hey.tsx", "content")
+
+      const filtered = filterEchoedFiles(
+        [
+          {
+            name: "Hey.tsx",
+            content: "content",
+            modifiedAt: Date.now(),
+          },
+        ],
+        hashTracker
+      )
+
+      expect(filtered).toHaveLength(0)
+    })
+
+    it("keeps inbound change when content differs", () => {
+      const hashTracker = createHashTracker()
+      hashTracker.remember("Hey.tsx", "old content")
+
+      const filtered = filterEchoedFiles(
+        [
+          {
+            name: "Hey.tsx",
+            content: "new content",
+            modifiedAt: Date.now(),
+          },
+        ],
+        hashTracker
+      )
+
+      expect(filtered).toHaveLength(1)
+      expect(filtered[0]?.content).toBe("new content")
+    })
+  })
 })

package/src/controller.ts

@@ -161,7 +161,12 @@ type Effect =
   | { type: "SEND_MESSAGE"; payload: OutgoingMessage }
   | { type: "LIST_LOCAL_FILES" }
   | { type: "DETECT_CONFLICTS"; remoteFiles: FileInfo[] }
-  | { type: "WRITE_FILES"; files: FileInfo[]; silent?: boolean }
+  | {
+      type: "WRITE_FILES"
+      files: FileInfo[]
+      silent?: boolean
+      skipEcho?: boolean // when true, skip writes that match hashTracker (inbound echo)
+    }
   | { type: "DELETE_LOCAL_FILES"; names: string[] }
   | { type: "REQUEST_CONFLICT_DECISIONS"; conflicts: Conflict[] }
   | { type: "REQUEST_CONFLICT_VERSIONS"; conflicts: Conflict[] }
@@ -199,6 +204,20 @@ function log(level: "info" | "debug" | "warn", message: string): Effect {
   return { type: "LOG", level, message }
 }
 
+/**
+ * Filter out files whose content matches the last remembered hash.
+ * Used to skip inbound echoes of our own local sends.
+ */
+export function filterEchoedFiles(
+  files: FileInfo[],
+  hashTracker: ReturnType<typeof createHashTracker>
+): FileInfo[] {
+  return files.filter((file) => {
+    if (file.content === undefined) return true
+    return !hashTracker.shouldSkip(file.name, file.content)
+  })
+}
+
 /**
  * Pure state transition function
  * Takes current state + event, returns new state + effects to execute
@@ -336,6 +355,7 @@ function transition(
       // - safeWrites = files we can apply (remote-only or local unchanged)
       // - conflicts = files that need manual resolution (content or deletion conflicts)
       // - localOnly = files to upload
+      // (unchanged files have metadata recorded in DETECT_CONFLICTS executor)
 
       // Apply safe writes
       if (safeWrites.length > 0) {
@@ -383,7 +403,6 @@ function transition(
       }
 
       // No conflicts - transition to watching
-      const totalSynced = safeWrites.length + localOnly.length
       const remoteTotal = state.queuedDiffs.length
       const totalCount = remoteTotal + localOnly.length
       const updatedCount = safeWrites.length + localOnly.length
@@ -447,6 +466,7 @@ function transition(
       effects.push(log("debug", `Applying remote change: ${event.file.name}`), {
         type: "WRITE_FILES",
         files: [event.file],
+        skipEcho: true,
       })
 
       return { state, effects }
@@ -832,12 +852,22 @@ async function executeEffect(
       }
 
       // Use existing helper to detect conflicts
-      const { conflicts, writes, localOnly } = await detectConflicts(
+      const { conflicts, writes, localOnly, unchanged } = await detectConflicts(
         effect.remoteFiles,
         config.filesDir,
         { persistedState: fileMetadataCache.getPersistedState() }
       )
 
+      // Record metadata for unchanged files so watcher add events get skipped
+      // (chokidar ignoreInitial=false fires late adds that would otherwise re-upload)
+      for (const file of unchanged) {
+        fileMetadataCache.recordRemoteWrite(
+          file.name,
+          file.content,
+          file.modifiedAt ?? Date.now()
+        )
+      }
+
       // Return CONFLICTS_DETECTED event to continue the flow
       return [
         {
@@ -863,13 +893,29 @@ async function executeEffect(
 
     case "WRITE_FILES": {
       if (config.filesDir) {
+        // skipEcho is opt-in: some callers still need side-effects (metadata/logs)
+        // even when content matches the last hash tracked in-memory.
+        const filesToWrite =
+          effect.skipEcho === true
+            ? filterEchoedFiles(effect.files, hashTracker)
+            : effect.files
+
+        if (effect.skipEcho && filesToWrite.length !== effect.files.length) {
+          const skipped = effect.files.length - filesToWrite.length
+          debug(`Skipped ${pluralize(skipped, "echoed change")}`)
+        }
+
+        if (filesToWrite.length === 0) {
+          return []
+        }
+
         await writeRemoteFiles(
-          effect.files,
+          filesToWrite,
           config.filesDir,
           hashTracker,
           installer ?? undefined
         )
-        for (const file of effect.files) {
+        for (const file of filesToWrite) {
           if (!effect.silent) {
             fileDown(file.name)
           }
@@ -1056,6 +1102,11 @@ async function executeEffect(
     case "SYNC_COMPLETE": {
       const wasDisconnected = wasRecentlyDisconnected()
 
+      // Notify plugin that sync is complete
+      if (syncState.socket) {
+        await sendMessage(syncState.socket, { type: "sync-complete" })
+      }
+
       if (wasDisconnected) {
         // Only show reconnect message if we actually showed the disconnect notice
         if (didShowDisconnect()) {

package/src/helpers/connection.ts

@@ -72,6 +72,7 @@ export function initConnection(port: number): Promise<Connection> {
 
       wss.on("connection", (ws: WebSocket) => {
         const connId = ++connectionId
+        let handshakeReceived = false
         debug(`Client connected (conn ${connId})`)
 
         ws.on("message", (data: Buffer) => {
@@ -81,9 +82,15 @@ export function initConnection(port: number): Promise<Connection> {
             // Special handling for handshake
             if (message.type === "handshake") {
               debug(`Received handshake (conn ${connId})`)
+              handshakeReceived = true
               handlers.onHandshake?.(ws, message)
-            } else {
+            } else if (handshakeReceived) {
               handlers.onMessage?.(message)
+            } else {
+              // Ignore messages before handshake - plugin will send full snapshot after
+              debug(
+                `Ignoring ${message.type} before handshake (conn ${connId})`
+              )
             }
           } catch (err) {
             error(`Failed to parse message:`, err)

package/src/helpers/files.ts

@@ -103,6 +103,7 @@ export async function detectConflicts(
   const conflicts: Conflict[] = []
   const writes: FileInfo[] = []
   const localOnly: FileInfo[] = []
+  const unchanged: FileInfo[] = []
   const detect = options.detectConflicts ?? true
   const preferRemote = options.preferRemote ?? false
   const persistedState = options.persistedState
@@ -169,7 +170,12 @@ export async function detectConflicts(
     }
 
     if (local.content === remote.content) {
-      // No change needed
+      // Content matches - no disk write needed but track for metadata
+      unchanged.push({
+        name: normalized.relativePath,
+        content: remote.content,
+        modifiedAt: remote.modifiedAt,
+      })
       continue
     }
 
@@ -203,15 +209,19 @@ export async function detectConflicts(
     if (!processedFiles.has(localKey)) {
       const persisted = getPersistedState(local.name)
       if (persisted) {
-        // File was previously synced but now missing from remote → deleted in Framer while offline
-        // This is a conflict: local=content, remote=null (deleted)
-        debug(`Conflict: ${local.name} deleted in Framer while offline`)
+        // File was previously synced but now missing from remote → deleted in Framer
+        const localHash = hashFileContent(local.content)
+        const localClean = localHash === persisted.contentHash
+        debug(
+          `Conflict: ${local.name} deleted in Framer (localClean=${localClean})`
+        )
         conflicts.push({
           fileName: local.name,
           localContent: local.content,
           remoteContent: null,
           localModifiedAt: local.modifiedAt,
           lastSyncedAt: persisted?.timestamp,
+          localClean,
         })
       } else {
         // New local file (never synced before): upload later
@@ -239,7 +249,7 @@ export async function detectConflicts(
     }
   }
 
-  return { conflicts, writes, localOnly }
+  return { conflicts, writes, localOnly, unchanged }
 }
 
 export interface AutoResolveResult {
@@ -265,9 +275,22 @@ export function autoResolveConflicts(
   for (const conflict of conflicts) {
     const latestRemoteVersionMs = versionMap.get(conflict.fileName)
     const lastSyncedAt = conflict.lastSyncedAt
+    const localClean = conflict.localClean === true
 
     debug(`Auto-resolve checking ${conflict.fileName}`)
 
+    // Remote deletion: file deleted in Framer
+    if (conflict.remoteContent === null) {
+      if (localClean) {
+        debug(`  Remote deleted, local clean -> REMOTE (delete locally)`)
+        autoResolvedRemote.push(conflict)
+      } else {
+        debug(`  Remote deleted, local modified -> conflict`)
+        remainingConflicts.push(conflict)
+      }
+      continue
+    }
+
     if (!latestRemoteVersionMs) {
       debug(`  No remote version data, keeping conflict`)
       remainingConflicts.push(conflict)
@@ -285,7 +308,7 @@ export function autoResolveConflicts(
 
     const remoteUnchanged =
       latestRemoteVersionMs <= lastSyncedAt + remoteDriftMs
-    const localClean = conflict.localClean === true
+    // localClean already declared above for remote deletion handling
 
     if (remoteUnchanged && !localClean) {
       debug(`  Remote unchanged, local changed -> LOCAL`)

package/src/helpers/installer.ts

@@ -1,9 +1,5 @@
 /**
- * Type installer helper
- *
- * Wraps @typescript/ata with our custom fetcher and initialization routines.
- * This preserves the battle-tested logic from the classic CLI while
- * conforming to the controller-centric architecture.
+ * Type installer helper using @typescript/ata
  */
 
 import { setupTypeAcquisition } from "@typescript/ata"

package/src/helpers/watcher.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi, afterEach } from "vitest"
+import fs from "fs/promises"
+import os from "os"
+import path from "path"
+import { initWatcher } from "./watcher.js"
+
+const createdWatchers: any[] = []
+
+vi.mock("chokidar", () => {
+  const createMockWatcher = () => {
+    const handlers: Record<string, Array<(filePath: string) => any>> = {
+      add: [],
+      change: [],
+      unlink: [],
+    }
+
+    return {
+      on(event: "add" | "change" | "unlink", handler: (file: string) => any) {
+        handlers[event]?.push(handler)
+        return this
+      },
+      async __emit(event: "add" | "change" | "unlink", filePath: string) {
+        for (const handler of handlers[event] ?? []) {
+          await handler(filePath)
+        }
+      },
+      close: vi.fn().mockResolvedValue(undefined),
+    }
+  }
+
+  const watch = vi.fn(() => {
+    const instance = createMockWatcher()
+    createdWatchers.push(instance)
+    return instance
+  })
+
+  return { default: { watch }, watch }
+})
+
+describe("initWatcher", () => {
+  afterEach(() => {
+    createdWatchers.length = 0
+  })
+
+  it("ignores unsupported extensions and sanitizes added files", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "framer-watcher-"))
+    const events: any[] = []
+    const watcher = initWatcher(tmpDir)
+    watcher.on("change", (event) => events.push(event))
+    const rawWatcher = createdWatchers.at(-1)!
+
+    const unsupportedPath = path.join(tmpDir, "note.txt")
+    await fs.writeFile(unsupportedPath, "hello", "utf-8")
+    await rawWatcher.__emit("add", unsupportedPath)
+    expect(events).toHaveLength(0)
+
+    const rawPath = path.join(tmpDir, "bad name!.tsx")
+    await fs.writeFile(rawPath, "export const X = 1;", "utf-8")
+    await rawWatcher.__emit("add", rawPath)
+
+    const addEvent = events.find((e) => e.kind === "add")
+    expect(addEvent).toBeDefined()
+    expect(addEvent?.relativePath).toBe("bad_name_.tsx")
+    expect(addEvent?.content).toContain("export const X")
+
+    const renamedPath = path.join(tmpDir, "bad_name_.tsx")
+    await expect(fs.readFile(renamedPath, "utf-8")).resolves.toContain(
+      "export const X"
+    )
+
+    await watcher.close()
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+})

package/src/types.ts

@@ -2,7 +2,6 @@
  * Core types for the controller-centric CLI architecture
  */
 
-import type { WebSocket } from "ws"
 import type { PendingDelete } from "@code-link/shared"
 
 // Configuration
@@ -30,6 +29,8 @@ export interface LocalFile {
 }
 
 // Conflict detection
+// Deletions are represented by null content
+// For AI: Do NOT add remoteDeletes/localDeletes arrays - use localContent/remoteContent === null
 export interface Conflict {
   fileName: string
   /** null means the file was deleted locally */
@@ -50,6 +51,7 @@ export interface ConflictResolution {
   conflicts: Conflict[]
   writes: FileInfo[]
   localOnly: FileInfo[]
+  unchanged: FileInfo[]
 }
 
 // Watcher events
@@ -107,3 +109,4 @@ export type OutgoingMessage =
       type: "conflict-version-request"
       conflicts: ConflictVersionRequest[]
     }
+  | { type: "sync-complete" }

package/src/utils/logging.ts

@@ -121,7 +121,10 @@ export function info(message: string, ...args: unknown[]): void {
  */
 export function warn(message: string, ...args: unknown[]): void {
   if (currentLevel <= LogLevel.WARN) {
+    if (message === lastMessage) return // Skip exact duplicates silently
     flushDedupe()
+    lastMessage = message
+    lastMessageCount = 1
     console.warn(pc.yellow(`⚠ ${message}`), ...args)
   }
 }

package/dist/project-DhpsFg77.js

@@ -1,53 +0,0 @@
-import fs from "fs/promises";
-import path from "path";
-
-//#region src/utils/project.ts
-function toPackageName(name) {
-	return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
-}
-async function findOrCreateProjectDir(projectHash, projectName, explicitDir) {
-	if (explicitDir) {
-		const resolved = path.resolve(explicitDir);
-		await fs.mkdir(path.join(resolved, "files"), { recursive: true });
-		return resolved;
-	}
-	const cwd = process.cwd();
-	const existing = await findExistingProjectDir(cwd, projectHash);
-	if (existing) return existing;
-	if (!projectName) throw new Error("Project name is required when creating a new workspace. Pass --name <project name>.");
-	const dirName = toPackageName(projectName);
-	const projectDir = path.join(cwd, dirName || projectHash.slice(0, 6));
-	await fs.mkdir(path.join(projectDir, "files"), { recursive: true });
-	const pkg = {
-		name: dirName || projectHash,
-		version: "1.0.0",
-		private: true,
-		framerProjectId: projectHash,
-		framerProjectName: projectName
-	};
-	await fs.writeFile(path.join(projectDir, "package.json"), JSON.stringify(pkg, null, 2));
-	return projectDir;
-}
-async function findExistingProjectDir(baseDir, projectHash) {
-	const candidate = path.join(baseDir, "package.json");
-	if (await matchesProject(candidate, projectHash)) return baseDir;
-	const entries = await fs.readdir(baseDir, { withFileTypes: true });
-	for (const entry of entries) {
-		if (!entry.isDirectory()) continue;
-		const dir = path.join(baseDir, entry.name);
-		if (await matchesProject(path.join(dir, "package.json"), projectHash)) return dir;
-	}
-	return null;
-}
-async function matchesProject(packageJsonPath, projectHash) {
-	try {
-		const content = await fs.readFile(packageJsonPath, "utf-8");
-		const pkg = JSON.parse(content);
-		return pkg.framerProjectId === projectHash;
-	} catch {
-		return false;
-	}
-}
-
-//#endregion
-export { findOrCreateProjectDir };