@stratixlabs/core 1.7.1

package/scripts/figma-sync.js

@@ -0,0 +1,738 @@
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+function ensurePathWithinRoot(resolvedPath, rootDir) {
+    const resolved = path.resolve(resolvedPath);
+    const root = path.resolve(rootDir);
+    const normalize = s => s.replace(/\\/g, '/').toLowerCase();
+    const resolvedNorm = normalize(resolved);
+    const rootNorm = normalize(root);
+    if (resolvedNorm !== rootNorm && !resolvedNorm.startsWith(rootNorm + '/')) {
+        throw new Error(`Configured path ${resolved} is outside of project root ${root}`);
+    }
+}
+
+function getRequiredEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        console.error(`❌ Missing required environment variable: ${name}`);
+        process.exit(1);
+    }
+    return value;
+}
+
+function fetchJson(url, token, options) {
+    return new Promise((resolve, reject) => {
+        const method = options && options.method ? options.method : 'GET';
+        const body = options && options.body ? JSON.stringify(options.body) : null;
+        const headers = {
+            'X-Figma-Token': token
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+            headers['Content-Length'] = Buffer.byteLength(body);
+        }
+
+        const req = https.request(
+            url,
+            {
+                method: method,
+                headers: headers
+            },
+            res => {
+                let data = '';
+                res.on('data', chunk => {
+                    data += chunk;
+                });
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        try {
+                            resolve(JSON.parse(data));
+                        } catch (error) {
+                            reject(error);
+                        }
+                    } else {
+                        console.error(`❌ Figma API error: ${res.statusCode}`);
+                        console.error(data);
+                        process.exit(1);
+                    }
+                });
+            }
+        );
+
+        req.on('error', error => {
+            reject(error);
+        });
+
+        if (body) {
+            req.write(body);
+        }
+
+        req.end();
+    });
+}
+
+function setDeep(obj, pathParts, value) {
+    let current = obj;
+    for (let i = 0; i < pathParts.length; i++) {
+        const part = pathParts[i];
+        if (i === pathParts.length - 1) {
+            current[part] = value;
+        } else {
+            if (!current[part] || typeof current[part] !== 'object' || Array.isArray(current[part])) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+    }
+}
+
+function getDeep(obj, pathParts) {
+    let current = obj;
+    for (const part of pathParts) {
+        if (!current || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+
+function deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+        const srcVal = source[key];
+        const tgtVal = target[key];
+        if (srcVal && typeof srcVal === 'object' && !Array.isArray(srcVal)) {
+            if (!tgtVal || typeof tgtVal !== 'object' || Array.isArray(tgtVal)) {
+                target[key] = {};
+            }
+            deepMerge(target[key], srcVal);
+        } else {
+            target[key] = srcVal;
+        }
+    }
+    return target;
+}
+
+function colorToHex(color) {
+    const r = Math.round(color.r * 255);
+    const g = Math.round(color.g * 255);
+    const b = Math.round(color.b * 255);
+    const a = typeof color.a === 'number' ? color.a : 1;
+
+    const toHex = n => n.toString(16).padStart(2, '0');
+
+    if (a === 1) {
+        return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+    }
+
+    const alpha = Math.round(a * 255);
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}${toHex(alpha)}`;
+}
+
+function hexToFigmaColor(hex) {
+    if (typeof hex !== 'string') return null;
+    let value = hex.trim();
+    if (!value) return null;
+    if (value[0] === '#') {
+        value = value.slice(1);
+    }
+
+    if (value.length === 3) {
+        value = value
+            .split('')
+            .map(ch => ch + ch)
+            .join('');
+    } else if (value.length === 4) {
+        value =
+            value
+                .slice(0, 3)
+                .split('')
+                .map(ch => ch + ch)
+                .join('') +
+            value[3] +
+            value[3];
+    }
+
+    if (value.length !== 6 && value.length !== 8) return null;
+
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    let a = 255;
+
+    if (value.length === 8) {
+        a = parseInt(value.slice(6, 8), 16);
+    }
+
+    if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) || Number.isNaN(a)) {
+        return null;
+    }
+
+    return {
+        r: r / 255,
+        g: g / 255,
+        b: b / 255,
+        a: a / 255
+    };
+}
+
+function figmaNameToPath(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '')
+        .split(/[\/\.]/)
+        .filter(Boolean);
+}
+
+function resolveOutputPath() {
+    let outputFile = path.join(__dirname, '../tokens.json');
+    const rootDir = process.cwd();
+    const configPath = path.join(rootDir, 'substrata.config.js');
+
+    if (fs.existsSync(configPath)) {
+        const config = require(configPath);
+        if (config.output) {
+            const resolvedOutputFile = path.resolve(rootDir, config.output);
+            ensurePathWithinRoot(resolvedOutputFile, rootDir);
+            outputFile = resolvedOutputFile;
+        }
+    }
+
+    return outputFile;
+}
+
+function flattenTokens(obj, prefix, result) {
+    const keys = Object.keys(obj || {});
+    for (const key of keys) {
+        const value = obj[key];
+        const nextPath = prefix.length ? `${prefix}.${key}` : key;
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            if (Object.prototype.hasOwnProperty.call(value, 'value') && value.type) {
+                result.push({
+                    path: nextPath,
+                    type: value.type,
+                    value: value.value
+                });
+            } else {
+                flattenTokens(value, nextPath, result);
+            }
+        }
+    }
+    return result;
+}
+
+function tokenPathToFigmaName(path) {
+    const parts = path.split('.');
+    if (parts.length >= 2 && parts[0] === 'font' && parts[1] === 'size') {
+        const rest = parts.slice(2).join('/');
+        return rest ? `font-size/${rest}` : 'font-size';
+    }
+    if (parts.length >= 2 && parts[0] === 'line' && parts[1] === 'height') {
+        const rest = parts.slice(2).join('/');
+        return rest ? `line-height/${rest}` : 'line-height';
+    }
+    return parts.join('/');
+}
+
+function resolveVariableValue(variable, modeId, variables) {
+    let current = variable;
+    const visited = new Set();
+
+    while (current && current.valuesByMode) {
+        const raw = current.valuesByMode[modeId];
+
+        if (!raw || typeof raw !== 'object' || raw.type !== 'VARIABLE_ALIAS') {
+            return raw;
+        }
+
+        const aliasId = raw.id;
+        if (!aliasId || visited.has(aliasId)) {
+            return raw;
+        }
+
+        visited.add(aliasId);
+        const next = variables[aliasId];
+        if (!next) {
+            return raw;
+        }
+
+        current = next;
+    }
+
+    return undefined;
+}
+
+function selectModeId(collection, preferredModeName) {
+    if (!collection) return null;
+    const modes = Array.isArray(collection.modes) ? collection.modes : [];
+    if (preferredModeName && modes.length > 0) {
+        const match = modes.find(
+            mode => mode.name && mode.name.toLowerCase() === preferredModeName.toLowerCase()
+        );
+        if (match) {
+            return match.modeId;
+        }
+    }
+    if (collection.defaultModeId) {
+        return collection.defaultModeId;
+    }
+    if (modes.length > 0) {
+        return modes[0].modeId;
+    }
+    return null;
+}
+
+async function runPull() {
+    const token = getRequiredEnv('FIGMA_TOKEN');
+    const fileKey = getRequiredEnv('FIGMA_FILE_KEY');
+    const spaceUnit = process.env.FIGMA_SPACE_UNIT || 'px';
+    const radiusUnit = process.env.FIGMA_RADIUS_UNIT || 'px';
+    const motionUnit = process.env.FIGMA_MOTION_UNIT || 'ms';
+    const fontSizeUnit = process.env.FIGMA_FONT_SIZE_UNIT || 'px';
+    const preferredModeName = process.env.FIGMA_MODE_NAME || null;
+
+    const url = `https://api.figma.com/v1/files/${fileKey}/variables/local`;
+
+    console.log('📡 Fetching local variables from Figma...');
+    const payload = await fetchJson(url, token);
+
+    if (!payload.meta || !payload.meta.variables || !payload.meta.variableCollections) {
+        console.error('❌ Unexpected Figma response shape');
+        process.exit(1);
+    }
+
+    const variables = payload.meta.variables;
+    const collections = payload.meta.variableCollections;
+
+    const outputFile = resolveOutputPath();
+    let existingTokens = {};
+
+    if (fs.existsSync(outputFile)) {
+        try {
+            existingTokens = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
+        } catch (error) {
+            console.error('❌ Could not parse existing tokens.json');
+            console.error(error);
+            process.exit(1);
+        }
+    }
+
+    const updates = {};
+    const changes = [];
+
+    for (const variableId of Object.keys(variables)) {
+        const variable = variables[variableId];
+        const collection = collections[variable.variableCollectionId];
+        if (!collection) continue;
+
+        const modeId = selectModeId(collection, preferredModeName);
+        if (!modeId) continue;
+
+        const resolvedValue = resolveVariableValue(variable, modeId, variables);
+
+        if (resolvedValue === undefined || resolvedValue === null) continue;
+
+        const name = variable.name || '';
+        const lowerName = name.toLowerCase();
+
+        if (variable.resolvedType === 'COLOR') {
+            if (
+                !lowerName.startsWith('neutral/') &&
+                !lowerName.startsWith('brand/') &&
+                !lowerName.startsWith('color/')
+            ) {
+                continue;
+            }
+
+            if (!resolvedValue || typeof resolvedValue !== 'object') continue;
+
+            const hex = colorToHex(resolvedValue);
+            const pathParts = figmaNameToPath(name);
+            const tokenValue = {
+                value: hex,
+                type: 'color',
+                originalVariable: `--${pathParts.join('-')}`
+            };
+
+            const previous = getDeep(existingTokens, pathParts);
+            setDeep(updates, pathParts, tokenValue);
+            changes.push({
+                path: pathParts.join('.'),
+                before: previous ? previous.value : undefined,
+                after: hex
+            });
+        }
+
+        if (variable.resolvedType === 'FLOAT') {
+            if (lowerName.startsWith('space/')) {
+                if (typeof resolvedValue !== 'number') continue;
+                const pathParts = figmaNameToPath(name);
+                const value = `${resolvedValue}${spaceUnit}`;
+                const tokenValue = {
+                    value: value,
+                    type: 'spacing',
+                    originalVariable: `--${pathParts.join('-')}`
+                };
+                const previous = getDeep(existingTokens, pathParts);
+                setDeep(updates, pathParts, tokenValue);
+                changes.push({
+                    path: pathParts.join('.'),
+                    before: previous ? previous.value : undefined,
+                    after: value
+                });
+                continue;
+            }
+
+            if (lowerName.startsWith('radius/') || lowerName.startsWith('border-radius/')) {
+                if (typeof resolvedValue !== 'number') continue;
+                const pathParts = figmaNameToPath(name);
+                const value = `${resolvedValue}${radiusUnit}`;
+                const tokenValue = {
+                    value: value,
+                    type: 'radius',
+                    originalVariable: `--${pathParts.join('-')}`
+                };
+                const previous = getDeep(existingTokens, pathParts);
+                setDeep(updates, pathParts, tokenValue);
+                changes.push({
+                    path: pathParts.join('.'),
+                    before: previous ? previous.value : undefined,
+                    after: value
+                });
+                continue;
+            }
+
+            if (lowerName.startsWith('motion/') || lowerName.startsWith('duration/')) {
+                if (typeof resolvedValue !== 'number') continue;
+                const pathParts = figmaNameToPath(name);
+                const value = `${resolvedValue}${motionUnit}`;
+                const tokenValue = {
+                    value: value,
+                    type: 'motion',
+                    originalVariable: `--${pathParts.join('-')}`
+                };
+                const previous = getDeep(existingTokens, pathParts);
+                setDeep(updates, pathParts, tokenValue);
+                changes.push({
+                    path: pathParts.join('.'),
+                    before: previous ? previous.value : undefined,
+                    after: value
+                });
+                continue;
+            }
+
+            if (
+                lowerName.startsWith('font-size/') ||
+                lowerName.startsWith('font/size/') ||
+                lowerName.startsWith('font.size/')
+            ) {
+                if (typeof resolvedValue !== 'number') continue;
+                const pathParts = figmaNameToPath(name);
+                const value = `${resolvedValue}${fontSizeUnit}`;
+                const tokenValue = {
+                    value: value,
+                    type: 'typography',
+                    originalVariable: `--${pathParts.join('-')}`
+                };
+                const previous = getDeep(existingTokens, pathParts);
+                setDeep(updates, pathParts, tokenValue);
+                changes.push({
+                    path: pathParts.join('.'),
+                    before: previous ? previous.value : undefined,
+                    after: value
+                });
+                continue;
+            }
+
+            if (
+                lowerName.startsWith('line-height/') ||
+                lowerName.startsWith('line/height/') ||
+                lowerName.startsWith('line.height/')
+            ) {
+                if (typeof resolvedValue !== 'number') continue;
+                const pathParts = figmaNameToPath(name);
+                const value = String(resolvedValue);
+                const tokenValue = {
+                    value: value,
+                    type: 'typography',
+                    originalVariable: `--${pathParts.join('-')}`
+                };
+                const previous = getDeep(existingTokens, pathParts);
+                setDeep(updates, pathParts, tokenValue);
+                changes.push({
+                    path: pathParts.join('.'),
+                    before: previous ? previous.value : undefined,
+                    after: value
+                });
+                continue;
+            }
+
+            if (lowerName.startsWith('opacity/')) {
+                if (typeof resolvedValue !== 'number') continue;
+                const pathParts = figmaNameToPath(name);
+                const value = String(resolvedValue);
+                const tokenValue = {
+                    value: value,
+                    type: 'opacity',
+                    originalVariable: `--${pathParts.join('-')}`
+                };
+                const previous = getDeep(existingTokens, pathParts);
+                setDeep(updates, pathParts, tokenValue);
+                changes.push({
+                    path: pathParts.join('.'),
+                    before: previous ? previous.value : undefined,
+                    after: value
+                });
+                continue;
+            }
+        }
+    }
+
+    if (changes.length === 0) {
+        console.log('ℹ️ No matching color or space variables found to update.');
+        return;
+    }
+
+    const merged = deepMerge(existingTokens, updates);
+    fs.writeFileSync(outputFile, JSON.stringify(merged, null, 2));
+
+    const reportFile = path.join(path.dirname(outputFile), 'figma-drift-report.json');
+    const report = {
+        generatedAt: new Date().toISOString(),
+        fileKey: fileKey,
+        mode: preferredModeName || 'default',
+        changes: changes
+    };
+    fs.writeFileSync(reportFile, JSON.stringify(report, null, 2));
+
+    console.log(`✅ Updated ${outputFile} with Figma variables.`);
+    console.log(`📝 Drift report written to ${reportFile}.`);
+    console.log('Changed tokens:');
+    for (const change of changes) {
+        console.log(
+            `  - ${change.path}: ${change.before === undefined ? '∅' : change.before} → ${
+                change.after
+            }`
+        );
+    }
+}
+
+async function runPush() {
+    const token = getRequiredEnv('FIGMA_TOKEN');
+    const fileKey = getRequiredEnv('FIGMA_FILE_KEY');
+    const preferredModeName = process.env.FIGMA_MODE_NAME || null;
+
+    const url = `https://api.figma.com/v1/files/${fileKey}/variables/local`;
+
+    console.log('📡 Fetching local variables from Figma for push preview...');
+    const payload = await fetchJson(url, token);
+
+    if (!payload.meta || !payload.meta.variables || !payload.meta.variableCollections) {
+        console.error('❌ Unexpected Figma response shape');
+        process.exit(1);
+    }
+
+    const variables = payload.meta.variables;
+    const collections = payload.meta.variableCollections;
+
+    const outputFile = resolveOutputPath();
+    if (!fs.existsSync(outputFile)) {
+        console.error(`❌ tokens.json not found at: ${outputFile}`);
+        process.exit(1);
+    }
+
+    let tokens;
+    try {
+        tokens = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
+    } catch (error) {
+        console.error('❌ Could not parse tokens.json');
+        console.error(error);
+        process.exit(1);
+    }
+
+    const flat = flattenTokens(tokens, '', []);
+    const allowedTypes = new Set(['color', 'spacing', 'radius', 'motion', 'opacity', 'typography']);
+
+    const filtered = flat.filter(entry => allowedTypes.has(entry.type));
+
+    const variableByName = {};
+    for (const id of Object.keys(variables)) {
+        const variable = variables[id];
+        const name = (variable.name || '').trim().toLowerCase();
+        if (!name) continue;
+        variableByName[name] = { id, variable };
+    }
+
+    const updates = [];
+
+    for (const entry of filtered) {
+        const figmaName = tokenPathToFigmaName(entry.path);
+        const key = figmaName.trim().toLowerCase();
+        const match = variableByName[key];
+        if (!match) continue;
+
+        const variable = match.variable;
+        const collection = collections[variable.variableCollectionId];
+        if (!collection) continue;
+
+        const modeId = selectModeId(collection, preferredModeName);
+        if (!modeId) continue;
+
+        const resolvedValue = resolveVariableValue(variable, modeId, variables);
+
+        let current = null;
+        if (variable.resolvedType === 'COLOR') {
+            if (resolvedValue && typeof resolvedValue === 'object') {
+                current = colorToHex(resolvedValue);
+            }
+        } else if (variable.resolvedType === 'FLOAT') {
+            if (typeof resolvedValue === 'number') {
+                current = resolvedValue;
+            }
+        }
+
+        updates.push({
+            path: entry.path,
+            figmaName: figmaName,
+            variableId: match.id,
+            type: entry.type,
+            resolvedType: variable.resolvedType,
+            modeId: modeId,
+            currentValue: current,
+            nextValue: entry.value
+        });
+    }
+
+    const previewFile = path.join(path.dirname(outputFile), 'figma-push-preview.json');
+    const preview = {
+        generatedAt: new Date().toISOString(),
+        fileKey: fileKey,
+        mode: preferredModeName || 'default',
+        updates: updates
+    };
+
+    fs.writeFileSync(previewFile, JSON.stringify(preview, null, 2));
+
+    console.log(`📝 Figma push preview written to ${previewFile}.`);
+    console.log(`   Total candidate updates: ${updates.length}`);
+}
+
+async function runApplyFromPreview() {
+    const token = getRequiredEnv('FIGMA_TOKEN');
+    const fileKey = getRequiredEnv('FIGMA_FILE_KEY');
+    const applyChanges = process.env.FIGMA_APPLY_CHANGES === '1';
+
+    const outputFile = resolveOutputPath();
+    const previewFile = path.join(path.dirname(outputFile), 'figma-push-preview.json');
+
+    if (!fs.existsSync(previewFile)) {
+        console.error(`❌ figma-push-preview.json not found at: ${previewFile}`);
+        process.exit(1);
+    }
+
+    let preview;
+    try {
+        preview = JSON.parse(fs.readFileSync(previewFile, 'utf8'));
+    } catch (error) {
+        console.error('❌ Could not parse figma-push-preview.json');
+        console.error(error);
+        process.exit(1);
+    }
+
+    if (preview.fileKey && preview.fileKey !== fileKey) {
+        console.error('❌ FIGMA_FILE_KEY does not match fileKey stored in figma-push-preview.json');
+        process.exit(1);
+    }
+
+    const updates = Array.isArray(preview.updates) ? preview.updates : [];
+
+    if (updates.length === 0) {
+        console.log('ℹ️ No updates found in figma-push-preview.json.');
+        return;
+    }
+
+    const variableModeValues = [];
+
+    for (const update of updates) {
+        if (!update.variableId || !update.modeId) continue;
+
+        const resolvedType = update.resolvedType;
+        let nextValue = update.nextValue;
+        let value = null;
+
+        if (resolvedType === 'COLOR') {
+            if (typeof nextValue !== 'string') continue;
+            const color = hexToFigmaColor(nextValue);
+            if (!color) continue;
+            value = color;
+        } else if (resolvedType === 'FLOAT') {
+            const numeric = parseFloat(String(nextValue));
+            if (!Number.isFinite(numeric)) continue;
+            value = numeric;
+        } else {
+            continue;
+        }
+
+        variableModeValues.push({
+            variableId: update.variableId,
+            modeId: update.modeId,
+            value: value
+        });
+    }
+
+    if (variableModeValues.length === 0) {
+        console.log('ℹ️ No applicable variable updates to apply from preview.');
+        return;
+    }
+
+    if (!applyChanges) {
+        console.log('🔎 Dry run (FIGMA_APPLY_CHANGES != 1). Planned updates:');
+        for (const update of updates) {
+            console.log(
+                `  - ${update.path} (${update.figmaName}) [${update.variableId}] mode=${update.modeId} ` +
+                    `current=${update.currentValue} → next=${update.nextValue}`
+            );
+        }
+        console.log('');
+        console.log(
+            `Set FIGMA_APPLY_CHANGES=1 to apply ${variableModeValues.length} variableModeValues via file_variables:write.`
+        );
+        return;
+    }
+
+    const url = `https://api.figma.com/v1/files/${fileKey}/variables`;
+    const body = {
+        variableModeValues: variableModeValues
+    };
+
+    console.log(
+        `📡 Applying ${variableModeValues.length} variable updates to Figma via file_variables:write...`
+    );
+
+    await fetchJson(url, token, { method: 'POST', body: body });
+
+    console.log('✅ Applied variable updates from figma-push-preview.json to Figma.');
+}
+
+const direction = (process.env.FIGMA_SYNC_DIRECTION || 'pull').toLowerCase();
+
+if (direction === 'push') {
+    runPush().catch(error => {
+        console.error('❌ Error running Figma Sync (push preview):', error);
+        process.exit(1);
+    });
+} else if (direction === 'apply') {
+    runApplyFromPreview().catch(error => {
+        console.error('❌ Error applying Figma push preview:', error);
+        process.exit(1);
+    });
+} else {
+    runPull().catch(error => {
+        console.error('❌ Error running Figma Sync:', error);
+        process.exit(1);
+    });
+}
+