beehaven 0.8.16

package/dist/commands/design.js

@@ -0,0 +1,617 @@
+/**
+ * `beehaven brand` and `beehaven component` — the workspace design system from a terminal.
+ *
+ * ⚠⚠ WHY VERBS WHEN `call brand` ALREADY WORKED. Same argument `sheet.ts` and `ticket.ts` make:
+ * the brand and the component library are first-class workspace artifacts, and an artifact whose
+ * only door is `beehaven call <action> '{…}'` is one nobody thinks to look for. These verbs are
+ * thin — every one maps to ONE action — and they earn their place by making the common traps
+ * untypeable:
+ *
+ *   · `brand set <brand> color.accent '#FF5500'` builds the ROLE-MERGE patch `{ colors: { accent } }`.
+ *     Sending `colors` as an array REPLACES the whole palette — the easiest way to lose ten colours
+ *     while changing one. The verb never sends the array form.
+ *   · `component place` needs a composition; it is taken as `--composition`, and `--x/--y` are
+ *     numbers, not strings the worker has to coerce.
+ *   · `component render -o button.svg` writes the file — a preview is something you look at.
+ *
+ * ⚠ `agentRpc`, NEVER bare `rpcOnce` — a bare call runs as the ACCOUNT OWNER rather than as the
+ * signed-in agent, skipping `agent-invoke`, the per-agent capability gate and the activity log.
+ * A refusal here is the gate working: it names the permission (`agent-denied-<verb>`).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { agentRpc as rpcOnce } from './workspace.js';
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+function getTimeout(values) {
+    const t = Number(values?.timeout);
+    return Number.isFinite(t) && t > 0 ? t : 30_000;
+}
+/** ⚠ `rpcOnce` returns `{ error }` as a VALUE and never throws — see `rpcFailure` in workspace.ts. */
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return null;
+    if (typeof res.error === 'string' && res.error)
+        return res.error + (res.code ? c.dim(`  (${res.code})`) : '');
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+function die(msg, hint) {
+    console.error(`  ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+/** `--patch '{…}'` or `--patch @file.json`. */
+function readJson(raw, flag) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const s = String(raw);
+    const text = s.startsWith('@') ? readFileSync(s.slice(1), 'utf8') : s;
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        die(`${flag} is not valid JSON: ${e?.message ?? e}`);
+    }
+}
+function num(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+const swatch = (hex) => {
+    const m = /^#?([0-9a-f]{6})/i.exec(hex);
+    if (!m)
+        return '  ';
+    const r = parseInt(m[1].slice(0, 2), 16), g = parseInt(m[1].slice(2, 4), 16), b = parseInt(m[1].slice(4, 6), 16);
+    return `\x1b[48;2;${r};${g};${b}m  \x1b[0m`;
+};
+// ── brand ──────────────────────────────────────────────────────────────────────────────────
+/**
+ * `brand set <brand> <field> <value>` → a patch. ⚠ Every colour goes through the role MAP, never the
+ * array, so one colour changes and the other roles are untouched.
+ */
+export function brandFieldPatch(field, value) {
+    const f = field.trim();
+    let m;
+    if ((m = /^(?:color|colour|colors)\.([a-z0-9-]+)$/i.exec(f)))
+        return { colors: { [m[1].toLowerCase()]: value === 'none' ? null : value } };
+    if ((m = /^(?:dark|colorsDark)\.([a-z0-9-]+)$/i.exec(f)))
+        return { colorsDark: { [m[1].toLowerCase()]: value === 'none' ? null : value } };
+    if ((m = /^(?:type|font|typography)\.(display|heading|body|label|mono)(?:\.(family|weight|size|lineHeight|letterSpacing))?$/i.exec(f))) {
+        const role = m[1].toLowerCase(), prop = m[2];
+        if (!prop || prop === 'family')
+            return { typography: { [role]: value } };
+        const n = Number(value);
+        if (!Number.isFinite(n))
+            return `${f} needs a number`;
+        return { typography: { [role]: { [prop]: n } } };
+    }
+    if ((m = /^(?:shape\.)?(radius|spacing|borderWidth)$/i.exec(f))) {
+        const n = Number(value);
+        return Number.isFinite(n) ? { shape: { [m[1]]: n } } : `${f} needs a number`;
+    }
+    if (/^voice(\.summary)?$/i.test(f))
+        return { voice: { summary: value } };
+    if (/^voice\.tone$/i.test(f))
+        return { voice: { tone: value.split(',').map((s) => s.trim()).filter(Boolean) } };
+    if (/^voice\.dos$/i.test(f))
+        return { voice: { dos: value.split('|').map((s) => s.trim()).filter(Boolean) } };
+    if (/^voice\.donts$/i.test(f))
+        return { voice: { donts: value.split('|').map((s) => s.trim()).filter(Boolean) } };
+    if (/^(name|description|imagery)$/i.test(f))
+        return { [f.toLowerCase()]: value };
+    return `unknown field "${f}" — use color.<role>, dark.<role>, type.<role>[.weight|.size|.lineHeight|.letterSpacing], radius, spacing, borderWidth, voice, voice.tone, voice.dos, voice.donts, name, description, imagery`;
+}
+export async function cmdBrand(sub, rest, values) {
+    const t = getTimeout(values);
+    const json = (res) => console.log(JSON.stringify(res, null, 2));
+    if (sub === 'help' || sub === '--help') {
+        console.log(`
+  ${c.cyan('beehaven brand')} — the workspace brand (colours, type, logos, voice, shape)
+
+    brand [list]                       Every brand; the default is marked
+    brand show [<brand>]               One brand in full + its checks  (default brand when omitted)
+    brand tokens [<brand>]             Design tokens  (--format css|json · --mode dark · --composition <id>)
+    brand new "<name>"                 Create one  (--from <brand> duplicates)
+    brand set <brand> <field> <value>  Change ONE field, e.g. color.accent '#FF5500' · type.heading Fraunces
+    brand edit <brand> --patch <json>  Any patch  (--patch @file.json)
+    brand default <brand>              Make it the workspace default
+    brand bind <brand> --composition <id>   Design that canvas with this brand
+    brand board [<brand>]              Lay it out as an editable brand board  (--composition <id> · --name "<title>")
+    brand history <brand>              Versions, newest first
+    brand revert <brand> <version>     Restore a version (adds a new one)
+    brand rm <brand>                   Delete — recoverable
+    brand restore <brandId>            Bring a deleted brand back
+
+  ${c.dim('<brand> is an id or a name. Colour roles: primary, secondary, accent, neutral, background, surface,')}
+  ${c.dim('text, muted, success, warning, danger — or any custom name. `none` removes a role.')}
+  ${c.dim('Agents: `brand` / clearly_brand does the same with { op }. Edits are bounded by your permissions.')}
+`);
+        return;
+    }
+    if (!sub || sub === 'list' || sub === 'ls') {
+        const res = await rpcOnce('brand-list', {}, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        const rows = res?.brands ?? [];
+        if (!rows.length) {
+            console.log(`  No brand yet. ${c.dim('beehaven brand new "Acme"')}`);
+            return;
+        }
+        console.log('');
+        for (const b of rows) {
+            const sw = (b.colors ?? []).slice(0, 6).map((x) => swatch(String(x.hex))).join('');
+            console.log(`  ${sw}  ${c.bold(String(b.name))}${b.isDefault ? c.dim('  (default)') : ''}  ${c.dim(String(b.id))}`);
+        }
+        console.log('');
+        return;
+    }
+    if (sub === 'show' || sub === 'get') {
+        const ref = rest.join(' ').trim();
+        const res = await rpcOnce('brand-get', { ...(ref ? { id: ref } : {}), ...(values.composition ? { compositionId: String(values.composition) } : {}) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log('');
+        console.log(`  ${c.bold(String(res.name))}${res.isDefault ? c.dim('  (default)') : ''}  ${c.dim(`v${res.version} · ${res.id}`)}`);
+        if (res.description)
+            console.log(`  ${res.description}`);
+        console.log(`\n  ${c.dim('COLOUR')}`);
+        for (const x of res.colors ?? [])
+            console.log(`    ${swatch(String(x.hex))}  ${String(x.role).padEnd(12)} ${String(x.hex).padEnd(9)} ${c.dim(String(x.name ?? ''))}`);
+        if ((res.colorsDark ?? []).length)
+            console.log(`    ${c.dim(`dark: ${res.colorsDark.map((x) => `${x.role} ${x.hex}`).join(', ')}`)}`);
+        console.log(`\n  ${c.dim('TYPE')}`);
+        for (const r of ['display', 'heading', 'body', 'label', 'mono']) {
+            const s = res.typography?.[r];
+            if (!s)
+                continue;
+            console.log(`    ${r.padEnd(8)} ${s.family} ${s.weight} · ${s.size}px / ${s.lineHeight}`);
+        }
+        console.log(`\n  ${c.dim('SHAPE')}  radius ${res.shape?.radius}px · spacing ${res.shape?.spacing}px · stroke ${res.shape?.borderWidth}px`);
+        if ((res.logos ?? []).length) {
+            console.log(`\n  ${c.dim('LOGOS')}`);
+            for (const l of res.logos)
+                console.log(`    ${String(l.variant).padEnd(9)} ${l.url.length > 90 ? `${l.url.slice(0, 87)}…` : l.url}`);
+        }
+        if (res.voice?.summary || res.voice?.tone?.length) {
+            console.log(`\n  ${c.dim('VOICE')}  ${res.voice.summary ?? ''}`);
+            if (res.voice.tone?.length)
+                console.log(`    tone: ${res.voice.tone.join(', ')}`);
+        }
+        if ((res.audit ?? []).length) {
+            console.log(`\n  ${c.dim('CHECKS')}`);
+            for (const a of res.audit)
+                console.log(`    ${a.level === 'error' ? c.red('✗') : c.yellow('!')} ${a.message}`);
+        }
+        console.log('');
+        return;
+    }
+    if (sub === 'tokens' || sub === 'css') {
+        const ref = rest.join(' ').trim();
+        const res = await rpcOnce('brand-tokens', {
+            ...(ref ? { id: ref } : {}),
+            ...(values.mode ? { mode: String(values.mode) } : {}),
+            ...(values.composition ? { compositionId: String(values.composition) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        const out = sub === 'css' || values.format === 'css' ? res.css : JSON.stringify(res.tokens, null, 2);
+        if (values.output) {
+            writeFileSync(String(values.output), out);
+            console.log(`  Wrote ${values.output}`);
+            return;
+        }
+        process.stdout.write(out.endsWith('\n') ? out : `${out}\n`);
+        return;
+    }
+    if (sub === 'new' || sub === 'create') {
+        const name = (rest.join(' ').trim() || String(values.name ?? '')).trim();
+        if (!name)
+            die('a name is required', 'beehaven brand new "Harbor"');
+        const res = await rpcOnce('brand-create', { name, ...(values.from ? { fromBrandId: String(values.from) } : {}) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Created ${c.bold(name)}  ${c.dim(String(res.id))}`);
+        console.log(c.dim(`  Next: beehaven brand set "${name}" color.primary '#123456'`));
+        return;
+    }
+    if (sub === 'set') {
+        const [ref, field, ...valueParts] = rest;
+        const value = valueParts.join(' ');
+        if (!ref || !field || !valueParts.length)
+            die('usage: brand set <brand> <field> <value>', "beehaven brand set Harbor color.accent '#FF5500'");
+        const patch = brandFieldPatch(field, value);
+        if (typeof patch === 'string')
+            die(patch);
+        const res = await rpcOnce('brand-update', { id: ref, patch, summary: `CLI: ${field} = ${value}`.slice(0, 200) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  ${c.bold(String(res.brand?.name ?? ref))} ${field} → ${value}  ${c.dim(`v${res.version}`)}`);
+        return;
+    }
+    if (sub === 'edit' || sub === 'update') {
+        const ref = rest.join(' ').trim();
+        const patch = readJson(values.patch, '--patch');
+        if (!ref || !patch)
+            die('usage: brand edit <brand> --patch <json|@file>', `beehaven brand edit Harbor --patch '{"colors":{"accent":"#FF5500"}}'`);
+        const res = await rpcOnce('brand-update', { id: ref, patch }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Updated ${c.bold(String(res.brand?.name ?? ref))}: ${(res.changed ?? []).join(', ')}  ${c.dim(`v${res.version}`)}`);
+        return;
+    }
+    if (sub === 'default') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: brand default <brand>');
+        const res = await rpcOnce('brand-set-default', { id: ref }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  ${c.bold(String(res.brand?.name ?? ref))} is now the workspace default`);
+        return;
+    }
+    if (sub === 'bind') {
+        const ref = rest.join(' ').trim();
+        if (!ref || !values.composition)
+            die('usage: brand bind <brand> --composition <id>');
+        const res = await rpcOnce('brand', { op: 'set-active', id: ref, compositionId: String(values.composition) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Composition ${values.composition} now designs with ${ref}`);
+        return;
+    }
+    if (sub === 'board' || sub === 'compose') {
+        const ref = rest.join(' ').trim();
+        const res = await rpcOnce('brand-compose', {
+            ...(ref ? { id: ref } : {}),
+            ...(values.composition ? { compositionId: String(values.composition) } : {}),
+            ...(values.name ? { title: String(values.name) } : {}),
+            ...(values.project ? { projectId: String(values.project) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Brand board ${res.created ? 'created' : 'added'} — ${res.nodes} layers in ${c.cyan(String(res.compositionId))}`);
+        console.log(c.dim(`  Open it: beehaven open ${res.compositionId}`));
+        return;
+    }
+    if (sub === 'history' || sub === 'versions') {
+        const ref = rest.join(' ').trim();
+        const got = await rpcOnce('brand-get', ref ? { id: ref } : {}, t, values);
+        const f0 = failure(got);
+        if (f0)
+            die(f0);
+        const res = await rpcOnce('brand-version-list', { brandId: got.id }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log('');
+        for (const v of res.versions ?? [])
+            console.log(`  v${String(v.version).padEnd(4)} ${String(v.change_summary ?? '').padEnd(48).slice(0, 48)} ${c.dim(`${v.created_by ?? v.source} · ${new Date(v.created_at).toLocaleString()}`)}`);
+        console.log('');
+        return;
+    }
+    if (sub === 'revert') {
+        const [ref, ver] = rest;
+        const target = num(ver ?? values.rev);
+        if (!ref || target === undefined)
+            die('usage: brand revert <brand> <version>');
+        const got = await rpcOnce('brand-get', { id: ref }, t, values);
+        const f0 = failure(got);
+        if (f0)
+            die(f0);
+        const res = await rpcOnce('brand-revert', { brandId: got.id, targetVersion: target }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Reverted ${got.name} to v${target}  ${c.dim(`(now v${res.newCurrentVersion})`)}`);
+        return;
+    }
+    if (sub === 'rm' || sub === 'delete') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: brand rm <brand>');
+        const res = await rpcOnce('brand-delete', { id: ref }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Deleted.  ${c.dim(`Undo: beehaven brand restore ${res.id}`)}`);
+        return;
+    }
+    if (sub === 'restore') {
+        const id = rest[0];
+        if (!id)
+            die('usage: brand restore <brandId>');
+        const res = await rpcOnce('brand-restore', { brandId: id }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Restored ${c.bold(String(res.name))}`);
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven brand help');
+}
+// ── component ──────────────────────────────────────────────────────────────────────────────
+export async function cmdComponent(sub, rest, values) {
+    const t = getTimeout(values);
+    const json = (res) => console.log(JSON.stringify(res, null, 2));
+    if (sub === 'help' || sub === '--help') {
+        console.log(`
+  ${c.cyan('beehaven component')} — the workspace component library (brand-aware, reusable blocks)
+
+    component [list] [<query>]          Browse  (--category actions|inputs|display|navigation|feedback|layout|marketing|brand)
+    component show <component>          Props, variants, size, brand tokens it lacks
+    component render <component>        SVG preview  (-o file.svg · --variant V · --props <json> · --brand <brand>)
+    component place <component> --composition <id>   Put it on a canvas  (--x --y --parent <frame> --variant --props --brand)
+    component save --composition <id> <node>         Save a canvas node + its layers as a component  (--name --category)
+    component new --patch <spec.json>   Author one from a spec  (--patch @file.json)
+    component edit <component> --patch <json>        Change fields: name, description, category, status, tags, props, variants, nodes…
+    component dup <component>           Duplicate  (--name "<new name>")
+    component history <component>       Versions
+    component revert <component> <version>
+    component rm <component>            Delete — recoverable
+    component restore <component>
+
+  ${c.dim('<component> is an id, a slug (button, pricing-card) or a name.')}
+  ${c.dim('Colours and faces in a component are brand tokens ({brand.color.primary}) — place and render use the')}
+  ${c.dim("composition's brand (or --brand). Agents: `component` / clearly_component does the same with { op }.")}
+`);
+        return;
+    }
+    if (!sub || sub === 'list' || sub === 'ls' || sub === 'search') {
+        const query = rest.join(' ').trim();
+        const res = await rpcOnce('component-list', { ...(query ? { query } : {}), ...(values.category ? { category: String(values.category) } : {}) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        const rows = res?.components ?? [];
+        if (!rows.length) {
+            console.log(query ? `  Nothing matches "${query}".` : '  The library is empty.');
+            return;
+        }
+        console.log('');
+        let cat = '';
+        for (const r of [...rows].sort((a, b) => String(a.category).localeCompare(String(b.category)) || String(a.name).localeCompare(String(b.name)))) {
+            if (r.category !== cat) {
+                cat = r.category;
+                console.log(`  ${c.dim(String(cat).toUpperCase())}`);
+            }
+            const variants = (r.variants ?? []).length > 1 ? c.dim(` · ${r.variants.join(' / ')}`) : '';
+            console.log(`    ${c.cyan(String(r.slug).padEnd(18))} ${String(r.name)}${variants}`);
+        }
+        if (res.migrated)
+            console.log(c.dim(`\n  ${res.migrated} older canvas component(s) were migrated into the library.`));
+        console.log('');
+        return;
+    }
+    if (sub === 'show' || sub === 'get') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: component show <component>');
+        const res = await rpcOnce('component-get', { id: ref, ...(values.brand ? { brandId: String(values.brand) } : {}) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        const s = res.component;
+        console.log('');
+        console.log(`  ${c.bold(s.name)}  ${c.dim(`${s.slug} · ${s.category} · ${s.width}×${s.height} · v${s.version} · ${s.source}`)}`);
+        if (s.description)
+            console.log(`  ${s.description}`);
+        if (s.props?.length) {
+            console.log(`\n  ${c.dim('PROPS')}`);
+            for (const p of s.props)
+                console.log(`    ${String(p.name).padEnd(14)} ${String(p.type === 'enum' ? (p.options ?? []).join('|') : p.type).padEnd(10)} ${c.dim(`= ${JSON.stringify(p.default)}`)}`);
+        }
+        if (s.variants?.length)
+            console.log(`\n  ${c.dim('VARIANTS')}  ${s.variants.map((v) => v.name).join(' · ')}`);
+        console.log(`\n  ${c.dim('LAYERS')}    ${s.nodes.length}   ${c.dim(`rendered in ${res.render?.brandName ? `"${res.render.brandName}"` : 'fallback values'}`)}`);
+        if (res.render?.missingTokens?.length)
+            console.log(`  ${c.yellow('!')} brand lacks: ${res.render.missingTokens.join(', ')}`);
+        console.log(c.dim(`\n  Place it: beehaven component place ${s.slug} --composition <id> --x 100 --y 100`));
+        console.log('');
+        return;
+    }
+    if (sub === 'render' || sub === 'preview') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: component render <component> [-o file.svg]');
+        const res = await rpcOnce('component-render', {
+            id: ref,
+            ...(values.variant ? { variant: String(values.variant) } : {}),
+            ...(values.props ? { props: readJson(values.props, '--props') } : {}),
+            ...(values.brand ? { brandId: String(values.brand) } : {}),
+            ...(values.format === 'nodes' ? { format: 'nodes' } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json || values.format === 'nodes')
+            return json(res);
+        if (values.output) {
+            writeFileSync(String(values.output), res.svg);
+            console.log(`  Wrote ${values.output}  ${c.dim(`(${res.variant || 'default'} variant)`)}`);
+            return;
+        }
+        process.stdout.write(`${res.svg}\n`);
+        return;
+    }
+    if (sub === 'place' || sub === 'instantiate' || sub === 'add') {
+        const ref = rest.join(' ').trim();
+        if (!ref || !values.composition)
+            die('usage: component place <component> --composition <id> [--x N --y N --parent <frame> --variant V]', 'beehaven component place button --composition 7f3a… --x 120 --y 80 --variant Secondary');
+        const res = await rpcOnce('component-instantiate', {
+            id: ref, compositionId: String(values.composition),
+            ...(num(values.x) !== undefined ? { x: num(values.x) } : {}),
+            ...(num(values.y) !== undefined ? { y: num(values.y) } : {}),
+            ...(values.parent ? { parentId: String(values.parent) } : {}),
+            ...(values.variant ? { variant: String(values.variant) } : {}),
+            ...(values.props ? { props: readJson(values.props, '--props') } : {}),
+            ...(values.brand ? { brandId: String(values.brand) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Placed ${c.bold(ref)}${res.variant ? ` · ${res.variant}` : ''} — ${res.ids?.length ?? 0} layers, root ${c.cyan(String(res.rootId))}`);
+        if (res.missingTokens?.length)
+            console.log(`  ${c.yellow('!')} brand lacks: ${res.missingTokens.join(', ')} — fallbacks used`);
+        return;
+    }
+    if (sub === 'save') {
+        const node = rest.join(' ').trim();
+        if (!values.composition || !node)
+            die('usage: component save --composition <id> <node id or name> [--name "…"] [--category …]', 'beehaven component save --composition 7f3a… "Hero frame" --name "Marketing hero"');
+        const res = await rpcOnce('component-create', {
+            fromCompositionId: String(values.composition), nodeId: node,
+            ...(values.name ? { name: String(values.name) } : {}),
+            ...(values.category ? { category: String(values.category) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Saved ${c.bold(String(res.component?.name ?? node))} as ${c.cyan(String(res.slug))} — brand colours and faces are linked to tokens`);
+        return;
+    }
+    if (sub === 'new' || sub === 'create') {
+        const spec = readJson(values.patch, '--patch');
+        if (!spec)
+            die('usage: component new --patch <spec.json|@file>', 'beehaven component new --patch @chip.json   (see: beehaven explain component-create)');
+        const res = await rpcOnce('component-create', { ...spec, ...(values.name ? { name: String(values.name) } : {}) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Created ${c.bold(String(res.component?.name))} ${c.dim(String(res.slug))}`);
+        return;
+    }
+    if (sub === 'edit' || sub === 'update') {
+        const ref = rest.join(' ').trim();
+        const patch = readJson(values.patch, '--patch');
+        if (!ref || !patch)
+            die('usage: component edit <component> --patch <json|@file>');
+        const res = await rpcOnce('component-update', { id: ref, patch }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Updated ${c.bold(String(res.component?.name ?? ref))}: ${(res.changed ?? []).join(', ')}  ${c.dim(`v${res.version}`)}`);
+        return;
+    }
+    if (sub === 'dup' || sub === 'duplicate') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: component dup <component> [--name "…"]');
+        const res = await rpcOnce('component-create', { fromComponentId: ref, ...(values.name ? { name: String(values.name) } : {}) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Duplicated as ${c.cyan(String(res.slug))}`);
+        return;
+    }
+    if (sub === 'history' || sub === 'versions') {
+        const ref = rest.join(' ').trim();
+        const res = await rpcOnce('component-versions', { id: ref }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        for (const v of res.versions ?? [])
+            console.log(`  v${String(v.version).padEnd(4)} ${String(v.change_summary ?? '')}  ${c.dim(String(v.created_by ?? ''))}`);
+        return;
+    }
+    if (sub === 'revert') {
+        const [ref, ver] = rest;
+        const version = num(ver ?? values.rev);
+        if (!ref || version === undefined)
+            die('usage: component revert <component> <version>');
+        const res = await rpcOnce('component-revert', { id: ref, version }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Reverted to v${version}  ${c.dim(`(now v${res.version})`)}`);
+        return;
+    }
+    if (sub === 'rm' || sub === 'delete') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: component rm <component>');
+        const res = await rpcOnce('component-delete', { id: ref }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  Deleted.  ${c.dim(`Undo: beehaven component restore ${res.id}`)}`);
+        return;
+    }
+    if (sub === 'restore') {
+        const ref = rest.join(' ').trim();
+        if (!ref)
+            die('usage: component restore <component>');
+        const res = await rpcOnce('component-restore', { id: ref }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json)
+            return json(res);
+        console.log(`  ${res.restored ? 'Restored' : 'Not deleted — nothing to do'}`);
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven component help');
+}