@fragments-sdk/cli 0.4.3 → 0.5.0

package/dist/mcp-bin.js

@@ -2,11 +2,11 @@
 import { createRequire } from 'module'; const require = createRequire(import.meta.url);
 import {
   generateContext
-} from "./chunk-G3M3MPQ6.js";
+} from "./chunk-B2TQKOLW.js";
 import {
   BRAND,
   DEFAULTS
-} from "./chunk-AW7MWOUH.js";
+} from "./chunk-ICAIQ57V.js";
 
 // src/mcp/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -57,7 +57,7 @@ var _service = null;
 async function getService() {
   if (!_service) {
     try {
-      _service = await import("./service-K52ORLCJ.js");
+      _service = await import("./service-2T26CBWE.js");
     } catch {
       throw new Error(
         "Visual tools require playwright. Install it with: npm install playwright"
@@ -69,7 +69,9 @@ async function getService() {
 var TOOL_NAMES = {
   discover: `${BRAND.nameLower}_discover`,
   inspect: `${BRAND.nameLower}_inspect`,
-  recipe: `${BRAND.nameLower}_recipe`,
+  blocks: `${BRAND.nameLower}_blocks`,
+  tokens: `${BRAND.nameLower}_tokens`,
+  implement: `${BRAND.nameLower}_implement`,
   render: `${BRAND.nameLower}_render`,
   fix: `${BRAND.nameLower}_fix`
 };
@@ -279,26 +281,61 @@ var TOOLS = [
     }
   },
   {
-    name: TOOL_NAMES.recipe,
-    description: `Search and retrieve composition recipes \u2014 named patterns showing how design system components wire together for common use cases (e.g., "Login Form", "Settings Page"). Returns the recipe with its code pattern.`,
+    name: TOOL_NAMES.blocks,
+    description: `Search and retrieve composition blocks \u2014 named patterns showing how design system components wire together for common use cases (e.g., "Login Form", "Settings Page"). Returns the block with its code pattern.`,
     inputSchema: {
       type: "object",
       properties: {
         name: {
           type: "string",
-          description: 'Exact recipe name to retrieve (e.g., "Login Form")'
+          description: 'Exact block name to retrieve (e.g., "Login Form")'
         },
         search: {
           type: "string",
-          description: "Free-text search across recipe names, descriptions, tags, and components"
+          description: "Free-text search across block names, descriptions, tags, and components"
         },
         component: {
           type: "string",
-          description: 'Filter recipes that use a specific component (e.g., "Button")'
+          description: 'Filter blocks that use a specific component (e.g., "Button")'
+        },
+        category: {
+          type: "string",
+          description: 'Filter by category (e.g., "authentication", "marketing", "dashboard", "settings", "ecommerce", "ai")'
         }
       }
     }
   },
+  {
+    name: TOOL_NAMES.tokens,
+    description: `List available CSS design tokens (custom properties) by category. Use this when you need to style custom elements or override defaults \u2014 no more guessing variable names. Filter by category or search by keyword.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description: 'Filter by category (e.g., "colors", "spacing", "typography", "surfaces", "shadows", "radius", "borders", "text", "focus", "layout", "code", "component-sizing")'
+        },
+        search: {
+          type: "string",
+          description: 'Search token names (e.g., "accent", "hover", "padding")'
+        }
+      }
+    }
+  },
+  {
+    name: TOOL_NAMES.implement,
+    description: `One-shot implementation helper. Describe what you want to build and get everything needed in a single call: best-matching component(s) with full props and code examples, relevant composition blocks, and applicable CSS tokens. Saves multiple round-trips.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        useCase: {
+          type: "string",
+          description: 'What you want to implement (e.g., "login form", "data table with sorting", "streaming chat messages")'
+        }
+      },
+      required: ["useCase"]
+    }
+  },
   {
     name: TOOL_NAMES.render,
     description: `Render a component and return a screenshot. Optionally compare against a stored baseline ('baseline: true') or against a Figma design ('figmaUrl'). Use this to verify your implementation looks correct.`,
@@ -383,7 +420,8 @@ function createMcpServer(config) {
     }
   );
   let segmentsData = null;
-  let packageName = null;
+  const segmentPackageMap = /* @__PURE__ */ new Map();
+  let defaultPackageName = null;
   let browserPool = null;
   let storageManager = null;
   let diffEngine = null;
@@ -400,23 +438,41 @@ function createMcpServer(config) {
     }
     const content = await readFile(paths[0], "utf-8");
     segmentsData = JSON.parse(content);
+    if (!segmentsData.blocks && segmentsData.recipes) {
+      segmentsData.blocks = segmentsData.recipes;
+    }
+    if (segmentsData.packageName) {
+      for (const name of Object.keys(segmentsData.segments)) {
+        segmentPackageMap.set(name, segmentsData.packageName);
+      }
+    }
     for (let i = 1; i < paths.length; i++) {
       const extra = JSON.parse(await readFile(paths[i], "utf-8"));
+      if (extra.packageName) {
+        for (const name of Object.keys(extra.segments)) {
+          segmentPackageMap.set(name, extra.packageName);
+        }
+      }
       Object.assign(segmentsData.segments, extra.segments);
-      if (extra.recipes) {
-        segmentsData.recipes = { ...segmentsData.recipes, ...extra.recipes };
+      const extraBlocks = extra.blocks ?? extra.recipes;
+      if (extraBlocks) {
+        segmentsData.blocks = { ...segmentsData.blocks, ...extraBlocks };
       }
     }
     return segmentsData;
   }
-  async function getPackageName() {
-    if (packageName) {
-      return packageName;
+  async function getPackageName(segmentName) {
+    await loadSegments();
+    if (segmentName) {
+      const segPkg = segmentPackageMap.get(segmentName);
+      if (segPkg) return segPkg;
     }
-    const data = await loadSegments();
-    if (data.packageName) {
-      packageName = data.packageName;
-      return packageName;
+    if (defaultPackageName) {
+      return defaultPackageName;
+    }
+    if (segmentsData?.packageName) {
+      defaultPackageName = segmentsData.packageName;
+      return defaultPackageName;
     }
     const packageJsonPath = join(config.projectRoot, "package.json");
     if (existsSync(packageJsonPath)) {
@@ -424,14 +480,14 @@ function createMcpServer(config) {
         const content = await readFile(packageJsonPath, "utf-8");
         const pkg = JSON.parse(content);
         if (pkg.name) {
-          packageName = pkg.name;
-          return packageName;
+          defaultPackageName = pkg.name;
+          return defaultPackageName;
         }
       } catch {
       }
     }
-    packageName = "your-component-library";
-    return packageName;
+    defaultPackageName = "your-component-library";
+    return defaultPackageName;
   }
   async function getBrowserPool() {
     if (!browserPool) {
@@ -501,7 +557,7 @@ function createMcpServer(config) {
           const includeRelations = args2?.includeRelations ?? false;
           if (compact || args2?.format && !useCase && !componentForAlts && !category && !search && !status) {
             const segments2 = Object.values(data.segments);
-            const recipes = Object.values(data.recipes ?? {});
+            const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
             const { content: ctxContent, tokenEstimate } = generateContext(segments2, {
               format,
               compact,
@@ -509,7 +565,7 @@ function createMcpServer(config) {
                 code: includeCode,
                 relations: includeRelations
               }
-            }, recipes);
+            }, allBlocks);
             return {
               content: [{
                 type: "text",
@@ -635,6 +691,22 @@ function createMcpServer(config) {
               }
             }
             const compositionHint = suggestions.length >= 2 ? `These components work well together. For example, ${suggestions[0].component} can be combined with ${suggestions.slice(1, 3).map((s) => s.component).join(" and ")}.` : void 0;
+            const STYLE_KEYWORDS = ["color", "spacing", "padding", "margin", "font", "border", "radius", "shadow", "variable", "token", "css", "theme", "dark mode", "background", "hover"];
+            const isStyleQuery = STYLE_KEYWORDS.some((kw) => useCaseLower.includes(kw));
+            const noMatch = suggestions.length === 0;
+            const weakMatch = !noMatch && suggestions.every((s) => s.confidence === "low");
+            let recommendation;
+            let nextStep;
+            if (noMatch) {
+              recommendation = isStyleQuery ? `No matching components found. Your query seems styling-related \u2014 try ${TOOL_NAMES.tokens} to find CSS custom properties.` : "No matching components found. Try different keywords or browse all components with fragments_discover.";
+              nextStep = isStyleQuery ? `Use ${TOOL_NAMES.tokens}(search: "${searchTerms[0]}") to find design tokens.` : void 0;
+            } else if (weakMatch) {
+              recommendation = `Weak matches only \u2014 ${suggestions[0].component} might work but confidence is low.${isStyleQuery ? ` If you need a CSS variable, try ${TOOL_NAMES.tokens}.` : ""}`;
+              nextStep = `Use ${TOOL_NAMES.inspect}("${suggestions[0].component}") to check if it fits, or try broader search terms.`;
+            } else {
+              recommendation = `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`;
+              nextStep = `Use ${TOOL_NAMES.inspect}("${suggestions[0].component}") for full details.`;
+            }
             return {
               content: [{
                 type: "text",
@@ -642,9 +714,11 @@ function createMcpServer(config) {
                   useCase,
                   context: context || void 0,
                   suggestions: suggestions.map(({ score, ...rest }) => rest),
-                  recommendation: suggestions.length > 0 ? `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}` : "No matching components found. Try different keywords or browse with fragments_discover.",
+                  noMatch,
+                  weakMatch,
+                  recommendation,
                   compositionHint,
-                  nextStep: suggestions.length > 0 ? `Use fragments_inspect("${suggestions[0].component}") for full details.` : void 0
+                  nextStep
                 }, null, 2)
               }]
             };
@@ -737,14 +811,29 @@ function createMcpServer(config) {
           if (!segment) {
             throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
           }
-          const pkgName = await getPackageName();
+          const pkgName = await getPackageName(segment.meta.name);
           let variants = segment.variants;
           if (variantName) {
-            const filtered = variants.filter(
-              (v) => v.name.toLowerCase() === variantName.toLowerCase()
+            const query = variantName.toLowerCase();
+            let filtered = variants.filter(
+              (v) => v.name.toLowerCase() === query
             );
+            if (filtered.length === 0) {
+              filtered = variants.filter(
+                (v) => v.name.toLowerCase().startsWith(query)
+              );
+            }
+            if (filtered.length === 0) {
+              filtered = variants.filter(
+                (v) => v.name.toLowerCase().includes(query)
+              );
+            }
             if (filtered.length > 0) {
               variants = filtered;
+            } else {
+              throw new Error(
+                `Variant "${variantName}" not found for ${componentName}. Available: ${segment.variants.map((v) => v.name).join(", ")}`
+              );
             }
           }
           if (maxExamples && maxExamples > 0) {
@@ -818,47 +907,53 @@ function createMcpServer(config) {
           };
         }
         // ================================================================
-        // RECIPE — unchanged
+        // BLOCKS — composition patterns
         // ================================================================
-        case TOOL_NAMES.recipe: {
+        case TOOL_NAMES.blocks: {
           const data = await loadSegments();
-          const recipeName = args2?.name;
+          const blockName = args2?.name;
           const search = args2?.search?.toLowerCase() ?? void 0;
           const component = args2?.component?.toLowerCase() ?? void 0;
-          const allRecipes = Object.values(data.recipes ?? {});
-          if (allRecipes.length === 0) {
+          const category = args2?.category?.toLowerCase() ?? void 0;
+          const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
+          if (allBlocks.length === 0) {
             return {
               content: [{
                 type: "text",
                 text: JSON.stringify({
                   total: 0,
-                  recipes: [],
-                  hint: `No recipes found. Run \`${BRAND.cliCommand} build\` after adding .recipe.ts files.`
+                  blocks: [],
+                  hint: `No blocks found. Run \`${BRAND.cliCommand} build\` after adding .block.ts files.`
                 }, null, 2)
               }]
             };
           }
-          let filtered = allRecipes;
-          if (recipeName) {
+          let filtered = allBlocks;
+          if (blockName) {
             filtered = filtered.filter(
-              (r) => r.name.toLowerCase() === recipeName.toLowerCase()
+              (b) => b.name.toLowerCase() === blockName.toLowerCase()
             );
           }
           if (search) {
-            filtered = filtered.filter((r) => {
+            filtered = filtered.filter((b) => {
               const haystack = [
-                r.name,
-                r.description,
-                ...r.tags ?? [],
-                ...r.components,
-                r.category
+                b.name,
+                b.description,
+                ...b.tags ?? [],
+                ...b.components,
+                b.category
               ].join(" ").toLowerCase();
               return haystack.includes(search);
             });
           }
           if (component) {
             filtered = filtered.filter(
-              (r) => r.components.some((c) => c.toLowerCase() === component)
+              (b) => b.components.some((c) => c.toLowerCase() === component)
+            );
+          }
+          if (category) {
+            filtered = filtered.filter(
+              (b) => b.category.toLowerCase() === category
             );
           }
           return {
@@ -866,7 +961,172 @@ function createMcpServer(config) {
               type: "text",
               text: JSON.stringify({
                 total: filtered.length,
-                recipes: filtered
+                blocks: filtered
+              }, null, 2)
+            }]
+          };
+        }
+        // ================================================================
+        // TOKENS — list CSS custom properties by category
+        // ================================================================
+        case TOOL_NAMES.tokens: {
+          const data = await loadSegments();
+          const category = args2?.category?.toLowerCase() ?? void 0;
+          const search = args2?.search?.toLowerCase() ?? void 0;
+          const tokenData = data.tokens;
+          if (!tokenData || tokenData.total === 0) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  total: 0,
+                  categories: {},
+                  hint: `No design tokens found. Add a tokens.include pattern to your ${BRAND.configFile} and run \`${BRAND.cliCommand} build\`.`
+                }, null, 2)
+              }]
+            };
+          }
+          let filteredCategories = {};
+          let filteredTotal = 0;
+          for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+            if (category && cat !== category) continue;
+            let filtered = tokens;
+            if (search) {
+              filtered = tokens.filter(
+                (t) => t.name.toLowerCase().includes(search) || t.description && t.description.toLowerCase().includes(search)
+              );
+            }
+            if (filtered.length > 0) {
+              filteredCategories[cat] = filtered;
+              filteredTotal += filtered.length;
+            }
+          }
+          let hint;
+          if (filteredTotal === 0) {
+            const availableCategories = Object.keys(tokenData.categories);
+            hint = search ? `No tokens matching "${search}". Try: ${availableCategories.join(", ")}` : category ? `Category "${category}" not found. Available: ${availableCategories.join(", ")}` : void 0;
+          } else if (!category && !search) {
+            hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                prefix: tokenData.prefix,
+                total: filteredTotal,
+                totalAvailable: tokenData.total,
+                categories: filteredCategories,
+                ...hint && { hint },
+                ...!category && !search && {
+                  availableCategories: Object.entries(tokenData.categories).map(
+                    ([cat, tokens]) => ({ category: cat, count: tokens.length })
+                  )
+                }
+              }, null, 2)
+            }]
+          };
+        }
+        // ================================================================
+        // IMPLEMENT — one-shot discover + inspect + blocks + tokens
+        // ================================================================
+        case TOOL_NAMES.implement: {
+          const data = await loadSegments();
+          const useCase = args2?.useCase;
+          if (!useCase) {
+            throw new Error("useCase is required");
+          }
+          const useCaseLower = useCase.toLowerCase();
+          const searchTerms = useCaseLower.split(/\s+/).filter(Boolean);
+          const synonymMap = {
+            "form": ["input", "field", "submit", "validation"],
+            "input": ["form", "field", "text", "entry"],
+            "button": ["action", "click", "submit", "trigger"],
+            "alert": ["notification", "message", "warning", "error", "feedback"],
+            "notification": ["alert", "message", "toast"],
+            "card": ["container", "panel", "box", "content"],
+            "toggle": ["switch", "checkbox", "boolean"],
+            "badge": ["tag", "label", "status", "indicator"],
+            "login": ["auth", "signin", "authentication", "form"],
+            "chat": ["message", "conversation", "ai"],
+            "table": ["data", "grid", "list", "rows"]
+          };
+          const expandedTerms = new Set(searchTerms);
+          searchTerms.forEach((term) => {
+            const synonyms = synonymMap[term];
+            if (synonyms) synonyms.forEach((syn) => expandedTerms.add(syn));
+          });
+          const scored = Object.values(data.segments).map((s) => {
+            let score = 0;
+            const nameLower = s.meta.name.toLowerCase();
+            if (searchTerms.some((t) => nameLower.includes(t))) score += 15;
+            else if (Array.from(expandedTerms).some((t) => nameLower.includes(t))) score += 8;
+            const desc = s.meta.description?.toLowerCase() ?? "";
+            score += searchTerms.filter((t) => desc.includes(t)).length * 6;
+            const tags = s.meta.tags?.map((t) => t.toLowerCase()) ?? [];
+            score += searchTerms.filter((t) => tags.some((tag) => tag.includes(t))).length * 4;
+            const whenUsed = s.usage?.when?.join(" ").toLowerCase() ?? "";
+            score += searchTerms.filter((t) => whenUsed.includes(t)).length * 10;
+            score += Array.from(expandedTerms).filter((t) => !searchTerms.includes(t) && whenUsed.includes(t)).length * 5;
+            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 };
+          });
+          const topMatches = scored.filter((s) => s.score >= 8).sort((a, b) => b.score - a.score).slice(0, 3);
+          const components = await Promise.all(
+            topMatches.map(async ({ segment: s, score }) => {
+              const pkgName = await getPackageName(s.meta.name);
+              const examples = s.variants.slice(0, 2).map((v) => ({
+                variant: v.name,
+                code: v.code ?? `<${s.meta.name} />`
+              }));
+              const propsSummary = Object.entries(s.props ?? {}).slice(0, 10).map(
+                ([name2, p]) => `${name2}${p.required ? " (required)" : ""}: ${p.type}${p.values ? ` = ${p.values.join("|")}` : ""}`
+              );
+              return {
+                name: s.meta.name,
+                category: s.meta.category,
+                description: s.meta.description,
+                confidence: score >= 25 ? "high" : score >= 15 ? "medium" : "low",
+                import: `import { ${s.meta.name} } from '${pkgName}';`,
+                props: propsSummary,
+                examples,
+                guidelines: filterPlaceholders(s.usage?.when).slice(0, 3),
+                accessibility: s.usage?.accessibility?.slice(0, 2) ?? []
+              };
+            })
+          );
+          const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
+          const matchingBlocks = allBlocks.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()));
+          }).slice(0, 2).map((b) => ({ name: b.name, description: b.description, components: b.components, code: b.code }));
+          const tokenData = data.tokens;
+          let relevantTokens;
+          if (tokenData) {
+            const STYLE_KEYWORDS = ["color", "spacing", "padding", "margin", "font", "border", "radius", "shadow", "background", "hover", "theme"];
+            const styleTerms = searchTerms.filter((t) => STYLE_KEYWORDS.includes(t));
+            if (styleTerms.length > 0) {
+              relevantTokens = {};
+              for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+                const matching = tokens.filter((t) => styleTerms.some((st) => t.name.includes(st) || cat.includes(st)));
+                if (matching.length > 0) {
+                  relevantTokens[cat] = matching.map((t) => t.name);
+                }
+              }
+              if (Object.keys(relevantTokens).length === 0) relevantTokens = void 0;
+            }
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                useCase,
+                components,
+                blocks: matchingBlocks.length > 0 ? matchingBlocks : void 0,
+                tokens: relevantTokens,
+                noMatch: components.length === 0,
+                summary: components.length > 0 ? `Found ${components.length} component(s) for "${useCase}". ${matchingBlocks.length > 0 ? `Plus ${matchingBlocks.length} ready-to-use block(s).` : ""}` : `No components match "${useCase}". Try ${TOOL_NAMES.discover} with different terms${tokenData ? ` or ${TOOL_NAMES.tokens} for CSS variables` : ""}.`
               }, null, 2)
             }]
           };