framer-code-link 0.1.0 → 0.1.1

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.1",
   "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": {
@@ -884,7 +872,6 @@ async function executeEffect(
       if (hashTracker.shouldSkip(effect.fileName, effect.content)) {
         return []
       }
-
       try {
         // Send change to plugin
         if (syncState.socket) {
@@ -967,21 +954,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: [],
@@ -995,7 +977,7 @@ export async function start(config: Config): Promise<void> {
   // Process events through state machine and execute effects recursively
   async function processEvent(event: SyncEvent) {
     const result = transition(syncState, event)
-    Object.assign(syncState, result.state)
+    syncState = result.state
 
     // Execute all effects and process any follow-up events
     for (const effect of result.effects) {
@@ -1079,6 +1061,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 +1162,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
 }
 
@@ -63,13 +65,18 @@ export function initConnection(port: number): Connection {
   })
 
   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
       }
     },
 

package/src/index.ts

@@ -15,11 +15,19 @@ import { getPortFromHash } from "./utils/hashing.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")
   .option("-n, --name <name>", "Project name (optional)")
   .option("-d, --dir <directory>", "Explicit project directory")
   .option("-v, --verbose", "Enable verbose logging")