@usableapp/cardds 0.7.70 → 0.7.72

package/lib/catalog.mjs

@@ -0,0 +1,140 @@
+// lib/catalog.mjs — what an AI session asks of the catalog (dist/catalog.json, built by scripts/build-catalog.mjs) instead of reading src/.
+// Pure functions over the loaded catalog, no dependency beyond node: `npx cardds list|get|find|scaffold` and `npx cardds mcp` (lib/mcp.mjs) are two doors to these.
+// Shipped in the package. The order of a session: find (has a screen like this been drawn?) → scaffold it, or get the components → check.
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkSource } from '../lint/rules.mjs';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CSS = 'node_modules/@usableapp/cardds/dist/cardds.css';
+const OTHERS = 5; // stories of OTHER components that show one in use: how many come with their code (`Btn` is in 117)
+
+/** the catalog of the package, or of a live repo at `root` (rebuilt first, so it is never stale) */
+export function load({ root } = {}) {
+  if (root && existsSync(join(root, 'scripts', 'build-catalog.mjs'))) {
+    execFileSync(process.execPath, [join(root, 'scripts', 'build-catalog.mjs'), root], { stdio: ['ignore', 'ignore', 'inherit'] });
+  }
+  const file = join(root ?? PKG, 'dist', 'catalog.json');
+  if (!existsSync(file)) throw new Error(`no catalog at ${file} — \`npm run build\` in the cardds repo makes it`);
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+/** the names only — the first call of nearly every session, so it stays small */
+export const list = (cat) => cat.components.map(({ name, group }) => ({ name, group }));
+
+const sentence = (text) => {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  const one = flat.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? flat;
+  return one.length > 160 ? `${one.slice(0, 157)}…` : one;
+};
+const isSlot = (type) => /\bReactNode\b/.test(type);
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const keep = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = keep;
+    }
+  }
+  return row[b.length];
+}
+const closest = (names, wanted) => {
+  const w = wanted.toLowerCase();
+  const rank = (n) => (n.toLowerCase().includes(w) || w.includes(n.toLowerCase()) ? 0 : 100) + distance(n.toLowerCase(), w);
+  return [...names].sort((a, b) => rank(a) - rank(b)).slice(0, 5);
+};
+
+/** one component: its props (a ReactNode prop is a slot) and its variations — the stories of its own file first, then a few that use it */
+export function get(cat, name, { html = false, all = false } = {}) {
+  const c = cat.components.find((x) => x.name.toLowerCase() === String(name).toLowerCase());
+  if (!c) return { error: `no component "${name}"`, closest: closest(cat.components.map((x) => x.name), String(name)) };
+  const show = (s) => ({ id: s.id, description: s.description, tsx: s.tsx, ...(html && { html: s.html }) });
+  const own = cat.stories.filter((s) => s.file === c.name);
+  const elsewhere = cat.stories.filter((s) => s.file !== c.name && s.uses.includes(c.name));
+  const shown = all ? elsewhere : [...elsewhere].sort((a, b) => a.tsx.length - b.tsx.length).slice(0, OTHERS);
+  return {
+    name: c.name,
+    group: c.group,
+    description: c.description,
+    element: c.element,
+    props: c.props.map((p) => ({ ...p, ...(isSlot(p.type) && { slot: true }) })),
+    variations: [...own, ...elsewhere.filter((s) => shown.includes(s))].map(show),
+    ...(elsewhere.length > shown.length && { alsoUsedIn: elsewhere.filter((s) => !shown.includes(s)).map((s) => s.id) }),
+  };
+}
+
+const words = (text) => text.replace(/([a-z\d])([A-Z])/g, '$1 $2').toLowerCase().match(/[\p{L}\p{M}\p{N}]+/gu) ?? [];
+const STOP = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'into', 'of', 'to', 'in', 'on', 'an', 'a']);
+const tokens = (query) => [...new Set(words(String(query)).filter((t) => t.length > 1 && !STOP.has(t)))];
+const stem = (t) => (t.length > 3 && t.endsWith('s') ? t.slice(0, -1) : t);
+const hits = (text, token) => words(text).some((w) => w.startsWith(token) || w.startsWith(stem(token)));
+
+/** short ranked answer to "what is there for this?": screens already drawn first, then components, then what they are used with.
+ *  A query that matches nothing (another language, say) returns every screen's id with `fallback: true` — ask again in English, or pick the nearest. */
+export function find(cat, query) {
+  const toks = tokens(query);
+  const rank = (items, fields) => items
+    .map((item) => {
+      let matched = 0, score = 0;
+      for (const t of toks) {
+        const w = fields(item).filter(([text]) => hits(text, t)).reduce((sum, [, weight]) => sum + weight, 0);
+        if (w) { matched++; score += w; }
+      }
+      return { item, matched, score };
+    })
+    .filter((r) => r.matched)
+    .sort((a, b) => b.matched - a.matched || b.score - a.score);
+  const screenOf = (s) => ({ kind: 'screen', id: s.id, summary: sentence(s.description) });
+  const screens = cat.stories.filter((s) => s.screen);
+  const ranked = [
+    ...rank(screens, (s) => [[s.id, 5], [s.description, 3], [s.uses.join(' '), 1]]).slice(0, 8).map((r) => screenOf(r.item)),
+    ...rank(cat.components, (c) => [[c.name, 6], [c.description, 2], [c.props.map((p) => p.name).join(' '), 1]]).slice(0, 8)
+      .map((r) => ({ kind: 'component', name: r.item.name, summary: sentence(r.item.description) })),
+  ];
+  if (!ranked.length) return { query, fallback: true, hint: 'the names and descriptions are English: ask again in English words', results: screens.map((s) => ({ kind: 'screen', id: s.id })) };
+
+  const matched = new Set(ranked.filter((r) => r.kind === 'component').map((r) => r.name));
+  const together = new Map();
+  for (const s of cat.stories) if (s.uses.some((u) => matched.has(u))) for (const u of s.uses) if (!matched.has(u)) together.set(u, (together.get(u) ?? 0) + 1);
+  const usedTogether = [...together].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 8).map(([name, stories]) => ({ name, stories }));
+  return { query, results: ranked, usedTogether };
+}
+
+/** no id: the screens already drawn. With one: a file to start from — `tsx` (the code) or `html` (the look, static) */
+export function scaffold(cat, id, { format = 'tsx', css = CSS } = {}) {
+  if (!id) return cat.stories.filter((s) => s.screen).map((s) => ({ id: s.id, summary: sentence(s.description) }));
+  const s = cat.stories.find((x) => x.id.toLowerCase() === String(id).toLowerCase());
+  if (!s) return { error: `no story "${id}"`, closest: closest(cat.stories.map((x) => x.id), String(id)) };
+  if (format === 'html') {
+    if (!s.html) return { error: `${s.id} has no rendered html: ${s.htmlError ?? 'it did not render'}` };
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content">
+<title>${s.id}</title>
+<link rel="stylesheet" href="${css}">
+</head>
+<body>
+<!-- ${s.id}, rendered once: the look only, no behaviour. \`scaffold ${s.id}\` (tsx) is the working code -->
+${s.html}
+</body>
+</html>
+`;
+  }
+  const glue = [...s.imports.matchAll(/import (.+?) from '\.\/_[^']*';/g)]
+    .flatMap((m) => m[1].replace(/[{}]/g, '').split(',').map((n) => n.trim().replace(/^type /, '').split(/ as /).pop()).filter(Boolean));
+  const taken = /\bScreen\b/.test(s.imports) || /^(?:function|const|class|type|interface) Screen\b/m.test(s.tsx);
+  const as = taken ? 'MyScreen' : 'Screen';
+  const note = glue.length ? `// story glue from ./_*, not part of the package — replace or drop: ${glue.join(', ')}\n` : '';
+  return `${note}${s.imports}\n\n${s.tsx.replace(new RegExp(`^function ${s.name}\\b`, 'm'), `export default function ${as}`)}\n`;
+}
+
+/** the rules of lint/rules.mjs over a piece of code */
+export const check = (code, filename = 'screen.tsx') => checkSource(code, filename);

package/lib/mcp.mjs

@@ -0,0 +1,91 @@
+// lib/mcp.mjs — `npx cardds mcp`: the catalog (lib/catalog.mjs) as an MCP server over stdio, so an AI session asks instead of reading src/.
+// Newline-delimited JSON-RPC 2.0 written by hand: the package has no MCP SDK and takes none. stdout carries protocol messages ONLY.
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as catalog from './catalog.mjs';
+
+const { version } = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+const str = (description) => ({ type: 'string', description });
+const bool = (description) => ({ type: 'boolean', description });
+
+const TOOLS = [
+  {
+    name: 'list_components',
+    description: 'The names of every cardds component and the group it belongs to, nothing else. Call this once, first, in a session that will build a UI with cardds, to learn what exists; then get_component for the ones you use.',
+    inputSchema: { type: 'object', properties: {} },
+    run: (cat) => catalog.list(cat),
+  },
+  {
+    name: 'get_component',
+    description: 'One component in full: what it is, its props (a prop marked slot takes children: ReactNode), and its variations, each a working story with its code. Call it before you use a component you have not used yet, and copy a variation rather than guessing a prop. A component used everywhere (Btn, Text) comes with a few of its stories and the ids of the rest (pass all for their code). Names are case-insensitive; a miss returns the closest names.',
+    inputSchema: { type: 'object', properties: { name: str('component name, e.g. Menu'), html: bool('also return each variation\'s rendered HTML — only to see the markup it makes'), all: bool('include the code of every story that uses the component') }, required: ['name'] },
+    run: (cat, a) => catalog.get(cat, a.name, { html: a.html, all: a.all }),
+  },
+  {
+    name: 'find_components',
+    description: 'Search by words ("stamp", "otp pin", "bottom sheet") when you do not know the component name. Answers short: the screens cardds has already drawn first, then components, then the components most often used together with them. Call it at the start of a task, before composing a screen from parts: if a screen like it exists, scaffold_screen gives its code. Ask in ENGLISH words — the names and descriptions are English; translate the request first. A query that matches nothing returns the id of every screen (fallback: true).',
+    inputSchema: { type: 'object', properties: { query: str('English words describing the screen or the part') }, required: ['query'] },
+    run: (cat, a) => catalog.find(cat, a.query),
+  },
+  {
+    name: 'scaffold_screen',
+    description: 'Start from a screen cardds has already drawn. With no id: the list of such screens, one line each. With an id (from find_components): a complete file to start from — format tsx (default) is the React code with its imports, edit its content for the task; format html is a static document (the look only, no behaviour) that links cardds.css, for a prototype without React. A tsx file may name story glue (from ./_story) that is not in the package: replace or drop it.',
+    inputSchema: { type: 'object', properties: { id: str('a screen id such as StampScreens/MakeStamp; omit to list the screens'), format: { type: 'string', enum: ['tsx', 'html'], description: 'tsx (default) or html' }, css: str('html only: the href of cardds.css from where the file will sit; default node_modules/@usableapp/cardds/dist/cardds.css') } },
+    run: (cat, a) => catalog.scaffold(cat, a.id, { format: a.format, css: a.css }),
+  },
+  {
+    name: 'check_source',
+    description: 'Run cardds\'s rules over code you wrote (a hand-written cardds class, a Sheet that cannot move, a bar with a sheet…). Call it on each screen before you call it done; an empty list means clean, an error must be fixed.',
+    inputSchema: { type: 'object', properties: { code: str('the .tsx/.jsx source'), filename: str('its file name, for the report (default screen.tsx)') }, required: ['code'] },
+    run: (_cat, a) => catalog.check(a.code, a.filename),
+  },
+];
+
+const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/** serve the catalog until the client closes stdin; `root` serves a live repo (rebuilt first) instead of the package's */
+export function serve({ root, input = process.stdin, output = process.stdout } = {}) {
+  let cat;
+  const text = (r) => typeof r === 'string' ? r : JSON.stringify(r);
+
+  function call(params) {
+    const tool = TOOLS.find((t) => t.name === params?.name);
+    if (!tool) return null;
+    const args = params.arguments ?? {};
+    const missing = tool.inputSchema.required?.find((k) => typeof args[k] !== 'string');
+    if (missing) return { content: [{ type: 'text', text: `${tool.name}: "${missing}" is required (a string)` }], isError: true };
+    try {
+      cat ??= catalog.load({ root });
+      const result = tool.run(cat, args);
+      return { content: [{ type: 'text', text: text(result) }], ...(result?.error && { isError: true }) };
+    } catch (e) { return { content: [{ type: 'text', text: `${tool.name}: ${e.message}` }], isError: true }; }
+  }
+
+  function handle(msg) {
+    const { id, method, params } = msg;
+    switch (method) {
+      case 'initialize': return reply(id, { protocolVersion: params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'cardds', version } });
+      case 'ping': return reply(id, {});
+      case 'tools/list': return reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+      case 'tools/call': { const r = call(params); return r ? reply(id, r) : fail(id, -32602, `unknown tool: ${params?.name}`); }
+      default: return fail(id, -32601, `method not found: ${method}`);
+    }
+  }
+
+  return new Promise((done) => {
+    const send = (msg) => output.write(`${JSON.stringify(msg)}\n`);
+    const lines = createInterface({ input });
+    lines.on('line', (line) => {
+      if (!line.trim()) return;
+      let msg;
+      try { msg = JSON.parse(line); } catch { return send(fail(null, -32700, 'parse error')); }
+      if (!msg || typeof msg !== 'object') return send(fail(null, -32600, 'invalid request'));
+      if (msg.id === undefined) return; // a notification (notifications/initialized…) is never answered
+      send(handle(msg));
+    });
+    lines.on('close', done);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.70",
+  "version": "0.7.72",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "dev": "vite --config gallery/vite.config.ts",
-    "build": "node scripts/build-icons.mjs && tsc -p tsconfig.json && node scripts/flatten-css.mjs",
+    "build": "node scripts/build-icons.mjs && tsc -p tsconfig.json && node scripts/flatten-css.mjs && node scripts/build-catalog.mjs",
     "test": "playwright test",
     "validate:inbox": "node scripts/validate-inbox.mjs",
     "prepack": "npm run build",
@@ -52,6 +52,7 @@
   "files": [
     "dist",
     "lint",
+    "lib",
     "bin",
     "css",
     "fonts",