@fragments-sdk/cli 0.2.2

package/src/commands/link/storybook.ts

@@ -0,0 +1,267 @@
+/**
+ * fragments link storybook - Bootstrap segments from Storybook stories
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../../core/index.js';
+import {
+  detectStorybookConfig,
+  discoverStoryFiles as discoverStorybookFiles,
+  parseStoryFile,
+  convertToSegment,
+} from '../../migrate/index.js';
+
+/**
+ * Options for link storybook command
+ */
+export interface LinkStorybookOptions {
+  /** Path to .storybook/main.* config */
+  config?: string;
+  /** Output directory for segment files */
+  out?: string;
+  /** Skip confirmation prompts */
+  yes?: boolean;
+  /** Preview what would be generated without writing files */
+  dryRun?: boolean;
+  /** Only process stories matching glob */
+  include?: string;
+  /** Skip stories matching glob */
+  exclude?: string;
+  /** Show verbose output */
+  verbose?: boolean;
+}
+
+/**
+ * Result of link storybook command
+ */
+export interface LinkStorybookResult {
+  success: boolean;
+  generated: number;
+}
+
+/**
+ * Preview item for stories
+ */
+interface PreviewItem {
+  componentName: string;
+  sourceFile: string;
+  outputFile: string;
+  variantCount: number;
+  propCount: number;
+  confidence: number;
+  warnings: string[];
+}
+
+/**
+ * Run the link storybook command
+ */
+export async function linkStorybook(
+  options: LinkStorybookOptions = {}
+): Promise<LinkStorybookResult> {
+  const { out, yes = false, dryRun = false, verbose = false } = options;
+
+  console.log(pc.cyan(`\n${BRAND.name} Storybook Link\n`));
+
+  // Detect Storybook config
+  const projectRoot = process.cwd();
+  console.log(pc.dim('Detecting Storybook configuration...'));
+
+  const sbConfig = await detectStorybookConfig(projectRoot);
+  if (!sbConfig) {
+    console.log(pc.yellow('\nNo Storybook configuration found.'));
+    console.log(pc.dim('Looking for: .storybook/main.ts, .storybook/main.js, etc.'));
+    console.log(pc.dim('\nUse --config to specify a custom path.'));
+    process.exit(1);
+  }
+
+  console.log(pc.green(`✓ Found: ${sbConfig.configPath}`));
+  if (sbConfig.framework) {
+    console.log(pc.dim(`  Framework: ${sbConfig.framework}`));
+  }
+  if (sbConfig.errors?.length) {
+    for (const err of sbConfig.errors) {
+      console.log(pc.yellow(`  Warning: ${err}`));
+    }
+  }
+
+  // Discover story files
+  console.log(pc.dim('\nDiscovering story files...'));
+  const storyFiles = await discoverStorybookFiles(projectRoot, sbConfig.storyPatterns);
+
+  if (storyFiles.length === 0) {
+    console.log(pc.yellow('\nNo story files found.'));
+    console.log(pc.dim(`Patterns: ${sbConfig.storyPatterns.join(', ')}`));
+    process.exit(1);
+  }
+
+  console.log(pc.green(`✓ Found ${storyFiles.length} story file(s)\n`));
+
+  // Parse and convert each story
+  const previews: PreviewItem[] = [];
+  let parseErrors = 0;
+  const total = storyFiles.length;
+
+  console.log(pc.dim(`Analyzing ${total} stories...\n`));
+
+  for (let i = 0; i < storyFiles.length; i++) {
+    const storyFile = storyFiles[i];
+    const relativePath = relative(projectRoot, storyFile);
+
+    // Show progress
+    process.stdout.write(`\r  ${pc.dim(`[${i + 1}/${total}]`)} ${relativePath.slice(0, 60).padEnd(60)}`);
+
+    try {
+      const parsed = await parseStoryFile(storyFile);
+      const result = convertToSegment(parsed);
+
+      // Determine output path
+      const outputFile = out
+        ? join(out, relativePath.replace(/\.stories\.(tsx?|jsx?)$/, BRAND.fileExtension))
+        : result.outputFile;
+
+      previews.push({
+        componentName: result.componentName,
+        sourceFile: relativePath,
+        outputFile: relative(projectRoot, outputFile),
+        variantCount: result.variantCount,
+        propCount: result.propCount,
+        confidence: result.confidence,
+        warnings: result.warnings,
+      });
+    } catch (error) {
+      parseErrors++;
+      if (verbose) {
+        process.stdout.write('\n');
+        console.log(pc.red(`✗ ${relativePath}: ${error instanceof Error ? error.message : 'Parse error'}`));
+      }
+    }
+  }
+
+  // Clear progress line
+  process.stdout.write('\r' + ' '.repeat(80) + '\r');
+
+  // Display preview table
+  console.log(pc.bold('Preview:\n'));
+  console.log(pc.dim('┌─────────────────────────────────────────────────────────────────┐'));
+  console.log(pc.dim('│') + ' Component'.padEnd(20) + pc.dim('│') + ' Stories'.padEnd(10) + pc.dim('│') + ' Props'.padEnd(8) + pc.dim('│') + ' Confidence'.padEnd(13) + pc.dim('│'));
+  console.log(pc.dim('├─────────────────────────────────────────────────────────────────┤'));
+
+  for (const item of previews) {
+    const confColor = item.confidence >= 0.8 ? pc.green : item.confidence >= 0.5 ? pc.yellow : pc.red;
+    const confLabel = item.confidence >= 0.8 ? 'high' : item.confidence >= 0.5 ? 'medium' : 'low';
+    console.log(
+      pc.dim('│') +
+      ` ${item.componentName}`.padEnd(20).slice(0, 20) +
+      pc.dim('│') +
+      ` ${item.variantCount}`.padEnd(10) +
+      pc.dim('│') +
+      ` ${item.propCount}`.padEnd(8) +
+      pc.dim('│') +
+      ` ${confColor(confLabel)}`.padEnd(13 + (confColor === pc.green ? 10 : confColor === pc.yellow ? 11 : 9)) +
+      pc.dim('│')
+    );
+  }
+
+  console.log(pc.dim('└─────────────────────────────────────────────────────────────────┘'));
+
+  if (parseErrors > 0) {
+    console.log(pc.yellow(`\n${parseErrors} file(s) could not be parsed (use --verbose for details)`));
+  }
+
+  if (previews.length === 0) {
+    console.log(pc.yellow('\nNo stories could be parsed successfully.'));
+    return { success: true, generated: 0 };
+  }
+
+  // Dry run stops here
+  if (dryRun) {
+    console.log(pc.dim(`\n${previews.length} segment file(s) would be created`));
+    console.log(pc.yellow('\n[Dry run - no files were written]'));
+    return { success: true, generated: 0 };
+  }
+
+  // Interactive selection or auto mode (--yes)
+  let selectedPreviews = previews;
+
+  if (yes) {
+    console.log(pc.dim(`\n${previews.length} segment file(s) will be created`));
+  } else {
+    const { checkbox } = await import('@inquirer/prompts');
+
+    console.log(pc.dim('\nUse ↑/↓ to navigate, Space to toggle, Enter to confirm\n'));
+
+    const choices = previews.map((item) => {
+      const confColor = item.confidence >= 0.8 ? pc.green : item.confidence >= 0.5 ? pc.yellow : pc.red;
+      const confLabel = item.confidence >= 0.8 ? 'high' : item.confidence >= 0.5 ? 'medium' : 'low';
+      return {
+        name: `${pc.bold(item.componentName)} ${pc.dim(`(${item.variantCount} stories, ${confLabel} confidence)`)}`,
+        value: item,
+        checked: true,
+      };
+    });
+
+    try {
+      selectedPreviews = await checkbox({
+        message: 'Select stories to convert:',
+        choices,
+        pageSize: 15,
+      });
+    } catch {
+      // User cancelled (Ctrl+C)
+      console.log(pc.dim('\nNo changes made.'));
+      return { success: true, generated: 0 };
+    }
+
+    if (selectedPreviews.length === 0) {
+      console.log(pc.dim('\nNo stories selected. No changes made.'));
+      return { success: true, generated: 0 };
+    }
+  }
+
+  // Generate files
+  const genTotal = selectedPreviews.length;
+  console.log(pc.dim(`\nGenerating ${genTotal} segment file(s)...\n`));
+
+  let generated = 0;
+  let genErrors = 0;
+  for (let i = 0; i < selectedPreviews.length; i++) {
+    const preview = selectedPreviews[i];
+    const storyFile = join(projectRoot, preview.sourceFile);
+    try {
+      const parsed = await parseStoryFile(storyFile);
+      const result = convertToSegment(parsed);
+
+      // Determine output path
+      const outputFile = out
+        ? join(projectRoot, out, preview.sourceFile.replace(/\.stories\.(tsx?|jsx?)$/, BRAND.fileExtension))
+        : result.outputFile;
+
+      // Create directory if needed
+      await mkdir(dirname(outputFile), { recursive: true });
+
+      // Write file
+      await writeFile(outputFile, result.code);
+      generated++;
+
+      console.log(`${pc.dim(`[${i + 1}/${genTotal}]`)} ${pc.green('✓')} ${result.componentName}`);
+    } catch (error) {
+      genErrors++;
+      console.log(`${pc.dim(`[${i + 1}/${genTotal}]`)} ${pc.red('✗')} ${preview.componentName}`);
+    }
+  }
+
+  console.log(pc.green(`\n✓ Generated ${generated} segment file(s)\n`));
+
+  // Next steps
+  console.log(pc.dim('───────────────────────────────────────'));
+  console.log(pc.bold('\nNext steps:'));
+  console.log(`  1. Review generated ${BRAND.fileExtension} files`);
+  console.log(`  2. Fill in usage.when and usage.whenNot fields`);
+  console.log(`  3. Run ${pc.cyan(`${BRAND.cliCommand} build`)} to compile`);
+  console.log(`  4. Run ${pc.cyan(`${BRAND.cliCommand} dev`)} to view your design system`);
+  console.log();
+
+  return { success: true, generated };
+}

package/src/commands/list.ts

@@ -0,0 +1,49 @@
+/**
+ * fragments list - List all discovered fragment files
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig, discoverSegmentFiles } from '../core/node.js';
+
+/**
+ * Options for list command
+ */
+export interface ListOptions {
+  /** Path to config file */
+  config?: string;
+}
+
+/**
+ * Result of list command
+ */
+export interface ListResult {
+  success: boolean;
+  files: Array<{
+    absolutePath: string;
+    relativePath: string;
+  }>;
+}
+
+/**
+ * Run the list command
+ */
+export async function list(options: ListOptions = {}): Promise<ListResult> {
+  const { config, configDir } = await loadConfig(options.config);
+  const files = await discoverSegmentFiles(config, configDir);
+
+  console.log(pc.cyan(`\n${BRAND.name} - Discovered Fragments\n`));
+
+  if (files.length === 0) {
+    console.log(pc.yellow('No fragment files found.\n'));
+    console.log(pc.dim(`Looking for: ${config.include.join(', ')}`));
+    return { success: true, files: [] };
+  }
+
+  for (const file of files) {
+    console.log(`  ${pc.dim('•')} ${file.relativePath}`);
+  }
+  console.log(pc.dim(`\n  ${files.length} fragment(s) found\n`));
+
+  return { success: true, files };
+}

package/src/commands/metrics.ts

@@ -0,0 +1,114 @@
+/**
+ * fragments metrics - View compliance trends over time
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import { createMetricsStore } from '../service/index.js';
+
+/**
+ * Options for metrics command
+ */
+export interface MetricsOptions {
+  /** Path to config file */
+  config?: string;
+  /** Number of days to look back */
+  days?: number;
+  /** Output JSON format */
+  json?: boolean;
+}
+
+/**
+ * Trend data point
+ */
+export interface TrendDataPoint {
+  date: string;
+  compliance: number;
+  violations: number;
+}
+
+/**
+ * Trend result
+ */
+export interface TrendResult {
+  dataPoints: TrendDataPoint[];
+  averageCompliance: number;
+  trend: 'improving' | 'declining' | 'stable';
+}
+
+/**
+ * Result of metrics command
+ */
+export interface MetricsResult {
+  success: boolean;
+  trend?: TrendResult;
+}
+
+/**
+ * Run the metrics command
+ */
+export async function metrics(
+  component: string | undefined,
+  options: MetricsOptions = {}
+): Promise<MetricsResult> {
+  const { config: configPath, days = 30, json = false } = options;
+
+  const { configDir } = await loadConfig(configPath);
+  const store = createMetricsStore(configDir);
+
+  console.log(pc.cyan(`\n${BRAND.name} Compliance Metrics\n`));
+
+  const trend = await store.getTrend(component || 'all', {
+    days,
+    groupBy: days > 14 ? 'week' : 'day',
+  });
+
+  if (json) {
+    console.log(JSON.stringify(trend, null, 2));
+    return { success: true, trend };
+  }
+
+  // Header
+  const title = component ? `Component: ${component}` : 'System-wide';
+  console.log(pc.bold(title));
+  console.log(pc.dim(`Last ${days} days\n`));
+
+  // Check if we have data
+  if (trend.dataPoints.length === 0) {
+    console.log(pc.yellow('No metrics data found.\n'));
+    console.log(pc.dim('Metrics are recorded automatically when running verification commands.'));
+    console.log(pc.dim(`Try running: ${pc.cyan(`${BRAND.cliCommand} verify --ci`)}\n`));
+    return { success: true, trend };
+  }
+
+  // Sparkline
+  const sparkline = store.generateSparkline(trend.dataPoints);
+  console.log(pc.bold('Trend: ') + sparkline);
+  console.log();
+
+  // Stats
+  const trendColor = trend.trend === 'improving' ? pc.green :
+                     trend.trend === 'declining' ? pc.red : pc.dim;
+  const trendIcon = trend.trend === 'improving' ? '↑' :
+                    trend.trend === 'declining' ? '↓' : '→';
+
+  console.log(`  Average compliance: ${pc.bold(`${trend.averageCompliance}%`)}`);
+  console.log(`  Direction: ${trendColor(`${trendIcon} ${trend.trend}`)}`);
+  console.log(`  Data points: ${trend.dataPoints.length}`);
+  console.log();
+
+  // Recent data points
+  const recent = trend.dataPoints.slice(-5);
+  if (recent.length > 0) {
+    console.log(pc.dim('Recent data:'));
+    for (const point of recent) {
+      const complianceColor = point.compliance >= 90 ? pc.green :
+                              point.compliance >= 70 ? pc.yellow : pc.red;
+      console.log(`  ${pc.dim(point.date)} ${complianceColor(`${point.compliance}%`)} ${pc.dim(`(${point.violations} violations)`)}`);
+    }
+    console.log();
+  }
+
+  return { success: true, trend };
+}

package/src/commands/reset.ts

@@ -0,0 +1,242 @@
+/**
+ * fragments reset - Reset to initial state (delete all generated files)
+ */
+
+import { stat, rm, unlink, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import pc from 'picocolors';
+import fg from 'fast-glob';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+
+/**
+ * Options for reset command
+ */
+export interface ResetOptions {
+  /** Skip confirmation prompt */
+  yes?: boolean;
+  /** Show what would be deleted without deleting */
+  dryRun?: boolean;
+}
+
+/**
+ * Result of reset command
+ */
+export interface ResetResult {
+  success: boolean;
+  deletedFiles: number;
+  deletedDirs: number;
+}
+
+/**
+ * Run the reset command
+ */
+export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
+  const { yes = false, dryRun = false } = options;
+
+  console.log(pc.cyan(`\n${BRAND.name} Reset\n`));
+
+  const projectRoot = process.cwd();
+
+  // Items to delete
+  const filesToDelete: string[] = [];
+  const dirsToDelete: string[] = [];
+
+  // Check data directory (.segments/)
+  const dataDir = join(projectRoot, BRAND.dataDir);
+  try {
+    const dataDirStat = await stat(dataDir);
+    if (dataDirStat.isDirectory()) {
+      dirsToDelete.push(dataDir);
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+
+  // Check for segments.json (default output file)
+  const defaultOutFile = join(projectRoot, 'segments.json');
+  try {
+    const fileStat = await stat(defaultOutFile);
+    if (fileStat.isFile()) {
+      filesToDelete.push(defaultOutFile);
+    }
+  } catch {
+    // File doesn't exist
+  }
+
+  // Try to load config for custom outFile and include patterns
+  let segmentPatterns = [`**/*${BRAND.fileExtension}`];
+  try {
+    const { config } = await loadConfig();
+    if (config.outFile && config.outFile !== 'segments.json') {
+      const customOutFile = join(projectRoot, config.outFile);
+      try {
+        const fileStat = await stat(customOutFile);
+        if (fileStat.isFile()) {
+          filesToDelete.push(customOutFile);
+        }
+      } catch {
+        // Custom outfile doesn't exist
+      }
+    }
+    // Use config include patterns if available
+    if (config.include && config.include.length > 0) {
+      segmentPatterns = config.include;
+    }
+  } catch {
+    // No config file, use defaults
+  }
+
+  // Find all segment files (*.segment.tsx)
+  console.log(pc.dim('Scanning for generated files...\n'));
+  for (const pattern of segmentPatterns) {
+    const matches = await fg(pattern, {
+      cwd: projectRoot,
+      ignore: ['**/node_modules/**'],
+      absolute: true,
+    });
+    for (const match of matches) {
+      if (!filesToDelete.includes(match)) {
+        filesToDelete.push(match);
+      }
+    }
+  }
+
+  // Find all Documentation.mdx files (generated by link storybook)
+  const mdxFiles = await fg('**/Documentation.mdx', {
+    cwd: projectRoot,
+    ignore: ['**/node_modules/**'],
+    absolute: true,
+  });
+  for (const mdxFile of mdxFiles) {
+    if (!filesToDelete.includes(mdxFile)) {
+      filesToDelete.push(mdxFile);
+    }
+  }
+
+  // Check if nothing to delete
+  if (filesToDelete.length === 0 && dirsToDelete.length === 0) {
+    console.log(pc.yellow('Nothing to reset. No generated files found.\n'));
+    return { success: true, deletedFiles: 0, deletedDirs: 0 };
+  }
+
+  // Show summary
+  console.log(pc.dim('The following will be deleted:\n'));
+
+  // Show directories
+  for (const dir of dirsToDelete) {
+    const relativePath = relative(projectRoot, dir);
+    console.log(`  📁 ${relativePath}/`);
+  }
+
+  // Group files by type for cleaner output
+  const segmentFiles = filesToDelete.filter((f) => f.endsWith(BRAND.fileExtension));
+  const mdxFilesFound = filesToDelete.filter((f) => f.endsWith('.mdx'));
+  const otherFiles = filesToDelete.filter(
+    (f) => !f.endsWith(BRAND.fileExtension) && !f.endsWith('.mdx')
+  );
+
+  if (segmentFiles.length > 0) {
+    console.log(`  📄 ${segmentFiles.length} segment file(s) (*${BRAND.fileExtension})`);
+    if (segmentFiles.length <= 5) {
+      for (const f of segmentFiles) {
+        console.log(pc.dim(`     ${relative(projectRoot, f)}`));
+      }
+    } else {
+      for (const f of segmentFiles.slice(0, 3)) {
+        console.log(pc.dim(`     ${relative(projectRoot, f)}`));
+      }
+      console.log(pc.dim(`     ... and ${segmentFiles.length - 3} more`));
+    }
+  }
+
+  if (mdxFilesFound.length > 0) {
+    console.log(`  📄 ${mdxFilesFound.length} documentation file(s) (*.mdx)`);
+    if (mdxFilesFound.length <= 5) {
+      for (const f of mdxFilesFound) {
+        console.log(pc.dim(`     ${relative(projectRoot, f)}`));
+      }
+    } else {
+      for (const f of mdxFilesFound.slice(0, 3)) {
+        console.log(pc.dim(`     ${relative(projectRoot, f)}`));
+      }
+      console.log(pc.dim(`     ... and ${mdxFilesFound.length - 3} more`));
+    }
+  }
+
+  for (const f of otherFiles) {
+    console.log(`  📄 ${relative(projectRoot, f)}`);
+  }
+
+  const totalCount = filesToDelete.length + dirsToDelete.length;
+  console.log(pc.dim(`\n  Total: ${totalCount} item(s)\n`));
+
+  // Dry run exits here
+  if (dryRun) {
+    console.log(pc.yellow('[Dry run - no files were deleted]\n'));
+    return { success: true, deletedFiles: 0, deletedDirs: 0 };
+  }
+
+  // Confirm unless --yes
+  let proceed = yes;
+  if (!proceed) {
+    const { confirm } = await import('@inquirer/prompts');
+    try {
+      proceed = await confirm({
+        message: `Delete ${totalCount} item(s)?`,
+        default: false,
+      });
+    } catch {
+      // User cancelled (Ctrl+C)
+      proceed = false;
+    }
+  }
+
+  if (!proceed) {
+    console.log(pc.dim('\nNo changes made.\n'));
+    return { success: true, deletedFiles: 0, deletedDirs: 0 };
+  }
+
+  // Delete directories first
+  console.log();
+  let deletedDirs = 0;
+  for (const dir of dirsToDelete) {
+    try {
+      const relativePath = relative(projectRoot, dir);
+      await rm(dir, { recursive: true, force: true });
+      console.log(`  ${pc.green('✓')} Deleted ${relativePath}/`);
+      deletedDirs++;
+    } catch {
+      console.log(`  ${pc.red('✗')} Failed: ${relative(projectRoot, dir)}`);
+    }
+  }
+
+  // Delete files
+  let deletedCount = 0;
+  let failedCount = 0;
+  for (const file of filesToDelete) {
+    try {
+      await unlink(file);
+      deletedCount++;
+    } catch {
+      failedCount++;
+    }
+  }
+
+  if (deletedCount > 0) {
+    console.log(`  ${pc.green('✓')} Deleted ${deletedCount} file(s)`);
+  }
+  if (failedCount > 0) {
+    console.log(`  ${pc.red('✗')} Failed to delete ${failedCount} file(s)`);
+  }
+
+  console.log(pc.green(`\n✓ Reset complete\n`));
+  console.log(pc.dim(`Config file retained: ${BRAND.configFile}`));
+  console.log(pc.dim(`Run ${pc.cyan(`${BRAND.cliCommand} init`)} to start fresh\n`));
+
+  return {
+    success: true,
+    deletedFiles: deletedCount,
+    deletedDirs,
+  };
+}