framer-code-link 0.1.1 → 0.1.3

package/dist/index.js

@@ -44,50 +44,107 @@ function success(message, ...args) {
 //#region src/helpers/connection.ts
 /**
 * Initializes a WebSocket server and returns a connection interface
+* Returns a Promise that resolves when the server is ready, or rejects on startup errors
 */
 function initConnection(port) {
-	const wss = new WebSocketServer({ port });
-	const handlers = {};
-	info(`WebSocket server listening on port ${port}`);
-	wss.on("connection", (ws) => {
-		info("Client connected");
-		ws.on("message", (data) => {
-			try {
-				const message = JSON.parse(data.toString());
-				if (message.type === "handshake") handlers.onHandshake?.(ws, message);
-				else handlers.onMessage?.(message);
-			} catch (err) {
-				error("Failed to parse message:", err);
+	return new Promise((resolve, reject) => {
+		const wss = new WebSocketServer({ port });
+		const handlers = {};
+		let connectionId = 0;
+		let isReady = false;
+		wss.on("error", (err) => {
+			if (!isReady) {
+				if (err.code === "EADDRINUSE") {
+					error(`Port ${port} is already in use.`);
+					error(`This usually means another instance of Code Link is already running.`);
+					error(``);
+					error(`To fix this:`);
+					error(`  1. Close any other terminal running Code Link for this project`);
+					error(`  2. Or run: lsof -i :${port} | grep LISTEN`);
+					error(`     Then kill the process: kill -9 <PID>`);
+					reject(new Error(`Port ${port} is already in use`));
+				} else {
+					error(`Failed to start WebSocket server: ${err.message}`);
+					reject(err);
+				}
+				return;
 			}
+			error(`WebSocket server error: ${err.message}`);
 		});
-		ws.on("close", () => {
-			info("Client disconnected");
-			handlers.onDisconnect?.();
-		});
-		ws.on("error", (err) => {
-			error("WebSocket error:", err);
+		wss.on("listening", () => {
+			isReady = true;
+			info(`WebSocket server listening on port ${port}`);
+			wss.on("connection", (ws) => {
+				const connId = ++connectionId;
+				info(`[CONN ${connId}] Client connected (readyState: ${ws.readyState})`);
+				ws.on("message", (data) => {
+					try {
+						const message = JSON.parse(data.toString());
+						if (message.type === "handshake") {
+							info(`[CONN ${connId}] Received handshake`);
+							handlers.onHandshake?.(ws, message);
+						} else handlers.onMessage?.(message);
+					} catch (err) {
+						error(`[CONN ${connId}] Failed to parse message:`, err);
+					}
+				});
+				ws.on("close", (code, reason) => {
+					info(`[CONN ${connId}] Client disconnected (code: ${code}, reason: ${reason?.toString() || "none"})`);
+					handlers.onDisconnect?.();
+				});
+				ws.on("error", (err) => {
+					error(`[CONN ${connId}] WebSocket error:`, err);
+				});
+			});
+			resolve({
+				on(event, handler) {
+					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();
+				}
+			});
 		});
 	});
-	return {
-		on(event, handler) {
-			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();
-		}
-	};
+}
+/**
+* WebSocket readyState constants for reference
+*/
+const READY_STATE = {
+	CONNECTING: 0,
+	OPEN: 1,
+	CLOSING: 2,
+	CLOSED: 3
+};
+function readyStateToString(state) {
+	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)
 */
 function sendMessage(socket, message) {
-	return new Promise((resolve, reject) => {
+	return new Promise((resolve) => {
+		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);
 		});
 	});
 }
@@ -1243,6 +1300,19 @@ function validateIncomingChange(file, fileMeta, currentMode) {
 function toPackageName(name) {
 	return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
 }
+function toDirName(name) {
+	return name.replace(/[^a-zA-Z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
+}
+async function getProjectHashFromCwd() {
+	try {
+		const packageJsonPath = path.join(process.cwd(), "package.json");
+		const content = await fs.readFile(packageJsonPath, "utf-8");
+		const pkg = JSON.parse(content);
+		return pkg.framerProjectId ?? null;
+	} catch {
+		return null;
+	}
+}
 async function findOrCreateProjectDir(projectHash, projectName, explicitDir) {
 	if (explicitDir) {
 		const resolved = path.resolve(explicitDir);
@@ -1253,11 +1323,12 @@ async function findOrCreateProjectDir(projectHash, projectName, explicitDir) {
 	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 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 = {
-		name: dirName || projectHash,
+		name: pkgName || projectHash,
 		version: "1.0.0",
 		private: true,
 		framerProjectId: projectHash,
@@ -1697,7 +1768,10 @@ async function executeEffect(effect, context) {
 			}];
 		}
 		case "SEND_MESSAGE": {
-			if (syncState.socket) await sendMessage(syncState.socket, effect.payload);
+			if (syncState.socket) {
+				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 [];
 		}
 		case "WRITE_FILES": {
@@ -1827,9 +1901,14 @@ async function start(config) {
 	};
 	const userActions = new UserActionCoordinator();
 	async function processEvent(event) {
+		const socketState = syncState.socket?.readyState;
+		info(`[STATE] Processing event: ${event.type} (mode: ${syncState.mode}, socket: ${socketState ?? "none"})`);
 		const result = transition(syncState, event);
 		syncState = result.state;
+		if (result.effects.length > 0) info(`[STATE] Event produced ${result.effects.length} effects: ${result.effects.map((e) => e.type).join(", ")}`);
 		for (const effect of result.effects) {
+			const currentSocketState = syncState.socket?.readyState;
+			if (currentSocketState !== void 0 && currentSocketState !== 1) warn(`[STATE] Socket not open (state: ${currentSocketState}) before executing ${effect.type}`);
 			const followUpEvents = await executeEffect(effect, {
 				config,
 				hashTracker,
@@ -1841,7 +1920,7 @@ async function start(config) {
 			for (const followUpEvent of followUpEvents) await processEvent(followUpEvent);
 		}
 	}
-	const connection = initConnection(config.port);
+	const connection = await initConnection(config.port);
 	connection.on("handshake", async (client, message) => {
 		info("Received handshake from plugin");
 		info(`Project: ${message.projectName} (${message.projectId})`);
@@ -1875,12 +1954,15 @@ async function start(config) {
 			case "request-files":
 				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 = {
 					type: "FILE_CHANGE",
@@ -1994,7 +2076,16 @@ program.exitOverride((err) => {
 	}
 	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) => {
+program.name("code-link").description("Sync Framer code components to your local filesystem").version("0.1.0").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").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) => {
+	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);
+		}
+	}
 	const isDev = process.env.NODE_ENV === "development";
 	if (options.logLevel) {
 		const levelMap = {
@@ -2017,7 +2108,11 @@ program.name("code-link").description("Sync Framer code components to your local
 		explicitName: options.name
 	};
 	if (config.dangerouslyAutoDelete) info("⚠️  Auto-delete mode enabled - files will be deleted without confirmation");
-	await start(config);
+	try {
+		await start(config);
+	} catch (err) {
+		process.exit(1);
+	}
 });
 program.parse();
 

package/package.json

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

package/src/controller.ts

@@ -760,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 []
     }
@@ -976,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)
     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,
@@ -998,7 +1022,7 @@ export async function start(config: Config): Promise<void> {
   }
 
   // WebSocket Connection
-  const connection = initConnection(config.port)
+  const connection = await initConnection(config.port)
 
   // Handle initial handshake
   connection.on("handshake", async (client: WebSocket, message) => {
@@ -1051,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 = {

package/src/helpers/connection.ts

@@ -29,74 +29,152 @@ export interface Connection {
 
 /**
  * Initializes a WebSocket server and returns a connection interface
+ * Returns a Promise that resolves when the server is ready, or rejects on startup errors
  */
-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
+export function initConnection(port: number): Promise<Connection> {
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer({ port })
+    const handlers: Partial<ConnectionCallbacks> = {}
+    let connectionId = 0
+    let isReady = false
 
-        // Special handling for handshake
-        if (message.type === "handshake") {
-          handlers.onHandshake?.(ws, message)
+    // Handle server-level errors (e.g., EADDRINUSE)
+    wss.on("error", (err: NodeJS.ErrnoException) => {
+      if (!isReady) {
+        // Startup error - reject the promise with a helpful message
+        if (err.code === "EADDRINUSE") {
+          error(`Port ${port} is already in use.`)
+          error(
+            `This usually means another instance of Code Link is already running.`
+          )
+          error(``)
+          error(`To fix this:`)
+          error(
+            `  1. Close any other terminal running Code Link for this project`
+          )
+          error(`  2. Or run: lsof -i :${port} | grep LISTEN`)
+          error(`     Then kill the process: kill -9 <PID>`)
+          reject(new Error(`Port ${port} is already in use`))
         } else {
-          handlers.onMessage?.(message)
+          error(`Failed to start WebSocket server: ${err.message}`)
+          reject(err)
         }
-      } catch (err) {
-        error("Failed to parse message:", err)
+        return
       }
+      // Runtime error - log but don't crash
+      error(`WebSocket server error: ${err.message}`)
     })
 
-    ws.on("close", () => {
-      info("Client disconnected")
-      handlers.onDisconnect?.()
-    })
+    // Server is ready when it starts listening
+    wss.on("listening", () => {
+      isReady = true
+      info(`WebSocket server listening on port ${port}`)
+
+      wss.on("connection", (ws: WebSocket) => {
+        const connId = ++connectionId
+        info(`[CONN ${connId}] Client connected (readyState: ${ws.readyState})`)
+
+        ws.on("message", (data: Buffer) => {
+          try {
+            const message = JSON.parse(data.toString()) as IncomingMessage
+
+            // Special handling for handshake
+            if (message.type === "handshake") {
+              info(`[CONN ${connId}] Received handshake`)
+              handlers.onHandshake?.(ws, message)
+            } else {
+              handlers.onMessage?.(message)
+            }
+          } catch (err) {
+            error(`[CONN ${connId}] Failed to parse message:`, err)
+          }
+        })
+
+        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)
+        ws.on("error", (err) => {
+          error(`[CONN ${connId}] WebSocket error:`, err)
+        })
+      })
+
+      resolve({
+        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
+          }
+        },
+
+        close(): void {
+          wss.close()
+        },
+      })
     })
   })
+}
 
-  return {
-    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
-      }
-    },
+/**
+ * WebSocket readyState constants for reference
+ */
+const READY_STATE = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const
 
-    close(): void {
-      wss.close()
-    },
+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,6 +12,7 @@ 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()
 
@@ -27,7 +28,10 @@ program
   .name("code-link")
   .description("Sync Framer code components to your local filesystem")
   .version("0.1.0")
-  .argument("<projectHash>", "Framer Project ID 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")
@@ -36,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"
 
@@ -73,7 +93,12 @@ program
       )
     }
 
-    await start(config)
+    try {
+      await start(config)
+    } catch (err) {
+      // Error already logged, exit cleanly
+      process.exit(1)
+    }
   })
 
 program.parse()

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,