@collectui/bdui 0.1.2

package/bin/bdui.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// BoardUI CLI 入口 — 极简 commander 复刻(零依赖)
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2)).catch((error) => {
+	console.error(`✗ ${error.message}`);
+	process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@collectui/bdui",
+  "version": "0.1.2",
+  "description": "Add BoardUI components to your project.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "bdui": "bin/bdui.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ora": "^8.1.1",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
+    "zod": "^4.5.1"
+  }
+}

package/src/add.js

@@ -0,0 +1,122 @@
+// `bdui add` 复刻 — 递归解析 registryDependencies,落盘文件,装依赖
+
+import { spawn } from "child_process";
+import ora from "ora";
+import c from "./color.js";
+import { detectProject, installCommand } from "./project.js";
+import { fetchIndex, fetchItem } from "./registry.js";
+import { writeItemFiles } from "./write.js";
+
+export async function installPackages(pm, packages, cwd) {
+	if (!packages.length) return;
+	const [command, args] = installCommand(pm, packages);
+	await new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd,
+			stdio: "ignore",
+			shell: process.platform === "win32",
+		});
+		child.on("error", reject);
+		child.on("close", (code) =>
+			code === 0
+				? resolve()
+				: reject(
+						new Error(`${command} ${args.join(" ")} exited with code ${code}`)
+					)
+		);
+	});
+}
+
+export async function cmdAdd(names, flags) {
+	const project = detectProject(flags.dir ?? process.cwd());
+	if (!project.pkg)
+		throw new Error(
+			"No package.json found — run this inside your app project."
+		);
+
+	const index = await fetchIndex(true);
+	const wanted = flags.all ? index.items.map((i) => i.name) : names;
+
+	if (!wanted.length) {
+		console.log(
+			"No components selected. Run `bdui list` to see what's available."
+		);
+		return;
+	}
+
+	// 递归收集:name → item(公共 + pro),依赖闭包先装;pro 用 --key
+	const key = flags.key;
+	const resolved = new Map();
+	const missing = [];
+	async function collect(name) {
+		if (resolved.has(name)) return;
+		const meta = index.items.find((i) => i.name === name);
+		if (!meta) {
+			missing.push(name);
+			return;
+		}
+		const item = await fetchItem(name, key);
+		resolved.set(name, item);
+		for (const dep of item.registryDependencies ?? []) {
+			if (!resolved.has(dep)) await collect(dep);
+		}
+	}
+	for (const name of wanted) await collect(name);
+
+	if (missing.length) {
+		throw new Error(
+			`Unknown component(s): ${missing.join(", ")} — run \`bdui list\`.`
+		);
+	}
+
+	const outRoot = flags.path ?? project.sourceRoot;
+	const deps = new Map(); // pkgName → 带 版本的 spec(去重,优先带版本形式)
+	let wrote = 0;
+	writeItemFiles.lastWroteStyles = false;
+
+	for (const item of resolved.values()) {
+		for (const dep of item.dependencies ?? []) {
+			const pkgName = dep.split("@")[0] || dep;
+			if (!project.deps[pkgName]) {
+				const prev = deps.get(pkgName);
+				if (!prev || (prev === pkgName && dep !== pkgName))
+					deps.set(pkgName, dep);
+			}
+		}
+		wrote += await writeItemFiles(item, outRoot, flags);
+	}
+
+	if (deps.size) {
+		const specs = [...deps.values()];
+		if (flags.noDeps) {
+			console.log(
+				`  ${c.yellow("deps")}   still needed (installDependencies was false): ${project.packageManager} add ${specs.join(" ")}`
+			);
+		} else {
+			console.log(`  ${c.cyan("deps")}   installing ${specs.join(", ")}`);
+			const spin = process.stderr.isTTY
+				? ora({
+						text: "Installing dependencies…",
+						stream: process.stderr,
+						color: "cyan",
+					}).start()
+				: null;
+			try {
+				await installPackages(project.packageManager, specs, project.cwd);
+				spin?.succeed("Dependencies installed");
+			} catch (e) {
+				spin?.fail("Dependency installation failed");
+				throw e;
+			}
+		}
+	}
+	console.log(c.green(`\n✓ ${wrote} file(s) written.`));
+	// 与 boardui 同款 Note:样式入口提示(本次写过 styles/ 文件时)
+	if (writeItemFiles.lastWroteStyles) {
+		console.log(
+			c.dim(
+				`\nNote: import the BoardUI styles in your root layout or global css:\n  import "@/styles/globals.css";`
+			)
+		);
+	}
+}

package/src/cli.js

@@ -0,0 +1,95 @@
+// 命令解析 — commander(与 boardui 同款),五命令 + 自动 help
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { cmdAdd } from "./add.js";
+import { cmdInit } from "./init.js";
+import { cmdList } from "./list.js";
+import { cmdMcp } from "./mcp.js";
+import { cmdSkill } from "./skill.js";
+
+const VERSION = JSON.parse(
+	readFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
+
+export async function run(argv) {
+	const program = new Command();
+
+	program
+		.name("bdui")
+		.description("Add BoardUI components to your project.")
+		.version(VERSION, "-v, --version", "output the version number")
+		.helpOption("-h, --help", "display help for command")
+		.helpCommand("help [command]", "display help for command");
+
+	program
+		.command("init")
+		.description(
+			"Set up BoardUI in an existing React project (deps, theme, utils)."
+		)
+		.option("-y, --yes", "skip confirmation prompts")
+		.option("-o, --overwrite", "overwrite existing files")
+		.option(
+			"-d, --dir <dir>",
+			"target directory (defaults to the project source root)"
+		)
+		.option(
+			"--pro",
+			"also install the deps BoardUI Pro components use (recharts, motion, ...)"
+		)
+		.action(cmdInit);
+
+	program
+		.command("add [components...]")
+		.description("Add components to your project.")
+		.option("-a, --all", "add every component in the registry")
+		.option(
+			"-k, --key <key>",
+			"license key for Pro components (single command, nothing is saved)"
+		)
+		.option(
+			"-p, --path <path>",
+			"custom directory to write component files into"
+		)
+		.option(
+			"-d, --dir <dir>",
+			"target directory (defaults to the project source root)"
+		)
+		.option("-o, --overwrite", "overwrite existing files")
+		.option("-y, --yes", "skip prompts (skips existing files, installs deps)")
+		.action(cmdAdd);
+
+	program
+		.command("list")
+		.description("List all available components.")
+		.action(cmdList);
+
+	program
+		.command("mcp")
+		.description(
+			"Start the BoardUI MCP server (stdio) so AI agents can browse and install components. Pass --key to unlock Pro items for the whole session (embed it in the args of your MCP config)."
+		)
+		.option(
+			"-k, --key <key>",
+			"license key for Pro components, active for this server session (nothing is saved)"
+		)
+		.action((options) => cmdMcp(options));
+
+	program
+		.command("skill")
+		.description(
+			"Install the BoardUI agent skill (SKILL.md + references) so agents know the design system."
+		)
+		.option(
+			"-g, --global",
+			"install to ~/.claude/skills/boardui instead of the project's .claude/skills"
+		)
+		.option(
+			"-c, --client <client>",
+			"install to ~/.agents/skills/boardui for clients that read it (codex, gemini)"
+		)
+		.option("-p, --path <dir>", "custom directory to install the skill into")
+		.option("-f, --force", "overwrite an existing install (how you update)")
+		.action(cmdSkill);
+
+	await program.parseAsync(argv, { from: "user" });
+}

package/src/color.js

@@ -0,0 +1,11 @@
+// picocolors 薄封装:保持各模块在用的具名色 API
+import pc from "picocolors";
+
+export default {
+	green: pc.green,
+	yellow: pc.yellow,
+	red: pc.red,
+	cyan: pc.cyan,
+	dim: pc.dim,
+	bold: pc.bold,
+};

package/src/init.js

@@ -0,0 +1,79 @@
+// `bdui init` — 对齐 boardui init:装 foundations(cx/theme/typography/globals)
+// + agent 规则(AGENTS.md + .cursor/rules),内容全部来自 registry(与官方同源)
+
+import ora from "ora";
+import { installPackages } from "./add.js";
+import c from "./color.js";
+import { detectProject } from "./project.js";
+import { fetchItem } from "./registry.js";
+import { applyAgentRules } from "./rules.js";
+import { writeItemFiles } from "./write.js";
+
+const FOUNDATIONS = ["cx", "theme", "typography", "globals"];
+const PRO_EXTRA_DEPS = [
+	"motion",
+	"recharts",
+	"react-aria-components",
+	"@remixicon/react",
+	"@internationalized/date",
+];
+
+export async function cmdInit(flags) {
+	const cwd = flags.dir ?? process.cwd();
+	const project = detectProject(cwd);
+	if (!project.pkg)
+		throw new Error("No package.json found — run inside your app project.");
+
+	console.log(
+		`${c.cyan("init")}   detected ${project.packageManager}, src=${project.usesSrcDir}, alias=${project.alias}`
+	);
+
+	// npm 依赖:foundation 用到的 + 可选 pro 依赖(官方 --pro 同款集)
+	const deps = new Set(["clsx", "tailwind-merge"]);
+	if (flags.pro) {
+		for (const d of PRO_EXTRA_DEPS) deps.add(d);
+	}
+
+	// foundations 条目落盘(boardui init 同款:theme tokens、type scale、globals、cx)
+	const outRoot = flags.path ?? project.sourceRoot;
+	let wrote = 0;
+	for (const name of FOUNDATIONS) {
+		const item = await fetchItem(name);
+		for (const dep of item.dependencies ?? []) {
+			const pkgName = dep.split("@")[0] || dep;
+			if (!project.deps[pkgName]) deps.add(dep);
+		}
+		wrote += await writeItemFiles(item, outRoot, flags);
+	}
+
+	// agent 规则(AGENTS.md + .cursor/rules/boardui.mdc)
+	const ruleLines = await applyAgentRules(cwd);
+
+	if (deps.size) {
+		console.log(`  ${c.cyan("deps")}   ${[...deps].join(", ")}`);
+		const spin = process.stderr.isTTY
+			? ora({
+					text: "Installing dependencies…",
+					stream: process.stderr,
+					color: "cyan",
+				}).start()
+			: null;
+		try {
+			await installPackages(project.packageManager, [...deps], cwd);
+			spin?.succeed("Dependencies installed");
+		} catch (e) {
+			spin?.fail("Dependency installation failed");
+			throw e;
+		}
+	}
+	console.log(c.green(`\n✓ ${wrote} foundation file(s) written.`));
+	for (const line of ruleLines) console.log(line);
+	console.log(
+		`  ${c.dim('Note: import the styles in your root layout or global css: import "@/styles/globals.css";')}`
+	);
+	console.log(
+		c.green(
+			"BoardUI ready. Add components with npx @collectui/bdui add <name>."
+		)
+	);
+}

package/src/list.js

@@ -0,0 +1,28 @@
+// `bdui list` 复刻 — 按分组打印 name + description
+import c from "./color.js";
+import { fetchIndex } from "./registry.js";
+
+export async function cmdList() {
+	const { items } = await fetchIndex(true);
+	const groups = new Map();
+	for (const item of items) {
+		const key = item.bdui2Type ?? "base";
+		if (!groups.has(key)) groups.set(key, []);
+		groups.get(key).push(item);
+	}
+	const labels = {
+		base: "Base components",
+		application: "Application blocks",
+		foundations: "Foundations",
+	};
+	for (const [key, group] of groups) {
+		console.log(c.bold(labels[key] ?? key));
+		const width = Math.max(...group.map((i) => i.name.length)) + 2;
+		for (const item of group) {
+			const name = item.name.padEnd(width);
+			console.log(`  ${name}${item.description ?? ""}`);
+		}
+		console.log();
+	}
+	console.log("Add a component with npx @collectui/bdui add <name>");
+}

package/src/mcp.js

@@ -0,0 +1,408 @@
+// `bdui mcp` — 裸 JSON-RPC 2.0 over stdio 的 MCP server(零依赖)
+// 工具面对齐 boardui MCP(13 个去掉 license 三件套 = 10 个):
+// get_started / list_components / get_component / get_usage_examples /
+// install_components / init_boardui / install_rules / get_skill / install_skill / get_theme
+
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import path from "path";
+import { createInterface } from "readline";
+import { z } from "zod";
+import { cmdAdd } from "./add.js";
+import { detectProject } from "./project.js";
+import { fetchIndex, fetchItem } from "./registry.js";
+import { applyAgentRules } from "./rules.js";
+
+const SKILL_ITEM = "skill";
+
+const NAME_PATTERN_DOC = "Exact item name from list_components.";
+const DIR_DOC = "Absolute path of the project root (defaults to cwd).";
+
+// zod 声明参数 → tools/list 的 inputSchema;tools/call 入口同一 schema 校验
+const SCHEMAS = {
+	get_started: z.object({}),
+	list_components: z.object({
+		tier: z
+			.string()
+			.optional()
+			.describe("'free' or 'pro' to filter; omit for all."),
+	}),
+	get_component: z.object({
+		name: z.string().describe(NAME_PATTERN_DOC),
+		key: z
+			.string()
+			.optional()
+			.describe(
+				"License key for Pro items; optional when the server was started with --key."
+			),
+	}),
+	get_usage_examples: z.object({
+		name: z.string().describe(NAME_PATTERN_DOC),
+		key: z.string().optional(),
+	}),
+	install_components: z.object({
+		names: z.array(z.string()).describe("Items from list_components."),
+		key: z
+			.string()
+			.optional()
+			.describe(
+				"License key for Pro items (same as `add --key`); optional when the server was started with --key."
+			),
+		overwrite: z.boolean().optional(),
+		installDependencies: z.boolean().optional(),
+		projectDir: z.string().optional().describe(DIR_DOC),
+	}),
+	init_boardui: z.object({
+		pro: z
+			.boolean()
+			.optional()
+			.describe(
+				"Also install the deps Pro components use (recharts, motion, ...)."
+			),
+		overwrite: z.boolean().optional(),
+		projectDir: z.string().optional().describe(DIR_DOC),
+	}),
+	install_rules: z.object({
+		overwrite: z.boolean().optional(),
+		projectDir: z.string().optional().describe(DIR_DOC),
+	}),
+	get_skill: z.object({}),
+	install_skill: z.object({
+		overwrite: z.boolean().optional(),
+		projectDir: z.string().optional().describe(DIR_DOC),
+	}),
+	get_theme: z.object({}),
+};
+
+const DESCRIPTIONS = {
+	get_started:
+		"Overview of BoardUI and how to use this server: setup, discovering components, installing, and the design rules.",
+	list_components:
+		"Lists every installable BoardUI item with exact names: free foundations/base/application items and Pro components/templates.",
+	get_component:
+		"Full detail for one BoardUI item: description, docs URL, npm/BoardUI dependencies, registry dependencies, and every source file with content.",
+	get_usage_examples:
+		"Working usage snippets for a BoardUI item, straight from its docs page.",
+	install_components:
+		"Installs BoardUI components/templates into the user's project: writes source files, resolves internal dependencies recursively, and installs npm dependencies.",
+	init_boardui:
+		"One-time BoardUI setup for an existing React project: installs deps, writes theme tokens, globals, the cx utility, and the always-on agent design rules (AGENTS.md + .cursor/rules).",
+	install_rules:
+		"Writes BoardUI's always-on design rules into the project: a fenced section in AGENTS.md plus .cursor/rules/boardui.mdc. init_boardui already does this — call this on projects initialized before rules existed, or to pull the latest rules.",
+	get_skill:
+		"What the BoardUI agent skill is and what it contains: returns the live SKILL.md plus the bundled reference files with their sizes and the install options for every client.",
+	install_skill:
+		"Writes the BoardUI agent skill into the project's .claude/skills/boardui (SKILL.md + references) so skill-capable agents get always-loaded BoardUI knowledge.",
+	get_theme:
+		"The BoardUI theme foundations: color primitives + semantic tokens (the source of every color in the system) and how to re-tint the accent ramp.",
+};
+
+const TOOLS = Object.entries(SCHEMAS).map(([name, schema]) => ({
+	name,
+	description: DESCRIPTIONS[name],
+	inputSchema: z.toJSONSchema(schema),
+}));
+
+function groupLabel(t) {
+	return (
+		{
+			base: "Base components",
+			application: "Application blocks",
+			foundations: "Foundations",
+		}[t] ?? t
+	);
+}
+
+// serverKey:`bdui mcp --key <key>` 启动内嵌(.mcp.json args),整会话兜底;
+// 调用级 key 参数优先。两者都不落盘,请求结束即消失。
+async function loadItem(name, key, serverKey) {
+	return fetchItem(name, key ?? serverKey);
+}
+
+async function dispatch(name, args, captured, serverKey) {
+	const projectDir = args.projectDir ?? process.cwd();
+	switch (name) {
+		case "get_started":
+			return [
+				"BoardUI is a React design system for agentic interfaces: components are copied into your project as plain React + Tailwind files (no runtime package).",
+				"",
+				"Quick flow:",
+				"1. init_boardui — one-time setup (deps, theme tokens, globals, cx, agent rules).",
+				"2. list_components — discover; get_component reads source/props.",
+				"3. get_usage_examples — working code for an item.",
+				"4. install_components — writes files, resolves internal deps recursively, installs npm deps.",
+				"",
+				"Pro items need the license key. Two ways, both leave nothing stored on this machine:",
+				"- Embed it in this server's config once: `npx -y @collectui/bdui mcp --key <key>` (the args block of your MCP config) — every tool call in the session is unlocked.",
+				"- Or pass it per call as `key` to install_components (same as the CLI's `add --key <license-key>`).",
+				"CLI equivalents: npx @collectui/bdui init | list | add <name> [--key <key>] | skill | mcp [--key <key>].",
+			].join("\n");
+
+		case "list_components": {
+			const idx = await fetchIndex(true);
+			const tier = (args.tier ?? "").toLowerCase();
+			const isPro = (i) => Boolean(i.pro);
+			const want = (i) =>
+				tier === "pro" ? isPro(i) : tier === "free" ? !isPro(i) : true;
+			const items = idx.items.filter(want);
+			const header =
+				tier === "pro"
+					? "## Pro components\nPro license required — pass `key` to install_components."
+					: tier === "free"
+						? "## Free components"
+						: "## All components";
+			const lines = [header];
+			const groups = new Map();
+			for (const i of items) {
+				const g = i.bdui2Type ?? "base";
+				if (!groups.has(g)) groups.set(g, []);
+				groups.get(g).push(i);
+			}
+			for (const [g, group] of groups) {
+				lines.push("", `### ${groupLabel(g)}`);
+				for (const i of group)
+					lines.push(
+						`- ${i.name}${i.pro ? " (pro)" : ""}: ${i.description ?? i.title ?? ""}`
+					);
+			}
+			return lines.join("\n");
+		}
+
+		case "get_component": {
+			const item = await loadItem(args.name, args.key, serverKey);
+			const meta = item.meta ?? {};
+			const lines = [
+				`# ${item.title ?? args.name} (${args.name})`,
+				item.description ?? "",
+				meta.docsUrl ? `Docs: ${meta.docsUrl}` : "",
+				"",
+				`npm dependencies: ${(item.dependencies ?? []).join(", ") || "none"}`,
+				`internal dependencies: ${(item.registryDependencies ?? []).join(", ") || "none"}`,
+				`files: ${(item.files ?? []).map((f) => f.path).join(", ")}`,
+			];
+			const first = item.files?.[0];
+			if (first?.content) {
+				lines.push(
+					"",
+					"## Source (first file)",
+					"```tsx",
+					first.content,
+					"```"
+				);
+			}
+			return lines.filter(Boolean).join("\n");
+		}
+
+		case "get_usage_examples": {
+			const item = await loadItem(args.name, args.key, serverKey);
+			const meta = item.meta ?? {};
+			const lines = [
+				`# ${item.title ?? args.name} (${args.name})`,
+				item.description ?? "",
+			];
+			if (meta.docsUrl) lines.push("", `Docs: ${meta.docsUrl}`);
+			if (meta.example)
+				lines.push("", "## Example", "```tsx", meta.example, "```");
+			if (Array.isArray(meta.snippets) && meta.snippets.length) {
+				lines.push("", "## Snippets");
+				for (const s of meta.snippets)
+					lines.push(
+						"",
+						"```tsx",
+						typeof s === "string" ? s : (s.code ?? JSON.stringify(s)),
+						"```"
+					);
+			}
+			if (!(meta.example || meta.snippets?.length))
+				lines.push("", "No usage examples recorded for this item.");
+			return lines.filter((x) => x !== undefined).join("\n");
+		}
+
+		case "install_components": {
+			const flags = {
+				overwrite: args.overwrite,
+				yes: true,
+				key: args.key ?? serverKey,
+				...(args.installDependencies === false ? { noDeps: true } : {}),
+				...(args.projectDir ? { dir: args.projectDir } : {}),
+			};
+			await cmdAdd(args.names, flags);
+			return `installed: ${args.names.join(", ")}\n${captured.join("\n")}`;
+		}
+
+		case "init_boardui": {
+			const project = detectProject(projectDir);
+			if (!project.pkg) {
+				return `No package.json found in ${projectDir}. Pass projectDir with the absolute path of the project root. If the directory is fresh, scaffold an app there first (e.g. npx create-next-app@latest .), then call init_boardui again.`;
+			}
+			const { cmdInit } = await import("./init.js");
+			await cmdInit({
+				dir: projectDir,
+				pro: args.pro,
+				overwrite: args.overwrite,
+				yes: true,
+			});
+			const ruleLines = await applyAgentRules(projectDir);
+			return ["Setup complete.", ...captured, ...ruleLines].join("\n");
+		}
+
+		case "install_rules":
+			return (await applyAgentRules(projectDir)).join("\n");
+
+		case "get_skill": {
+			const skill = await loadItem(SKILL_ITEM);
+			const skillMd = skill.files?.find((f) => f.path.endsWith("SKILL.md"));
+			const refs = (skill.files ?? []).filter(
+				(f) => !f.path.endsWith("SKILL.md")
+			);
+			const lines = [
+				"The BoardUI agent skill (SKILL.md open standard) gives skill-capable agents always-loaded BoardUI knowledge; the MCP server stays the on-demand companion for live source and installs.",
+				"",
+				"Files in the skill:",
+				`- SKILL.md (${(skillMd?.content ?? "").length.toLocaleString()} bytes)`,
+				...refs.map(
+					(f) =>
+						`- ${path.posix.basename(f.path)} (${(f.content ?? "").length.toLocaleString()} bytes)`
+				),
+				"",
+				"Install options: install_skill (this MCP, project .claude/skills/boardui) or the CLI: npx @collectui/bdui skill (project), --global (~/.claude/skills), --client codex (~/.agents/skills, read by Codex and Gemini), --path <dir>, --force (update).",
+			];
+			if (skillMd?.content) lines.push("", "---", skillMd.content);
+			return lines.join("\n");
+		}
+
+		case "install_skill": {
+			const skill = await loadItem(SKILL_ITEM);
+			const target = path.join(projectDir, ".claude", "skills", "boardui");
+			mkdirSync(target, { recursive: true });
+			let n = 0;
+			for (const f of skill.files ?? []) {
+				// references/ 下的归 references/,其余(SKILL.md)落根
+				const rel = f.path.includes("references/")
+					? path.join("references", path.posix.basename(f.path))
+					: path.posix.basename(f.path);
+				const dest = path.join(target, rel);
+				mkdirSync(path.dirname(dest), { recursive: true });
+				if (existsSync(dest) && !args.overwrite) continue;
+				writeFileSync(dest, f.content ?? "");
+				n++;
+			}
+			return `Skill ${n > 0 ? `installed (${n} files)` : "already present (pass overwrite)"} → ${target}`;
+		}
+
+		case "get_theme": {
+			const theme = await loadItem("theme");
+			const globals = await loadItem("globals");
+			const themeCss = theme.files?.[0]?.content ?? "";
+			const lines = [
+				"# BoardUI theme foundations",
+				"",
+				"Every color rides a semantic token (text / background / border / foreground / chart); dark mode flips tokens automatically under `.dark` — never write a dark: override or a raw hex value. The accent ramp drives CTAs and selection states and can be re-tinted to your brand in one override.",
+				"",
+				"## theme (color primitives + semantic tokens)",
+				"```css",
+				themeCss.slice(0, 6000),
+				"```",
+				"",
+				"## globals (entry css)",
+				"```css",
+				(globals.files?.[0]?.content ?? "").slice(0, 3000),
+				"```",
+			];
+			return lines.join("\n");
+		}
+
+		default:
+			throw new Error(`Unknown tool: ${name}`);
+	}
+}
+
+// CLI 子流程的 console.log 会污染 stdio JSON-RPC 流:调用期间捕获收集
+async function call(name, args, serverKey) {
+	const schema = SCHEMAS[name];
+	if (!schema) throw new Error(`Unknown tool: ${name}`);
+	const parsed = schema.safeParse(args ?? {});
+	if (!parsed.success) {
+		throw new Error(
+			`Invalid arguments for ${name}: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+		);
+	}
+	const captured = [];
+	const originalLog = console.log;
+	console.log = (...a) => captured.push(a.join(" "));
+	try {
+		return await dispatch(name, parsed.data, captured, serverKey);
+	} finally {
+		console.log = originalLog;
+	}
+}
+
+export async function cmdMcp(options = {}) {
+	const serverKey = options.key ?? undefined; // `bdui mcp --key <key>`:整会话兜底,见 loadItem 注释
+	const rl = createInterface({ input: process.stdin });
+	const write = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
+
+	rl.on("line", (line) => {
+		if (!line.trim()) return;
+		let msg;
+		try {
+			msg = JSON.parse(line);
+		} catch {
+			return write({
+				jsonrpc: "2.0",
+				id: null,
+				error: { code: -32_700, message: "Parse error" },
+			});
+		}
+		const { id, method, params } = msg;
+		(async () => {
+			if (method === "initialize") {
+				return write({
+					jsonrpc: "2.0",
+					id,
+					result: {
+						protocolVersion: params?.protocolVersion ?? "2024-11-05",
+						capabilities: { tools: {} },
+						serverInfo: { name: "boardui", version: VERSION },
+					},
+				});
+			}
+			if (
+				method === "notifications/initialized" ||
+				method === "notifications/cancelled"
+			)
+				return;
+			if (method === "ping") return write({ jsonrpc: "2.0", id, result: {} });
+			if (method === "tools/list")
+				return write({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+			if (method === "tools/call") {
+				try {
+					const result = await call(
+						params.name,
+						params.arguments ?? {},
+						serverKey
+					);
+					return write({
+						jsonrpc: "2.0",
+						id,
+						result: { content: [{ type: "text", text: String(result) }] },
+					});
+				} catch (error) {
+					return write({
+						jsonrpc: "2.0",
+						id,
+						result: {
+							content: [{ type: "text", text: `Error: ${error.message}` }],
+							isError: true,
+						},
+					});
+				}
+			}
+			write({
+				jsonrpc: "2.0",
+				id,
+				error: { code: -32_601, message: `Method not found: ${method}` },
+			});
+		})().catch(() => {});
+	});
+	return new Promise(() => {}); // stdio server 常驻
+}

package/src/project.js

@@ -0,0 +1,45 @@
+// 项目检测复刻 — package manager / ts / 组件写入根 / 别名
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+
+export function detectProject(cwd = process.cwd()) {
+	const pkgPath = path.join(cwd, "package.json");
+	const pkg = existsSync(pkgPath)
+		? JSON.parse(readFileSync(pkgPath, "utf8"))
+		: null;
+	const deps = {
+		...(pkg?.dependencies ?? {}),
+		...(pkg?.devDependencies ?? {}),
+	};
+
+	const usesSrcDir = existsSync(path.join(cwd, "src"));
+	const sourceRoot = usesSrcDir ? path.join(cwd, "src") : cwd;
+
+	// 组件目录: @/ 别名指向的 components 目录,fallback 到 <src>/components/ui
+	let alias = "@/components/ui";
+	try {
+		const ts = readFileSync(path.join(cwd, "tsconfig.json"), "utf8");
+		const m = ts.match(/"components\/\*"[^}]*"(.\/[^"]*components)[^"]*"/);
+		if (m) alias = m[1].replace(/^\.\//, "@/");
+	} catch {}
+
+	let packageManager = "npm";
+	if (existsSync(path.join(cwd, "pnpm-lock.yaml"))) packageManager = "pnpm";
+	else if (existsSync(path.join(cwd, "yarn.lock"))) packageManager = "yarn";
+	else if (existsSync(path.join(cwd, "bun.lockb"))) packageManager = "bun";
+
+	return { cwd, pkg, deps, usesSrcDir, sourceRoot, alias, packageManager };
+}
+
+export function installCommand(pm, packages) {
+	switch (pm) {
+		case "pnpm":
+			return ["pnpm", ["add", ...packages]];
+		case "yarn":
+			return ["yarn", ["add", ...packages]];
+		case "bun":
+			return ["bun", ["add", ...packages]];
+		default:
+			return ["npm", ["install", ...packages]];
+	}
+}

package/src/registry.js

@@ -0,0 +1,54 @@
+// Registry 拉取 — shadcn registry.json schema 兼容
+// 公共:  GET {BASE}/r/registry.json 与 /r/<name>.json      (免鉴权)
+// Pro:   GET {BASE}/api/pro/r/<name>   Bearer <key>(CLI `add --key` 传入 / MCP server `mcp --key` 启动内嵌;校验/缓存/熔断全在服务端)
+// 端点内置,不提供 env 覆盖,本机不存任何状态。
+const BASE = "https://boardui.collectui.pro";
+
+export const registryBaseUrl = () => `${BASE}/r`;
+export const proRegistryBaseUrl = () => `${BASE}/api/pro/r`;
+
+async function fetchJson(url, headers) {
+	const response = await fetch(url, { headers });
+	if (!response.ok)
+		throw new Error(`Registry request failed (${response.status}) for ${url}`);
+	return response.json();
+}
+
+export async function fetchIndex(includePro = false) {
+	const base = await fetchJson(`${registryBaseUrl()}/registry.json`);
+	if (!includePro) return base;
+	try {
+		const pro = await fetchJson(`${registryBaseUrl()}/registry-pro.json`);
+		return {
+			...base,
+			items: [...base.items, ...pro.items.map((i) => ({ ...i, pro: true }))],
+		};
+	} catch {
+		return base; // pro index 拉不到时静默降级
+	}
+}
+
+// 单个条目:先公共后 pro。pro 的 key 校验在服务端完成,客户端只管带 Bearer 下载。
+export async function fetchItem(name, key) {
+	try {
+		return await fetchJson(`${registryBaseUrl()}/${name}.json`);
+	} catch {
+		if (!key) {
+			throw new Error(
+				`"${name}" is a BoardUI Pro component. Pass --key <license-key> to install it (CLI), or start the MCP server with --key <key>. The key is distributed by your platform or administrator.`
+			);
+		}
+		const response = await fetch(`${proRegistryBaseUrl()}/${name}`, {
+			headers: { Authorization: `Bearer ${key}` },
+		});
+		if (!response.ok) {
+			let message = `Pro registry request failed (${response.status}).`;
+			try {
+				const body = await response.json();
+				if (body.message ?? body.error) message = body.message ?? body.error;
+			} catch {}
+			throw new Error(message);
+		}
+		return response.json();
+	}
+}

package/src/rules.js

@@ -0,0 +1,53 @@
+// Agent 设计规则 — 与 boardui 的 applyAgentRules 同款:
+// rules registry 条目 → AGENTS.md fenced section + .cursor/rules/boardui.mdc
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+import { fetchItem } from "./registry.js";
+
+export async function applyAgentRules(projectDir) {
+	const rules = await fetchItem("rules");
+	const content = rules.files?.[0]?.content;
+	if (!content) return ["Rules item has no content."];
+
+	const agentsMd = path.join(projectDir, "AGENTS.md");
+	const section = `\n<!-- boardui:rules start -->\n${content}\n<!-- boardui:rules end -->\n`;
+	let verb;
+	if (existsSync(agentsMd)) {
+		const prev = readFileSync(agentsMd, "utf8");
+		if (
+			prev.includes("boardui:rules start") ||
+			prev.includes("bdui2:rules start")
+		) {
+			writeFileSync(
+				agentsMd,
+				prev.replace(
+					/<!-- boardui:rules start -->[\s\S]*?<!-- boardui:rules end -->/,
+					section.trimEnd()
+				)
+			);
+			verb = "refreshed in AGENTS.md";
+		} else {
+			writeFileSync(agentsMd, prev + section);
+			verb = "appended to AGENTS.md";
+		}
+	} else {
+		writeFileSync(agentsMd, `# AGENTS.md\n${section}`);
+		verb = "written to a new AGENTS.md";
+	}
+
+	const cursorDir = path.join(projectDir, ".cursor", "rules");
+	mkdirSync(cursorDir, { recursive: true });
+	writeFileSync(path.join(cursorDir, "boardui.mdc"), content);
+
+	const lines = [`  rules    ${verb}(AGENTS.md + .cursor/rules/boardui.mdc)`];
+	const claudeMd = path.join(projectDir, "CLAUDE.md");
+	if (
+		existsSync(claudeMd) &&
+		!readFileSync(claudeMd, "utf8").includes("AGENTS.md")
+	) {
+		lines.push(
+			'  Note: CLAUDE.md does not reference AGENTS.md — add a "@AGENTS.md" line so Claude Code loads the BoardUI rules too.'
+		);
+	}
+	return lines;
+}

package/src/skill.js

@@ -0,0 +1,38 @@
+// `bdui skill` — 从 registry 拉 skill 条目(SKILL.md + references)写入目标目录
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import path from "path";
+import c from "./color.js";
+import { fetchItem } from "./registry.js";
+
+export async function cmdSkill(flags) {
+	// -g → ~/.claude/skills; -c → ~/.agents/skills (codex/gemini);默认项目内 .claude/skills
+	const home = process.env.HOME;
+	let target;
+	if (flags.global) target = path.join(home, ".claude", "skills", "boardui");
+	else if (flags.client)
+		target = path.join(home, ".agents", "skills", "boardui");
+	else target = path.join(process.cwd(), ".claude", "skills", "boardui");
+
+	const skill = await fetchItem("skill");
+	if (existsSync(target) && !flags.force) {
+		throw new Error(
+			`${target} already exists — pass --force to overwrite (how you update).`
+		);
+	}
+	rmSync(target, { recursive: true, force: true });
+	mkdirSync(target, { recursive: true });
+	let n = 0;
+	for (const f of skill.files ?? []) {
+		const rel = f.path.includes("references/")
+			? path.join("references", path.posix.basename(f.path))
+			: path.posix.basename(f.path);
+		const dest = path.join(target, rel);
+		mkdirSync(path.dirname(dest), { recursive: true });
+		writeFileSync(dest, f.content ?? "");
+		n++;
+	}
+	console.log(c.green(`✓ Agent skill installed → ${target} (${n} files)`));
+	console.log(
+		"  Agents can now browse BoardUI with always-loaded design-system knowledge."
+	);
+}

package/src/write.js

@@ -0,0 +1,51 @@
+// 条目落盘共享逻辑(add / init 复用):registry item → sourceRoot 相对路径
+// 已存在文件:--overwrite 覆盖、--yes 跳过、否则 prompts 交互询问(boardui 同款)
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import path from "path";
+import pc from "picocolors";
+import prompts from "prompts";
+
+/** 非交互环境(MCP/无 TTY/-y)返回 false(跳过);交互时逐个问,可 All */
+async function confirmOverwrite(target, flags, state) {
+	if (flags.overwrite || state.all) return true;
+	if (flags.yes || !process.stdin.isTTY) return false;
+	const { value } = await prompts({
+		type: "select",
+		name: "value",
+		message: `Overwrite ${path.relative(process.cwd(), target)}?`,
+		choices: [
+			{ title: "Yes", value: "yes" },
+			{ title: "No (skip)", value: "no" },
+			{ title: "All (overwrite the rest)", value: "all" },
+		],
+		initial: 1,
+		stdout: process.stderr, // 交互走 stderr,不污染管道输出
+	});
+	if (value === "all") state.all = true;
+	return value === "yes" || value === "all";
+}
+
+export async function writeItemFiles(item, outRoot, flags = {}) {
+	let wrote = 0;
+	let wroteStyles = false;
+	const state = { all: false };
+	for (const file of item.files ?? []) {
+		const target = path.join(outRoot, file.path);
+		if (existsSync(target) && !(await confirmOverwrite(target, flags, state))) {
+			console.log(
+				`  ${pc.yellow("skip")}    ${path.relative(process.cwd(), target)} (exists)`
+			);
+			continue;
+		}
+		mkdirSync(path.dirname(target), { recursive: true });
+		writeFileSync(target, file.content ?? "");
+		wrote++;
+		if (file.path.startsWith("styles/")) wroteStyles = true;
+		console.log(
+			`  ${pc.green("add")}    ${path.relative(process.cwd(), target)}${item.pro ? pc.cyan(" (pro)") : ""}`
+		);
+	}
+	writeItemFiles.lastWroteStyles =
+		writeItemFiles.lastWroteStyles || wroteStyles;
+	return wrote;
+}