bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/bin/bitboss-ui.mjs

@@ -0,0 +1,710 @@
+#!/usr/bin/env node
+/**
+ * bitboss-ui CLI — AI-affordance utilities for consumer projects.
+ *
+ * Commands:
+ *   ai-init   Inject bitboss-ui knowledge-base pointers into the current
+ *             project so coding agents discover and follow the library's
+ *             agent contract — harness-agnostic, not Claude-only. Writes:
+ *             - AGENTS.md fragment (Cursor, Codex, many others)
+ *             - .cursor/rules/bitboss-ui.mdc (Cursor)
+ *             - .github/copilot-instructions.md fragment (GitHub Copilot)
+ *             - .claude/skills/bitboss-ui/SKILL.md (Claude Code)
+ *             - .windsurf/rules/bitboss-ui.md (Windsurf)
+ *             Accepts an optional --mcp flag (combinable with --update) to also
+ *             register the `bitboss-ui mcp` server in .mcp.json.
+ *   locale    Generate a custom locale blueprint (.locale.ts)
+ *   check     Validate Bb* markup in .vue/.md files against the installed
+ *             components.json manifest (unknown props, removed props, bad
+ *             v-models). Exits 1 on findings; supports --json output.
+ *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
+ *             (search_components, get_component, list_recipes, get_recipe,
+ *             validate) to MCP-capable agent harnesses.
+ *
+ * Plain ESM JavaScript on purpose: shipped as-is in the package, no build.
+ */
+
+import {
+	existsSync,
+	globSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { ensureMcpConfigs } from '../scripts/lib/mcp-config.mjs';
+import {
+	loadManifest,
+	validateMarkdown,
+	validateVueSnippet,
+} from '../scripts/lib/validate-bb-markup.mjs';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const KNOWLEDGE_BASE = 'node_modules/bitboss-ui/dist/ai';
+const ROUTER = `${KNOWLEDGE_BASE}/guides/ai-router.md`;
+const CONTRACT = `${KNOWLEDGE_BASE}/guides/agent-contract.md`;
+
+const START_MARKER = '<!-- bitboss-ui:ai:start -->';
+const END_MARKER = '<!-- bitboss-ui:ai:end -->';
+
+function packageVersion() {
+	try {
+		const pkg = JSON.parse(
+			readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')
+		);
+		return pkg.version ?? 'unknown';
+	} catch {
+		return 'unknown';
+	}
+}
+
+/** Shared rules body used by every harness (paths relative to project root). */
+function coreRules(version) {
+	return `This project uses \`bitboss-ui\` (v${version}). Before writing any UI that uses it:
+
+1. **Start at the AI Router**: \`${ROUTER}\` — which file to open next (do not dump the full catalogue into context).
+2. **Obey the agent contract**: \`${CONTRACT}\`.
+3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` is consumer API; most other \`BbBase*\` form primitives are not.)
+4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or validate against \`${KNOWLEDGE_BASE}/components.json\`.
+5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
+6. **Item-driven components**: declarative \`items\` / \`item-text\` / \`item-value\`, \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
+7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).
+8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\` — \`--bb-*\` tokens only; one primary action per view region.
+9. **Variants are yours to add**: the shipped \`variant\` names are a floor, not a ceiling. When the design needs a colour the library doesn't ship (soft status badges, a brand button tone), **register the name** in the build plugin's \`badgeVariants\`/\`buttonVariants\`/\`alertVariants\`/… and **style \`.bb-badge--<name>\`** (etc.) in a project stylesheet loaded after \`bitboss-ui/styles.css\`. Do both halves — a registered name with no CSS ships an unstyled pill, and CSS with no registration fails \`vue-tsc\`. Never write an unregistered name, and never downgrade the design to a neutral shipped variant to avoid registering. Canonical palette + snippet: \`${KNOWLEDGE_BASE}/guides/design-language.md\` § Getting soft semantic badges.
+10. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review.
+
+After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\``;
+}
+
+function agentsFragment(version) {
+	return `${START_MARKER}
+## bitboss-ui (v${version})
+
+${coreRules(version)}
+${END_MARKER}`;
+}
+
+function skillContent(version) {
+	return `---
+name: bitboss-ui
+description: Use when writing, reviewing, or debugging Vue code that uses the bitboss-ui component library (Bb* components, useToast/useConfirm composables) — provides typed component contracts, agent rules, and usage playbooks.
+---
+
+# bitboss-ui knowledge base (v${version})
+
+All paths are relative to the project root.
+
+## Before writing any bitboss-ui code
+
+${coreRules(version)}
+
+## Deeper material
+
+- Playbooks and setup: \`${KNOWLEDGE_BASE}/guides/\`
+- Composables: \`${KNOWLEDGE_BASE}/composables/\`
+- Full index (last resort): \`${KNOWLEDGE_BASE}/index.md\`
+- Implementation source (rarely needed): \`${KNOWLEDGE_BASE}/source/<ComponentName>.md\`
+`;
+}
+
+function cursorRuleContent(version) {
+	return `---
+description: bitboss-ui Vue component library — read AI router before generating Bb* usage
+globs: **/*.{vue,ts,tsx,js,jsx}
+alwaysApply: false
+---
+
+# bitboss-ui (v${version})
+
+${coreRules(version)}
+`;
+}
+
+function windsurfRuleContent(version) {
+	return `# bitboss-ui (v${version})
+
+${coreRules(version)}
+`;
+}
+
+function upsertMarkedFile(filePath, fragment, { createHeader } = {}) {
+	const existed = existsSync(filePath);
+
+	if (!existed) {
+		mkdirSync(dirname(filePath), { recursive: true });
+		const header = createHeader ? `${createHeader}\n\n` : '';
+		writeFileSync(filePath, `${header}${fragment}\n`, 'utf-8');
+		return { path: filePath, action: 'created' };
+	}
+
+	const current = readFileSync(filePath, 'utf-8');
+	const startIndex = current.indexOf(START_MARKER);
+	const endIndex = current.indexOf(END_MARKER);
+
+	if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+		const updated =
+			current.slice(0, startIndex) +
+			fragment +
+			current.slice(endIndex + END_MARKER.length);
+		writeFileSync(filePath, updated, 'utf-8');
+		return { path: filePath, action: 'updated' };
+	}
+
+	writeFileSync(filePath, `${current.trimEnd()}\n\n${fragment}\n`, 'utf-8');
+	return { path: filePath, action: 'appended' };
+}
+
+function writeWholeFile(filePath, content) {
+	const existed = existsSync(filePath);
+	mkdirSync(dirname(filePath), { recursive: true });
+	writeFileSync(filePath, content, 'utf-8');
+	return { path: filePath, action: existed ? 'updated' : 'created' };
+}
+
+function tryWrite(label, fn) {
+	try {
+		return fn();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`[bitboss-ui] skipped ${label}: ${message}`);
+		return { path: label, action: 'skipped' };
+	}
+}
+
+function aiInit({ mcp = false } = {}) {
+	const projectRoot = process.cwd();
+	const version = packageVersion();
+
+	if (!existsSync(join(projectRoot, 'package.json'))) {
+		console.error(
+			'[bitboss-ui] No package.json found in the current directory — run ai-init from your project root.'
+		);
+		process.exit(1);
+	}
+
+	const results = [
+		tryWrite('AGENTS.md', () =>
+			upsertMarkedFile(
+				join(projectRoot, 'AGENTS.md'),
+				agentsFragment(version),
+				{
+					createHeader: '# Agent Instructions',
+				}
+			)
+		),
+		tryWrite('.cursor/rules/bitboss-ui.mdc', () =>
+			writeWholeFile(
+				join(projectRoot, '.cursor', 'rules', 'bitboss-ui.mdc'),
+				cursorRuleContent(version)
+			)
+		),
+		tryWrite('.github/copilot-instructions.md', () =>
+			upsertMarkedFile(
+				join(projectRoot, '.github', 'copilot-instructions.md'),
+				agentsFragment(version),
+				{ createHeader: '# Copilot instructions' }
+			)
+		),
+		tryWrite('.claude/skills/bitboss-ui/SKILL.md', () =>
+			writeWholeFile(
+				join(projectRoot, '.claude', 'skills', 'bitboss-ui', 'SKILL.md'),
+				skillContent(version)
+			)
+		),
+		tryWrite('.windsurf/rules/bitboss-ui.md', () =>
+			writeWholeFile(
+				join(projectRoot, '.windsurf', 'rules', 'bitboss-ui.md'),
+				windsurfRuleContent(version)
+			)
+		),
+	];
+
+	if (mcp) {
+		// Explicit command → register every harness, including Windsurf's global
+		// (home-dir) config.
+		for (const result of ensureMcpConfigs(projectRoot, {
+			includeWindsurf: true,
+		})) {
+			const suffix = result.reason ? ` (${result.reason})` : '';
+			results.push({
+				path: `${result.path} [${result.label}]${suffix}`,
+				action: result.action,
+			});
+		}
+	}
+
+	console.log(`[bitboss-ui] ai-init complete (library v${version})`);
+	for (const result of results) {
+		console.log(`  - ${result.action}: ${result.path}`);
+	}
+	console.log(
+		'\nHarness-agnostic kickstart: AGENTS.md + Cursor / Copilot / Claude / Windsurf pointers.'
+	);
+	if (mcp) {
+		console.log(
+			'MCP: registered the bitboss-ui server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium global) — restart your harness to pick it up.'
+		);
+	} else {
+		console.log(
+			'Tip: `npx bitboss-ui ai-init --mcp` also registers the MCP server across Claude Code / Cursor / VS Code / Windsurf so agents can query the knowledge base instead of reading files.'
+		);
+	}
+	console.log('Re-run after upgrading bitboss-ui to refresh the pointers.');
+	console.log(
+		'Tip: `npx bitboss-ui ai-init --update` is the same command (idempotent).'
+	);
+
+	if (results.some((r) => r.action === 'skipped')) {
+		process.exitCode = 1;
+	}
+}
+
+/**
+ * Serialize the blueprint dictionary as a readable TS object literal
+ * (single-quoted, tab-indented, matching the library's own locale files).
+ */
+function localeObjectLiteral(dictionary) {
+	const quote = (s) =>
+		`'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+	const sections = Object.entries(dictionary)
+		.map(([section, entries]) => {
+			const lines = Object.entries(entries)
+				.map(([key, value]) => `\t\t${key}: ${quote(value)},`)
+				.join('\n');
+			return `\t${section}: {\n${lines}\n\t},`;
+		})
+		.join('\n');
+	return `{\n${sections}\n}`;
+}
+
+function localeBlueprint(key) {
+	const projectRoot = process.cwd();
+
+	if (!key) {
+		console.error(
+			'[bitboss-ui] Usage: npx bitboss-ui locale <key>   (e.g. `npx bitboss-ui locale nl`)'
+		);
+		process.exit(1);
+	}
+	// Keys double as dayjs module names (`dayjs/locale/<key>`) — keep them tame.
+	if (!/^[a-z0-9-]+$/.test(key)) {
+		console.error(
+			`[bitboss-ui] Invalid locale key '${key}' — use lowercase letters, digits and dashes (it doubles as the dayjs locale name, e.g. 'nl', 'ja', 'zh-cn').`
+		);
+		process.exit(1);
+	}
+
+	const blueprintPath = join(PACKAGE_ROOT, 'dist', 'locale-blueprint.json');
+	if (!existsSync(blueprintPath)) {
+		console.error(
+			'[bitboss-ui] dist/locale-blueprint.json not found in the installed package — reinstall bitboss-ui (or run `npm run build` when working in the library repo).'
+		);
+		process.exit(1);
+	}
+	const { builtins, template } = JSON.parse(
+		readFileSync(blueprintPath, 'utf-8')
+	);
+
+	if (builtins.includes(key)) {
+		console.error(
+			`[bitboss-ui] '${key}' is a built-in locale — built-ins cannot be overridden; the \`additionalLocales\` option only adds new ones. Just set \`locale: '${key}'\`.`
+		);
+		process.exit(1);
+	}
+
+	const outPath = join(projectRoot, `${key}.locale.ts`);
+	if (existsSync(outPath)) {
+		console.error(
+			`[bitboss-ui] ${key}.locale.ts already exists — delete it first if you want a fresh blueprint.`
+		);
+		process.exit(1);
+	}
+
+	// Same check the vite plugin performs at build time — surface it here too,
+	// while the consumer is still choosing the key.
+	let dayjsHint = `Calendar (dayjs) locale '${key}' found — calendars will follow automatically.`;
+	try {
+		// Consumer's own resolution first; fall back to the installed package's
+		// (dayjs is a bitboss-ui dependency, so it's always reachable from here).
+		try {
+			createRequire(join(projectRoot, 'package.json')).resolve(
+				`dayjs/locale/${key}.js`
+			);
+		} catch {
+			createRequire(join(PACKAGE_ROOT, 'package.json')).resolve(
+				`dayjs/locale/${key}.js`
+			);
+		}
+	} catch {
+		dayjsHint = `⚠ dayjs ships no locale named '${key}' — calendars will fall back to English (the vite plugin repeats this warning at build time). If a nearby dayjs name exists (e.g. 'zh-cn', 'pt-br'), prefer it as your key: https://github.com/iamkun/dayjs/tree/dev/src/locale`;
+	}
+
+	writeFileSync(
+		outPath,
+		`import type { LocaleOverrides } from 'bitboss-ui';
+
+/**
+ * bitboss-ui locale blueprint for '${key}' — generated by \`npx bitboss-ui locale ${key}\`.
+ *
+ * Translate the English strings below ({0}/{1} placeholders are interpolated
+ * arguments — keep them). Keys you delete fall back per-key to the library's
+ * default locale. Register it in your vite config:
+ *
+ *   import ${key.replace(/-/g, '_')} from './${key}.locale';
+ *   bitbossUi({ iconDir: '...', locale: '${key}', additionalLocales: { '${key}': ${key.replace(/-/g, '_')} } })
+ *
+ * The plugin regenerates \`locale-registry.d.ts\` on build start, making
+ * '${key}' a valid \`locale\` value everywhere (run dev once after adding it).
+ */
+export default ${localeObjectLiteral(template)} satisfies LocaleOverrides;
+`,
+		'utf-8'
+	);
+
+	console.log(`[bitboss-ui] Wrote ${key}.locale.ts (English blueprint).`);
+	console.log(`  ${dayjsHint}`);
+}
+
+// SNT-007: a bare-segment skip list of `node_modules`/`dist`/`.git` let a
+// default (no-glob) `check` sweep straight through a Laravel-style consumer's
+// `vendor/`, `storage/`, and `public/` trees — hundreds of vendored
+// `README.md`s outnumbering the app's own `.vue`/`.md` files 20:1. These are
+// all directories no project authors `Bb*` markup into, so they're safe
+// blanket exclusions; framework build caches (`.nuxt`, `.output`) get the
+// same treatment.
+const CHECK_SKIP_DIRS = new Set([
+	'node_modules',
+	'dist',
+	'.git',
+	'vendor',
+	'storage',
+	'public',
+	'.output',
+	'.nuxt',
+]);
+// Composite (multi-segment) skips: too narrow to earn a bare-segment entry —
+// skipping all of `bootstrap/` would also hide a project's own
+// `bootstrap/*.md` — but `bootstrap/cache` specifically is Laravel's compiled
+// config/routes cache, never hand-authored.
+const CHECK_SKIP_SUBPATHS = ['bootstrap/cache'];
+const CHECK_EXTENSIONS = ['.vue', '.md'];
+
+/** True when a path segment (by itself) is a directory `check` never descends into. */
+function isSkippedSegment(name) {
+	return CHECK_SKIP_DIRS.has(name);
+}
+
+/** True when the relative path IS, or falls under, a skipped multi-segment subpath. */
+function isSkippedSubpath(relPath) {
+	const normalized = relPath.split(/[\\/]/).join('/');
+	return CHECK_SKIP_SUBPATHS.some(
+		(sub) => normalized === sub || normalized.startsWith(`${sub}/`)
+	);
+}
+
+/** True when any path segment (or composite subpath) is skipped. */
+function inSkippedDir(relPath) {
+	return (
+		relPath.split(/[\\/]/).some((segment) => isSkippedSegment(segment)) ||
+		isSkippedSubpath(relPath)
+	);
+}
+
+/**
+ * Every `.vue`/`.md` file under `dir`, excluding the skip list (see
+ * `CHECK_SKIP_DIRS`/`CHECK_SKIP_SUBPATHS`) at any depth. A hand-rolled
+ * recursive walk rather than `globSync` because glob's `**` never traverses
+ * dot-directories (and there is no `dot` option) — the sweep must keep
+ * matching files like `.github/copilot-instructions.md`. Pruning skipped
+ * directories BEFORE descending (rather than filtering after a flat
+ * `recursive: true` readdir) is what keeps a multi-thousand-file `vendor/`
+ * tree from being walked at all.
+ */
+function collectCheckFiles(dir, relBase = dir) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (isSkippedSegment(entry.name)) continue;
+			if (isSkippedSubpath(relative(relBase, full))) continue;
+			out.push(...collectCheckFiles(full, relBase));
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		if (!CHECK_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) continue;
+		out.push(full);
+	}
+	return out;
+}
+
+/**
+ * Resolve the file list for `check`: explicit globs/paths if given, otherwise
+ * every `.vue`/`.md` file under `cwd` (excluding `CHECK_SKIP_DIRS`/
+ * `CHECK_SKIP_SUBPATHS` — node_modules, dist, .git, vendor, storage, public,
+ * .output, .nuxt, bootstrap/cache). Literal paths resolve directly: a literal
+ * FILE is always included (even one that lives inside a skipped dir — asking
+ * for it by name is the widen-the-scan escape hatch), a literal DIRECTORY is
+ * swept recursively and only its descendants are checked against the skip
+ * list (so `check vendor/some-pkg` still works even though a bare sweep would
+ * never enter `vendor/` on its own). Glob patterns (`*`, `**`, `?`, `{a,b}`)
+ * go through `node:fs` globSync, restricted to `.vue`/`.md` outside the
+ * skipped dirs.
+ */
+function resolveCheckFiles(cwd, patterns) {
+	if (patterns.length === 0) return collectCheckFiles(cwd).sort();
+
+	const matched = new Set();
+	for (const pattern of patterns) {
+		if (!/[*?{}[\]]/.test(pattern)) {
+			const abs = isAbsolute(pattern) ? pattern : join(cwd, pattern);
+			if (existsSync(abs)) {
+				const stat = statSync(abs);
+				if (stat.isDirectory()) {
+					for (const file of collectCheckFiles(abs)) matched.add(file);
+				} else if (stat.isFile()) {
+					matched.add(abs);
+				}
+				continue;
+			}
+		}
+		const dirents = globSync(pattern, {
+			cwd,
+			withFileTypes: true,
+			// Pruning is a traversal shortcut; the inSkippedDir filter below is
+			// what guarantees skip-dir parity. `entry` is a Dirent when
+			// withFileTypes is set, but tolerate the string form too.
+			exclude: (entry) =>
+				CHECK_SKIP_DIRS.has(
+					typeof entry === 'string' ? entry.split('/').pop() : entry.name
+				),
+		});
+		for (const dirent of dirents) {
+			if (!dirent.isFile()) continue;
+			if (!CHECK_EXTENSIONS.some((ext) => dirent.name.endsWith(ext))) continue;
+			const joined = join(dirent.parentPath, dirent.name);
+			const full = isAbsolute(joined) ? joined : join(cwd, joined);
+			if (inSkippedDir(relative(cwd, full))) continue;
+			matched.add(full);
+		}
+	}
+
+	return [...matched].sort();
+}
+
+/**
+ * `4 .vue + 8 .md` — a plain file count on its own ("715 file(s)") reads as
+ * "715 files carefully checked" when SNT-007 showed it can just as easily be
+ * "701 vendored READMEs + 14 real files"; splitting by extension makes the
+ * number honest about what was actually covered. `.vue`/`.md` sort first
+ * (the extensions `check` targets by default); any other extension a literal
+ * path argument pulled in — see `resolveCheckFiles` — sorts after, A-Z.
+ */
+function summarizeFileCounts(files) {
+	const counts = new Map();
+	for (const file of files) {
+		const base = file.split(/[\\/]/).pop() ?? file;
+		const dot = base.lastIndexOf('.');
+		const ext = dot === -1 ? '(no extension)' : base.slice(dot);
+		counts.set(ext, (counts.get(ext) ?? 0) + 1);
+	}
+	const priority = ['.vue', '.md'];
+	const exts = [...counts.keys()].sort((a, b) => {
+		const pa = priority.indexOf(a);
+		const pb = priority.indexOf(b);
+		if (pa !== -1 || pb !== -1) {
+			return (
+				(pa === -1 ? priority.length : pa) - (pb === -1 ? priority.length : pb)
+			);
+		}
+		return a.localeCompare(b);
+	});
+	return exts.map((ext) => `${counts.get(ext)} ${ext}`).join(' + ');
+}
+
+/**
+ * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup in `.vue`
+ * and `.md` files against the installed components.json manifest.
+ */
+function checkCommand(globs, jsonMode) {
+	const projectRoot = process.cwd();
+
+	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
+	if (!existsSync(manifestPath)) {
+		console.error(
+			`[bitboss-ui] Manifest not found at ${manifestPath} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
+		);
+		process.exit(1);
+	}
+	const manifest = loadManifest(manifestPath);
+	const files = resolveCheckFiles(projectRoot, globs);
+
+	const findings = [];
+	for (const file of files) {
+		const relPath = relative(projectRoot, file);
+		const content = readFileSync(file, 'utf-8');
+		const { findings: fileFindings } = file.endsWith('.md')
+			? validateMarkdown(content, manifest)
+			: validateVueSnippet(content, manifest);
+		for (const finding of fileFindings) {
+			findings.push({ file: relPath, ...finding });
+		}
+	}
+
+	if (jsonMode) {
+		console.log(JSON.stringify({ findings }, null, 2));
+		if (findings.length > 0) process.exit(1);
+		return;
+	}
+
+	if (files.length === 0) {
+		console.log(
+			'[bitboss-ui] check: no .vue/.md files matched — nothing to do.'
+		);
+		return;
+	}
+
+	if (findings.length === 0) {
+		console.log(
+			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models.`
+		);
+		return;
+	}
+
+	const fileCount = new Set(findings.map((f) => f.file)).size;
+	console.error(
+		`[bitboss-ui] check FAILED — ${findings.length} finding(s) across ${fileCount} file(s):`
+	);
+	let lastFile = null;
+	for (const finding of findings) {
+		if (finding.file !== lastFile) {
+			console.error(`\n  ${finding.file}`);
+			lastFile = finding.file;
+		}
+		const where =
+			finding.fenceInfo != null
+				? `fence#${finding.fenceIndex}${finding.fenceInfo ? ` (${finding.fenceInfo})` : ''} `
+				: '';
+		console.error(
+			`    ✗ ${where ? `[${where.trim()}] ` : ''}${finding.message}`
+		);
+		if (finding.hint) console.error(`      hint: ${finding.hint}`);
+	}
+	console.error(
+		'\nFix the markup (or the component API) so it stays copy-safe for agents.'
+	);
+	process.exit(1);
+}
+
+function printHelp() {
+	console.log(`bitboss-ui CLI
+
+Usage:
+  npx bitboss-ui <command>
+
+Commands:
+  ai-init [--update] [--mcp]
+                      Inject AI-agent knowledge-base pointers into the current
+                      project (AGENTS.md, Cursor rules, Copilot instructions,
+                      Claude skill, Windsurf rules). Idempotent — safe to re-run
+                      after upgrades. \`--mcp\` also registers the bitboss-ui MCP
+                      server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json),
+                      VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
+                      global) — merges, never overwrites other servers.
+  check [glob…] [--json]
+                      Validate \`Bb*\` markup in .vue/.md files against the
+                      installed components.json manifest (unknown/removed props,
+                      bad v-models). Defaults to every .vue/.md file under the
+                      current directory (node_modules, dist, .git, vendor,
+                      storage, public, .output, .nuxt, bootstrap/cache
+                      excluded — pass an explicit glob/path to widen the scan).
+                      Exits 1 on findings; \`--json\` prints \`{ findings: [...] }\`.
+  mcp                 Start a stdio MCP server exposing the dist/ai knowledge
+                      base (search_components, get_component, list_recipes,
+                      get_recipe, validate) to MCP-capable agent harnesses.
+  locale <key>        Generate <key>.locale.ts at the project root — an English
+                      blueprint dictionary to translate and pass to the plugin's
+                      \`additionalLocales\` option (additions only; built-ins are refused).
+  help                Show this help.
+`);
+}
+
+/**
+ * Strict `node:util` parseArgs wrapper: unknown flags/positionals become an
+ * actionable `[bitboss-ui] <command>: …` error + help + exit 1.
+ */
+function parseCommandArgs(
+	command,
+	args,
+	options,
+	{ allowPositionals = false } = {}
+) {
+	try {
+		return parseArgs({ args, options, allowPositionals, strict: true });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`[bitboss-ui] ${command}: ${message}`);
+		printHelp();
+		process.exit(1);
+	}
+}
+
+const [command, ...commandArgs] = process.argv.slice(2);
+
+switch (command) {
+	case 'ai-init': {
+		const { values } = parseCommandArgs(command, commandArgs, {
+			update: { type: 'boolean' },
+			mcp: { type: 'boolean' },
+		});
+		aiInit({ mcp: values.mcp ?? false });
+		break;
+	}
+	case 'check': {
+		const { values, positionals } = parseCommandArgs(
+			command,
+			commandArgs,
+			{ json: { type: 'boolean' } },
+			{ allowPositionals: true }
+		);
+		checkCommand(positionals, values.json ?? false);
+		break;
+	}
+	case 'mcp': {
+		const { main } = await import('./bitboss-ui-mcp.mjs');
+		await main();
+		break;
+	}
+	case 'locale': {
+		const { positionals } = parseCommandArgs(
+			command,
+			commandArgs,
+			{},
+			{
+				allowPositionals: true,
+			}
+		);
+		localeBlueprint(positionals[0]);
+		break;
+	}
+	case 'help':
+	case '--help':
+	case '-h':
+	case undefined:
+		printHelp();
+		break;
+	default:
+		console.error(`[bitboss-ui] Unknown command: ${command}`);
+		printHelp();
+		process.exit(1);
+}