@fragments-sdk/cli 0.2.2

package/src/service/utils.ts

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { BRAND } from "../core/index.js";
+
+/**
+ * Base error class for all service errors.
+ * Includes error code and optional suggestion for resolution.
+ */
+export class ServiceError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly suggestion?: string
+  ) {
+    super(message);
+    this.name = `${BRAND.name}Error`;
+  }
+
+  /**
+   * Format error for CLI output
+   */
+  toCliString(): string {
+    let str = `Error: ${this.message}`;
+    if (this.suggestion) {
+      str += `\n  Suggestion: ${this.suggestion}`;
+    }
+    return str;
+  }
+}
+
+/**
+ * Compute SHA-256 hash of a buffer
+ */
+export function computeHash(data: Buffer): string {
+  return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+
+/**
+ * Simple timer utility for measuring operations
+ */
+export class Timer {
+  private startTime: number;
+
+  constructor() {
+    this.startTime = performance.now();
+  }
+
+  /**
+   * Get elapsed time in milliseconds
+   */
+  elapsed(): number {
+    return Math.round(performance.now() - this.startTime);
+  }
+
+  /**
+   * Reset timer and return elapsed time
+   */
+  reset(): number {
+    const elapsed = this.elapsed();
+    this.startTime = performance.now();
+    return elapsed;
+  }
+}
+
+/**
+ * Create a deferred promise with external resolve/reject
+ */
+export function createDeferred<T>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: Error) => void;
+} {
+  let resolve!: (value: T) => void;
+  let reject!: (error: Error) => void;
+
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return { promise, resolve, reject };
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Convert buffer to base64 data URL
+ */
+export function bufferToBase64Url(
+  buffer: Buffer,
+  mimeType = "image/png"
+): string {
+  return `data:${mimeType};base64,${buffer.toString("base64")}`;
+}
+
+/**
+ * Convert base64 data URL to buffer
+ */
+export function base64UrlToBuffer(dataUrl: string): Buffer {
+  const base64 = dataUrl.replace(/^data:[^;]+;base64,/, "");
+  return Buffer.from(base64, "base64");
+}
+
+/**
+ * Sanitize a string for use as a filename
+ */
+export function sanitizeFilename(name: string): string {
+  return name
+    .replace(/[/\\?%*:|"<>]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Build path for screenshot file
+ */
+export function buildScreenshotPath(
+  component: string,
+  variant: string,
+  theme: string
+): string {
+  const safeComponent = sanitizeFilename(component);
+  const safeVariant = sanitizeFilename(variant);
+  return `${theme}/${safeComponent}/${safeVariant}.png`;
+}
+
+/**
+ * Format milliseconds for display
+ */
+export function formatMs(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  } = {}
+): Promise<T> {
+  const { maxAttempts = 3, initialDelayMs = 100, maxDelayMs = 1000 } = options;
+
+  let lastError: Error | undefined;
+  let delay = initialDelayMs;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt < maxAttempts) {
+        await sleep(delay);
+        delay = Math.min(delay * 2, maxDelayMs);
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/setup.ts

@@ -0,0 +1,241 @@
+import pc from 'picocolors';
+import { BRAND } from './core/index.js';
+import { loadConfig, discoverSegmentFiles } from './core/node.js';
+import { buildSegments } from './build.js';
+import {
+  detectStorybookConfig,
+  discoverStoryFiles as discoverStorybookFiles,
+  parseStoryFile,
+  convertToSegment,
+} from './migrate/index.js';
+
+export interface SetupOptions {
+  skipStorybook?: boolean;
+  skipFigma?: boolean;
+  skipBuild?: boolean;
+  silent?: boolean;
+  configPath?: string;
+}
+
+export interface SetupResult {
+  segmentFilesCreated: number;
+  segmentsBuilt: number;
+  figmaLinked: number;
+  errors: string[];
+}
+
+interface SegmentInfo {
+  name: string;
+  filePath: string;
+  hasFigma: boolean;
+}
+
+/**
+ * Check if segments.json exists and is newer than all segment files.
+ */
+async function isSegmentsJsonStale(configDir: string, outFile: string): Promise<{ stale: boolean; missing: boolean }> {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const fg = await import('fast-glob');
+
+  const segmentsJsonPath = path.join(configDir, outFile);
+
+  try {
+    const segmentsJsonStat = await fs.stat(segmentsJsonPath);
+
+    // Find all segment files
+    const segmentFiles = await fg.default(`**/*${BRAND.fileExtension}`, {
+      cwd: configDir,
+      ignore: ['**/node_modules/**'],
+      absolute: true,
+    });
+
+    // Check if any segment file is newer than segments.json
+    for (const file of segmentFiles) {
+      const stat = await fs.stat(file);
+      if (stat.mtimeMs > segmentsJsonStat.mtimeMs) {
+        return { stale: true, missing: false };
+      }
+    }
+
+    return { stale: false, missing: false };
+  } catch {
+    // segments.json doesn't exist
+    return { stale: false, missing: true };
+  }
+}
+
+/**
+ * Load segment files and check which ones have Figma links.
+ */
+async function loadSegmentInfo(segmentFiles: Array<{ absolutePath: string; relativePath: string }>): Promise<SegmentInfo[]> {
+  const fs = await import('node:fs/promises');
+  const segments: SegmentInfo[] = [];
+
+  for (const file of segmentFiles) {
+    try {
+      const content = await fs.readFile(file.absolutePath, 'utf-8');
+      const nameMatch = content.match(/name:\s*['"]([^'"]+)['"]/);
+      const hasFigma = /meta:\s*\{[^}]*figma:\s*['"]https?:/.test(content);
+
+      if (nameMatch) {
+        segments.push({
+          name: nameMatch[1],
+          filePath: file.absolutePath,
+          hasFigma,
+        });
+      }
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Run auto-setup for segments dev server.
+ *
+ * This function:
+ * 1. Checks for segment files, imports from Storybook if none found
+ * 2. Builds segments.json if missing or stale
+ * 3. Links Figma if configured but no segments are linked
+ */
+export async function runSetup(options: SetupOptions = {}): Promise<SetupResult> {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+
+  const result: SetupResult = {
+    segmentFilesCreated: 0,
+    segmentsBuilt: 0,
+    figmaLinked: 0,
+    errors: [],
+  };
+
+  const log = (msg: string) => {
+    if (!options.silent) console.log(msg);
+  };
+
+  try {
+    // Load config
+    const { config, configDir } = await loadConfig(options.configPath);
+
+    // Step 1: Check for segment files
+    log(pc.dim('Checking for fragment files...'));
+    let segmentFiles = await discoverSegmentFiles(config, configDir);
+
+    if (segmentFiles.length === 0 && !options.skipStorybook) {
+      // No fragment files - check for Storybook
+      log(pc.yellow('\n   No fragment files found'));
+
+      const sbConfig = await detectStorybookConfig(configDir);
+      if (sbConfig) {
+        log(pc.dim(`   Found Storybook at ${sbConfig.configPath}`));
+        log(pc.dim('   Converting stories to fragments...\n'));
+
+        // Discover and convert stories
+        const storyFiles = await discoverStorybookFiles(configDir, sbConfig.storyPatterns);
+
+        if (storyFiles.length > 0) {
+          let converted = 0;
+          for (const storyFile of storyFiles) {
+            try {
+              const parsed = await parseStoryFile(storyFile);
+              const segmentResult = convertToSegment(parsed);
+
+              // Create directory and write file
+              await fs.mkdir(path.dirname(segmentResult.outputFile), { recursive: true });
+              await fs.writeFile(segmentResult.outputFile, segmentResult.code);
+              converted++;
+            } catch {
+              // Skip files that can't be converted
+            }
+          }
+
+          result.segmentFilesCreated = converted;
+          log(pc.green(`   Generated ${converted} fragment file(s)`));
+
+          // Refresh segment files list
+          segmentFiles = await discoverSegmentFiles(config, configDir);
+        }
+      } else {
+        log(pc.dim('   No Storybook config found'));
+        log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} add <ComponentName>`)} to create your first fragment`));
+      }
+    } else if (segmentFiles.length > 0) {
+      log(pc.green(`   Found ${segmentFiles.length} fragment file(s)`));
+    }
+
+    // Step 2: Build fragments.json if needed
+    if (segmentFiles.length > 0 && !options.skipBuild) {
+      const outFile = config.outFile || BRAND.outFile;
+      const { stale, missing } = await isSegmentsJsonStale(configDir, outFile);
+
+      if (missing || stale) {
+        const reason = missing ? 'Building' : 'Rebuilding';
+        log(pc.dim(`\n${reason} ${BRAND.outFile}...`));
+
+        try {
+          const buildResult = await buildSegments(config, configDir);
+          result.segmentsBuilt = buildResult.segmentCount;
+
+          if (buildResult.errors.length > 0) {
+            for (const err of buildResult.errors) {
+              result.errors.push(`${err.file}: ${err.error}`);
+            }
+          }
+
+          log(pc.green(`   Built ${buildResult.segmentCount} fragment(s)`));
+        } catch (error) {
+          result.errors.push(`Build failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+      } else {
+        log(pc.dim(`\n   ${BRAND.outFile} is up to date`));
+      }
+    }
+
+    // Step 3: Link Figma if configured
+    if (!options.skipFigma && config.figmaFile && process.env.FIGMA_ACCESS_TOKEN) {
+      const segments = await loadSegmentInfo(segmentFiles);
+      const linkedCount = segments.filter((s) => s.hasFigma).length;
+
+      if (linkedCount === 0 && segments.length > 0) {
+        log(pc.dim('\n   Figma configured but no fragments linked'));
+        log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} link figma --auto`)} to auto-link components`));
+        // Note: We don't auto-link here because it requires API calls and user may want control
+        // But we inform them about the option
+      } else if (linkedCount > 0) {
+        log(pc.dim(`\n   ${linkedCount}/${segments.length} fragment(s) linked to Figma`));
+      }
+    } else if (!options.skipFigma && config.figmaFile && !process.env.FIGMA_ACCESS_TOKEN) {
+      log(pc.dim('\n   Figma file configured but FIGMA_ACCESS_TOKEN not set'));
+    }
+
+  } catch (error) {
+    result.errors.push(error instanceof Error ? error.message : 'Unknown error');
+  }
+
+  return result;
+}
+
+/**
+ * Print setup summary with user-friendly output.
+ */
+export function printSetupSummary(result: SetupResult): void {
+  console.log();
+
+  if (result.segmentFilesCreated > 0) {
+    console.log(pc.green(`   Imported ${result.segmentFilesCreated} segments from Storybook`));
+  }
+
+  if (result.segmentsBuilt > 0) {
+    console.log(pc.green(`   Built ${result.segmentsBuilt} segments`));
+  }
+
+  if (result.errors.length > 0) {
+    console.log(pc.yellow('\n   Warnings:'));
+    for (const error of result.errors) {
+      console.log(pc.dim(`   ${error}`));
+    }
+  }
+}

package/src/shared/command-wrapper.ts

@@ -0,0 +1,81 @@
+/**
+ * Command Wrapper
+ *
+ * Provides error handling and common patterns for CLI commands.
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { DevServerConnectionError, DevServerError } from './dev-server-client.js';
+
+/**
+ * Options for command execution
+ */
+export interface CommandOptions {
+  /** CI mode - output JSON and exit non-zero on failure */
+  ci?: boolean;
+  /** Port for dev server */
+  port?: number | string;
+}
+
+/**
+ * Format and print a dev server connection error with helpful suggestions
+ */
+export function formatConnectionError(error: DevServerConnectionError, port: number | string): string {
+  return (
+    `Cannot connect to dev server at ${error.serverUrl}\n\n` +
+    `The command requires the dev server to be running.\n` +
+    `Start it with: ${pc.cyan(`${BRAND.cliCommand} dev`)}\n\n` +
+    `Alternatively, run with a different port:\n` +
+    `  ${pc.cyan(`${BRAND.cliCommand} <command> --port ${port}`)}`
+  );
+}
+
+/**
+ * Handle errors in a command, formatting appropriately for CI vs interactive mode
+ */
+export function handleCommandError(
+  error: unknown,
+  options: CommandOptions = {}
+): never {
+  const { ci = false, port = 6006 } = options;
+
+  if (error instanceof DevServerConnectionError) {
+    if (ci) {
+      console.log(JSON.stringify({ error: `Cannot connect to dev server at ${error.serverUrl}` }));
+    } else {
+      console.error(pc.red('Error:'), formatConnectionError(error, port));
+    }
+  } else if (error instanceof DevServerError) {
+    if (ci) {
+      console.log(JSON.stringify({ error: error.message }));
+    } else {
+      console.error(pc.red('Error:'), error.message);
+    }
+  } else {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    if (ci) {
+      console.log(JSON.stringify({ error: message }));
+    } else {
+      console.error(pc.red('Error:'), message);
+    }
+  }
+
+  process.exit(1);
+}
+
+/**
+ * Wrap a command function with standard error handling
+ */
+export function withErrorHandling<T extends unknown[], R>(
+  fn: (...args: T) => Promise<R>,
+  options: CommandOptions = {}
+): (...args: T) => Promise<R> {
+  return async (...args: T): Promise<R> => {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      handleCommandError(error, options);
+    }
+  };
+}

package/src/shared/dev-server-client.ts

@@ -0,0 +1,199 @@
+/**
+ * Dev Server Client
+ *
+ * HTTP client for communicating with the fragments dev server.
+ * Provides typed methods for all server endpoints.
+ */
+
+import type {
+  ComplianceResult,
+  SegmentInfo,
+  ContextData,
+  ViolationItem,
+  A11yResult,
+} from './types.js';
+
+export interface DevServerClientOptions {
+  /** Base URL of the dev server */
+  baseUrl: string;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * Request body for compliance endpoint
+ */
+export interface ComplianceRequest {
+  /** Component name */
+  component: string;
+  /** Variant name (optional) */
+  variant?: string;
+  /** Theme to use (default: "default") */
+  theme?: string;
+}
+
+/**
+ * Client for interacting with the fragments dev server
+ */
+export class DevServerClient {
+  private baseUrl: string;
+  private timeout: number;
+
+  constructor(options: DevServerClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, ''); // Remove trailing slash
+    this.timeout = options.timeout ?? 30000;
+  }
+
+  /**
+   * Check if the dev server is reachable
+   */
+  async ping(): Promise<boolean> {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+      const response = await fetch(`${this.baseUrl}/segments/context?format=json`, {
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get all segments from the context endpoint
+   */
+  async getSegments(): Promise<SegmentInfo[]> {
+    const response = await this.fetch('/segments/context?format=json');
+    const data = await response.json() as {
+      components: Record<string, { category?: string; description?: string; status?: string; figma?: string }>;
+    };
+
+    // Transform object to array of SegmentInfo
+    const components = data.components || {};
+    return Object.entries(components).map(([name, info]) => ({
+      name,
+      category: info.category || 'components',
+      description: info.description,
+      status: info.status,
+      figma: info.figma,
+    }));
+  }
+
+  /**
+   * Get compliance data for a component
+   */
+  async getCompliance(request: ComplianceRequest): Promise<ComplianceResult> {
+    const response = await this.fetch('/segments/compliance', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    });
+
+    const data = await response.json() as ComplianceResult;
+    return data;
+  }
+
+  /**
+   * Get accessibility results for a component
+   */
+  async getA11y(component: string, variant?: string): Promise<A11yResult> {
+    const response = await this.fetch('/fragments/a11y', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ component, variant }),
+    });
+
+    const data = await response.json() as A11yResult;
+    return data;
+  }
+
+  /**
+   * Internal fetch wrapper with error handling
+   */
+  private async fetch(path: string, options?: RequestInit): Promise<Response> {
+    const url = `${this.baseUrl}${path}`;
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorBody = await response.text().catch(() => '');
+        throw new DevServerError(
+          `Server returned ${response.status}: ${response.statusText}`,
+          response.status,
+          errorBody
+        );
+      }
+
+      return response;
+    } catch (error) {
+      if (error instanceof DevServerError) {
+        throw error;
+      }
+
+      // Handle connection errors
+      const errMsg = error instanceof Error && error.cause
+        ? String((error.cause as { code?: string }).code || error.message)
+        : error instanceof Error
+          ? error.message
+          : 'Unknown error';
+
+      if (errMsg.includes('ECONNREFUSED') || errMsg.includes('fetch failed')) {
+        throw new DevServerConnectionError(
+          `Cannot connect to dev server at ${this.baseUrl}`,
+          this.baseUrl
+        );
+      }
+
+      throw error;
+    }
+  }
+}
+
+/**
+ * Error thrown when the dev server returns an error response
+ */
+export class DevServerError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly body?: string
+  ) {
+    super(message);
+    this.name = 'DevServerError';
+  }
+}
+
+/**
+ * Error thrown when we can't connect to the dev server
+ */
+export class DevServerConnectionError extends Error {
+  constructor(
+    message: string,
+    public readonly serverUrl: string
+  ) {
+    super(message);
+    this.name = 'DevServerConnectionError';
+  }
+}
+
+/**
+ * Create a dev server client with default options
+ */
+export function createDevServerClient(port: number | string = 6006): DevServerClient {
+  return new DevServerClient({
+    baseUrl: `http://localhost:${port}`,
+  });
+}

package/src/shared/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared utilities for CLI commands
+ */
+
+export * from './types.js';
+export * from './dev-server-client.js';
+export * from './command-wrapper.js';
+export * from './segment-loader.js';