@linktr.ee/arbor-mcp 0.5.0 → 0.6.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,68 @@ 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,
+    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 +6212,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 +6271,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 +6291,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), and what it is commonly confused with. 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 +6302,114 @@ 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"),
+  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,
+    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 = {
@@ -7177,6 +7319,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.6.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"