@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/service/metrics-store.ts

@@ -2,7 +2,7 @@
  * Metrics Store
  *
  * Persists compliance metrics over time for trend analysis.
- * Stores snapshots in .segments/metrics/ directory.
+ * Stores snapshots in .fragments/metrics/ directory.
  */
 
 import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";

package/src/service/patch-generator.ts

@@ -47,7 +47,7 @@ export interface PatchGenerationResult {
  * Options for patch generation
  */
 export interface PatchGenerationOptions {
-  /** Source file path (if known from segment metadata) */
+  /** Source file path (if known from fragment metadata) */
   sourceFile?: string;
 
   /** Style type hint */

package/src/setup.ts

@@ -1,12 +1,12 @@
 import pc from 'picocolors';
 import { BRAND } from './core/index.js';
-import { loadConfig, discoverSegmentFiles } from './core/node.js';
-import { buildSegments } from './build.js';
+import { loadConfig, discoverFragmentFiles } from './core/node.js';
+import { buildFragments } from './build.js';
 import {
   detectStorybookConfig,
   discoverStoryFiles as discoverStorybookFiles,
   parseStoryFile,
-  convertToSegment,
+  convertToFragment,
 } from './migrate/index.js';
 
 export interface SetupOptions {
@@ -18,68 +18,68 @@ export interface SetupOptions {
 }
 
 export interface SetupResult {
-  segmentFilesCreated: number;
-  segmentsBuilt: number;
+  fragmentFilesCreated: number;
+  fragmentsBuilt: number;
   figmaLinked: number;
   errors: string[];
 }
 
-interface SegmentInfo {
+interface FragmentInfo {
   name: string;
   filePath: string;
   hasFigma: boolean;
 }
 
 /**
- * Check if segments.json exists and is newer than all segment files.
+ * Check if fragments.json exists and is newer than all fragment files.
  */
-async function isSegmentsJsonStale(configDir: string, outFile: string): Promise<{ stale: boolean; missing: boolean }> {
+async function isFragmentsJsonStale(configDir: string, outFile: string): Promise<{ stale: boolean; missing: boolean }> {
   const fs = await import('node:fs/promises');
   const path = await import('node:path');
   const fg = await import('fast-glob');
 
-  const segmentsJsonPath = path.join(configDir, outFile);
+  const fragmentsJsonPath = path.join(configDir, outFile);
 
   try {
-    const segmentsJsonStat = await fs.stat(segmentsJsonPath);
+    const fragmentsJsonStat = await fs.stat(fragmentsJsonPath);
 
-    // Find all segment files
-    const segmentFiles = await fg.default(`**/*${BRAND.fileExtension}`, {
+    // Find all fragment files
+    const fragmentFiles = await fg.default(`**/*${BRAND.fileExtension}`, {
       cwd: configDir,
       ignore: ['**/node_modules/**'],
       absolute: true,
     });
 
-    // Check if any segment file is newer than segments.json
-    for (const file of segmentFiles) {
+    // Check if any fragment file is newer than fragments.json
+    for (const file of fragmentFiles) {
       const stat = await fs.stat(file);
-      if (stat.mtimeMs > segmentsJsonStat.mtimeMs) {
+      if (stat.mtimeMs > fragmentsJsonStat.mtimeMs) {
         return { stale: true, missing: false };
       }
     }
 
     return { stale: false, missing: false };
   } catch {
-    // segments.json doesn't exist
+    // fragments.json doesn't exist
     return { stale: false, missing: true };
   }
 }
 
 /**
- * Load segment files and check which ones have Figma links.
+ * Load fragment files and check which ones have Figma links.
  */
-async function loadSegmentInfo(segmentFiles: Array<{ absolutePath: string; relativePath: string }>): Promise<SegmentInfo[]> {
+async function loadFragmentInfo(fragmentFiles: Array<{ absolutePath: string; relativePath: string }>): Promise<FragmentInfo[]> {
   const fs = await import('node:fs/promises');
-  const segments: SegmentInfo[] = [];
+  const fragments: FragmentInfo[] = [];
 
-  for (const file of segmentFiles) {
+  for (const file of fragmentFiles) {
     try {
       const content = await fs.readFile(file.absolutePath, 'utf-8');
       const nameMatch = content.match(/name:\s*['"]([^'"]+)['"]/);
       const hasFigma = /meta:\s*\{[^}]*figma:\s*['"]https?:/.test(content);
 
       if (nameMatch) {
-        segments.push({
+        fragments.push({
           name: nameMatch[1],
           filePath: file.absolutePath,
           hasFigma,
@@ -90,24 +90,24 @@ async function loadSegmentInfo(segmentFiles: Array<{ absolutePath: string; relat
     }
   }
 
-  return segments;
+  return fragments;
 }
 
 /**
- * Run auto-setup for segments dev server.
+ * Run auto-setup for fragments dev server.
  *
  * This function:
- * 1. Checks for segment files, imports from Storybook if none found
- * 2. Builds segments.json if missing or stale
- * 3. Links Figma if configured but no segments are linked
+ * 1. Checks for fragment files, imports from Storybook if none found
+ * 2. Builds fragments.json if missing or stale
+ * 3. Links Figma if configured but no fragments are linked
  */
 export async function runSetup(options: SetupOptions = {}): Promise<SetupResult> {
   const fs = await import('node:fs/promises');
   const path = await import('node:path');
 
   const result: SetupResult = {
-    segmentFilesCreated: 0,
-    segmentsBuilt: 0,
+    fragmentFilesCreated: 0,
+    fragmentsBuilt: 0,
     figmaLinked: 0,
     errors: [],
   };
@@ -120,11 +120,11 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
     // Load config
     const { config, configDir } = await loadConfig(options.configPath);
 
-    // Step 1: Check for segment files
+    // Step 1: Check for fragment files
     log(pc.dim('Checking for fragment files...'));
-    let segmentFiles = await discoverSegmentFiles(config, configDir);
+    let fragmentFiles = await discoverFragmentFiles(config, configDir);
 
-    if (segmentFiles.length === 0 && !options.skipStorybook) {
+    if (fragmentFiles.length === 0 && !options.skipStorybook) {
       // No fragment files - check for Storybook
       log(pc.yellow('\n   No fragment files found'));
 
@@ -141,43 +141,43 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
           for (const storyFile of storyFiles) {
             try {
               const parsed = await parseStoryFile(storyFile);
-              const segmentResult = convertToSegment(parsed);
+              const fragmentResult = convertToFragment(parsed);
 
               // Create directory and write file
-              await fs.mkdir(path.dirname(segmentResult.outputFile), { recursive: true });
-              await fs.writeFile(segmentResult.outputFile, segmentResult.code);
+              await fs.mkdir(path.dirname(fragmentResult.outputFile), { recursive: true });
+              await fs.writeFile(fragmentResult.outputFile, fragmentResult.code);
               converted++;
             } catch {
               // Skip files that can't be converted
             }
           }
 
-          result.segmentFilesCreated = converted;
+          result.fragmentFilesCreated = converted;
           log(pc.green(`   Generated ${converted} fragment file(s)`));
 
-          // Refresh segment files list
-          segmentFiles = await discoverSegmentFiles(config, configDir);
+          // Refresh fragment files list
+          fragmentFiles = await discoverFragmentFiles(config, configDir);
         }
       } else {
         log(pc.dim('   No Storybook config found'));
         log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} add <ComponentName>`)} to create your first fragment`));
       }
-    } else if (segmentFiles.length > 0) {
-      log(pc.green(`   Found ${segmentFiles.length} fragment file(s)`));
+    } else if (fragmentFiles.length > 0) {
+      log(pc.green(`   Found ${fragmentFiles.length} fragment file(s)`));
     }
 
     // Step 2: Build fragments.json if needed
-    if (segmentFiles.length > 0 && !options.skipBuild) {
+    if (fragmentFiles.length > 0 && !options.skipBuild) {
       const outFile = config.outFile || BRAND.outFile;
-      const { stale, missing } = await isSegmentsJsonStale(configDir, outFile);
+      const { stale, missing } = await isFragmentsJsonStale(configDir, outFile);
 
       if (missing || stale) {
         const reason = missing ? 'Building' : 'Rebuilding';
         log(pc.dim(`\n${reason} ${BRAND.outFile}...`));
 
         try {
-          const buildResult = await buildSegments(config, configDir);
-          result.segmentsBuilt = buildResult.segmentCount;
+          const buildResult = await buildFragments(config, configDir);
+          result.fragmentsBuilt = buildResult.fragmentCount;
 
           if (buildResult.errors.length > 0) {
             for (const err of buildResult.errors) {
@@ -185,7 +185,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
             }
           }
 
-          log(pc.green(`   Built ${buildResult.segmentCount} fragment(s)`));
+          log(pc.green(`   Built ${buildResult.fragmentCount} fragment(s)`));
         } catch (error) {
           result.errors.push(`Build failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
@@ -196,16 +196,16 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
 
     // Step 3: Link Figma if configured
     if (!options.skipFigma && config.figmaFile && process.env.FIGMA_ACCESS_TOKEN) {
-      const segments = await loadSegmentInfo(segmentFiles);
-      const linkedCount = segments.filter((s) => s.hasFigma).length;
+      const fragments = await loadFragmentInfo(fragmentFiles);
+      const linkedCount = fragments.filter((s) => s.hasFigma).length;
 
-      if (linkedCount === 0 && segments.length > 0) {
+      if (linkedCount === 0 && fragments.length > 0) {
         log(pc.dim('\n   Figma configured but no fragments linked'));
         log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} link figma --auto`)} to auto-link components`));
         // Note: We don't auto-link here because it requires API calls and user may want control
         // But we inform them about the option
       } else if (linkedCount > 0) {
-        log(pc.dim(`\n   ${linkedCount}/${segments.length} fragment(s) linked to Figma`));
+        log(pc.dim(`\n   ${linkedCount}/${fragments.length} fragment(s) linked to Figma`));
       }
     } else if (!options.skipFigma && config.figmaFile && !process.env.FIGMA_ACCESS_TOKEN) {
       log(pc.dim('\n   Figma file configured but FIGMA_ACCESS_TOKEN not set'));
@@ -224,12 +224,12 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
 export function printSetupSummary(result: SetupResult): void {
   console.log();
 
-  if (result.segmentFilesCreated > 0) {
-    console.log(pc.green(`   Imported ${result.segmentFilesCreated} segments from Storybook`));
+  if (result.fragmentFilesCreated > 0) {
+    console.log(pc.green(`   Imported ${result.fragmentFilesCreated} fragments from Storybook`));
   }
 
-  if (result.segmentsBuilt > 0) {
-    console.log(pc.green(`   Built ${result.segmentsBuilt} segments`));
+  if (result.fragmentsBuilt > 0) {
+    console.log(pc.green(`   Built ${result.fragmentsBuilt} fragments`));
   }
 
   if (result.errors.length > 0) {

package/src/shared/dev-server-client.ts

@@ -7,7 +7,7 @@
 
 import type {
   ComplianceResult,
-  SegmentInfo,
+  FragmentInfo,
   ContextData,
   ViolationItem,
   A11yResult,
@@ -52,7 +52,7 @@ export class DevServerClient {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), 5000);
 
-      const response = await fetch(`${this.baseUrl}/segments/context?format=json`, {
+      const response = await fetch(`${this.baseUrl}/fragments/context?format=json`, {
         signal: controller.signal,
       });
 
@@ -64,15 +64,15 @@ export class DevServerClient {
   }
 
   /**
-   * Get all segments from the context endpoint
+   * Get all fragments from the context endpoint
    */
-  async getSegments(): Promise<SegmentInfo[]> {
-    const response = await this.fetch('/segments/context?format=json');
+  async getFragments(): Promise<FragmentInfo[]> {
+    const response = await this.fetch('/fragments/context?format=json');
     const data = await response.json() as {
       components: Record<string, { category?: string; description?: string; status?: string; figma?: string }>;
     };
 
-    // Transform object to array of SegmentInfo
+    // Transform object to array of FragmentInfo
     const components = data.components || {};
     return Object.entries(components).map(([name, info]) => ({
       name,
@@ -87,7 +87,7 @@ export class DevServerClient {
    * Get compliance data for a component
    */
   async getCompliance(request: ComplianceRequest): Promise<ComplianceResult> {
-    const response = await this.fetch('/segments/compliance', {
+    const response = await this.fetch('/fragments/compliance', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(request),

package/src/shared/fragment-loader.ts

@@ -0,0 +1,59 @@
+/**
+ * Fragment Loader
+ *
+ * Utilities for loading fragment data from the dev server or fragments.json
+ */
+
+import type { FragmentInfo } from './types.js';
+import { DevServerClient, createDevServerClient } from './dev-server-client.js';
+
+/**
+ * Options for loading fragments
+ */
+export interface LoadFragmentsOptions {
+  /** Dev server port */
+  port?: number | string;
+  /** Filter by component name */
+  component?: string;
+}
+
+/**
+ * Load fragments from the dev server
+ */
+export async function loadFragments(options: LoadFragmentsOptions = {}): Promise<FragmentInfo[]> {
+  const { port = 6006, component } = options;
+
+  const client = createDevServerClient(port);
+  let fragments = await client.getFragments();
+
+  // Filter by component if specified
+  if (component) {
+    fragments = fragments.filter(
+      s => s.name.toLowerCase() === component.toLowerCase()
+    );
+  }
+
+  return fragments;
+}
+
+/**
+ * Load a single fragment by name
+ */
+export async function loadFragment(
+  name: string,
+  options: { port?: number | string } = {}
+): Promise<FragmentInfo | null> {
+  const fragments = await loadFragments({ ...options, component: name });
+  return fragments.length > 0 ? fragments[0] : null;
+}
+
+/**
+ * Check if a fragment exists
+ */
+export async function fragmentExists(
+  name: string,
+  options: { port?: number | string } = {}
+): Promise<boolean> {
+  const fragment = await loadFragment(name, options);
+  return fragment !== null;
+}

package/src/shared/index.ts

@@ -5,4 +5,4 @@
 export * from './types.js';
 export * from './dev-server-client.js';
 export * from './command-wrapper.js';
-export * from './segment-loader.js';
+export * from './fragment-loader.js';

package/src/shared/types.ts

@@ -81,9 +81,9 @@ export interface ComplianceResult {
 }
 
 /**
- * Segment information from context endpoint
+ * Fragment information from context endpoint
  */
-export interface SegmentInfo {
+export interface FragmentInfo {
   /** Component name */
   name: string;
   /** Component category */
@@ -107,11 +107,11 @@ export interface CommandResult {
 }
 
 /**
- * Context data from the /segments/context endpoint
+ * Context data from the /fragments/context endpoint
  */
 export interface ContextData {
   /** List of components */
-  components: SegmentInfo[];
+  components: FragmentInfo[];
 }
 
 /**

package/src/static-viewer.ts

@@ -1,23 +1,23 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import type { CompiledSegmentsFile } from "./core/index.js";
+import type { CompiledFragmentsFile } from "./core/index.js";
 import { BRAND } from "./core/index.js";
 
 /**
- * Generate a static HTML viewer for the segments.json file.
+ * Generate a static HTML viewer for the fragments.json file.
  * This viewer shows component documentation without needing to render actual components.
  */
-export function generateStaticViewer(data: CompiledSegmentsFile): string {
-  const segments = Object.values(data.segments);
+export function generateStaticViewer(data: CompiledFragmentsFile): string {
+  const fragments = Object.values(data.fragments);
 
   // Group by category
-  const categories = new Map<string, typeof segments>();
-  for (const segment of segments) {
-    const category = segment.meta.category ?? "Uncategorized";
+  const categories = new Map<string, typeof fragments>();
+  for (const fragment of fragments) {
+    const category = fragment.meta.category ?? "Uncategorized";
     if (!categories.has(category)) {
       categories.set(category, []);
     }
-    categories.get(category)!.push(segment);
+    categories.get(category)!.push(fragment);
   }
 
   // Sort categories and components
@@ -426,11 +426,11 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
       
       <div class="sidebar-stats">
         <div class="stat">
-          <div class="stat-value">${segments.length}</div>
+          <div class="stat-value">${fragments.length}</div>
           <div class="stat-label">Components</div>
         </div>
         <div class="stat">
-          <div class="stat-value">${segments.reduce(
+          <div class="stat-value">${fragments.reduce(
             (sum, s) => sum + s.variants.length,
             0
           )}</div>
@@ -465,34 +465,34 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
     
     <main class="main" id="main">
       ${
-        segments.length === 0
+        fragments.length === 0
           ? `
         <div class="empty-state">
           <h2>No Components Found</h2>
-          <p>Run <code>segments build</code> to compile your segment files.</p>
+          <p>Run <code>fragments build</code> to compile your fragment files.</p>
         </div>
       `
-          : segments
+          : fragments
               .sort((a, b) => a.meta.name.localeCompare(b.meta.name))
               .map(
-                (segment) => `
-        <section class="component-section" id="${segment.meta.name}">
+                (fragment) => `
+        <section class="component-section" id="${fragment.meta.name}">
           <div class="component-header">
-            <h2 class="component-name">${segment.meta.name}</h2>
-            <p class="component-description">${segment.meta.description}</p>
+            <h2 class="component-name">${fragment.meta.name}</h2>
+            <p class="component-description">${fragment.meta.description}</p>
             <div class="component-meta">
               ${
-                segment.meta.status
-                  ? `<span class="meta-badge status-${segment.meta.status}">${segment.meta.status}</span>`
+                fragment.meta.status
+                  ? `<span class="meta-badge status-${fragment.meta.status}">${fragment.meta.status}</span>`
                   : ""
               }
               ${
-                segment.meta.category
-                  ? `<span class="meta-badge">${segment.meta.category}</span>`
+                fragment.meta.category
+                  ? `<span class="meta-badge">${fragment.meta.category}</span>`
                   : ""
               }
               ${
-                segment.meta.tags
+                fragment.meta.tags
                   ?.map((tag) => `<span class="meta-badge">${tag}</span>`)
                   .join("") ?? ""
               }
@@ -500,15 +500,15 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
           </div>
           
           ${
-            segment.usage
+            fragment.usage
               ? `
             <div class="section">
               <h3 class="section-title">Usage Guidelines</h3>
               ${
-                segment.usage.when?.length
+                fragment.usage.when?.length
                   ? `
                 <ul class="usage-list">
-                  ${segment.usage.when
+                  ${fragment.usage.when
                     .map((item) => `<li class="usage-item when">${item}</li>`)
                     .join("")}
                 </ul>
@@ -516,10 +516,10 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
                   : ""
               }
               ${
-                segment.usage.whenNot?.length
+                fragment.usage.whenNot?.length
                   ? `
                 <ul class="usage-list" style="margin-top: 12px;">
-                  ${segment.usage.whenNot
+                  ${fragment.usage.whenNot
                     .map(
                       (item) => `<li class="usage-item when-not">${item}</li>`
                     )
@@ -534,7 +534,7 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
           }
           
           ${
-            segment.props && Object.keys(segment.props).length
+            fragment.props && Object.keys(fragment.props).length
               ? `
             <div class="section">
               <h3 class="section-title">Props</h3>
@@ -548,7 +548,7 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
                   </tr>
                 </thead>
                 <tbody>
-                  ${Object.entries(segment.props)
+                  ${Object.entries(fragment.props)
                     .map(
                       ([name, prop]) => `
                     <tr>
@@ -579,12 +579,12 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
           }
           
           ${
-            segment.variants?.length
+            fragment.variants?.length
               ? `
             <div class="section">
               <h3 class="section-title">Variants</h3>
               <div class="variants-grid">
-                ${segment.variants
+                ${fragment.variants
                   .map(
                     (variant) => `
                   <div class="variant-card">
@@ -612,12 +612,12 @@ export function generateStaticViewer(data: CompiledSegmentsFile): string {
           }
           
           ${
-            segment.relations?.length
+            fragment.relations?.length
               ? `
             <div class="section">
               <h3 class="section-title">Related Components</h3>
               <div class="relations-list">
-                ${segment.relations
+                ${fragment.relations
                   .map(
                     (rel) =>
                       `<a href="#${
@@ -704,12 +704,12 @@ function escapeHtml(str: string): string {
 }
 
 /**
- * Load segments.json and generate static viewer
+ * Load fragments.json and generate static viewer
  */
 export async function generateViewerFromJson(
   jsonPath: string
 ): Promise<string> {
   const content = await readFile(jsonPath, "utf-8");
-  const data = JSON.parse(content) as CompiledSegmentsFile;
+  const data = JSON.parse(content) as CompiledFragmentsFile;
   return generateStaticViewer(data);
 }

package/src/test/discovery.ts

@@ -3,12 +3,12 @@
  */
 
 import { readFile } from 'node:fs/promises';
-import type { SegmentsConfig } from '../core/index.js';
-import { discoverSegmentFiles, parseSegmentFile } from '../core/node.js';
+import type { FragmentsConfig } from '../core/index.js';
+import { discoverFragmentFiles, parseFragmentFile } from '../core/node.js';
 import type { TestCase, DiscoveryOptions } from './types.js';
 
 /**
- * Discovered segment with play function metadata
+ * Discovered fragment with play function metadata
  */
 interface DiscoveredVariant {
   component: string;
@@ -23,17 +23,17 @@ interface DiscoveredVariant {
  * Discover all variants with play functions
  */
 export async function discoverTests(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string,
   options: DiscoveryOptions = {}
 ): Promise<TestCase[]> {
-  const files = await discoverSegmentFiles(config, configDir);
+  const files = await discoverFragmentFiles(config, configDir);
   const variants: DiscoveredVariant[] = [];
 
   for (const file of files) {
     try {
       const content = await readFile(file.absolutePath, 'utf-8');
-      const parsed = parseSegmentFile(content, file.relativePath);
+      const parsed = parseFragmentFile(content, file.relativePath);
 
       if (!parsed.meta.name) continue;