framer-code-link 0.1.0

package/src/helpers/user-actions.ts

@@ -0,0 +1,162 @@
+/**
+ * User Action Coordinator
+ *
+ * Provides a clean awaitable API for user confirmations via the plugin.
+ * Just coordinates the request/response - all business logic stays in the controller.
+ */
+
+import type { WebSocket } from "ws"
+import type { Conflict } from "../types.js"
+import { sendMessage } from "./connection.js"
+import { info, warn } from "../utils/logging.js"
+
+class PluginDisconnectedError extends Error {
+  constructor() {
+    super("Plugin disconnected")
+    this.name = "PluginDisconnectedError"
+  }
+}
+
+type PendingAction<T> = {
+  resolve: (value: T) => void
+  reject: (error: Error) => void
+}
+
+export class UserActionCoordinator {
+  private pendingActions = new Map<string, PendingAction<any>>()
+
+  /**
+   * Sends the delete request to the plugin and awaits the user's decision
+   */
+  async requestDeleteDecision(
+    socket: WebSocket | null,
+    {
+      fileName,
+      requireConfirmation,
+    }: { fileName: string; requireConfirmation: boolean }
+  ): Promise<boolean> {
+    if (!socket) {
+      throw new Error("Cannot request delete decision: plugin not connected")
+    }
+
+    if (requireConfirmation) {
+      const confirmationPromise = this.awaitConfirmation<boolean>(
+        `delete:${fileName}`,
+        "delete confirmation"
+      )
+
+      await sendMessage(socket, {
+        type: "file-delete",
+        fileNames: [fileName],
+        requireConfirmation: true,
+      })
+
+      try {
+        return await confirmationPromise
+      } catch (err) {
+        if (err instanceof PluginDisconnectedError) {
+          info(
+            `[USER-ACTION] Plugin disconnected while waiting for delete confirmation: ${fileName}`
+          )
+          return false
+        }
+        throw err
+      }
+    }
+
+    await sendMessage(socket, {
+      type: "file-delete",
+      fileNames: [fileName],
+      requireConfirmation: false,
+    })
+
+    return true
+  }
+
+  /**
+   * Sends conflicts to the plugin and awaits user resolutions
+   */
+  async requestConflictDecisions(
+    socket: WebSocket | null,
+    conflicts: Conflict[]
+  ): Promise<Map<string, "local" | "remote">> {
+    if (!socket) {
+      throw new Error("Cannot request conflict decision: plugin not connected")
+    }
+
+    if (conflicts.length === 0) {
+      return new Map()
+    }
+
+    const pending = conflicts.map((conflict) => ({
+      fileName: conflict.fileName,
+      promise: this.awaitConfirmation<"local" | "remote">(
+        `conflict:${conflict.fileName}`,
+        "conflict resolution"
+      ),
+    }))
+
+    await sendMessage(socket, {
+      type: "conflicts-detected",
+      conflicts,
+    })
+
+    try {
+      const results = await Promise.all(
+        pending.map(
+          async ({ fileName, promise }) => [fileName, await promise] as const
+        )
+      )
+
+      return new Map(results)
+    } catch (err) {
+      if (err instanceof PluginDisconnectedError) {
+        info(
+          "[USER-ACTION] Plugin disconnected while awaiting conflict decisions"
+        )
+        return new Map()
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Generic confirmation awaiter
+   */
+  private awaitConfirmation<T>(
+    actionId: string,
+    description: string
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.pendingActions.set(actionId, { resolve, reject })
+      info(`[USER-ACTION] Awaiting ${description}: ${actionId}`)
+    })
+  }
+
+  /**
+   * Handle incoming confirmation response
+   */
+  handleConfirmation<T>(actionId: string, value: T): boolean {
+    const pending = this.pendingActions.get(actionId)
+    if (!pending) {
+      warn(`[USER-ACTION] Unexpected confirmation for ${actionId}`)
+      return false
+    }
+
+    this.pendingActions.delete(actionId)
+    pending.resolve(value)
+    info(`[USER-ACTION] Confirmed: ${actionId}`)
+    return true
+  }
+
+  /**
+   * Cleanup all pending actions (e.g., on disconnect)
+   */
+  cleanup(): void {
+    for (const [actionId, pending] of this.pendingActions.entries()) {
+      pending.reject(new PluginDisconnectedError())
+      warn(`[USER-ACTION] Cancelled pending action: ${actionId}`)
+    }
+    this.pendingActions.clear()
+  }
+}

package/src/helpers/watcher.ts

@@ -0,0 +1,115 @@
+/**
+ * File watcher helper
+ *
+ * Thin wrapper around chokidar that normalizes file paths and emits
+ * only supported file types (ts, tsx, js, json). Controller never worries
+ * about addDir or platform separators.
+ */
+
+import chokidar from "chokidar"
+import fs from "fs/promises"
+import path from "path"
+import type { WatcherEvent } from "../types.js"
+import {
+  isSupportedExtension,
+  normalizePath,
+  sanitizeFilePath,
+} from "@code-link/shared"
+import { getRelativePath } from "../utils/paths.js"
+import { info, debug, warn } from "../utils/logging.js"
+
+export interface Watcher {
+  on(event: "change", handler: (event: WatcherEvent) => void): void
+  close(): Promise<void>
+}
+
+/**
+ * Initializes a file watcher for the given directory
+ */
+export function initWatcher(filesDir: string): Watcher {
+  const handlers: Array<(event: WatcherEvent) => void> = []
+
+  const watcher = chokidar.watch(filesDir, {
+    ignored: /(^|[\/\\])\../, // ignore dotfiles
+    persistent: true,
+    ignoreInitial: false, // Emit add events for existing files so we can sanitize them
+  })
+
+  info(`Watching directory: ${filesDir}`)
+
+  // Helper to emit normalized events
+  const emitEvent = async (
+    kind: "add" | "change" | "delete",
+    absolutePath: string
+  ): Promise<void> => {
+    if (!isSupportedExtension(absolutePath)) {
+      return
+    }
+
+    const rawRelativePath = normalizePath(
+      getRelativePath(filesDir, absolutePath)
+    )
+    // Don't capitalize - preserve exact file names as they exist
+    // This ensures 1:1 sync with Framer without modifying user's casing choices
+    const sanitized = sanitizeFilePath(rawRelativePath, false)
+    const relativePath = sanitized.path
+
+    // If the user created a file that doesn't match our sanitization rules,
+    // rename it on disk to match what can be synced.
+    let effectiveAbsolutePath = absolutePath
+    if (relativePath !== rawRelativePath && kind === "add") {
+      const newAbsolutePath = path.join(filesDir, relativePath)
+      try {
+        await fs.mkdir(path.dirname(newAbsolutePath), { recursive: true })
+        await fs.rename(absolutePath, newAbsolutePath)
+        info(
+          `Renamed ${rawRelativePath} -> ${relativePath} to match Framer rules`
+        )
+        effectiveAbsolutePath = newAbsolutePath
+      } catch (err) {
+        warn(
+          `Failed to rename ${rawRelativePath} to ${relativePath}, syncing with original name`,
+          err
+        )
+      }
+    }
+
+    let content: string | undefined
+    if (kind !== "delete") {
+      try {
+        content = await fs.readFile(effectiveAbsolutePath, "utf-8")
+      } catch (err) {
+        debug(`Failed to read file ${relativePath}:`, err)
+        return
+      }
+    }
+
+    const event: WatcherEvent = {
+      kind,
+      relativePath,
+      content,
+    }
+
+    debug(`Watcher event: ${kind} ${relativePath}`)
+
+    for (const handler of handlers) {
+      handler(event)
+    }
+  }
+
+  watcher.on("add", (filePath) => emitEvent("add", filePath))
+  watcher.on("change", (filePath) => emitEvent("change", filePath))
+  watcher.on("unlink", (filePath) => emitEvent("delete", filePath))
+
+  return {
+    on(event: "change", handler: (event: WatcherEvent) => void): void {
+      if (event === "change") {
+        handlers.push(handler)
+      }
+    },
+
+    async close(): Promise<void> {
+      await watcher.close()
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * Framer Code Link CLI - Next Generation
+ *
+ * Entry point for the CLI tool. Parses command-line arguments and starts
+ * the controller with the appropriate configuration.
+ */
+
+import { Command } from "commander"
+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"
+
+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: string, options) => {
+    // Auto-enable debug in development unless overridden
+    const isDev = process.env.NODE_ENV === "development"
+
+    if (options.logLevel) {
+      const levelMap: Record<string, LogLevel> = {
+        debug: LogLevel.DEBUG,
+        info: LogLevel.INFO,
+        warn: LogLevel.WARN,
+        error: LogLevel.ERROR,
+      }
+      const level = levelMap[options.logLevel.toLowerCase()]
+      if (level !== undefined) {
+        setLogLevel(level)
+      }
+    } else if (options.verbose || isDev) {
+      setLogLevel(LogLevel.DEBUG)
+    }
+
+    const port = getPortFromHash(projectHash)
+
+    const config: Config = {
+      port,
+      projectHash,
+      projectDir: null, // Will be set during handshake
+      filesDir: null, // Will be set during handshake
+      dangerouslyAutoDelete: options.dangerouslyAutoDelete ?? false,
+      explicitDir: options.dir,
+      explicitName: options.name,
+    }
+
+    if (config.dangerouslyAutoDelete) {
+      info(
+        "⚠️  Auto-delete mode enabled - files will be deleted without confirmation"
+      )
+    }
+
+    await start(config)
+  })
+
+program.parse()
+
+// Export for programmatic usage
+export { start } from "./controller.js"
+export type { Config } from "./types.js"

package/src/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Core types for the controller-centric CLI architecture
+ */
+
+import type { WebSocket } from "ws"
+import type { PendingDelete } from "@code-link/shared"
+
+// Configuration
+export interface Config {
+  port: number
+  projectHash: string
+  projectDir: string | null // Set during handshake if not already determined
+  filesDir: string | null // Set during handshake if not already determined
+  dangerouslyAutoDelete: boolean
+  explicitDir?: string // User-provided directory override
+  explicitName?: string // User-provided name override
+}
+
+// File representations
+export interface FileInfo {
+  name: string
+  content: string
+  modifiedAt?: number
+}
+
+export interface LocalFile {
+  relativePath: string
+  content: string
+  modifiedAt?: number
+}
+
+// Conflict detection
+export interface Conflict {
+  fileName: string
+  localContent: string
+  remoteContent: string
+  localModifiedAt?: number
+  remoteModifiedAt?: number
+  lastSyncedAt?: number // Timestamp of last successful sync from CLI perspective
+  /**
+   * True when the local file still matches the last persisted hash.
+   * Used for auto-resolution heuristics.
+   */
+  localClean?: boolean
+}
+
+export interface ConflictResolution {
+  conflicts: Conflict[]
+  writes: FileInfo[]
+  localOnly: FileInfo[]
+}
+
+// Watcher events
+export type WatcherEventKind = "add" | "change" | "delete"
+
+export interface WatcherEvent {
+  kind: WatcherEventKind
+  relativePath: string
+  content?: string
+}
+
+// Conflict version data
+export interface ConflictVersionRequest {
+  fileName: string
+  lastSyncedAt?: number
+}
+
+export interface ConflictVersionData {
+  fileName: string
+  latestRemoteVersionMs?: number
+}
+
+// WebSocket messages (incoming from plugin)
+export type IncomingMessage =
+  | { type: "handshake"; projectId: string; projectName: string }
+  | { type: "request-files" }
+  | { type: "file-list"; files: FileInfo[] }
+  | { type: "file-change"; fileName: string; content: string }
+  | { type: "file-delete"; fileNames: string[]; requireConfirmation?: boolean }
+  | { type: "delete-confirmed"; fileNames: string[] }
+  | { type: "delete-cancelled"; files: PendingDelete[] }
+  | { type: "file-synced"; fileName: string; remoteModifiedAt: number }
+  | {
+      type: "conflicts-resolved"
+      resolution: "local" | "remote"
+    }
+  | {
+      type: "conflict-version-response"
+      versions: ConflictVersionData[]
+    }
+  | { type: "error"; fileName?: string; message: string }
+
+// WebSocket messages (outgoing to plugin)
+export type OutgoingMessage =
+  | { type: "request-files" }
+  | { type: "file-list"; files: FileInfo[] }
+  | { type: "file-change"; fileName: string; content: string }
+  | {
+      type: "file-delete"
+      fileNames: string[]
+      requireConfirmation?: boolean
+    }
+  | { type: "conflicts-detected"; conflicts: Conflict[] }
+  | {
+      type: "conflict-version-request"
+      conflicts: ConflictVersionRequest[]
+    }

package/src/utils/file-metadata-cache.ts

@@ -0,0 +1,121 @@
+import {
+  hashFileContent,
+  loadPersistedState,
+  savePersistedState,
+  type PersistedFileState,
+} from "./state-persistence.js"
+
+export interface FileSyncMetadata {
+  localHash: string
+  lastSyncedHash: string
+  lastRemoteTimestamp?: number
+}
+
+export class FileMetadataCache {
+  private metadata = new Map<string, FileSyncMetadata>()
+  private persisted = new Map<string, PersistedFileState>()
+  private projectDir: string | null = null
+  private initialized = false
+  private pendingPersist: Promise<void> | null = null
+
+  async initialize(projectDir: string): Promise<void> {
+    if (this.initialized && this.projectDir === projectDir) {
+      return
+    }
+
+    this.projectDir = projectDir
+    const loaded = await loadPersistedState(projectDir)
+    this.persisted = loaded
+    this.metadata = new Map()
+
+    for (const [fileName, state] of loaded.entries()) {
+      this.metadata.set(fileName, {
+        localHash: state.contentHash,
+        lastSyncedHash: state.contentHash,
+        lastRemoteTimestamp: state.timestamp,
+      })
+    }
+
+    this.initialized = true
+  }
+
+  get(fileName: string): FileSyncMetadata | undefined {
+    return this.metadata.get(fileName)
+  }
+
+  has(fileName: string): boolean {
+    return this.metadata.has(fileName)
+  }
+
+  size(): number {
+    return this.metadata.size
+  }
+
+  getPersistedState(): Map<string, PersistedFileState> {
+    return this.persisted
+  }
+
+  recordRemoteWrite(
+    fileName: string,
+    content: string,
+    remoteModifiedAt: number
+  ): void {
+    const contentHash = hashFileContent(content)
+    this.metadata.set(fileName, {
+      localHash: contentHash,
+      lastSyncedHash: contentHash,
+      lastRemoteTimestamp: remoteModifiedAt,
+    })
+    this.persisted.set(fileName, {
+      contentHash,
+      timestamp: remoteModifiedAt,
+    })
+    this.schedulePersist()
+  }
+
+  recordSyncedSnapshot(
+    fileName: string,
+    contentHash: string,
+    remoteModifiedAt: number
+  ): void {
+    this.metadata.set(fileName, {
+      localHash: contentHash,
+      lastSyncedHash: contentHash,
+      lastRemoteTimestamp: remoteModifiedAt,
+    })
+    this.persisted.set(fileName, {
+      contentHash,
+      timestamp: remoteModifiedAt,
+    })
+    this.schedulePersist()
+  }
+
+  recordDelete(fileName: string): void {
+    this.metadata.delete(fileName)
+    this.persisted.delete(fileName)
+    this.schedulePersist()
+  }
+
+  async flush(): Promise<void> {
+    if (this.pendingPersist) {
+      await this.pendingPersist
+    }
+  }
+
+  private schedulePersist(): void {
+    if (!this.projectDir) {
+      return
+    }
+
+    if (!this.pendingPersist) {
+      this.pendingPersist = (async () => {
+        try {
+          await Promise.resolve()
+          await savePersistedState(this.projectDir as string, this.persisted)
+        } finally {
+          this.pendingPersist = null
+        }
+      })()
+    }
+  }
+}

package/src/utils/hashing.ts

@@ -0,0 +1,95 @@
+/**
+ * Hash tracking utilities for echo prevention
+ *
+ * The hash tracker prevents echo loops by remembering content hashes
+ * and skipping watcher events for files we just wrote.
+ */
+
+import { createHash } from "crypto"
+
+export interface HashTracker {
+  remember(filePath: string, content: string): void
+  shouldSkip(filePath: string, content: string): boolean
+  forget(filePath: string): void
+  clear(): void
+  markDelete(filePath: string): void
+  shouldSkipDelete(filePath: string): boolean
+  clearDelete(filePath: string): void
+}
+
+/**
+ * Creates a hash tracker instance for echo prevention
+ */
+export function createHashTracker(): HashTracker {
+  const hashes = new Map<string, string>()
+  const pendingDeletes = new Map<string, ReturnType<typeof setTimeout>>()
+
+  return {
+    remember(filePath: string, content: string): void {
+      const hash = hashContent(content)
+      hashes.set(filePath, hash)
+    },
+
+    shouldSkip(filePath: string, content: string): boolean {
+      const currentHash = hashContent(content)
+      const storedHash = hashes.get(filePath)
+      return storedHash === currentHash
+    },
+
+    forget(filePath: string): void {
+      hashes.delete(filePath)
+    },
+
+    clear(): void {
+      hashes.clear()
+    },
+
+    markDelete(filePath: string): void {
+      const existingTimer = pendingDeletes.get(filePath)
+      if (existingTimer) {
+        clearTimeout(existingTimer)
+      }
+
+      const timeout = setTimeout(() => {
+        pendingDeletes.delete(filePath)
+      }, 5000)
+
+      pendingDeletes.set(filePath, timeout)
+    },
+
+    shouldSkipDelete(filePath: string): boolean {
+      return pendingDeletes.has(filePath)
+    },
+
+    clearDelete(filePath: string): void {
+      const timeout = pendingDeletes.get(filePath)
+      if (timeout) {
+        clearTimeout(timeout)
+      }
+      pendingDeletes.delete(filePath)
+    },
+  }
+}
+
+/**
+ * Computes a hash of file content for comparison
+ */
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex")
+}
+
+/**
+ * Generate a deterministic port number from a project hash
+ * Port range: 3847-4096 (250 possible ports)
+ * Uses simple hash to match client-side implementation
+ */
+export function getPortFromHash(projectHash: string): number {
+  let hash = 0
+  for (let i = 0; i < projectHash.length; i++) {
+    const char = projectHash.charCodeAt(i)
+    hash = (hash << 5) - hash + char
+    hash = hash & hash // Convert to 32bit integer
+  }
+  const portOffset = Math.abs(hash) % 250
+  return 3847 + portOffset
+}