@fragments-sdk/cli 0.14.2 → 0.15.0

package/src/commands/setup.ts

@@ -456,6 +456,28 @@ function generateScssSeedImport(brand?: string): string {
 `;
 }
 
+// ============================================
+// Step runner
+// ============================================
+
+async function runSetupStep(
+  fn: () => Promise<{ modified: boolean; message: string }>,
+  failureLabel: string,
+  actions: string[],
+  errors: string[],
+): Promise<void> {
+  try {
+    const result = await fn();
+    const icon = result.modified ? pc.green('+') : pc.dim('·');
+    console.log(`  ${icon} ${result.message}`);
+    if (result.modified) actions.push(result.message);
+  } catch (error) {
+    const msg = `${failureLabel}: ${error instanceof Error ? error.message : error}`;
+    console.log(`  ${pc.red('✗')} ${msg}`);
+    errors.push(msg);
+  }
+}
+
 // ============================================
 // Main Setup Function
 // ============================================
@@ -491,72 +513,27 @@ export async function setup(options: SetupOptions = {}): Promise<SetupResult> {
 
   // 3. Add styles import
   if (entryFile) {
-    try {
-      const result = await addStylesImport(root, entryFile);
-      const icon = result.modified ? pc.green('+') : pc.dim('·');
-      console.log(`  ${icon} ${result.message}`);
-      if (result.modified) actions.push(result.message);
-    } catch (error) {
-      const msg = `Failed to add styles import: ${error instanceof Error ? error.message : error}`;
-      console.log(`  ${pc.red('✗')} ${msg}`);
-      errors.push(msg);
-    }
+    await runSetupStep(() => addStylesImport(root, entryFile), 'Failed to add styles import', actions, errors);
   }
 
   // 4. Add ThemeProvider imports
   if (entryFile) {
-    try {
-      const result = await addThemeProvider(root, entryFile, framework);
-      const icon = result.modified ? pc.green('+') : pc.dim('·');
-      console.log(`  ${icon} ${result.message}`);
-      if (result.modified) actions.push(result.message);
-    } catch (error) {
-      const msg = `Failed to add ThemeProvider: ${error instanceof Error ? error.message : error}`;
-      console.log(`  ${pc.red('✗')} ${msg}`);
-      errors.push(msg);
-    }
+    await runSetupStep(() => addThemeProvider(root, entryFile, framework), 'Failed to add ThemeProvider', actions, errors);
   }
 
   // 5. Next.js: add transpilePackages
   if (framework === 'nextjs-app' || framework === 'nextjs-pages') {
-    try {
-      const result = await addTranspilePackages(root);
-      const icon = result.modified ? pc.green('+') : pc.dim('·');
-      console.log(`  ${icon} ${result.message}`);
-      if (result.modified) actions.push(result.message);
-    } catch (error) {
-      const msg = `Failed to update next.config: ${error instanceof Error ? error.message : error}`;
-      console.log(`  ${pc.red('✗')} ${msg}`);
-      errors.push(msg);
-    }
+    await runSetupStep(() => addTranspilePackages(root), 'Failed to update next.config', actions, errors);
   }
 
   // 6. Create SCSS seeds file (if --scss flag or brand color specified)
   if (options.scss || options.brand) {
-    try {
-      const result = await createScssSeeds(root, options.brand);
-      const icon = result.modified ? pc.green('+') : pc.dim('·');
-      console.log(`  ${icon} ${result.message}`);
-      if (result.modified) actions.push(result.message);
-    } catch (error) {
-      const msg = `Failed to create SCSS seeds: ${error instanceof Error ? error.message : error}`;
-      console.log(`  ${pc.red('✗')} ${msg}`);
-      errors.push(msg);
-    }
+    await runSetupStep(() => createScssSeeds(root, options.brand), 'Failed to create SCSS seeds', actions, errors);
   }
 
   // 7. Configure MCP server (if --mcp flag)
   if (options.mcp) {
-    try {
-      const result = await setupMcpConfig(root);
-      const icon = result.modified ? pc.green('+') : pc.dim('·');
-      console.log(`  ${icon} ${result.message}`);
-      if (result.modified) actions.push(result.message);
-    } catch (error) {
-      const msg = `Failed to configure MCP: ${error instanceof Error ? error.message : error}`;
-      console.log(`  ${pc.red('✗')} ${msg}`);
-      errors.push(msg);
-    }
+    await runSetupStep(() => setupMcpConfig(root), 'Failed to configure MCP', actions, errors);
   }
 
   // Summary

package/src/commands/tokens-generate.ts

@@ -0,0 +1,113 @@
+/**
+ * fragments tokens generate — Generate CSS, SCSS, Tailwind, or Figma output
+ * from a DTCG .tokens.json source file.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname, basename, extname } from 'node:path';
+import pc from 'picocolors';
+import {
+  generateCSSCustomProperties,
+  generateSCSSVariables,
+  generateTailwindConfig,
+  generateFigmaVariables,
+} from '../core/index.js';
+import type { DTCGTokenFile } from '../core/index.js';
+
+export interface TokensGenerateOptions {
+  /** Path to DTCG .tokens.json source file */
+  from: string;
+  /** Output formats (comma-separated: css, scss, tailwind, figma) */
+  format: string;
+  /** Output directory */
+  out?: string;
+  /** Token name prefix */
+  prefix?: string;
+  /** CSS selector for custom properties (default: ':root') */
+  selector?: string;
+  /** Verbose output */
+  verbose?: boolean;
+}
+
+type OutputFormat = 'css' | 'scss' | 'tailwind' | 'figma';
+
+const VALID_FORMATS = new Set<OutputFormat>(['css', 'scss', 'tailwind', 'figma']);
+
+export async function tokensGenerate(options: TokensGenerateOptions): Promise<void> {
+  const { from, format, out, prefix, selector, verbose } = options;
+
+  // Parse formats
+  const formats = format.split(',').map((f) => f.trim().toLowerCase()) as OutputFormat[];
+  const invalidFormats = formats.filter((f) => !VALID_FORMATS.has(f));
+  if (invalidFormats.length > 0) {
+    console.error(pc.red(`Invalid format(s): ${invalidFormats.join(', ')}`));
+    console.error(`Valid formats: ${[...VALID_FORMATS].join(', ')}`);
+    process.exit(1);
+  }
+
+  // Read source file
+  const sourcePath = resolve(process.cwd(), from);
+  let content: string;
+  try {
+    content = await readFile(sourcePath, 'utf-8');
+  } catch {
+    console.error(pc.red(`Could not read file: ${sourcePath}`));
+    process.exit(1);
+  }
+
+  let tokens: DTCGTokenFile;
+  try {
+    tokens = JSON.parse(content) as DTCGTokenFile;
+  } catch {
+    console.error(pc.red(`Invalid JSON in: ${sourcePath}`));
+    process.exit(1);
+  }
+
+  // Determine output directory
+  const outDir = out ? resolve(process.cwd(), out) : dirname(sourcePath);
+  await mkdir(outDir, { recursive: true });
+
+  const baseName = basename(from, extname(from)).replace(/\.tokens$/, '');
+
+  // Generate each format
+  for (const fmt of formats) {
+    let output: string;
+    let fileName: string;
+
+    switch (fmt) {
+      case 'css': {
+        output = generateCSSCustomProperties(tokens, { prefix, selector });
+        fileName = `${baseName}.css`;
+        break;
+      }
+      case 'scss': {
+        output = generateSCSSVariables(tokens, { prefix });
+        fileName = `_${baseName}.scss`;
+        break;
+      }
+      case 'tailwind': {
+        const config = generateTailwindConfig(tokens);
+        output = `// Auto-generated Tailwind config from DTCG tokens\n// Do not edit directly\nexport default ${JSON.stringify(config, null, 2)};\n`;
+        fileName = `tailwind.tokens.js`;
+        break;
+      }
+      case 'figma': {
+        const collections = generateFigmaVariables(tokens);
+        output = JSON.stringify(collections, null, 2);
+        fileName = `${baseName}.figma-variables.json`;
+        break;
+      }
+      default:
+        continue;
+    }
+
+    const outputPath = resolve(outDir, fileName);
+    await writeFile(outputPath, output, 'utf-8');
+
+    if (verbose) {
+      console.log(pc.green(`  ✓ ${fmt}`), pc.dim(outputPath));
+    }
+  }
+
+  console.log(pc.green(`Generated ${formats.length} output(s) from ${from}`));
+}

package/src/commands/verify.ts

@@ -6,7 +6,14 @@
  */
 
 import pc from 'picocolors';
-import { BRAND } from '../core/index.js';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  BRAND,
+  type CompiledFragment,
+  type CompiledFragmentsFile,
+} from '../core/index.js';
 import { loadConfig } from '../core/node.js';
 import {
   createDevServerClient,
@@ -86,6 +93,10 @@ export async function verify(
     console.log(pc.dim(`Minimum compliance: ${minCompliance}%\n`));
   }
 
+  if (ci) {
+    return verifyFromLocalFragments(configPath, minCompliance, component);
+  }
+
   // Check if dev server is reachable
   const isReachable = await client.ping();
   if (!isReachable) {
@@ -213,3 +224,186 @@ export async function verify(
 
   return summary;
 }
+
+/**
+ * Compute metadata completeness score for a compiled fragment.
+ *
+ * Scoring breakdown (max 100):
+ *  - Has description:                       +20
+ *  - Has category that isn't "Components":  +15
+ *  - Has when/whenNot usage guidelines:     +20
+ *  - Has props with types:                  +20
+ *  - Has variants:                          +15
+ *  - Has relations:                         +10
+ */
+function computeMetadataScore(fragment: CompiledFragment): {
+  score: number;
+  violations: ViolationItem[];
+} {
+  let score = 0;
+  const violations: ViolationItem[] = [];
+
+  // Description (+20)
+  if (fragment.meta.description && fragment.meta.description.trim().length > 0) {
+    score += 20;
+  } else {
+    violations.push({
+      property: 'meta.description',
+      issue: 'Missing component description',
+      severity: 'warning',
+      suggestion: 'Add a description to the fragment definition',
+    });
+  }
+
+  // Category that isn't the default "Components" (+15)
+  if (fragment.meta.category && fragment.meta.category !== 'Components') {
+    score += 15;
+  } else {
+    violations.push({
+      property: 'meta.category',
+      issue: fragment.meta.category === 'Components'
+        ? 'Using default category "Components"'
+        : 'Missing category',
+      severity: 'warning',
+      suggestion: 'Set a specific category (e.g., "forms", "layout", "feedback")',
+    });
+  }
+
+  // Usage guidelines — when/whenNot (+20)
+  const hasWhen = fragment.usage?.when && fragment.usage.when.length > 0;
+  const hasWhenNot = fragment.usage?.whenNot && fragment.usage.whenNot.length > 0;
+  if (hasWhen || hasWhenNot) {
+    score += 20;
+  } else {
+    violations.push({
+      property: 'usage.when / usage.whenNot',
+      issue: 'Missing usage guidelines',
+      severity: 'warning',
+      suggestion: 'Add when[] and whenNot[] arrays to describe appropriate usage',
+    });
+  }
+
+  // Props with types (+20)
+  const propKeys = Object.keys(fragment.props ?? {});
+  if (propKeys.length > 0) {
+    score += 20;
+  } else {
+    violations.push({
+      property: 'props',
+      issue: 'No props defined',
+      severity: 'warning',
+      suggestion: 'Define props with types in the fragment definition',
+    });
+  }
+
+  // Variants (+15)
+  if (fragment.variants && fragment.variants.length > 0) {
+    score += 15;
+  } else {
+    violations.push({
+      property: 'variants',
+      issue: 'No variants defined',
+      severity: 'warning',
+      suggestion: 'Add at least one variant showing component usage',
+    });
+  }
+
+  // Relations (+10)
+  if (fragment.relations && fragment.relations.length > 0) {
+    score += 10;
+  } else {
+    violations.push({
+      property: 'relations',
+      issue: 'No component relations defined',
+      severity: 'warning',
+      suggestion: 'Define relations to related components (parent, child, alternative)',
+    });
+  }
+
+  return { score, violations };
+}
+
+/**
+ * CI fallback: verify components from the local fragments.json file
+ * without requiring a running dev server.
+ */
+async function verifyFromLocalFragments(
+  configPath: string | undefined,
+  minCompliance: number,
+  component: string | undefined,
+): Promise<VerifySummary> {
+  // Load config to resolve outFile
+  const { config, configDir } = await loadConfig(configPath);
+  const outFile = config.outFile ?? 'fragments.json';
+  const fragmentsPath = resolve(configDir ?? process.cwd(), outFile);
+
+  if (!existsSync(fragmentsPath)) {
+    const error = {
+      error: `fragments.json not found at ${fragmentsPath}. Run "fragments build" first.`,
+    };
+    console.log(JSON.stringify(error));
+    process.exit(1);
+  }
+
+  const raw = await readFile(fragmentsPath, 'utf-8');
+  const data: CompiledFragmentsFile = JSON.parse(raw);
+
+  // Filter to only local fragments (skip anything from node_modules)
+  let entries = Object.entries(data.fragments).filter(
+    ([, frag]) => !frag.filePath.includes('node_modules')
+  );
+
+  // Filter by specific component if requested
+  if (component) {
+    entries = entries.filter(
+      ([name]) => name.toLowerCase() === component.toLowerCase()
+    );
+
+    if (entries.length === 0) {
+      const error = { error: `Component "${component}" not found in local fragments` };
+      console.log(JSON.stringify(error));
+      process.exit(1);
+    }
+  }
+
+  const results: VerifyResultItem[] = [];
+  let totalCompliance = 0;
+
+  for (const [name, fragment] of entries) {
+    const { score, violations } = computeMetadataScore(fragment);
+    const passed = score >= minCompliance;
+
+    results.push({
+      component: name,
+      compliance: score,
+      passed,
+      violations,
+      totalProperties: Object.keys(fragment.props ?? {}).length,
+      hardcoded: 0,
+      usingTokens: 0,
+    });
+
+    totalCompliance += score;
+  }
+
+  const componentCount = entries.length;
+  const averageCompliance = componentCount > 0 ? totalCompliance / componentCount : 100;
+  const allPassed = results.every(r => r.passed);
+
+  const summary: VerifySummary = {
+    passed: allPassed,
+    compliance: Math.round(averageCompliance * 100) / 100,
+    threshold: minCompliance,
+    totalComponents: componentCount,
+    passedComponents: results.filter(r => r.passed).length,
+    failedComponents: results.filter(r => !r.passed).length,
+    results,
+    violations: results.flatMap(r => r.violations.map(v => ({
+      component: r.component,
+      ...v,
+    }))),
+  };
+
+  console.log(JSON.stringify(summary, null, 2));
+  return summary;
+}

package/src/core/__fixtures__/shadcn-input/input.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+  return <input className={className} type={type} {...props} />;
+}
+
+export { Input };

package/src/core/__fixtures__/shadcn-input/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["react", "react-dom"]
+  },
+  "include": ["input.tsx"]
+}

package/src/core/__fixtures__/shadcn-label/label.tsx

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { Primitive } from './primitive';
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof Primitive.Root>) {
+  return <Primitive.Root data-class={className} {...props} />;
+}
+
+export { Label };

package/src/core/__fixtures__/shadcn-label/primitive.tsx

@@ -0,0 +1,14 @@
+import * as React from 'react';
+
+export interface PrimitiveLabelProps {
+  className?: string;
+  htmlFor?: string;
+  form?: string;
+  children?: React.ReactNode;
+}
+
+function Root(props: PrimitiveLabelProps) {
+  return <label {...props} />;
+}
+
+export const Primitive = { Root };

package/src/core/__fixtures__/shadcn-label/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["react", "react-dom"]
+  },
+  "include": ["*.tsx"]
+}

package/src/core/__fixtures__/shadcn-radix-label/label.tsx

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { Label as LabelPrimitive } from 'radix-ui';
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return <LabelPrimitive.Root data-class={className} {...props} />;
+}
+
+export { Label };

package/src/core/__fixtures__/shadcn-radix-label/node_modules/radix-ui/index.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+
+export interface LabelRootProps {
+  className?: string;
+  htmlFor?: string;
+  form?: string;
+  children?: React.ReactNode;
+}
+
+export const Label: {
+  Root: (props: LabelRootProps) => JSX.Element;
+};

package/src/core/__fixtures__/shadcn-radix-label/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["react", "react-dom"]
+  },
+  "include": ["*.tsx", "node_modules/**/*.d.ts"]
+}