framer-code-link 0.1.0

package/src/utils/imports.ts

@@ -0,0 +1,62 @@
+/**
+ * Utilities for parsing import statements and extracting package information.
+ */
+
+export interface ImportInfo {
+  type: "npm" | "url"
+  name: string
+  raw: string
+}
+
+/**
+ * Extract npm and URL-based imports from source code.
+ */
+export function extractImports(code: string): ImportInfo[] {
+  const imports: ImportInfo[] = []
+  const seen = new Set<string>()
+
+  const npmRegex =
+    /import\s+(?:(?:\*\s+as\s+\w+)|(?:\w+)|(?:\{[^}]*\}))\s+from\s+['"]([^.\/][^'"]+)['"]/g
+  const urlRegex =
+    /import\s+(?:(?:\*\s+as\s+\w+)|(?:\w+)|(?:\{[^}]*\}))\s+from\s+['"]https?:\/\/[^'"]+['"]/g
+
+  let match: RegExpExecArray | null
+
+  while ((match = npmRegex.exec(code)) !== null) {
+    const pkgName = match[1]
+    const normalized = pkgName.startsWith("@")
+      ? pkgName.split("/").slice(0, 2).join("/")
+      : pkgName.split("/")[0]
+
+    if (!seen.has(normalized)) {
+      seen.add(normalized)
+      imports.push({
+        type: "npm",
+        name: normalized,
+        raw: match[0],
+      })
+    }
+  }
+
+  while ((match = urlRegex.exec(code)) !== null) {
+    const pkgName = extractPackageFromUrl(match[0])
+    if (pkgName && !seen.has(pkgName)) {
+      seen.add(pkgName)
+      imports.push({
+        type: "url",
+        name: pkgName,
+        raw: match[0],
+      })
+    }
+  }
+
+  return imports
+}
+
+/**
+ * Attempt to derive an npm-style package specifier from a URL import.
+ */
+export function extractPackageFromUrl(url: string): string | null {
+  const match = url.match(/\/(@?[^@\/]+(?:\/[^@\/]+)?)/)
+  return match?.[1] ?? null
+}

package/src/utils/logging.ts

@@ -0,0 +1,47 @@
+/**
+ * Logging utilities for consistent output
+ */
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+let currentLevel = LogLevel.INFO
+
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level
+}
+
+export function debug(message: string, ...args: unknown[]): void {
+  if (currentLevel <= LogLevel.DEBUG) {
+    console.debug(`[DEBUG] ${message}`, ...args)
+  }
+}
+
+export function info(message: string, ...args: unknown[]): void {
+  if (currentLevel <= LogLevel.INFO) {
+    console.info(`[INFO] ${message}`, ...args)
+  }
+}
+
+export function warn(message: string, ...args: unknown[]): void {
+  if (currentLevel <= LogLevel.WARN) {
+    console.warn(`[WARN] ${message}`, ...args)
+  }
+}
+
+export function error(message: string, ...args: unknown[]): void {
+  if (currentLevel <= LogLevel.ERROR) {
+    console.error(`[ERROR] ${message}`, ...args)
+  }
+}
+
+export function success(message: string, ...args: unknown[]): void {
+  if (currentLevel <= LogLevel.INFO) {
+    console.log(`✓ ${message}`, ...args)
+  }
+}
+

package/src/utils/paths.ts

@@ -0,0 +1,76 @@
+/**
+ * Path manipulation utilities
+ */
+
+import path from "path"
+import { fileURLToPath } from "url"
+
+/**
+ * Resolves a path relative to the project directory
+ */
+export function resolveProjectPath(
+  projectDir: string,
+  relativePath: string
+): string {
+  return path.resolve(projectDir, relativePath)
+}
+
+/**
+ * Gets a relative path from the project directory
+ */
+export function getRelativePath(
+  projectDir: string,
+  absolutePath: string
+): string {
+  return path.relative(projectDir, absolutePath)
+}
+
+/**
+ * Ensures a directory path ends with a separator
+ */
+export function ensureTrailingSlash(dirPath: string): string {
+  return dirPath.endsWith(path.sep) ? dirPath : dirPath + path.sep
+}
+
+/**
+ * Gets the directory name from an import.meta.url (ESM)
+ */
+export function getDirname(importMetaUrl: string): string {
+  return path.dirname(fileURLToPath(importMetaUrl))
+}
+
+/**
+ * Normalizes a file path by:
+ * - Converting backslashes to forward slashes
+ * - Resolving . and .. segments
+ * - Removing duplicate slashes
+ */
+export function normalizePath(filePath: string): string {
+  if (!filePath) return ""
+
+  const isAbsolute = filePath.startsWith("/")
+  const segments = filePath.replace(/\\/g, "/").split("/")
+  const stack: string[] = []
+
+  for (const segment of segments) {
+    if (!segment || segment === ".") {
+      continue
+    }
+
+    if (segment === "..") {
+      if (stack.length > 0) {
+        stack.pop()
+      }
+      continue
+    }
+
+    stack.push(segment)
+  }
+
+  const normalized = stack.join("/")
+  if (isAbsolute) {
+    return `/${normalized}`
+  }
+
+  return normalized
+}

package/src/utils/project.ts

@@ -0,0 +1,94 @@
+import fs from "fs/promises"
+import path from "path"
+
+interface PackageJson {
+  framerProjectId?: string
+  framerProjectName?: string
+  name?: string
+  version?: string
+  [key: string]: unknown
+}
+
+export function toPackageName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, "-")
+}
+
+export async function findOrCreateProjectDir(
+  projectHash: string,
+  projectName?: string,
+  explicitDir?: string
+): Promise<string> {
+  if (explicitDir) {
+    const resolved = path.resolve(explicitDir)
+    await fs.mkdir(path.join(resolved, "files"), { recursive: true })
+    return resolved
+  }
+
+  const cwd = process.cwd()
+  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 projectDir = path.join(cwd, dirName || projectHash.slice(0, 6))
+
+  await fs.mkdir(path.join(projectDir, "files"), { recursive: true })
+  const pkg: PackageJson = {
+    name: dirName || projectHash,
+    version: "1.0.0",
+    private: true,
+    framerProjectId: projectHash,
+    framerProjectName: projectName,
+  }
+  await fs.writeFile(
+    path.join(projectDir, "package.json"),
+    JSON.stringify(pkg, null, 2)
+  )
+
+  return projectDir
+}
+
+async function findExistingProjectDir(
+  baseDir: string,
+  projectHash: string
+): Promise<string | null> {
+  const candidate = path.join(baseDir, "package.json")
+  if (await matchesProject(candidate, projectHash)) {
+    return baseDir
+  }
+
+  const entries = await fs.readdir(baseDir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const dir = path.join(baseDir, entry.name)
+    if (await matchesProject(path.join(dir, "package.json"), projectHash)) {
+      return dir
+    }
+  }
+
+  return null
+}
+
+async function matchesProject(
+  packageJsonPath: string,
+  projectHash: string
+): Promise<boolean> {
+  try {
+    const content = await fs.readFile(packageJsonPath, "utf-8")
+    const pkg = JSON.parse(content) as PackageJson
+    return pkg.framerProjectId === projectHash
+  } catch {
+    return false
+  }
+}

package/src/utils/state-persistence.ts

@@ -0,0 +1,138 @@
+/**
+ * State persistence helper
+ *
+ * Persists last sync timestamps along with content hashes.
+ * We only trust persisted timestamps if the file content hasn't changed
+ * (hash matches), because that means the file wasn't edited while CLI was offline.
+ */
+
+import fs from "fs/promises"
+import path from "path"
+import { createHash } from "crypto"
+import { debug, warn } from "./logging.js"
+import { normalizePath } from "./paths.js"
+
+export interface PersistedFileState {
+  timestamp: number // Remote modified timestamp from last sync
+  contentHash: string // Hash of content when we received the sync confirmation
+}
+
+interface PersistedState {
+  version: number
+  files: Record<string, PersistedFileState>
+}
+
+const STATE_FILE_NAME = ".framer-sync-state.json"
+// Version 2: State machine rewrite - only stores hashes/timestamps for local edit detection
+// Breaking change: users must delete old .framer-sync-state.json files
+const CURRENT_VERSION = 2
+const SUPPORTED_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".json"]
+const DEFAULT_EXTENSION = ".tsx"
+
+export function normalizePersistedFileName(fileName: string): string {
+  let normalized = normalizePath(fileName.trim())
+  if (
+    !SUPPORTED_EXTENSIONS.some((ext) => normalized.toLowerCase().endsWith(ext))
+  ) {
+    normalized = `${normalized}${DEFAULT_EXTENSION}`
+  }
+  return normalized
+}
+
+/**
+ * Hash file content to detect changes
+ */
+export function hashFileContent(content: string): string {
+  return createHash("sha256").update(content, "utf-8").digest("hex")
+}
+
+/**
+ * Load persisted state from disk
+ */
+export async function loadPersistedState(
+  projectDir: string
+): Promise<Map<string, PersistedFileState>> {
+  const statePath = path.join(projectDir, STATE_FILE_NAME)
+  const result = new Map<string, PersistedFileState>()
+
+  try {
+    const data = await fs.readFile(statePath, "utf-8")
+    const parsed: PersistedState = JSON.parse(data)
+
+    if (parsed.version !== CURRENT_VERSION) {
+      warn(
+        `State file version mismatch (expected ${CURRENT_VERSION}, got ${parsed.version}). Ignoring persisted state.`
+      )
+      return result
+    }
+
+    for (const [fileName, state] of Object.entries(parsed.files)) {
+      const normalizedName = normalizePersistedFileName(fileName)
+      if (normalizedName !== fileName) {
+        debug(
+          `Normalized persisted key "${fileName}" -> "${normalizedName}" for compatibility`
+        )
+      }
+      result.set(normalizedName, state)
+    }
+
+    debug(`Loaded persisted state for ${result.size} files`)
+    return result
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      debug("No persisted state found (first run)")
+      return result
+    }
+    warn("Failed to load persisted state:", err)
+    return result
+  }
+}
+
+/**
+ * Save current state to disk
+ */
+export async function savePersistedState(
+  projectDir: string,
+  state: Map<string, PersistedFileState>
+): Promise<void> {
+  const statePath = path.join(projectDir, STATE_FILE_NAME)
+
+  const persistedState: PersistedState = {
+    version: CURRENT_VERSION,
+    files: Object.fromEntries(state.entries()),
+  }
+
+  try {
+    await fs.writeFile(statePath, JSON.stringify(persistedState, null, 2))
+    debug(`Saved persisted state for ${state.size} files`)
+  } catch (err) {
+    warn("Failed to save persisted state:", err)
+  }
+}
+
+/**
+ * Validate persisted timestamp against current file content
+ * Returns the timestamp only if the content hash matches (file unchanged)
+ */
+export function validatePersistedTimestamp(
+  persistedState: PersistedFileState | undefined,
+  currentContent: string
+): number | null {
+  if (!persistedState) {
+    return null
+  }
+
+  const currentHash = hashFileContent(currentContent)
+
+  if (currentHash === persistedState.contentHash) {
+    debug(
+      `Hash matches for persisted state - trusting timestamp ${persistedState.timestamp}`
+    )
+    return persistedState.timestamp
+  }
+
+  debug(
+    "Hash mismatch for persisted state - file was edited while CLI was offline"
+  )
+  return null
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}
+

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    pool: "threads", // Fork pool trips tinypool on Node 25; threads stay stable
+  },
+})
+