@fragments-sdk/cli 0.11.1 → 0.13.0

package/src/migrate/bin.ts

@@ -1,114 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI entry point for migration tool.
- *
- * Can be run standalone or integrated with the main fragments CLI.
- */
-
-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("fragments-migrate")
-  .description(`${BRAND.name} Storybook Migration Tool`)
-  .version(pkg.version);
-
-program
-  .command("migrate")
-  .description("Migrate Storybook stories to Fragments")
-  .argument("<source>", "Source directory or file containing .stories.tsx files")
-  .option("-o, --output <dir>", "Output directory (default: same as source)")
-  .option("--dry-run", "Show what would be generated without writing files")
-  .option("--overwrite", "Overwrite existing fragment files")
-  .option("--report", "Generate HTML migration report")
-  .option("--report-path <path>", "Path for the migration report")
-  .option("-v, --verbose", "Verbose output")
-  .action(async (source, options) => {
-    try {
-      console.log(pc.cyan(`\n${BRAND.name} Migration Tool\n`));
-      console.log(pc.dim("Discovering Storybook files...\n"));
-
-      const report = await migrate({
-        from: source,
-        to: options.output,
-        dryRun: options.dryRun,
-        overwrite: options.overwrite,
-        report: options.report,
-        reportPath: options.reportPath,
-        verbose: options.verbose,
-      });
-
-      // Print results
-      if (report.totalStoryFiles === 0) {
-        console.log(pc.yellow("No story files found.\n"));
-        console.log(pc.dim("Looking for: *.stories.tsx, *.stories.ts, *.stories.jsx, *.stories.js"));
-        return;
-      }
-
-      console.log(pc.dim(`Found ${report.totalStoryFiles} story file(s)\n`));
-
-      // Print each conversion
-      for (const result of report.results) {
-        if (result.success) {
-          console.log(`${pc.green("✓")} ${pc.bold(result.componentName)} → ${result.outputFile}`);
-          console.log(pc.dim(`  ${result.variantCount} variant(s), ${result.todos.length} TODO(s)`));
-        } else {
-          console.log(`${pc.red("✗")} ${result.sourceFile}`);
-          for (const warning of result.warnings) {
-            console.log(pc.dim(`  ${warning}`));
-          }
-        }
-      }
-
-      console.log();
-
-      // Summary
-      if (report.successfulConversions > 0) {
-        console.log(pc.green(`✓ Converted ${report.successfulConversions} component(s)`));
-      }
-      if (report.failedConversions > 0) {
-        console.log(pc.red(`✗ Failed ${report.failedConversions} conversion(s)`));
-      }
-      console.log(pc.dim(`  ${report.totalVariants} variant(s) total`));
-      console.log(pc.dim(`  ${report.totalTodos} TODO(s) need attention`));
-
-      if (options.dryRun) {
-        console.log(pc.yellow("\n[Dry run - no files were written]"));
-      }
-
-      if (options.report) {
-        const reportPath = options.reportPath ?? `${source}/migration-report.html`;
-        console.log(pc.cyan(`\n📊 Report generated: ${reportPath}`));
-      }
-
-      // Next steps
-      console.log(pc.dim("\n───────────────────────────────────────"));
-      console.log(pc.bold("\nNext steps:"));
-      console.log(`  1. Review generated ${BRAND.fileExtension} files`);
-      console.log(`  2. Fill in TODO comments (usage.when, usage.whenNot, etc.)`);
-      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();
-    } catch (error) {
-      console.error(pc.red("Error:"), error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  });
-
-// Also support direct execution without subcommand
-if (process.argv.length > 2 && !process.argv[2].startsWith("-") && process.argv[2] !== "migrate") {
-  // Insert "migrate" as the command
-  process.argv.splice(2, 0, "migrate");
-}
-
-program.parse();

package/src/theme/index.ts

@@ -1,77 +0,0 @@
-/**
- * Theme Customization Module
- *
- * Provides theme configuration, validation, serialization, and generation
- */
-
-// Types
-export type {
-  ThemeConfig,
-  ThemeColors,
-  ThemeSurfaces,
-  ThemeText,
-  ThemeBorders,
-  ThemeTypography,
-  ThemeRadius,
-  ThemeShadows,
-  ThemeDarkMode,
-  TokenOutputFormat,
-  TokenGeneratorOptions,
-  TokenGeneratorResult,
-  PresetName,
-  ContrastPair,
-  ContrastWarning,
-  ContrastValidationResult,
-} from "./types.js";
-
-// Schema validation
-export {
-  themeConfigSchema,
-  themeColorsSchema,
-  themeSurfacesSchema,
-  themeTextSchema,
-  themeBordersSchema,
-  themeTypographySchema,
-  themeRadiusSchema,
-  themeShadowsSchema,
-  themeDarkModeSchema,
-  validateThemeConfig,
-} from "./schema.js";
-export type { ThemeValidationResult } from "./schema.js";
-
-// Serialization
-export {
-  encodeThemeToUrl,
-  decodeThemeFromUrl,
-  compressTheme,
-  decompressTheme,
-} from "./serializer.js";
-
-// Generation
-export {
-  generateScssTokens,
-  generateCssTokens,
-  generateTokenFiles,
-  validateContrast,
-} from "./generator.js";
-
-// Contrast utilities
-export {
-  parseColor,
-  relativeLuminance,
-  contrastRatio,
-  meetsAA,
-  meetsAAA,
-  rgbToHex,
-  suggestFix,
-} from "./contrast.js";
-export type { RGB } from "./contrast.js";
-
-// Presets
-export {
-  DEFAULT_PRESET,
-  PRESETS,
-  getPreset,
-  listPresets,
-  isValidPresetName,
-} from "./presets.js";

package/src/viewer/bin.ts

@@ -1,86 +0,0 @@
-#!/usr/bin/env node
-import pc from 'picocolors';
-import { BRAND } from '../core/index.js';
-import { createDevServer } from './server.js';
-import { runCommand } from './cli/index.js';
-
-async function startDevServer(): Promise<void> {
-  const args = process.argv.slice(2);
-  const portArg = args.find((arg) => arg.startsWith('--port='));
-  const port = portArg ? parseInt(portArg.split('=')[1], 10) : 6006;
-  const noOpen = args.includes('--no-open');
-
-  console.log(pc.cyan(`\n${BRAND.name} Dev Server\n`));
-  console.log(pc.dim('Starting development server...\n'));
-
-  try {
-    const server = await createDevServer({
-      port,
-      open: !noOpen,
-    });
-
-    const address = server.httpServer?.address();
-    const actualPort = typeof address === 'object' && address ? address.port : port;
-
-    console.log(pc.green(`✓ Server running at http://localhost:${actualPort}\n`));
-    console.log(pc.dim('Press Ctrl+C to stop\n'));
-  } catch (error) {
-    console.error(pc.red('Failed to start server:'), error);
-    process.exit(1);
-  }
-}
-
-function showHelp(): void {
-  console.log(pc.cyan(`\n${BRAND.name} CLI\n`));
-  console.log(`Usage: ${BRAND.cliCommand} <command> [options]\n`);
-  console.log('Commands:');
-  console.log('  dev              Start the development server (default)');
-  console.log('  scan <dir>       Scan codebase for component usage');
-  console.log('  health           Generate design system health report');
-  console.log('');
-  console.log('Dev Server Options:');
-  console.log('  --port=<port>    Port to run on (default: 6006)');
-  console.log('  --no-open        Don\'t open browser automatically');
-  console.log('');
-  console.log('Scan Options:');
-  console.log('  --format=<fmt>   Output format: table, json (default: table)');
-  console.log('  --component=<n>  Filter to specific component');
-  console.log('  --verbose        Show detailed usage info');
-  console.log('');
-  console.log('Health Options:');
-  console.log('  --format=<fmt>   Output format: table, json, markdown (default: table)');
-  console.log('  --scan=<dir>     Include codebase usage scan');
-  console.log('  --ci             CI mode: exit 1 if score below threshold');
-  console.log('  --threshold=<n>  Minimum score for CI mode (default: 80)');
-  console.log('');
-}
-
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  // Show help
-  if (command === '--help' || command === '-h' || command === 'help') {
-    showHelp();
-    return;
-  }
-
-  // Route to subcommands
-  if (command === 'scan' || command === 'health') {
-    await runCommand(command, args.slice(1));
-    return;
-  }
-
-  // Default: start dev server (handles 'dev' command or no command)
-  if (!command || command === 'dev' || command.startsWith('--')) {
-    await startDevServer();
-    return;
-  }
-
-  // Unknown command
-  console.error(pc.red(`Unknown command: ${command}`));
-  console.log(pc.dim(`Run "${BRAND.cliCommand} --help" for usage information.\n`));
-  process.exit(1);
-}
-
-main();

package/src/viewer/cli/health.ts

@@ -1,256 +0,0 @@
-/**
- * Health Command
- * Generates a comprehensive design system health report
- */
-
-import pc from 'picocolors';
-import fs from 'fs';
-import path from 'path';
-import { BRAND } from '../../core/index.js';
-import { loadConfig } from '../../core/node.js';
-import { scanForUsages } from '../intelligence/usageScanner.js';
-import { generateHealthReport, formatHealthReportAsMarkdown, type HealthReport } from '../intelligence/healthReport.js';
-import {
-  parseArgs,
-  createSpinner,
-  formatScore,
-  printHeader,
-  printKV,
-  printWarning,
-  printSuccess,
-  formatList,
-} from './utils.js';
-
-type OutputFormat = 'table' | 'json' | 'markdown';
-
-interface HealthCommandOptions {
-  format: OutputFormat;
-  scanDir?: string;
-  ci: boolean;
-  threshold: number;
-}
-
-function parseOptions(args: string[]): HealthCommandOptions {
-  const { options } = parseArgs(args);
-
-  return {
-    format: (options.format as OutputFormat) || 'table',
-    scanDir: options.scan as string | undefined,
-    ci: !!options.ci,
-    threshold: options.threshold ? parseInt(options.threshold as string, 10) : 80,
-  };
-}
-
-/**
- * Load fragments from the project
- */
-async function loadFragments(): Promise<Array<{ path: string; fragment: any }>> {
-  const configResult = await loadConfig();
-
-  if (!configResult) {
-    throw new Error('No fragments.config.ts found. Run this command from a Fragments project.');
-  }
-
-  const { config } = configResult;
-
-  // Try to load compiled fragments
-  const fragmentsPath = path.resolve(process.cwd(), config.outFile || `${BRAND.dataDir}/${BRAND.outFile}`);
-
-  if (fs.existsSync(fragmentsPath)) {
-    const data = JSON.parse(fs.readFileSync(fragmentsPath, 'utf-8'));
-    return Object.entries(data.fragments || {}).map(([name, fragment]: [string, any]) => ({
-      path: fragment.filePath || name,
-      fragment: {
-        meta: fragment.meta || { name, description: '', category: '' },
-        usage: fragment.usage || { when: [], whenNot: [] },
-        props: fragment.props || {},
-        variants: fragment.variants || [],
-        relations: fragment.relations,
-        contract: fragment.contract,
-        _generated: fragment._generated,
-        component: () => null, // Placeholder
-      },
-    }));
-  }
-
-  // Fallback: return empty if no compiled fragments
-  console.log(pc.yellow(`No compiled fragments found. Run \`${BRAND.cliCommand} build\` first for complete analysis.`));
-  return [];
-}
-
-function formatGrade(grade: string): string {
-  switch (grade) {
-    case 'A':
-      return pc.green(pc.bold(grade));
-    case 'B':
-      return pc.cyan(grade);
-    case 'C':
-      return pc.yellow(grade);
-    case 'D':
-      return pc.magenta(grade);
-    case 'F':
-      return pc.red(pc.bold(grade));
-    default:
-      return grade;
-  }
-}
-
-function formatTableOutput(report: HealthReport): void {
-  console.log(pc.cyan(`\n${BRAND.name} Health Report\n`));
-  console.log(pc.dim(`Generated: ${new Date(report.generatedAt).toLocaleString()}\n`));
-
-  // Overall score
-  const scoreColor = report.overallScore >= 80 ? pc.green : report.overallScore >= 60 ? pc.yellow : pc.red;
-  console.log(`  ${pc.bold('Overall Score:')} ${scoreColor(pc.bold(`${report.overallScore}%`))}\n`);
-
-  // Grade summary
-  console.log(pc.bold('  Category Grades:\n'));
-  console.log(`    Usage:         ${formatGrade(report.grades.usage)}  (${report.usage.adoptionRate}% adoption)`);
-  console.log(`    Style Drift:   ${formatGrade(report.grades.drift)}  (${report.styleDrift.averageCompliance}% compliance)`);
-  console.log(`    Documentation: ${formatGrade(report.grades.documentation)}  (${report.documentation.documentationRate}% documented)`);
-  console.log(`    Token Usage:   ${formatGrade(report.grades.tokens)}  (${report.tokens.tokenizationRate}% tokenized)`);
-  console.log('');
-
-  // Usage section
-  printHeader('Usage Statistics');
-  printKV('Total Components', report.usage.totalComponents.toString());
-  printKV('Used Components', report.usage.usedComponents.toString());
-  printKV('Adoption Rate', formatScore(report.usage.adoptionRate));
-
-  if (report.usage.mostUsed.length > 0) {
-    console.log(pc.dim('\n  Most Used:'));
-    for (const item of report.usage.mostUsed.slice(0, 5)) {
-      console.log(`    ${pc.cyan(item.component)}: ${item.count} uses`);
-    }
-  }
-
-  if (report.usage.unusedComponents.length > 0 && report.usage.unusedComponents.length <= 5) {
-    console.log(pc.dim('\n  Unused:'));
-    for (const name of report.usage.unusedComponents) {
-      printWarning(name);
-    }
-  } else if (report.usage.unusedComponents.length > 5) {
-    printWarning(`${report.usage.unusedComponents.length} unused components`);
-  }
-
-  // Style Drift section
-  printHeader('Style Drift Analysis');
-  printKV('Components with Drift', report.styleDrift.componentsWithDrift.toString());
-  printKV('Total Drifts', report.styleDrift.totalDrifts.toString());
-  printKV('Average Compliance', formatScore(report.styleDrift.averageCompliance));
-
-  if (report.styleDrift.bySeverity.high > 0) {
-    console.log('');
-    printWarning(`${report.styleDrift.bySeverity.high} high-severity drift(s) - affects brand identity`);
-  }
-
-  if (report.styleDrift.worstOffenders.length > 0) {
-    console.log(pc.dim('\n  Needs Attention:'));
-    for (const item of report.styleDrift.worstOffenders.slice(0, 3)) {
-      console.log(`    ${pc.red('!')} ${item.component} (${item.variant}): ${item.driftCount} drifts`);
-    }
-  }
-
-  // Documentation section
-  printHeader('Documentation Coverage');
-  printKV('Documented', `${report.documentation.documented} components`);
-  printKV('Coverage', formatScore(report.documentation.documentationRate));
-
-  if (report.documentation.missingDescriptions.length > 0) {
-    printWarning(`${report.documentation.missingDescriptions.length} missing descriptions`);
-  }
-
-  if (report.documentation.missingUsage.length > 0) {
-    printWarning(`${report.documentation.missingUsage.length} missing usage guidelines`);
-  }
-
-  // Token section
-  printHeader('Design Token Usage');
-  printKV('Token Compliance', formatScore(report.tokens.complianceScore));
-  printKV('Tokenized Values', report.tokens.tokenizedValues.toString());
-  printKV('Hardcoded Values', report.tokens.hardcodedValues.toString(), report.tokens.hardcodedValues > 0 ? pc.yellow : undefined);
-
-  // Recommendations
-  if (report.recommendations.length > 0) {
-    printHeader('Recommendations');
-    console.log('');
-    for (const rec of report.recommendations) {
-      console.log(`  ${pc.yellow('→')} ${rec}`);
-    }
-  }
-
-  console.log('');
-}
-
-function formatJsonOutput(report: HealthReport): void {
-  console.log(JSON.stringify(report, null, 2));
-}
-
-function formatMarkdownOutput(report: HealthReport): void {
-  console.log(formatHealthReportAsMarkdown(report));
-}
-
-/**
- * Run the health command
- */
-export async function healthCommand(args: string[]): Promise<void> {
-  const options = parseOptions(args);
-
-  const spinner = createSpinner('Analyzing design system health...');
-  spinner.start();
-
-  try {
-    // Load fragments
-    spinner.update('Loading fragments...');
-    const fragments = await loadFragments();
-
-    if (fragments.length === 0) {
-      spinner.stop(false, 'No fragments found');
-      console.log(pc.yellow(`\nNo components to analyze. Create fragment files or run \`${BRAND.cliCommand} build\`.\n`));
-      return;
-    }
-
-    // Run usage scan if directory provided
-    let usageScan;
-    if (options.scanDir) {
-      spinner.update(`Scanning ${options.scanDir} for component usage...`);
-      usageScan = await scanForUsages({ directory: options.scanDir });
-    }
-
-    // Generate report
-    spinner.update('Generating health report...');
-    const report = generateHealthReport({
-      fragments,
-      usageScan,
-      // Note: Drift reports would require running the viewer and extracting styles
-      // For CLI, we focus on what can be statically analyzed
-    });
-
-    spinner.stop(true, 'Health analysis complete');
-
-    // Output
-    switch (options.format) {
-      case 'json':
-        formatJsonOutput(report);
-        break;
-      case 'markdown':
-        formatMarkdownOutput(report);
-        break;
-      default:
-        formatTableOutput(report);
-    }
-
-    // CI mode: exit with error if below threshold
-    if (options.ci) {
-      if (report.overallScore < options.threshold) {
-        console.log(pc.red(`\nCI Check Failed: Score ${report.overallScore}% is below threshold ${options.threshold}%\n`));
-        process.exit(1);
-      } else {
-        console.log(pc.green(`\nCI Check Passed: Score ${report.overallScore}% meets threshold ${options.threshold}%\n`));
-      }
-    }
-  } catch (error) {
-    spinner.stop(false, 'Health analysis failed');
-    throw error;
-  }
-}

package/src/viewer/cli/index.ts

@@ -1,33 +0,0 @@
-/**
- * CLI Command Router
- * Routes subcommands to their respective handlers
- */
-
-import pc from 'picocolors';
-import { scanCommand } from './scan.js';
-import { healthCommand } from './health.js';
-
-export type CommandName = 'scan' | 'health';
-
-/**
- * Run a CLI command with the given arguments
- */
-export async function runCommand(command: CommandName, args: string[]): Promise<void> {
-  try {
-    switch (command) {
-      case 'scan':
-        await scanCommand(args);
-        break;
-      case 'health':
-        await healthCommand(args);
-        break;
-      default:
-        console.error(pc.red(`Unknown command: ${command}`));
-        process.exit(1);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(pc.red(`\nError: ${message}\n`));
-    process.exit(1);
-  }
-}

package/src/viewer/cli/scan.ts

@@ -1,124 +0,0 @@
-/**
- * Scan Command
- * Scans a codebase for component usage
- */
-
-import pc from 'picocolors';
-import path from 'path';
-import { scanForUsages, type FullScanResult, type UsageScanResult } from '../intelligence/usageScanner.js';
-import { parseArgs, createSpinner, formatTable, formatDuration, printHeader, printKV } from './utils.js';
-
-type OutputFormat = 'table' | 'json';
-
-interface ScanCommandOptions {
-  format: OutputFormat;
-  component?: string;
-  verbose: boolean;
-}
-
-function parseOptions(args: string[]): { directory: string; options: ScanCommandOptions } {
-  const { positional, options } = parseArgs(args);
-
-  return {
-    directory: positional[0] || '.',
-    options: {
-      format: (options.format as OutputFormat) || 'table',
-      component: options.component as string | undefined,
-      verbose: !!options.verbose || !!options.v,
-    },
-  };
-}
-
-function formatTableOutput(result: FullScanResult, options: ScanCommandOptions): void {
-  const { results, summary } = result;
-
-  printHeader('Component Usage Scan');
-  printKV('Directory scanned', path.resolve(result.results[0]?.usages[0]?.file || '.').split(path.sep).slice(0, -1).join(path.sep) || '.');
-  printKV('Files scanned', summary.totalFiles.toString());
-  printKV('Files with usage', summary.filesWithUsage.toString());
-  printKV('Scan time', formatDuration(summary.scanTimeMs));
-  console.log('');
-
-  if (results.length === 0) {
-    console.log(pc.yellow('  No component usages found.\n'));
-    return;
-  }
-
-  // Summary table
-  const headers = ['Component', 'Files', 'Total Uses'];
-  const rows = results.map((r) => [
-    r.component,
-    String(r.usages.length),
-    String(r.totalUsages),
-  ]);
-
-  console.log(formatTable(headers, rows));
-  console.log('');
-
-  // Verbose: show file details
-  if (options.verbose) {
-    console.log(pc.bold('\nDetailed Usage:\n'));
-
-    for (const r of results) {
-      console.log(pc.cyan(`  ${r.component}`));
-      for (const usage of r.usages) {
-        const relativePath = path.relative(process.cwd(), usage.file);
-        const importIcon = usage.importType === 'named' ? '{}' : usage.importType === 'default' ? '=>' : '*';
-        console.log(pc.dim(`    ${importIcon} ${relativePath}:${usage.line} (${usage.usageCount} uses)`));
-      }
-      console.log('');
-    }
-  }
-
-  // Summary footer
-  console.log(pc.dim('─'.repeat(50)));
-  console.log(`  ${pc.bold(String(summary.totalComponents))} components used ${pc.bold(String(summary.totalUsages))} times across ${pc.bold(String(summary.filesWithUsage))} files`);
-  console.log('');
-}
-
-function formatJsonOutput(result: FullScanResult): void {
-  const output = {
-    summary: result.summary,
-    components: result.results.map((r) => ({
-      name: r.component,
-      totalUsages: r.totalUsages,
-      fileCount: r.usages.length,
-      usages: r.usages.map((u) => ({
-        file: path.relative(process.cwd(), u.file),
-        line: u.line,
-        importType: u.importType,
-        usageCount: u.usageCount,
-      })),
-    })),
-  };
-
-  console.log(JSON.stringify(output, null, 2));
-}
-
-/**
- * Run the scan command
- */
-export async function scanCommand(args: string[]): Promise<void> {
-  const { directory, options } = parseOptions(args);
-
-  const spinner = createSpinner(`Scanning ${directory} for component usage...`);
-  spinner.start();
-
-  try {
-    const result = await scanForUsages({
-      directory,
-      components: options.component ? [options.component] : undefined,
-    });
-
-    spinner.stop(true, `Scanned ${result.summary.totalFiles} files in ${formatDuration(result.summary.scanTimeMs)}`);
-
-    if (options.format === 'json') {
-      formatJsonOutput(result);
-    } else {
-      formatTableOutput(result, options);
-    }
-  } catch (error) {
-    spinner.stop(false, 'Scan failed');
-    throw error;
-  }
-}