mlola-ui 1.0.3 → 1.0.4

package/src/knowledge.js

@@ -0,0 +1,235 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_CONFIG, interpolateTarget } from "./config.js";
+import { BUNDLED_REGISTRY_ROOT, loadRegistry, readJson, sourcePath } from "./registry.js";
+
+/**
+ * What the CLI knows about Mlola UI, as answers rather than files: every
+ * component and catalog item, the tokens, the rules for new UI, and the
+ * element contract markup is checked against. All of it is read from the
+ * registry bundled with this CLI, so an answer always matches the version
+ * that `add` installs, and it works offline.
+ */
+
+const cache = new Map();
+function bundled(name) {
+  if (!cache.has(name)) {
+    const filename = path.join(BUNDLED_REGISTRY_ROOT, name);
+    cache.set(name, fs.existsSync(filename) ? (name.endsWith(".json") ? readJson(filename) : fs.readFileSync(filename, "utf8")) : null);
+  }
+  return cache.get(name);
+}
+
+const KIND = { "registry:ui": "component", "registry:block": "block", "registry:page": "page", "registry:template": "template" };
+
+/** Every item, free and Pro, in one shape. */
+export function allItems() {
+  const registry = loadRegistry();
+  const free = registry.items.map((item) => ({
+    name: item.name,
+    kind: KIND[item.type] ?? "component",
+    tier: "free",
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    tags: item.tags ?? [],
+    variants: item.variants ?? [],
+    sizes: item.sizes ?? [],
+  }));
+  const pro = (bundled("catalog.json")?.items ?? []).map((item) => ({
+    name: item.name,
+    kind: KIND[item.type] ?? "component",
+    tier: "pro",
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    tags: item.tags ?? [],
+    variants: [],
+    sizes: [],
+  }));
+  return [...free, ...pro];
+}
+
+/** Items matching a query: every word must appear in the name, title, description, category or tags. */
+export function searchItems({ query = "", kind, category, tier } = {}) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return allItems()
+    .filter((item) => (!kind || item.kind === kind) && (!category || item.category === category) && (!tier || item.tier === tier))
+    .map((item) => {
+      const haystack = [item.name, item.title, item.description, item.category, ...item.tags].join(" ").toLowerCase();
+      const score = words.reduce((sum, word) => sum + (item.name === word ? 5 : item.name.includes(word) ? 3 : haystack.includes(word) ? 1 : -100), 0);
+      return { item, score };
+    })
+    .filter(({ score }) => score >= 0)
+    .sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name))
+    .map(({ item }) => item);
+}
+
+/** The classes a component styles (its own prefix) and the attributes each reacts to. */
+function elementsOf(name) {
+  const contract = bundled("contract.json");
+  if (!contract) return [];
+  const prefix = `ml-${name}`;
+  return contract.classes
+    .filter((cls) => cls === prefix || cls.startsWith(`${prefix}-`))
+    .map((cls) => ({ class: cls, attributes: contract.elements[cls] ?? {} }));
+}
+
+function projectConfig(cwd) {
+  try {
+    return readJson(path.join(cwd, "mlola.config.json"));
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+/** Everything an agent needs to use one item correctly. */
+export function describeItem(name, { cwd = process.cwd(), includeSource = false } = {}) {
+  const registry = loadRegistry();
+  const item = registry.items.find((entry) => entry.name === name);
+  if (!item) {
+    const pro = (bundled("catalog.json")?.items ?? []).find((entry) => entry.name === name);
+    if (pro) {
+      return {
+        name,
+        tier: "pro",
+        kind: KIND[pro.type] ?? "component",
+        title: pro.title,
+        description: pro.description,
+        category: pro.category,
+        install: `npx mlola-ui login <token>   # once, with a token from https://ui.mlola.com/account\nnpx mlola-ui add ${name}`,
+        note: "Part of Mlola Pro. Its source arrives with a license token; its classes and attributes are listed in mlola-pro.agents.md after the first Pro install.",
+      };
+    }
+    const close = allItems().filter((entry) => entry.name.includes(name) || name.includes(entry.name)).map((entry) => entry.name).slice(0, 5);
+    throw new Error(`No item named "${name}".${close.length ? ` Did you mean: ${close.join(", ")}?` : ""} Search with search_components.`);
+  }
+  const config = projectConfig(cwd);
+  const usage = item.usage
+    ? { import: `import { ${item.usage.exportName} } from "${interpolateTarget(item.usage.importPath, config, "import")}";`, exportName: item.usage.exportName }
+    : null;
+  const result = {
+    name,
+    tier: "free",
+    kind: KIND[item.type] ?? "component",
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    variants: item.variants ?? [],
+    sizes: item.sizes ?? [],
+    usage,
+    install: `npx mlola-ui add ${name}`,
+    dependsOn: item.registryDependencies ?? [],
+    engineDependencies: item.engineDependencies ?? {},
+    elements: elementsOf(name),
+  };
+  if (includeSource) {
+    result.source = (item.files ?? [])
+      .filter((file) => !file.path.includes("/_internal/"))
+      .map((file) => ({ path: interpolateTarget(file.target, config), content: fs.readFileSync(sourcePath(file.path), "utf8") }));
+  }
+  return result;
+}
+
+export function designData() {
+  return bundled("agents.json");
+}
+
+export function designGuide() {
+  return bundled("agents.md");
+}
+
+export function tokens(group) {
+  const data = designData();
+  if (!data) return [];
+  const groups = data.tokens;
+  if (!group) return groups;
+  const wanted = group.toLowerCase();
+  return groups.filter((entry) => entry.group.toLowerCase().includes(wanted) || entry.names.some((name) => name.includes(wanted)));
+}
+
+export function themes() {
+  const registry = loadRegistry();
+  return registry.themes ?? designData()?.themes ?? [];
+}
+
+/* ── Checking markup against the contract ─────────────────────────── */
+
+const SHARED = new Set(["data-tone", "data-variant", "data-size", "data-state", "data-status"]);
+const UTILITY = /^(-?(m|p)[trblxy]?-\d|flex$|grid$|block$|inline|hidden$|items-|justify-|gap-|w-|h-|min-|max-|text-(xs|sm|base|lg|xl|\d|[a-z]+-\d)|font-(bold|medium|semibold|light)|bg-|border-|rounded|shadow|ring-|space-[xy]-|leading-|tracking-|opacity-|z-\d|absolute$|relative$|fixed$|sticky$|overflow-|col-span|row-span|sm:|md:|lg:|xl:|hover:|focus:|dark:)/;
+const COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i;
+
+/**
+ * Checks HTML or JSX against the element contract. It reads string-valued
+ * class, className, style and data-* attributes; expressions in braces are
+ * skipped, since their value is only known at runtime.
+ */
+export function checkMarkup(markup) {
+  const contract = bundled("contract.json");
+  const known = new Set(contract?.classes ?? []);
+  const proPrefixes = (bundled("catalog.json")?.items ?? []).map((item) => `ml-${item.name}`);
+  const themeIds = new Set(themes().map((theme) => theme.id));
+  const issues = [];
+  const note = (severity, tag, message, fix) => issues.push({ severity, element: tag.slice(0, 120), message, ...(fix ? { fix } : {}) });
+
+  for (const match of markup.matchAll(/<([A-Za-z][\w.-]*)((?:\s+(?:[^\s"'>={}]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}))?))*)\s*\/?>/g)) {
+    const tag = match[0];
+    const attributes = new Map();
+    for (const attribute of match[2].matchAll(/([^\s"'>={}]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\{(?:[^{}]|\{[^{}]*\})*\})))?/g)) {
+      const [, name, double, single, expression] = attribute;
+      const value = double ?? single ?? (expression ? /^\{\s*["'`]([^"'`$]*)["'`]\s*\}$/.exec(expression)?.[1] ?? null : "");
+      attributes.set(name, value);
+      if (expression) attributes.set(`${name}:raw`, expression);
+    }
+    const classValue = attributes.get("class") ?? attributes.get("className");
+    const classes = typeof classValue === "string" ? classValue.split(/\s+/).filter(Boolean) : [];
+    const mlola = classes.filter((cls) => cls.startsWith("ml-"));
+
+    for (const cls of mlola) {
+      if (known.has(cls) || proPrefixes.some((prefix) => cls === prefix || cls.startsWith(`${prefix}-`))) continue;
+      const base = [...known].find((candidate) => cls.startsWith(`${candidate}-`) && elementsOf(candidate.slice(3)).length);
+      note(
+        "error",
+        tag,
+        `"${cls}" is not a Mlola class.`,
+        base ? `Mlola has no variant classes: use "${base}" with a data-* attribute (data-variant, data-tone, data-size).` : "Search with search_components, or name your own element with your own prefix (not ml-).",
+      );
+    }
+    const utilities = classes.filter((cls) => !cls.startsWith("ml-") && UTILITY.test(cls));
+    if (utilities.length) {
+      note("warning", tag, `Utility classes (${utilities.slice(0, 4).join(" ")}) do nothing here: Mlola ships no utility framework.`, "Use a component or composition primitive; for your own CSS, read --ml-* tokens.");
+    }
+
+    for (const [name, value] of attributes) {
+      if (!name.startsWith("data-") || typeof value !== "string") continue;
+      if (name === "data-theme" && value && !themeIds.has(value) && !/^th-[0-9a-z]{12}$/.test(value)) {
+        note("error", tag, `data-theme="${value}" is not a theme.`, `Use one of: ${[...themeIds].join(", ")}, or a Studio theme id.`);
+      }
+      if (name === "data-mode" && !["light", "dark"].includes(value)) {
+        note("error", tag, `data-mode is "light" or "dark"; "${value}" belongs in an attribute of your own.`, "data-theme and data-mode belong to the engine. Use data-kind or data-state for a component's own meaning.");
+      }
+      if (!SHARED.has(name) || !mlola.length) continue;
+      const allowed = new Set();
+      let reacts = false;
+      for (const cls of mlola) {
+        const values = contract?.elements?.[cls]?.[name];
+        if (values) {
+          reacts = true;
+          for (const entry of values) allowed.add(entry);
+        }
+      }
+      if (reacts && allowed.size && !allowed.has(value)) {
+        note("error", tag, `${name}="${value}" is not a value ${mlola.join(" ")} reacts to.`, `Allowed: ${[...allowed].sort().join(", ")}.`);
+      } else if (!reacts && mlola.every((cls) => known.has(cls))) {
+        note("warning", tag, `${name} has no effect on ${mlola.join(" ")}.`, `See get_component for the attributes it reacts to.`);
+      }
+    }
+
+    // A style string, or a JSX style object, with a color written into it.
+    const style = attributes.get("style") ?? attributes.get("style:raw");
+    if (typeof style === "string" && COLOR.test(style)) {
+      note("error", tag, "A color is written by hand in style.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens).");
+    }
+  }
+  return issues;
+}

package/src/mcp.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { checkMarkup, describeItem, designData, designGuide, searchItems, themes, tokens } from "./knowledge.js";
+
+/**
+ * `mlola-ui mcp` — a Model Context Protocol server over stdio.
+ *
+ * A coding agent (Claude Code, Cursor, Codex, VS Code, …) starts it in the
+ * project and asks it about Mlola instead of recalling Tailwind from its
+ * training: which component fits, what it is called, which token to read,
+ * whether the markup it just wrote is right. It can also install components
+ * and set a project up. Answers come from the registry bundled with this
+ * CLI, so they match what `add` installs, offline.
+ *
+ * The protocol is newline-delimited JSON-RPC 2.0, small enough to speak
+ * without a dependency. Nothing but protocol messages is written to stdout;
+ * diagnostics go to stderr.
+ */
+
+const PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+
+const INSTRUCTIONS = `This project's UI is Mlola UI: native CSS classes (ml-*), data-* attributes for state and variant, and --ml-* tokens. There is no Tailwind.
+Before writing UI: call get_design_rules once, then search_components for what you need and get_component for how to use it. Read tokens with get_tokens instead of writing colors, sizes, shadows or durations. After writing markup, run check_markup on it and fix what it reports.`;
+
+const text = (value) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] });
+
+function tools({ cwd, run }) {
+  const capture = async (argv) => {
+    const lines = [];
+    const output = { log: (...parts) => lines.push(parts.join(" ")), error: (...parts) => lines.push(parts.join(" ")) };
+    const code = await run(argv, { cwd, output });
+    return { code, output: lines.join("\n") };
+  };
+  return [
+    {
+      name: "get_design_rules",
+      title: "Mlola design rules",
+      description: "The rules for building UI with Mlola: compose first, color by role, measure with the scales, shared state words, touch and focus. Read once before writing UI.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      handler: () => {
+        const data = designData();
+        return text(`${data?.rules ?? ""}\nThemes: ${themes().map((theme) => theme.id).join(", ")} (data-theme on any ancestor, data-mode light|dark).\nComposition primitives: ${(data?.primitives ?? []).map((entry) => entry.name).join(" ")}`);
+      },
+    },
+    {
+      name: "search_components",
+      title: "Search Mlola components",
+      description: "Find components, blocks, pages and templates by what they do (for example 'date range', 'chat input', 'pricing'). Returns name, tier (free or Mlola Pro) and a one-line description.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Words describing what you need. Empty lists everything." },
+          kind: { type: "string", enum: ["component", "block", "page", "template"] },
+          tier: { type: "string", enum: ["free", "pro"] },
+        },
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true },
+      handler: ({ query = "", kind, tier }) => {
+        const found = searchItems({ query, kind, tier });
+        return text(found.length ? found.slice(0, 40).map((item) => `${item.name} (${item.kind}, ${item.tier}) — ${item.description}`).join("\n") : `Nothing matches "${query}". Try other words, or search with an empty query to list everything.`);
+      },
+    },
+    {
+      name: "get_component",
+      title: "How to use a Mlola component",
+      description: "Everything needed to use one item: import, variants, sizes, the classes it styles and the data-* values each reacts to, dependencies and the install command. Set include_source to read a free component's source.",
+      inputSchema: {
+        type: "object",
+        properties: { name: { type: "string" }, include_source: { type: "boolean", default: false } },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true },
+      handler: ({ name, include_source = false }) => text(describeItem(name, { cwd, includeSource: include_source })),
+    },
+    {
+      name: "get_tokens",
+      title: "Mlola design tokens",
+      description: "The --ml-* tokens grouped by purpose (planes and ink, color roles, spacing, type, density, shape, depth, motion, layers…). Filter with a group name or part of a token name.",
+      inputSchema: { type: "object", properties: { group: { type: "string", description: "For example 'spacing', 'color', 'shadow', 'radius'." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      handler: ({ group }) => {
+        const found = tokens(group);
+        return text(found.length ? found.map((entry) => `${entry.group}: ${entry.purpose}\n  ${entry.names.join(" ")}`).join("\n\n") : `No token group matches "${group}".`);
+      },
+    },
+    {
+      name: "check_markup",
+      title: "Check markup against the Mlola contract",
+      description: "Checks HTML or JSX: classes that do not exist, variant classes, data-* values a class does not react to, utility classes, hand-written colors, and misuse of data-theme or data-mode. Run it on markup you wrote before finishing.",
+      inputSchema: { type: "object", properties: { markup: { type: "string" } }, required: ["markup"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      handler: ({ markup }) => {
+        const issues = checkMarkup(markup);
+        return text(issues.length ? issues : "No issues: every Mlola class exists and every data-* value is one its element reacts to.");
+      },
+    },
+    {
+      name: "add_components",
+      title: "Install Mlola components",
+      description: "Copies components into the project with the Mlola CLI (npx mlola-ui add), with their dependencies and styles. Pro items need a login first.",
+      inputSchema: {
+        type: "object",
+        properties: { names: { type: "array", items: { type: "string" }, minItems: 1 }, overwrite: { type: "boolean", default: false } },
+        required: ["names"],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+      handler: async ({ names, overwrite = false }) => {
+        const result = await capture(["add", ...names, ...(overwrite ? ["--overwrite"] : [])]);
+        return { ...text(result.output || "Done."), isError: result.code !== 0 };
+      },
+    },
+    {
+      name: "init_project",
+      title: "Set a project up for Mlola",
+      description: "Runs npx mlola-ui init: writes mlola.config.json, the stylesheet entry and the agent instructions (AGENTS.md, the design guide, MCP config).",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+      handler: async () => {
+        const result = await capture(["init"]);
+        return { ...text(result.output), isError: result.code !== 0 };
+      },
+    },
+  ];
+}
+
+function resources(cwd) {
+  const list = [{ uri: "mlola://guide", name: "Mlola UI design guide", description: "Classes, attributes, tokens and rules, generated from the stylesheet.", mimeType: "text/markdown" }];
+  if (fs.existsSync(path.join(cwd, "mlola-pro.agents.md"))) {
+    list.push({ uri: "mlola://guide/pro", name: "Mlola Pro design guide", description: "The classes and attributes of the Pro items installed here.", mimeType: "text/markdown" });
+  }
+  return list;
+}
+
+function readResource(uri, cwd) {
+  if (uri === "mlola://guide") return designGuide() ?? "";
+  if (uri === "mlola://guide/pro") return fs.readFileSync(path.join(cwd, "mlola-pro.agents.md"), "utf8");
+  throw Object.assign(new Error(`Unknown resource ${uri}`), { code: -32002 });
+}
+
+const PROMPTS = [
+  {
+    name: "build_ui",
+    title: "Build UI with Mlola",
+    description: "Build a screen or component the Mlola way, and check it.",
+    arguments: [{ name: "goal", description: "What to build.", required: true }],
+  },
+];
+
+function prompt(name, args) {
+  if (name !== "build_ui") throw Object.assign(new Error(`Unknown prompt ${name}`), { code: -32602 });
+  return {
+    description: "Build UI with Mlola",
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Build this with Mlola UI: ${args?.goal ?? ""}\n\n1. Read the rules (get_design_rules).\n2. Find the components that cover it (search_components, get_component) and install what is missing (add_components).\n3. Compose with them and the composition primitives; write CSS only for what they do not cover, reading --ml-* tokens (get_tokens).\n4. Check the markup (check_markup) and fix every issue before you finish.`,
+        },
+      },
+    ],
+  };
+}
+
+export async function serveMcp({ cwd, run, version, input = process.stdin, output = process.stdout }) {
+  const available = tools({ cwd, run });
+  const send = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+  async function handle(message) {
+    const { id, method, params } = message ?? {};
+    const isRequest = id !== undefined && id !== null;
+    try {
+      switch (method) {
+        case "initialize": {
+          const requested = params?.protocolVersion;
+          reply(id, {
+            protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
+            capabilities: { tools: { listChanged: false }, resources: { listChanged: false }, prompts: { listChanged: false } },
+            serverInfo: { name: "mlola-ui", title: "Mlola UI", version },
+            instructions: INSTRUCTIONS,
+          });
+          return;
+        }
+        case "ping":
+          return reply(id, {});
+        case "tools/list":
+          return reply(id, { tools: available.map(({ handler, ...tool }) => tool) });
+        case "tools/call": {
+          const tool = available.find((entry) => entry.name === params?.name);
+          if (!tool) return fail(id, -32602, `Unknown tool ${params?.name}`);
+          try {
+            return reply(id, await tool.handler(params?.arguments ?? {}));
+          } catch (error) {
+            // A tool that fails answers with the reason, so the agent can correct course.
+            return reply(id, { ...text(error.message), isError: true });
+          }
+        }
+        case "resources/list":
+          return reply(id, { resources: resources(cwd) });
+        case "resources/templates/list":
+          return reply(id, { resourceTemplates: [] });
+        case "resources/read":
+          return reply(id, { contents: [{ uri: params?.uri, mimeType: "text/markdown", text: readResource(params?.uri, cwd) }] });
+        case "prompts/list":
+          return reply(id, { prompts: PROMPTS });
+        case "prompts/get":
+          return reply(id, prompt(params?.name, params?.arguments));
+        default:
+          if (method?.startsWith("notifications/")) return;
+          if (isRequest) fail(id, -32601, `Method not found: ${method}`);
+      }
+    } catch (error) {
+      if (isRequest) fail(id, error.code ?? -32603, error.message);
+    }
+  }
+
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const pending = new Set();
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+      continue;
+    }
+    for (const entry of Array.isArray(message) ? message : [message]) {
+      const task = handle(entry).finally(() => pending.delete(task));
+      pending.add(task);
+    }
+  }
+  await Promise.all(pending);
+}