@fragments-sdk/cli 0.2.2

package/src/commands/storygen.ts

@@ -0,0 +1,207 @@
+/**
+ * fragments storygen - Generate Storybook stories from segment definitions
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { resolve, join, relative } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import type { SegmentDefinition } from '../core/index.js';
+import { loadConfig, discoverSegmentFiles, loadSegmentFile } from '../core/node.js';
+
+/**
+ * Options for storygen command
+ */
+export interface StorygenOptions {
+  /** Path to config file */
+  config?: string;
+  /** Output directory */
+  output?: string;
+  /** Watch for segment changes and regenerate */
+  watch?: boolean;
+  /** Story format (csf3) */
+  format?: string;
+}
+
+/**
+ * Result of storygen command
+ */
+export interface StorygenResult {
+  success: boolean;
+  generated: number;
+  outputDir: string;
+}
+
+/**
+ * Run the storygen command
+ */
+export async function storygen(options: StorygenOptions = {}): Promise<StorygenResult> {
+  const { config: configPath, output = '.storybook/generated', watch = false } = options;
+
+  const { config, configDir } = await loadConfig(configPath);
+
+  console.log(pc.cyan(`\n${BRAND.name} Story Generator\n`));
+
+  // Discover segment files
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+
+  if (segmentFiles.length === 0) {
+    console.log(pc.yellow('No segment files found.\n'));
+    return { success: true, generated: 0, outputDir: output };
+  }
+
+  const outputDir = resolve(configDir, output);
+  await mkdir(outputDir, { recursive: true });
+
+  let generated = 0;
+
+  // Generate function for a single segment
+  const generateStory = async (file: { absolutePath: string; relativePath: string }) => {
+    try {
+      const segment = await loadSegmentFile(file.absolutePath);
+      if (!segment) return false;
+
+      const storyContent = generateCSF3Story(segment, file.relativePath);
+      const storyName = `${segment.meta.name}.stories.tsx`;
+      const storyPath = join(outputDir, storyName);
+
+      await writeFile(storyPath, storyContent);
+      console.log(`${pc.green('✓')} Generated ${storyName}`);
+      return true;
+    } catch (error) {
+      console.log(`${pc.red('✗')} Failed: ${file.relativePath} - ${error instanceof Error ? error.message : error}`);
+      return false;
+    }
+  };
+
+  // Initial generation
+  console.log(pc.dim(`Generating stories to ${relative(process.cwd(), outputDir)}/\n`));
+
+  for (const file of segmentFiles) {
+    if (await generateStory(file)) {
+      generated++;
+    }
+  }
+
+  console.log();
+  console.log(pc.green(`✓ Generated ${generated} story file(s)\n`));
+
+  // Watch mode
+  if (watch) {
+    console.log(pc.dim('Watching for segment changes... (Ctrl+C to stop)\n'));
+
+    const chokidar = await import('chokidar');
+    const patterns = segmentFiles.map(f => f.absolutePath);
+
+    const watcher = chokidar.watch(patterns, {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 100 },
+    });
+
+    watcher.on('change', async (changedPath: string) => {
+      const file = segmentFiles.find(f => f.absolutePath === changedPath);
+      if (file) {
+        console.log(pc.dim(`\nChanged: ${relative(process.cwd(), changedPath)}`));
+        await generateStory(file);
+      }
+    });
+
+    watcher.on('add', async (addedPath: string) => {
+      console.log(pc.dim(`\nAdded: ${relative(process.cwd(), addedPath)}`));
+      // Re-discover to get the new file's relative path
+      const newFiles = await discoverSegmentFiles(config, configDir);
+      const file = newFiles.find(f => f.absolutePath === addedPath);
+      if (file) {
+        segmentFiles.push(file);
+        await generateStory(file);
+      }
+    });
+
+    // Keep process alive
+    await new Promise(() => {});
+  }
+
+  return { success: true, generated, outputDir };
+}
+
+/**
+ * Generate a CSF3 story file from a segment definition
+ */
+function generateCSF3Story(segment: SegmentDefinition, relativePath: string): string {
+  const { meta, variants, props, usage } = segment;
+  const componentName = meta.name;
+
+  // Build argTypes from props
+  const argTypes: string[] = [];
+  if (props) {
+    for (const [propName, propDef] of Object.entries(props)) {
+      let controlType = 'text';
+      let controlOptions = '';
+
+      if (propDef.type === 'enum' && propDef.values) {
+        controlType = 'select';
+        controlOptions = `,\n        options: ${JSON.stringify(propDef.values)}`;
+      } else if (propDef.type === 'boolean') {
+        controlType = 'boolean';
+      } else if (propDef.type === 'number') {
+        controlType = 'number';
+      }
+
+      argTypes.push(`    ${propName}: {
+      control: '${controlType}'${controlOptions},
+      description: ${JSON.stringify(propDef.description || '')},
+      ${propDef.default !== undefined ? `defaultValue: ${JSON.stringify(propDef.default)},` : ''}
+    }`);
+    }
+  }
+
+  // Build story exports from variants
+  const storyExports: string[] = [];
+  for (const variant of variants) {
+    const storyName = variant.name.replace(/[^a-zA-Z0-9]/g, '');
+    storyExports.push(`
+export const ${storyName}: Story = {
+  name: ${JSON.stringify(variant.name)},
+  ${variant.description ? `parameters: { docs: { description: { story: ${JSON.stringify(variant.description)} } } },` : ''}
+};`);
+  }
+
+  // Build usage description
+  const usageDoc = usage
+    ? `When to use:
+${usage.when?.map(w => `- ${w}`).join('\n') || ''}
+
+When not to use:
+${usage.whenNot?.map(w => `- ${w}`).join('\n') || ''}`
+    : '';
+
+  return `/**
+ * Auto-generated Storybook stories from ${relativePath}
+ *
+ * DO NOT EDIT - regenerate with: segments storygen
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { ${componentName} } from '${relativePath.replace(/\.segment\.tsx$/, '/index.js')}';
+
+const meta: Meta<typeof ${componentName}> = {
+  title: '${meta.category ? `${meta.category.charAt(0).toUpperCase() + meta.category.slice(1)}/` : ''}${componentName}',
+  component: ${componentName},
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: ${JSON.stringify(meta.description || '')},
+      },
+    },
+  },
+  argTypes: {
+${argTypes.join(',\n')}
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+${storyExports.join('\n')}
+`;
+}

package/src/commands/tokens.ts

@@ -0,0 +1,251 @@
+/**
+ * CLI Tokens Command
+ *
+ * Discover and list design tokens from CSS/SCSS files.
+ *
+ * Usage:
+ *   fragments tokens              # List all tokens
+ *   fragments tokens --json       # Output as JSON
+ *   fragments tokens --categories # Group by category
+ *   fragments tokens --theme dark # Filter by theme
+ */
+
+import pc from "picocolors";
+import { BRAND } from "../core/index.js";
+import type { DesignToken, TokenCategory, TokenConfig } from "../core/index.js";
+import { loadConfig } from "../core/node.js";
+import { parseTokenFiles, createTokenRegistry } from "../service/index.js";
+
+export interface TokensCommandOptions {
+  config?: string;
+  json?: boolean;
+  categories?: boolean;
+  theme?: string;
+  category?: string;
+  verbose?: boolean;
+}
+
+export interface TokensCommandResult {
+  success: boolean;
+  tokenCount: number;
+  errors: string[];
+}
+
+/**
+ * Run the tokens command
+ */
+export async function tokens(
+  options: TokensCommandOptions
+): Promise<TokensCommandResult> {
+  const errors: string[] = [];
+
+  try {
+    console.log(pc.cyan(`\n${BRAND.name} Token Discovery\n`));
+
+    // Load config
+    const { config, configDir } = await loadConfig(options.config);
+
+    // Check for token configuration
+    if (!config.tokens || !config.tokens.include || config.tokens.include.length === 0) {
+      console.log(pc.yellow("No token configuration found.\n"));
+      console.log(pc.dim("Add 'tokens' config to fragments.config.ts:"));
+      console.log(pc.dim(`
+  tokens: {
+    include: ['src/styles/theme.scss', 'src/styles/variables.css'],
+    themeSelectors: {
+      ':root': 'default',
+      '[data-theme="dark"]': 'dark',
+    },
+  },
+`));
+      return { success: false, tokenCount: 0, errors: ["No token configuration"] };
+    }
+
+    console.log(pc.dim(`Scanning files: ${config.tokens.include.join(", ")}\n`));
+
+    // Parse token files
+    const parseResult = await parseTokenFiles(config.tokens, configDir);
+
+    if (parseResult.errors.length > 0) {
+      console.log(pc.yellow("Parse errors:"));
+      for (const err of parseResult.errors) {
+        console.log(pc.red(`  ${err.file}: ${err.message}`));
+        errors.push(`${err.file}: ${err.message}`);
+      }
+      console.log();
+    }
+
+    if (parseResult.warnings.length > 0 && options.verbose) {
+      console.log(pc.yellow("Warnings:"));
+      for (const warning of parseResult.warnings) {
+        console.log(pc.dim(`  ${warning}`));
+      }
+      console.log();
+    }
+
+    let tokens = parseResult.tokens;
+
+    // Filter by theme if specified
+    if (options.theme) {
+      tokens = tokens.filter(
+        (t) => t.theme === options.theme || t.theme === "default"
+      );
+    }
+
+    // Filter by category if specified
+    if (options.category) {
+      tokens = tokens.filter((t) => t.category === options.category);
+    }
+
+    if (tokens.length === 0) {
+      console.log(pc.yellow("No tokens found.\n"));
+      console.log(pc.dim("Make sure your CSS files contain CSS custom properties (--token-name: value;)"));
+      return { success: true, tokenCount: 0, errors };
+    }
+
+    // Output based on format
+    if (options.json) {
+      outputJson(tokens, parseResult.parseTimeMs);
+    } else if (options.categories) {
+      outputByCategory(tokens, parseResult.parseTimeMs);
+    } else {
+      outputList(tokens, parseResult.parseTimeMs, options.verbose);
+    }
+
+    return { success: true, tokenCount: tokens.length, errors };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    console.error(pc.red("Error:"), message);
+    errors.push(message);
+    return { success: false, tokenCount: 0, errors };
+  }
+}
+
+/**
+ * Output tokens as JSON
+ */
+function outputJson(tokens: DesignToken[], parseTimeMs: number): void {
+  const output = {
+    tokens,
+    meta: {
+      totalTokens: tokens.length,
+      parseTimeMs,
+      discoveredAt: new Date().toISOString(),
+    },
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * Output tokens grouped by category
+ */
+function outputByCategory(tokens: DesignToken[], parseTimeMs: number): void {
+  // Group by category
+  const byCategory = new Map<TokenCategory, DesignToken[]>();
+
+  for (const token of tokens) {
+    const list = byCategory.get(token.category) || [];
+    list.push(token);
+    byCategory.set(token.category, list);
+  }
+
+  // Sort categories alphabetically
+  const categories = Array.from(byCategory.keys()).sort();
+
+  for (const category of categories) {
+    const categoryTokens = byCategory.get(category) || [];
+    console.log(pc.bold(`${category} (${categoryTokens.length})`));
+    console.log(pc.dim("─".repeat(40)));
+
+    for (const token of categoryTokens.slice(0, 10)) {
+      const levelLabel = token.level === 1 ? "base" : token.level === 2 ? "semantic" : "component";
+      console.log(`  ${pc.cyan(token.name)}`);
+      console.log(`    ${pc.dim("Value:")} ${token.resolvedValue}`);
+      console.log(`    ${pc.dim("Level:")} ${levelLabel} ${pc.dim(`(${token.theme})`)}`);
+    }
+
+    if (categoryTokens.length > 10) {
+      console.log(pc.dim(`  ... and ${categoryTokens.length - 10} more`));
+    }
+    console.log();
+  }
+
+  // Summary
+  console.log(pc.dim("─".repeat(40)));
+  console.log(pc.green(`✓ Found ${tokens.length} token(s) in ${categories.length} categories`));
+  console.log(pc.dim(`  Parsed in ${parseTimeMs.toFixed(1)}ms\n`));
+}
+
+/**
+ * Output tokens as a simple list
+ */
+function outputList(tokens: DesignToken[], parseTimeMs: number, verbose?: boolean): void {
+  // Group by theme first
+  const byTheme = new Map<string, DesignToken[]>();
+
+  for (const token of tokens) {
+    const list = byTheme.get(token.theme) || [];
+    list.push(token);
+    byTheme.set(token.theme, list);
+  }
+
+  const themes = Array.from(byTheme.keys()).sort();
+
+  for (const theme of themes) {
+    const themeTokens = byTheme.get(theme) || [];
+
+    if (themes.length > 1) {
+      console.log(pc.bold(`Theme: ${theme} (${themeTokens.length} tokens)`));
+      console.log(pc.dim("─".repeat(50)));
+    }
+
+    // Sort tokens by name
+    themeTokens.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Table header
+    console.log(
+      pc.dim(
+        `${"Token Name".padEnd(32)} ${"Value".padEnd(20)} ${"Category".padEnd(12)}`
+      )
+    );
+    console.log(pc.dim("─".repeat(70)));
+
+    const displayTokens = verbose ? themeTokens : themeTokens.slice(0, 30);
+
+    for (const token of displayTokens) {
+      const name = token.name.length > 30 ? token.name.slice(0, 27) + "..." : token.name;
+      const value = token.resolvedValue.length > 18 ? token.resolvedValue.slice(0, 15) + "..." : token.resolvedValue;
+
+      console.log(
+        `${pc.cyan(name.padEnd(32))} ${value.padEnd(20)} ${pc.dim(token.category.padEnd(12))}`
+      );
+    }
+
+    if (!verbose && themeTokens.length > 30) {
+      console.log(pc.dim(`\n  ... and ${themeTokens.length - 30} more (use --verbose to show all)`));
+    }
+
+    console.log();
+  }
+
+  // Summary
+  console.log(pc.dim("─".repeat(50)));
+  console.log(pc.green(`✓ Found ${tokens.length} token(s)`));
+
+  // Category breakdown
+  const categoryCounts: Record<string, number> = {};
+  for (const token of tokens) {
+    categoryCounts[token.category] = (categoryCounts[token.category] || 0) + 1;
+  }
+
+  const breakdown = Object.entries(categoryCounts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([cat, count]) => `${cat}: ${count}`)
+    .join(", ");
+
+  console.log(pc.dim(`  ${breakdown}`));
+  console.log(pc.dim(`  Parsed in ${parseTimeMs.toFixed(1)}ms\n`));
+}
+
+export default tokens;

package/src/commands/validate.ts

@@ -0,0 +1,93 @@
+/**
+ * fragments validate - Validate segment files
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import { validateSchema, validateCoverage, validateAll } from '../validators.js';
+
+/**
+ * Options for validate command
+ */
+export interface ValidateOptions {
+  /** Path to config file */
+  config?: string;
+  /** Validate segment schema only */
+  schema?: boolean;
+  /** Validate coverage only */
+  coverage?: boolean;
+}
+
+/**
+ * Result of validate command
+ */
+export interface ValidateResult {
+  valid: boolean;
+  errors: Array<{
+    file: string;
+    message: string;
+    details?: string;
+  }>;
+  warnings: Array<{
+    file: string;
+    message: string;
+  }>;
+}
+
+/**
+ * Run the validate command
+ */
+export async function validate(options: ValidateOptions = {}): Promise<ValidateResult> {
+  const { config, configDir } = await loadConfig(options.config);
+
+  console.log(pc.cyan(`\n${BRAND.name} Validator\n`));
+
+  let result: ValidateResult;
+  if (options.schema) {
+    console.log(pc.dim('Running schema validation...\n'));
+    result = await validateSchema(config, configDir);
+  } else if (options.coverage) {
+    console.log(pc.dim('Running coverage validation...\n'));
+    result = await validateCoverage(config, configDir);
+  } else {
+    console.log(pc.dim('Running all validations...\n'));
+    result = await validateAll(config, configDir);
+  }
+
+  // Print errors
+  if (result.errors.length > 0) {
+    console.log(pc.red(pc.bold('Errors:')));
+    for (const error of result.errors) {
+      console.log(`  ${pc.red('✗')} ${pc.bold(error.file)}`);
+      console.log(`    ${error.message}`);
+      if (error.details) {
+        console.log(pc.dim(`    ${error.details}`));
+      }
+    }
+    console.log();
+  }
+
+  // Print warnings
+  if (result.warnings.length > 0) {
+    console.log(pc.yellow(pc.bold('Warnings:')));
+    for (const warning of result.warnings) {
+      console.log(`  ${pc.yellow('⚠')} ${pc.bold(warning.file)}`);
+      console.log(`    ${warning.message}`);
+    }
+    console.log();
+  }
+
+  // Summary
+  if (result.valid && result.warnings.length === 0) {
+    console.log(pc.green('✓ All validations passed\n'));
+  } else if (result.valid) {
+    console.log(
+      pc.yellow(`⚠ Passed with ${result.warnings.length} warning(s)\n`)
+    );
+  } else {
+    console.log(pc.red(`✗ Failed with ${result.errors.length} error(s)\n`));
+  }
+
+  return result;
+}