@fragments-sdk/cli 0.4.4 → 0.5.1

package/dist/{viewer-H7TVFT4E.js → viewer-YDGFDTK5.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-V7YLRR4C.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-RWUMZ3EW.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-RWUMZ3EW.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-RWUMZ3EW.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-RWUMZ3EW.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-RWUMZ3EW.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-RWUMZ3EW.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-DKHB7FYV.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-RWUMZ3EW.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-RWUMZ3EW.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-YDGFDTK5.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/cli",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "CLI, MCP server, and dev tools for Fragments design system",
   "type": "module",
   "bin": {
@@ -63,7 +63,8 @@
     "tailwindcss": "^3.4.17",
     "vite": "^6.0.0",
     "vite-plugin-svgr": "^4.5.0",
-    "zod": "^3.24.1"
+    "zod": "^3.24.1",
+    "@fragments-sdk/context": "0.2.0"
   },
   "devDependencies": {
     "@types/babel__generator": "^7.6.8",

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,380 +1,2 @@
-import type { CompiledSegment, CompiledRecipe, PropDefinition } from "./types.js";
-
-/**
- * Placeholder patterns to filter out from usage text.
- * These are generated by the migrate tool and provide no value.
- */
-const PLACEHOLDER_PATTERNS = [
-  /^\w+ component is needed$/i,
-  /^Alternative component is more appropriate$/i,
-  /^Use \w+ when you need/i,
-];
-
-/**
- * Filter out placeholder text from usage arrays
- */
-function filterPlaceholders(items: string[]): string[] {
-  return items.filter(item =>
-    !PLACEHOLDER_PATTERNS.some(pattern => pattern.test(item.trim()))
-  );
-}
-
-/**
- * Options for context generation
- */
-export interface ContextOptions {
-  /** Output format */
-  format?: "markdown" | "json";
-
-  /** What to include in the output */
-  include?: {
-    /** Include prop details (default: true) */
-    props?: boolean;
-    /** Include variant list (default: true) */
-    variants?: boolean;
-    /** Include usage guidelines (default: true) */
-    usage?: boolean;
-    /** Include related components (default: false) */
-    relations?: boolean;
-    /** Include code examples (default: false) */
-    code?: boolean;
-  };
-
-  /** Compact mode - minimal output for token efficiency */
-  compact?: boolean;
-}
-
-/**
- * Result of context generation
- */
-export interface ContextResult {
-  /** The generated context content */
-  content: string;
-  /** Estimated token count */
-  tokenEstimate: number;
-}
-
-/**
- * Generate AI-ready context from compiled segments and optional recipes
- */
-export function generateContext(
-  segments: CompiledSegment[],
-  options: ContextOptions = {},
-  recipes?: CompiledRecipe[]
-): ContextResult {
-  const format = options.format ?? "markdown";
-  const compact = options.compact ?? false;
-
-  const include = {
-    props: options.include?.props ?? true,
-    variants: options.include?.variants ?? true,
-    usage: options.include?.usage ?? true,
-    relations: options.include?.relations ?? false,
-    code: options.include?.code ?? false,
-  };
-
-  // Sort segments by category, then name
-  const sorted = [...segments].sort((a, b) => {
-    const catCompare = a.meta.category.localeCompare(b.meta.category);
-    if (catCompare !== 0) return catCompare;
-    return a.meta.name.localeCompare(b.meta.name);
-  });
-
-  if (format === "json") {
-    return generateJsonContext(sorted, include, compact, recipes);
-  }
-
-  return generateMarkdownContext(sorted, include, compact, recipes);
-}
-
-/**
- * Generate markdown context
- */
-function generateMarkdownContext(
-  segments: CompiledSegment[],
-  include: Required<NonNullable<ContextOptions["include"]>>,
-  compact: boolean,
-  recipes?: CompiledRecipe[]
-): ContextResult {
-  const lines: string[] = [];
-
-  lines.push("# Design System Reference");
-  lines.push("");
-
-  // Quick reference table
-  lines.push("## Quick Reference");
-  lines.push("");
-  lines.push("| Component | Category | Use For |");
-  lines.push("|-----------|----------|---------|");
-
-  for (const segment of segments) {
-    const filteredWhen = filterPlaceholders(segment.usage.when);
-    const useFor = filteredWhen.slice(0, 2).join(", ") || segment.meta.description;
-    lines.push(`| ${segment.meta.name} | ${segment.meta.category} | ${truncate(useFor, 50)} |`);
-  }
-
-  lines.push("");
-
-  // If compact mode, stop here
-  if (compact) {
-    const content = lines.join("\n");
-    return {
-      content,
-      tokenEstimate: estimateTokens(content),
-    };
-  }
-
-  // Full component documentation
-  lines.push("## Components");
-  lines.push("");
-
-  for (const segment of segments) {
-    lines.push(`### ${segment.meta.name}`);
-    lines.push("");
-
-    // Status line
-    const statusParts = [`**Category:** ${segment.meta.category}`];
-    if (segment.meta.status) {
-      statusParts.push(`**Status:** ${segment.meta.status}`);
-    }
-    lines.push(statusParts.join(" | "));
-    lines.push("");
-
-    if (segment.meta.description) {
-      lines.push(segment.meta.description);
-      lines.push("");
-    }
-
-    // Usage guidelines (filter out placeholder text)
-    const whenFiltered = filterPlaceholders(segment.usage.when);
-    const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
-
-    if (include.usage && (whenFiltered.length > 0 || whenNotFiltered.length > 0)) {
-      if (whenFiltered.length > 0) {
-        lines.push("**When to use:**");
-        for (const when of whenFiltered) {
-          lines.push(`- ${when}`);
-        }
-        lines.push("");
-      }
-
-      if (whenNotFiltered.length > 0) {
-        lines.push("**When NOT to use:**");
-        for (const whenNot of whenNotFiltered) {
-          lines.push(`- ${whenNot}`);
-        }
-        lines.push("");
-      }
-    }
-
-    // Props
-    if (include.props && Object.keys(segment.props).length > 0) {
-      lines.push("**Props:**");
-      for (const [name, prop] of Object.entries(segment.props)) {
-        lines.push(`- \`${name}\`: ${formatPropType(prop)}${prop.required ? " (required)" : ""}`);
-      }
-      lines.push("");
-    }
-
-    // Variants
-    if (include.variants && segment.variants.length > 0) {
-      const variantNames = segment.variants.map((v) => v.name).join(", ");
-      lines.push(`**Variants:** ${variantNames}`);
-      lines.push("");
-
-      // Code examples
-      if (include.code) {
-        for (const variant of segment.variants) {
-          if (variant.code) {
-            lines.push(`*${variant.name}:*`);
-            lines.push("```tsx");
-            lines.push(variant.code);
-            lines.push("```");
-            lines.push("");
-          }
-        }
-      }
-    }
-
-    // Relations
-    if (include.relations && segment.relations && segment.relations.length > 0) {
-      lines.push("**Related:**");
-      for (const relation of segment.relations) {
-        lines.push(`- ${relation.component} (${relation.relationship}): ${relation.note}`);
-      }
-      lines.push("");
-    }
-
-    lines.push("---");
-    lines.push("");
-  }
-
-  // Recipes section
-  if (recipes && recipes.length > 0) {
-    lines.push("## Recipes");
-    lines.push("");
-    lines.push("Composition patterns showing how components wire together.");
-    lines.push("");
-
-    for (const recipe of recipes) {
-      lines.push(`### ${recipe.name}`);
-      lines.push("");
-      lines.push(recipe.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("");
-      lines.push("```tsx");
-      lines.push(recipe.code);
-      lines.push("```");
-      lines.push("");
-      lines.push("---");
-      lines.push("");
-    }
-  }
-
-  const content = lines.join("\n");
-  return {
-    content,
-    tokenEstimate: estimateTokens(content),
-  };
-}
-
-/**
- * Generate JSON context
- */
-function generateJsonContext(
-  segments: CompiledSegment[],
-  include: Required<NonNullable<ContextOptions["include"]>>,
-  compact: boolean,
-  recipes?: CompiledRecipe[]
-): ContextResult {
-  const categories = [...new Set(segments.map((s) => s.meta.category))].sort();
-
-  interface JsonComponent {
-    category: string;
-    description: string;
-    status?: string;
-    whenToUse?: string[];
-    whenNotToUse?: string[];
-    props?: Record<string, { type: string; required?: boolean; default?: unknown; description: string }>;
-    variants?: string[];
-    relations?: Array<{ component: string; relationship: string; note: string }>;
-  }
-
-  const components: Record<string, JsonComponent> = {};
-
-  for (const segment of segments) {
-    const component: JsonComponent = {
-      category: segment.meta.category,
-      description: segment.meta.description,
-    };
-
-    if (segment.meta.status) {
-      component.status = segment.meta.status;
-    }
-
-    if (!compact) {
-      if (include.usage) {
-        const whenFiltered = filterPlaceholders(segment.usage.when);
-        const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
-        if (whenFiltered.length > 0) {
-          component.whenToUse = whenFiltered;
-        }
-        if (whenNotFiltered.length > 0) {
-          component.whenNotToUse = whenNotFiltered;
-        }
-      }
-
-      if (include.props && Object.keys(segment.props).length > 0) {
-        component.props = {};
-        for (const [name, prop] of Object.entries(segment.props)) {
-          component.props[name] = {
-            type: formatPropType(prop),
-            description: prop.description,
-          };
-          if (prop.required) {
-            component.props[name].required = true;
-          }
-          if (prop.default !== undefined) {
-            component.props[name].default = prop.default;
-          }
-        }
-      }
-
-      if (include.variants && segment.variants.length > 0) {
-        component.variants = segment.variants.map((v) => v.name);
-      }
-
-      if (include.relations && segment.relations && segment.relations.length > 0) {
-        component.relations = segment.relations.map((r) => ({
-          component: r.component,
-          relationship: r.relationship,
-          note: r.note,
-        }));
-      }
-    }
-
-    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,
-      }]))
-    : undefined;
-
-  const output = {
-    version: "1.0",
-    generatedAt: new Date().toISOString(),
-    summary: {
-      totalComponents: segments.length,
-      categories,
-      ...(recipesMap && { totalRecipes: recipes!.length }),
-    },
-    components,
-    ...(recipesMap && { recipes: recipesMap }),
-  };
-
-  const content = JSON.stringify(output, null, 2);
-  return {
-    content,
-    tokenEstimate: estimateTokens(content),
-  };
-}
-
-/**
- * Format a prop type for display
- */
-function formatPropType(prop: PropDefinition): string {
-  if (prop.type === "enum" && prop.values) {
-    return prop.values.map((v) => `"${v}"`).join(" | ");
-  }
-  if (prop.default !== undefined) {
-    return `${prop.type} (default: ${JSON.stringify(prop.default)})`;
-  }
-  return prop.type;
-}
-
-/**
- * Truncate string to max length
- */
-function truncate(str: string, maxLength: number): string {
-  if (str.length <= maxLength) return str;
-  return str.slice(0, maxLength - 3) + "...";
-}
-
-/**
- * Estimate token count (rough approximation: ~4 chars per token)
- */
-function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
+export { generateContext, filterPlaceholders, PLACEHOLDER_PATTERNS } from '@fragments-sdk/context/generate';
+export type { ContextOptions, ContextResult } from '@fragments-sdk/context/generate';

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
  */