framer-code-link 0.1.0 → 0.1.2

package/README.md

@@ -1,196 +1,3 @@
-# Framer Code Link CLI - Next Generation
+# Framer Code Link CLI
 
-A controller-centric architecture for syncing Framer code components to your local filesystem.
-
-## Architecture
-
-This implementation follows a **controller-centric design** inspired by Go's `main.go` pattern:
-
-- **Single source of truth**: All runtime state lives in `controller.ts`
-- **Clear orchestration**: The controller owns the lifecycle and message routing
-- **Thin helpers**: Domain logic is delegated to pure/stateless helper functions
-- **Extensible**: Easy to add new flows without touching the core controller logic
-
-### File Structure
-
-```
-src/
-  controller.ts      # The orchestration hub - holds state, routes messages
-  index.ts           # CLI entry point
-  types.ts           # Shared TypeScript types
-  helpers/
-    connection.ts    # WebSocket server wrapper
-    watcher.ts       # File watcher wrapper (chokidar)
-    files.ts         # Disk I/O and conflict detection
-    installer.ts     # Type installer (ATA wrapper)
-  utils/
-    hashing.ts       # Hash tracking for echo prevention
-    sanitization.ts  # Path sanitization
-    logging.ts       # Consistent logging
-    paths.ts         # Path manipulation utilities
-```
-
-## Key Design Principles
-
-### 1. Controller Owns State
-
-The controller maintains all runtime state in plain objects:
-
-```typescript
-const state: RuntimeState = {
-  socket: null, // Active WebSocket connection
-  initialSyncComplete: false, // Has first sync finished?
-  pendingConflicts: [], // Conflicts awaiting user input
-  lastRemoteAck: new Map(), // Remote timestamps for conflict detection
-}
-```
-
-### 2. Helpers Provide Data, Never Control
-
-Helpers are thin wrappers that:
-
-- Return data to the controller
-- Never hold callbacks or "service" state
-- Keep logic focused and testable
-
-Example:
-
-```typescript
-// Helper provides data
-const { conflicts, writes } = detectConflicts(remoteFiles, filesDir)
-
-// Controller decides what to do
-if (conflicts.length > 0) {
-  state.pendingConflicts = conflicts
-  sendMessage(socket, { type: "conflicts-detected", conflicts })
-}
-```
-
-### 3. Clear Message Routing
-
-All incoming messages flow through a single `switch` statement in the controller:
-
-```typescript
-switch (message.type) {
-  case "request-files": {
-    /* ... */
-  }
-  case "file-list": {
-    /* ... */
-  }
-  case "file-change": {
-    /* ... */
-  }
-  // etc.
-}
-```
-
-This makes the flow obvious and easy to trace.
-
-### 4. Echo Prevention
-
-Critical ordering prevents infinite loops:
-
-```typescript
-// 1. Update hash tracker FIRST (in memory)
-hashTracker.remember(fileName, content)
-
-// 2. Write to disk SECOND
-await fs.writeFile(filePath, content)
-
-// 3. Watcher fires, checks hash, and skips (no echo!)
-```
-
-## Usage
-
-### CLI
-
-```bash
-# Start with project hash (project name will be received from plugin during handshake)
-npx framer-code-link <projectHash>
-
-# Override project name (optional - useful if you want a different folder name)
-npx framer-code-link <projectHash> --name "My Project"
-
-# Custom directory
-npx framer-code-link <projectHash> --dir ./my-project
-
-# Verbose logging
-npx framer-code-link <projectHash> --verbose
-
-# Auto-delete files without confirmation (use with caution!)
-npx framer-code-link <projectHash> --dangerously-auto-delete
-```
-
-**Note**: The project name is automatically received from the Framer plugin during the initial handshake. You only need to specify `--name` if you want to override it or if you're creating a new workspace before the plugin connects.
-
-### Sync Behavior
-
-The CLI performs **symmetric two-way sync** during initial connection:
-
-- **Remote-only files** → Downloaded to local
-- **Local-only files** → Uploaded to remote
-- **Files on both sides with differences** → Conflict (requires user resolution)
-
-This ensures that new files created while the CLI was offline are automatically synced in both directions.
-
-### Delete Confirmation
-
-By default, when you delete a file locally, the plugin will show a confirmation modal before deleting it from Framer. This prevents accidental data loss.
-
-To skip confirmations and auto-delete files, use the `--dangerously-auto-delete` flag:
-
-```bash
-npx framer-code-link <projectHash> --dangerously-auto-delete
-```
-
-**⚠️ Warning**: This will immediately delete files from Framer without any confirmation when you delete them locally.
-
-### Programmatic
-
-```typescript
-import { start } from "code-link-cli-next-2"
-
-await start({
-  port: 8080,
-  projectHash: "my-project-hash",
-  projectDir: "/path/to/project",
-  filesDir: "/path/to/project/files",
-})
-```
-
-## Extending the Controller
-
-To add new functionality:
-
-1. **Add message type** to `types.ts`
-2. **Add case** to the controller's `switch` statement
-3. **Extract logic** to a helper if it's complex
-4. **Update state** as needed in the controller
-
-Example - adding a "bulk sync" feature:
-
-```typescript
-// 1. Add to types.ts
-export type IncomingMessage =
-  | { type: "bulk-sync"; files: FileInfo[] }
-  | // ... existing types
-
-// 2. Add case to controller
-case "bulk-sync": {
-  info(`Bulk syncing ${message.files.length} files`)
-  await writeRemoteFiles(message.files, config.filesDir, hashTracker, installer)
-  success("Bulk sync complete")
-  break
-}
-```
-
-## Testing Strategy
-
-- **Controller**: Integration-style tests with mock connection + watcher
-- **Helpers**: Unit tests for conflict detection, file operations, etc.
-- **Utils**: Tiny focused tests for hashing, sanitization, etc.
-
-## Design Document
-
-For the full design rationale, see `../cli-next/design.md`.
+A controller-centric architecture for two-way syncing Framer code components to your local filesystem.

package/dist/index.js

@@ -73,6 +73,7 @@ function initConnection(port) {
 			if (event === "handshake") handlers.onHandshake = handler;
 			else if (event === "message") handlers.onMessage = handler;
 			else if (event === "disconnect") handlers.onDisconnect = handler;
+			else if (event === "error") handlers.onError = handler;
 		},
 		close() {
 			wss.close();
@@ -1288,7 +1289,7 @@ async function matchesProject(packageJsonPath, projectHash) {
 
 //#endregion
 //#region src/controller.ts
-/** One-liner log effect builder */
+/** Log helper */
 function log(level, message) {
 	return {
 		type: "LOG",
@@ -1562,13 +1563,6 @@ function transition(state, event) {
 					effects
 				};
 			}
-			if (!state.socket) {
-				effects.push(log("debug", `Ignoring watcher event (disconnected): ${kind} ${relativePath}`));
-				return {
-					state,
-					effects
-				};
-			}
 			switch (kind) {
 				case "add":
 				case "change": {
@@ -1818,13 +1812,13 @@ async function executeEffect(effect, context) {
 * Starts the sync controller with the given configuration
 */
 async function start(config) {
-	info("🚀 Starting Framer Code Link CLI (Next Gen)");
+	info("🚀 Starting Code Link");
 	info(`Project: ${config.projectHash}`);
 	info(`Port: ${config.port} (auto-selected from project hash)`);
 	const hashTracker = createHashTracker();
 	const fileMetadataCache = new FileMetadataCache();
 	let installer = null;
-	const syncState = {
+	let syncState = {
 		mode: "disconnected",
 		socket: null,
 		queuedDiffs: [],
@@ -1834,7 +1828,7 @@ async function start(config) {
 	const userActions = new UserActionCoordinator();
 	async function processEvent(event) {
 		const result = transition(syncState, event);
-		Object.assign(syncState, result.state);
+		syncState = result.state;
 		for (const effect of result.effects) {
 			const followUpEvents = await executeEffect(effect, {
 				config,
@@ -1966,6 +1960,9 @@ async function start(config) {
 		userActions.cleanup();
 		info("Will perform full diff on reconnect");
 	});
+	connection.on("error", (err) => {
+		error("Error on WebSocket connection:", err);
+	});
 	let watcher = null;
 	const startWatcher = () => {
 		if (!config.filesDir || watcher) return;
@@ -1990,7 +1987,14 @@ async function start(config) {
 //#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("code-link").description("Sync Framer code components to your local filesystem").version("0.1.0").argument("<projectHash>", "Framer project hash").option("-n, --name <name>", "Project name (optional)").option("-d, --dir <directory>", "Explicit project directory").option("-v, --verbose", "Enable verbose logging").option("--log-level <level>", "Set log level (debug, info, warn, error)").option("--dangerously-auto-delete", "Automatically delete remote files without confirmation").action(async (projectHash, options) => {
+program.exitOverride((err) => {
+	if (err.code === "commander.missingArgument") {
+		console.error("Missing Project ID. Copy command via Code Link Plugin.");
+		process.exit(err.exitCode ?? 1);
+	}
+	throw err;
+});
+program.name("code-link").description("Sync Framer code components to your local filesystem").version("0.1.0").argument("<projectHash>", "Framer Project ID Hash").option("-n, --name <name>", "Project name (optional)").option("-d, --dir <directory>", "Explicit project directory").option("-v, --verbose", "Enable verbose logging").option("--log-level <level>", "Set log level (debug, info, warn, error)").option("--dangerously-auto-delete", "Automatically delete remote files without confirmation").action(async (projectHash, options) => {
 	const isDev = process.env.NODE_ENV === "development";
 	if (options.logLevel) {
 		const levelMap = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-code-link",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI tool for syncing Framer code components - controller-centric architecture",
   "main": "dist/index.js",
   "type": "module",

package/src/controller.ts

@@ -1,7 +1,6 @@
 /**
  * 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.
  */
 
@@ -173,7 +172,7 @@ type Effect =
   | { type: "PERSIST_STATE" }
   | { type: "LOG"; level: "info" | "debug" | "warn"; message: string }
 
-/** One-liner log effect builder */
+/** Log helper */
 function log(level: "info" | "debug" | "warn", message: string): Effect {
   return { type: "LOG", level, message }
 }
@@ -547,17 +546,6 @@ function transition(
         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": {
@@ -772,7 +760,12 @@ async function executeEffect(
 
     case "SEND_MESSAGE": {
       if (syncState.socket) {
-        await sendMessage(syncState.socket, effect.payload)
+        const sent = await sendMessage(syncState.socket, effect.payload)
+        if (!sent) {
+          warn(`Failed to send message: ${effect.payload.type}`)
+        }
+      } else {
+        warn(`No socket available to send: ${effect.payload.type}`)
       }
       return []
     }
@@ -884,7 +877,6 @@ async function executeEffect(
       if (hashTracker.shouldSkip(effect.fileName, effect.content)) {
         return []
       }
-
       try {
         // Send change to plugin
         if (syncState.socket) {
@@ -967,21 +959,16 @@ async function executeEffect(
  * 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("🚀 Starting Code Link")
   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 = {
+  let syncState: SyncState = {
     mode: "disconnected",
     socket: null,
     queuedDiffs: [],
@@ -994,11 +981,30 @@ export async function start(config: Config): Promise<void> {
   // State Machine Execution Helper
   // Process events through state machine and execute effects recursively
   async function processEvent(event: SyncEvent) {
+    const socketState = syncState.socket?.readyState
+    info(
+      `[STATE] Processing event: ${event.type} (mode: ${syncState.mode}, socket: ${socketState ?? "none"})`
+    )
+
     const result = transition(syncState, event)
-    Object.assign(syncState, result.state)
+    syncState = result.state
+
+    if (result.effects.length > 0) {
+      info(
+        `[STATE] Event produced ${result.effects.length} effects: ${result.effects.map((e) => e.type).join(", ")}`
+      )
+    }
 
     // Execute all effects and process any follow-up events
     for (const effect of result.effects) {
+      // Check socket state before each effect
+      const currentSocketState = syncState.socket?.readyState
+      if (currentSocketState !== undefined && currentSocketState !== 1) {
+        warn(
+          `[STATE] Socket not open (state: ${currentSocketState}) before executing ${effect.type}`
+        )
+      }
+
       const followUpEvents = await executeEffect(effect, {
         config,
         hashTracker,
@@ -1069,9 +1075,17 @@ export async function start(config: Config): Promise<void> {
         event = { type: "REQUEST_FILES" }
         break
 
-      case "file-list":
+      case "file-list": {
+        const totalSize = message.files.reduce(
+          (sum, f) => sum + (f.content?.length ?? 0),
+          0
+        )
+        info(
+          `[FILE_LIST] Received ${message.files.length} files (${(totalSize / 1024).toFixed(1)}KB total)`
+        )
         event = { type: "FILE_LIST", files: message.files }
         break
+      }
 
       case "file-change":
         event = {
@@ -1079,6 +1093,8 @@ export async function start(config: Config): Promise<void> {
           file: {
             name: message.fileName,
             content: message.content,
+            // Remote modifiedAt is expensive to compute (requires getVerions API call), so we
+            // use local receipt time. Conflict detection uses content hashes, not timestamps.
             modifiedAt: Date.now(),
           },
           fileMeta: fileMetadataCache.get(message.fileName),
@@ -1178,6 +1194,10 @@ export async function start(config: Config): Promise<void> {
     info("Will perform full diff on reconnect")
   })
 
+  connection.on("error", (err) => {
+    error("Error on WebSocket connection:", err)
+  })
+
   // File Watcher Setup
   // Note: Watcher will be initialized after handshake when filesDir is set
 

package/src/helpers/connection.ts

@@ -16,12 +16,14 @@ export interface ConnectionCallbacks {
   ) => void
   onMessage: (message: IncomingMessage) => void
   onDisconnect: () => void
+  onError: (error: Error) => 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
+  on(event: "error", handler: ConnectionCallbacks["onError"]): void
   close(): void
 }
 
@@ -31,11 +33,13 @@ export interface Connection {
 export function initConnection(port: number): Connection {
   const wss = new WebSocketServer({ port })
   const handlers: Partial<ConnectionCallbacks> = {}
+  let connectionId = 0
 
   info(`WebSocket server listening on port ${port}`)
 
   wss.on("connection", (ws: WebSocket) => {
-    info("Client connected")
+    const connId = ++connectionId
+    info(`[CONN ${connId}] Client connected (readyState: ${ws.readyState})`)
 
     ws.on("message", (data: Buffer) => {
       try {
@@ -43,33 +47,41 @@ export function initConnection(port: number): Connection {
 
         // Special handling for handshake
         if (message.type === "handshake") {
+          info(`[CONN ${connId}] Received handshake`)
           handlers.onHandshake?.(ws, message)
         } else {
           handlers.onMessage?.(message)
         }
       } catch (err) {
-        error("Failed to parse message:", err)
+        error(`[CONN ${connId}] Failed to parse message:`, err)
       }
     })
 
-    ws.on("close", () => {
-      info("Client disconnected")
+    ws.on("close", (code, reason) => {
+      info(
+        `[CONN ${connId}] Client disconnected (code: ${code}, reason: ${reason?.toString() || "none"})`
+      )
       handlers.onDisconnect?.()
     })
 
     ws.on("error", (err) => {
-      error("WebSocket error:", err)
+      error(`[CONN ${connId}] WebSocket error:`, err)
     })
   })
 
   return {
-    on(event: "handshake" | "message" | "disconnect", handler: any): void {
+    on(
+      event: "handshake" | "message" | "disconnect" | "error",
+      handler: any
+    ): void {
       if (event === "handshake") {
         handlers.onHandshake = handler
       } else if (event === "message") {
         handlers.onMessage = handler
       } else if (event === "disconnect") {
         handlers.onDisconnect = handler
+      } else if (event === "error") {
+        handlers.onError = handler
       }
     },
 
@@ -79,17 +91,50 @@ export function initConnection(port: number): Connection {
   }
 }
 
+/**
+ * WebSocket readyState constants for reference
+ */
+const READY_STATE = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const
+
+function readyStateToString(state: number): string {
+  switch (state) {
+    case 0: return "CONNECTING"
+    case 1: return "OPEN"
+    case 2: return "CLOSING"
+    case 3: return "CLOSED"
+    default: return `UNKNOWN(${state})`
+  }
+}
+
 /**
  * Sends a message to a connected socket
+ * Returns false if the socket is not open (instead of throwing)
  */
 export function sendMessage(
   socket: WebSocket,
   message: OutgoingMessage
-): Promise<void> {
-  return new Promise((resolve, reject) => {
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    // Check socket state before attempting to send
+    if (socket.readyState !== READY_STATE.OPEN) {
+      const stateStr = readyStateToString(socket.readyState)
+      info(`[WS] Cannot send ${message.type}: socket is ${stateStr}`)
+      resolve(false)
+      return
+    }
+
     socket.send(JSON.stringify(message), (err) => {
-      if (err) reject(err)
-      else resolve()
+      if (err) {
+        error(`[WS] Send error for ${message.type}:`, err.message)
+        resolve(false)
+      } else {
+        resolve(true)
+      }
     })
   })
 }

package/src/index.ts

@@ -12,14 +12,26 @@ import { start } from "./controller.js"
 import type { Config } from "./types.js"
 import { setLogLevel, LogLevel, info } from "./utils/logging.js"
 import { getPortFromHash } from "./utils/hashing.js"
+import { getProjectHashFromCwd } from "./utils/project.js"
 
 const program = new Command()
 
+program.exitOverride((err) => {
+  if (err.code === "commander.missingArgument") {
+    console.error("Missing Project ID. Copy command via Code Link Plugin.")
+    process.exit(err.exitCode ?? 1)
+  }
+  throw err
+})
+
 program
   .name("code-link")
   .description("Sync Framer code components to your local filesystem")
   .version("0.1.0")
-  .argument("<projectHash>", "Framer project hash")
+  .argument(
+    "[projectHash]",
+    "Framer Project ID Hash (auto-detected from package.json if omitted)"
+  )
   .option("-n, --name <name>", "Project name (optional)")
   .option("-d, --dir <directory>", "Explicit project directory")
   .option("-v, --verbose", "Enable verbose logging")
@@ -28,7 +40,23 @@ program
     "--dangerously-auto-delete",
     "Automatically delete remote files without confirmation"
   )
-  .action(async (projectHash: string, options) => {
+  .action(async (projectHash: string | undefined, options) => {
+    // If no projectHash provided, try to read from cwd's package.json
+    if (!projectHash) {
+      const detected = await getProjectHashFromCwd()
+      if (detected) {
+        projectHash = detected
+      } else {
+        console.error(
+          "No project ID provided and no framerProjectId found in package.json."
+        )
+        console.error(
+          "Either run this command from a project directory or copy the command from the Code Link Plugin."
+        )
+        process.exit(1)
+      }
+    }
+
     // Auto-enable debug in development unless overridden
     const isDev = process.env.NODE_ENV === "development"
 

package/src/utils/project.ts

@@ -17,6 +17,24 @@ export function toPackageName(name: string): string {
     .replace(/-+/g, "-")
 }
 
+export function toDirName(name: string): string {
+  return name
+    .replace(/[^a-zA-Z0-9-]/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, "-")
+}
+
+export async function getProjectHashFromCwd(): Promise<string | null> {
+  try {
+    const packageJsonPath = path.join(process.cwd(), "package.json")
+    const content = await fs.readFile(packageJsonPath, "utf-8")
+    const pkg = JSON.parse(content) as PackageJson
+    return pkg.framerProjectId ?? null
+  } catch {
+    return null
+  }
+}
+
 export async function findOrCreateProjectDir(
   projectHash: string,
   projectName?: string,
@@ -40,12 +58,13 @@ export async function findOrCreateProjectDir(
     )
   }
 
-  const dirName = toPackageName(projectName)
+  const dirName = toDirName(projectName)
+  const pkgName = toPackageName(projectName)
   const projectDir = path.join(cwd, dirName || projectHash.slice(0, 6))
 
   await fs.mkdir(path.join(projectDir, "files"), { recursive: true })
   const pkg: PackageJson = {
-    name: dirName || projectHash,
+    name: pkgName || projectHash,
     version: "1.0.0",
     private: true,
     framerProjectId: projectHash,