@fragments-sdk/cli 0.3.3 → 0.4.0

package/dist/{viewer-D7QC4GM2.js → viewer-6VCZMA3T.js}

@@ -6,13 +6,13 @@ import {
   findStorybookDir,
   generatePreviewModule,
   loadConfig
-} from "./chunk-PMGI7ATF.js";
+} from "./chunk-OZQ7Z6C3.js";
 import {
   generateContext
-} from "./chunk-LY2CFFPY.js";
+} from "./chunk-FYIYMXGA.js";
 import {
   BRAND
-} from "./chunk-XHNKNI6J.js";
+} from "./chunk-AW7MWOUH.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-QSZMZJBJ.js");
+    browserPoolModule = await import("./service-U7AR2PC2.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-QSZMZJBJ.js");
+            const { FigmaClient, bufferToBase64Url } = await import("./service-U7AR2PC2.js");
             const figmaClient = new FigmaClient({
               accessToken: figmaToken
             });
@@ -562,7 +562,7 @@ function segmentsPlugin(options) {
               );
               return;
             }
-            const { FigmaClient } = await import("./service-QSZMZJBJ.js");
+            const { FigmaClient } = await import("./service-U7AR2PC2.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-QSZMZJBJ.js");
+            const { getSharedTokenRegistry } = await import("./service-U7AR2PC2.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-QSZMZJBJ.js");
+            const { getSharedTokenRegistry } = await import("./service-U7AR2PC2.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-QSZMZJBJ.js");
+            const { getSharedTokenRegistry } = await import("./service-U7AR2PC2.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-DWKLGY4N.js");
+            const { BRAND: BRAND2 } = await import("./core-F3VT277E.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-QSZMZJBJ.js");
+            } = await import("./service-U7AR2PC2.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-QSZMZJBJ.js");
+  const { DiffEngine, base64UrlToBuffer, bufferToBase64Url } = await import("./service-U7AR2PC2.js");
   const { PNG } = await import("pngjs");
   const buffer1 = base64UrlToBuffer(image1Base64);
   const buffer2 = base64UrlToBuffer(image2Base64);
@@ -11101,4 +11101,4 @@ export {
   segmentsPlugin,
   useTheme
 };
-//# sourceMappingURL=viewer-D7QC4GM2.js.map
+//# sourceMappingURL=viewer-6VCZMA3T.js.map

package/package.json

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

package/src/bin.ts

@@ -8,9 +8,15 @@
 
 import { Command } from 'commander';
 import pc from 'picocolors';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { BRAND } from './core/index.js';
 import { loadConfig } from './core/node.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8')) as { version: string };
+
 // Import command implementations
 import { validate } from './commands/validate.js';
 import { build } from './commands/build.js';
@@ -40,7 +46,7 @@ const program = new Command();
 program
   .name(BRAND.cliCommand)
   .description(`${BRAND.name} - Design system documentation and compliance tool`)
-  .version('0.1.0');
+  .version(pkg.version);
 
 // ============================================================================
 // VALIDATE COMMAND

package/src/build.ts

@@ -111,6 +111,8 @@ export async function buildSegments(
           ...(v.figma && { figma: v.figma }),
           ...(v.args && { args: v.args }),
         })),
+        // Include AI metadata if present
+        ...(parsed.ai && { ai: parsed.ai }),
       };
 
       segments[parsed.meta.name] = compiled;

package/src/core/index.ts

@@ -32,6 +32,8 @@ export type {
   // Contract and provenance types
   SegmentContract,
   SegmentGenerated,
+  // AI metadata type
+  AIMetadata,
   // Screenshot types
   ScreenshotConfig,
   ServiceConfig,
@@ -87,6 +89,8 @@ export {
   segmentGeneratedSchema,
   segmentBanSchema,
   recipeDefinitionSchema,
+  // AI metadata schema
+  aiMetadataSchema,
 } from "./schema.js";
 
 // Main API

package/src/core/parser.ts

@@ -8,7 +8,7 @@
  */
 
 import ts from "typescript";
-import type { SegmentMeta, SegmentUsage, PropDefinition } from "./types.js";
+import type { SegmentMeta, SegmentUsage, PropDefinition, AIMetadata } from "./types.js";
 
 /**
  * Parsed segment metadata (extracted statically from AST)
@@ -45,6 +45,9 @@ export interface ParsedSegmentMetadata {
     note: string;
   }>;
 
+  /** AI-specific metadata for playground context generation */
+  ai?: AIMetadata;
+
   /** Parse warnings */
   warnings: string[];
 }
@@ -129,6 +132,9 @@ export function parseSegmentFile(
   // Extract relations
   const relations = extractRelations(arg, warnings);
 
+  // Extract AI metadata
+  const ai = extractAIMetadata(arg, warnings);
+
   return {
     componentImport,
     componentName,
@@ -137,6 +143,7 @@ export function parseSegmentFile(
     props,
     variants,
     relations,
+    ai,
     warnings,
   };
 }
@@ -460,6 +467,52 @@ function extractRelations(
   return relations;
 }
 
+/**
+ * Extract AI metadata from defineSegment call.
+ */
+function extractAIMetadata(
+  arg: ts.ObjectLiteralExpression,
+  warnings: string[]
+): AIMetadata | undefined {
+  const aiProp = findProperty(arg, "ai");
+  if (!aiProp || !ts.isObjectLiteralExpression(aiProp)) {
+    return undefined;
+  }
+
+  const ai: AIMetadata = {};
+
+  // Extract compositionPattern
+  const compositionPattern = extractStringProperty(aiProp, "compositionPattern");
+  if (compositionPattern && ['compound', 'simple', 'controlled'].includes(compositionPattern)) {
+    ai.compositionPattern = compositionPattern as AIMetadata['compositionPattern'];
+  }
+
+  // Extract subComponents array
+  const subComponents = extractStringArray(aiProp, "subComponents");
+  if (subComponents.length > 0) {
+    ai.subComponents = subComponents;
+  }
+
+  // Extract requiredChildren array
+  const requiredChildren = extractStringArray(aiProp, "requiredChildren");
+  if (requiredChildren.length > 0) {
+    ai.requiredChildren = requiredChildren;
+  }
+
+  // Extract commonPatterns array
+  const commonPatterns = extractStringArray(aiProp, "commonPatterns");
+  if (commonPatterns.length > 0) {
+    ai.commonPatterns = commonPatterns;
+  }
+
+  // Only return if we have any fields
+  if (Object.keys(ai).length > 0) {
+    return ai;
+  }
+
+  return undefined;
+}
+
 /**
  * Extract a string property from an object literal.
  */

package/src/core/schema.ts

@@ -138,6 +138,16 @@ export const segmentGeneratedSchema = z.object({
   timestamp: z.string().datetime().optional(),
 });
 
+/**
+ * Schema for AI-specific metadata for playground context generation
+ */
+export const aiMetadataSchema = z.object({
+  compositionPattern: z.enum(['compound', 'simple', 'controlled']).optional(),
+  subComponents: z.array(z.string()).optional(),
+  requiredChildren: z.array(z.string()).optional(),
+  commonPatterns: z.array(z.string()).optional(),
+});
+
 /**
  * Schema for recipe definitions
  */
@@ -158,6 +168,7 @@ export const segmentDefinitionSchema = z.object({
   relations: z.array(componentRelationSchema).optional(),
   variants: z.array(segmentVariantSchema), // Allow empty variants array
   contract: segmentContractSchema.optional(),
+  ai: aiMetadataSchema.optional(),
   _generated: segmentGeneratedSchema.optional(),
 });
 

package/src/core/types.ts

@@ -314,6 +314,24 @@ export interface SegmentGenerated {
   timestamp?: string;
 }
 
+/**
+ * AI-specific metadata for playground context generation
+ * Provides hints for AI code generation about component composition
+ */
+export interface AIMetadata {
+  /** How this component is composed with others */
+  compositionPattern?: "compound" | "simple" | "controlled";
+
+  /** Sub-component names (without parent prefix, e.g., "Header" not "Card.Header") */
+  subComponents?: string[];
+
+  /** Sub-components that must be present for valid composition */
+  requiredChildren?: string[];
+
+  /** Common usage patterns as JSX strings for AI reference */
+  commonPatterns?: string[];
+}
+
 /**
  * Complete segment definition
  */
@@ -339,6 +357,9 @@ export interface SegmentDefinition<TProps = unknown> {
   /** Agent-optimized contract metadata */
   contract?: SegmentContract;
 
+  /** AI-specific metadata for playground context generation */
+  ai?: AIMetadata;
+
   /** Provenance tracking (for generated segments) */
   _generated?: SegmentGenerated;
 }
@@ -706,6 +727,9 @@ export interface CompiledSegment {
   /** Agent-optimized contract metadata */
   contract?: SegmentContract;
 
+  /** AI-specific metadata for playground context generation */
+  ai?: AIMetadata;
+
   /** Provenance tracking (for generated segments) */
   _generated?: SegmentGenerated;
 }

package/src/migrate/bin.ts

@@ -7,15 +7,21 @@
 
 import { Command } from "commander";
 import pc from "picocolors";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { BRAND } from "../core/index.js";
 import { migrate } from "./migrate.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8")) as { version: string };
+
 const program = new Command();
 
 program
   .name("segments-migrate")
   .description(`${BRAND.name} Storybook Migration Tool`)
-  .version("0.0.1");
+  .version(pkg.version);
 
 program
   .command("migrate")

package/src/migrate/report.ts

@@ -49,7 +49,7 @@ function getStyles(): string {
       --bg-warning: rgba(234, 179, 8, 0.1);
       --bg-error: rgba(239, 68, 68, 0.1);
       --border: #262626;
-      --text: #fafafa;
+      --text: #f2f2f2;
       --text-secondary: #a1a1aa;
       --text-muted: #71717a;
       --accent: #8b5cf6;

package/src/service/report.ts

@@ -61,7 +61,7 @@ function getStyles(): string {
       --bg-card: #141414;
       --bg-hover: #1a1a1a;
       --border: #262626;
-      --text: #fafafa;
+      --text: #f2f2f2;
       --text-secondary: #a1a1aa;
       --text-muted: #71717a;
       --accent: #10b981;