@linktr.ee/arbor-mcp 0.5.0 → 0.7.0

package/dist/index.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -5532,7 +5536,7 @@ ZodNaN.create = (params) => {
     ...processCreateParams(params)
   });
 };
-var BRAND = Symbol("zod_brand");
+var BRAND = /* @__PURE__ */ Symbol("zod_brand");
 var ZodBranded = class extends ZodType {
   _parse(input) {
     const { ctx } = this._processInputParams(input);
@@ -6130,6 +6134,69 @@ async function resolveVersionId(version, deps = {}) {
   return { ok: true, versionId, versionName };
 }
 
+// src/lib/intentions.ts
+var INTENTIONS_ARTIFACT = "component-intentions.json";
+var INTENTION_STATUSES = [
+  "shipped",
+  "in-progress",
+  "design-only",
+  "deprecated",
+  "researched-not-shipped"
+];
+var STATUS_SET = new Set(INTENTION_STATUSES);
+function normalizeComponentKey(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((s) => typeof s === "string") : [];
+}
+function asDisambiguations(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const d of v) {
+    if (d && typeof d === "object") {
+      const component = d.component;
+      const distinction = d.distinction;
+      if (typeof component === "string" && typeof distinction === "string") {
+        out.push({ component, distinction });
+      }
+    }
+  }
+  return out;
+}
+function coerceEntry(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  const name = typeof r.name === "string" ? r.name.trim() : "";
+  const status = typeof r.status === "string" ? r.status : "";
+  if (!name || !STATUS_SET.has(status)) return null;
+  return {
+    name,
+    status,
+    shippedVersion: typeof r.shippedVersion === "string" ? r.shippedVersion : null,
+    useWhen: asStringArray(r.useWhen),
+    notWhen: asStringArray(r.notWhen),
+    disambiguateFrom: asDisambiguations(r.disambiguateFrom),
+    guideline: typeof r.guideline === "string" ? r.guideline : null,
+    implementation: typeof r.implementation === "string" ? r.implementation : null,
+    decisions: asStringArray(r.decisions)
+  };
+}
+async function loadIntentions(load = loadPublishedJson) {
+  const res = await load(INTENTIONS_ARTIFACT);
+  if (!res.ok) return { ok: false, reason: res.reason };
+  const data = res.data;
+  if (data.degraded === true || !Array.isArray(data.components)) {
+    return { ok: false, reason: "degraded" };
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const raw of data.components) {
+    const entry = coerceEntry(raw);
+    if (entry) byKey.set(normalizeComponentKey(entry.name), entry);
+  }
+  return { ok: true, byKey, generatedAt: typeof data.generatedAt === "string" ? data.generatedAt : null };
+}
+
 // src/tools/list-components.ts
 var TOOL_NAME3 = "arbor_list_components";
 var TOOL_TITLE3 = "List Arbor components";
@@ -6146,7 +6213,16 @@ var inputSchema3 = external_exports.object({
 var outputSchema3 = external_exports.object({
   source: external_exports.enum(["remote", "unavailable"]),
   total: external_exports.number(),
-  components: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), description: external_exports.string().nullable() })),
+  components: external_exports.array(
+    external_exports.object({
+      id: external_exports.string(),
+      name: external_exports.string(),
+      description: external_exports.string().nullable(),
+      // Lifecycle status merged from the component-intentions manifest (DNG-726).
+      // null when the manifest has no entry for this component or could not be loaded.
+      status: external_exports.enum(INTENTION_STATUSES).nullable()
+    })
+  ),
   detail: external_exports.string().nullable()
 });
 var annotations3 = { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false };
@@ -6196,7 +6272,13 @@ async function handleListComponents(args, deps = {}) {
         (c) => c.name.toLowerCase().includes(q) || (c.description ? c.description.toLowerCase().includes(q) : false)
       );
     }
-    out = { source: "remote", total: components.length, components, detail: null };
+    const intentionsRes = await (deps.loadIntentions ?? (() => loadIntentions()))();
+    const byKey = intentionsRes.ok ? intentionsRes.byKey : null;
+    const withStatus = components.map((c) => ({
+      ...c,
+      status: byKey ? byKey.get(normalizeComponentKey(c.name))?.status ?? null : null
+    }));
+    out = { source: "remote", total: withStatus.length, components: withStatus, detail: null };
   }
   const summary = out.source === "unavailable" ? `Could not load components (${out.detail}). Treat as unavailable \u2014 do not assume there are none.` : `${out.total} component${out.total === 1 ? "" : "s"}${args.query ? ` matching "${args.query}"` : ""}.`;
   return { content: [{ type: "text", text: summary }], structuredContent: out };
@@ -6210,7 +6292,7 @@ var listComponentsTool = {
 // src/tools/get-component.ts
 var TOOL_NAME4 = "arbor_get_component";
 var TOOL_TITLE4 = "Get one Arbor component";
-var TOOL_DESCRIPTION4 = "Get a single Arbor component's metadata by name (case-insensitive) or id from Supernova via the Arbor federation proxy (name, id, description). Read-only; matches top-level components, not Figma variants. Does NOT return token values or rendered source \u2014 use the shadcn registry / Storybook for implementation and arbor_open_in_playroom for a runnable snippet. Does NOT change anything.";
+var TOOL_DESCRIPTION4 = "Get a single Arbor component's metadata by name (case-insensitive) or id (name, id, description) PLUS its intention overlay \u2014 lifecycle status (shipped | in-progress | design-only | deprecated | researched-not-shipped), when to use it, when NOT to (and what to use instead), what it is commonly confused with, and repo paths to its guideline and (when present) agent implementation guidance. Intention comes from Arbor's source of truth, so a design-only component absent from the live design data still resolves. Read-only; matches top-level components, not Figma variants. Does NOT return token values or rendered source \u2014 use the shadcn registry / Storybook for implementation and arbor_open_in_playroom for a runnable snippet. Does NOT change anything.";
 var inputSchema4 = external_exports.object({
   name: external_exports.string().trim().min(1).max(100).optional().describe('Component name (case-insensitive), e.g. "Button"'),
   id: external_exports.string().trim().min(1).max(100).optional().describe("Supernova component id"),
@@ -6221,53 +6303,116 @@ var inputSchema4 = external_exports.object({
     'Read a specific released version, e.g. "15.1.0" \u2014 resolves to that frozen Supernova version and reads the component there ("what shipped in 15.1.0"). Takes precedence over versionSelector. See arbor_list_versions for the versions that have been cut.'
   )
 }).strict();
+var disambiguationSchema = external_exports.object({
+  component: external_exports.string().describe("The thing to disambiguate from \u2014 an Arbor component or an external concept (chip, snackbar, \u2026)"),
+  distinction: external_exports.string().describe("How they differ and which to pick when")
+});
+var intentionSchema = external_exports.object({
+  status: external_exports.enum(["shipped", "in-progress", "design-only", "deprecated", "researched-not-shipped"]).describe("Lifecycle/availability in the @linktr.ee/arbor package"),
+  shippedVersion: external_exports.string().nullable().describe("The arbor version where this became available, when known"),
+  useWhen: external_exports.array(external_exports.string()).describe("Situations this is the right choice for"),
+  notWhen: external_exports.array(external_exports.string()).describe("When NOT to reach for it, ideally naming the better alternative"),
+  disambiguateFrom: external_exports.array(disambiguationSchema).describe("Things this is commonly confused with"),
+  guideline: external_exports.string().nullable().describe("Repo-relative path to the long-form guideline, when one exists"),
+  implementation: external_exports.string().nullable().describe("Repo-relative path to the agent-facing implementation guidance (code-correctness + a11y rules), when one exists"),
+  decisions: external_exports.array(external_exports.string()).describe("Decision-log ids (DL-NN) that explain this intention")
+});
 var outputSchema4 = external_exports.object({
-  source: external_exports.enum(["remote", "unavailable"]),
-  found: external_exports.boolean(),
+  source: external_exports.enum(["remote", "unavailable"]).describe("Live design-data (Supernova) availability"),
+  found: external_exports.boolean().describe("True when a component OR an intention entry matched"),
   component: external_exports.object({ id: external_exports.string(), name: external_exports.string(), description: external_exports.string().nullable() }).nullable(),
+  intention: intentionSchema.nullable().describe("Intention overlay from the source-of-truth manifest; null when no entry matched or it could not be loaded"),
+  intentionSource: external_exports.enum(["remote", "absent", "unavailable"]).describe("'remote' = matched, 'absent' = manifest loaded but no entry, 'unavailable' = manifest could not be loaded"),
   detail: external_exports.string().nullable()
 });
 var annotations4 = { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false };
+async function resolveIntention(lookupName, load) {
+  const res = await load();
+  if (!res.ok) return { intention: null, intentionSource: "unavailable" };
+  if (!lookupName) return { intention: null, intentionSource: "absent" };
+  const match = res.byKey.get(normalizeComponentKey(lookupName));
+  if (!match) return { intention: null, intentionSource: "absent" };
+  const intention = {
+    status: match.status,
+    shippedVersion: match.shippedVersion,
+    useWhen: match.useWhen,
+    notWhen: match.notWhen,
+    disambiguateFrom: match.disambiguateFrom.map((d) => ({ component: d.component, distinction: d.distinction })),
+    guideline: match.guideline,
+    implementation: match.implementation,
+    decisions: match.decisions
+  };
+  return { intention, intentionSource: "remote" };
+}
 async function handleGetComponent(args, deps = {}) {
   const name = args.name?.trim();
   const id = args.id?.trim();
+  const loadIntentionsFn = deps.loadIntentions ?? (() => loadIntentions());
   if (!name && !id) {
-    const out2 = { source: "remote", found: false, component: null, detail: "provide name or id" };
+    const out2 = {
+      source: "remote",
+      found: false,
+      component: null,
+      intention: null,
+      intentionSource: "absent",
+      detail: "provide name or id"
+    };
     return {
       content: [{ type: "text", text: 'Provide a component name or id \u2014 e.g. {"name":"Button"} or {"id":"35988997"}.' }],
       structuredContent: out2
     };
   }
   const query = deps.query ?? ((r, opts) => querySupernova(r, opts));
-  let queryOpts;
+  let supernovaSource = "remote";
+  let component = null;
+  let supernovaDetail = null;
+  let queryOpts = null;
   if (args.version) {
     const resolveVersion = deps.resolveVersion ?? ((v) => resolveVersionId(v));
     const resolved = await resolveVersion(args.version);
-    if (!resolved.ok) {
-      const out2 = { source: "unavailable", found: false, component: null, detail: resolved.detail };
-      return {
-        content: [{ type: "text", text: `Could not read version ${args.version}: ${resolved.detail}. Treat as unavailable.` }],
-        structuredContent: out2
-      };
+    if (resolved.ok) {
+      queryOpts = { versionId: resolved.versionId };
+    } else {
+      supernovaSource = "unavailable";
+      supernovaDetail = resolved.detail;
     }
-    queryOpts = { versionId: resolved.versionId };
   } else {
     queryOpts = { versionSelector: args.versionSelector };
   }
-  const result = await query("components", queryOpts);
-  let out;
-  if (!result.ok) {
-    out = { source: "unavailable", found: false, component: null, detail: `could not load components (${result.reason})` };
-  } else {
-    const components = extractComponents(result.data);
-    if (components === null) {
-      out = { source: "unavailable", found: false, component: null, detail: "proxy returned an unrecognized components payload" };
+  if (queryOpts) {
+    const result = await query("components", queryOpts);
+    if (!result.ok) {
+      supernovaSource = "unavailable";
+      supernovaDetail = `could not load components (${result.reason})`;
     } else {
-      const match = id ? components.find((c) => c.id === id) : components.find((c) => c.name.toLowerCase() === name.toLowerCase());
-      out = match ? { source: "remote", found: true, component: match, detail: null } : { source: "remote", found: false, component: null, detail: `no component ${id ? `with id ${id}` : `named "${name}"`}` };
+      const components = extractComponents(result.data);
+      if (components === null) {
+        supernovaSource = "unavailable";
+        supernovaDetail = "proxy returned an unrecognized components payload";
+      } else {
+        const target = name ? normalizeComponentKey(name) : null;
+        const match = id ? components.find((c) => c.id === id) : components.find((c) => normalizeComponentKey(c.name) === target);
+        if (match) component = match;
+        else supernovaDetail = `no component ${id ? `with id ${id}` : `named "${name}"`}`;
+      }
     }
   }
-  const summary = out.source === "unavailable" ? `Could not load components (${out.detail}). Treat as unavailable.` : out.found ? `${out.component.name}${out.component.description ? ` \u2014 ${out.component.description}` : " (no description)"}.` : `No Arbor component ${args.id ? `with id ${args.id.trim()}` : `named "${args.name?.trim()}"`} exists.`;
+  const lookupName = component?.name ?? name ?? null;
+  const { intention, intentionSource } = await resolveIntention(lookupName, loadIntentionsFn);
+  const found = component !== null || intention !== null;
+  let detail = supernovaDetail;
+  if (!component && intention) {
+    detail = supernovaSource === "unavailable" ? `live design data unavailable (${supernovaDetail}); intention found \u2014 status "${intention.status}"` : `not in the live design data, but tracked as "${intention.status}" in Arbor's component intentions`;
+  }
+  const out = { source: supernovaSource, found, component, intention, intentionSource, detail };
+  let summary;
+  if (!found) {
+    summary = supernovaSource === "unavailable" ? `Could not load components (${supernovaDetail}). Treat as unavailable.` : `No Arbor component ${id ? `with id ${id}` : `named "${name}"`} exists.`;
+  } else {
+    const head = component ? `${component.name}${component.description ? ` \u2014 ${component.description}` : " (no description)"}.` : `${lookupName} \u2014 ${detail}.`;
+    const intentionLine = intention ? ` Status: ${intention.status}.${intention.useWhen.length ? ` Use when: ${intention.useWhen[0]}` : ""}` : intentionSource === "unavailable" ? " (intention overlay unavailable)" : "";
+    summary = `${head}${intentionLine}`;
+  }
   return { content: [{ type: "text", text: summary }], structuredContent: out };
 }
 var getComponentTool = {
@@ -6790,6 +6935,22 @@ var compositions_default = [
     name: "NotificationBadge",
     code: "<NotificationBadge count={3} />"
   },
+  // ── IndicatorBadge ──
+  {
+    group: "IndicatorBadge",
+    name: "IndicatorBadge (count)",
+    code: "<IndicatorBadge count={5} />"
+  },
+  {
+    group: "IndicatorBadge",
+    name: "IndicatorBadge (dot)",
+    code: '<IndicatorBadge dot aria-label="Unread" />'
+  },
+  {
+    group: "IndicatorBadge",
+    name: "IndicatorBadge (custom color)",
+    code: '<IndicatorBadge count={5} color="#7B61FF" />'
+  },
   // ── Button ──
   {
     group: "Button",
@@ -6823,6 +6984,31 @@ var compositions_default = [
   <Button variant="secondary">Cancel</Button>
   <Button>Save changes</Button>
 </div>`
+  },
+  // ── ButtonGroup ──
+  {
+    group: "ButtonGroup",
+    name: "ButtonGroup (confirm / cancel)",
+    code: `<ButtonGroup aria-label="Save changes">
+  <Button variant="secondary">Cancel</Button>
+  <Button>Save changes</Button>
+</ButtonGroup>`
+  },
+  {
+    group: "ButtonGroup",
+    name: "ButtonGroup (stacked)",
+    code: `<ButtonGroup stacked aria-label="Start trial or decide later">
+  <Button variant="accent">Start 7-day free trial</Button>
+  <Button variant="ghost">Decide later</Button>
+</ButtonGroup>`
+  },
+  {
+    group: "ButtonGroup",
+    name: "ButtonGroup (auto width)",
+    code: `<ButtonGroup fullWidth={false} aria-label="Discard or update">
+  <Button variant="ghost">Discard changes</Button>
+  <Button>Update everywhere</Button>
+</ButtonGroup>`
   },
   // ── CardSelect ──
   {
@@ -7053,6 +7239,12 @@ var compositions_default = [
   </RadioGroup>
 </Fieldset>`
   },
+  // ── FileUpload ──
+  {
+    group: "FileUpload",
+    name: "FileUpload",
+    code: '<div className="w-full max-w-md"><FileUpload label="Select files to upload" supportingText="PDF, PNG, or JPG \u2014 up to 100MB each" /></div>'
+  },
   // ── HeaderBar ──
   // Maps to figma-mappings `HeaderBar` (node 5223-5837). Title + back-button
   // is the canonical small variant; HeaderBar.stories.tsx covers the full
@@ -7177,6 +7369,30 @@ var compositions_default = [
     code: `<RadioGroup defaultValue="option-1">
   <RadioButton value="option-1" variant="pill">Option 1</RadioButton>
   <RadioButton value="option-2" variant="pill">Option 2</RadioButton>
+</RadioGroup>`
+  },
+  // ── Radio ──
+  // Maps to figma-mappings `Radio` (canonical control, node 9232-27291). The bare
+  // 20px control must render inside a RadioGroup; pair each with an accessible
+  // name (aria-label here, or a sibling <label htmlFor> in real usage).
+  {
+    group: "Radio",
+    name: "Radio",
+    code: `<RadioGroup defaultValue="email" aria-label="Notifications">
+  <Radio value="email" aria-label="Email" />
+  <Radio value="sms" aria-label="SMS" />
+  <Radio value="push" aria-label="Push notification" />
+</RadioGroup>`
+  },
+  // ── RadioItem ──
+  // Maps to figma-mappings `RadioItem` (canonical control + label, node 12360-58265).
+  {
+    group: "RadioItem",
+    name: "RadioItem",
+    code: `<RadioGroup defaultValue="email" aria-label="Notifications">
+  <RadioItem value="email" description="We'll send a confirmation">Email</RadioItem>
+  <RadioItem value="sms">SMS</RadioItem>
+  <RadioItem value="push" disabled>Push notification</RadioItem>
 </RadioGroup>`
   },
   // ── SearchInput ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linktr.ee/arbor-mcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Model Context Protocol server exposing Arbor design system tools: Playroom snippets, Figma→code sync health, UX-writing checks, decision-log lookup, and federated component/version metadata.",
   "keywords": [
     "arbor",
@@ -45,7 +45,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
+    "esbuild": "^0.28.1",
     "tsx": "^4.7.0",
     "typescript": "^5.7.0",
     "zod": "3.25.76"