framer-code-link 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# Framer Code Link CLI - Next Generation
+
+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`.