@fragments-sdk/cli 0.3.2 → 0.4.0

package/src/build.ts

@@ -1,5 +1,6 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
+import { existsSync } from "node:fs";
 import type {
   SegmentsConfig,
   CompiledSegmentsFile,
@@ -110,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;
@@ -150,9 +153,22 @@ export async function buildSegments(
     // Recipe discovery failure is non-fatal
   }
 
+  // Read package name for import statements
+  let packageName: string | undefined;
+  const pkgJsonPath = resolve(configDir, "package.json");
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(await readFile(pkgJsonPath, "utf-8"));
+      if (pkg.name) packageName = pkg.name;
+    } catch {
+      // Non-fatal
+    }
+  }
+
   const output: CompiledSegmentsFile = {
     version: "1.0.0",
     generatedAt: new Date().toISOString(),
+    ...(packageName && { packageName }),
     segments,
     ...(Object.keys(recipes).length > 0 && { recipes }),
   };

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;
 }
@@ -746,6 +770,9 @@ export interface CompiledSegmentsFile {
   /** When this file was generated */
   generatedAt: string;
 
+  /** Package name for import statements (read from package.json at build time) */
+  packageName?: string;
+
   /** All compiled segments indexed by component name */
   segments: Record<string, CompiledSegment>;
 

package/src/mcp/server.ts

@@ -366,13 +366,23 @@ export function createMcpServer(config: McpServerConfig): Server {
   }
 
   /**
-   * Get the package name from package.json for import statements
+   * Get the package name for import statements.
+   * Prefers packageName from fragments.json (set at build time),
+   * falls back to the project's package.json name.
    */
   async function getPackageName(): Promise<string> {
     if (packageName) {
       return packageName;
     }
 
+    // Prefer packageName from compiled fragments.json
+    const data = await loadSegments();
+    if (data.packageName) {
+      packageName = data.packageName;
+      return packageName;
+    }
+
+    // Fallback to project package.json
     const packageJsonPath = join(config.projectRoot, 'package.json');
     if (existsSync(packageJsonPath)) {
       try {

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;

package/src/theme/__tests__/generator.test.ts

@@ -0,0 +1,412 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  generateScssTokens,
+  generateCssTokens,
+  generateTokenFiles,
+} from "../generator.js";
+import type { ThemeConfig } from "../types.js";
+
+describe("Theme Generator", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(
+      tmpdir(),
+      `theme-generator-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe("SCSS generation", () => {
+    it("should generate valid SCSS with custom accent color", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#ff6600",
+        },
+      };
+
+      const scss = generateScssTokens(theme);
+
+      expect(scss).toContain("$fui-color-accent: #ff6600 !default;");
+    });
+
+    it("should include !default flag for all variables", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+          danger: "#ef4444",
+        },
+        radius: {
+          sm: "4px",
+        },
+      };
+
+      const scss = generateScssTokens(theme);
+
+      // All variable definitions should have !default
+      const lines = scss.split("\n").filter((l) => l.includes("$fui-"));
+      for (const line of lines) {
+        expect(line).toContain("!default;");
+      }
+    });
+
+    it("should generate dark mode variables", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        dark: {
+          surfaces: {
+            bgPrimary: "#0f172a",
+          },
+          text: {
+            primary: "#f8fafc",
+          },
+        },
+      };
+
+      const scss = generateScssTokens(theme);
+
+      expect(scss).toContain("$fui-dark-bg-primary: #0f172a !default;");
+      expect(scss).toContain("$fui-dark-text-primary: #f8fafc !default;");
+    });
+
+    it("should include header comment with theme name", () => {
+      const theme: ThemeConfig = {
+        name: "My Custom Theme",
+      };
+
+      const scss = generateScssTokens(theme);
+
+      expect(scss).toContain("// Theme: My Custom Theme");
+      expect(scss).toContain("// Auto-generated by @fragments-sdk/cli");
+    });
+
+    it("should generate all token categories", () => {
+      const theme: ThemeConfig = {
+        name: "Complete Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+        surfaces: {
+          bgPrimary: "#ffffff",
+        },
+        text: {
+          primary: "#0f172a",
+        },
+        borders: {
+          default: "#e2e8f0",
+        },
+        typography: {
+          fontSans: "system-ui, sans-serif",
+          fontWeightNormal: 400,
+        },
+        radius: {
+          sm: "4px",
+        },
+        shadows: {
+          sm: "0 1px 2px rgba(0,0,0,0.05)",
+        },
+      };
+
+      const scss = generateScssTokens(theme);
+
+      // Check for section comments
+      expect(scss).toContain("// Colors");
+      expect(scss).toContain("// Surfaces");
+      expect(scss).toContain("// Text");
+      expect(scss).toContain("// Borders");
+      expect(scss).toContain("// Typography");
+      expect(scss).toContain("// Border Radius");
+      expect(scss).toContain("// Shadows");
+    });
+
+    it("should only include overridden tokens", () => {
+      const theme: ThemeConfig = {
+        name: "Minimal Theme",
+        colors: {
+          accent: "#ff0000",
+        },
+      };
+
+      const scss = generateScssTokens(theme);
+
+      // Should include accent
+      expect(scss).toContain("$fui-color-accent: #ff0000");
+
+      // Should NOT include non-overridden tokens
+      expect(scss).not.toContain("$fui-color-danger:");
+      expect(scss).not.toContain("$fui-bg-primary:");
+    });
+  });
+
+  describe("CSS generation", () => {
+    it("should generate CSS custom properties", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#ff6600",
+        },
+      };
+
+      const css = generateCssTokens(theme);
+
+      expect(css).toContain("--fui-color-accent: #ff6600;");
+    });
+
+    it("should wrap in :root selector", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const css = generateCssTokens(theme);
+
+      expect(css).toContain(":root {");
+      expect(css).toContain("}");
+    });
+
+    it("should generate dark mode with .dark and [data-theme] selectors", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        dark: {
+          surfaces: {
+            bgPrimary: "#0f172a",
+          },
+        },
+      };
+
+      const css = generateCssTokens(theme);
+
+      expect(css).toContain(':root.dark,\n:root[data-theme="dark"] {');
+      expect(css).toContain("--fui-bg-primary: #0f172a;");
+    });
+
+    it("should include header comment with theme name", () => {
+      const theme: ThemeConfig = {
+        name: "My CSS Theme",
+      };
+
+      const css = generateCssTokens(theme);
+
+      expect(css).toContain("/* Theme: My CSS Theme */");
+      expect(css).toContain("/* Auto-generated by @fragments-sdk/cli */");
+    });
+  });
+
+  describe("file generation", () => {
+    it("should create SCSS file at specified path", async () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const result = await generateTokenFiles(theme, {
+        format: "scss",
+        outputDir: testDir,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.scssPath).toBeDefined();
+
+      // Verify file exists and contains content
+      const content = await readFile(result.scssPath!, "utf-8");
+      expect(content).toContain("$fui-color-accent: #6366f1");
+    });
+
+    it("should create CSS file at specified path", async () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const result = await generateTokenFiles(theme, {
+        format: "css",
+        outputDir: testDir,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.cssPath).toBeDefined();
+
+      // Verify file exists and contains content
+      const content = await readFile(result.cssPath!, "utf-8");
+      expect(content).toContain("--fui-color-accent: #6366f1");
+    });
+
+    it('should create both when format is "both"', async () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const result = await generateTokenFiles(theme, {
+        format: "both",
+        outputDir: testDir,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.scssPath).toBeDefined();
+      expect(result.cssPath).toBeDefined();
+
+      // Verify both files exist
+      await expect(access(result.scssPath!)).resolves.toBeUndefined();
+      await expect(access(result.cssPath!)).resolves.toBeUndefined();
+    });
+
+    it("should use custom file prefix", async () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      const result = await generateTokenFiles(theme, {
+        format: "scss",
+        outputDir: testDir,
+        filePrefix: "_custom-tokens",
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.scssPath).toContain("_custom-tokens.scss");
+    });
+
+    it("should create output directory if needed", async () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      const nestedDir = join(testDir, "nested", "path");
+
+      const result = await generateTokenFiles(theme, {
+        format: "scss",
+        outputDir: nestedDir,
+      });
+
+      expect(result.success).toBe(true);
+      await expect(access(nestedDir)).resolves.toBeUndefined();
+    });
+
+    it("should use default file prefix when not specified", async () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      const result = await generateTokenFiles(theme, {
+        format: "scss",
+        outputDir: testDir,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.scssPath).toContain("_theme-tokens.scss");
+    });
+  });
+
+  describe("token mapping", () => {
+    it("should map colors.accent to $fui-color-accent", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        colors: { accent: "#123456" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-color-accent: #123456");
+    });
+
+    it("should map surfaces.bgPrimary to $fui-bg-primary", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        surfaces: { bgPrimary: "#ffffff" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-bg-primary: #ffffff");
+    });
+
+    it("should map text.primary to $fui-text-primary", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        text: { primary: "#000000" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-text-primary: #000000");
+    });
+
+    it("should map borders.default to $fui-border", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        borders: { default: "#cccccc" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-border: #cccccc");
+    });
+
+    it("should map typography.fontSans to $fui-font-sans", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        typography: { fontSans: "Arial, sans-serif" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-font-sans: Arial, sans-serif");
+    });
+
+    it("should map radius.sm to $fui-radius-sm", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        radius: { sm: "2px" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-radius-sm: 2px");
+    });
+
+    it("should map shadows.md to $fui-shadow-md", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        shadows: { md: "0 4px 8px rgba(0,0,0,0.1)" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-shadow-md: 0 4px 8px rgba(0,0,0,0.1)");
+    });
+
+    it("should map dark.surfaces.bgPrimary to $fui-dark-bg-primary", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        dark: { surfaces: { bgPrimary: "#1a1a1a" } },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-dark-bg-primary: #1a1a1a");
+    });
+
+    it("should map dark.dangerBg to $fui-dark-color-danger-bg", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        dark: { dangerBg: "rgba(239, 68, 68, 0.15)" },
+      };
+
+      const scss = generateScssTokens(theme);
+      expect(scss).toContain("$fui-dark-color-danger-bg: rgba(239, 68, 68, 0.15)");
+    });
+  });
+});