@fragments-sdk/cli 0.7.0 → 0.7.1

package/src/commands/link/index.ts

@@ -1,9 +1,9 @@
 /**
- * fragments link - Link external resources to segments
+ * fragments link - Link external resources to fragments
  *
  * This module provides subcommands for:
- * - figma: Link Figma components to segments
- * - storybook: Bootstrap segments from Storybook stories
+ * - figma: Link Figma components to fragments
+ * - storybook: Bootstrap fragments from Storybook stories
  */
 
 export { linkFigma, type LinkFigmaOptions, type LinkFigmaResult } from './figma.js';

package/src/commands/link/storybook.ts

@@ -1,5 +1,5 @@
 /**
- * fragments link storybook - Bootstrap segments from Storybook stories
+ * fragments link storybook - Bootstrap fragments from Storybook stories
  */
 
 import { writeFile, mkdir } from 'node:fs/promises';
@@ -10,7 +10,7 @@ import {
   detectStorybookConfig,
   discoverStoryFiles as discoverStorybookFiles,
   parseStoryFile,
-  convertToSegment,
+  convertToFragment,
 } from '../../migrate/index.js';
 
 /**
@@ -19,7 +19,7 @@ import {
 export interface LinkStorybookOptions {
   /** Path to .storybook/main.* config */
   config?: string;
-  /** Output directory for segment files */
+  /** Output directory for fragment files */
   out?: string;
   /** Skip confirmation prompts */
   yes?: boolean;
@@ -114,7 +114,7 @@ export async function linkStorybook(
 
     try {
       const parsed = await parseStoryFile(storyFile);
-      const result = convertToSegment(parsed);
+      const result = convertToFragment(parsed);
 
       // Determine output path
       const outputFile = out
@@ -177,7 +177,7 @@ export async function linkStorybook(
 
   // Dry run stops here
   if (dryRun) {
-    console.log(pc.dim(`\n${previews.length} segment file(s) would be created`));
+    console.log(pc.dim(`\n${previews.length} fragment file(s) would be created`));
     console.log(pc.yellow('\n[Dry run - no files were written]'));
     return { success: true, generated: 0 };
   }
@@ -186,7 +186,7 @@ export async function linkStorybook(
   let selectedPreviews = previews;
 
   if (yes) {
-    console.log(pc.dim(`\n${previews.length} segment file(s) will be created`));
+    console.log(pc.dim(`\n${previews.length} fragment file(s) will be created`));
   } else {
     const { checkbox } = await import('@inquirer/prompts');
 
@@ -222,7 +222,7 @@ export async function linkStorybook(
 
   // Generate files
   const genTotal = selectedPreviews.length;
-  console.log(pc.dim(`\nGenerating ${genTotal} segment file(s)...\n`));
+  console.log(pc.dim(`\nGenerating ${genTotal} fragment file(s)...\n`));
 
   let generated = 0;
   let genErrors = 0;
@@ -231,7 +231,7 @@ export async function linkStorybook(
     const storyFile = join(projectRoot, preview.sourceFile);
     try {
       const parsed = await parseStoryFile(storyFile);
-      const result = convertToSegment(parsed);
+      const result = convertToFragment(parsed);
 
       // Determine output path
       const outputFile = out
@@ -252,7 +252,7 @@ export async function linkStorybook(
     }
   }
 
-  console.log(pc.green(`\n✓ Generated ${generated} segment file(s)\n`));
+  console.log(pc.green(`\n✓ Generated ${generated} fragment file(s)\n`));
 
   // Next steps
   console.log(pc.dim('───────────────────────────────────────'));

package/src/commands/list.ts

@@ -4,7 +4,7 @@
 
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
-import { loadConfig, discoverSegmentFiles } from '../core/node.js';
+import { loadConfig, discoverFragmentFiles } from '../core/node.js';
 
 /**
  * Options for list command
@@ -30,7 +30,7 @@ export interface ListResult {
  */
 export async function list(options: ListOptions = {}): Promise<ListResult> {
   const { config, configDir } = await loadConfig(options.config);
-  const files = await discoverSegmentFiles(config, configDir);
+  const files = await discoverFragmentFiles(config, configDir);
 
   console.log(pc.cyan(`\n${BRAND.name} - Discovered Fragments\n`));
 

package/src/commands/reset.ts

@@ -42,7 +42,7 @@ export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
   const filesToDelete: string[] = [];
   const dirsToDelete: string[] = [];
 
-  // Check data directory (.segments/)
+  // Check data directory (.fragments/)
   const dataDir = join(projectRoot, BRAND.dataDir);
   try {
     const dataDirStat = await stat(dataDir);
@@ -53,8 +53,8 @@ export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
     // Directory doesn't exist
   }
 
-  // Check for segments.json (default output file)
-  const defaultOutFile = join(projectRoot, 'segments.json');
+  // Check for fragments.json (default output file)
+  const defaultOutFile = join(projectRoot, 'fragments.json');
   try {
     const fileStat = await stat(defaultOutFile);
     if (fileStat.isFile()) {
@@ -65,10 +65,10 @@ export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
   }
 
   // Try to load config for custom outFile and include patterns
-  let segmentPatterns = [`**/*${BRAND.fileExtension}`];
+  let fragmentPatterns = [`**/*${BRAND.fileExtension}`];
   try {
     const { config } = await loadConfig();
-    if (config.outFile && config.outFile !== 'segments.json') {
+    if (config.outFile && config.outFile !== 'fragments.json') {
       const customOutFile = join(projectRoot, config.outFile);
       try {
         const fileStat = await stat(customOutFile);
@@ -81,15 +81,15 @@ export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
     }
     // Use config include patterns if available
     if (config.include && config.include.length > 0) {
-      segmentPatterns = config.include;
+      fragmentPatterns = config.include;
     }
   } catch {
     // No config file, use defaults
   }
 
-  // Find all segment files (*.segment.tsx)
+  // Find all fragment files (*.fragment.tsx)
   console.log(pc.dim('Scanning for generated files...\n'));
-  for (const pattern of segmentPatterns) {
+  for (const pattern of fragmentPatterns) {
     const matches = await fg(pattern, {
       cwd: projectRoot,
       ignore: ['**/node_modules/**'],
@@ -130,23 +130,23 @@ export async function reset(options: ResetOptions = {}): Promise<ResetResult> {
   }
 
   // Group files by type for cleaner output
-  const segmentFiles = filesToDelete.filter((f) => f.endsWith(BRAND.fileExtension));
+  const fragmentFiles = filesToDelete.filter((f) => f.endsWith(BRAND.fileExtension));
   const mdxFilesFound = filesToDelete.filter((f) => f.endsWith('.mdx'));
   const otherFiles = filesToDelete.filter(
     (f) => !f.endsWith(BRAND.fileExtension) && !f.endsWith('.mdx')
   );
 
-  if (segmentFiles.length > 0) {
-    console.log(`  📄 ${segmentFiles.length} segment file(s) (*${BRAND.fileExtension})`);
-    if (segmentFiles.length <= 5) {
-      for (const f of segmentFiles) {
+  if (fragmentFiles.length > 0) {
+    console.log(`  📄 ${fragmentFiles.length} fragment file(s) (*${BRAND.fileExtension})`);
+    if (fragmentFiles.length <= 5) {
+      for (const f of fragmentFiles) {
         console.log(pc.dim(`     ${relative(projectRoot, f)}`));
       }
     } else {
-      for (const f of segmentFiles.slice(0, 3)) {
+      for (const f of fragmentFiles.slice(0, 3)) {
         console.log(pc.dim(`     ${relative(projectRoot, f)}`));
       }
-      console.log(pc.dim(`     ... and ${segmentFiles.length - 3} more`));
+      console.log(pc.dim(`     ... and ${fragmentFiles.length - 3} more`));
     }
   }
 

package/src/commands/scan.ts

@@ -1,5 +1,5 @@
 /**
- * fragments scan - Zero-config segments.json generation from source code
+ * fragments scan - Zero-config fragments.json generation from source code
  *
  * Automatically extracts component documentation by:
  * 1. Discovering components from source files and barrel exports
@@ -7,7 +7,7 @@
  * 3. Scanning codebase for usage patterns
  * 4. Parsing Storybook stories for examples
  * 5. Inferring component relationships from usage data
- * 6. Generating complete segments.json without manual documentation
+ * 6. Generating complete fragments.json without manual documentation
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
@@ -15,8 +15,8 @@ import { resolve, join, dirname, relative } from "node:path";
 import pc from "picocolors";
 import {
   BRAND,
-  type CompiledSegmentsFile,
-  type CompiledSegment,
+  type CompiledFragmentsFile,
+  type CompiledFragment,
   type PropDefinition,
 } from "../core/index.js";
 import {
@@ -32,7 +32,7 @@ import {
   generateComponentContext,
   generateEnhancementSuggestions,
   filterBoilerplate,
-  convertToSegmentProps,
+  convertToFragmentProps,
   type UsageAnalysis,
   type ComponentRelation,
   type PropsExtractionResult,
@@ -42,7 +42,7 @@ import {
 export interface ScanOptions {
   /** Path to config file */
   config?: string;
-  /** Output file path (default: segments.json) */
+  /** Output file path (default: fragments.json) */
   output?: string;
   /** Component patterns to scan */
   componentPatterns?: string[];
@@ -71,7 +71,7 @@ export interface ScanResult {
 }
 
 /**
- * Scan codebase and generate segments.json directly from source
+ * Scan codebase and generate fragments.json directly from source
  */
 export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   const startTime = Date.now();
@@ -86,17 +86,17 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   try {
     const loaded = await loadConfig(options.config);
     configDir = loaded.configDir;
-    outputFile = options.output || loaded.config.outFile || "segments.json";
+    outputFile = options.output || loaded.config.outFile || "fragments.json";
     componentPatterns = options.componentPatterns || loaded.config.components;
   } catch {
     // No config file, use defaults
     configDir = process.cwd();
-    outputFile = options.output || "segments.json";
+    outputFile = options.output || "fragments.json";
     componentPatterns = options.componentPatterns;
   }
 
   console.log(pc.cyan(`\n${BRAND.name} Scan\n`));
-  console.log(pc.dim("Zero-config segments.json generation from source code\n"));
+  console.log(pc.dim("Zero-config fragments.json generation from source code\n"));
 
   // Phase 1: Discover components
   console.log(pc.dim("Phase 1: Discovering components..."));
@@ -133,7 +133,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 
   // Phase 2: Extract props from TypeScript
   console.log(pc.dim("\nPhase 2: Extracting props from TypeScript..."));
-  const propsMap = new Map<string, ReturnType<typeof convertToSegmentProps>>();
+  const propsMap = new Map<string, ReturnType<typeof convertToFragmentProps>>();
   const propsResults = new Map<string, PropsExtractionResult>();
   let propsExtracted = 0;
 
@@ -146,7 +146,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
       propsResults.set(comp.name, extraction);
 
       if (extraction.success && extraction.props.length > 0) {
-        propsMap.set(comp.name, convertToSegmentProps(extraction.props));
+        propsMap.set(comp.name, convertToFragmentProps(extraction.props));
         propsExtracted++;
       }
     } catch (e) {
@@ -238,13 +238,13 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
     console.log(pc.dim("\nPhase 4: Skipping Storybook parsing"));
   }
 
-  // Phase 5: Generate segments
-  console.log(pc.dim("\nPhase 5: Generating segments..."));
-  const segments: Record<string, CompiledSegment> = {};
+  // Phase 5: Generate fragments
+  console.log(pc.dim("\nPhase 5: Generating fragments..."));
+  const fragments: Record<string, CompiledFragment> = {};
 
   for (const comp of components) {
     try {
-      const segment = generateSegmentFromData(
+      const fragment = generateFragmentFromData(
         comp,
         configDir,
         propsMap.get(comp.name),
@@ -253,7 +253,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
         storiesMap.get(comp.name)
       );
 
-      segments[comp.name] = segment;
+      fragments[comp.name] = fragment;
     } catch (e) {
       errors.push({
         component: comp.name,
@@ -266,10 +266,10 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   const outputPath = resolve(configDir, outputFile);
   await mkdir(dirname(outputPath), { recursive: true });
 
-  const output: CompiledSegmentsFile = {
+  const output: CompiledFragmentsFile = {
     version: "1.0.0",
     generatedAt: new Date().toISOString(),
-    segments,
+    fragments,
   };
 
   await writeFile(outputPath, JSON.stringify(output, null, 2));
@@ -278,9 +278,9 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 
   // Summary
   console.log(pc.dim("\n────────────────────────────────────────"));
-  console.log(pc.green(`\n✓ Generated segments.json in ${elapsed}s`));
+  console.log(pc.green(`\n✓ Generated fragments.json in ${elapsed}s`));
   console.log(pc.dim(`  Output: ${relative(process.cwd(), outputPath)}`));
-  console.log(pc.dim(`  Components: ${Object.keys(segments).length}`));
+  console.log(pc.dim(`  Components: ${Object.keys(fragments).length}`));
   console.log(pc.dim(`  Props extracted: ${propsExtracted}`));
   console.log(pc.dim(`  Usages found: ${usagesFound}`));
   console.log(pc.dim(`  Relations inferred: ${allRelations.size}`));
@@ -307,7 +307,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   return {
     success: errors.length === 0,
     outputPath,
-    componentCount: Object.keys(segments).length,
+    componentCount: Object.keys(fragments).length,
     propsExtracted,
     usagesFound,
     relationsInferred: allRelations.size,
@@ -318,16 +318,16 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 }
 
 /**
- * Generate a CompiledSegment from extracted data
+ * Generate a CompiledFragment from extracted data
  */
-function generateSegmentFromData(
+function generateFragmentFromData(
   comp: DiscoveredComponent,
   configDir: string,
   props: Record<string, PropDefinition> | undefined,
   usageAnalysis: UsageAnalysis["components"][string] | undefined,
   relations: ComponentRelation[] | undefined,
   storyFile: ParsedStoryFile | undefined
-): CompiledSegment {
+): CompiledFragment {
   // Generate context for AI suggestions
   const context = generateComponentContext(
     comp.name,
@@ -352,7 +352,7 @@ function generateSegmentFromData(
   const status = inferStatus(comp.relativePath);
 
   // Build variants from stories
-  const variants: CompiledSegment["variants"] = [];
+  const variants: CompiledFragment["variants"] = [];
   if (storyFile?.stories) {
     for (const story of storyFile.stories) {
       variants.push({
@@ -364,7 +364,7 @@ function generateSegmentFromData(
   }
 
   // Build relations
-  const compiledRelations: CompiledSegment["relations"] = [];
+  const compiledRelations: CompiledFragment["relations"] = [];
   if (relations && relations.length > 0) {
     for (const rel of relations.slice(0, 10)) {
       compiledRelations.push({

package/src/commands/storygen.ts

@@ -1,13 +1,13 @@
 /**
- * fragments storygen - Generate Storybook stories from segment definitions
+ * fragments storygen - Generate Storybook stories from fragment 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';
+import type { FragmentDefinition } from '../core/index.js';
+import { loadConfig, discoverFragmentFiles, loadFragmentFile } from '../core/node.js';
 
 /**
  * Options for storygen command
@@ -17,7 +17,7 @@ export interface StorygenOptions {
   config?: string;
   /** Output directory */
   output?: string;
-  /** Watch for segment changes and regenerate */
+  /** Watch for fragment changes and regenerate */
   watch?: boolean;
   /** Story format (csf3) */
   format?: string;
@@ -42,11 +42,11 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 
   console.log(pc.cyan(`\n${BRAND.name} Story Generator\n`));
 
-  // Discover segment files
-  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  // Discover fragment files
+  const fragmentFiles = await discoverFragmentFiles(config, configDir);
 
-  if (segmentFiles.length === 0) {
-    console.log(pc.yellow('No segment files found.\n'));
+  if (fragmentFiles.length === 0) {
+    console.log(pc.yellow('No fragment files found.\n'));
     return { success: true, generated: 0, outputDir: output };
   }
 
@@ -55,14 +55,14 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 
   let generated = 0;
 
-  // Generate function for a single segment
+  // Generate function for a single fragment
   const generateStory = async (file: { absolutePath: string; relativePath: string }) => {
     try {
-      const segment = await loadSegmentFile(file.absolutePath);
-      if (!segment) return false;
+      const fragment = await loadFragmentFile(file.absolutePath);
+      if (!fragment) return false;
 
-      const storyContent = generateCSF3Story(segment, file.relativePath);
-      const storyName = `${segment.meta.name}.stories.tsx`;
+      const storyContent = generateCSF3Story(fragment, file.relativePath);
+      const storyName = `${fragment.meta.name}.stories.tsx`;
       const storyPath = join(outputDir, storyName);
 
       await writeFile(storyPath, storyContent);
@@ -77,7 +77,7 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
   // Initial generation
   console.log(pc.dim(`Generating stories to ${relative(process.cwd(), outputDir)}/\n`));
 
-  for (const file of segmentFiles) {
+  for (const file of fragmentFiles) {
     if (await generateStory(file)) {
       generated++;
     }
@@ -88,10 +88,10 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 
   // Watch mode
   if (watch) {
-    console.log(pc.dim('Watching for segment changes... (Ctrl+C to stop)\n'));
+    console.log(pc.dim('Watching for fragment changes... (Ctrl+C to stop)\n'));
 
     const chokidar = await import('chokidar');
-    const patterns = segmentFiles.map(f => f.absolutePath);
+    const patterns = fragmentFiles.map(f => f.absolutePath);
 
     const watcher = chokidar.watch(patterns, {
       ignoreInitial: true,
@@ -99,7 +99,7 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
     });
 
     watcher.on('change', async (changedPath: string) => {
-      const file = segmentFiles.find(f => f.absolutePath === changedPath);
+      const file = fragmentFiles.find(f => f.absolutePath === changedPath);
       if (file) {
         console.log(pc.dim(`\nChanged: ${relative(process.cwd(), changedPath)}`));
         await generateStory(file);
@@ -109,10 +109,10 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
     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 newFiles = await discoverFragmentFiles(config, configDir);
       const file = newFiles.find(f => f.absolutePath === addedPath);
       if (file) {
-        segmentFiles.push(file);
+        fragmentFiles.push(file);
         await generateStory(file);
       }
     });
@@ -125,10 +125,10 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 }
 
 /**
- * Generate a CSF3 story file from a segment definition
+ * Generate a CSF3 story file from a fragment definition
  */
-function generateCSF3Story(segment: SegmentDefinition, relativePath: string): string {
-  const { meta, variants, props, usage } = segment;
+function generateCSF3Story(fragment: FragmentDefinition, relativePath: string): string {
+  const { meta, variants, props, usage } = fragment;
   const componentName = meta.name;
 
   // Build argTypes from props
@@ -178,11 +178,11 @@ ${usage.whenNot?.map(w => `- ${w}`).join('\n') || ''}`
   return `/**
  * Auto-generated Storybook stories from ${relativePath}
  *
- * DO NOT EDIT - regenerate with: segments storygen
+ * DO NOT EDIT - regenerate with: fragments storygen
  */
 
 import type { Meta, StoryObj } from '@storybook/react';
-import { ${componentName} } from '${relativePath.replace(/\.segment\.tsx$/, '/index.js')}';
+import { ${componentName} } from '${relativePath.replace(/\.fragment\.tsx$/, '/index.js')}';
 
 const meta: Meta<typeof ${componentName}> = {
   title: '${meta.category ? `${meta.category.charAt(0).toUpperCase() + meta.category.slice(1)}/` : ''}${componentName}',

package/src/commands/validate.ts

@@ -1,5 +1,5 @@
 /**
- * fragments validate - Validate segment files
+ * fragments validate - Validate fragment files
  */
 
 import pc from 'picocolors';
@@ -13,7 +13,7 @@ import { validateSchema, validateCoverage, validateAll } from '../validators.js'
 export interface ValidateOptions {
   /** Path to config file */
   config?: string;
-  /** Validate segment schema only */
+  /** Validate fragment schema only */
   schema?: boolean;
   /** Validate coverage only */
   coverage?: boolean;

package/src/commands/verify.ts

@@ -1,7 +1,7 @@
 /**
  * fragments verify - Verify component compliance for CI pipelines
  *
- * Uses the /segments/compliance endpoint to get real token compliance data
+ * Uses the /fragments/compliance endpoint to get real token compliance data
  * based on computed styles compared against the design token registry.
  */
 
@@ -13,7 +13,7 @@ import {
   DevServerConnectionError,
   type ComplianceResult,
   type ViolationItem,
-  type SegmentInfo,
+  type FragmentInfo,
 } from '../shared/index.js';
 
 /**
@@ -95,16 +95,16 @@ export async function verify(
     );
   }
 
-  // Fetch all segments
-  let segments = await client.getSegments();
+  // Fetch all fragments
+  let fragments = await client.getFragments();
 
   // Filter by component if specified
   if (component) {
-    segments = segments.filter(
+    fragments = fragments.filter(
       s => s.name.toLowerCase() === component.toLowerCase()
     );
 
-    if (segments.length === 0) {
+    if (fragments.length === 0) {
       const error = { error: `Component "${component}" not found` };
       if (ci) {
         console.log(JSON.stringify(error));
@@ -115,8 +115,8 @@ export async function verify(
     }
   }
 
-  // Check compliance for each segment
-  for (const seg of segments) {
+  // Check compliance for each fragment
+  for (const seg of fragments) {
     try {
       // Get real compliance from the server
       const complianceResult = await client.getCompliance({

package/src/core/auto-props.ts

@@ -64,18 +64,18 @@ function resolveModulePath(basePath: string): string | null {
 }
 
 /**
- * Resolve a component source file from the segment file path + component import path.
+ * Resolve a component source file from the fragment file path + component import path.
  * Supports relative imports like ".", "./Button", "../components/Button".
  */
 export function resolveComponentSourcePath(
-  segmentFileAbsolutePath: string,
+  fragmentFileAbsolutePath: string,
   componentImportPath: string | null
 ): string | null {
   if (!componentImportPath) return null;
   if (!componentImportPath.startsWith(".")) return null;
 
-  const segmentDir = dirname(segmentFileAbsolutePath);
-  const basePath = resolve(segmentDir, componentImportPath);
+  const fragmentDir = dirname(fragmentFileAbsolutePath);
+  const basePath = resolve(fragmentDir, componentImportPath);
   return resolveModulePath(basePath);
 }