@fragments-sdk/cli 0.3.3 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/cli",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "CLI, MCP server, and dev tools for Fragments design system",
   "type": "module",
   "bin": {
@@ -100,6 +100,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "lint": "eslint src",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"

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,
   };
 }
@@ -401,6 +408,51 @@ function extractVariants(
   return variants;
 }
 
+/**
+ * Remove common leading whitespace from all lines (dedent).
+ * This handles template literals and JSX that have extra indentation from code formatting.
+ *
+ * Special handling: If the first line has no indentation (common after .trim()),
+ * we calculate minimum indent from subsequent lines only.
+ */
+function dedent(str: string): string {
+  const lines = str.split('\n');
+
+  if (lines.length <= 1) {
+    return str;
+  }
+
+  // Check if first line has no indentation
+  const firstLineIndent = lines[0].match(/^(\s*)/)?.[1].length ?? 0;
+  const startIndex = firstLineIndent === 0 ? 1 : 0;
+
+  // Find the minimum indentation (ignoring empty lines)
+  let minIndent = Infinity;
+  for (let i = startIndex; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+    const match = line.match(/^(\s*)/);
+    if (match) {
+      minIndent = Math.min(minIndent, match[1].length);
+    }
+  }
+
+  // If no indentation found, return as-is
+  if (minIndent === Infinity || minIndent === 0) {
+    return str;
+  }
+
+  // Remove the common indentation from all lines (except first if it had no indent)
+  return lines
+    .map((line, index) => {
+      if (index === 0 && firstLineIndent === 0) {
+        return line; // Keep first line as-is
+      }
+      return line.slice(minIndent);
+    })
+    .join('\n');
+}
+
 /**
  * Extract the code from a render function.
  */
@@ -421,6 +473,9 @@ function extractRenderCode(
       code = code.slice(1, -1).trim();
     }
 
+    // Dedent the code to remove common leading whitespace
+    code = dedent(code);
+
     return code;
   }
 
@@ -460,6 +515,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/storyAdapter.ts

@@ -9,7 +9,7 @@
  */
 
 import { createElement, type ComponentType, type ReactNode } from "react";
-import { toId, storyNameFromExport, isExportStory } from "@storybook/csf";
+import { toId, storyNameFromExport, isExportStory } from "./storybook-csf.js";
 import type {
   SegmentDefinition,
   SegmentMeta,

package/src/core/storybook-csf.ts

@@ -0,0 +1,11 @@
+import {
+  toId as storybookToId,
+  storyNameFromExport as storybookStoryNameFromExport,
+  isExportStory as storybookIsExportStory,
+} from "@storybook/csf";
+
+export const toId: typeof storybookToId = (...args) => storybookToId(...args);
+export const storyNameFromExport: typeof storybookStoryNameFromExport = (...args) =>
+  storybookStoryNameFromExport(...args);
+export const isExportStory: typeof storybookIsExportStory = (...args) =>
+  storybookIsExportStory(...args);

package/src/core/types.ts

@@ -5,7 +5,7 @@ import type { ComponentType, ReactNode, JSX } from "react";
  * This type is intentionally broad to support various React component patterns
  * including FC, forwardRef, memo, and class components across different React versions.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 export type SegmentComponent<TProps = any> =
   | ComponentType<TProps>
   | ((props: TProps) => ReactNode | JSX.Element | null);
@@ -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/mcp/server.ts

@@ -276,7 +276,7 @@ export function createMcpServer(config: McpServerConfig): Server {
   // Lazy-loaded resources
   let segmentsData: CompiledSegmentsFile | null = null;
   let packageName: string | null = null;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- lazy-loaded from service
+   
   let browserPool: any = null;
   let storageManager: any = null;
   let diffEngine: any = null;

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/enhance/doc-extractor.ts

@@ -139,7 +139,7 @@ function extractJSDoc(
 
   // Parse JSDoc content
   const lines = content.split("\n");
-  let currentDescription: string[] = [];
+  const currentDescription: string[] = [];
   let currentTag: string | null = null;
   let currentTagContent: string[] = [];
 
@@ -197,7 +197,7 @@ function processTag(
       if (propMatch) {
         const [, type, nameRaw, description] = propMatch;
         const isOptional = nameRaw.startsWith("[");
-        const name = nameRaw.replace(/[\[\]]/g, "");
+        const name = nameRaw.replaceAll("[", "").replaceAll("]", "");
         docs.props?.push({
           name,
           type,

package/src/service/enhance/props-extractor.ts

@@ -331,7 +331,7 @@ function parseJSDocContent(
   }
 ): void {
   const lines = content.split("\n");
-  let currentDescription: string[] = [];
+  const currentDescription: string[] = [];
   let currentTag: string | null = null;
   let currentTagContent: string[] = [];
 

package/src/service/enhance/storybook-parser.ts

@@ -484,7 +484,7 @@ function camelToTitle(str: string): string {
 function inferComponentFromPath(filePath: string): string {
   const fileName = basename(filePath);
   // Remove .stories.tsx etc
-  let name = fileName.replace(/\.stories\.(tsx?|jsx?|mdx?)$/, "");
+  const name = fileName.replace(/\.stories\.(tsx?|jsx?|mdx?)$/, "");
   // Handle patterns like Button.stories.tsx
   return name;
 }

package/src/service/figma.ts

@@ -313,7 +313,7 @@ export class FigmaClient {
    */
   parseUrl(url: string): FigmaUrlParts {
     // Match both /file/ and /design/ paths
-    const urlPattern = /figma\.com\/(?:file|design)\/([^\/]+)\/[^?]*\?.*node-id=([^&]+)/i;
+    const urlPattern = /figma\.com\/(?:file|design)\/([^/]+)\/[^?]*\?.*node-id=([^&]+)/i;
     const match = url.match(urlPattern);
 
     if (!match) {
@@ -410,7 +410,7 @@ export class FigmaClient {
    */
   parseFileUrl(url: string): { fileKey: string; nodeId?: string } {
     // Match both /file/ and /design/ paths
-    const urlPattern = /figma\.com\/(?:file|design)\/([^\/]+)/i;
+    const urlPattern = /figma\.com\/(?:file|design)\/([^/]+)/i;
     const match = url.match(urlPattern);
 
     if (!match) {

package/src/service/metrics-store.ts

@@ -200,12 +200,13 @@ export class MetricsStore {
       let key: string;
 
       switch (groupBy) {
-        case "week":
+        case "week": {
           // Get ISO week
           const weekStart = new Date(date);
           weekStart.setDate(date.getDate() - date.getDay());
           key = weekStart.toISOString().split("T")[0];
           break;
+        }
         case "month":
           key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
           break;

package/src/service/patch-generator.ts

@@ -189,13 +189,14 @@ function generateHunk(
 
   // The hunk format depends on the style type
   switch (styleType) {
-    case "inline":
+    case "inline": {
       // React inline style: { backgroundColor: '#0051c2' }
       const camelProp = toCamelCase(cssProperty);
       lines.push(`@@ -1,1 +1,1 @@ inline style`);
       lines.push(`-  ${camelProp}: '${currentValue}',`);
       lines.push(`+  ${camelProp}: 'var(${suggestedFix.tokenName})',`);
       break;
+    }
 
     case "styled-components":
     case "emotion":

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/test/reporters/junit.ts

@@ -176,11 +176,15 @@ function generateTestCaseXml(result: TestResult): string {
  * Escape special XML characters
  */
 function escapeXml(str: string): string {
-  return str
+  const cleaned = Array.from(str).filter((ch) => {
+    const code = ch.charCodeAt(0);
+    return code === 0x09 || code === 0x0A || code === 0x0D || code >= 0x20;
+  }).join('');
+
+  return cleaned
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;')
-    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, ''); // Remove invalid XML characters
+    .replace(/'/g, '&apos;');
 }

package/src/test/runner.ts

@@ -20,11 +20,11 @@ import type {
 import { groupTestsByComponent } from './discovery.js';
 
 // Dynamic playwright types (since it's optional)
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 type Browser = any;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 type BrowserContext = any;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 type Page = any;
 
 /**
@@ -59,7 +59,7 @@ export async function runTests(
   }
 
   // Import Playwright dynamically (optional dependency)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+   
   let playwright: any;
   try {
     playwright = await import('playwright');

package/src/test/watch.ts

@@ -34,7 +34,7 @@ export async function startWatchMode(
 
   let debounceTimer: NodeJS.Timeout | null = null;
   let isRunning = false;
-  let pendingFiles = new Set<string>();
+  const pendingFiles = new Set<string>();
 
   // Get files to watch
   const segmentFiles = await discoverSegmentFiles(config, configDir);
@@ -190,7 +190,7 @@ export async function startInteractiveWatchMode(
   runnerOptions: RunnerOptions,
   reporters: TestReporter[]
 ): Promise<void> {
-  let lastFailedTests: TestCase[] = [];
+  const lastFailedTests: TestCase[] = [];
 
   // Start basic watch mode
   await startWatchMode(config, configDir, runnerOptions, reporters, {