@fragments-sdk/cli 0.7.0 → 0.7.2

package/src/build.ts

@@ -2,20 +2,20 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { existsSync } from "node:fs";
 import type {
-  SegmentsConfig,
-  CompiledSegmentsFile,
-  CompiledSegment,
+  FragmentsConfig,
+  CompiledFragmentsFile,
+  CompiledFragment,
   CompiledBlock,
   CompiledTokenData,
 } from "./core/index.js";
 import { BRAND, compileBlock, parseTokenFile } from "./core/index.js";
 import type { BlockDefinition } from "./core/index.js";
 import {
-  discoverSegmentFiles,
+  discoverFragmentFiles,
   discoverBlockFiles,
   discoverTokenFiles,
-  parseSegmentFile,
-  loadSegmentFile,
+  parseFragmentFile,
+  loadFragmentFile,
   generateRegistry,
   generateContextMd,
 } from "./core/node.js";
@@ -27,7 +27,7 @@ import {
 import { buildComponentGraph } from "./core/graph-extractor.js";
 import { serializeGraph } from "@fragments-sdk/context/graph";
 
-type CompiledProp = CompiledSegment["props"][string];
+type CompiledProp = CompiledFragment["props"][string];
 
 function normalizeParsedProps(
   parsedProps: Record<string, Partial<CompiledProp>>
@@ -74,7 +74,7 @@ function mergeDocumentedAndAutoProps(
 export interface BuildResult {
   success: boolean;
   outputPath: string;
-  segmentCount: number;
+  fragmentCount: number;
   errors: Array<{ file: string; error: string }>;
   warnings: Array<{ file: string; warning: string }>;
 }
@@ -85,14 +85,14 @@ export interface BuildResult {
  * Uses AST parsing to extract metadata WITHOUT executing fragment files.
  * This means the build works without any project dependencies installed.
  */
-export async function buildSegments(
-  config: SegmentsConfig,
+export async function buildFragments(
+  config: FragmentsConfig,
   configDir: string
 ): Promise<BuildResult> {
-  const files = await discoverSegmentFiles(config, configDir);
+  const files = await discoverFragmentFiles(config, configDir);
   const errors: Array<{ file: string; error: string }> = [];
   const warnings: Array<{ file: string; warning: string }> = [];
-  const segments: CompiledSegmentsFile["segments"] = {};
+  const fragments: CompiledFragmentsFile["fragments"] = {};
 
   for (const file of files) {
     try {
@@ -100,7 +100,7 @@ export async function buildSegments(
       const content = await readFile(file.absolutePath, "utf-8");
 
       // Parse using AST (no execution)
-      const parsed = parseSegmentFile(content, file.relativePath);
+      const parsed = parseFragmentFile(content, file.relativePath);
 
       // Collect warnings
       for (const warning of parsed.warnings) {
@@ -171,7 +171,7 @@ export async function buildSegments(
       }
 
       // Build compiled fragment from parsed metadata
-      const compiled: CompiledSegment = {
+      const compiled: CompiledFragment = {
         filePath: file.relativePath,
         meta: {
           name: parsed.meta.name,
@@ -208,9 +208,11 @@ export async function buildSegments(
         })),
         // Include AI metadata if present
         ...(parsed.ai && { ai: parsed.ai }),
+        // Include contract metadata if present
+        ...(parsed.contract && { contract: parsed.contract }),
       };
 
-      segments[parsed.meta.name] = compiled;
+      fragments[parsed.meta.name] = compiled;
     } catch (error) {
       errors.push({
         file: file.relativePath,
@@ -225,9 +227,9 @@ export async function buildSegments(
     const blockFiles = await discoverBlockFiles(configDir, config.exclude);
     for (const file of blockFiles) {
       try {
-        // loadSegmentFile uses esbuild to bundle+evaluate, returns default export
+        // loadFragmentFile uses esbuild to bundle+evaluate, returns default export
         // CJS/ESM interop may double-wrap the default export
-        let raw = await loadSegmentFile(file.absolutePath) as unknown as Record<string, unknown> | null;
+        let raw = await loadFragmentFile(file.absolutePath) as unknown as Record<string, unknown> | null;
         // Unwrap double-default from CJS interop
         if (raw && 'default' in raw && typeof raw.default === 'object') {
           raw = raw.default as Record<string, unknown>;
@@ -255,7 +257,7 @@ export async function buildSegments(
     const tokenFiles = await discoverTokenFiles(configDir, tokenPatterns, config.exclude);
     if (tokenFiles.length > 0) {
       // Merge tokens from all discovered files
-      const mergedCategories: Record<string, Array<{ name: string; description?: string }>> = {};
+      const mergedCategories: Record<string, Array<{ name: string; value?: string; description?: string }>> = {};
       let prefix = '--';
       let total = 0;
 
@@ -271,7 +273,7 @@ export async function buildSegments(
           for (const t of catTokens) {
             // Deduplicate by name
             if (!mergedCategories[cat].some((e) => e.name === t.name)) {
-              mergedCategories[cat].push({ name: t.name, description: t.description });
+              mergedCategories[cat].push({ name: t.name, ...(t.value && { value: t.value }), description: t.description });
             }
           }
         }
@@ -302,25 +304,25 @@ export async function buildSegments(
   const componentDir = resolve(configDir, "src", "components");
   let graphData: ReturnType<typeof serializeGraph> | undefined;
   try {
-    const graphResult = await buildComponentGraph(segments, blocks, componentDir);
+    const graphResult = await buildComponentGraph(fragments, blocks, componentDir);
 
-    // Auto-enrich segments with detected metadata
-    for (const [name, segment] of Object.entries(segments)) {
+    // Auto-enrich fragments with detected metadata
+    for (const [name, fragment] of Object.entries(fragments)) {
       const detected = graphResult.autoDetected.get(name);
       if (!detected) continue;
 
-      if (!segment.ai) segment.ai = {};
-      if (!segment.ai.subComponents && detected.subComponents) {
-        segment.ai.subComponents = detected.subComponents;
+      if (!fragment.ai) fragment.ai = {};
+      if (!fragment.ai.subComponents && detected.subComponents) {
+        fragment.ai.subComponents = detected.subComponents;
       }
-      if (!segment.ai.compositionPattern && detected.compositionPattern) {
-        segment.ai.compositionPattern = detected.compositionPattern;
+      if (!fragment.ai.compositionPattern && detected.compositionPattern) {
+        fragment.ai.compositionPattern = detected.compositionPattern;
       }
-      if (!segment.ai.commonPatterns && detected.commonPatterns) {
-        segment.ai.commonPatterns = detected.commonPatterns;
+      if (!fragment.ai.commonPatterns && detected.commonPatterns) {
+        fragment.ai.commonPatterns = detected.commonPatterns;
       }
-      if (!segment.ai.requiredChildren && detected.requiredChildren) {
-        segment.ai.requiredChildren = detected.requiredChildren;
+      if (!fragment.ai.requiredChildren && detected.requiredChildren) {
+        fragment.ai.requiredChildren = detected.requiredChildren;
       }
     }
 
@@ -337,11 +339,11 @@ export async function buildSegments(
     });
   }
 
-  const output: CompiledSegmentsFile = {
+  const output: CompiledFragmentsFile = {
     version: "1.0.0",
     generatedAt: new Date().toISOString(),
     ...(packageName && { packageName }),
-    segments,
+    fragments,
     ...(Object.keys(blocks).length > 0 && { blocks }),
     ...(tokens && { tokens }),
     ...(graphData && { graph: graphData }),
@@ -353,7 +355,7 @@ export async function buildSegments(
   return {
     success: errors.length === 0,
     outputPath,
-    segmentCount: Object.keys(segments).length,
+    fragmentCount: Object.keys(fragments).length,
     errors,
     warnings,
   };
@@ -381,7 +383,7 @@ export interface FragmentsBuildResult {
  * - .fragments/context.md - AI-ready consolidated context file
  */
 export async function buildFragmentsDir(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string
 ): Promise<FragmentsBuildResult> {
   const fragmentsDir = join(configDir, BRAND.dataDir);

package/src/commands/a11y.ts

@@ -229,10 +229,10 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
     );
   }
 
-  // Fetch all segments
-  const segments = await client.getSegments();
+  // Fetch all fragments
+  const fragments = await client.getFragments();
 
-  if (segments.length === 0) {
+  if (fragments.length === 0) {
     if (isJsonOutput) {
       console.log(JSON.stringify({ error: 'No fragments found', components: [] }));
     } else {
@@ -254,11 +254,11 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
 
   // Filter to specific component if requested
   const componentsToCheck = component
-    ? segments.filter(s => s.name.toLowerCase() === component.toLowerCase())
-    : segments;
+    ? fragments.filter(s => s.name.toLowerCase() === component.toLowerCase())
+    : fragments;
 
   if (component && componentsToCheck.length === 0) {
-    const error = `Component '${component}' not found. Available: ${segments.map(s => s.name).join(', ')}`;
+    const error = `Component '${component}' not found. Available: ${fragments.map(s => s.name).join(', ')}`;
     if (isJsonOutput) {
       console.log(JSON.stringify({ error }));
     } else {

package/src/commands/add.ts

@@ -27,7 +27,7 @@ export interface AddOptions {
 export interface AddResult {
   success: boolean;
   componentPath?: string;
-  segmentPath: string;
+  fragmentPath: string;
   indexPath?: string;
 }
 
@@ -110,7 +110,7 @@ export async function add(
   // Determine output paths
   const componentDir = resolve(process.cwd(), dir, componentName);
   const componentFile = join(componentDir, `${componentName}.tsx`);
-  const segmentFile = join(componentDir, `${componentName}${BRAND.fileExtension}`);
+  const fragmentFile = join(componentDir, `${componentName}${BRAND.fileExtension}`);
   const indexFile = join(componentDir, 'index.ts');
 
   // Check if directory already exists
@@ -133,10 +133,10 @@ export async function add(
     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 fragment file
+  const fragmentCode = generateFragmentStub(componentName, category, template);
+  await writeFile(fragmentFile, fragmentCode);
+  console.log(`${pc.green('✓')} Created ${relative(process.cwd(), fragmentFile)}`);
 
   // Generate index.ts
   const indexCode = `export { ${componentName} } from './${componentName}.js';\n`;
@@ -159,7 +159,7 @@ export async function add(
   return {
     success: true,
     componentPath: generateComponent ? componentFile : undefined,
-    segmentPath: segmentFile,
+    fragmentPath: fragmentFile,
     indexPath: indexFile,
   };
 }
@@ -195,9 +195,9 @@ export function ${name}({ children, className }: ${name}Props) {
 }
 
 /**
- * Generate a segment stub based on template type.
+ * Generate a fragment stub based on template type.
  */
-function generateSegmentStub(name: string, category: string, template: string): string {
+function generateFragmentStub(name: string, category: string, template: string): string {
   // Template-specific usage hints
   const usageHints: Record<string, { when: string[]; whenNot: string[] }> = {
     action: {
@@ -231,10 +231,10 @@ function generateSegmentStub(name: string, category: string, template: string):
   const scenarioTags = scenarioTagHints[template] || scenarioTagHints.display;
 
   return `import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { ${name} } from './index.js';
 
-export default defineSegment({
+export default defineFragment({
   component: ${name},
 
   meta: {

package/src/commands/audit.ts

@@ -69,9 +69,9 @@ export async function audit(options: AuditOptions = {}): Promise<AuditSummary> {
   }
 
   // Fetch all fragments
-  const segments = await client.getSegments();
+  const fragments = await client.getFragments();
 
-  if (segments.length === 0) {
+  if (fragments.length === 0) {
     if (json) {
       console.log(JSON.stringify({ error: 'No fragments found', components: [] }));
     } else {
@@ -91,11 +91,11 @@ export async function audit(options: AuditOptions = {}): Promise<AuditSummary> {
   }
 
   if (!json) {
-    console.log(pc.dim(`Auditing ${segments.length} component(s)...\n`));
+    console.log(pc.dim(`Auditing ${fragments.length} component(s)...\n`));
   }
 
   // Audit each fragment
-  for (const seg of segments) {
+  for (const seg of fragments) {
     try {
       // Get real compliance from the server
       const complianceResult = await client.getCompliance({

package/src/commands/baseline.ts

@@ -98,16 +98,16 @@ async function updateBaseline(
     }
 
     const contextData = JSON.parse(await contextResp.text());
-    const segments = contextData.components || [];
+    const fragments = contextData.components || [];
 
-    if (segments.length === 0) {
+    if (fragments.length === 0) {
       console.log(pc.yellow('No components found.\n'));
       return { success: true, action: 'update', count: 0 };
     }
 
     component = await select({
       message: 'Select component to update:',
-      choices: segments.map((s: { name: string }) => ({
+      choices: fragments.map((s: { name: string }) => ({
         name: s.name,
         value: s.name,
       })),

package/src/commands/build.ts

@@ -5,7 +5,7 @@
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
-import { buildSegments, buildFragmentsDir } from '../build.js';
+import { buildFragments, buildFragmentsDir } from '../build.js';
 import { scan } from './scan.js';
 
 /**
@@ -35,7 +35,7 @@ export interface BuildOptions {
  */
 export interface BuildResult {
   success: boolean;
-  segmentCount?: number;
+  fragmentCount?: number;
   outputPath?: string;
   componentCount?: number;
   registryPath?: string;
@@ -65,7 +65,7 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
 
     return {
       success: scanResult.success,
-      segmentCount: scanResult.componentCount,
+      fragmentCount: scanResult.componentCount,
       outputPath: scanResult.outputPath,
       errors: scanResult.errors.map((e) => ({ file: e.component, error: e.error })),
     };
@@ -80,7 +80,7 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
   console.log(pc.cyan(`\n${BRAND.name} Build\n`));
 
   const errors: Array<{ file: string; error: string }> = [];
-  let segmentCount: number | undefined;
+  let fragmentCount: number | undefined;
   let outputPath: string | undefined;
   let componentCount: number | undefined;
   let registryPath: string | undefined;
@@ -90,7 +90,7 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
   if (!options.registryOnly) {
     console.log(pc.dim('Compiling fragments...\n'));
 
-    const result = await buildSegments(config, configDir);
+    const result = await buildFragments(config, configDir);
 
     if (result.errors.length > 0) {
       console.log(pc.yellow('Build completed with errors:\n'));
@@ -109,10 +109,10 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
       console.log();
     }
 
-    segmentCount = result.segmentCount;
+    fragmentCount = result.fragmentCount;
     outputPath = result.outputPath;
 
-    console.log(pc.green(`✓ Built ${result.segmentCount} fragment(s)`));
+    console.log(pc.green(`✓ Built ${result.fragmentCount} fragment(s)`));
     console.log(pc.dim(`  Output: ${result.outputPath}\n`));
   }
 
@@ -150,7 +150,7 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
 
   return {
     success: errors.length === 0,
-    segmentCount,
+    fragmentCount,
     outputPath,
     componentCount,
     registryPath,

package/src/commands/compare.ts

@@ -15,7 +15,7 @@ export interface CompareOptions {
   config?: string;
   /** Compare specific variant */
   variant?: string;
-  /** Figma frame URL (uses segment figma link if not provided) */
+  /** Figma frame URL (uses fragment figma link if not provided) */
   figma?: string;
   /** Diff threshold percentage */
   threshold?: number;
@@ -112,7 +112,7 @@ export async function compare(
   let failed = 0;
 
   for (const comp of componentsToCompare) {
-    const response = await fetch(`${baseUrl}/segments/compare`, {
+    const response = await fetch(`${baseUrl}/fragments/compare`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
@@ -177,24 +177,24 @@ async function compareAll(
 ): Promise<CompareCommandResult> {
   console.log(pc.dim('Comparing all components with Figma links...\n'));
 
-  // Fetch the context to get all segments
-  const contextResp = await fetch(`${baseUrl}/segments/context?format=json`);
+  // Fetch the context to get all fragments
+  const contextResp = await fetch(`${baseUrl}/fragments/context?format=json`);
   if (!contextResp.ok) {
-    throw new Error('Failed to fetch segments. Make sure dev server is running.');
+    throw new Error('Failed to fetch fragments. Make sure dev server is running.');
   }
 
   const contextText = await contextResp.text();
-  let segments: Array<{ name: string; figma?: string }> = [];
+  let fragments: Array<{ name: string; figma?: string }> = [];
   try {
     const contextData = JSON.parse(contextText);
-    segments = contextData.components || [];
+    fragments = contextData.components || [];
   } catch {
-    segments = [];
+    fragments = [];
   }
 
-  if (segments.length === 0) {
+  if (fragments.length === 0) {
     console.log(pc.yellow('No components found with Figma links.'));
-    console.log(pc.dim('Add figma field to your segment definitions:'));
+    console.log(pc.dim('Add figma field to your fragment definitions:'));
     console.log(pc.dim('  meta: { figma: "https://figma.com/file/..." }'));
     return { success: true, passed: 0, failed: 0, skipped: 0 };
   }
@@ -203,7 +203,7 @@ async function compareAll(
   let failed = 0;
   let skipped = 0;
 
-  for (const seg of segments) {
+  for (const seg of fragments) {
     // Skip components without figma links
     if (!seg.figma) {
       skipped++;
@@ -212,7 +212,7 @@ async function compareAll(
     }
 
     try {
-      const response = await fetch(`${baseUrl}/segments/compare`, {
+      const response = await fetch(`${baseUrl}/fragments/compare`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -267,23 +267,23 @@ async function compareAll(
 async function selectComponents(baseUrl: string): Promise<string[]> {
   console.log(pc.dim('Fetching components with Figma links...\n'));
 
-  const contextResp = await fetch(`${baseUrl}/segments/context?format=json`);
+  const contextResp = await fetch(`${baseUrl}/fragments/context?format=json`);
   if (!contextResp.ok) {
-    throw new Error('Failed to fetch segments. Make sure dev server is running.');
+    throw new Error('Failed to fetch fragments. Make sure dev server is running.');
   }
 
   const contextText = await contextResp.text();
-  let segments: Array<{ name: string; figma?: string }> = [];
+  let fragments: Array<{ name: string; figma?: string }> = [];
   try {
     const contextData = JSON.parse(contextText);
-    segments = (contextData.components || []).filter((s: { figma?: string }) => s.figma);
+    fragments = (contextData.components || []).filter((s: { figma?: string }) => s.figma);
   } catch {
-    segments = [];
+    fragments = [];
   }
 
-  if (segments.length === 0) {
+  if (fragments.length === 0) {
     console.log(pc.yellow('No components found with Figma links.'));
-    console.log(pc.dim('Add figma field to your segment definitions:'));
+    console.log(pc.dim('Add figma field to your fragment definitions:'));
     console.log(pc.dim('  meta: { figma: "https://figma.com/file/..." }'));
     return [];
   }
@@ -291,7 +291,7 @@ async function selectComponents(baseUrl: string): Promise<string[]> {
   const { checkbox } = await import('@inquirer/prompts');
 
   try {
-    const choices = segments.map((seg) => ({
+    const choices = fragments.map((seg) => ({
       name: seg.name,
       value: seg.name,
       checked: true,

package/src/commands/context.ts

@@ -6,9 +6,9 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import pc from 'picocolors';
 import { generateContext } from '../core/index.js';
-import type { CompiledSegment, CompiledSegmentsFile } from '../core/index.js';
+import type { CompiledFragment, CompiledFragmentsFile } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
-import { buildSegments } from '../build.js';
+import { buildFragments } from '../build.js';
 
 /**
  * Options for context command
@@ -16,7 +16,7 @@ import { buildSegments } from '../build.js';
 export interface ContextOptions {
   /** Path to config file */
   config?: string;
-  /** Path to segments.json (builds if not provided) */
+  /** Path to fragments.json (builds if not provided) */
   input?: string;
   /** Output format (markdown/json) */
   format?: 'markdown' | 'json';
@@ -51,36 +51,36 @@ export async function context(options: ContextOptions = {}): Promise<ContextResu
     tokensOnly = false,
   } = options;
 
-  let segments: CompiledSegment[];
+  let fragments: CompiledFragment[];
 
   if (options.input) {
-    // Read from existing segments.json
+    // Read from existing fragments.json
     const inputPath = resolve(process.cwd(), options.input);
     const content = await readFile(inputPath, 'utf-8');
-    const data: CompiledSegmentsFile = JSON.parse(content);
-    segments = Object.values(data.segments);
+    const data: CompiledFragmentsFile = JSON.parse(content);
+    fragments = Object.values(data.fragments);
   } else {
-    // Build segments on the fly
+    // Build fragments on the fly
     const { config, configDir } = await loadConfig(options.config);
-    const result = await buildSegments(config, configDir);
+    const result = await buildFragments(config, configDir);
 
-    if (result.errors.length > 0 && result.segmentCount === 0) {
-      console.error(pc.red('Error: No segments found. Run `segments build` first or fix errors.'));
+    if (result.errors.length > 0 && result.fragmentCount === 0) {
+      console.error(pc.red('Error: No fragments found. Run `fragments build` first or fix errors.'));
       return { success: false, tokenEstimate: 0 };
     }
 
     // Read the generated file
     const content = await readFile(result.outputPath, 'utf-8');
-    const data: CompiledSegmentsFile = JSON.parse(content);
-    segments = Object.values(data.segments);
+    const data: CompiledFragmentsFile = JSON.parse(content);
+    fragments = Object.values(data.fragments);
   }
 
-  if (segments.length === 0) {
-    console.error(pc.red('No segments found.'));
+  if (fragments.length === 0) {
+    console.error(pc.red('No fragments found.'));
     return { success: false, tokenEstimate: 0 };
   }
 
-  const { content, tokenEstimate } = generateContext(segments, {
+  const { content, tokenEstimate } = generateContext(fragments, {
     format,
     compact,
     include: {