mlola-ui 1.0.3 → 1.0.4

package/registry/index.json

@@ -2,7 +2,7 @@
   "$schema": "./schema/registry-index.schema.json",
   "schemaVersion": 2,
   "name": "mlola-ui",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "homepage": "https://ui.mlola.com",
   "themeContract": {
     "attribute": "data-theme",
@@ -179,8 +179,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3",
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4",
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -236,7 +236,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -352,7 +352,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -401,7 +401,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -463,7 +463,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/motion": "^1.0.3"
+        "@mlola-ui/motion": "^1.0.4"
       },
       "files": [
         {
@@ -567,8 +567,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3",
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4",
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -618,7 +618,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -670,7 +670,7 @@
         "modal"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -732,8 +732,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3",
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4",
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -784,7 +784,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -980,8 +980,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3",
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4",
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -1086,7 +1086,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -1394,7 +1394,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4"
       },
       "files": [
         {
@@ -1448,8 +1448,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3",
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4",
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -1520,8 +1520,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3",
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4",
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -1628,7 +1628,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4"
       },
       "files": [
         {
@@ -1735,7 +1735,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.0.3"
+        "@mlola-ui/behavior": "^1.0.4"
       },
       "files": [
         {
@@ -1837,7 +1837,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -1893,7 +1893,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2102,7 +2102,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2161,7 +2161,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2219,7 +2219,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2383,7 +2383,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2448,7 +2448,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2500,7 +2500,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2560,7 +2560,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2616,7 +2616,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2719,7 +2719,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2840,7 +2840,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {
@@ -2905,7 +2905,7 @@
         "sheet"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.0.3"
+        "@mlola-ui/icons": "^1.0.4"
       },
       "files": [
         {

package/src/agents.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import { designGuide } from "./knowledge.js";
+
+/**
+ * Tells the project's coding agents that the UI is Mlola, where the design
+ * language is written down, and how to ask about it, so an assistant builds
+ * with Mlola without being reminded:
+ *
+ * - `mlola.agents.md`   the design guide: classes, tokens, rules (refreshed)
+ * - `AGENTS.md`         a short section, between markers, read by most agents
+ * - `CLAUDE.md`         imports AGENTS.md for Claude Code
+ * - `.mcp.json`         the Mlola MCP server, for Claude Code and others
+ * - `.cursor/…`         a rule and the MCP server, when the project uses Cursor
+ * - `.vscode/mcp.json`  the MCP server, when the project uses VS Code
+ *
+ * Every write merges: anything else in these files is left as it was.
+ */
+
+export const GUIDE_FILE = "mlola.agents.md";
+const START = "<!-- mlola-ui:start -->";
+const END = "<!-- mlola-ui:end -->";
+const SERVER = { command: "npx", args: ["-y", "mlola-ui", "mcp"] };
+
+const BRIEF = `## UI: Mlola UI
+
+This project's interface is built with Mlola UI. Before writing or changing UI:
+
+- Read \`${GUIDE_FILE}\` (and \`mlola-pro.agents.md\` when it exists): every
+  class, attribute and token, and the rules for new UI.
+- Compose from Mlola components first: \`npx mlola-ui list\`,
+  \`npx mlola-ui add <name>\`. Write new CSS only for what they do not cover.
+- Never write a color, spacing, radius, shadow or duration by hand: read the
+  \`--ml-*\` tokens. There is no Tailwind or other styling framework here.
+- State and variants go in \`data-*\` and \`aria-*\` with the shared words
+  (\`data-tone\`, \`data-variant\`, \`data-size\`, \`data-status\`), never in extra
+  classes. \`data-theme\` and \`data-mode\` belong to the engine.
+- The \`mlola\` MCP server (\`npx mlola-ui mcp\`) searches components, explains
+  tokens and checks markup against the contract. Check new markup with its
+  \`check_markup\` tool before finishing.`;
+
+/** Replaces the marked section, or appends it; returns what happened. */
+function mergeSection(filename, body) {
+  const block = `${START}\n${body}\n${END}`;
+  if (!fs.existsSync(filename)) {
+    fs.writeFileSync(filename, `${block}\n`);
+    return "created";
+  }
+  const current = fs.readFileSync(filename, "utf8");
+  const start = current.indexOf(START);
+  const end = current.indexOf(END);
+  const next = start >= 0 && end > start ? `${current.slice(0, start)}${block}${current.slice(end + END.length)}` : `${current.replace(/\s*$/, "")}\n\n${block}\n`;
+  if (next === current) return "unchanged";
+  fs.writeFileSync(filename, next);
+  return "updated";
+}
+
+function mergeJson(filename, update) {
+  let data = {};
+  if (fs.existsSync(filename)) {
+    try {
+      data = JSON.parse(fs.readFileSync(filename, "utf8"));
+    } catch {
+      return "skipped (not valid JSON; add the server by hand)";
+    }
+  }
+  const next = update(structuredClone(data));
+  if (JSON.stringify(next) === JSON.stringify(data)) return "unchanged";
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  const existed = fs.existsSync(filename);
+  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`);
+  return existed ? "updated" : "created";
+}
+
+export function writeAgentFiles(cwd) {
+  const results = [];
+  const record = (file, status) => results.push({ file, status });
+
+  const guide = designGuide();
+  if (guide) {
+    const filename = path.join(cwd, GUIDE_FILE);
+    const before = fs.existsSync(filename) ? fs.readFileSync(filename, "utf8") : null;
+    if (before !== guide) fs.writeFileSync(filename, guide);
+    record(GUIDE_FILE, before === null ? "created" : before === guide ? "unchanged" : "updated");
+  }
+
+  record("AGENTS.md", mergeSection(path.join(cwd, "AGENTS.md"), BRIEF));
+
+  // Claude Code reads CLAUDE.md, which can import AGENTS.md rather than repeat it.
+  const claude = path.join(cwd, "CLAUDE.md");
+  const claudeText = fs.existsSync(claude) ? fs.readFileSync(claude, "utf8") : null;
+  if (claudeText === null) {
+    fs.writeFileSync(claude, "@AGENTS.md\n");
+    record("CLAUDE.md", "created");
+  } else if (!/^@AGENTS\.md\s*$/m.test(claudeText)) {
+    record("CLAUDE.md", mergeSection(claude, "@AGENTS.md"));
+  } else {
+    record("CLAUDE.md", "unchanged");
+  }
+
+  record(".mcp.json", mergeJson(path.join(cwd, ".mcp.json"), (data) => ({ ...data, mcpServers: { ...(data.mcpServers ?? {}), mlola: SERVER } })));
+
+  if (fs.existsSync(path.join(cwd, ".cursor"))) {
+    record(".cursor/mcp.json", mergeJson(path.join(cwd, ".cursor", "mcp.json"), (data) => ({ ...data, mcpServers: { ...(data.mcpServers ?? {}), mlola: SERVER } })));
+    const rule = path.join(cwd, ".cursor", "rules", "mlola.mdc");
+    const text = `---\ndescription: Mlola UI, how interface code is built and styled in this project\nalwaysApply: true\n---\n\n${BRIEF.replace(/^## .*\n\n/, "")}\n`;
+    const before = fs.existsSync(rule) ? fs.readFileSync(rule, "utf8") : null;
+    if (before !== text) {
+      fs.mkdirSync(path.dirname(rule), { recursive: true });
+      fs.writeFileSync(rule, text);
+    }
+    record(".cursor/rules/mlola.mdc", before === null ? "created" : before === text ? "unchanged" : "updated");
+  }
+
+  if (fs.existsSync(path.join(cwd, ".vscode"))) {
+    record(".vscode/mcp.json", mergeJson(path.join(cwd, ".vscode", "mcp.json"), (data) => ({ ...data, servers: { ...(data.servers ?? {}), mlola: { type: "stdio", ...SERVER } } })));
+  }
+  return results;
+}

package/src/cli.js

@@ -7,17 +7,21 @@ import {
   targetRoot,
   writeDefaultConfig,
 } from "./config.js";
+import { writeAgentFiles } from "./agents.js";
 import { addAssets, assetHint, loadAssetIndex } from "./assets.js";
 import { runDoctor } from "./doctor.js";
 import { collectEngineDependencies, installItems } from "./installer.js";
 import { loadCatalogNames, loadRegistry, resolveItems } from "./registry.js";
 import { clearCredentials, fetchProItems, GUIDE_FILENAME, hostFrom, readCredentials, saveCredentials, verifyToken, writeProGuide, writeProStyles } from "./pro.js";
+import { serveMcp } from "./mcp.js";
 import { pullTheme } from "./theme-pull.js";
 
 const HELP = `Mlola UI — source-copy components with Theme
 
 Usage:
-  mlola-ui init [--force]
+  mlola-ui init [--force] [--no-agents]
+  mlola-ui agents
+  mlola-ui mcp
   mlola-ui add <name...> [--overwrite] [--install|--yes]
   mlola-ui add asset <id...> [--overwrite]
   mlola-ui login <token> [--host <url>]
@@ -27,15 +31,25 @@ Usage:
   mlola-ui theme pull <theme-id | url> [--host <url>] [--overwrite]
 
 Examples:
-  npx mlola-ui init
+  npx mlola-ui init                   (also tells your coding agents about Mlola)
   npx mlola-ui add button card
   npx mlola-ui login mlp_…          (Mlola Pro: a token from /account)
   npx mlola-ui add conversation bot
   npx mlola-ui add asset empty-inbox orb
   npx mlola-ui list --kind block
   npx mlola-ui theme pull https://ui.mlola.com/t/th-4k2x9qf7wz3m
+  npx mlola-ui mcp                    (an MCP server for Claude Code, Cursor, Codex…)
 `;
 
+const CLI_VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+function reportAgents(results, output) {
+  const changed = results.filter((entry) => entry.status !== "unchanged");
+  for (const { file, status } of changed) output.log(`✓ ${status[0].toUpperCase()}${status.slice(1)} ${file}`);
+  if (!changed.length) output.log("• Agent instructions are up to date");
+  output.log("Coding agents now know this UI is Mlola: AGENTS.md points them at mlola.agents.md, and .mcp.json starts the Mlola MCP server.");
+}
+
 function hasFlag(args, ...names) {
   return args.some((argument) => names.includes(argument));
 }
@@ -113,6 +127,17 @@ export async function run(argv, options = {}) {
       output.log(
         `Install the engines you use, starting with: npm install ${config.engine.engine ?? "@mlola-ui/engine"} ${config.engine.motion}`,
       );
+      if (!hasFlag(args, "--no-agents")) reportAgents(writeAgentFiles(cwd), output);
+      return 0;
+    }
+
+    if (command === "agents") {
+      reportAgents(writeAgentFiles(cwd), output);
+      return 0;
+    }
+
+    if (command === "mcp") {
+      await serveMcp({ cwd, run, version: CLI_VERSION });
       return 0;
     }