framer-code-link 0.17.0 → 0.18.0

package/dist/index.mjs

@@ -3,10 +3,13 @@ import { createRequire } from "node:module";
 import { Command } from "commander";
 import fs from "fs/promises";
 import path from "path";
-import { WebSocketServer } from "ws";
 import { createHash } from "crypto";
-import { execSync } from "child_process";
-import fs$1 from "fs";
+import { execFile, execSync } from "child_process";
+import nodeFs from "fs";
+import os from "os";
+import { promisify } from "util";
+import https from "node:https";
+import { WebSocketServer } from "ws";
 import { setupTypeAcquisition } from "@typescript/ata";
 import ts from "typescript";
 import { fileURLToPath } from "node:url";
@@ -142,7 +145,7 @@ function pathJoin(...parts) {
 	});
 	return res;
 }
-function normalizePath$1(filePath) {
+function normalizePath(filePath) {
 	if (!filePath) return "";
 	const isAbsolute = filePath.startsWith("/");
 	const segments = filePath.replace(/\\/g, "/").split("/");
@@ -159,12 +162,24 @@ function normalizePath$1(filePath) {
 	if (isAbsolute) return `/${normalized}`;
 	return normalized;
 }
+/**
+* Use when you only want path normalization.
+* Preserves the caller-provided extension so `Foo.ts` and `Foo.tsx` stay distinct.
+*/
 function normalizeCodeFilePath(filePath) {
-	const normalized = normalizePath$1(filePath);
+	const normalized = normalizePath(filePath);
 	return normalized.startsWith("/") ? normalized.slice(1) : normalized;
 }
-function canonicalFileName(filePath) {
-	return normalizeCodeFilePath(filePath);
+function ensureExtension(filePath, extension = ".tsx") {
+	const normalized = normalizeCodeFilePath(filePath);
+	return /\.(tsx?|jsx?|json)$/i.test(normalized) ? normalized : `${normalized}${extension}`;
+}
+/**
+* Use when the path must match the code-file API contract.
+* Normalizes the path and ensures a default `.tsx` extension when one is missing.
+*/
+function normalizeCodeFilePathWithExtension(filePath) {
+	return ensureExtension(filePath);
 }
 function sanitizeFilePath(input, capitalizeReactComponent = true) {
 	const trimmed = input.trim();
@@ -188,7 +203,7 @@ function isSupportedExtension$1(filePath) {
 * Use this for Map keys on operating systems where "File.tsx" and "file.tsx" are the same file.
 */
 function fileKeyForLookup(filePath) {
-	return canonicalFileName(filePath).toLowerCase();
+	return normalizeCodeFilePath(filePath).toLowerCase();
 }
 /**
 * Pluralize a word based on count
@@ -220,6 +235,11 @@ function getPortFromHash(projectHash) {
 	return 3847 + Math.abs(hash) % 250;
 }
 
+//#endregion
+//#region ../code-link-shared/src/types.ts
+/** Custom close code sent when a new plugin tab replaces the active one. */
+const CLOSE_CODE_REPLACED = 4001;
+
 //#endregion
 //#region ../../node_modules/picocolors/picocolors.js
 var require_picocolors = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -475,28 +495,249 @@ function resetDisconnectState() {
 	hadRecentDisconnect = false;
 }
 
+//#endregion
+//#region src/helpers/certs.ts
+/**
+* Certificate management for WSS support.
+*
+* Downloads FiloSottile's mkcert binary on first run, then shells out to it
+* to generate and trust a local CA + server certificate for wss://localhost.
+*
+* The mkcert binary is SHA-256 verified before execution (update
+* MKCERT_CHECKSUMS when bumping MKCERT_VERSION). The CA key is user-only;
+* never share or commit the cert directory.
+*
+* Certs and the mkcert binary are cached in ~/.framer/code-link/.
+*/
+const execFileAsync = promisify(execFile);
+/** Keep in sync with MKCERT_CHECKSUMS below. */
+const MKCERT_VERSION = "v1.4.4";
+const CERT_DIR = process.env.FRAMER_CODE_LINK_CERT_DIR ?? path.join(os.homedir(), ".framer", "code-link");
+const MKCERT_BIN_NAME = process.platform === "win32" ? "mkcert.exe" : "mkcert";
+const MKCERT_BIN_PATH = path.join(CERT_DIR, MKCERT_BIN_NAME);
+const ROOT_CA_CERT_PATH = path.join(CERT_DIR, "rootCA.pem");
+const ROOT_CA_KEY_PATH = path.join(CERT_DIR, "rootCA-key.pem");
+const SERVER_KEY_PATH = path.join(CERT_DIR, "localhost-key.pem");
+const SERVER_CERT_PATH = path.join(CERT_DIR, "localhost.pem");
+/**
+* SHA-256 checksums for mkcert v1.4.4 release binaries, keyed by "platform-arch".
+* These must be updated whenever MKCERT_VERSION changes.
+* Source: https://github.com/FiloSottile/mkcert/releases/tag/v1.4.4
+*/
+const MKCERT_CHECKSUMS = {
+	"darwin-amd64": "a32dfab51f1845d51e810db8e47dcf0e6b51ae3422426514bf5a2b8302e97d4e",
+	"darwin-arm64": "c8af0df44bce04359794dad8ea28d750437411d632748049d08644ffb66a60c6",
+	"linux-amd64": "6d31c65b03972c6dc4a14ab429f2928300518b26503f58723e532d1b0a3bbb52",
+	"linux-arm64": "b98f2cc69fd9147fe4d405d859c57504571adec0d3611c3eefd04107c7ac00d0",
+	"windows-amd64": "d2660b50a9ed59eada480750561c96abc2ed4c9a38c6a24d93e30e0977631398",
+	"windows-arm64": "793747256c562622d40127c8080df26add2fb44c50906ce9db63b42a5280582e"
+};
+/** Env vars passed to every mkcert invocation. */
+const MKCERT_ENV = {
+	...process.env,
+	CAROOT: CERT_DIR,
+	JAVA_HOME: "",
+	...process.platform === "darwin" ? { TRUST_STORES: "system" } : {}
+};
+/**
+* Returns a TLS cert bundle for the WSS server, or null if generation fails.
+* On first run, downloads mkcert, installs a local CA into trust stores, and
+* generates a server cert for localhost.
+*/
+async function getOrCreateCerts() {
+	try {
+		await fs.mkdir(CERT_DIR, { recursive: true });
+		const mkcertPath = await ensureMkcertBinary();
+		const rootCAState = await syncRootCA(mkcertPath);
+		if (rootCAState !== "unchanged") await invalidateServerCerts(rootCAState);
+		const existingKey = await loadFile(SERVER_KEY_PATH);
+		const existingCert = await loadFile(SERVER_CERT_PATH);
+		if (existingKey && existingCert) {
+			debug("Loaded existing server certificates from disk");
+			return {
+				key: existingKey,
+				cert: existingCert
+			};
+		}
+		if (existingKey || existingCert) await invalidateIncompleteServerBundle();
+		status("Generating local certificates to connect securely. You may be asked for your password.");
+		await generateCerts(mkcertPath);
+		return {
+			key: await fs.readFile(SERVER_KEY_PATH, "utf-8"),
+			cert: await fs.readFile(SERVER_CERT_PATH, "utf-8")
+		};
+	} catch (err) {
+		error(`Failed to set up TLS certificates: ${err instanceof Error ? err.message : String(err)}`);
+		return null;
+	}
+}
+function getDownloadInfo() {
+	const platformMap = {
+		darwin: "darwin",
+		linux: "linux",
+		win32: "windows"
+	};
+	const archMap = {
+		x64: "amd64",
+		arm64: "arm64"
+	};
+	const platform = platformMap[process.platform];
+	const arch = archMap[process.arch];
+	if (!platform || !arch) throw new Error(`Unsupported platform: ${process.platform}/${process.arch}. Install mkcert manually: https://github.com/FiloSottile/mkcert#installation`);
+	const key = `${platform}-${arch}`;
+	const expectedChecksum = MKCERT_CHECKSUMS[key];
+	if (!expectedChecksum) throw new Error(`No checksum available for mkcert ${key}. Install mkcert manually: https://github.com/FiloSottile/mkcert#installation`);
+	return {
+		url: `https://github.com/FiloSottile/mkcert/releases/download/${MKCERT_VERSION}/${`mkcert-${MKCERT_VERSION}-${platform}-${arch}${process.platform === "win32" ? ".exe" : ""}`}`,
+		expectedChecksum
+	};
+}
+async function ensureMkcertBinary() {
+	const { url, expectedChecksum } = getDownloadInfo();
+	try {
+		await fs.access(MKCERT_BIN_PATH, nodeFs.constants.X_OK);
+		if (await verifyFileChecksum(MKCERT_BIN_PATH, expectedChecksum)) {
+			debug("mkcert binary already available and verified");
+			return MKCERT_BIN_PATH;
+		}
+		warn("Cached mkcert binary failed checksum verification, re-downloading...");
+	} catch {}
+	debug(`Downloading mkcert from ${url}`);
+	status("Downloading mkcert for certificate generation...");
+	try {
+		const response = await fetch(url, { redirect: "follow" });
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		const buffer = Buffer.from(await response.arrayBuffer());
+		const actualChecksum = createHash("sha256").update(buffer).digest("hex");
+		if (actualChecksum !== expectedChecksum) throw new Error(`mkcert binary checksum mismatch — the download may have been tampered with.\n  Expected: ${expectedChecksum}\n  Actual:   ${actualChecksum}`);
+		await fs.writeFile(MKCERT_BIN_PATH, buffer, { mode: 493 });
+		debug(`mkcert binary saved to ${MKCERT_BIN_PATH}`);
+		return MKCERT_BIN_PATH;
+	} catch (err) {
+		await fs.rm(MKCERT_BIN_PATH, { force: true });
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to download mkcert: ${message}\nYou can install it manually: https://github.com/FiloSottile/mkcert#installation\nThen run: mkcert -install && mkcert -key-file "${SERVER_KEY_PATH}" -cert-file "${SERVER_CERT_PATH}" localhost 127.0.0.1`);
+	}
+}
+async function generateCerts(mkcertPath) {
+	debug("Running mkcert to install the local root CA...");
+	try {
+		await execFileAsync(mkcertPath, ["-install"], { env: MKCERT_ENV });
+	} catch (err) {
+		throw new Error(`Failed to install mkcert root CA into the system trust store. If you canceled the password prompt, rerun this command and allow the install.
+mkcert error: ${formatMkcertError(err)}`);
+	}
+	debug("Running mkcert to generate the localhost server certificate...");
+	try {
+		await execFileAsync(mkcertPath, [
+			"-key-file",
+			SERVER_KEY_PATH,
+			"-cert-file",
+			SERVER_CERT_PATH,
+			"localhost",
+			"127.0.0.1"
+		], { env: MKCERT_ENV });
+	} catch (err) {
+		if (await loadFile(SERVER_KEY_PATH) || await loadFile(SERVER_CERT_PATH)) await invalidateIncompleteServerBundle();
+		throw new Error(`Failed to generate localhost TLS certificate and key with mkcert.
+mkcert error: ${formatMkcertError(err)}\nPlease rerun:\n  mkcert -key-file "${SERVER_KEY_PATH}" -cert-file "${SERVER_CERT_PATH}" localhost 127.0.0.1`);
+	}
+	const [generatedKey, generatedCert] = await Promise.all([loadFile(SERVER_KEY_PATH), loadFile(SERVER_CERT_PATH)]);
+	if (generatedKey && generatedCert) {
+		debug("CA installed and server certificate generated successfully");
+		return;
+	}
+	if (generatedKey || generatedCert) await invalidateIncompleteServerBundle();
+	throw new Error(`Failed to generate localhost TLS certificate and key with mkcert. Please ensure mkcert is installed and rerun:
+  mkcert -install && mkcert -key-file "${SERVER_KEY_PATH}" -cert-file "${SERVER_CERT_PATH}" localhost 127.0.0.1`);
+}
+async function syncRootCA(mkcertPath) {
+	const existingRootCert = await loadFile(ROOT_CA_CERT_PATH);
+	const existingRootKey = await loadFile(ROOT_CA_KEY_PATH);
+	const { stdout } = await execFileAsync(mkcertPath, ["-CAROOT"], { env: {
+		...process.env,
+		JAVA_HOME: ""
+	} });
+	const defaultCAROOT = stdout.trim();
+	if (!defaultCAROOT || defaultCAROOT === CERT_DIR) return existingRootCert && existingRootKey ? "unchanged" : "missing";
+	const defaultRootCert = await loadFile(path.join(defaultCAROOT, "rootCA.pem"));
+	const defaultRootKey = await loadFile(path.join(defaultCAROOT, "rootCA-key.pem"));
+	if (!defaultRootCert || !defaultRootKey) return existingRootCert && existingRootKey ? "unchanged" : "missing";
+	if (existingRootCert === defaultRootCert && existingRootKey === defaultRootKey) return "unchanged";
+	await Promise.all([fs.rm(ROOT_CA_CERT_PATH, { force: true }), fs.rm(ROOT_CA_KEY_PATH, { force: true })]);
+	await fs.writeFile(ROOT_CA_CERT_PATH, defaultRootCert, { mode: 420 });
+	await fs.writeFile(ROOT_CA_KEY_PATH, defaultRootKey, { mode: 384 });
+	return existingRootCert && existingRootKey ? "updated" : "copied";
+}
+async function invalidateServerCerts(rootCAState) {
+	const reasons = {
+		copied: "Copied an existing mkcert root CA into the Code Link cache",
+		updated: "Detected a different mkcert root CA and refreshed the Code Link cache",
+		missing: "No cached mkcert root CA was available for the existing server certificate"
+	};
+	if (!(await loadFile(SERVER_KEY_PATH) !== null || await loadFile(SERVER_CERT_PATH) !== null)) return;
+	await fs.rm(SERVER_KEY_PATH, { force: true });
+	await fs.rm(SERVER_CERT_PATH, { force: true });
+	debug(`${reasons[rootCAState]}; removed stale localhost certificate`);
+}
+async function invalidateIncompleteServerBundle() {
+	await fs.rm(SERVER_KEY_PATH, { force: true });
+	await fs.rm(SERVER_CERT_PATH, { force: true });
+	warn("Found an incomplete localhost certificate bundle; regenerating it");
+}
+async function verifyFileChecksum(filePath, expectedHash) {
+	const data = await fs.readFile(filePath);
+	return createHash("sha256").update(data).digest("hex") === expectedHash;
+}
+async function loadFile(filePath) {
+	try {
+		return await fs.readFile(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+function formatMkcertError(err) {
+	if (err instanceof Error) {
+		const stdout = "stdout" in err && typeof err.stdout === "string" ? err.stdout.trim() : "";
+		const output = ["stderr" in err && typeof err.stderr === "string" ? err.stderr.trim() : "", stdout].filter(Boolean).join("\n");
+		return output ? `${err.message}\n${output}` : err.message;
+	}
+	return String(err);
+}
+
 //#endregion
 //#region src/helpers/connection.ts
 /**
-* Initializes a WebSocket server and returns a connection interface
-* Returns a Promise that resolves when the server is ready, or rejects on startup errors
+* WebSocket connection helper
+*
+* Wrapper around ws.Server that normalizes handshake and surfaces callbacks.
+*/
+/**
+* Initializes a WSS (TLS) WebSocket server and returns a connection interface.
+* Returns a Promise that resolves when the server is ready, or rejects on startup errors.
 */
-function initConnection(port) {
+function initConnection(port, certs) {
 	return new Promise((resolve, reject) => {
-		const wss = new WebSocketServer({ port });
 		const handlers = {};
 		let connectionId = 0;
 		let isReady = false;
+		const httpsServer = https.createServer({
+			key: certs.key,
+			cert: certs.cert
+		});
+		const wss = new WebSocketServer({ server: httpsServer });
 		wss.on("error", (err) => {
+			error(`WebSocket server error: ${err.message}`);
+			handlers.onError?.(err);
+		});
+		const handleError = (err) => {
 			if (!isReady) {
 				if (err.code === "EADDRINUSE") {
 					error(`Port ${port} is already in use.`);
-					error(`This usually means another instance of Code Link is already running.`);
-					error(``);
-					error(`To fix this:`);
-					error(`  1. Close any other terminal running Code Link for this project`);
-					error(`  2. Or run: lsof -i :${port} | grep LISTEN`);
-					error(`     Then kill the process: kill -9 <PID>`);
+					info(`This usually means another instance of Code Link is already running.`);
+					info(``);
+					info(`To fix this:`);
+					info(`  Close any other terminal running Code Link for this project`);
 					reject(/* @__PURE__ */ new Error(`Port ${port} is already in use`));
 				} else {
 					error(`Failed to start WebSocket server: ${err.message}`);
@@ -505,10 +746,11 @@ function initConnection(port) {
 				return;
 			}
 			error(`WebSocket server error: ${err.message}`);
-		});
-		wss.on("listening", () => {
+			handlers.onError?.(err);
+		};
+		const handleListening = () => {
 			isReady = true;
-			debug(`WebSocket server listening on port ${port}`);
+			debug(`WSS server listening on port ${port}`);
 			let activeClient = null;
 			wss.on("connection", (ws) => {
 				const connId = ++connectionId;
@@ -524,7 +766,7 @@ function initConnection(port) {
 							activeClient = ws;
 							if (previousActiveClient && previousActiveClient !== activeClient) {
 								debug(`Replacing active client with conn ${connId}`);
-								if (previousActiveClient.readyState === READY_STATE.OPEN || previousActiveClient.readyState === READY_STATE.CONNECTING) previousActiveClient.close();
+								if (previousActiveClient.readyState === READY_STATE.OPEN || previousActiveClient.readyState === READY_STATE.CONNECTING) previousActiveClient.close(CLOSE_CODE_REPLACED);
 							}
 							handlers.onHandshake?.(ws, message);
 						} else if (handshakeReceived && activeClient === ws) handlers.onMessage?.(message);
@@ -564,9 +806,13 @@ function initConnection(port) {
 				},
 				close() {
 					wss.close();
+					httpsServer.close();
 				}
 			});
-		});
+		};
+		httpsServer.on("error", handleError);
+		httpsServer.on("listening", handleListening);
+		httpsServer.listen(port);
 	});
 }
 /**
@@ -608,41 +854,6 @@ function sendMessage(socket, message) {
 	});
 }
 
-//#endregion
-//#region src/utils/node-paths.ts
-/**
-* Path manipulation utilities
-*/
-/**
-* Gets a relative path from the project directory
-*/
-function getRelativePath(projectDir, absolutePath) {
-	return path.relative(projectDir, absolutePath);
-}
-/**
-* Normalizes a file path by:
-* - Converting backslashes to forward slashes
-* - Resolving . and .. segments
-* - Removing duplicate slashes
-*/
-function normalizePath(filePath) {
-	if (!filePath) return "";
-	const isAbsolute = filePath.startsWith("/");
-	const segments = filePath.replace(/\\/g, "/").split("/");
-	const stack = [];
-	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;
-}
-
 //#endregion
 //#region src/utils/state-persistence.ts
 /**
@@ -654,18 +865,8 @@ function normalizePath(filePath) {
 */
 const STATE_FILE_NAME = ".framer-sync-state.json";
 const CURRENT_VERSION = 1;
-const SUPPORTED_EXTENSIONS$1 = [
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".json"
-];
-const DEFAULT_EXTENSION$1 = ".tsx";
-function normalizePersistedFileName(fileName) {
-	let normalized = normalizePath(fileName.trim());
-	if (!SUPPORTED_EXTENSIONS$1.some((ext) => normalized.toLowerCase().endsWith(ext))) normalized = `${normalized}${DEFAULT_EXTENSION$1}`;
-	return normalized;
+function persistedFileKey(fileName) {
+	return fileKeyForLookup(normalizeCodeFilePathWithExtension(fileName));
 }
 /**
 * Hash file content to detect changes
@@ -687,7 +888,7 @@ async function loadPersistedState(projectDir) {
 			return result;
 		}
 		for (const [fileName, state] of Object.entries(parsed.files)) {
-			const normalizedName = normalizePersistedFileName(fileName);
+			const normalizedName = persistedFileKey(fileName);
 			if (normalizedName !== fileName) debug(`Normalized persisted key "${fileName}" -> "${normalizedName}" for compatibility`);
 			result.set(normalizedName, state);
 		}
@@ -755,7 +956,7 @@ async function listFiles(filesDir) {
 				continue;
 			}
 			if (!isSupportedExtension(entry.name)) continue;
-			const sanitizedPath = sanitizeFilePath(normalizePath$1(path.relative(filesDir, entryPath)), false).path;
+			const sanitizedPath = sanitizeFilePath(normalizePath(path.relative(filesDir, entryPath)), false).path;
 			try {
 				const [content, stats] = await Promise.all([fs.readFile(entryPath, "utf-8"), fs.stat(entryPath)]);
 				files.push({
@@ -1000,9 +1201,9 @@ function resolveRemoteReference(filesDir, rawName) {
 	};
 }
 function sanitizeRelativePath(relativePath) {
-	const trimmed = normalizePath$1(relativePath.trim());
+	const trimmed = normalizePath(relativePath.trim());
 	const sanitized = sanitizeFilePath(SUPPORTED_EXTENSIONS.some((ext) => trimmed.toLowerCase().endsWith(ext)) ? trimmed : `${trimmed}${DEFAULT_EXTENSION}`, false);
-	const normalized = normalizePath$1(sanitized.path);
+	const normalized = normalizePath(sanitized.path);
 	return {
 		relativePath: normalized,
 		extension: sanitized.extension || path.extname(normalized) || DEFAULT_EXTENSION
@@ -1061,6 +1262,7 @@ function tryGitInit(projectDir) {
 			debug("Already in a repository, skipping git init");
 			return false;
 		}
+		status("Initializing git repository...");
 		execSync("git init", {
 			stdio: "ignore",
 			cwd: projectDir
@@ -1082,7 +1284,7 @@ function tryGitInit(projectDir) {
 		return true;
 	} catch (e) {
 		if (didInit) try {
-			fs$1.rmSync(path.join(projectDir, ".git"), {
+			nodeFs.rmSync(path.join(projectDir, ".git"), {
 				recursive: true,
 				force: true
 			});
@@ -1379,7 +1581,8 @@ var Installer = class {
 		try {
 			await this.ata(filteredContent);
 		} catch (err) {
-			warn(`ATA failed for ${fileName}`, err);
+			warn(`Type fetching failed for ${fileName}`);
+			debug(`ATA error for ${fileName}:`, err);
 		}
 	}
 	/**
@@ -1502,7 +1705,7 @@ declare module "*.json"
 				private: true,
 				description: "Framer files synced with framer-code-link"
 			};
-			await fs.writeFile(packagePath, JSON.stringify(pkg, null, 2));
+			await fs.writeFile(packagePath, JSON.stringify(pkg, null, 4));
 			debug("Created package.json");
 		}
 	}
@@ -1634,11 +1837,12 @@ async function fetchWithRetry(url, init, retries = MAX_FETCH_RETRIES) {
 			if (isRetryable) checkFatalFailure(urlString);
 			if (attempt < retries && isRetryable) {
 				const delay = attempt * 1e3;
-				warn(`Fetch failed (${error.cause?.code ?? error.message}) for ${urlString}, retrying in ${delay}ms...`);
+				debug(`Fetch failed for ${urlString}, retrying...`, error);
 				await new Promise((resolve) => setTimeout(resolve, delay));
 				continue;
 			}
-			warn(`Fetch failed for ${urlString}`, error);
+			warn(`Fetch failed for ${urlString}`);
+			debug(`Fetch error details:`, error);
 			throw error;
 		}
 	}
@@ -1783,6 +1987,18 @@ function validateIncomingChange(fileMeta, currentMode) {
 	};
 }
 
+//#endregion
+//#region src/utils/node-paths.ts
+/**
+* Path manipulation utilities
+*/
+/**
+* Gets a relative path from the project directory
+*/
+function getRelativePath(projectDir, absolutePath) {
+	return path.relative(projectDir, absolutePath);
+}
+
 //#endregion
 //#region src/helpers/watcher.ts
 /**
@@ -1790,47 +2006,244 @@ function validateIncomingChange(fileMeta, currentMode) {
 *
 * Wrapper around chokidar that normalizes file paths and filters to ts, tsx, js, json.
 */
+const RENAME_BUFFER_MS = 100;
+function findUniqueHashMatch(pendingItems, contentHash) {
+	let matchingKey;
+	for (const [key, pending] of pendingItems) {
+		if (pending.contentHash !== contentHash) continue;
+		if (matchingKey !== void 0) return;
+		matchingKey = key;
+	}
+	return matchingKey;
+}
+function matchPendingAddForDelete(contentHash, pendingAdds) {
+	if (!contentHash) return null;
+	const matchingAddKey = findUniqueHashMatch(pendingAdds, contentHash);
+	if (!matchingAddKey) return null;
+	const pendingAdd = pendingAdds.get(matchingAddKey);
+	if (!pendingAdd) return null;
+	return {
+		key: matchingAddKey,
+		pendingAdd
+	};
+}
+function matchPendingDeleteForAdd(contentHash, pendingDeletes) {
+	const matchingDeleteKey = findUniqueHashMatch(pendingDeletes, contentHash);
+	if (!matchingDeleteKey) return null;
+	const pendingDelete = pendingDeletes.get(matchingDeleteKey);
+	if (!pendingDelete) return null;
+	return {
+		key: matchingDeleteKey,
+		pendingDelete
+	};
+}
 /**
 * Initializes a file watcher for the given directory
 */
 function initWatcher(filesDir) {
 	const handlers = [];
+	const contentHashCache = /* @__PURE__ */ new Map();
+	const pendingDeletes = /* @__PURE__ */ new Map();
+	const pendingAdds = /* @__PURE__ */ new Map();
+	const recentSanitizations = /* @__PURE__ */ new Set();
 	const watcher = chokidar.watch(filesDir, {
 		ignored: /(^|[/\\])\.\./,
 		persistent: true,
 		ignoreInitial: false
 	});
 	debug(`Watching directory: ${filesDir}`);
-	const emitEvent = async (kind, absolutePath) => {
-		if (!isSupportedExtension$1(absolutePath)) return;
-		const rawRelativePath = normalizePath$1(getRelativePath(filesDir, absolutePath));
-		const relativePath = sanitizeFilePath(rawRelativePath, false).path;
+	const dispatchEvent = (event) => {
+		let eventToDispatch = event;
+		if (event.kind === "rename" && event.relativePath === event.oldRelativePath) {
+			if (event.content === void 0) {
+				warn(`Skipping invalid same-path rename without content: ${event.relativePath}`);
+				return;
+			}
+			debug(`Converting same-path rename to change: ${event.relativePath}`);
+			eventToDispatch = {
+				kind: "change",
+				relativePath: event.relativePath,
+				content: event.content
+			};
+		}
+		debug(`Watcher event: ${eventToDispatch.kind} ${eventToDispatch.relativePath}`);
+		for (const handler of handlers) handler(eventToDispatch);
+	};
+	/**
+	* Resolves the relative path identity for a watcher event.
+	* Only "add" may rewrite that identity by successfully sanitizing on disk.
+	*/
+	const resolveRelativePath = async (kind, absolutePath) => {
+		if (!isSupportedExtension$1(absolutePath)) return null;
+		const rawRelativePath = normalizePath(getRelativePath(filesDir, absolutePath));
+		let relativePath = rawRelativePath;
 		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);
+		if (kind === "add") {
+			const sanitized = sanitizeFilePath(rawRelativePath, false);
+			if (sanitized.path !== rawRelativePath) {
+				const nextRelativePath = sanitized.path;
+				const newAbsolutePath = path.join(filesDir, nextRelativePath);
+				try {
+					await fs.mkdir(path.dirname(newAbsolutePath), { recursive: true });
+					await fs.rename(absolutePath, newAbsolutePath);
+					debug(`Renamed ${rawRelativePath} -> ${nextRelativePath}`);
+					relativePath = nextRelativePath;
+					effectiveAbsolutePath = newAbsolutePath;
+					recentSanitizations.add(rawRelativePath);
+					recentSanitizations.add(nextRelativePath);
+					setTimeout(() => {
+						recentSanitizations.delete(rawRelativePath);
+						recentSanitizations.delete(nextRelativePath);
+					}, RENAME_BUFFER_MS * 3);
+				} catch (err) {
+					warn(`Failed to rename ${rawRelativePath}`, err);
+					return {
+						relativePath: rawRelativePath,
+						effectiveAbsolutePath: absolutePath
+					};
+				}
 			}
 		}
+		return {
+			relativePath,
+			effectiveAbsolutePath
+		};
+	};
+	const emitEvent = async (kind, absolutePath) => {
+		const rawRelPath = normalizePath(getRelativePath(filesDir, absolutePath));
+		if (recentSanitizations.delete(rawRelPath)) {
+			debug(`Suppressing sanitization echo: ${kind} ${rawRelPath}`);
+			return;
+		}
+		const resolved = await resolveRelativePath(kind, absolutePath);
+		if (!resolved) return;
+		const { relativePath, effectiveAbsolutePath } = resolved;
+		if (kind === "delete") {
+			const lastHash = contentHashCache.get(relativePath);
+			contentHashCache.delete(relativePath);
+			const samePathPendingAdd = pendingAdds.get(relativePath);
+			if (samePathPendingAdd) {
+				clearTimeout(samePathPendingAdd.timer);
+				pendingAdds.delete(relativePath);
+				try {
+					const latestContent = await fs.readFile(effectiveAbsolutePath, "utf-8");
+					const latestHash = hashFileContent(latestContent);
+					contentHashCache.set(relativePath, latestHash);
+					dispatchEvent({
+						kind: "change",
+						relativePath,
+						content: latestContent
+					});
+				} catch {
+					if (samePathPendingAdd.previousContentHash !== void 0) dispatchEvent({
+						kind: "delete",
+						relativePath
+					});
+					else debug(`Suppressing transient add+delete: ${relativePath}`);
+				}
+				return;
+			}
+			const matchedAdd = matchPendingAddForDelete(lastHash, pendingAdds);
+			if (matchedAdd) {
+				clearTimeout(matchedAdd.pendingAdd.timer);
+				pendingAdds.delete(matchedAdd.key);
+				dispatchEvent({
+					kind: "rename",
+					relativePath: matchedAdd.pendingAdd.relativePath,
+					oldRelativePath: relativePath,
+					content: matchedAdd.pendingAdd.content
+				});
+				return;
+			}
+			if (lastHash) {
+				const timer = setTimeout(() => {
+					pendingDeletes.delete(relativePath);
+					dispatchEvent({
+						kind: "delete",
+						relativePath
+					});
+				}, RENAME_BUFFER_MS);
+				pendingDeletes.set(relativePath, {
+					relativePath,
+					contentHash: lastHash,
+					timer
+				});
+			} else dispatchEvent({
+				kind: "delete",
+				relativePath
+			});
+			return;
+		}
 		let content;
-		if (kind !== "delete") try {
+		try {
 			content = await fs.readFile(effectiveAbsolutePath, "utf-8");
 		} catch (err) {
 			debug(`Failed to read file ${relativePath}:`, err);
 			return;
 		}
-		const event = {
+		const previousContentHash = contentHashCache.get(relativePath);
+		const contentHash = hashFileContent(content);
+		contentHashCache.set(relativePath, contentHash);
+		if (kind === "add") {
+			const samePathPendingDelete = pendingDeletes.get(relativePath);
+			if (samePathPendingDelete) {
+				clearTimeout(samePathPendingDelete.timer);
+				pendingDeletes.delete(relativePath);
+				dispatchEvent({
+					kind: "change",
+					relativePath,
+					content
+				});
+				return;
+			}
+			const matchedDelete = matchPendingDeleteForAdd(contentHash, pendingDeletes);
+			if (matchedDelete) {
+				clearTimeout(matchedDelete.pendingDelete.timer);
+				pendingDeletes.delete(matchedDelete.key);
+				dispatchEvent({
+					kind: "rename",
+					relativePath,
+					oldRelativePath: matchedDelete.pendingDelete.relativePath,
+					content
+				});
+				return;
+			}
+			const existingPendingAdd = pendingAdds.get(relativePath);
+			if (existingPendingAdd) clearTimeout(existingPendingAdd.timer);
+			const retainedPreviousContentHash = existingPendingAdd ? existingPendingAdd.previousContentHash : previousContentHash;
+			const timer = setTimeout(() => {
+				pendingAdds.delete(relativePath);
+				dispatchEvent({
+					kind: "add",
+					relativePath,
+					content
+				});
+			}, RENAME_BUFFER_MS);
+			pendingAdds.set(relativePath, {
+				relativePath,
+				contentHash,
+				content,
+				timer,
+				previousContentHash: retainedPreviousContentHash
+			});
+			return;
+		}
+		const pendingAdd = pendingAdds.get(relativePath);
+		if (pendingAdd) {
+			clearTimeout(pendingAdd.timer);
+			pendingAdds.delete(relativePath);
+			dispatchEvent({
+				kind: "add",
+				relativePath,
+				content
+			});
+			return;
+		}
+		dispatchEvent({
 			kind,
 			relativePath,
 			content
-		};
-		debug(`Watcher event: ${kind} ${relativePath}`);
-		for (const handler of handlers) handler(event);
+		});
 	};
 	watcher.on("add", (filePath) => {
 		emitEvent("add", filePath);
@@ -1846,6 +2259,12 @@ function initWatcher(filesDir) {
 			handlers.push(handler);
 		},
 		async close() {
+			for (const pending of pendingDeletes.values()) clearTimeout(pending.timer);
+			for (const pending of pendingAdds.values()) clearTimeout(pending.timer);
+			pendingDeletes.clear();
+			pendingAdds.clear();
+			contentHashCache.clear();
+			recentSanitizations.clear();
 			await watcher.close();
 		}
 	};
@@ -1948,45 +2367,42 @@ var FileMetadataCache = class {
 function createHashTracker() {
 	const hashes = /* @__PURE__ */ new Map();
 	const pendingDeletes = /* @__PURE__ */ new Map();
+	const keyFor = (filePath) => normalizeCodeFilePathWithExtension(filePath);
 	return {
 		remember(filePath, content) {
-			const hash = hashContent(content);
-			hashes.set(filePath, hash);
+			const hash = hashFileContent(content);
+			hashes.set(keyFor(filePath), hash);
 		},
 		shouldSkip(filePath, content) {
-			const currentHash = hashContent(content);
-			return hashes.get(filePath) === currentHash;
+			const currentHash = hashFileContent(content);
+			return hashes.get(keyFor(filePath)) === currentHash;
 		},
 		forget(filePath) {
-			hashes.delete(filePath);
+			hashes.delete(keyFor(filePath));
 		},
 		clear() {
 			hashes.clear();
 		},
 		markDelete(filePath) {
-			const existingTimer = pendingDeletes.get(filePath);
+			const key = keyFor(filePath);
+			const existingTimer = pendingDeletes.get(key);
 			if (existingTimer) clearTimeout(existingTimer);
 			const timeout = setTimeout(() => {
-				pendingDeletes.delete(filePath);
+				pendingDeletes.delete(key);
 			}, 5e3);
-			pendingDeletes.set(filePath, timeout);
+			pendingDeletes.set(key, timeout);
 		},
 		shouldSkipDelete(filePath) {
-			return pendingDeletes.has(filePath);
+			return pendingDeletes.has(keyFor(filePath));
 		},
 		clearDelete(filePath) {
-			const timeout = pendingDeletes.get(filePath);
+			const key = keyFor(filePath);
+			const timeout = pendingDeletes.get(key);
 			if (timeout) clearTimeout(timeout);
-			pendingDeletes.delete(filePath);
+			pendingDeletes.delete(key);
 		}
 	};
 }
-/**
-* Computes a SHA256 hash of file content for comparison
-*/
-function hashContent(content) {
-	return createHash("sha256").update(content).digest("hex");
-}
 
 //#endregion
 //#region src/utils/project.ts
@@ -1994,7 +2410,7 @@ function toPackageName(name) {
 	return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
 }
 function toDirectoryName(name) {
-	return name.replace(/[^a-zA-Z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
+	return name.replace(/[^a-zA-Z0-9 -]/g, "-").trim().replace(/^-+|-+$/g, "").replace(/-+/g, "-");
 }
 async function getProjectHashFromCwd() {
 	try {
@@ -2034,7 +2450,7 @@ async function findOrCreateProjectDirectory(options) {
 		shortProjectHash: shortId,
 		framerProjectName: projectName
 	};
-	await fs.writeFile(path.join(projectDirectory, "package.json"), JSON.stringify(pkg, null, 2));
+	await fs.writeFile(path.join(projectDirectory, "package.json"), JSON.stringify(pkg, null, 4));
 	return {
 		directory: projectDirectory,
 		created: true,
@@ -2399,6 +2815,21 @@ function transition(state, event) {
 						fileNames: [relativePath]
 					});
 					break;
+				case "rename":
+					if (content === void 0 || !event.event.oldRelativePath) {
+						effects.push(log("warn", `Rename event missing data: ${relativePath}`));
+						return {
+							state,
+							effects
+						};
+					}
+					effects.push(log("debug", `Local rename detected: ${event.event.oldRelativePath} → ${relativePath}`), {
+						type: "SEND_FILE_RENAME",
+						oldFileName: event.event.oldRelativePath,
+						newFileName: relativePath,
+						content
+					});
+					break;
 			}
 			return {
 				state,
@@ -2487,7 +2918,7 @@ function transition(state, event) {
 * Returns additional events that should be processed (e.g., CONFLICTS_DETECTED after DETECT_CONFLICTS)
 */
 async function executeEffect(effect, context) {
-	const { config, hashTracker, installer, fileMetadataCache, userActions, syncState } = context;
+	const { config, hashTracker, installer, fileMetadataCache, pendingRenameConfirmations, userActions, syncState } = context;
 	switch (effect.type) {
 		case "INIT_WORKSPACE":
 			if (!config.projectDir) {
@@ -2582,10 +3013,18 @@ async function executeEffect(effect, context) {
 		case "UPDATE_FILE_METADATA": {
 			if (!config.filesDir || !config.projectDir) return [];
 			const currentContent = await readFileSafe(effect.fileName, config.filesDir);
-			if (currentContent !== null) {
-				const contentHash = hashFileContent(currentContent);
+			const pendingRenameConfirmation = pendingRenameConfirmations.get(normalizeCodeFilePathWithExtension(effect.fileName));
+			const syncedContent = currentContent ?? pendingRenameConfirmation?.content ?? null;
+			if (syncedContent !== null) {
+				const contentHash = hashFileContent(syncedContent);
 				fileMetadataCache.recordSyncedSnapshot(effect.fileName, contentHash, effect.remoteModifiedAt);
 			}
+			if (pendingRenameConfirmation) {
+				hashTracker.forget(pendingRenameConfirmation.oldFileName);
+				fileMetadataCache.recordDelete(pendingRenameConfirmation.oldFileName);
+				if (currentContent !== null) hashTracker.remember(effect.fileName, currentContent);
+				pendingRenameConfirmations.delete(normalizeCodeFilePathWithExtension(effect.fileName));
+			}
 			return [];
 		}
 		case "SEND_LOCAL_CHANGE": {
@@ -2612,6 +3051,37 @@ async function executeEffect(effect, context) {
 			}
 			return [];
 		}
+		case "SEND_FILE_RENAME": {
+			const normalizedNewFileName = normalizeCodeFilePathWithExtension(effect.newFileName);
+			if (hashTracker.shouldSkip(normalizedNewFileName, effect.content) && hashTracker.shouldSkipDelete(effect.oldFileName)) {
+				hashTracker.forget(normalizedNewFileName);
+				hashTracker.clearDelete(effect.oldFileName);
+				debug(`Skipping echoed rename ${effect.oldFileName} -> ${effect.newFileName}`);
+				return [];
+			}
+			try {
+				if (!syncState.socket) {
+					warn(`No socket available to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
+					return [];
+				}
+				if (!await sendMessage(syncState.socket, {
+					type: "file-rename",
+					oldFileName: effect.oldFileName,
+					newFileName: normalizedNewFileName,
+					content: effect.content
+				})) {
+					warn(`Failed to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
+					return [];
+				}
+				pendingRenameConfirmations.set(normalizeCodeFilePathWithExtension(effect.newFileName), {
+					oldFileName: effect.oldFileName,
+					content: effect.content
+				});
+			} catch (err) {
+				warn(`Failed to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
+			}
+			return [];
+		}
 		case "LOCAL_INITIATED_FILE_DELETE": {
 			const filesToDelete = effect.fileNames.filter((fileName) => {
 				const shouldSkip = hashTracker.shouldSkipDelete(fileName);
@@ -2682,6 +3152,7 @@ async function start(config) {
 	status("Waiting for Plugin connection...");
 	const hashTracker = createHashTracker();
 	const fileMetadataCache = new FileMetadataCache();
+	const pendingRenameConfirmations = /* @__PURE__ */ new Map();
 	let installer = null;
 	let syncState = {
 		mode: "disconnected",
@@ -2703,13 +3174,24 @@ async function start(config) {
 				hashTracker,
 				installer,
 				fileMetadataCache,
+				pendingRenameConfirmations,
 				userActions,
 				syncState
 			});
 			for (const followUpEvent of followUpEvents) await processEvent(followUpEvent);
 		}
 	}
-	const connection = await initConnection(config.port);
+	const certs = await getOrCreateCerts();
+	if (!certs) {
+		error("Failed to generate TLS certificates. The Framer plugin requires a secure (wss://) connection.");
+		info("");
+		info("To fix this:");
+		info("  1. Re-run this command — certificate generation is often a one-time issue");
+		info(`  2. Manually delete "${String(CERT_DIR)}" and try again`);
+		info("");
+		throw new Error("TLS certificate generation failed");
+	}
+	const connection = await initConnection(config.port, certs);
 	connection.on("handshake", (client, message) => {
 		debug(`Received handshake: ${message.projectName} (${message.projectId})`);
 		const expectedShort = shortProjectHash(config.projectHash);
@@ -2727,6 +3209,7 @@ async function start(config) {
 					return;
 				}
 				debug(`New handshake received in ${syncState.mode} mode, resetting sync state`);
+				pendingRenameConfirmations.clear();
 				await processEvent({ type: "DISCONNECT" });
 			}
 			if (!wasRecentlyDisconnected() && !didShowDisconnect()) success(`Connected to ${message.projectName}`);
@@ -2808,6 +3291,10 @@ async function start(config) {
 					remoteModifiedAt: message.remoteModifiedAt
 				};
 				break;
+			case "error":
+				if (message.fileName) pendingRenameConfirmations.delete(normalizeCodeFilePathWithExtension(message.fileName));
+				warn(message.message);
+				return;
 			case "conflicts-resolved":
 				event = {
 					type: "CONFLICTS_RESOLVED",
@@ -2844,6 +3331,7 @@ async function start(config) {
 			status("Disconnected, waiting to reconnect...");
 		});
 		(async () => {
+			pendingRenameConfirmations.clear();
 			await processEvent({ type: "DISCONNECT" });
 			userActions.cleanup();
 		})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-code-link",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "CLI tool for syncing Framer code components - controller-centric architecture",
   "main": "dist/index.mjs",
   "type": "module",