@fragments-sdk/cli 0.15.0 → 0.15.1

package/src/commands/tokens-push.ts

@@ -0,0 +1,199 @@
+/**
+ * fragments tokens push — Push code tokens to Fragments Cloud for drift comparison.
+ *
+ * Extracts CSS custom properties from Tailwind v4 @theme blocks (or config-based
+ * token files) and POSTs them to the Fragments Cloud /api/ingest endpoint.
+ * Supports --dry-run for local inspection without pushing.
+ */
+
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface TokensPushOptions {
+  /** Path to fragments config file */
+  config?: string;
+  /** Path to Tailwind v4 CSS file with @theme block */
+  tailwindV4?: string;
+  /** Parse and display tokens without pushing */
+  dryRun?: boolean;
+  /** Show detailed output */
+  verbose?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// tokensPush
+// ---------------------------------------------------------------------------
+
+export async function tokensPush(options: TokensPushOptions): Promise<void> {
+  const startTime = Date.now();
+
+  // 1. Resolve API credentials
+  const apiKey = process.env.FRAGMENTS_API_KEY;
+  const baseUrl = process.env.FRAGMENTS_URL || 'https://app.usefragments.com';
+
+  if (!apiKey && !options.dryRun) {
+    console.error(pc.red('Error: FRAGMENTS_API_KEY environment variable is required'));
+    console.error(pc.dim('Get your API key from https://app.usefragments.com/api-keys'));
+    process.exit(1);
+  }
+
+  // 2. Token extraction
+  const flatMap: Record<string, string> = {};
+
+  if (options.tailwindV4) {
+    // Use @theme parser for Tailwind v4 CSS files
+    const { parseTailwindV4File } = await import('../service/token-parser.js');
+
+    const filePath = resolve(process.cwd(), options.tailwindV4);
+    const result = parseTailwindV4File(filePath);
+
+    if (result.errors.length > 0) {
+      for (const err of result.errors) {
+        console.error(pc.red(`  Error: ${err.message}`));
+      }
+    }
+
+    if (options.verbose && result.warnings.length > 0) {
+      for (const warn of result.warnings) {
+        console.warn(pc.yellow(`  Warning: ${warn}`));
+      }
+    }
+
+    for (const token of result.tokens) {
+      flatMap[token.name] = token.resolvedValue;
+    }
+
+    if (options.verbose) {
+      console.log(
+        pc.dim(`  Parsed ${result.tokens.length} tokens from ${options.tailwindV4} (${result.parseTimeMs.toFixed(1)}ms)`),
+      );
+    }
+  } else if (options.config) {
+    // Use config-based token extraction
+    try {
+      const { loadConfig } = await import('../core/node.js');
+      const { parseTokenFiles } = await import('../service/index.js');
+
+      const { config, configDir } = await loadConfig(options.config);
+      if (config.tokens?.include?.length) {
+        const result = await parseTokenFiles(config.tokens, configDir);
+        for (const token of result.tokens) {
+          flatMap[token.name] = token.resolvedValue;
+        }
+
+        if (options.verbose) {
+          console.log(
+            pc.dim(`  Parsed ${result.tokens.length} tokens from config (${result.parseTimeMs.toFixed(1)}ms)`),
+          );
+        }
+      } else {
+        console.error(pc.red('Error: Config file has no tokens.include patterns'));
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error loading config:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  } else {
+    // No source specified — try auto-detection
+    try {
+      const { loadConfig } = await import('../core/node.js');
+      const { parseTokenFiles } = await import('../service/index.js');
+
+      const { config, configDir } = await loadConfig();
+      if (config.tokens?.include?.length) {
+        const result = await parseTokenFiles(config.tokens, configDir);
+        for (const token of result.tokens) {
+          flatMap[token.name] = token.resolvedValue;
+        }
+
+        if (options.verbose) {
+          console.log(
+            pc.dim(`  Parsed ${result.tokens.length} tokens from auto-detected config (${result.parseTimeMs.toFixed(1)}ms)`),
+          );
+        }
+      }
+    } catch {
+      // No config found — fall through to error
+    }
+
+    if (Object.keys(flatMap).length === 0) {
+      console.error(pc.red('Error: No token source specified'));
+      console.error(pc.dim('Provide one of:'));
+      console.error(pc.dim('  --tailwind-v4 <path>  Path to Tailwind v4 CSS file with @theme block'));
+      console.error(pc.dim('  --config <path>       Path to fragments config with tokens.include'));
+      console.error(pc.dim('\nExample: fragments tokens push --tailwind-v4 ./app.css'));
+      process.exit(1);
+    }
+  }
+
+  const tokenCount = Object.keys(flatMap).length;
+
+  if (tokenCount === 0) {
+    console.log(pc.yellow('No tokens found.'));
+    return;
+  }
+
+  console.log(pc.cyan(`Found ${tokenCount} tokens`));
+
+  // 3. Dry run — display tokens and exit
+  if (options.dryRun) {
+    console.log(pc.dim('\nDry run — tokens that would be pushed:\n'));
+    const entries = Object.entries(flatMap);
+    for (const [name, value] of entries.slice(0, 20)) {
+      console.log(`  ${pc.bold(name)}: ${value}`);
+    }
+    if (entries.length > 20) {
+      console.log(pc.dim(`  ... and ${entries.length - 20} more`));
+    }
+    return;
+  }
+
+  // 4. POST to Fragments Cloud
+  try {
+    const response = await fetch(`${baseUrl}/api/ingest`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        codeTokens: JSON.stringify(flatMap),
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error(pc.red(`Error: API returned ${response.status}`));
+      console.error(pc.dim(errorText));
+      process.exit(1);
+    }
+
+    const result = await response.json() as Record<string, unknown>;
+
+    console.log(pc.green(`\nPushed ${tokenCount} tokens to Fragments Cloud`));
+
+    if (result.tokenDrift) {
+      const drift = result.tokenDrift as Record<string, unknown>;
+      const summary = drift.summary as Record<string, number> | undefined;
+      if (summary) {
+        console.log(pc.cyan('\nDrift Summary:'));
+        if (summary.total !== undefined) console.log(pc.dim(`  Total issues: ${summary.total}`));
+        if (summary.missingInCode > 0) console.log(pc.yellow(`  Missing in code: ${summary.missingInCode}`));
+        if (summary.missingInFigma > 0) console.log(pc.yellow(`  Missing in Figma: ${summary.missingInFigma}`));
+        if (summary.valueMismatch > 0) console.log(pc.yellow(`  Value mismatches: ${summary.valueMismatch}`));
+        if (summary.score !== undefined) console.log(`  Health score: ${summary.score}%`);
+      }
+    }
+
+    console.log(pc.dim(`\nView dashboard: ${baseUrl}/tokens`));
+    console.log(pc.dim(`Completed in ${Date.now() - startTime}ms`));
+  } catch (error) {
+    console.error(pc.red('Error pushing tokens:'), error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}

package/src/core/__tests__/token-resolver.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveTokensWithSass } from '../token-resolver.js';
+import { resolveTokensWithSass } from '@fragments-sdk/extract';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 

package/src/core/component-extractor.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { resolve, join } from 'node:path';
-import { createComponentExtractor, type ComponentExtractor, type ComponentMeta } from './component-extractor.js';
+import { createComponentExtractor, type ComponentExtractor, type ComponentMeta } from '@fragments-sdk/extract';
 
 // ---------------------------------------------------------------------------
 // Setup

package/src/core/drift-verifier.ts

@@ -6,7 +6,7 @@
  */
 
 import type { CompiledContractOutput } from '@fragments-sdk/core';
-import type { ComponentMeta } from './component-extractor.js';
+import type { ComponentMeta } from '@fragments-sdk/extract';
 
 export interface DriftReport {
   componentName: string;

package/src/core/extractor-adapter.ts

@@ -5,7 +5,7 @@
  * Non-React frameworks return a no-op adapter with verificationLevel: 'none'.
  */
 
-import { createComponentExtractor, type ComponentExtractor, type ComponentMeta } from './component-extractor.js';
+import { createComponentExtractor, type ComponentExtractor, type ComponentMeta } from '@fragments-sdk/extract';
 
 export interface ExtractorAdapter {
   /** Whether this adapter can handle the given framework */

package/src/index.ts

@@ -17,9 +17,9 @@ export type {
   ValidationRunOptions,
 } from "./validators.js";
 
-// Build
-export { buildFragments } from "./build.js";
-export type { BuildResult } from "./build.js";
+// Build (delegated to @fragments-sdk/compiler)
+export { buildFragments } from '@fragments-sdk/compiler';
+export type { BuildResult } from '@fragments-sdk/compiler';
 
 // Screenshot
 export { runScreenshotCommand } from "./screenshot.js";

package/src/migrate/fragment-to-contract.ts

@@ -9,8 +9,8 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve, dirname, relative, basename } from 'node:path';
 import { parseFragmentFile } from '../core/parser.js';
-import { createComponentExtractor, type ComponentMeta } from '../core/component-extractor.js';
-import { resolveComponentSourcePath } from '../core/auto-props.js';
+import { createComponentExtractor, type ComponentMeta } from '@fragments-sdk/extract';
+import { resolveComponentSourcePath } from '@fragments-sdk/extract';
 import type { ComponentContract } from '@fragments-sdk/core';
 
 export interface MigrateOptions {

package/src/service/index.ts

@@ -97,12 +97,20 @@ export { generateHtmlReport } from "./report.js";
 export {
   parseTokenFile,
   parseTokenFiles,
+  parseTailwindV4File,
+  containsTailwindV4Theme,
   hexToRgb,
   rgbToHex,
   parseRgb,
   normalizeColor,
 } from "./token-parser.js";
 
+// Tailwind v4 @theme parser
+export {
+  parseTailwindV4Theme,
+  type ThemeParserResult,
+} from "./tailwind-v4-parser.js";
+
 export {
   TokenRegistryManager,
   getSharedTokenRegistry,

package/src/service/tailwind-v4-parser.ts

@@ -0,0 +1,314 @@
+/**
+ * Tailwind v4 @theme Block Parser
+ *
+ * Extracts CSS custom properties (--name: value;) from Tailwind v4 @theme {}
+ * blocks. Tailwind v4 moves token definitions from tailwind.config.js into
+ * CSS @theme blocks, declaring design tokens as standard custom properties.
+ *
+ * Handles:
+ * - Multiple @theme blocks in one file
+ * - @theme inline { ... } variant
+ * - Empty @theme {} blocks
+ * - Comments (// single-line and multi-line)
+ * - Nested blocks inside @theme (tracks brace depth correctly)
+ * - Lines without semicolons (skipped with warning)
+ */
+
+import type {
+  DesignToken,
+  TokenCategory,
+} from "../core/index.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ThemeParserResult {
+  tokens: DesignToken[];
+  errors: string[];
+  warnings: string[];
+  parseTimeMs: number;
+}
+
+// ─── Category Inference ──────────────────────────────────────────────────────
+
+/**
+ * Category inference patterns — same logic as token-parser.ts CATEGORY_PATTERNS
+ * to keep categorization consistent across all parsers.
+ */
+const CATEGORY_PATTERNS: Array<{
+  pattern: RegExp;
+  category: TokenCategory;
+}> = [
+  { pattern: /color|bg|background|border-color|fill|stroke/i, category: "color" },
+  { pattern: /spacing|margin|padding|gap|space|inset/i, category: "spacing" },
+  { pattern: /font|text|line-height|letter-spacing|typography/i, category: "typography" },
+  { pattern: /radius|rounded|corner/i, category: "radius" },
+  { pattern: /shadow|elevation/i, category: "shadow" },
+  { pattern: /size|width|height|min|max/i, category: "sizing" },
+  { pattern: /border(?!-color)|stroke-width|outline/i, category: "border" },
+  { pattern: /animation|transition|duration|timing|delay/i, category: "animation" },
+  { pattern: /z-index|layer|stack/i, category: "z-index" },
+];
+
+/**
+ * Infer token category from a CSS custom property name.
+ */
+function inferCategory(name: string): TokenCategory {
+  const lowerName = name.toLowerCase();
+
+  for (const { pattern, category } of CATEGORY_PATTERNS) {
+    if (pattern.test(lowerName)) {
+      return category;
+    }
+  }
+
+  return "other";
+}
+
+/**
+ * Infer token level:
+ * - 1 (base) for raw values (hex colors, numbers, named CSS values)
+ * - 2 (semantic) for var() references
+ */
+function inferLevel(rawValue: string): 1 | 2 | 3 {
+  if (/var\(/.test(rawValue)) {
+    return 2;
+  }
+  return 1;
+}
+
+// ─── Comment Stripping ───────────────────────────────────────────────────────
+
+/**
+ * Remove block comments from a CSS string, handling multi-line spans.
+ * Returns the cleaned string.
+ */
+function stripBlockComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+// ─── Parser ──────────────────────────────────────────────────────────────────
+
+/** Regex to match a CSS custom property declaration inside a @theme block */
+const CUSTOM_PROPERTY_PATTERN = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;?\s*$/;
+
+/**
+ * Parse Tailwind v4 @theme blocks from CSS content and extract design tokens.
+ *
+ * @param cssContent - Raw CSS file content (may contain @theme blocks)
+ * @param filePath   - Optional source file path for diagnostics
+ * @returns ThemeParserResult with extracted tokens, errors, and warnings
+ */
+export function parseTailwindV4Theme(
+  cssContent: string,
+  filePath?: string,
+): ThemeParserResult {
+  const startTime = performance.now();
+  const tokens: DesignToken[] = [];
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const source = filePath ?? "unknown";
+
+  // Strip block comments first so they don't interfere with parsing
+  const cleaned = stripBlockComments(cssContent);
+
+  const lines = cleaned.split("\n");
+
+  let insideTheme = false;
+  let themeDepth = 0; // brace depth relative to the @theme block
+  let pendingTheme = false; // saw @theme keyword, waiting for opening brace
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    const lineNumber = i + 1;
+
+    // Strip single-line comments (// ...)
+    const singleCommentIdx = line.indexOf("//");
+    if (singleCommentIdx !== -1) {
+      // Make sure // is not inside a string (simple heuristic: not inside quotes)
+      const beforeComment = line.slice(0, singleCommentIdx);
+      const singleQuotes = (beforeComment.match(/'/g) || []).length;
+      const doubleQuotes = (beforeComment.match(/"/g) || []).length;
+      // If both quote counts are even, the // is not inside a string
+      if (singleQuotes % 2 === 0 && doubleQuotes % 2 === 0) {
+        line = beforeComment;
+      }
+    }
+
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (trimmed === "") {
+      continue;
+    }
+
+    // Detect @theme keyword (with optional modifiers like "inline")
+    if (!insideTheme && !pendingTheme) {
+      // Match @theme, @theme inline, @theme { ... }, etc.
+      if (/^@theme\b/.test(trimmed)) {
+        pendingTheme = true;
+        // Check if the opening brace is on the same line
+        const braceIdx = trimmed.indexOf("{");
+        if (braceIdx !== -1) {
+          pendingTheme = false;
+          insideTheme = true;
+          themeDepth = 1;
+
+          // Count any additional braces on this same line
+          const afterBrace = trimmed.slice(braceIdx + 1);
+          for (const ch of afterBrace) {
+            if (ch === "{") themeDepth++;
+            else if (ch === "}") themeDepth--;
+          }
+
+          // If there are declarations on the same line as @theme {
+          // (e.g., @theme { --color-primary: #000; })
+          const inlineContent = afterBrace.trim();
+          if (inlineContent && themeDepth > 0) {
+            processThemeLine(inlineContent, lineNumber, source, tokens, warnings);
+          }
+
+          if (themeDepth <= 0) {
+            insideTheme = false;
+          }
+        }
+        continue;
+      }
+    }
+
+    // If we saw @theme but haven't found the opening brace yet
+    if (pendingTheme) {
+      const braceIdx = trimmed.indexOf("{");
+      if (braceIdx !== -1) {
+        pendingTheme = false;
+        insideTheme = true;
+        themeDepth = 1;
+
+        // Count additional braces on this line
+        const afterBrace = trimmed.slice(braceIdx + 1);
+        for (const ch of afterBrace) {
+          if (ch === "{") themeDepth++;
+          else if (ch === "}") themeDepth--;
+        }
+
+        // Process any inline content after the brace
+        const inlineContent = afterBrace.trim();
+        if (inlineContent && themeDepth > 0) {
+          processThemeLine(inlineContent, lineNumber, source, tokens, warnings);
+        }
+
+        if (themeDepth <= 0) {
+          insideTheme = false;
+        }
+      }
+      // If no brace found, keep waiting (could be multi-line @theme declaration)
+      continue;
+    }
+
+    // Inside a @theme block — track braces and extract declarations
+    if (insideTheme) {
+      // Count braces to track depth
+      for (const ch of trimmed) {
+        if (ch === "{") {
+          themeDepth++;
+        } else if (ch === "}") {
+          themeDepth--;
+          if (themeDepth <= 0) {
+            insideTheme = false;
+            break;
+          }
+        }
+      }
+
+      // Only extract declarations at depth 1 (directly inside @theme)
+      // or if we're still inside the theme block
+      if (insideTheme || themeDepth > 0) {
+        // Remove any closing braces from the line content before matching
+        const contentLine = trimmed.replace(/\}/g, "").trim();
+        if (contentLine) {
+          processThemeLine(contentLine, lineNumber, source, tokens, warnings);
+        }
+      }
+    }
+  }
+
+  // If we ended while still expecting a @theme block, warn
+  if (pendingTheme) {
+    warnings.push(
+      `@theme keyword found but no opening brace — incomplete block in ${source}`,
+    );
+  }
+
+  if (insideTheme) {
+    warnings.push(
+      `Unclosed @theme block — missing closing brace in ${source}`,
+    );
+  }
+
+  return {
+    tokens,
+    errors,
+    warnings,
+    parseTimeMs: performance.now() - startTime,
+  };
+}
+
+/**
+ * Process a single line inside a @theme block, attempting to extract a
+ * CSS custom property declaration.
+ */
+function processThemeLine(
+  line: string,
+  lineNumber: number,
+  source: string,
+  tokens: DesignToken[],
+  warnings: string[],
+): void {
+  const match = line.match(CUSTOM_PROPERTY_PATTERN);
+
+  if (!match) {
+    // If the line looks like it has a custom property but is missing a semicolon
+    const partialMatch = line.match(/^\s*(--[\w-]+)\s*:\s*(.+?)\s*$/);
+    if (partialMatch) {
+      // It matched without semicolon — treat as valid (CSS tolerates missing trailing semicolons)
+      const [, name, rawValue] = partialMatch;
+      tokens.push(buildToken(name, rawValue, lineNumber, source));
+      return;
+    }
+
+    // Lines that contain -- but couldn't be parsed
+    if (/^\s*--/.test(line)) {
+      warnings.push(
+        `Line ${lineNumber}: Could not parse custom property declaration: ${line.trim()}`,
+      );
+    }
+    return;
+  }
+
+  const [, name, rawValue] = match;
+  tokens.push(buildToken(name, rawValue, lineNumber, source));
+}
+
+/**
+ * Build a DesignToken from a parsed custom property declaration.
+ */
+function buildToken(
+  name: string,
+  rawValue: string,
+  lineNumber: number,
+  source: string,
+): DesignToken {
+  const value = rawValue.trim();
+
+  return {
+    name,
+    rawValue: value,
+    resolvedValue: value,
+    category: inferCategory(name),
+    level: inferLevel(value),
+    referenceChain: [],
+    sourceFile: source,
+    lineNumber,
+    theme: "default",
+    selector: "@theme",
+  };
+}

package/src/service/token-parser.ts

@@ -7,9 +7,11 @@
  * - Reference resolution (var(--other-token))
  * - Theme detection via selectors
  * - Category inference from naming conventions
+ * - Tailwind v4 @theme blocks (via tailwind-v4-parser)
  */
 
 import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { resolve, relative } from "node:path";
 import fastGlob from "fast-glob";
 import type {
@@ -19,6 +21,7 @@ import type {
   TokenParseResult,
   TokenParseError,
 } from "../core/index.js";
+import { parseTailwindV4Theme } from "./tailwind-v4-parser.js";
 
 /**
  * Pattern to match CSS custom property declarations
@@ -78,6 +81,16 @@ export async function parseTokenFile(
       ? relative(projectRoot, filePath)
       : filePath;
 
+    // If the file contains @theme blocks, also extract tokens via the v4 parser
+    if (containsTailwindV4Theme(content)) {
+      const v4Result = parseTailwindV4Theme(content, relativePath);
+      tokens.push(...v4Result.tokens);
+      warnings.push(...v4Result.warnings);
+      for (const err of v4Result.errors) {
+        errors.push({ message: err, file: filePath });
+      }
+    }
+
     // Track which tokens we've seen for reference resolution
     const tokensByName = new Map<string, { rawValue: string; line?: number }>();
 
@@ -502,3 +515,46 @@ export function normalizeColor(color: string): string {
 
   return color.toLowerCase();
 }
+
+// ─── Tailwind v4 @theme Parser Integration ──────────────────────────────────
+
+/**
+ * Parse a CSS file containing Tailwind v4 @theme blocks.
+ *
+ * Reads the file synchronously and delegates to parseTailwindV4Theme.
+ * Returns a TokenParseResult compatible with the rest of the token pipeline.
+ */
+export function parseTailwindV4File(filePath: string): TokenParseResult {
+  const startTime = performance.now();
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const result = parseTailwindV4Theme(content, filePath);
+
+    return {
+      tokens: result.tokens,
+      errors: result.errors.map((message) => ({ message, file: filePath })),
+      warnings: result.warnings,
+      parseTimeMs: result.parseTimeMs,
+    };
+  } catch (error) {
+    return {
+      tokens: [],
+      errors: [
+        {
+          message: error instanceof Error ? error.message : "Unknown error",
+          file: filePath,
+        },
+      ],
+      warnings: [],
+      parseTimeMs: performance.now() - startTime,
+    };
+  }
+}
+
+/**
+ * Check whether a CSS file contains Tailwind v4 @theme blocks.
+ */
+export function containsTailwindV4Theme(content: string): boolean {
+  return /^@theme\b/m.test(content);
+}