@fragments-sdk/cli 0.2.2

package/src/commands/add.ts

@@ -0,0 +1,313 @@
+/**
+ * fragments add - Scaffold a new component with fragment file
+ */
+
+import { writeFile, mkdir, access } from 'node:fs/promises';
+import { resolve, join, relative } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+
+/**
+ * Options for add command
+ */
+export interface AddOptions {
+  /** Component category */
+  category?: string;
+  /** Output directory */
+  dir?: string;
+  /** Template to use (action, form-input, layout, display) */
+  template?: string;
+  /** Only generate fragment file, skip component stub */
+  component?: boolean;
+}
+
+/**
+ * Result of add command
+ */
+export interface AddResult {
+  success: boolean;
+  componentPath?: string;
+  segmentPath: string;
+  indexPath?: string;
+}
+
+/**
+ * Run the add command
+ */
+export async function add(
+  name: string | undefined,
+  options: AddOptions = {}
+): Promise<AddResult> {
+  console.log(pc.cyan(`\n${BRAND.name} Component Scaffold\n`));
+
+  let componentName = name;
+  let category = options.category;
+  let template = options.template;
+  let dir = options.dir;
+  const generateComponent = options.component !== false;
+
+  // If any required values are missing, go interactive
+  if (!componentName || !category || !template || !dir) {
+    const { input, select } = await import('@inquirer/prompts');
+
+    try {
+      // Component name
+      if (!componentName) {
+        componentName = await input({
+          message: 'Component name:',
+          validate: (value) => {
+            if (!value.trim()) return 'Component name is required';
+            if (!/^[A-Za-z][A-Za-z0-9]*$/.test(value)) return 'Use PascalCase (e.g., Button, TextField)';
+            return true;
+          },
+        });
+      }
+
+      // Template type
+      if (!template) {
+        template = await select({
+          message: 'What type of component is this?',
+          choices: [
+            { name: 'Display - Shows information or status', value: 'display' },
+            { name: 'Action - Triggers an action (button, link)', value: 'action' },
+            { name: 'Form Input - Accepts user input', value: 'form-input' },
+            { name: 'Layout - Organizes content structure', value: 'layout' },
+          ],
+          default: 'display',
+        });
+      }
+
+      // Category
+      if (!category) {
+        category = await input({
+          message: 'Category:',
+          default: template === 'form-input' ? 'forms' : template === 'layout' ? 'layout' : 'components',
+        });
+      }
+
+      // Output directory
+      if (!dir) {
+        dir = await input({
+          message: 'Output directory:',
+          default: 'src/components',
+        });
+      }
+    } catch {
+      // User cancelled (Ctrl+C)
+      console.log(pc.dim('\nNo changes made.'));
+      process.exit(0);
+    }
+  }
+
+  // Normalize component name (PascalCase)
+  componentName = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+  // Apply defaults for non-interactive values
+  category = category || 'components';
+  template = template || 'display';
+  dir = dir || 'src/components';
+
+  // Determine output paths
+  const componentDir = resolve(process.cwd(), dir, componentName);
+  const componentFile = join(componentDir, `${componentName}.tsx`);
+  const segmentFile = join(componentDir, `${componentName}${BRAND.fileExtension}`);
+  const indexFile = join(componentDir, 'index.ts');
+
+  // Check if directory already exists
+  try {
+    await access(componentDir);
+    console.log(pc.yellow(`Directory already exists: ${relative(process.cwd(), componentDir)}`));
+    console.log(pc.dim('Use a different name or remove the existing directory.'));
+    process.exit(1);
+  } catch {
+    // Directory doesn't exist, proceed
+  }
+
+  // Create directory
+  await mkdir(componentDir, { recursive: true });
+
+  // Generate component stub (unless --no-component)
+  if (generateComponent) {
+    const componentCode = generateComponentStub(componentName, template);
+    await writeFile(componentFile, componentCode);
+    console.log(`${pc.green('✓')} Created ${relative(process.cwd(), componentFile)}`);
+  }
+
+  // Generate segment file
+  const segmentCode = generateSegmentStub(componentName, category, template);
+  await writeFile(segmentFile, segmentCode);
+  console.log(`${pc.green('✓')} Created ${relative(process.cwd(), segmentFile)}`);
+
+  // Generate index.ts
+  const indexCode = `export { ${componentName} } from './${componentName}.js';\n`;
+  await writeFile(indexFile, indexCode);
+  console.log(`${pc.green('✓')} Created ${relative(process.cwd(), indexFile)}`);
+
+  console.log(pc.green(`\n✓ Scaffolded ${componentName}\n`));
+
+  // Next steps
+  console.log(pc.dim('───────────────────────────────────────'));
+  console.log(pc.bold('\nNext steps:'));
+  if (generateComponent) {
+    console.log(`  1. Implement ${componentName}.tsx`);
+  }
+  console.log(`  2. Fill in usage.when and usage.whenNot in the fragment file`);
+  console.log(`  3. Add variants with different prop combinations`);
+  console.log(`  4. Run ${pc.cyan(`${BRAND.cliCommand} dev`)} to preview`);
+  console.log();
+
+  return {
+    success: true,
+    componentPath: generateComponent ? componentFile : undefined,
+    segmentPath: segmentFile,
+    indexPath: indexFile,
+  };
+}
+
+/**
+ * Generate a React component stub based on template type.
+ */
+function generateComponentStub(name: string, _template: string): string {
+  const propsInterface = `export interface ${name}Props {
+  /** Content to display */
+  children?: React.ReactNode;
+  /** Additional CSS classes */
+  className?: string;
+}`;
+
+  return `import React from 'react';
+
+${propsInterface}
+
+/**
+ * ${name} component
+ *
+ * TODO: Implement this component
+ */
+export function ${name}({ children, className }: ${name}Props) {
+  return (
+    <div className={className}>
+      {children}
+    </div>
+  );
+}
+`;
+}
+
+/**
+ * Generate a segment stub based on template type.
+ */
+function generateSegmentStub(name: string, category: string, template: string): string {
+  // Template-specific usage hints
+  const usageHints: Record<string, { when: string[]; whenNot: string[] }> = {
+    action: {
+      when: ['User needs to trigger an action', 'Form submission is required'],
+      whenNot: ['Navigation is needed (use Link)', 'Action is destructive without confirmation'],
+    },
+    'form-input': {
+      when: ['User needs to enter data', 'Form field is required'],
+      whenNot: ['Display-only data is shown', 'Rich text editing is needed'],
+    },
+    layout: {
+      when: ['Content needs to be organized', 'Responsive layout is required'],
+      whenNot: ['Simple inline content is displayed', 'Scroll container is needed'],
+    },
+    display: {
+      when: ['Information needs to be presented', 'Status or feedback is shown'],
+      whenNot: ['User interaction is required', 'Data input is needed'],
+    },
+  };
+
+  const hints = usageHints[template] || usageHints.display;
+
+  // Template-specific scenario tags
+  const scenarioTagHints: Record<string, string[]> = {
+    action: ['action.primary', 'action.secondary', 'form.submit'],
+    'form-input': ['form.input', 'form.field', 'form.text'],
+    layout: ['layout.container', 'layout.section', 'content.group'],
+    display: ['display.info', 'display.status', 'content.text'],
+  };
+
+  const scenarioTags = scenarioTagHints[template] || scenarioTagHints.display;
+
+  return `import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ${name} } from './index.js';
+
+export default defineSegment({
+  component: ${name},
+
+  meta: {
+    name: '${name}',
+    description: 'TODO: Add description',
+    category: '${category}',
+    status: 'experimental',
+    tags: ['${category}'],
+  },
+
+  usage: {
+    when: [
+      '${hints.when[0]}',
+      '${hints.when[1]}',
+    ],
+    whenNot: [
+      '${hints.whenNot[0]}',
+      '${hints.whenNot[1]}',
+    ],
+    guidelines: [
+      // TODO: Add best practices
+    ],
+    accessibility: [
+      // TODO: Add accessibility guidelines
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Content to display',
+    },
+    className: {
+      type: 'string',
+      description: 'Additional CSS classes',
+    },
+    // TODO: Add more props
+  },
+
+  relations: [
+    // TODO: Add related components
+    // { component: 'RelatedComponent', relationship: 'alternative', note: 'Use for...' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - content to display',
+      'className: string - additional CSS classes',
+      // TODO: Add prop summaries
+    ],
+    scenarioTags: [
+      '${scenarioTags[0]}',
+      '${scenarioTags[1]}',
+      // TODO: Add scenario tags for AI agent queries
+    ],
+    a11yRules: [
+      // TODO: Add accessibility rule IDs
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Default ${name} appearance',
+      render: () => <${name}>Example content</${name}>,
+    },
+    // TODO: Add more variants
+    // {
+    //   name: 'WithProps',
+    //   description: '${name} with additional props',
+    //   render: () => <${name} someProp="value">Content</${name}>,
+    // },
+  ],
+});
+`;
+}

package/src/commands/audit.ts

@@ -0,0 +1,195 @@
+/**
+ * fragments audit - Scan all fragments and show compliance metrics
+ *
+ * Uses the /fragments/compliance endpoint to get real token compliance data
+ * for all components in the design system.
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import {
+  createDevServerClient,
+  DevServerConnectionError,
+  type AuditResult,
+} from '../shared/index.js';
+
+/**
+ * Options for audit command
+ */
+export interface AuditOptions {
+  /** Path to config file */
+  config?: string;
+  /** Output JSON format */
+  json?: boolean;
+  /** Sort field: compliance, name, hardcoded */
+  sort?: 'compliance' | 'name' | 'hardcoded';
+  /** Dev server port */
+  port?: number | string;
+}
+
+/**
+ * Summary of audit results
+ */
+export interface AuditSummary {
+  totalComponents: number;
+  averageCompliance: number;
+  worstOffenders: AuditResult[];
+  components: AuditResult[];
+  stats: {
+    totalHardcoded: number;
+    totalTokenMismatches: number;
+    totalProperties: number;
+  };
+}
+
+/**
+ * Run the audit command
+ */
+export async function audit(options: AuditOptions = {}): Promise<AuditSummary> {
+  const { config: configPath, json = false, sort = 'compliance', port = 6006 } = options;
+
+  // Load config
+  await loadConfig(configPath);
+
+  const client = createDevServerClient(port);
+  const audits: AuditResult[] = [];
+
+  if (!json) {
+    console.log(pc.cyan(`\n${BRAND.name} Design System Audit\n`));
+  }
+
+  // Check if dev server is reachable
+  const isReachable = await client.ping();
+  if (!isReachable) {
+    throw new DevServerConnectionError(
+      `Cannot connect to dev server at http://localhost:${port}`,
+      `http://localhost:${port}`
+    );
+  }
+
+  // Fetch all fragments
+  const segments = await client.getSegments();
+
+  if (segments.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({ error: 'No fragments found', components: [] }));
+    } else {
+      console.log(pc.yellow('No fragments found.\n'));
+    }
+    return {
+      totalComponents: 0,
+      averageCompliance: 100,
+      worstOffenders: [],
+      components: [],
+      stats: {
+        totalHardcoded: 0,
+        totalTokenMismatches: 0,
+        totalProperties: 0,
+      },
+    };
+  }
+
+  if (!json) {
+    console.log(pc.dim(`Auditing ${segments.length} component(s)...\n`));
+  }
+
+  // Audit each fragment
+  for (const seg of segments) {
+    try {
+      // Get real compliance from the server
+      const complianceResult = await client.getCompliance({
+        component: seg.name,
+      });
+
+      audits.push({
+        name: seg.name,
+        category: seg.category || 'uncategorized',
+        compliance: complianceResult.compliance,
+        hardcoded: complianceResult.hardcoded,
+        tokenMismatches: complianceResult.violations.filter(
+          v => v.issue.includes('mismatch')
+        ).length,
+        totalProperties: complianceResult.totalProperties,
+      });
+    } catch (error) {
+      // Handle individual component errors
+      audits.push({
+        name: seg.name,
+        category: seg.category || 'uncategorized',
+        compliance: 0,
+        hardcoded: 0,
+        tokenMismatches: 0,
+        totalProperties: 0,
+      });
+    }
+  }
+
+  // Sort results
+  audits.sort((a, b) => {
+    switch (sort) {
+      case 'name':
+        return a.name.localeCompare(b.name);
+      case 'hardcoded':
+        return b.hardcoded - a.hardcoded; // Most hardcoded first
+      case 'compliance':
+      default:
+        return a.compliance - b.compliance; // Worst first
+    }
+  });
+
+  const summary: AuditSummary = {
+    totalComponents: audits.length,
+    averageCompliance: audits.length > 0
+      ? Math.round(audits.reduce((sum, a) => sum + a.compliance, 0) / audits.length * 100) / 100
+      : 100,
+    worstOffenders: audits.slice(0, 5),
+    components: audits,
+    stats: {
+      totalHardcoded: audits.reduce((sum, a) => sum + a.hardcoded, 0),
+      totalTokenMismatches: audits.reduce((sum, a) => sum + a.tokenMismatches, 0),
+      totalProperties: audits.reduce((sum, a) => sum + a.totalProperties, 0),
+    },
+  };
+
+  if (json) {
+    // JSON output for CI/automation
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    // Table output for humans
+    console.log(pc.bold('Component'.padEnd(30) + 'Compliance'.padEnd(12) + 'Hardcoded'.padEnd(12) + 'Properties'));
+    console.log(pc.dim('─'.repeat(66)));
+
+    for (const auditItem of audits) {
+      const complianceColor = auditItem.compliance >= 90
+        ? pc.green
+        : auditItem.compliance >= 70
+          ? pc.yellow
+          : pc.red;
+
+      console.log(
+        auditItem.name.padEnd(30) +
+        complianceColor(`${auditItem.compliance}%`.padEnd(12)) +
+        String(auditItem.hardcoded).padEnd(12) +
+        String(auditItem.totalProperties)
+      );
+    }
+
+    console.log(pc.dim('─'.repeat(66)));
+
+    console.log();
+    console.log(pc.bold('Summary:'));
+    console.log(`  Total components: ${audits.length}`);
+    console.log(`  Average compliance: ${summary.averageCompliance}%`);
+    console.log(`  Total hardcoded values: ${summary.stats.totalHardcoded}`);
+    console.log(`  Total properties checked: ${summary.stats.totalProperties}`);
+
+    if (audits.some(a => a.compliance < 100)) {
+      console.log();
+      console.log(pc.dim(`Run ${pc.cyan(`${BRAND.cliCommand} verify <component>`)} for detailed compliance info.`));
+    }
+    console.log();
+  }
+
+  return summary;
+}