@fragments-sdk/cli 0.2.2

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@fragments-sdk/cli",
+  "version": "0.2.2",
+  "description": "CLI, MCP server, and dev tools for Fragments design system",
+  "type": "module",
+  "bin": {
+    "fragments": "./dist/bin.js",
+    "fragments-mcp": "./dist/mcp-bin.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@babel/generator": "^7.23.6",
+    "@babel/parser": "^7.23.6",
+    "@babel/traverse": "^7.23.6",
+    "@babel/types": "^7.23.6",
+    "@figma/rest-api-spec": "^0.35.0",
+    "@hookform/resolvers": "^5.2.2",
+    "@inquirer/prompts": "^7.2.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@monaco-editor/react": "^4.7.0",
+    "@storybook/csf": "^0.1.12",
+    "@tanstack/react-virtual": "^3.13.18",
+    "@vitejs/plugin-react": "^4.3.0",
+    "autoprefixer": "^10.4.20",
+    "axe-core": "^4.11.1",
+    "chokidar": "^4.0.3",
+    "clsx": "^2.1.1",
+    "commander": "^12.1.0",
+    "esbuild": "^0.24.0",
+    "fast-glob": "^3.3.3",
+    "html2canvas": "^1.4.1",
+    "jiti": "^2.6.1",
+    "monaco-editor": "^0.55.1",
+    "openai": "^6.16.0",
+    "picocolors": "^1.1.1",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0",
+    "postcss": "^8.4.49",
+    "react-colorful": "^5.6.1",
+    "react-hook-form": "^7.71.0",
+    "react-live": "^4.1.6",
+    "shiki": "^3.21.0",
+    "tailwindcss": "^3.4.17",
+    "vite": "^6.0.0",
+    "vite-plugin-svgr": "^4.5.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/babel__generator": "^7.6.8",
+    "@types/babel__traverse": "^7.20.5",
+    "@types/node": "^22.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "sass": "^1.83.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "peerDependencies": {
+    "playwright": "^1.40.0",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/ai.ts

@@ -0,0 +1,266 @@
+import type { CompiledSegment, CompiledSegmentsFile } from "./core/index.js";
+import { generateContext } from "./core/index.js";
+
+export interface AiSuggestOptions {
+  /** The user's prompt describing what they want to build */
+  prompt: string;
+  /** Optional additional context */
+  context?: string;
+  /** Compiled segments to use */
+  segments: CompiledSegment[];
+  /** Whether to stream output */
+  stream?: boolean;
+}
+
+export interface AiSuggestResult {
+  success: boolean;
+  response?: string;
+  error?: string;
+  tokensUsed?: number;
+}
+
+/**
+ * Call AI API to get component suggestions based on design system context.
+ * Supports both Anthropic and OpenAI APIs via environment variables.
+ */
+export async function aiSuggest(options: AiSuggestOptions): Promise<AiSuggestResult> {
+  const { prompt, context, segments, stream = true } = options;
+
+  // Check for API keys
+  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  const openaiKey = process.env.OPENAI_API_KEY;
+
+  if (!anthropicKey && !openaiKey) {
+    return {
+      success: false,
+      error: "No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable.",
+    };
+  }
+
+  // Generate design system context
+  const { content: systemContext } = generateContext(segments, {
+    format: "markdown",
+    compact: false,
+    include: {
+      props: true,
+      variants: true,
+      usage: true,
+      code: true,
+    },
+  });
+
+  // Build the system prompt
+  const systemPrompt = `You are a UI developer assistant helping to build interfaces using a specific design system.
+
+You have access to the following design system components:
+
+${systemContext}
+
+When suggesting components:
+1. ONLY use components from this design system - never suggest generic HTML or components not listed above
+2. Explain WHY each component is appropriate for the use case
+3. Show complete, ready-to-use code examples with correct props
+4. Follow the "when to use" and "when NOT to use" guidelines for each component
+5. Consider accessibility and best practices
+6. If multiple approaches are valid, recommend the simplest one first
+
+Format your response as:
+1. A brief explanation of the approach
+2. Code example(s) with comments
+3. Any important notes about props or customization`;
+
+  // Build the user prompt
+  const userPrompt = context
+    ? `${prompt}\n\nAdditional context: ${context}`
+    : prompt;
+
+  // Prefer Anthropic, fallback to OpenAI
+  if (anthropicKey) {
+    return callAnthropic(anthropicKey, systemPrompt, userPrompt, stream);
+  } else {
+    return callOpenAI(openaiKey!, systemPrompt, userPrompt, stream);
+  }
+}
+
+/**
+ * Call Anthropic's Claude API
+ */
+async function callAnthropic(
+  apiKey: string,
+  systemPrompt: string,
+  userPrompt: string,
+  stream: boolean
+): Promise<AiSuggestResult> {
+  try {
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: "claude-sonnet-4-20250514",
+        max_tokens: 4096,
+        system: systemPrompt,
+        messages: [
+          {
+            role: "user",
+            content: userPrompt,
+          },
+        ],
+        stream: stream,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      return {
+        success: false,
+        error: `Anthropic API error: ${response.status} - ${error}`,
+      };
+    }
+
+    if (stream && response.body) {
+      // Stream the response
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let fullResponse = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        const lines = chunk.split("\n");
+
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data = line.slice(6);
+            if (data === "[DONE]") continue;
+
+            try {
+              const parsed = JSON.parse(data);
+              if (parsed.type === "content_block_delta" && parsed.delta?.text) {
+                process.stdout.write(parsed.delta.text);
+                fullResponse += parsed.delta.text;
+              }
+            } catch {
+              // Skip malformed JSON
+            }
+          }
+        }
+      }
+
+      console.log(); // Final newline
+      return {
+        success: true,
+        response: fullResponse,
+      };
+    } else {
+      const data = await response.json();
+      const text = data.content?.[0]?.text ?? "";
+
+      return {
+        success: true,
+        response: text,
+        tokensUsed: data.usage?.input_tokens + data.usage?.output_tokens,
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to call Anthropic API: ${error instanceof Error ? error.message : error}`,
+    };
+  }
+}
+
+/**
+ * Call OpenAI's API
+ */
+async function callOpenAI(
+  apiKey: string,
+  systemPrompt: string,
+  userPrompt: string,
+  stream: boolean
+): Promise<AiSuggestResult> {
+  try {
+    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model: "gpt-4o",
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt },
+        ],
+        max_tokens: 4096,
+        stream: stream,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      return {
+        success: false,
+        error: `OpenAI API error: ${response.status} - ${error}`,
+      };
+    }
+
+    if (stream && response.body) {
+      // Stream the response
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let fullResponse = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        const lines = chunk.split("\n");
+
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data = line.slice(6);
+            if (data === "[DONE]") continue;
+
+            try {
+              const parsed = JSON.parse(data);
+              const content = parsed.choices?.[0]?.delta?.content;
+              if (content) {
+                process.stdout.write(content);
+                fullResponse += content;
+              }
+            } catch {
+              // Skip malformed JSON
+            }
+          }
+        }
+      }
+
+      console.log(); // Final newline
+      return {
+        success: true,
+        response: fullResponse,
+      };
+    } else {
+      const data = await response.json();
+      const text = data.choices?.[0]?.message?.content ?? "";
+
+      return {
+        success: true,
+        response: text,
+        tokensUsed: data.usage?.total_tokens,
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to call OpenAI API: ${error instanceof Error ? error.message : error}`,
+    };
+  }
+}

package/src/analyze.ts

@@ -0,0 +1,265 @@
+/**
+ * CLI command: segments analyze
+ *
+ * Analyzes the design system and generates an HTML report with:
+ * - Component inventory
+ * - Documentation coverage
+ * - Quality insights
+ * - Actionable recommendations
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import pc from "picocolors";
+import type { SegmentsConfig, CompiledSegmentsFile } from "./core/index.js";
+import { BRAND, DEFAULTS } from "./core/index.js";
+import {
+  analyzeDesignSystem,
+  generateHtmlReport,
+  getGrade,
+  getScoreColor,
+  type DesignSystemAnalytics,
+} from "./service/index.js";
+
+export interface AnalyzeOptions {
+  /** Output format */
+  format?: "html" | "json" | "console";
+  /** Output file path (default: segments-report.html) */
+  output?: string;
+  /** Open report in browser after generation */
+  open?: boolean;
+  /** CI mode - exit with appropriate code */
+  ci?: boolean;
+  /** Minimum score to pass in CI mode */
+  minScore?: number;
+}
+
+export interface AnalyzeResult {
+  success: boolean;
+  analytics: DesignSystemAnalytics;
+  outputPath?: string;
+}
+
+/**
+ * Run the analyze command
+ */
+export async function runAnalyzeCommand(
+  config: SegmentsConfig,
+  configDir: string,
+  options: AnalyzeOptions = {}
+): Promise<AnalyzeResult> {
+  const format = options.format ?? "html";
+  const minScore = options.minScore ?? 0;
+
+  console.log(pc.cyan(`\n${BRAND.name} Analyzer\n`));
+
+  // Load compiled segments
+  const segmentsPath = join(configDir, config.outFile ?? "segments.json");
+
+  if (!existsSync(segmentsPath)) {
+    console.log(pc.red(`✗ No segments.json found. Run \`${BRAND.cliCommand} build\` first.\n`));
+    return {
+      success: false,
+      analytics: createEmptyAnalytics(),
+    };
+  }
+
+  console.log(pc.dim("Analyzing design system...\n"));
+
+  const content = await readFile(segmentsPath, "utf-8");
+  const data: CompiledSegmentsFile = JSON.parse(content);
+
+  // Run analysis
+  const analytics = analyzeDesignSystem(data);
+
+  // Print summary to console
+  printConsoleSummary(analytics);
+
+  // Generate output based on format
+  let outputPath: string | undefined;
+
+  if (format === "html" || format === "json") {
+    outputPath = options.output ?? getDefaultOutputPath(format, configDir);
+
+    // Ensure output directory exists
+    await mkdir(dirname(outputPath), { recursive: true });
+
+    if (format === "html") {
+      const html = generateHtmlReport(analytics);
+      await writeFile(outputPath, html);
+      console.log(pc.green(`✓ Report generated: ${outputPath}\n`));
+    } else {
+      await writeFile(outputPath, JSON.stringify(analytics, null, 2));
+      console.log(pc.green(`✓ JSON report generated: ${outputPath}\n`));
+    }
+
+    // Open in browser if requested
+    if (options.open && format === "html") {
+      await openInBrowser(outputPath);
+    }
+  }
+
+  // CI mode - check score
+  const passedCi = analytics.summary.overallScore >= minScore;
+
+  if (options.ci) {
+    if (passedCi) {
+      console.log(
+        pc.green(`✓ Score ${analytics.summary.overallScore} meets minimum threshold ${minScore}\n`)
+      );
+    } else {
+      console.log(
+        pc.red(
+          `✗ Score ${analytics.summary.overallScore} below minimum threshold ${minScore}\n`
+        )
+      );
+    }
+  }
+
+  return {
+    success: !options.ci || passedCi,
+    analytics,
+    outputPath,
+  };
+}
+
+/**
+ * Print a summary to the console
+ */
+function printConsoleSummary(analytics: DesignSystemAnalytics): void {
+  const { summary, coverage, recommendations } = analytics;
+  const grade = getGrade(summary.overallScore);
+
+  // Score header
+  console.log(
+    pc.bold(
+      `Overall Score: ${colorizeScore(summary.overallScore)} (${grade})\n`
+    )
+  );
+
+  // Summary stats
+  console.log(pc.dim("Summary"));
+  console.log(`  Components:  ${pc.white(summary.totalComponents.toString())}`);
+  console.log(`  Variants:    ${pc.white(summary.totalVariants.toString())}`);
+  console.log(`  Props:       ${pc.white(summary.totalProps.toString())}`);
+  console.log(`  Categories:  ${pc.white(summary.categories.join(", "))}`);
+  console.log();
+
+  // Coverage
+  console.log(pc.dim("Coverage"));
+  console.log(`  Description:  ${formatCoverage(coverage.fields.description)}`);
+  console.log(`  Usage when:   ${formatCoverage(coverage.fields.usageWhen)}`);
+  console.log(`  Usage whenNot:${formatCoverage(coverage.fields.usageWhenNot)}`);
+  console.log(`  Guidelines:   ${formatCoverage(coverage.fields.guidelines)}`);
+  console.log(`  Relations:    ${formatCoverage(coverage.fields.relations)}`);
+  console.log();
+
+  // Top recommendations
+  if (recommendations.length > 0) {
+    console.log(pc.dim("Top Recommendations"));
+    for (const rec of recommendations.slice(0, 3)) {
+      const priority = rec.priority === "high"
+        ? pc.red(`[${rec.priority}]`)
+        : rec.priority === "medium"
+          ? pc.yellow(`[${rec.priority}]`)
+          : pc.dim(`[${rec.priority}]`);
+      console.log(`  ${priority} ${rec.title}`);
+    }
+    console.log();
+  }
+}
+
+/**
+ * Format coverage percentage with color
+ */
+function formatCoverage(field: { percentage: number; covered: number; total: number }): string {
+  const pct = colorizeScore(field.percentage);
+  return `${pct} (${field.covered}/${field.total})`;
+}
+
+/**
+ * Colorize a score
+ */
+function colorizeScore(score: number): string {
+  if (score >= 80) return pc.green(`${score}%`);
+  if (score >= 60) return pc.yellow(`${score}%`);
+  return pc.red(`${score}%`);
+}
+
+/**
+ * Get default output path
+ */
+function getDefaultOutputPath(format: "html" | "json", configDir: string): string {
+  const filename = format === "html" ? "segments-report.html" : "segments-report.json";
+  return join(configDir, filename);
+}
+
+/**
+ * Open file in default browser
+ */
+async function openInBrowser(path: string): Promise<void> {
+  const { platform } = await import("node:os");
+  const { exec } = await import("node:child_process");
+
+  const os = platform();
+  const cmd = os === "darwin"
+    ? `open "${path}"`
+    : os === "win32"
+      ? `start "" "${path}"`
+      : `xdg-open "${path}"`;
+
+  exec(cmd);
+}
+
+/**
+ * Create empty analytics for error cases
+ */
+function createEmptyAnalytics(): DesignSystemAnalytics {
+  return {
+    analyzedAt: new Date(),
+    summary: {
+      totalComponents: 0,
+      totalVariants: 0,
+      totalProps: 0,
+      categories: [],
+      overallScore: 0,
+    },
+    inventory: {
+      byCategory: {},
+      byStatus: {},
+      byVariantCount: [],
+      byPropCount: [],
+    },
+    coverage: {
+      overall: 0,
+      fields: {
+        description: { covered: 0, total: 0, percentage: 0 },
+        usageWhen: { covered: 0, total: 0, percentage: 0 },
+        usageWhenNot: { covered: 0, total: 0, percentage: 0 },
+        guidelines: { covered: 0, total: 0, percentage: 0 },
+        accessibility: { covered: 0, total: 0, percentage: 0 },
+        relations: { covered: 0, total: 0, percentage: 0 },
+        propDescriptions: { covered: 0, total: 0, percentage: 0 },
+        propConstraints: { covered: 0, total: 0, percentage: 0 },
+      },
+      incomplete: [],
+    },
+    quality: {
+      missingWhenNot: [],
+      isolated: [],
+      deprecated: [],
+      fewVariants: [],
+      undocumentedProps: [],
+      unconstrainedProps: [],
+    },
+    distribution: {
+      variantsPerComponent: [],
+      propsPerComponent: [],
+      componentsPerCategory: [],
+      statusDistribution: [],
+      tagFrequency: [],
+    },
+    recommendations: [],
+  };
+}