@a2uicatalog/mcp 0.1.1 → 0.2.0

package/cli-test.mjs

@@ -0,0 +1,54 @@
+// cli-test.mjs — the CLI must agree with the server it fronts.
+//
+// The interesting failure is not "does it run" but "does it tell the truth":
+// validate reads the BUNDLED vocabulary snapshot while render asks the live
+// endpoint, so the two drift apart the moment data/ goes stale. That happened
+// on the first run of this CLI — validate reported a payload clean that the
+// server correctly refused — which is why the agreement is asserted here
+// rather than assumed.
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, unlinkSync } from 'node:fs';
+
+const run = (args, ok = [0]) => {
+  try { return { out: execFileSync('node', ['cli.mjs', ...args], { encoding: 'utf8' }), code: 0 }; }
+  catch (e) {
+    if (!ok.includes(e.status)) throw new Error(`a2ui ${args.join(' ')} exited ${e.status}\n${e.stderr}`);
+    return { out: (e.stdout || '') + (e.stderr || ''), code: e.status };
+  }
+};
+let n = 0;
+const t = (name, fn) => { fn(); n++; console.log(`  ok  ${name}`); };
+
+const f = '/tmp/a2ui-cli-test.json';
+writeFileSync(f, JSON.stringify({ blocks: [{ type: 'heading', text: 'x' }, { type: 'quiz_set', questions: [] }] }));
+
+t('help lists every command', () => {
+  const { out } = run(['help']);
+  for (const c of ['render', 'validate', 'atoms', 'surfaces'])
+    if (!out.includes(c)) throw new Error(`help omits ${c}`);
+});
+t('validate passes a clean payload', () => {
+  writeFileSync(f, JSON.stringify({ blocks: [{ type: 'heading', text: 'x' }] }));
+  if (run(['validate', f]).code !== 0) throw new Error('clean payload rejected');
+});
+t('validate rejects an unknown atom', () => {
+  writeFileSync(f, JSON.stringify({ blocks: [{ type: 'not_an_atom' }] }));
+  if (run(['validate', f], [0, 1]).code !== 1) throw new Error('unknown atom accepted');
+});
+t('validate honours the surface declaration', () => {
+  writeFileSync(f, JSON.stringify({ blocks: [{ type: 'quiz_set', questions: [] }] }));
+  const r = run(['validate', f, '--surface', 'web'], [0, 1]);
+  if (r.code !== 1 || !r.out.includes('incompatible'))
+    throw new Error('quiz_set accepted on web — bundled vocabulary is stale (npm run sync-data)');
+});
+t('surfaces reports declared incompatibility', () => {
+  if (!run(['surfaces', 'quiz_set']).out.includes('incompatible'))
+    throw new Error('surfaces omits incompatible_on');
+});
+t('atoms filters by surface', () => {
+  const all = run(['atoms']).out.split('\n').length;
+  const email = run(['atoms', '--surface', 'email']).out.split('\n').length;
+  if (!(email < all)) throw new Error('--surface did not narrow the list');
+});
+unlinkSync(f);
+console.log(`\n${n} CLI checks passed`);

package/cli.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// cli.mjs — the A2UI command line.
+//
+// The on-ramp for someone who wants the vocabulary and none of the protocol:
+// no MCP client, no connector, no deployment, no account. Compose a payload
+// against spec.json, render it, get HTML.
+//
+//   npx @a2uicatalog/mcp render page.json > page.html
+//   npx @a2uicatalog/mcp validate page.json
+//   npx @a2uicatalog/mcp atoms --surface email
+//   npx @a2uicatalog/mcp surfaces quiz_set
+//
+// ZERO DEPENDENCIES. Node 18+ has fetch built in, and the vocabulary ships in
+// data/ so validate and atoms work with no network at all. Only `render`
+// leaves the machine, and only to the public endpoint.
+//
+// This file exists because package.json has described this package as
+// "CLI + local MCP server" since 0.1.0 while `bin` pointed at the stdio MCP
+// server and no command line existed. Same class of overclaim the catalogue
+// spent 2026-08-02 removing from its own schema; the honest fix is to build
+// the thing that was advertised.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BASE = process.env.A2UI_BASE || 'https://a2uicatalog.ai';
+const KEY = process.env.A2UI_RENDER_KEY || '';
+
+const die = (msg, code = 1) => { process.stderr.write(`a2ui: ${msg}\n`); process.exit(code); };
+
+function loadSpec() {
+  for (const p of [join(HERE, 'data', 'spec.json'), join(HERE, '..', 'public', 'spec.json')]) {
+    if (existsSync(p)) return JSON.parse(readFileSync(p, 'utf8'));
+  }
+  die('vocabulary not found — reinstall the package, or run from a repo checkout');
+}
+
+function readPayload(file) {
+  const raw = file && file !== '-' ? readFileSync(file, 'utf8') : readFileSync(0, 'utf8');
+  let p;
+  try { p = JSON.parse(raw); } catch (e) { die(`${file || 'stdin'} is not valid JSON: ${e.message}`); }
+  return Array.isArray(p) ? { blocks: p } : p;
+}
+
+// Walk nested blocks the way the render endpoint does, so validate sees the
+// same atoms the server will.
+function collect(blocks, out = new Set(), depth = 0) {
+  if (depth > 20 || !Array.isArray(blocks)) return out;
+  for (const b of blocks) {
+    if (!b || typeof b !== 'object') continue;
+    const t = b.component || b.type;
+    if (typeof t === 'string') out.add(t);
+    for (const v of Object.values(b)) {
+      if (Array.isArray(v)) collect(v.filter((x) => x && typeof x === 'object'), out, depth + 1);
+      else if (v && typeof v === 'object') collect([v], out, depth + 1);
+    }
+  }
+  return out;
+}
+
+const CMD = {
+  async render(args) {
+    const surface = takeFlag(args, '--surface');
+    const payload = readPayload(args[0]);
+    const url = `${BASE}/api/render${surface ? `?surface=${encodeURIComponent(surface)}` : ''}`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(KEY ? { 'x-a2ui-render-key': KEY } : {}) },
+      body: JSON.stringify(payload),
+    });
+    const body = await res.text();
+    if (!res.ok) die(`render failed (${res.status}): ${body.slice(0, 300)}`);
+    // Degradation is reported on stderr so stdout stays pipeable to a file.
+    for (const [h, label] of [['x-a2ui-incompatible', 'omitted (incompatible)'],
+                              ['x-a2ui-degraded', 'degraded'],
+                              ['x-a2ui-unpublished', 'not published']]) {
+      const v = res.headers.get(h);
+      if (v) process.stderr.write(`a2ui: ${label} on ${surface || 'this surface'}: ${v}\n`);
+    }
+    process.stdout.write(body);
+  },
+
+  validate(args) {
+    const spec = loadSpec();
+    const known = new Map((spec.atoms || []).map((a) => [a.type, a]));
+    const surface = takeFlag(args, '--surface');
+    const payload = readPayload(args[0]);
+    if (!Array.isArray(payload.blocks) || !payload.blocks.length) die('payload has no blocks');
+    const used = [...collect(payload.blocks)];
+    let bad = 0;
+    for (const t of used) {
+      const a = known.get(t);
+      if (!a) { console.error(`  unknown atom  ${t}`); bad++; continue; }
+      if (!surface) continue;
+      const s = a.surfaces || {};
+      if ((s.incompatible_on || []).some((x) => x.surface === surface)) {
+        console.error(`  incompatible  ${t} on ${surface}`); bad++;
+      } else if ((s.degraded_on || []).some((x) => x.surface === surface)) {
+        console.error(`  degraded      ${t} on ${surface}`);
+      }
+    }
+    console.log(`${used.length} atom(s) checked${surface ? ` for ${surface}` : ''}: ` +
+                `${bad ? `${bad} problem(s)` : 'all valid'}`);
+    process.exit(bad ? 1 : 0);
+  },
+
+  atoms(args) {
+    const spec = loadSpec();
+    const surface = takeFlag(args, '--surface');
+    const grep = args[0];
+    let list = spec.atoms || [];
+    if (surface) list = list.filter((a) => ((a.surfaces || {}).works_on || []).includes(surface));
+    if (grep) list = list.filter((a) => a.type.includes(grep) ||
+      (a.compact_description || '').toLowerCase().includes(grep.toLowerCase()));
+    for (const a of list) console.log(`${a.type.padEnd(28)} ${a.compact_description || ''}`);
+    console.error(`\n${list.length} atom(s)${surface ? ` on ${surface}` : ''}`);
+  },
+
+  surfaces(args) {
+    const t = args[0] || die('usage: a2ui surfaces <atom>');
+    const a = (loadSpec().atoms || []).find((x) => x.type === t) || die(`unknown atom '${t}'`);
+    const s = a.surfaces || {};
+    console.log(`${t} — ${a.compact_description || ''}\n`);
+    for (const x of s.works_on || []) console.log(`  works        ${x}`);
+    for (const d of s.degraded_on || []) console.log(`  degraded     ${d.surface}  ${d.note || ''}`);
+    for (const d of s.incompatible_on || []) console.log(`  incompatible ${d.surface}  ${d.reason || ''}`);
+  },
+
+  help() {
+    process.stdout.write(`a2ui — the A2UI Atomic Catalog command line
+
+  render <file|->  [--surface S]   payload in, HTML on stdout
+  validate <file|-> [--surface S]  check atoms exist and are supported; exit 1 if not
+  atoms [match] [--surface S]      browse the vocabulary
+  surfaces <atom>                  where one atom works, degrades, or cannot go
+
+Surfaces for --surface: web · mcp-apps · google-apps-script-web · google-meet-stage
+
+  A2UI_BASE         override the endpoint (default https://a2uicatalog.ai)
+  A2UI_RENDER_KEY   unmetered rendering, if you have a key
+
+validate and atoms are fully offline — the vocabulary ships with the package.
+Only render makes a network call. No account, no API key, no MCP client.
+
+  npx @a2uicatalog/mcp render page.json > page.html
+`);
+  },
+};
+
+function takeFlag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return null;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+const fn = CMD[cmd] || (cmd === undefined || cmd === '--help' || cmd === '-h' ? CMD.help : null);
+if (!fn) die(`unknown command '${cmd}' — try: a2ui help`);
+await fn(rest);

package/data/atoms-index.json

@@ -3324,6 +3324,7 @@
    "type": "paragraph",
    "compact": "prose paragraph (GAS alias for body)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3332,6 +3333,7 @@
    "type": "text_block",
    "compact": "plain text block",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3340,6 +3342,7 @@
    "type": "blockquote",
    "compact": "styled pull-quote with attribution",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3348,6 +3351,7 @@
    "type": "spacer",
    "compact": "vertical whitespace gap",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3356,6 +3360,7 @@
    "type": "tag_chip",
    "compact": "inline tag chip",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3364,6 +3369,7 @@
    "type": "badge",
    "compact": "inline badge pill",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3372,6 +3378,7 @@
    "type": "inline_code",
    "compact": "monospace inline code span",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3380,6 +3387,7 @@
    "type": "code_block",
    "compact": "syntax-highlighted code block",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3388,6 +3396,7 @@
    "type": "link_button",
    "compact": "text hyperlink button",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3396,6 +3405,7 @@
    "type": "cta_button",
    "compact": "call-to-action button",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3414,6 +3424,7 @@
    "type": "info_card",
    "compact": "simple info card with title and body",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3438,6 +3449,7 @@
    "type": "dark_hero",
    "compact": "dark hero banner with gradient and CTA",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3446,6 +3458,7 @@
    "type": "glowing_stat",
    "compact": "neon-glow stat number on dark card",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3454,6 +3467,7 @@
    "type": "glass_card",
    "compact": "frosted-glass card with blur backdrop — dark-theme highlight box",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3462,6 +3476,7 @@
    "type": "gradient_border_card",
    "compact": "animated gradient border card",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3470,6 +3485,7 @@
    "type": "floating_orbs",
    "compact": "decorative blurred colour orbs background",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3486,6 +3502,7 @@
    "type": "dark_feature_grid",
    "compact": "dark-theme feature grid with icons",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3494,6 +3511,7 @@
    "type": "dark_divider",
    "compact": "dark-theme horizontal divider",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3510,6 +3528,7 @@
    "type": "depth_stack",
    "compact": "stacked cards with depth parallax",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3526,6 +3545,7 @@
    "type": "scroll_trigger",
    "compact": "scroll-triggered animated reveal",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3534,6 +3554,7 @@
    "type": "flow_connector",
    "compact": "animated beam connector between two or more nodes",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3542,6 +3563,7 @@
    "type": "live_metric",
    "compact": "animated counting number (alias for animated_counter)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3550,6 +3572,7 @@
    "type": "deadline_ticker",
    "compact": "countdown timer to a target date (alias)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3558,6 +3581,7 @@
    "type": "pattern_background",
    "compact": "dot-grid pattern background (alias)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3566,6 +3590,7 @@
    "type": "glitch_text",
    "compact": "RGB-split glitch-effect headline",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3598,6 +3623,7 @@
    "type": "floating_particles",
    "compact": "floating particles background (canvas placeholder)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3606,6 +3632,7 @@
    "type": "parallax_section",
    "compact": "parallax scroll section (canvas placeholder)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3614,6 +3641,7 @@
    "type": "scroll_progress",
    "compact": "fixed scroll-progress bar at page top",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3622,6 +3650,7 @@
    "type": "live_clock",
    "compact": "live ticking clock widget",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3630,6 +3659,7 @@
    "type": "decision_tree",
    "compact": "interactive collapsible decision tree",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3638,6 +3668,7 @@
    "type": "step_reveal_sequence",
    "compact": "tabbed step-by-step sequence",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3654,6 +3685,7 @@
    "type": "tooltip_glossary",
    "compact": "glossary with hover tooltips",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3662,6 +3694,7 @@
    "type": "focus_lens",
    "compact": "spotlight focus lens on blurred background",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3678,6 +3711,7 @@
    "type": "stagger_list",
    "compact": "stagger-animated list of items",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3686,6 +3720,7 @@
    "type": "liquid_button",
    "compact": "liquid morphing hover button",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3694,6 +3729,7 @@
    "type": "highlight_sweep",
    "compact": "animated highlight sweep text",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3702,6 +3738,7 @@
    "type": "progress_reveal",
    "compact": "scroll-triggered animated progress bar",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3710,6 +3747,7 @@
    "type": "big_reveal",
    "compact": "spring-animation big number or word reveal",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3718,6 +3756,7 @@
    "type": "kinetic_headline",
    "compact": "word-by-word kinetic headline animation",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3726,6 +3765,7 @@
    "type": "text_reveal_mask",
    "compact": "clip-path text reveal mask animation",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3734,6 +3774,7 @@
    "type": "split_reveal",
    "compact": "split-panel reveal animation",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3742,6 +3783,7 @@
    "type": "mesh_gradient",
    "compact": "dark card with radial mesh gradient background",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3750,6 +3792,7 @@
    "type": "stripe_background",
    "compact": "animated diagonal stripe background card",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3774,6 +3817,7 @@
    "type": "orbit_diagram",
    "compact": "animated orbit diagram with satellite nodes",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3782,6 +3826,7 @@
    "type": "noise_card",
    "compact": "dark card with film-grain noise texture",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3790,6 +3835,7 @@
    "type": "comparison_morph",
    "compact": "draggable before/after comparison slider",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3814,6 +3860,7 @@
    "type": "globe_3d",
    "compact": "interactive spinning 3-D globe (wire or earth)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3870,6 +3917,7 @@
    "type": "surface_unlocked",
    "compact": "achievement-style surface unlocked notification",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3886,6 +3934,7 @@
    "type": "url_anatomy",
    "compact": "annotated URL anatomy diagram",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3907,6 +3956,7 @@
    "type": "take_away_card",
    "compact": "bold screenshot-ready insight card",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3915,6 +3965,7 @@
    "type": "next_step_strip",
    "compact": "horizontal numbered next-steps strip",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3931,6 +3982,7 @@
    "type": "atom_anatomy",
    "compact": "rendered atom + raw schema side-by-side anatomy view",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3939,6 +3991,7 @@
    "type": "renderer_stats",
    "compact": "stat grid for renderer capability metrics",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3947,6 +4000,7 @@
    "type": "prompt_to_schema",
    "compact": "three-panel prompt → schema → output flow",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]
@@ -3987,6 +4041,7 @@
    "type": "surface_map",
    "compact": "A2UI surface diagram (schema → surfaces)",
    "surfaces": [
+    "web",
     "google-apps-script-web",
     "mcp-apps"
    ]