@usableapp/cardds 0.7.71 → 0.7.72

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 > For: a project that consumes `@usableapp/cardds` and its AI — what changed between versions, written as before → after, so a screen can be brought up to date without reading the source. Newest first. A consumer never edits cardds; if something here leaves you without a way to do what you did before, report the gap.
 
+## 0.7.72 — 2026-10-08
+
+### Added
+- **The catalog — for an AI session that builds with cardds** (Lh 2026-10-08) — the package now carries every component, its props and slots, and every variation's code and rendered HTML (`dist/catalog.json`), with one set of commands over it. Before → after: a session read `src/` and the gallery's stories to learn a component → it asks. `npx cardds list` (every name, by group) · `npx cardds get Menu [--html] [--all]` (props, slots, each variation's code) · `npx cardds find stamp picker` (the screens already drawn first, then components, then what they are used with — ask in English words) · `npx cardds scaffold [id] [--html [--css <href>]]` (a file to start a screen from: the React code, or a static HTML page that links `cardds.css`) · `npx cardds check` as before. Each takes `--json`.
+- **`npx cardds mcp`** — the same five as an MCP server over stdio (`list_components`, `get_component`, `find_components`, `scaffold_screen`, `check_source`): `{"mcpServers":{"cardds":{"command":"npx","args":["cardds","mcp"]}}}`. It answers for the version the project has installed. README "For an AI session: the catalog".
+
 ## 0.7.71 — 2026-10-08
 
 ### Fixed

package/README.md

@@ -136,6 +136,28 @@ back here. It is deliberately thin — **this repo stays the source of truth**,
 so new components and rule changes go here, and the skill only gets updated
 if the contract itself changes.
 
+### For an AI session: the catalog
+
+A session asked for a prototype need not read `src/`: the package ships a catalog (`dist/catalog.json`, built by
+`npm run build`) of every component — props, slots — and every story with its code and its rendered HTML. Ask it first:
+
+```bash
+npx cardds find <words…>        # the screens already drawn, then components, then what is used with them (no match → every screen)
+npx cardds scaffold <id>        # a whole file from a screen: tsx (the code) or --html (a static document linking cardds.css)
+npx cardds get <Name> [--html]  # one component: props (a ReactNode prop is a slot) + variations with code
+npx cardds list                 # every name and group, nothing more
+npx cardds check <dir>          # the rules, before a screen is called done
+```
+
+All take `--json` (the function's result) and `--root <path>` (a cardds checkout: rebuilt first, so never stale). The same
+five answers over MCP — `list_components` · `get_component` · `find_components` · `scaffold_screen` · `check_source`:
+
+```json
+{ "mcpServers": { "cardds": { "command": "npx", "args": ["cardds", "mcp"] } } }
+```
+
+A scaffolded tsx may import `./_story` or `./_*Art`: story glue, not in the package — replace or drop it.
+
 ### React adapter — how a component is written
 
 `src/<group>/<Name>.tsx`, one export per class family; sub-parts are their own

package/bin/cardds.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 // `npx cardds init` — set a project up the ONE way (Lh 2026-09-29): the project's theme.css, the check script, the ESLint rules.
 // `npx cardds check [dir…]` — the rules of lint/rules.mjs over the project's source; exit 1 on an error.
+// `npx cardds list | get <Name> | find <words…> | scaffold [id]` — the component catalog (lib/catalog.mjs) for an AI session; `npx cardds mcp` serves the same over MCP.
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkSource } from '../lint/rules.mjs';
+import * as catalog from '../lib/catalog.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const [cmd, ...args] = process.argv.slice(2);
@@ -68,5 +70,43 @@ import them, never copy their markup: the behaviour lives in the component. Gall
   return 0;
 }
 
-const code = cmd === 'check' ? check(args) : cmd === 'init' ? init() : (console.log('usage: cardds init | cardds check [dir…]'), cmd ? 2 : 0);
-process.exit(code);
+const one = (text) => text.replace(/\s+/g, ' ').trim();
+const indent = (text, by = '    ') => text.replace(/^(?=.)/gm, by);
+
+// each catalog command: the function's result as compact text (--json prints the result itself)
+const asText = {
+  list: (groups) => Object.entries(Object.groupBy(groups, (c) => c.group)).map(([g, cs]) => `${g}: ${cs.map((c) => c.name).join(' ')}`).join('\n'),
+  get: (c, { html }) => [
+    `${c.name} (${c.group})${c.element ? ` — forwards the <${c.element}> attributes` : ''}`,
+    one(c.description),
+    '\nprops',
+    ...c.props.map((p) => `  ${p.name}${p.optional ? '?' : ''}: ${p.type}${p.slot ? '  [slot]' : ''}${p.description ? ` — ${one(p.description)}` : ''}`),
+    `\nvariations (${c.variations.length})`,
+    ...c.variations.map((v) => `\n  ${v.id} — ${one(v.description)}\n${indent(v.tsx)}${html ? `\n    html:\n${indent(v.html, '      ')}` : ''}`),
+    ...(c.alsoUsedIn ? [`\nalso used in: ${c.alsoUsedIn.join(' ')}\n(--all prints their code too)`] : []),
+  ].join('\n'),
+  find: (r) => [
+    ...(r.fallback ? [`nothing matches "${r.query}" — ${r.hint}. Every screen already drawn:\n${r.results.map((x) => x.id).join(' ')}`] : r.results.map((x) => `${x.kind === 'screen' ? 'screen    ' : 'component '}${x.id ?? x.name} — ${x.summary}`)),
+    ...(r.usedTogether?.length ? [`\nused together: ${r.usedTogether.map((u) => `${u.name} (${u.stories})`).join(' ')}`] : []),
+  ].join('\n'),
+  scaffold: (r) => typeof r === 'string' ? r.trimEnd() : r.map((x) => `${x.id} — ${x.summary}`).join('\n'),
+};
+
+function ask(cmd, argv) {
+  const flag = (name) => { const i = argv.indexOf(name); return i >= 0 && argv.splice(i, 1).length > 0; };
+  const at = argv.indexOf('--root');
+  const root = at >= 0 ? join(cwd, argv.splice(at, 2)[1] ?? '') : undefined;
+  const cssAt = argv.indexOf('--css'), css = cssAt >= 0 ? argv.splice(cssAt, 2)[1] : undefined;
+  const json = flag('--json'), html = flag('--html'), all = flag('--all');
+  if (cmd === 'mcp') return import('../lib/mcp.mjs').then((m) => m.serve({ root }));
+  const cat = catalog.load({ root });
+  const q = argv.join(' ');
+  const result = cmd === 'list' ? catalog.list(cat) : cmd === 'get' ? catalog.get(cat, q, { html, all }) : cmd === 'find' ? catalog.find(cat, q) : catalog.scaffold(cat, q || undefined, { format: html ? 'html' : 'tsx', css });
+  if (result.error) { console.error(`cardds ${cmd}: ${result.error}${result.closest ? ` — closest: ${result.closest.join(', ')}` : ''}`); return 1; }
+  console.log(json ? JSON.stringify(result) : asText[cmd](result, { html }));
+  return 0;
+}
+
+const code = cmd === 'check' ? check(args) : cmd === 'init' ? init() : ['list', 'get', 'find', 'scaffold', 'mcp'].includes(cmd) ? await ask(cmd, args)
+  : (console.log('usage: cardds init | check [dir…] | list | get <Name> [--html] | find <words…> | scaffold [id] [--html [--css <href>]] | mcp   (list get find scaffold mcp: --root <path> --json)'), cmd ? 2 : 0);
+process.exitCode = code;  // not process.exit: a big answer piped to a reader is cut off by an exit before it is flushed