@terrazzo/cli 2.0.0-beta.3 → 2.0.0-beta.4

package/dist/index.js

@@ -9,10 +9,12 @@ import { ViteNodeRunner } from "vite-node/client";
 import { ViteNodeServer } from "vite-node/server";
 import chokidar from "chokidar";
 import yamlToMomoa from "yaml-to-momoa";
-import { spawn } from "node:child_process";
 import fs$1 from "node:fs/promises";
-import { confirm, intro, multiselect, outro, select, spinner } from "@clack/prompts";
 import { isAlias, pluralize } from "@terrazzo/token-tools";
+import { merge } from "merge-anything";
+import { camelCase } from "scule";
+import { spawn } from "node:child_process";
+import { confirm, intro, multiselect, outro, select, spinner } from "@clack/prompts";
 import { detect } from "detect-package-manager";
 import { generate } from "escodegen";
 import { parseModule } from "meriyah";
@@ -377,21 +379,584 @@ async function checkCmd({ config, logger, positionals }) {
 function helpCmd() {
 	console.log(`tz
   [commands]
-    build           Build token artifacts from tokens.json
-      --watch, -w   Watch tokens.json for changes and recompile
-      --no-lint     Disable linters running on build
-    check [path]    Check tokens.json for errors and run linters
-    lint [path]     (alias of check)
-    init            Create a starter tokens.json file
-    lab             Manage your tokens with a web interface
+    build            Build token artifacts from tokens.json
+      --watch, -w    Watch tokens.json for changes and recompile
+      --no-lint      Disable linters running on build
+    check [path]     Check tokens.json for errors and run linters
+    lint [path]      (alias of check)
+    init             Create a starter tokens.json file
+    lab              Manage your tokens with a web interface
+    import [path]    Import from a Figma Design file
+      --o [file]     Save imported JSON
+      --unpublished  Include unpublished Variables
+      --skip-styles  Don’t import styles
+      --skip-variables
+                     Don’t import variables
 
   [options]
-    --help          Show this message
-    --config, -c    Path to config (default: ./terrazzo.config.ts)
-    --quiet         Suppress warnings
+    --help           Show this message
+    --config, -c     Path to config (default: ./terrazzo.config.ts)
+    --quiet          Suppress warnings
 `);
 }
 
+//#endregion
+//#region src/import/figma/lib.ts
+const KEY = ":key";
+const FILE_KEY = ":file_key";
+const API = {
+	file: `https://api.figma.com/v1/files/${FILE_KEY}`,
+	fileNodes: `https://api.figma.com/v1/files/${FILE_KEY}/nodes`,
+	fileStyles: `https://api.figma.com/v1/files/${FILE_KEY}/styles`,
+	localVariables: `https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
+	publishedVariables: `https://api.figma.com/v1/files/${FILE_KEY}/variables/published`,
+	styles: `https://api.figma.com/v1/styles/${KEY}`
+};
+/** Wrapper around camelCase to handle more cases */
+function formatName(name) {
+	return camelCase(name.replace(/\s+/g, "-"));
+}
+const nf = new Intl.NumberFormat("en-us");
+/** Wrapper around camelCase to handle more cases */
+function formatNumber(number) {
+	return nf.format(number);
+}
+/** Get File ID from design URL */
+function getFileID(url) {
+	return url.match(/^https:\/\/(www\.)?figma\.com\/design\/([^/]+)/)?.[2];
+}
+/** /v1/files/:file_key */
+async function getFile(fileKey, { logger }) {
+	const res = await fetch(API.file.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text()}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/nodes */
+async function getFileNodes(fileKey, { ids, logger }) {
+	let url = API.fileNodes.replace(FILE_KEY, fileKey);
+	if (ids?.length) url += `?ids=${ids.join(",")}`;
+	const res = await fetch(url, {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text()}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/styles */
+async function getFileStyles(fileKey, { logger }) {
+	const res = await fetch(API.fileStyles.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text()}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/variables/local */
+async function getFileLocalVariables(fileKey, { logger }) {
+	const res = await fetch(API.localVariables.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/variables/published */
+async function getFilePublishedVariables(fileKey, { logger }) {
+	const res = await fetch(API.publishedVariables.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text}`
+	});
+	return await res.json();
+}
+
+//#endregion
+//#region src/import/figma/styles.ts
+/** /v1/files/:file_key/styles */
+async function getStyles(fileKey, { logger, unpublished }) {
+	const result = {
+		count: 0,
+		code: { sets: { styles: { sources: [{}] } } }
+	};
+	const styleNodeIDs = /* @__PURE__ */ new Set();
+	const stylesByID = /* @__PURE__ */ new Map();
+	if (unpublished) {
+		const styles = await getFile(fileKey, { logger });
+		for (const [id, style] of Object.entries(styles.styles)) {
+			styleNodeIDs.add(id);
+			stylesByID.set(id, style);
+		}
+	} else {
+		const styles = await getFileStyles(fileKey, { logger });
+		for (const style of styles.meta.styles) {
+			styleNodeIDs.add(style.node_id);
+			stylesByID.set(style.node_id, style);
+		}
+	}
+	const fileNodes = await getFileNodes(fileKey, {
+		ids: [...styleNodeIDs],
+		logger
+	});
+	result.count += styleNodeIDs.size;
+	for (const [id, s] of stylesByID) {
+		const styleNode = fileNodes.nodes[id];
+		if (!styleNode) {
+			logger.warn({
+				group: "import",
+				message: `Style ${s.name} not found in file nodes. Does it need to be published?`
+			});
+			continue;
+		}
+		const styleType = "style_type" in s ? s.style_type : s.styleType;
+		const tokenBase = {
+			$type: void 0,
+			$description: s.description || void 0,
+			$value: void 0,
+			$extensions: { "figma.com": {
+				name: s.name,
+				node_id: id,
+				created_at: "created_at" in s ? s.created_at : void 0,
+				updated_at: "updated_at" in s ? s.updated_at : void 0
+			} }
+		};
+		switch (styleType) {
+			case "FILL": {
+				const $value = fillStyle(styleNode.document);
+				if (!$value) logger.error({
+					group: "import",
+					message: `Could not parse fill for ${s.name}`,
+					continueOnError: true
+				});
+				if (Array.isArray($value)) tokenBase.$type = "gradient";
+				else tokenBase.$type = "color";
+				tokenBase.$value = $value;
+				break;
+			}
+			case "TEXT": {
+				const $value = textStyle(styleNode.document);
+				if (!$value) logger.error({
+					group: "import",
+					message: `Could not parse text for ${s.name}`,
+					continueOnError: true
+				});
+				tokenBase.$type = "typography";
+				tokenBase.$value = $value;
+				break;
+			}
+			case "EFFECT": {
+				const $value = effectStyle(styleNode.document);
+				if (!$value) logger.error({
+					group: "import",
+					message: `Could not parse effect for ${s.name}`,
+					continueOnError: true
+				});
+				tokenBase.$type = "shadow";
+				tokenBase.$value = $value;
+				break;
+			}
+			case "GRID": {
+				const layoutGrids = gridStyles(styleNode.document);
+				if (!layoutGrids) logger.error({
+					group: "import",
+					message: `Could not parse grid for ${s.name}`,
+					continueOnError: true
+				});
+				let node = result.code.sets.styles.sources[0];
+				const path = s.name.split("/").map(formatName);
+				const name = path.pop();
+				for (const key of path) {
+					if (!(key in node)) node[key] = {};
+					node = node[key];
+				}
+				node[name] = layoutGrids;
+				break;
+			}
+		}
+		if (tokenBase.$type !== void 0) {
+			let node = result.code.sets.styles.sources[0];
+			const path = s.name.split("/").map(formatName);
+			const name = path.pop();
+			for (const key of path) {
+				if (!(key in node)) node[key] = {};
+				node = node[key];
+			}
+			node[name] = tokenBase;
+		}
+	}
+	return result;
+}
+/** Return a shadow token from an effect */
+function effectStyle(node) {
+	if ("effects" in node) {
+		const shadows = node.effects.filter((e) => e.type === "DROP_SHADOW" || e.type === "INNER_SHADOW");
+		if (shadows.length) return shadows.map((s) => ({
+			inset: s.type === "INNER_SHADOW",
+			offsetX: {
+				value: s.offset.x,
+				unit: "px"
+			},
+			offsetY: {
+				value: s.offset.y,
+				unit: "px"
+			},
+			blur: {
+				value: s.radius,
+				unit: "px"
+			},
+			spread: {
+				value: s.spread ?? 0,
+				unit: "px"
+			},
+			color: {
+				colorSpace: "srgb",
+				components: [
+					s.color.r,
+					s.color.g,
+					s.color.b
+				],
+				alpha: s.color.a
+			}
+		}));
+	}
+}
+/** Return a color or gradient token from a fill */
+function fillStyle(node) {
+	if ("fills" in node) for (const fill of node.fills) switch (fill.type) {
+		case "SOLID": return {
+			colorSpace: "srgb",
+			components: [
+				fill.color.r,
+				fill.color.g,
+				fill.color.b
+			],
+			alpha: fill.color.a
+		};
+		case "GRADIENT_LINEAR":
+		case "GRADIENT_RADIAL":
+		case "GRADIENT_ANGULAR":
+		case "GRADIENT_DIAMOND": return fill.gradientStops.map((stop) => ({
+			position: stop.position,
+			color: {
+				colorSpace: "srgb",
+				components: [
+					stop.color.r,
+					stop.color.g,
+					stop.color.b
+				],
+				alpha: stop.color.a
+			}
+		}));
+	}
+}
+/** Return a dimension token from grid */
+function gridStyles(node) {
+	if (!("layoutGrids" in node) || !node.layoutGrids?.length) return;
+	const values = {};
+	for (const grid of node.layoutGrids) {
+		const pattern = grid.pattern.toLowerCase();
+		if (values[pattern]) continue;
+		values[pattern] = {
+			sectionSize: {
+				$type: "dimension",
+				$value: {
+					value: grid.sectionSize,
+					unit: "px"
+				}
+			},
+			gutterSize: {
+				$type: "dimension",
+				$value: {
+					value: grid.sectionSize,
+					unit: "px"
+				}
+			}
+		};
+		if (grid.count > 0) values[pattern].count = {
+			$type: "number",
+			$value: grid.count
+		};
+	}
+	return values;
+}
+/** Return a typography token from text */
+function textStyle(node) {
+	if (!("style" in node)) return;
+	return {
+		fontFamily: [node.style.fontFamily],
+		fontWeight: node.style.fontWeight,
+		fontStyle: node.style.fontStyle,
+		fontSize: node.style.fontSize ? {
+			value: node.style.fontSize,
+			unit: "px"
+		} : {
+			value: 1,
+			unit: "em"
+		},
+		letterSpacing: {
+			value: node.style.letterSpacing ?? 0,
+			unit: "px"
+		},
+		lineHeight: "lineHeightPercentFontSize" in node.style ? node.style.lineHeightPercentFontSize : "lineHeightPx" in node.style ? {
+			value: node.style.lineHeightPx,
+			unit: "px"
+		} : 1
+	};
+}
+
+//#endregion
+//#region src/import/figma/variables.ts
+/** /v1/files/:file_key/variables/published | /v1/files/:file_key/variables/local */
+async function getVariables(fileKey, { logger, unpublished, matchers }) {
+	const result = {
+		count: 0,
+		remoteCount: 0,
+		code: {
+			sets: {},
+			modifiers: {}
+		}
+	};
+	const allVariables = {};
+	const variableCollections = {};
+	let finalVariables = {};
+	const modeIDToName = {};
+	const local = await getFileLocalVariables(fileKey, { logger });
+	for (const id of Object.keys(local.meta.variables)) {
+		if (local.meta.variables[id].hiddenFromPublishing) continue;
+		allVariables[id] = local.meta.variables[id];
+	}
+	for (const id of Object.keys(local.meta.variableCollections)) {
+		variableCollections[id] = local.meta.variableCollections[id];
+		for (const mode of local.meta.variableCollections[id].modes) modeIDToName[mode.modeId] = formatName(mode.name);
+	}
+	if (unpublished) finalVariables = allVariables;
+	else {
+		const published = await getFilePublishedVariables(fileKey, { logger });
+		for (const id of Object.keys(published.meta.variables)) finalVariables[id] = allVariables[id];
+	}
+	const remoteIDs = /* @__PURE__ */ new Set();
+	for (const id of Object.keys(finalVariables)) {
+		const variable = finalVariables[id];
+		const collection = variableCollections[variable.variableCollectionId];
+		const collectionName = formatName(collection.name);
+		const hasMultipleModes = collection.modes.length > 1;
+		if (hasMultipleModes) {
+			if (!(collectionName in result.code.modifiers)) result.code.modifiers[collectionName] = {
+				contexts: Object.fromEntries(collection.modes.map((m) => [formatName(m.name), [{}]])),
+				default: modeIDToName[collection.defaultModeId]
+			};
+		} else if (!(collectionName in result.code.sets)) result.code.sets[collectionName] = { sources: [{}] };
+		const matches = matchers.fontFamily?.test(variable.name) && "fontFamily" || matchers.fontWeight?.test(variable.name) && "fontWeight" || matchers.number?.test(variable.name) && "number" || void 0;
+		for (const [modeID, value] of Object.entries(variable.valuesByMode)) {
+			const modeName = modeIDToName[modeID];
+			let node = result.code;
+			if (hasMultipleModes) {
+				if (!(modeName in result.code.modifiers[collectionName].contexts)) result.code.modifiers[collectionName].contexts[modeName] = [{}];
+				node = result.code.modifiers[collectionName].contexts[modeName][0];
+			} else node = result.code.sets[collectionName].sources[0];
+			const tokenBase = {
+				$type: void 0,
+				$description: variable.description || void 0,
+				$value: void 0,
+				$extensions: { "figma.com": {
+					name: variable.name,
+					id: variable.id,
+					variableCollectionId: variable.variableCollectionId,
+					codeSyntax: Object.keys(variable.codeSyntax).length ? variable.codeSyntax : void 0
+				} }
+			};
+			const isAliasOfID = typeof value === "object" && "type" in value && value.type === "VARIABLE_ALIAS" && value.id || void 0;
+			if (isAliasOfID) if (allVariables[isAliasOfID]) {
+				tokenBase.$type = matches || {
+					COLOR: "color",
+					BOOLEAN: "boolean",
+					STRING: "string",
+					FLOAT: "dimension"
+				}[variable.resolvedType];
+				tokenBase.$value = `{${allVariables[isAliasOfID].name.split("/").map(formatName).join(".")}}`;
+			} else {
+				remoteIDs.add(isAliasOfID);
+				continue;
+			}
+			else if (matches === "fontFamily") {
+				tokenBase.$type = "fontFamily";
+				tokenBase.$value = String(value).split(",");
+			} else if (matches === "fontWeight") {
+				tokenBase.$type = "fontWeight";
+				tokenBase.$value = value;
+			} else if (matches === "number") {
+				if (typeof value === "object") throw new Error(`Can’t coerce ${variable.name} into number type.`);
+				tokenBase.$type = "number";
+				tokenBase.$value = Number(value);
+			} else switch (variable.resolvedType) {
+				case "BOOLEAN":
+				case "STRING":
+					tokenBase.$type = variable.resolvedType.toLowerCase();
+					tokenBase.$value = value;
+					break;
+				case "FLOAT":
+					tokenBase.$type = "dimension";
+					tokenBase.$value = {
+						value,
+						unit: "px"
+					};
+					break;
+				case "COLOR": {
+					const { r, g, b, a } = value;
+					tokenBase.$type = "color";
+					tokenBase.$value = {
+						colorSpace: "srgb",
+						components: [
+							r,
+							g,
+							b
+						],
+						alpha: a
+					};
+					break;
+				}
+			}
+			if (tokenBase.$value !== void 0) {
+				const path = variable.name.split("/").map(formatName);
+				const name = path.pop();
+				for (const key of path) {
+					if (!(key in node)) node[key] = {};
+					node = node[key];
+				}
+				node[name] = tokenBase;
+			}
+		}
+	}
+	result.count = Object.keys(finalVariables).length;
+	result.remoteCount = remoteIDs.size;
+	return result;
+}
+
+//#endregion
+//#region src/import/figma/index.ts
+async function importFromFigma({ url, logger, unpublished, skipStyles, skipVariables, fontFamilyNames, fontWeightNames, numberNames }) {
+	const fileKey = getFileID(url);
+	if (!fileKey) logger.error({
+		group: "import",
+		message: `Invalid Figma URL: ${url}`
+	});
+	const result = {
+		variableCount: 0,
+		styleCount: 0,
+		code: {
+			$schema: "https://www.designtokens.org/schemas/2025.10/resolver.json",
+			version: "2025.10",
+			resolutionOrder: [],
+			sets: {},
+			modifiers: {}
+		}
+	};
+	try {
+		const [styles, vars] = await Promise.all([!skipStyles ? getStyles(fileKey, { logger }) : null, !skipVariables ? getVariables(fileKey, {
+			logger,
+			unpublished,
+			matchers: {
+				fontFamily: new RegExp(fontFamilyNames || "/fontFamily$"),
+				fontWeight: new RegExp(fontWeightNames || "/fontWeight$"),
+				number: numberNames ? new RegExp(numberNames) : void 0
+			}
+		}) : null]);
+		if (styles) {
+			result.styleCount += styles.count;
+			result.code = merge(result.code, styles.code);
+		}
+		if (vars) {
+			result.variableCount += vars.count;
+			result.code = merge(result.code, vars.code);
+			if (vars.remoteCount) logger.warn({
+				group: "import",
+				message: `${formatNumber(vars.remoteCount)} ${pluralize(vars.remoteCount, "Variable", "Variables")} were remote and could not be accessed. Try importing from other files to grab them.`
+			});
+		}
+	} catch (err) {
+		logger.error({
+			group: "import",
+			message: err.message
+		});
+	}
+	for (const group of ["sets", "modifiers"]) for (const name of Object.keys(result.code[group])) result.code.resolutionOrder.push({ $ref: `#/${group}/${name}` });
+	return result;
+}
+/** Is this a valid URL, and one belonging to a Figma file? */
+function isFigmaPath(url) {
+	try {
+		new URL(url);
+		return /^https:\/\/(www\.)?figma\.com\/design\/[A-Za-z0-9]+/.test(url);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/import/index.ts
+async function importCmd({ flags, positionals, logger }) {
+	const [_cmd, url] = positionals;
+	if (!url) logger.error({
+		group: "import",
+		message: "Missing import path. Expected `tz import [file]`."
+	});
+	if (isFigmaPath(url)) {
+		const { FIGMA_ACCESS_TOKEN } = process.env;
+		if (!FIGMA_ACCESS_TOKEN) logger.error({
+			group: "import",
+			message: `FIGMA_ACCESS_TOKEN not set! See https://terrazzo.app/docs/guides/import-from-figma`
+		});
+		const start = performance.now();
+		const result = await importFromFigma({
+			url,
+			logger,
+			unpublished: flags.unpublished,
+			skipStyles: flags["skip-styles"],
+			skipVariables: flags["skip-variables"],
+			fontFamilyNames: flags["font-family-names"],
+			fontWeightNames: flags["font-weight-names"],
+			numberNames: flags["number-names"]
+		});
+		const end = performance.now() - start;
+		if (flags.output) {
+			const oldFile = fs.existsSync(flags.output) ? JSON.parse(await fs$1.readFile(flags.output, "utf8")) : {};
+			const code = {
+				$schema: result.code.$schema,
+				version: result.code.version,
+				resolutionOrder: oldFile.resolutionOrder?.length ? oldFile.resolutionOrder : result.code.resolutionOrder,
+				sets: result.code.sets,
+				modifiers: result.code.modifiers,
+				$defs: oldFile.$defs,
+				$extensions: oldFile.$extensions
+			};
+			await fs$1.writeFile(flags.output, `${JSON.stringify(code, void 0, 2)}\n`);
+			logger.info({
+				group: "import",
+				message: `Imported ${formatNumber(result.variableCount)} ${pluralize(result.variableCount, "Variable", "Variables")}, ${formatNumber(result.styleCount)} ${pluralize(result.styleCount, "Style", "Styles")} → ${flags.output}`,
+				timing: end
+			});
+		} else process.stdout.write(JSON.stringify(result.code));
+		return;
+	}
+}
+
 //#endregion
 //#region src/init.ts
 const INSTALL_COMMAND = {
@@ -1035,5 +1600,5 @@ function defineConfig(config) {
 }
 
 //#endregion
-export { DEFAULT_CONFIG_PATH, DEFAULT_TOKENS_PATH, GREEN_CHECK, buildCmd, checkCmd, cwd, defineConfig, helpCmd, initCmd, labCmd, loadConfig, loadTokens, normalizeCmd, printError, printSuccess, resolveConfig, resolveTokenPath, time, versionCmd, writeFiles };
+export { DEFAULT_CONFIG_PATH, DEFAULT_TOKENS_PATH, GREEN_CHECK, buildCmd, checkCmd, cwd, defineConfig, helpCmd, importCmd, importFromFigma, initCmd, isFigmaPath, labCmd, loadConfig, loadTokens, normalizeCmd, printError, printSuccess, resolveConfig, resolveTokenPath, time, versionCmd, writeFiles };
 //# sourceMappingURL=index.js.map