@fragments-sdk/mcp 0.7.1 → 0.8.1

package/dist/bin.js

@@ -4,7 +4,7 @@ import {
   resolveDataAdapter,
   resolveSearchApiKey,
   startMcpServer
-} from "./chunk-HGGAXLRO.js";
+} from "./chunk-6JMX4AMO.js";
 import "./chunk-4SVS3AA3.js";
 import "./chunk-YSRGQDEB.js";
 

package/dist/{chunk-HGGAXLRO.js → chunk-6JMX4AMO.js}

@@ -2462,6 +2462,205 @@ var governHandler = async (args, ctx) => {
   }
 };
 
+// src/tools/validate-and-fix.ts
+import {
+  formatVerdict as formatVerdict2,
+  fragments as fragmentsPreset2,
+  handleGovernTool as handleGovernTool2,
+  universal as universal2
+} from "@fragments-sdk/govern";
+function classifyComponent(component) {
+  if (component.status === "deprecated") return "discouraged";
+  if (component.isCanonical && component.tier === "core") return "preferred";
+  return "allowed";
+}
+function buildEffectiveComponents(ctx) {
+  const selectionByKey = new Map(
+    (ctx.data.validateFixContext?.components ?? []).map((component) => [
+      component.componentKey,
+      component.selection
+    ])
+  );
+  return Object.entries(ctx.data.components).map(([componentKey, component]) => ({
+    component,
+    selection: selectionByKey.get(componentKey) ?? classifyComponent(component)
+  }));
+}
+function cloneSpec(spec) {
+  return structuredClone(spec);
+}
+function getSelectionNames(effectiveComponents, selection) {
+  const selections = Array.isArray(selection) ? selection : [selection];
+  return Array.from(
+    new Set(
+      effectiveComponents.filter((entry) => selections.includes(entry.selection)).map((entry) => entry.component.name)
+    )
+  );
+}
+function buildBasePolicy(ctx) {
+  const tokenPrefix = ctx.data.tokens?.prefix;
+  const basePolicy = tokenPrefix === "fui-" ? { rules: fragmentsPreset2().rules } : { rules: universal2().rules };
+  const allowedComponents = buildEffectiveComponents(ctx).filter(({ selection }) => selection === "preferred" || selection === "allowed").map(({ component }) => component.name);
+  basePolicy.rules["components/allow"] = {
+    enabled: true,
+    severity: "serious",
+    options: {
+      components: allowedComponents
+    }
+  };
+  return basePolicy;
+}
+async function runGovern(spec, ctx, policyOverrides) {
+  const input = {
+    spec,
+    policy: policyOverrides,
+    format: "json"
+  };
+  const engineOptions = ctx.data.tokens ? { tokenData: ctx.data.tokens } : void 0;
+  return handleGovernTool2(input, buildBasePolicy(ctx), engineOptions);
+}
+function applyDeterministicReplacements(spec, ctx) {
+  const effectiveComponents = buildEffectiveComponents(ctx);
+  const byName = /* @__PURE__ */ new Map();
+  const preferredByCategory = /* @__PURE__ */ new Map();
+  for (const entry of effectiveComponents) {
+    const list = byName.get(entry.component.name) ?? [];
+    list.push(entry);
+    byName.set(entry.component.name, list);
+    if (entry.selection !== "preferred") continue;
+    const category = entry.component.category ?? "uncategorized";
+    const names = preferredByCategory.get(category) ?? [];
+    if (!names.includes(entry.component.name)) {
+      names.push(entry.component.name);
+    }
+    preferredByCategory.set(category, names);
+  }
+  const fixedSpec = cloneSpec(spec);
+  const nodes = Array.isArray(fixedSpec.nodes) ? fixedSpec.nodes : [];
+  const replacements = [];
+  for (const node of nodes) {
+    if (!node.type) continue;
+    const componentEntries = byName.get(node.type) ?? [];
+    const component = componentEntries[0];
+    if (!component || component.selection !== "discouraged" && component.selection !== "forbidden") {
+      continue;
+    }
+    const candidates = (preferredByCategory.get(component.component.category ?? "uncategorized") ?? []).filter((candidate) => candidate !== component.component.name);
+    if (candidates.length !== 1) continue;
+    const replacement = candidates[0];
+    replacements.push({
+      nodeId: node.id ?? node.type,
+      from: component.component.name,
+      to: replacement,
+      reason: "deprecated_component"
+    });
+    node.type = replacement;
+  }
+  return {
+    fixedSpec,
+    replacements
+  };
+}
+function buildSummary(args) {
+  const lines = [
+    `status: ${args.status}`,
+    `original: ${formatVerdict2(args.originalVerdict, "summary")}`
+  ];
+  if (args.replacements.length > 0) {
+    lines.push(
+      `replacements: ${args.replacements.map((item) => `${item.from} -> ${item.to}`).join(", ")}`
+    );
+    lines.push(`final: ${formatVerdict2(args.finalVerdict, "summary")}`);
+  }
+  return lines.join("\n");
+}
+var validateAndFixHandler = async (args, ctx) => {
+  const spec = args?.spec;
+  if (!spec || typeof spec !== "object") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "spec is required and must be an object with { nodes: [{ id, type, props, children }] }"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const policyOverrides = args?.policy;
+  const applyFixes = args?.applyFixes !== false;
+  const format = args?.format ?? "json";
+  try {
+    const effectiveComponents = buildEffectiveComponents(ctx);
+    const originalVerdict = await runGovern(spec, ctx, policyOverrides);
+    let finalVerdict = originalVerdict;
+    let fixedSpec;
+    let replacements = [];
+    if (!originalVerdict.passed && applyFixes) {
+      const result = applyDeterministicReplacements(
+        spec,
+        ctx
+      );
+      replacements = result.replacements;
+      fixedSpec = result.fixedSpec;
+      if (replacements.length > 0) {
+        finalVerdict = await runGovern(fixedSpec, ctx, policyOverrides);
+      }
+    }
+    const status = originalVerdict.passed ? "pass" : replacements.length > 0 ? "fixed" : "fail";
+    const payload = {
+      status,
+      applyFixes,
+      replacements,
+      originalVerdict,
+      finalVerdict,
+      ...fixedSpec ? { fixedSpec } : {},
+      preferredComponents: getSelectionNames(
+        effectiveComponents,
+        "preferred"
+      ),
+      discouragedComponents: getSelectionNames(effectiveComponents, [
+        "discouraged",
+        "forbidden"
+      ])
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: format === "summary" ? buildSummary({
+            status,
+            originalVerdict,
+            finalVerdict,
+            replacements
+          }) : JSON.stringify(payload)
+        }
+      ],
+      _meta: {
+        status,
+        replacementCount: replacements.length,
+        passed: finalVerdict.passed
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isSpecError = message.includes("Expected") || message.includes("Required");
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: isSpecError ? `Invalid spec format: ${message}. Expected: { nodes: [{ id: string, type: string, props: object, children?: string[] }] }` : message
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
 // src/tools/generate-ui.ts
 var generateUiHandler = async (args, ctx) => {
   const prompt = args?.prompt;
@@ -2491,6 +2690,142 @@ var generateUiHandler = async (args, ctx) => {
   };
 };
 
+// src/findings-service.ts
+var DEFAULT_CLOUD_URL = "https://app.usefragments.com";
+function normalizeCloudUrl(url) {
+  if (!url) return DEFAULT_CLOUD_URL;
+  return url.replace(/\/+$/, "");
+}
+async function fetchFindings(apiKey, params, cloudUrl) {
+  const base = normalizeCloudUrl(cloudUrl);
+  const url = new URL(`${base}/api/findings`);
+  if (params.status) url.searchParams.set("status", params.status);
+  if (params.severity) url.searchParams.set("severity", params.severity);
+  if (params.category) url.searchParams.set("category", params.category);
+  if (params.ruleId) url.searchParams.set("ruleId", params.ruleId);
+  if (params.filePath) url.searchParams.set("filePath", params.filePath);
+  if (params.limit != null) url.searchParams.set("limit", String(params.limit));
+  const response = await fetch(url.toString(), {
+    headers: { "X-API-Key": apiKey }
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    let message;
+    try {
+      const parsed = JSON.parse(body);
+      message = parsed.error ?? body;
+    } catch {
+      message = body;
+    }
+    throw new Error(
+      `Cloud findings API error (${response.status}): ${message}`
+    );
+  }
+  return await response.json();
+}
+async function fetchFindingsForFile(apiKey, filePath, cloudUrl) {
+  return fetchFindings(
+    apiKey,
+    { status: "open", filePath, limit: 200 },
+    cloudUrl
+  );
+}
+
+// src/tools/findings.ts
+function resolveCloudApiKey(ctx) {
+  return ctx.config.cloudApiKey ?? ctx.config.fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
+}
+function resolveCloudUrl(ctx) {
+  return ctx.config.fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
+}
+function missingKeyError() {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: "Cloud API key required. Set FRAGMENTS_API_KEY env var, pass --cloud-api-key, or configure cloud.apiKey in ds-mcp.config.json."
+        })
+      }
+    ],
+    isError: true
+  };
+}
+var findingsListHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const cloudUrl = resolveCloudUrl(ctx);
+  const params = {};
+  if (args.status) params.status = args.status;
+  if (args.severity)
+    params.severity = args.severity;
+  if (args.category) params.category = String(args.category);
+  if (args.ruleId) params.ruleId = String(args.ruleId);
+  if (args.filePath) params.filePath = String(args.filePath);
+  if (args.limit != null) params.limit = Number(args.limit);
+  try {
+    const result = await fetchFindings(apiKey, params, cloudUrl);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result) }],
+      _meta: { count: result.findings.length }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+var findingsForFileHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const filePath = args.filePath;
+  if (!filePath || typeof filePath !== "string") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: "filePath is required." })
+        }
+      ],
+      isError: true
+    };
+  }
+  const cloudUrl = resolveCloudUrl(ctx);
+  try {
+    const result = await fetchFindingsForFile(apiKey, filePath, cloudUrl);
+    const findings = result.findings.filter((f) => f.filePath === filePath);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ findings, filePath })
+        }
+      ],
+      _meta: { count: findings.length, filePath }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
 // src/tools/index.ts
 var CORE_TOOLS = {
   discover: discoverHandler,
@@ -2499,7 +2834,10 @@ var CORE_TOOLS = {
   tokens: tokensHandler,
   graph: graphHandler,
   perf: perfHandler,
-  govern: governHandler
+  govern: governHandler,
+  validate_and_fix: validateAndFixHandler,
+  findings_list: findingsListHandler,
+  findings_for_file: findingsForFileHandler
 };
 var VIEWER_TOOLS = {
   render: renderHandler,
@@ -2521,6 +2859,7 @@ var TOOL_CAPABILITIES = {
   tokens: ["tokens"],
   graph: ["graph"],
   perf: ["performance"],
+  validate_and_fix: ["components"],
   render: ["components"],
   fix: ["components"],
   a11y: ["components"]
@@ -3782,7 +4121,7 @@ function readPackageName(projectRoot) {
 }
 
 // src/adapters/cloud-catalog.ts
-var DEFAULT_CLOUD_URL = "https://app.usefragments.com/api/catalog";
+var DEFAULT_CLOUD_URL2 = "https://app.usefragments.com/api/catalog";
 var TOKEN_CATEGORY_ALIASES2 = {
   color: ["color", "colors", "accent", "background", "foreground", "danger", "brand"],
   spacing: ["spacing", "space", "padding", "margin", "gap", "inset"],
@@ -3795,10 +4134,14 @@ var TOKEN_CATEGORY_ALIASES2 = {
   surface: ["surface", "surfaces", "canvas", "card", "background"]
 };
 function normalizeCatalogUrl(url) {
-  if (!url) return DEFAULT_CLOUD_URL;
+  if (!url) return DEFAULT_CLOUD_URL2;
   if (url.endsWith("/api/catalog")) return url;
   return `${url.replace(/\/+$/, "")}/api/catalog`;
 }
+function normalizeValidateFixUrl(url) {
+  const base = normalizeCatalogUrl(url).replace(/\/api\/catalog$/, "");
+  return `${base}/api/context?target=validate-fix`;
+}
 function normalizeValue(value) {
   return value?.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim() ?? "";
 }
@@ -3917,17 +4260,54 @@ function mapComponent(component, designSystem) {
     }
   };
 }
+function normalizeValidateFixContext(raw) {
+  const content = raw.content;
+  if (!content || !Array.isArray(content.components)) {
+    return void 0;
+  }
+  const components = content.components.filter(
+    (component) => Boolean(component?.componentKey) && Boolean(component?.publicRef) && Boolean(component?.name) && Boolean(component?.selection)
+  ).map((component) => ({
+    componentKey: component.componentKey,
+    publicRef: component.publicRef,
+    name: component.name,
+    category: component.category ?? "uncategorized",
+    status: component.status ?? "stable",
+    tier: component.tier ?? "composition",
+    isCanonical: component.isCanonical ?? false,
+    isActive: component.isActive ?? true,
+    selection: component.selection ?? "allowed",
+    reasons: component.reasons ?? [],
+    usageGuidance: component.usageGuidance,
+    dos: component.dos ?? [],
+    donts: component.donts ?? []
+  }));
+  return {
+    version: 1,
+    catalogRevision: content.catalogRevision,
+    updatedAt: content.updatedAt,
+    policy: {
+      mode: "cloud",
+      endpoint: content.policy?.endpoint ?? "/api/govern/policy"
+    },
+    components
+  };
+}
 var CloudCatalogAdapter = class {
   constructor(options) {
     this.options = options;
   }
   name = "cloud";
   async load(_projectRoot) {
-    const response = await fetch(normalizeCatalogUrl(this.options.url), {
-      headers: {
-        "X-API-Key": this.options.apiKey
-      }
-    });
+    const headers = {
+      "X-API-Key": this.options.apiKey
+    };
+    const [response, validateFixResponse] = await Promise.all([
+      fetch(normalizeCatalogUrl(this.options.url), { headers }),
+      fetch(normalizeValidateFixUrl(this.options.url), { headers }).catch(
+        () => null
+      )
+    ]);
     if (!response.ok) {
       throw new Error(
         `Failed to load Cloud catalog (${response.status} ${response.statusText}).`
@@ -3969,6 +4349,9 @@ var CloudCatalogAdapter = class {
       packageMap,
       defaultPackageName: packageName
     });
+    const validateFixContext = validateFixResponse && validateFixResponse.ok ? normalizeValidateFixContext(
+      await validateFixResponse.json()
+    ) : void 0;
     const hydratedComponents = Object.fromEntries(
       Object.entries(snapshot.components).map(([componentId, component]) => [
         componentId,
@@ -3990,6 +4373,7 @@ var CloudCatalogAdapter = class {
       performanceSummary: void 0,
       packageMap: snapshot.packageMap,
       defaultPackageName: snapshot.defaultPackageName,
+      validateFixContext,
       capabilities: new Set(snapshot.capabilities)
     };
   }
@@ -4224,10 +4608,10 @@ var BundleAdapter = class {
 };
 
 // src/source-selection.ts
-function resolveCloudApiKey(config, fileConfig) {
+function resolveCloudApiKey2(config, fileConfig) {
   return config.cloudApiKey ?? fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
 }
-function resolveCloudUrl(fileConfig) {
+function resolveCloudUrl2(fileConfig) {
   return fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
 }
 function hasTsProject(projectRoot) {
@@ -4237,8 +4621,8 @@ function resolveDataAdapter(config, fileConfig) {
   const source = config.source ?? fileConfig?.source ?? "auto";
   const fragmentsJsonPaths = findFragmentsJson(config.projectRoot);
   const bundleManifestPaths = findBundleManifest(config.projectRoot);
-  const cloudApiKey = resolveCloudApiKey(config, fileConfig);
-  const cloudUrl = resolveCloudUrl(fileConfig);
+  const cloudApiKey = resolveCloudApiKey2(config, fileConfig);
+  const cloudUrl = resolveCloudUrl2(fileConfig);
   switch (source) {
     case "fragments-json":
       return { adapter: new FragmentsJsonAdapter(), mode: "fragments-json" };
@@ -4498,4 +4882,4 @@ export {
   startMcpServer,
   createSandboxServer
 };
-//# sourceMappingURL=chunk-HGGAXLRO.js.map
+//# sourceMappingURL=chunk-6JMX4AMO.js.map