@carto/meridian-ds 3.0.3-alpha.cdb2a4e.260 → 3.0.3-alpha.dd2ac14.266

package/dist/bin/meridian-ds-mcp.js

@@ -5,6 +5,16 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
+
+// ai-metadata/types.ts
+function subName(s) {
+  return typeof s === "string" ? s : s.name;
+}
+function relatedName(e) {
+  return typeof e === "string" ? e : e.name;
+}
+
+// ai-metadata/mcp/server.ts
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
 function resolveBundlePath() {
   if (process.env.MERIDIAN_DS_METADATA) return process.env.MERIDIAN_DS_METADATA;
@@ -26,7 +36,7 @@ var VERSION = "0.0.0";
 var TOOLS = [
   {
     name: "meridian_list_components",
-    description: "List all Meridian components with their description, keywords, and example count, plus a family signal where relevant (`subComponents` for a compound component, `variants` for sibling components chosen between). Start here: the catalog is small, so read it and pick the component whose description/keywords match your need.",
+    description: "List all Meridian components with their description and keywords, plus a family signal where relevant (`subComponents` for a compound component, `variants` for sibling components chosen between \u2014 each with a one-line description). Start here: the catalog is small, so read it and pick the component whose description/keywords match your need. Rows flagged `documented: false` are listed-but-not-yet-curated \u2014 they exist and have examples, but get_component carries no when-to-use/decisionTree/prop guidance for them.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -35,7 +45,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_component",
-    description: "Curation for one component: when to use it, its decisionTree (when to reach for a different component), any limitations (capabilities it lacks vs. similar components \u2014 check before downgrading from one), and the high-value inherited MUI props (curation.mui, some with an aiHint). Own props, types, and JSDoc are NOT here \u2014 read the shipped .d.ts (the propTypes field gives the exact command).",
+    description: "Curation for one component: when to use it, its decisionTree (when to reach for a different component), any limitations (capabilities it lacks vs. similar components \u2014 check before downgrading from one), and the high-value inherited MUI props (curation.mui, some with an aiHint). Own props, types, and JSDoc are NOT here \u2014 read the shipped .d.ts (the propTypes field gives the exact command). For a not-yet-curated component (`documented: false`) it returns the examples + .d.ts pointer + a note instead of curation. Sub-components and variants (`DialogHeader`, `MultipleAutocomplete`, \u2026) have no standalone catalog entry \u2014 `meridian_get_component`/`meridian_get_examples` on them return a pointer to the parent (check its `curation.subComponents`/`curation.variants`).",
     inputSchema: {
       type: "object",
       properties: {
@@ -47,7 +57,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_examples",
-    description: "Real, copy-able example code (per Storybook story, with imports), shipped in the package. With no storyId: the lead usage story and the notable stories in full, plus an 'Other Stories' list (name + id) of the rest. Pass a storyId (from that list or meridian_get_component) to get just that story's full code.",
+    description: "Real, copy-able example code (per Storybook story, with imports), shipped in the package. With no storyId: the lead usage story and the notable stories in full, plus an 'Other Stories' list (name + id) of the rest. Pass a storyId (from that list or meridian_get_component) to get just that story's full code. Sub-components and variants (`DialogHeader`, `MultipleAutocomplete`, \u2026) have no standalone catalog entry \u2014 `meridian_get_component`/`meridian_get_examples` on them return a pointer to the parent (check its `curation.subComponents`/`curation.variants`).",
     inputSchema: {
       type: "object",
       properties: {
@@ -75,68 +85,95 @@ var find = (name) => DOCS.find((d) => d.name.toLowerCase() === String(name).toLo
 var notFound = (name) => ({
   error: `Unknown component "${name}". Available: ${DOCS.map((d) => d.name).join(", ")}`
 });
+function dtsFindRecipe(...names) {
+  const root = "find node_modules/@carto/meridian-ds/dist/types";
+  const clauses = names.map((n) => `-name '${n}.d.ts'`);
+  return names.length > 1 ? `${root} \\( ${clauses.join(" -o ")} \\)` : `${root} ${clauses[0]}`;
+}
 function familyRedirect(name) {
   const lc = String(name).toLowerCase();
   for (const d of DOCS) {
-    const isPart = d.curation.subComponents?.some((s) => s.toLowerCase() === lc);
-    const isVariant = d.curation.variants?.some((v) => v.toLowerCase() === lc);
-    if (!isPart && !isVariant) continue;
-    const rel = isPart ? `a sub-component of ${d.name} (a compound component)` : `a variant of ${d.name}`;
-    return {
-      note: `"${name}" is ${rel} and has no standalone catalog entry. See meridian_get_examples('${d.name}') for usage/composition and meridian_get_component('${d.name}') for its curation. Read ${name}'s own props from its type declarations: find node_modules/@carto/meridian-ds/dist/types -name '${name}.d.ts'.`
-    };
+    const part = d.curation.subComponents?.map(subName).find((s) => s.toLowerCase() === lc);
+    const variant = d.curation.variants?.map(subName).find((v) => v.toLowerCase() === lc);
+    const canonical = part ?? variant;
+    if (!canonical) continue;
+    const note = part ? `"${canonical}" is a sub-component of ${d.name} (a compound component) \u2014 it has no standalone catalog entry. See meridian_get_examples('${d.name}') for how it's composed, and read its own props from its type declarations: ${dtsFindRecipe(canonical)}.` : `"${canonical}" is a variant of ${d.name} \u2014 a full component in its own right, not yet individually documented in this catalog. For now use meridian_get_component('${d.name}') / meridian_get_examples('${d.name}'), and read ${canonical}'s own props from its type declarations: ${dtsFindRecipe(canonical)}.`;
+    return { note };
   }
   return void 0;
 }
 function partitionExamples(examples) {
   const usage = examples.filter((e) => e.isUsage);
   const summarized = examples.filter((e) => !e.isUsage && e.summary);
-  let shown = [...usage, ...summarized];
-  if (!shown.length) shown = examples.slice(0, 1);
+  const shown = usage.length ? usage : summarized.length ? summarized : examples.slice(0, 1);
   const inShown = new Set(shown);
   return { shown, rest: examples.filter((e) => !inShown.has(e)) };
 }
+function exampleStories(examples) {
+  const { shown, rest } = partitionExamples(examples);
+  const leadId = shown[0]?.id;
+  const ordered = [
+    ...shown,
+    ...rest.filter((e) => e.summary),
+    ...rest.filter((e) => !e.summary)
+  ];
+  return ordered.map((e) => ({
+    id: e.id,
+    name: titleize(e.name),
+    ...e.id === leadId ? { lead: true } : {},
+    ...e.summary ? { summary: e.summary } : {}
+  }));
+}
 function listComponents() {
   return DOCS.map((d) => ({
     name: d.name,
     description: d.description,
+    // LISTED-only components (no metadata file): flagged so an agent knows
+    // get_component won't carry when-to-use/decisionTree/mui guidance for them —
+    // examples + the .d.ts are still available. Documented rows omit the flag.
+    ...d.documented ? {} : { documented: false },
     keywords: d.curation.keywords ?? [],
-    examples: d.examples.length,
     // Family signal: the parts a compound component is composed with, and the
-    // sibling variants chosen between — so relationships are visible while scanning.
+    // sibling variants chosen between — each as { name, description } (same shape
+    // as get_component) so an agent can pick a family member while scanning.
     ...d.curation.subComponents?.length ? { subComponents: d.curation.subComponents } : {},
-    ...d.curation.variants?.length ? { variants: d.curation.variants } : {}
+    ...d.curation.variants?.length ? { variants: d.curation.variants } : {},
+    // Existence signal for the public hooks/utils/constants that ship with this
+    // component — compact here (name + kind); get_component carries the full
+    // { description, import } so an agent can act on them.
+    ...d.curation.relatedExports?.length ? {
+      relatedExports: d.curation.relatedExports.map((e) => ({
+        name: relatedName(e),
+        ...typeof e === "object" && e.kind ? { kind: e.kind } : {}
+      }))
+    } : {}
   }));
 }
 function getComponent(name) {
   const doc = find(name);
   if (!doc) return familyRedirect(name) ?? notFound(name);
-  const parts = doc.curation.subComponents ?? [];
-  const dtsGlob = parts.length > 0 ? `find node_modules/@carto/meridian-ds/dist/types \\( ${[doc.name, ...parts].map((n) => `-name '${n}.d.ts'`).join(" -o ")} \\)` : `find node_modules/@carto/meridian-ds/dist/types -name '${doc.name}.d.ts'`;
+  const parts = (doc.curation.subComponents ?? []).map(subName);
+  const dtsGlob = dtsFindRecipe(doc.name, ...parts);
   const compound = parts.length > 0 ? `${doc.name} is a compound component \u2014 compose it with its parts: ${parts.join(", ")}. ` : "";
   return {
     name: doc.name,
     description: doc.description,
-    reminder: "Apply the session conventions when using this \u2014 call meridian_get_conventions first if you have not this session.",
+    documented: doc.documented,
+    // A LISTED-only component has no curated guidance — be explicit so the agent
+    // leans on the examples + .d.ts rather than assuming the curation is just empty.
+    ...doc.documented ? {} : {
+      note: "Not yet curated: no when-to-use / decisionTree / keywords / promoted-prop guidance for this component. Use the examples below and its type declarations \u2014 and still prefer it over a bare MUI equivalent."
+    },
     curation: doc.curation,
     // Own props/types/JSDoc aren't in the bundle by design; point a headless
     // agent at the shipped .d.ts (no IDE/hover assumed) — for the root and, for a
     // compound component, every part. Promoted inherited MUI props, when curated,
     // are already in `curation.mui` above.
     propTypes: `${compound}Own props, exact types, and JSDoc are not in this payload \u2014 they ship as TypeScript declarations. Read them from the installed package: \`${dtsGlob}\`. Import from '@carto/meridian-ds/components'.`,
-    examples: (() => {
-      const { shown, rest } = partitionExamples(doc.examples);
-      const leadId = shown[0]?.id;
-      return {
-        note: "Stories are ordered by copy-value; the flagged lead is the starting point. Call meridian_get_examples(name) for the lead and the summarized stories in full plus an index of the rest; pass a storyId for any specific one.",
-        stories: [...shown, ...rest].map((e) => ({
-          id: e.id,
-          name: titleize(e.name),
-          ...e.id === leadId ? { lead: true } : {},
-          ...e.summary ? { summary: e.summary } : {}
-        }))
-      };
-    })()
+    examples: {
+      note: "Stories are ordered by copy-value; the flagged lead is the starting point. Call meridian_get_examples(name) for the lead in full plus an index of the rest; pass a storyId for any specific one.",
+      stories: exampleStories(doc.examples)
+    }
   };
 }
 function titleize(name) {
@@ -223,6 +260,8 @@ Flow:
 3. meridian_get_component(name) \u2014 when to use it, its decisionTree (conditions that point to a different component), and the high-value inherited MUI props worth knowing (curation.mui; some carry an aiHint). It also returns the example story ids.
 4. meridian_get_examples(name[, storyId]) \u2014 real, copy-able example code. With no storyId: the lead usage story and the notable stories in full plus a list of the rest; pass a storyId for one story's full code.
 
+Two tiers of components: most are fully CURATED, but some are LISTED only (flagged "documented": false in list_components / get_component) \u2014 they exist and have examples (use them), but carry no curated when-to-use / decisionTree / promoted-prop guidance yet. For a listed component, lean on get_examples + the .d.ts, and still prefer it over a bare MUI equivalent.
+
 Exact own props, types, and JSDoc are NOT served here \u2014 they ship as TypeScript declarations in the installed package. Read them with: find node_modules/@carto/meridian-ds/dist/types -name '<Component>.d.ts'. Import the component from '@carto/meridian-ds/components'. Prefer a Meridian component over a bare MUI one whenever one exists.`;
 function send(msg) {
   process.stdout.write(JSON.stringify(msg) + "\n");