@tonycodes-ui/mortar 0.0.0-stage → 0.11.0

package/cli/data.mjs

@@ -0,0 +1,176 @@
+// Loads what the CLI and MCP server describe: the installed package's own
+// catalog.json, docs and build-time data (dist/agent-data.json, generated by
+// scripts/agent-data.mjs during `npm run build`). Nothing is fetched; the data
+// always matches the installed version.
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const PACKAGE_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+const readJson = (file) => JSON.parse(readFileSync(file, "utf8"));
+
+/** Guide topic → the shipped markdown file (and an optional section). */
+export const GUIDES = {
+  design: {
+    file: "DESIGN.md",
+    summary: "Design principles, API conventions and composing flows.",
+  },
+  conventions: {
+    file: "DESIGN.md",
+    section: "API conventions",
+    summary:
+      "Prop naming rules every component follows: headings, layout/variant/align, tone, state, callbacks, items, className, data attributes.",
+  },
+  theming: {
+    file: "docs/theming.md",
+    summary:
+      "Brands, appearance (light/dark/system), density, runtime brandTokens and the token scales.",
+  },
+  "auth-flows": {
+    file: "docs/auth-flows.md",
+    summary:
+      "Sign-in and registration: each step mapped to components, autocomplete values, validation, security and accessibility.",
+  },
+  "migrating-0.6": {
+    file: "docs/migrating-to-0.6.md",
+    summary: "Every prop and markup change from 0.5 to 0.6.",
+  },
+  contributing: {
+    file: "CONTRIBUTING.md",
+    also: ["AGENTS.md"],
+    summary:
+      "How to contribute a component or fix through a GitHub pull request, and the rules for coding agents.",
+  },
+  testing: {
+    file: "TESTING.md",
+    summary:
+      "The component test contract: profiles, states, browser and visual checks.",
+  },
+  agents: {
+    file: "docs/agents.md",
+    summary: "How a coding agent uses Mortar with this MCP server and CLI.",
+  },
+};
+
+/** One `## Heading` section of a markdown document. */
+export function markdownSection(text, heading) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trim() === `## ${heading}`);
+  if (start < 0) return "";
+  let end = lines.findIndex((l, i) => i > start && /^## /.test(l));
+  if (end < 0) end = lines.length;
+  return lines.slice(start, end).join("\n").trim();
+}
+
+let cached;
+
+/**
+ * The data for a package root. `root` defaults to this package; the audit
+ * passes an application's installed copy when it has one.
+ */
+export async function loadData(root = PACKAGE_ROOT) {
+  if (root === PACKAGE_ROOT && cached) return cached;
+  const catalog = readJson(join(root, "catalog.json"));
+  let agent;
+  const built = join(root, "dist", "agent-data.json");
+  if (existsSync(built)) agent = readJson(built);
+  else if (existsSync(join(root, "scripts", "agent-data.mjs"))) {
+    // A source checkout that has not been built yet (needs devDependencies).
+    try {
+      const { agentData } = await import(
+        pathToFileURL(join(root, "scripts", "agent-data.mjs")).href
+      );
+      agent = agentData(root);
+    } catch {
+      agent = undefined;
+    }
+  }
+  agent ??= {
+    taxonomy: { kits: [] },
+    templates: [],
+    exports: { values: catalog.components.map((c) => c.export), types: [] },
+    examples: {},
+    inherited: {},
+    inheritedSets: [],
+    classes: [],
+    sourceHashes: {},
+    missing: true,
+  };
+  let principles = [];
+  const principlesFile = join(root, "design-principles.json");
+  if (existsSync(principlesFile))
+    principles = readJson(principlesFile).principles;
+  const pkg = readJson(join(root, "package.json"));
+  const data = makeData({ root, catalog, agent, principles, pkg });
+  if (root === PACKAGE_ROOT) cached = data;
+  return data;
+}
+
+function makeData({ root, catalog, agent, principles, pkg }) {
+  const components = catalog.components;
+  const byId = new Map(components.map((c) => [c.id, c]));
+  const byName = new Map(components.map((c) => [c.export.toLowerCase(), c]));
+  // Category and kit for each component, from the playground taxonomy.
+  const placement = new Map();
+  for (const kit of agent.taxonomy.kits)
+    for (const category of kit.categories)
+      for (const name of category.components)
+        placement.set(name, { kit, category });
+  const kitTitle = (id) =>
+    agent.taxonomy.kits.find((k) => k.id === id)?.title ?? id;
+  return {
+    root,
+    packageName: catalog.package ?? pkg.name,
+    version: catalog.version ?? pkg.version,
+    catalog,
+    components,
+    agent,
+    principles,
+    /** A component by export name (any case) or catalogue id. */
+    find(name) {
+      if (typeof name !== "string") return undefined;
+      const key = name.trim().replace(/^<|\/?>$/g, "");
+      return (
+        byName.get(key.toLowerCase()) ??
+        byId.get(key) ??
+        byId.get(`mortar-${key}`)
+      );
+    },
+    byId: (id) => byId.get(id),
+    placement(c) {
+      const p = placement.get(c.export);
+      return {
+        kit: p?.kit.id ?? c.kitId,
+        kitTitle: p?.kit.title ?? kitTitle(c.kitId),
+        category: p?.category.id,
+        categoryTitle: p?.category.title,
+      };
+    },
+    /** Every prop name the component accepts, including inherited DOM attributes. */
+    accepts(c) {
+      const names = new Set(Object.keys(c.contract.propTypes ?? {}));
+      const set = agent.inherited[c.export];
+      if (set !== undefined)
+        for (const n of agent.inheritedSets[set]) names.add(n);
+      return names;
+    },
+    guide(topic) {
+      const g = GUIDES[topic];
+      if (!g) return undefined;
+      const parts = [];
+      for (const file of [g.file, ...(g.also ?? [])]) {
+        const path = join(root, file);
+        if (!existsSync(path)) continue;
+        let text = readFileSync(path, "utf8");
+        if (g.section && file === g.file)
+          text = markdownSection(text, g.section);
+        parts.push(text.trim());
+      }
+      return parts.length ? parts.join("\n\n---\n\n") : undefined;
+    },
+  };
+}

package/cli/mcp.mjs

@@ -0,0 +1,216 @@
+// A Model Context Protocol server over stdio: newline-delimited JSON-RPC 2.0 on
+// stdin/stdout, implemented without dependencies. Only JSON-RPC messages are
+// written to stdout; diagnostics go to stderr.
+import { createInterface } from "node:readline";
+import { loadData } from "./data.mjs";
+import { TOOLS, ToolError, validateArguments } from "./tools.mjs";
+
+/** Protocol revisions this server speaks, newest first. */
+export const PROTOCOL_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+];
+
+export const ERRORS = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603,
+};
+
+class RpcError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+}
+
+const INSTRUCTIONS =
+  "Mortar is an MIT React 19 + Tailwind 4 UI kit (@tonycodes-ui/mortar). Before writing UI, search_components (or list_kits) to find what to reuse, then get_build_packet for the components or the brief and compose from it: start from the purpose shell (AppShell, MarketingHeader, DocsShell, AuthLayout), use named imports and the exact props in each contract, theme through ThemeProvider and tokens, never copy components or override .m-* classes. Run audit_app on the application when done and fix its findings. Missing shared patterns are contributed to the kit by GitHub pull request (get_guide contributing).";
+
+/**
+ * Handle one parsed JSON-RPC message. Returns the response object, or
+ * undefined for notifications.
+ */
+export async function handleMessage(message, context) {
+  const isObject =
+    message && typeof message === "object" && !Array.isArray(message);
+  const id = isObject && "id" in message ? message.id : undefined;
+  const respond = (result) => ({ jsonrpc: "2.0", id, result });
+  const fail = (code, msg, data) => ({
+    jsonrpc: "2.0",
+    id: id === undefined ? null : id,
+    error: { code, message: msg, ...(data !== undefined ? { data } : {}) },
+  });
+  if (
+    !isObject ||
+    message.jsonrpc !== "2.0" ||
+    typeof message.method !== "string" ||
+    (id !== undefined &&
+      id !== null &&
+      typeof id !== "string" &&
+      typeof id !== "number")
+  ) {
+    // A response from the client (we never send requests) needs no answer.
+    if (
+      isObject &&
+      message.jsonrpc === "2.0" &&
+      ("result" in message || "error" in message)
+    )
+      return undefined;
+    return fail(ERRORS.INVALID_REQUEST, "Invalid Request");
+  }
+  const notification = id === undefined;
+  try {
+    const result = await dispatch(message.method, message.params, context);
+    return notification ? undefined : respond(result);
+  } catch (error) {
+    if (notification) return undefined;
+    if (error instanceof RpcError)
+      return fail(error.code, error.message, error.data);
+    context.log(`mortar mcp: ${error?.stack ?? error}`);
+    return fail(ERRORS.INTERNAL, "Internal error");
+  }
+}
+
+async function dispatch(method, params = {}, context) {
+  if (params === null || typeof params !== "object")
+    throw new RpcError(ERRORS.INVALID_PARAMS, "params must be an object");
+  switch (method) {
+    case "initialize": {
+      const requested = params.protocolVersion;
+      if (typeof requested !== "string")
+        throw new RpcError(
+          ERRORS.INVALID_PARAMS,
+          "protocolVersion is required",
+        );
+      const data = await context.data();
+      context.initialized = true;
+      return {
+        protocolVersion: PROTOCOL_VERSIONS.includes(requested)
+          ? requested
+          : PROTOCOL_VERSIONS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: {
+          name: "mortar",
+          title: "Mortar UI kit",
+          version: data.version,
+        },
+        instructions: INSTRUCTIONS,
+      };
+    }
+    case "notifications/initialized":
+    case "notifications/cancelled":
+    case "notifications/progress":
+    case "notifications/roots/list_changed":
+      return {};
+    case "ping":
+      return {};
+    case "tools/list":
+      return {
+        tools: TOOLS.map(({ run, ...tool }) => tool),
+      };
+    case "tools/call": {
+      const tool = TOOLS.find((t) => t.name === params.name);
+      if (!tool)
+        throw new RpcError(
+          ERRORS.INVALID_PARAMS,
+          `Unknown tool: ${params.name}`,
+        );
+      const args = params.arguments ?? {};
+      const invalid = validateArguments(tool, args);
+      if (invalid)
+        return {
+          content: [{ type: "text", text: `Invalid arguments: ${invalid}.` }],
+          isError: true,
+        };
+      try {
+        const result = await tool.run(await context.data(), args);
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                typeof result === "string"
+                  ? result
+                  : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        if (!(error instanceof ToolError))
+          context.log(`mortar mcp: ${error?.stack ?? error}`);
+        return {
+          content: [{ type: "text", text: String(error?.message ?? error) }],
+          isError: true,
+        };
+      }
+    }
+    default:
+      throw new RpcError(
+        ERRORS.METHOD_NOT_FOUND,
+        `Method not found: ${method}`,
+      );
+  }
+}
+
+/** Run the server on stdin/stdout until stdin closes. */
+export function serve({
+  input = process.stdin,
+  output = process.stdout,
+  log = (line) => process.stderr.write(line + "\n"),
+} = {}) {
+  // Nothing but protocol messages may reach stdout.
+  console.log = console.info = console.debug = (...args) => log(args.join(" "));
+  let dataPromise;
+  const context = {
+    data: () => (dataPromise ??= loadData()),
+    log,
+    initialized: false,
+  };
+  const write = (message) => output.write(JSON.stringify(message) + "\n");
+  // Messages are handled one at a time, in order, so responses keep the
+  // order of their requests.
+  let queue = Promise.resolve();
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    queue = queue.then(async () => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        write({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: ERRORS.PARSE, message: "Parse error" },
+        });
+        return;
+      }
+      if (Array.isArray(message)) {
+        if (!message.length) {
+          write({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: ERRORS.INVALID_REQUEST, message: "Invalid Request" },
+          });
+          return;
+        }
+        const responses = (
+          await Promise.all(message.map((m) => handleMessage(m, context)))
+        ).filter(Boolean);
+        if (responses.length) write(responses);
+        return;
+      }
+      const response = await handleMessage(message, context);
+      if (response) write(response);
+    });
+  });
+  return new Promise((resolveDone) => {
+    lines.on("close", () => queue.then(resolveDone));
+  });
+}

package/cli/migrations.mjs

@@ -0,0 +1,128 @@
+// Removed names and their replacements, from docs/migrating-to-0.6.md and the
+// CHANGELOG. The audit uses them to suggest the current name for an import, a
+// prop or a value. tests/cli.test.mjs checks every replacement exists in the
+// catalogue and every removed prop is gone.
+
+export const REMOVED_EXPORTS = {
+  MarketingTone: {
+    replacement: "SectionTone",
+    note: "MarketingTone (surface | inverse) was merged into SectionTone (default | muted | inverse) in 0.6.",
+  },
+};
+
+/** Component → removed prop → { to, note }. */
+export const RENAMED_PROPS = {
+  AppShell: {
+    user: { to: "footer", note: "AppShell `user` became `footer` in 0.6." },
+    secondaryNavigation: {
+      to: "sections",
+      note: "AppShell `secondaryNavigation` became `sections` in 0.6.",
+    },
+  },
+  Hero: {
+    align: {
+      to: "layout",
+      note: 'Hero `align="center" | "split"` became `layout` in 0.6.',
+    },
+  },
+  StackedList: {
+    heading: { to: "title", note: "StackedList `heading` became `title`." },
+  },
+  DataTable: {
+    emptyTitle: { to: "empty", note: "Use `empty={{ title, description? }}`." },
+    emptyDescription: {
+      to: "empty",
+      note: "Use `empty={{ title, description? }}`.",
+    },
+  },
+  Text: { tone: { to: "color", note: "Text `tone` became `color` in 0.6." } },
+  CommandPalette: {
+    emptyMessage: {
+      to: "empty",
+      note: "Use `empty={{ title, description? }}`.",
+    },
+  },
+  Callout: {
+    type: {
+      to: "tone",
+      note: 'Callout `type` became `tone: Tone`: `tip` → `success`, `breaking` → `tone="danger" title="Breaking"`.',
+    },
+  },
+  SaveBar: { saving: { to: "loading", note: "Busy props are `loading`." } },
+  CommentComposer: {
+    submitting: { to: "loading", note: "Busy props are `loading`." },
+    onValueChange: { to: "onChange", note: "Value changes use `onChange`." },
+  },
+  ConfirmDialog: {
+    destructive: {
+      to: "tone",
+      note: 'ConfirmDialog `destructive` became `tone: "default" | "danger"` (default "danger").',
+    },
+  },
+  Combobox: {
+    emptyLabel: { to: "empty", note: "Use `empty={{ title }}`." },
+  },
+  PreviewFrame: {
+    title: {
+      to: "label",
+      note: "PreviewFrame `title` became `label` (an accessible name).",
+    },
+  },
+  ProductOverview: {
+    adding: { to: "loading", note: "Busy props are `loading`." },
+  },
+  ProductQuickView: {
+    adding: { to: "loading", note: "Busy props are `loading`." },
+  },
+  ShoppingCart: {
+    emptyTitle: {
+      to: "empty",
+      note: "Use `empty={{ title, description?, action? }}`.",
+    },
+    emptyDescription: {
+      to: "empty",
+      note: "Use `empty={{ title, description?, action? }}`.",
+    },
+    emptyAction: {
+      to: "empty",
+      note: "Use `empty={{ title, description?, action? }}`.",
+    },
+  },
+  OrderHistory: {
+    emptyTitle: { to: "empty", note: "Use `empty={{ title, description? }}`." },
+    emptyDescription: {
+      to: "empty",
+      note: "Use `empty={{ title, description? }}`.",
+    },
+  },
+};
+
+/** Renames that apply to any component (DESIGN.md API conventions). */
+export const GENERAL_PROPS = {
+  saving: "loading",
+  submitting: "loading",
+  adding: "loading",
+  busy: "loading",
+  isLoading: "loading",
+  emptyTitle: "empty",
+  emptyDescription: "empty",
+  emptyAction: "empty",
+  emptyMessage: "empty",
+  emptyLabel: "empty",
+  heading: "title",
+  onValueChange: "onChange",
+  onClick: "onSelect",
+};
+
+/** Values renamed by the 0.6 conventions. */
+export const RENAMED_VALUES = {
+  centered: "center",
+  card: "cards",
+  surface: "default",
+  sunken: "muted",
+  left: "start",
+  right: "end",
+  tip: "success",
+  note: "info",
+  breaking: "danger",
+};