@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/diff.ts

@@ -2,11 +2,11 @@ import pc from 'picocolors';
 import {
   BRAND,
   DEFAULTS,
-  type SegmentsConfig,
-  type SegmentDefinition,
+  type FragmentsConfig,
+  type FragmentDefinition,
   type Theme,
 } from './core/index.js';
-import { discoverSegmentFiles, loadSegmentFile } from './core/node.js';
+import { discoverFragmentFiles, loadFragmentFile } from './core/node.js';
 import {
   BrowserPool,
   CaptureEngine,
@@ -68,7 +68,7 @@ export interface DiffCommandResult {
  * Execute the diff command
  */
 export async function runDiffCommand(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string,
   options: DiffCommandOptions = {}
 ): Promise<DiffCommandResult> {
@@ -86,11 +86,11 @@ export async function runDiffCommand(
   const threshold = options.threshold ?? config.screenshots?.threshold ?? DEFAULTS.diffThreshold;
   const diffEngine = new DiffEngine(threshold);
 
-  // Discover segments
-  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  // Discover fragments
+  const fragmentFiles = await discoverFragmentFiles(config, configDir);
 
-  if (segmentFiles.length === 0) {
-    console.log(pc.yellow('No segment files found.'));
+  if (fragmentFiles.length === 0) {
+    console.log(pc.yellow('No fragment files found.'));
     return {
       success: true,
       total: 0,
@@ -102,14 +102,14 @@ export async function runDiffCommand(
     };
   }
 
-  // Load all segments
-  const segments: Array<{ path: string; segment: SegmentDefinition }> = [];
+  // Load all fragments
+  const fragments: Array<{ path: string; fragment: FragmentDefinition }> = [];
 
-  for (const file of segmentFiles) {
+  for (const file of fragmentFiles) {
     try {
-      const segment = await loadSegmentFile(file.absolutePath);
-      if (segment) {
-        segments.push({ path: file.relativePath, segment });
+      const fragment = await loadFragmentFile(file.absolutePath);
+      if (fragment) {
+        fragments.push({ path: file.relativePath, fragment });
       }
     } catch {
       // Skip failed loads
@@ -117,11 +117,11 @@ export async function runDiffCommand(
   }
 
   // Filter by component if specified
-  const filteredSegments = options.component
-    ? segments.filter((s) => s.segment.meta.name === options.component)
-    : segments;
+  const filteredFragments = options.component
+    ? fragments.filter((s) => s.fragment.meta.name === options.component)
+    : fragments;
 
-  if (options.component && filteredSegments.length === 0) {
+  if (options.component && filteredFragments.length === 0) {
     console.log(pc.yellow(`Component "${options.component}" not found.`));
     return {
       success: false,
@@ -140,14 +140,14 @@ export async function runDiffCommand(
     variant: string;
   }> = [];
 
-  for (const { segment } of filteredSegments) {
+  for (const { fragment } of filteredFragments) {
     const variants = options.variant
-      ? segment.variants.filter((v) => v.name === options.variant)
-      : segment.variants;
+      ? fragment.variants.filter((v) => v.name === options.variant)
+      : fragment.variants;
 
     for (const variant of variants) {
       variantsToDiff.push({
-        component: segment.meta.name,
+        component: fragment.meta.name,
         variant: variant.name,
       });
     }

package/src/index.ts

@@ -2,7 +2,7 @@
 export {
   loadConfig,
   findConfigFile,
-  discoverSegmentFiles,
+  discoverFragmentFiles,
   discoverComponentFiles,
   extractComponentName,
 } from "./core/node.js";
@@ -17,7 +17,7 @@ export type {
 } from "./validators.js";
 
 // Build
-export { buildSegments } from "./build.js";
+export { buildFragments } from "./build.js";
 export type { BuildResult } from "./build.js";
 
 // Screenshot

package/src/mcp/server.ts

@@ -9,7 +9,7 @@ import {
   BRAND,
   DEFAULTS,
   generateContext,
-  type CompiledSegmentsFile,
+  type CompiledFragmentsFile,
   type VerifyResult,
   type Theme,
 } from '../core/index.js';
@@ -298,9 +298,9 @@ export function createMcpServer(config: McpServerConfig): Server {
   );
 
   // Lazy-loaded resources
-  let segmentsData: CompiledSegmentsFile | null = null;
-  // Per-segment package name map (segment name → package name from its source fragments.json)
-  const segmentPackageMap = new Map<string, string>();
+  let fragmentsData: CompiledFragmentsFile | null = null;
+  // Per-fragment package name map (fragment name → package name from its source fragments.json)
+  const fragmentPackageMap = new Map<string, string>();
   let defaultPackageName: string | null = null;
 
   let browserPool: any = null;
@@ -308,9 +308,9 @@ export function createMcpServer(config: McpServerConfig): Server {
   let diffEngine: any = null;
   let isPoolWarming = false;
 
-  async function loadSegments(): Promise<CompiledSegmentsFile> {
-    if (segmentsData) {
-      return segmentsData;
+  async function loadFragments(): Promise<CompiledFragmentsFile> {
+    if (fragmentsData) {
+      return fragmentsData;
     }
 
     const paths = findFragmentsJson(config.projectRoot);
@@ -324,51 +324,51 @@ export function createMcpServer(config: McpServerConfig): Server {
 
     // Load and merge all found fragments files
     const content = await readFile(paths[0], 'utf-8');
-    segmentsData = JSON.parse(content) as CompiledSegmentsFile;
+    fragmentsData = JSON.parse(content) as CompiledFragmentsFile;
 
     // Normalize legacy "recipes" key to "blocks"
-    if (!segmentsData.blocks && segmentsData.recipes) {
-      segmentsData.blocks = segmentsData.recipes;
+    if (!fragmentsData.blocks && fragmentsData.recipes) {
+      fragmentsData.blocks = fragmentsData.recipes;
     }
 
-    // Track per-segment package names from each source file
-    if (segmentsData.packageName) {
-      for (const name of Object.keys(segmentsData.segments)) {
-        segmentPackageMap.set(name, segmentsData.packageName);
+    // Track per-fragment package names from each source file
+    if (fragmentsData.packageName) {
+      for (const name of Object.keys(fragmentsData.fragments)) {
+        fragmentPackageMap.set(name, fragmentsData.packageName);
       }
     }
 
     for (let i = 1; i < paths.length; i++) {
-      const extra = JSON.parse(await readFile(paths[i], 'utf-8')) as CompiledSegmentsFile;
-      // Track package name for each segment from this file
+      const extra = JSON.parse(await readFile(paths[i], 'utf-8')) as CompiledFragmentsFile;
+      // Track package name for each fragment from this file
       if (extra.packageName) {
-        for (const name of Object.keys(extra.segments)) {
-          segmentPackageMap.set(name, extra.packageName);
+        for (const name of Object.keys(extra.fragments)) {
+          fragmentPackageMap.set(name, extra.packageName);
         }
       }
-      Object.assign(segmentsData.segments, extra.segments);
+      Object.assign(fragmentsData.fragments, extra.fragments);
       // Support both "blocks" (new) and "recipes" (legacy) keys
       const extraBlocks = extra.blocks ?? extra.recipes;
       if (extraBlocks) {
-        segmentsData.blocks = { ...segmentsData.blocks, ...extraBlocks };
+        fragmentsData.blocks = { ...fragmentsData.blocks, ...extraBlocks };
       }
     }
 
-    return segmentsData;
+    return fragmentsData;
   }
 
   /**
    * Get the package name for import statements for a specific component.
-   * Uses per-segment tracking when multiple fragments.json files are merged,
+   * Uses per-fragment tracking when multiple fragments.json files are merged,
    * falls back to the first fragments.json packageName, then project package.json.
    */
-  async function getPackageName(segmentName?: string): Promise<string> {
-    // Ensure segments are loaded (populates segmentPackageMap)
-    await loadSegments();
+  async function getPackageName(fragmentName?: string): Promise<string> {
+    // Ensure fragments are loaded (populates fragmentPackageMap)
+    await loadFragments();
 
-    // Check per-segment map first (handles multi-library merges correctly)
-    if (segmentName) {
-      const segPkg = segmentPackageMap.get(segmentName);
+    // Check per-fragment map first (handles multi-library merges correctly)
+    if (fragmentName) {
+      const segPkg = fragmentPackageMap.get(fragmentName);
       if (segPkg) return segPkg;
     }
 
@@ -377,8 +377,8 @@ export function createMcpServer(config: McpServerConfig): Server {
     }
 
     // Prefer packageName from first fragments.json
-    if (segmentsData?.packageName) {
-      defaultPackageName = segmentsData.packageName;
+    if (fragmentsData?.packageName) {
+      defaultPackageName = fragmentsData.packageName;
       return defaultPackageName;
     }
 
@@ -479,7 +479,7 @@ export function createMcpServer(config: McpServerConfig): Server {
         // DISCOVER — list, suggest, context, alternatives
         // ================================================================
         case TOOL_NAMES.discover: {
-          const data = await loadSegments();
+          const data = await loadFragments();
           const useCase = (args?.useCase as string) ?? undefined;
           const componentForAlts = (args?.component as string) ?? undefined;
           const category = (args?.category as string) ?? undefined;
@@ -492,10 +492,10 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           // --- Context mode: compact or format specified with no specific query ---
           if (compact || (args?.format && !useCase && !componentForAlts && !category && !search && !status)) {
-            const segments = Object.values(data.segments);
+            const fragments = Object.values(data.fragments);
             const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
 
-            const { content: ctxContent, tokenEstimate } = generateContext(segments, {
+            const { content: ctxContent, tokenEstimate } = generateContext(fragments, {
               format,
               compact,
               include: {
@@ -543,7 +543,7 @@ export function createMcpServer(config: McpServerConfig): Server {
               }
             });
 
-            const scored = Object.values(data.segments).map((s) => {
+            const scored = Object.values(data.fragments).map((s) => {
               let score = 0;
               const reasons: string[] = [];
 
@@ -700,17 +700,17 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           // --- Alternatives mode: component provided (no useCase) ---
           if (componentForAlts) {
-            const segment = Object.values(data.segments).find(
+            const fragment = Object.values(data.fragments).find(
               (s) => s.meta.name.toLowerCase() === componentForAlts.toLowerCase()
             );
 
-            if (!segment) {
+            if (!fragment) {
               throw new Error(`Component "${componentForAlts}" not found. Use fragments_discover to see available components.`);
             }
 
-            const relations = segment.relations ?? [];
+            const relations = fragment.relations ?? [];
 
-            const referencedBy = Object.values(data.segments)
+            const referencedBy = Object.values(data.fragments)
               .filter((s) =>
                 s.relations?.some((r) => r.component.toLowerCase() === componentForAlts.toLowerCase())
               )
@@ -724,10 +724,10 @@ export function createMcpServer(config: McpServerConfig): Server {
                 )?.note,
               }));
 
-            const sameCategory = Object.values(data.segments)
+            const sameCategory = Object.values(data.fragments)
               .filter(
                 (s) =>
-                  s.meta.category === segment.meta.category &&
+                  s.meta.category === fragment.meta.category &&
                   s.meta.name.toLowerCase() !== componentForAlts.toLowerCase()
               )
               .map((s) => ({
@@ -739,8 +739,8 @@ export function createMcpServer(config: McpServerConfig): Server {
               content: [{
                 type: 'text' as const,
                 text: JSON.stringify({
-                  component: segment.meta.name,
-                  category: segment.meta.category,
+                  component: fragment.meta.name,
+                  category: fragment.meta.category,
                   directRelations: relations,
                   referencedBy,
                   sameCategory,
@@ -753,7 +753,7 @@ export function createMcpServer(config: McpServerConfig): Server {
           }
 
           // --- Default: list mode ---
-          const segments = Object.values(data.segments)
+          const fragments = Object.values(data.fragments)
             .filter((s) => {
               if (category && s.meta.category !== category) return false;
               if (status && (s.meta.status ?? 'stable') !== status) return false;
@@ -778,12 +778,12 @@ export function createMcpServer(config: McpServerConfig): Server {
             content: [{
               type: 'text' as const,
               text: JSON.stringify({
-                total: segments.length,
-                segments,
-                categories: [...new Set(segments.map((s) => s.category))],
-                hint: segments.length === 0
+                total: fragments.length,
+                fragments,
+                categories: [...new Set(fragments.map((s) => s.category))],
+                hint: fragments.length === 0
                   ? 'No components found. Try broader search terms or check available categories.'
-                  : segments.length > 5
+                  : fragments.length > 5
                     ? 'Use fragments_discover with useCase for recommendations, or fragments_inspect for details on a specific component.'
                     : undefined,
               }, null, 2),
@@ -795,7 +795,7 @@ export function createMcpServer(config: McpServerConfig): Server {
         // INSPECT — get + guidelines + example in one call
         // ================================================================
         case TOOL_NAMES.inspect: {
-          const data = await loadSegments();
+          const data = await loadFragments();
           const componentName = args?.component as string;
           const fields = args?.fields as string[] | undefined;
           const variantName = (args?.variant as string) ?? undefined;
@@ -806,19 +806,19 @@ export function createMcpServer(config: McpServerConfig): Server {
             throw new Error('component is required');
           }
 
-          const segment = Object.values(data.segments).find(
+          const fragment = Object.values(data.fragments).find(
             (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
           );
 
-          if (!segment) {
+          if (!fragment) {
             throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
           }
 
           // Build the full inspect result combining get + guidelines + example
-          const pkgName = await getPackageName(segment.meta.name);
+          const pkgName = await getPackageName(fragment.meta.name);
 
           // Filter variants for examples — fuzzy match: exact → prefix → contains
-          let variants = segment.variants;
+          let variants = fragment.variants;
           if (variantName) {
             const query = variantName.toLowerCase();
             // 1. Exact match
@@ -842,7 +842,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             } else {
               throw new Error(
                 `Variant "${variantName}" not found for ${componentName}. ` +
-                `Available: ${segment.variants.map((v) => v.name).join(', ')}`
+                `Available: ${fragment.variants.map((v) => v.name).join(', ')}`
               );
             }
           }
@@ -868,12 +868,12 @@ export function createMcpServer(config: McpServerConfig): Server {
             return {
               variant: variant.name,
               description: variant.description,
-              code: `<${segment.meta.name} />`,
+              code: `<${fragment.meta.name} />`,
               note: 'No code example provided in fragment. Refer to props for customization.',
             };
           });
 
-          const propsReference = Object.entries(segment.props ?? {}).map(([propName, prop]) => ({
+          const propsReference = Object.entries(fragment.props ?? {}).map(([propName, prop]) => ({
             name: propName,
             type: prop.type,
             required: prop.required,
@@ -881,7 +881,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             description: prop.description,
           }));
 
-          const propConstraints = Object.entries(segment.props ?? {})
+          const propConstraints = Object.entries(fragment.props ?? {})
             .filter(([, prop]) => prop.constraints && prop.constraints.length > 0)
             .map(([pName, prop]) => ({
               prop: pName,
@@ -890,20 +890,20 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           const fullResult = {
             // Component data (from old "get")
-            meta: segment.meta,
-            props: segment.props,
-            variants: segment.variants,
-            relations: segment.relations,
-            contract: segment.contract,
-            generated: segment._generated,
+            meta: fragment.meta,
+            props: fragment.props,
+            variants: fragment.variants,
+            relations: fragment.relations,
+            contract: fragment.contract,
+            generated: fragment._generated,
             // Guidelines (from old "guidelines")
             guidelines: {
-              when: filterPlaceholders(segment.usage?.when),
-              whenNot: filterPlaceholders(segment.usage?.whenNot),
-              guidelines: segment.usage?.guidelines ?? [],
-              accessibility: segment.usage?.accessibility ?? [],
+              when: filterPlaceholders(fragment.usage?.when),
+              whenNot: filterPlaceholders(fragment.usage?.whenNot),
+              guidelines: fragment.usage?.guidelines ?? [],
+              accessibility: fragment.usage?.accessibility ?? [],
               propConstraints,
-              alternatives: segment.relations
+              alternatives: fragment.relations
                 ?.filter((r) => r.relationship === 'alternative')
                 .map((r) => ({
                   component: r.component,
@@ -912,7 +912,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             },
             // Examples (from old "example")
             examples: {
-              import: `import { ${segment.meta.name} } from '${pkgName}';`,
+              import: `import { ${fragment.meta.name} } from '${pkgName}';`,
               code: examples,
               propsReference,
             },
@@ -935,7 +935,7 @@ export function createMcpServer(config: McpServerConfig): Server {
         // BLOCKS — composition patterns
         // ================================================================
         case TOOL_NAMES.blocks: {
-          const data = await loadSegments();
+          const data = await loadFragments();
           const blockName = args?.name as string | undefined;
           const search = (args?.search as string)?.toLowerCase() ?? undefined;
           const component = (args?.component as string)?.toLowerCase() ?? undefined;
@@ -1004,7 +1004,7 @@ export function createMcpServer(config: McpServerConfig): Server {
         // TOKENS — list CSS custom properties by category
         // ================================================================
         case TOOL_NAMES.tokens: {
-          const data = await loadSegments();
+          const data = await loadFragments();
           const category = (args?.category as string)?.toLowerCase() ?? undefined;
           const search = (args?.search as string)?.toLowerCase() ?? undefined;
 
@@ -1082,7 +1082,7 @@ export function createMcpServer(config: McpServerConfig): Server {
         // IMPLEMENT — one-shot discover + inspect + blocks + tokens
         // ================================================================
         case TOOL_NAMES.implement: {
-          const data = await loadSegments();
+          const data = await loadFragments();
           const useCase = args?.useCase as string;
           if (!useCase) {
             throw new Error('useCase is required');
@@ -1091,7 +1091,7 @@ export function createMcpServer(config: McpServerConfig): Server {
           const useCaseLower = useCase.toLowerCase();
           const searchTerms = useCaseLower.split(/\s+/).filter(Boolean);
 
-          // 1. Score all segments (same logic as discover suggest)
+          // 1. Score all fragments (same logic as discover suggest)
           const synonymMap: Record<string, string[]> = {
             'form': ['input', 'field', 'submit', 'validation'],
             'input': ['form', 'field', 'text', 'entry'],
@@ -1112,7 +1112,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             if (synonyms) synonyms.forEach((syn) => expandedTerms.add(syn));
           });
 
-          const scored = Object.values(data.segments).map((s) => {
+          const scored = Object.values(data.fragments).map((s) => {
             let score = 0;
             const nameLower = s.meta.name.toLowerCase();
             if (searchTerms.some((t) => nameLower.includes(t))) score += 15;
@@ -1127,7 +1127,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             if (s.meta.category && searchTerms.some((t) => s.meta.category!.toLowerCase().includes(t))) score += 8;
             if (s.meta.status === 'stable') score += 5;
             if (s.meta.status === 'deprecated') score -= 25;
-            return { segment: s, score };
+            return { fragment: s, score };
           });
 
           const topMatches = scored
@@ -1137,7 +1137,7 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           // 2. Build component details for top matches
           const components = await Promise.all(
-            topMatches.map(async ({ segment: s, score }) => {
+            topMatches.map(async ({ fragment: s, score }) => {
               const pkgName = await getPackageName(s.meta.name);
               const examples = s.variants.slice(0, 2).map((v) => ({
                 variant: v.name,
@@ -1166,7 +1166,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             .filter((b) => {
               const haystack = [b.name, b.description, ...(b.tags ?? []), ...b.components, b.category].join(' ').toLowerCase();
               return searchTerms.some((t) => haystack.includes(t)) ||
-                     topMatches.some(({ segment }) => b.components.some((c) => c.toLowerCase() === segment.meta.name.toLowerCase()));
+                     topMatches.some(({ fragment }) => b.components.some((c) => c.toLowerCase() === fragment.meta.name.toLowerCase()));
             })
             .slice(0, 2)
             .map((b) => ({ name: b.name, description: b.description, components: b.components, code: b.code }));
@@ -1460,7 +1460,7 @@ export function createMcpServer(config: McpServerConfig): Server {
         // FIX — unchanged
         // ================================================================
         case TOOL_NAMES.fix: {
-          const data = await loadSegments();
+          const data = await loadFragments();
           const componentName = args?.component as string;
           const variantName = (args?.variant as string) ?? undefined;
           const fixType = (args?.fixType as 'token' | 'all') ?? 'all';
@@ -1469,11 +1469,11 @@ export function createMcpServer(config: McpServerConfig): Server {
             throw new Error('component is required');
           }
 
-          const segment = Object.values(data.segments).find(
+          const fragment = Object.values(data.fragments).find(
             (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
           );
 
-          if (!segment) {
+          if (!fragment) {
             throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
           }
 

package/src/migrate/__tests__/utils/utils.test.ts

@@ -241,11 +241,11 @@ describe("storyNameToTitle", () => {
 });
 
 describe("extractCategory", () => {
-  it("extracts category from two-segment path", () => {
+  it("extracts category from two-fragment path", () => {
     expect(extractCategory("Components/Button")).toBe("components");
   });
 
-  it("extracts category from multi-segment path", () => {
+  it("extracts category from multi-fragment path", () => {
     expect(extractCategory("Design System/Forms/Input")).toBe("forms");
   });
 
@@ -254,7 +254,7 @@ describe("extractCategory", () => {
     expect(extractCategory("UI/Forms/Select")).toBe("forms");
   });
 
-  it("returns 'components' for single segment", () => {
+  it("returns 'components' for single fragment", () => {
     expect(extractCategory("Button")).toBe("components");
   });
 

package/src/migrate/bin.ts

@@ -2,7 +2,7 @@
 /**
  * CLI entry point for migration tool.
  *
- * Can be run standalone or integrated with the main segments CLI.
+ * Can be run standalone or integrated with the main fragments CLI.
  */
 
 import { Command } from "commander";
@@ -19,17 +19,17 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-
 const program = new Command();
 
 program
-  .name("segments-migrate")
+  .name("fragments-migrate")
   .description(`${BRAND.name} Storybook Migration Tool`)
   .version(pkg.version);
 
 program
   .command("migrate")
-  .description("Migrate Storybook stories to Segments")
+  .description("Migrate Storybook stories to Fragments")
   .argument("<source>", "Source directory or file containing .stories.tsx files")
   .option("-o, --output <dir>", "Output directory (default: same as source)")
   .option("--dry-run", "Show what would be generated without writing files")
-  .option("--overwrite", "Overwrite existing segment files")
+  .option("--overwrite", "Overwrite existing fragment files")
   .option("--report", "Generate HTML migration report")
   .option("--report-path <path>", "Path for the migration report")
   .option("-v, --verbose", "Verbose output")