@fragments-sdk/cli 0.4.4 → 0.5.0

package/dist/{viewer-H7TVFT4E.js → viewer-XDPD52L7.js}

@@ -6,13 +6,13 @@ import {
   findStorybookDir,
   generatePreviewModule,
   loadConfig
-} from "./chunk-5CKYLCJH.js";
+} from "./chunk-2H2JAA3U.js";
 import {
   generateContext
-} from "./chunk-G3M3MPQ6.js";
+} from "./chunk-B2TQKOLW.js";
 import {
   BRAND
-} from "./chunk-AW7MWOUH.js";
+} from "./chunk-ICAIQ57V.js";
 
 // src/viewer/server.ts
 import {
@@ -242,7 +242,7 @@ var sharedRenderPool = null;
 var browserPoolModule = null;
 async function getSharedRenderPool() {
   if (!browserPoolModule) {
-    browserPoolModule = await import("./service-K52ORLCJ.js");
+    browserPoolModule = await import("./service-2T26CBWE.js");
   }
   if (!sharedRenderPool) {
     sharedRenderPool = new browserPoolModule.BrowserPool({
@@ -471,7 +471,7 @@ function segmentsPlugin(options) {
             const address = _server.httpServer?.address();
             const port = typeof address === "object" && address ? address.port : 6006;
             const renderViewport = viewport || { width: 800, height: 600 };
-            const { FigmaClient, bufferToBase64Url } = await import("./service-K52ORLCJ.js");
+            const { FigmaClient, bufferToBase64Url } = await import("./service-2T26CBWE.js");
             const figmaClient = new FigmaClient({
               accessToken: figmaToken
             });
@@ -562,7 +562,7 @@ function segmentsPlugin(options) {
               );
               return;
             }
-            const { FigmaClient } = await import("./service-K52ORLCJ.js");
+            const { FigmaClient } = await import("./service-2T26CBWE.js");
             const figmaClient = new FigmaClient({ accessToken: figmaToken });
             const { fileKey, nodeId } = figmaClient.parseUrl(figmaUrl);
             const figmaDesignProps = await figmaClient.getNodeProperties(
@@ -603,7 +603,7 @@ function segmentsPlugin(options) {
               }));
               return;
             }
-            const { getSharedTokenRegistry } = await import("./service-K52ORLCJ.js");
+            const { getSharedTokenRegistry } = await import("./service-2T26CBWE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -663,7 +663,7 @@ function segmentsPlugin(options) {
               }));
               return;
             }
-            const { getSharedTokenRegistry } = await import("./service-K52ORLCJ.js");
+            const { getSharedTokenRegistry } = await import("./service-2T26CBWE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -725,7 +725,7 @@ function segmentsPlugin(options) {
               res.end(JSON.stringify({ error: "Could not resolve segment file path" }));
               return;
             }
-            const { getSharedTokenRegistry } = await import("./service-K52ORLCJ.js");
+            const { getSharedTokenRegistry } = await import("./service-2T26CBWE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -851,7 +851,7 @@ function segmentsPlugin(options) {
             }
             const { writeFile, mkdir } = await import("fs/promises");
             const { join: join2 } = await import("path");
-            const { BRAND: BRAND2 } = await import("./core-LNXDLXDP.js");
+            const { BRAND: BRAND2 } = await import("./core-NJVKKLJ4.js");
             const fragmentsDir = join2(projectRoot, BRAND2.dataDir, BRAND2.componentsDir);
             await mkdir(fragmentsDir, { recursive: true });
             const fragmentPath = join2(
@@ -906,7 +906,7 @@ function segmentsPlugin(options) {
             const {
               getSharedTokenRegistry,
               generateTokenPatches
-            } = await import("./service-K52ORLCJ.js");
+            } = await import("./service-2T26CBWE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -1568,7 +1568,7 @@ async function loadFullSegmentForCompare(_server, _segmentFiles, componentName,
   }
 }
 async function compareImages(image1Base64, image2Base64, threshold) {
-  const { DiffEngine, base64UrlToBuffer, bufferToBase64Url } = await import("./service-K52ORLCJ.js");
+  const { DiffEngine, base64UrlToBuffer, bufferToBase64Url } = await import("./service-2T26CBWE.js");
   const { PNG } = await import("pngjs");
   const buffer1 = base64UrlToBuffer(image1Base64);
   const buffer2 = base64UrlToBuffer(image2Base64);
@@ -11101,4 +11101,4 @@ export {
   segmentsPlugin,
   useTheme
 };
-//# sourceMappingURL=viewer-H7TVFT4E.js.map
+//# sourceMappingURL=viewer-XDPD52L7.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/cli",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "CLI, MCP server, and dev tools for Fragments design system",
   "type": "module",
   "bin": {

package/src/build.ts

@@ -5,13 +5,15 @@ import type {
   SegmentsConfig,
   CompiledSegmentsFile,
   CompiledSegment,
-  CompiledRecipe,
+  CompiledBlock,
+  CompiledTokenData,
 } from "./core/index.js";
-import { BRAND, compileRecipe } from "./core/index.js";
-import type { RecipeDefinition } from "./core/index.js";
+import { BRAND, compileBlock, parseTokenFile } from "./core/index.js";
+import type { BlockDefinition } from "./core/index.js";
 import {
   discoverSegmentFiles,
-  discoverRecipeFiles,
+  discoverBlockFiles,
+  discoverTokenFiles,
   parseSegmentFile,
   loadSegmentFile,
   generateRegistry,
@@ -124,11 +126,11 @@ export async function buildSegments(
     }
   }
 
-  // Discover and compile recipe files
-  const recipes: Record<string, CompiledRecipe> = {};
+  // Discover and compile block files
+  const blocks: Record<string, CompiledBlock> = {};
   try {
-    const recipeFiles = await discoverRecipeFiles(configDir, config.exclude);
-    for (const file of recipeFiles) {
+    const blockFiles = await discoverBlockFiles(configDir, config.exclude);
+    for (const file of blockFiles) {
       try {
         // loadSegmentFile uses esbuild to bundle+evaluate, returns default export
         // CJS/ESM interop may double-wrap the default export
@@ -139,18 +141,55 @@ export async function buildSegments(
         }
         const def = raw;
         if (def && typeof def === 'object' && 'name' in def && 'code' in def && 'components' in def) {
-          const compiled = compileRecipe(def as unknown as RecipeDefinition, file.relativePath);
-          recipes[compiled.name] = compiled;
+          const compiled = compileBlock(def as unknown as BlockDefinition, file.relativePath);
+          blocks[compiled.name] = compiled;
         }
       } catch (error) {
         warnings.push({
           file: file.relativePath,
-          warning: `Failed to load recipe: ${error instanceof Error ? error.message : String(error)}`,
+          warning: `Failed to load block: ${error instanceof Error ? error.message : String(error)}`,
         });
       }
     }
   } catch {
-    // Recipe discovery failure is non-fatal
+    // Block discovery failure is non-fatal
+  }
+
+  // Discover and extract design tokens from SCSS/CSS files
+  let tokens: CompiledTokenData | undefined;
+  try {
+    const tokenPatterns = config.tokens?.include;
+    const tokenFiles = await discoverTokenFiles(configDir, tokenPatterns, config.exclude);
+    if (tokenFiles.length > 0) {
+      // Merge tokens from all discovered files
+      const mergedCategories: Record<string, Array<{ name: string; description?: string }>> = {};
+      let prefix = '--';
+      let total = 0;
+
+      for (const file of tokenFiles) {
+        const content = await readFile(file.absolutePath, 'utf-8');
+        const parsed = parseTokenFile(content, file.relativePath);
+        prefix = parsed.prefix; // Use last file's prefix (usually consistent)
+        total += parsed.total;
+        for (const [cat, catTokens] of Object.entries(parsed.categories)) {
+          if (!mergedCategories[cat]) {
+            mergedCategories[cat] = [];
+          }
+          for (const t of catTokens) {
+            // Deduplicate by name
+            if (!mergedCategories[cat].some((e) => e.name === t.name)) {
+              mergedCategories[cat].push({ name: t.name, description: t.description });
+            }
+          }
+        }
+      }
+
+      if (total > 0) {
+        tokens = { prefix, total, categories: mergedCategories };
+      }
+    }
+  } catch {
+    // Token extraction failure is non-fatal
   }
 
   // Read package name for import statements
@@ -170,7 +209,8 @@ export async function buildSegments(
     generatedAt: new Date().toISOString(),
     ...(packageName && { packageName }),
     segments,
-    ...(Object.keys(recipes).length > 0 && { recipes }),
+    ...(Object.keys(blocks).length > 0 && { blocks }),
+    ...(tokens && { tokens }),
   };
 
   const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);

package/src/core/constants.ts

@@ -66,7 +66,10 @@ export const BRAND = {
   /** MCP tool name prefix (e.g., "fragments_") */
   mcpToolPrefix: "fragments_",
 
-  /** File extension for recipe definition files */
+  /** File extension for block definition files */
+  blockFileExtension: ".block.ts",
+
+  /** @deprecated Use blockFileExtension instead */
   recipeFileExtension: ".recipe.ts",
 
   /** Vite plugin namespace */

package/src/core/context.ts

@@ -1,4 +1,4 @@
-import type { CompiledSegment, CompiledRecipe, PropDefinition } from "./types.js";
+import type { CompiledSegment, CompiledBlock, PropDefinition } from "./types.js";
 
 /**
  * Placeholder patterns to filter out from usage text.
@@ -55,12 +55,12 @@ export interface ContextResult {
 }
 
 /**
- * Generate AI-ready context from compiled segments and optional recipes
+ * Generate AI-ready context from compiled segments and optional blocks
  */
 export function generateContext(
   segments: CompiledSegment[],
   options: ContextOptions = {},
-  recipes?: CompiledRecipe[]
+  blocks?: CompiledBlock[]
 ): ContextResult {
   const format = options.format ?? "markdown";
   const compact = options.compact ?? false;
@@ -81,10 +81,10 @@ export function generateContext(
   });
 
   if (format === "json") {
-    return generateJsonContext(sorted, include, compact, recipes);
+    return generateJsonContext(sorted, include, compact, blocks);
   }
 
-  return generateMarkdownContext(sorted, include, compact, recipes);
+  return generateMarkdownContext(sorted, include, compact, blocks);
 }
 
 /**
@@ -94,7 +94,7 @@ function generateMarkdownContext(
   segments: CompiledSegment[],
   include: Required<NonNullable<ContextOptions["include"]>>,
   compact: boolean,
-  recipes?: CompiledRecipe[]
+  blocks?: CompiledBlock[]
 ): ContextResult {
   const lines: string[] = [];
 
@@ -209,26 +209,26 @@ function generateMarkdownContext(
     lines.push("");
   }
 
-  // Recipes section
-  if (recipes && recipes.length > 0) {
-    lines.push("## Recipes");
+  // Blocks section
+  if (blocks && blocks.length > 0) {
+    lines.push("## Blocks");
     lines.push("");
     lines.push("Composition patterns showing how components wire together.");
     lines.push("");
 
-    for (const recipe of recipes) {
-      lines.push(`### ${recipe.name}`);
+    for (const block of blocks) {
+      lines.push(`### ${block.name}`);
       lines.push("");
-      lines.push(recipe.description);
+      lines.push(block.description);
       lines.push("");
-      lines.push(`**Category:** ${recipe.category}`);
-      lines.push(`**Components:** ${recipe.components.join(", ")}`);
-      if (recipe.tags && recipe.tags.length > 0) {
-        lines.push(`**Tags:** ${recipe.tags.join(", ")}`);
+      lines.push(`**Category:** ${block.category}`);
+      lines.push(`**Components:** ${block.components.join(", ")}`);
+      if (block.tags && block.tags.length > 0) {
+        lines.push(`**Tags:** ${block.tags.join(", ")}`);
       }
       lines.push("");
       lines.push("```tsx");
-      lines.push(recipe.code);
+      lines.push(block.code);
       lines.push("```");
       lines.push("");
       lines.push("---");
@@ -250,7 +250,7 @@ function generateJsonContext(
   segments: CompiledSegment[],
   include: Required<NonNullable<ContextOptions["include"]>>,
   compact: boolean,
-  recipes?: CompiledRecipe[]
+  blocks?: CompiledBlock[]
 ): ContextResult {
   const categories = [...new Set(segments.map((s) => s.meta.category))].sort();
 
@@ -321,14 +321,14 @@ function generateJsonContext(
     components[segment.meta.name] = component;
   }
 
-  // Build recipes map
-  const recipesMap = recipes && recipes.length > 0
-    ? Object.fromEntries(recipes.map(r => [r.name, {
-        description: r.description,
-        category: r.category,
-        components: r.components,
-        code: r.code,
-        tags: r.tags,
+  // Build blocks map
+  const blocksMap = blocks && blocks.length > 0
+    ? Object.fromEntries(blocks.map(b => [b.name, {
+        description: b.description,
+        category: b.category,
+        components: b.components,
+        code: b.code,
+        tags: b.tags,
       }]))
     : undefined;
 
@@ -338,10 +338,10 @@ function generateJsonContext(
     summary: {
       totalComponents: segments.length,
       categories,
-      ...(recipesMap && { totalRecipes: recipes!.length }),
+      ...(blocksMap && { totalBlocks: blocks!.length }),
     },
     components,
-    ...(recipesMap && { recipes: recipesMap }),
+    ...(blocksMap && { blocks: blocksMap }),
   };
 
   const content = JSON.stringify(output, null, 2);

package/src/core/defineSegment.ts

@@ -1,5 +1,5 @@
-import type { SegmentDefinition, CompiledSegment, SegmentComponent, RecipeDefinition, CompiledRecipe } from './types.js';
-import { segmentDefinitionSchema, recipeDefinitionSchema } from './schema.js';
+import type { SegmentDefinition, CompiledSegment, SegmentComponent, BlockDefinition, CompiledBlock } from './types.js';
+import { segmentDefinitionSchema, blockDefinitionSchema } from './schema.js';
 
 /**
  * Define a segment for a component.
@@ -92,20 +92,20 @@ export function compileSegment(
 }
 
 /**
- * Define a composition recipe.
+ * Define a composition block.
  *
- * Recipes are pure data describing how design system components
+ * Blocks are pure data describing how design system components
  * wire together for common use cases.
  */
-export function defineRecipe(definition: RecipeDefinition): RecipeDefinition {
+export function defineBlock(definition: BlockDefinition): BlockDefinition {
   if (process.env.NODE_ENV !== 'production') {
-    const result = recipeDefinitionSchema.safeParse(definition);
+    const result = blockDefinitionSchema.safeParse(definition);
     if (!result.success) {
       const errors = result.error.errors
         .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
         .join('\n');
       throw new Error(
-        `Invalid recipe definition for "${definition.name || 'unknown'}":\n${errors}`
+        `Invalid block definition for "${definition.name || 'unknown'}":\n${errors}`
       );
     }
   }
@@ -114,12 +114,17 @@ export function defineRecipe(definition: RecipeDefinition): RecipeDefinition {
 }
 
 /**
- * Compile a recipe definition to JSON-serializable format.
+ * @deprecated Use defineBlock instead
  */
-export function compileRecipe(
-  definition: RecipeDefinition,
+export const defineRecipe = defineBlock;
+
+/**
+ * Compile a block definition to JSON-serializable format.
+ */
+export function compileBlock(
+  definition: BlockDefinition,
   filePath: string
-): CompiledRecipe {
+): CompiledBlock {
   return {
     filePath,
     name: definition.name,
@@ -131,6 +136,11 @@ export function compileRecipe(
   };
 }
 
+/**
+ * @deprecated Use compileBlock instead
+ */
+export const compileRecipe = compileBlock;
+
 /**
  * Type helper for extracting props type from a component
  */

package/src/core/discovery.ts

@@ -27,14 +27,18 @@ export interface DiscoveredComponent {
 }
 
 /**
- * Discover recipe files (*.recipe.ts) under the config directory
+ * Discover block files (*.block.ts) under the config directory.
+ * Also discovers legacy *.recipe.ts files for backward compatibility.
  */
-export async function discoverRecipeFiles(
+export async function discoverBlockFiles(
   configDir: string,
   exclude?: string[]
 ): Promise<DiscoveredFile[]> {
-  const pattern = `**/*${BRAND.recipeFileExtension}`;
-  const files = await fg(pattern, {
+  const patterns = [
+    `**/*${BRAND.blockFileExtension}`,
+    `**/*${BRAND.recipeFileExtension}`,
+  ];
+  const files = await fg(patterns, {
     cwd: configDir,
     ignore: exclude ?? ['**/node_modules/**', '**/dist/**'],
     absolute: false,
@@ -46,6 +50,11 @@ export async function discoverRecipeFiles(
   }));
 }
 
+/**
+ * @deprecated Use discoverBlockFiles instead
+ */
+export const discoverRecipeFiles = discoverBlockFiles;
+
 /**
  * Discover segment files matching the config patterns
  */
@@ -296,6 +305,45 @@ export async function discoverComponentsFromBarrel(
   return components;
 }
 
+/**
+ * Default glob patterns for discovering token files (SCSS/CSS with custom properties)
+ */
+const DEFAULT_TOKEN_PATTERNS = [
+  'src/**/tokens/**/_variables.scss',
+  'src/**/tokens/**/variables.scss',
+  'src/**/styles/**/variables.scss',
+  'src/**/styles/**/tokens.scss',
+  'src/**/styles/**/variables.css',
+  'src/**/theme/**/_variables.scss',
+  'src/**/theme/**/tokens.css',
+];
+
+/**
+ * Discover token files (SCSS/CSS files containing CSS custom properties).
+ * Uses config.tokens.include patterns if provided, otherwise falls back
+ * to default patterns that match common project structures.
+ */
+export async function discoverTokenFiles(
+  configDir: string,
+  patterns?: string[],
+  exclude?: string[]
+): Promise<DiscoveredFile[]> {
+  const searchPatterns = patterns && patterns.length > 0
+    ? patterns
+    : DEFAULT_TOKEN_PATTERNS;
+
+  const files = await fg(searchPatterns, {
+    cwd: configDir,
+    ignore: exclude ?? ['**/node_modules/**', '**/dist/**'],
+    absolute: false,
+  });
+
+  return files.map((relativePath) => ({
+    relativePath,
+    absolutePath: resolve(configDir, relativePath),
+  }));
+}
+
 /**
  * Discover fragment files from installed packages that declare a "fragments" field
  * in their package.json. This allows consumer projects to see components from

package/src/core/index.ts

@@ -27,8 +27,10 @@ export type {
   RegistryOptions,
   CompiledSegment,
   CompiledSegmentsFile,
-  RecipeDefinition,
-  CompiledRecipe,
+  BlockDefinition,
+  CompiledBlock,
+  RecipeDefinition, // @deprecated - use BlockDefinition
+  CompiledRecipe, // @deprecated - use CompiledBlock
   // Contract and provenance types
   SegmentContract,
   SegmentGenerated,
@@ -57,6 +59,9 @@ export type {
   FigmaTextContentMapping,
   // Token configuration
   TokenConfig,
+  // Compiled token types
+  CompiledTokenEntry,
+  CompiledTokenData,
 } from "./types.js";
 
 // Token types
@@ -88,13 +93,14 @@ export {
   segmentContractSchema,
   segmentGeneratedSchema,
   segmentBanSchema,
-  recipeDefinitionSchema,
+  blockDefinitionSchema,
+  recipeDefinitionSchema, // @deprecated - use blockDefinitionSchema
   // AI metadata schema
   aiMetadataSchema,
 } from "./schema.js";
 
 // Main API
-export { defineSegment, defineFragment, compileSegment, defineRecipe, compileRecipe } from "./defineSegment.js";
+export { defineSegment, defineFragment, compileSegment, defineBlock, compileBlock, defineRecipe, compileRecipe } from "./defineSegment.js";
 export type { InferProps } from "./defineSegment.js";
 
 // Story adapter (runtime conversion of Storybook modules)
@@ -143,6 +149,10 @@ export type {
   FragmentContextOptions,
 } from "./fragment-types.js";
 
+// Token parsing
+export { parseTokenFile } from "./token-parser.js";
+export type { ParsedToken, TokenParseOutput } from "./token-parser.js";
+
 // Composition analysis
 export { analyzeComposition } from "./composition.js";
 export type {

package/src/core/loader.ts

@@ -14,6 +14,9 @@ export function defineSegment(def) {
 export function defineFragment(def) {
   return def;
 }
+export function defineBlock(def) {
+  return def;
+}
 export function defineRecipe(def) {
   return def;
 }

package/src/core/node.ts

@@ -9,7 +9,8 @@ export { loadConfig, findConfigFile } from './config.js';
 // Discovery
 export {
   discoverSegmentFiles,
-  discoverRecipeFiles,
+  discoverBlockFiles,
+  discoverRecipeFiles, // @deprecated - use discoverBlockFiles
   discoverComponentFiles,
   discoverInstalledFragments,
   extractComponentName,
@@ -17,6 +18,7 @@ export {
   discoverComponentsFromSource,
   discoverComponentsFromBarrel,
   discoverAllComponents,
+  discoverTokenFiles,
 } from './discovery.js';
 export type { DiscoveredFile, DiscoveredComponent } from './discovery.js';
 

package/src/core/parser.ts

@@ -375,7 +375,7 @@ function extractVariants(
 
         // Try to extract code property if present
         const codeProp = findProperty(element, "code");
-        if (codeProp && ts.isStringLiteral(codeProp)) {
+        if (codeProp && (ts.isStringLiteral(codeProp) || ts.isNoSubstitutionTemplateLiteral(codeProp))) {
           variant.code = codeProp.text;
         }
 

package/src/core/schema.ts

@@ -149,9 +149,9 @@ export const aiMetadataSchema = z.object({
 });
 
 /**
- * Schema for recipe definitions
+ * Schema for block definitions
  */
-export const recipeDefinitionSchema = z.object({
+export const blockDefinitionSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   category: z.string().min(1),
@@ -191,3 +191,8 @@ export const segmentsConfigSchema = z.object({
     include: z.array(z.string()).min(1),
   }).passthrough().optional(),
 });
+
+/**
+ * @deprecated Use blockDefinitionSchema instead
+ */
+export const recipeDefinitionSchema = blockDefinitionSchema;