framer-code-link 0.2.0 → 0.2.1

package/src/helpers/user-actions.ts

@@ -1,158 +0,0 @@
-/**
- * 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 { debug, 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) {
-          debug(`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) {
-        debug("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 })
-      debug(`Awaiting ${description}: ${actionId}`)
-    })
-  }
-
-  /**
-   * Handle incoming confirmation response
-   */
-  handleConfirmation<T>(actionId: string, value: T): boolean {
-    const pending = this.pendingActions.get(actionId)
-    if (!pending) {
-      debug(`Unexpected confirmation for ${actionId}`)
-      return false
-    }
-
-    this.pendingActions.delete(actionId)
-    pending.resolve(value)
-    debug(`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())
-      debug(`Cancelled pending action: ${actionId}`)
-    }
-    this.pendingActions.clear()
-  }
-}

package/src/helpers/watcher.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, it, vi, afterEach } from "vitest"
-import fs from "fs/promises"
-import os from "os"
-import path from "path"
-import { initWatcher } from "./watcher.js"
-
-const createdWatchers: any[] = []
-
-vi.mock("chokidar", () => {
-  const createMockWatcher = () => {
-    const handlers: Record<string, Array<(filePath: string) => any>> = {
-      add: [],
-      change: [],
-      unlink: [],
-    }
-
-    return {
-      on(event: "add" | "change" | "unlink", handler: (file: string) => any) {
-        handlers[event]?.push(handler)
-        return this
-      },
-      async __emit(event: "add" | "change" | "unlink", filePath: string) {
-        for (const handler of handlers[event] ?? []) {
-          await handler(filePath)
-        }
-      },
-      close: vi.fn().mockResolvedValue(undefined),
-    }
-  }
-
-  const watch = vi.fn(() => {
-    const instance = createMockWatcher()
-    createdWatchers.push(instance)
-    return instance
-  })
-
-  return { default: { watch }, watch }
-})
-
-describe("initWatcher", () => {
-  afterEach(() => {
-    createdWatchers.length = 0
-  })
-
-  it("ignores unsupported extensions and sanitizes added files", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "framer-watcher-"))
-    const events: any[] = []
-    const watcher = initWatcher(tmpDir)
-    watcher.on("change", (event) => events.push(event))
-    const rawWatcher = createdWatchers.at(-1)!
-
-    const unsupportedPath = path.join(tmpDir, "note.txt")
-    await fs.writeFile(unsupportedPath, "hello", "utf-8")
-    await rawWatcher.__emit("add", unsupportedPath)
-    expect(events).toHaveLength(0)
-
-    const rawPath = path.join(tmpDir, "bad name!.tsx")
-    await fs.writeFile(rawPath, "export const X = 1;", "utf-8")
-    await rawWatcher.__emit("add", rawPath)
-
-    const addEvent = events.find((e) => e.kind === "add")
-    expect(addEvent).toBeDefined()
-    expect(addEvent?.relativePath).toBe("bad_name_.tsx")
-    expect(addEvent?.content).toContain("export const X")
-
-    const renamedPath = path.join(tmpDir, "bad_name_.tsx")
-    await expect(fs.readFile(renamedPath, "utf-8")).resolves.toContain(
-      "export const X"
-    )
-
-    await watcher.close()
-    await fs.rm(tmpDir, { recursive: true, force: true })
-  })
-})

package/src/helpers/watcher.ts

@@ -1,110 +0,0 @@
-/**
- * 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 { 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
-  })
-
-  debug(`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)
-        debug(`Renamed ${rawRelativePath} -> ${relativePath}`)
-        effectiveAbsolutePath = newAbsolutePath
-      } catch (err) {
-        warn(`Failed to rename ${rawRelativePath}`, 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

@@ -1,111 +0,0 @@
-#!/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, banner, warn } from "./utils/logging.js"
-import { getPortFromHash } from "@code-link/shared"
-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 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: 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"
-
-    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)
-
-    // Show startup banner
-    banner("0.1.3", port)
-
-    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) {
-      warn(
-        "Auto-delete mode enabled - files will be deleted without confirmation"
-      )
-    }
-
-    try {
-      await start(config)
-    } catch (err) {
-      // Error already logged, exit cleanly
-      process.exit(1)
-    }
-  })
-
-program.parse()
-
-// Export for programmatic usage
-export { start } from "./controller.js"
-export type { Config } from "./types.js"

package/src/types.ts

@@ -1,112 +0,0 @@
-/**
- * Core types for the controller-centric CLI architecture
- */
-
-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
-// Deletions are represented by null content
-// For AI: Do NOT add remoteDeletes/localDeletes arrays - use localContent/remoteContent === null
-export interface Conflict {
-  fileName: string
-  /** null means the file was deleted locally */
-  localContent: string | null
-  /** null means the file was deleted in Framer */
-  remoteContent: string | null
-  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[]
-  unchanged: 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[]
-    }
-  | { type: "sync-complete" }

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

@@ -1,121 +0,0 @@
-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
-        }
-      })()
-    }
-  }
-}