@usableapp/cardds 0.7.71 → 0.7.73

package/lib/mcp.mjs

@@ -0,0 +1,107 @@
+// 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 what each is FOR, nothing else. represents is what it stands for (person, group, time…) or, for a control that stands for no one thing, the KIND of data it carries (words, number, picture, signal); the word in parentheses after a name in the text is its represents. Every component shows information; shape says how much: "one" (one thing), "group-brief" (a group read at a glance or in a line), "group-detail" (a group read in detail), "—" (a helper function or structure, not something drawn). interact says whether the member can do something with it: false (it only shows or holds), or the kinds, any of pick, act, write, navigate — alone when shape is one (a Btn acts), as a group when shape is a group (a Segment picks among several). Two kinds mean it does both. group is the src folder, not what it is for. 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: (cat) => `Find what to build with when you do not know the component name. Ask BOTH ways and read both answers: by the AXES (translated from the request) AND by the English noun of the task ("stamp", "otp", "postcard") — the screen already drawn is often found by the noun. The axes are a closed vocabulary, so ask by them in any language: represents (what it stands for, or for a control the KIND of data it carries${cat ? `: ${catalog.vocabulary(cat).represents.join(' · ')}` : ' — the word in parentheses after a name in list_components'}), shape (one · group-brief · group-detail · group = either group shape), interact (the kinds the member can do with it: ${catalog.KINDS.join(' · ')}, or "none" = it only shows). "Show all the members" is represents [person] + shape group; adding interact [pick] narrows it to the ones the member chooses from. Whatever matches every axis you give comes first, each with its role so you see why; with axes and no words they are the whole answer. Words ("stamp", "otp pin", "bottom sheet") rank what matches only by words, in ENGLISH — the names and descriptions are English, translate first. Answers short: the screens cardds has already drawn (a screen is a composition: it counts when its parts answer the axes between them, one component per axis, and one that answers them all ranks higher), 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. A query that matches nothing returns fallback: true, a hint and the number of screens drawn, not their ids: ask again in English words or by the axes, or call scaffold_screen with no id to list them.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        represents: { type: 'array', items: { type: 'string' }, description: 'what it stands for, e.g. ["person"]; a component must hold every value you give' },
+        shape: { type: 'string', enum: ['one', 'group-brief', 'group-detail', 'group'], description: 'how many it shows and how much reading; group = group-brief or group-detail' },
+        interact: { anyOf: [{ type: 'array', items: { type: 'string' }, description: 'kinds, e.g. ["pick"]; the component must have every one' }, { type: 'string', enum: ['none'], description: 'only shows, nothing to do with it' }] },
+        query: str('English words describing the screen or the part; optional when axes are given'),
+      },
+    },
+    run: (cat, a) => catalog.find(cat, a.query ?? '', { represents: a.represents, shape: a.shape, interact: a.interact === 'none' ? false : a.interact }),
+  },
+  {
+    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 — when the screen has a sheet, menu, step or the like, the file begins with a comment saying the static picture is not the layout. 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) => {
+      const r = catalog.scaffold(cat, a.id, { format: a.format, css: a.css });
+      return typeof r.html === 'string' ? `${r.warning ? `<!-- ${r.warning} -->\n` : ''}${r.html}` : r; // the warning first, where a caller reading the top of the file cannot miss it
+    },
+  },
+  {
+    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);
+
+  // the catalog, or nothing: listing the tools must not fail because it cannot be loaded (a call says why)
+  function loaded() {
+    try { return (cat ??= catalog.load({ root })); } catch { return undefined; }
+  }
+
+  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: typeof description === 'function' ? description(loaded()) : 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/lib/role.mjs

@@ -0,0 +1,30 @@
+// lib/role.mjs — the role table (docs/roles.md) read, and what a role says a component is FOR. Pure, no fs: the catalog (node), scripts/roles.mjs
+// and the gallery's nav (browser) all read the table through these.
+const AXES = ['represents', 'count', 'density', 'job'];
+const values = (cell) => cell.trim().split(' · ').map((v) => v.trim()).filter(Boolean);
+
+/** the text of docs/roles.md → `vocabulary` (each axis's closed values) and `rows` (one per component). Hand-written; the vocabulary is the
+ *  table's own definition lines, so a value outside it is the test's to catch, not this reader's. */
+export function parseRoles(doc) {
+  const vocabulary = Object.fromEntries([...doc.matchAll(/^- `([a-z]+)`: (.+)$/gm)].filter((m) => AXES.includes(m[1])).map((m) => [m[1], values(m[2])]));
+  const rows = [...doc.matchAll(/^\| (?!component )([A-Za-z]\w*) \| ([a-z]+) \|(.*)\|$/gm)].map((m) => {
+    const [represents, count, density, job, stands, note] = m[3].split('|').map((c) => c.trim());
+    return {
+      component: m[1],
+      group: m[2],
+      represents: values(represents), count: values(count), density: values(density), job: values(job),
+      standsInFor: stands ? stands.split(';').map((s) => s.trim().match(/^(\w+)(?: \((.*)\))?$/)).map((x) => ({ name: x[1], condition: x[2] ?? '' })) : [],
+      note: note.replace(/^\?\s*/, ''),
+      unsure: note.startsWith('?'),
+    };
+  });
+  return { vocabulary, rows };
+}
+
+// What a component is FOR, read from its role: every component shows information; what differs is how much it shows
+// (`one` thing, a group in brief, a group in detail) and whether the member can do something with it (and what: pick, act, write, navigate).
+export const SHAPES = ['one', 'group-brief', 'group-detail', '—'];
+export const KINDS = ['pick', 'act', 'write', 'navigate'];
+export const shapeOf = ({ count: [count], density: [density] }) =>
+  count === 'one' ? 'one' : count === 'few' || count === 'many' ? (density === 'detail' || density === 'full' ? 'group-detail' : 'group-brief') : '—'; // a holder with no density of its own claims no detail
+export const interactOf = ({ job }) => job.some((j) => KINDS.includes(j)) ? job.filter((j) => KINDS.includes(j)) : false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.71",
+  "version": "0.7.73",
   "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",