@collectui/bdui 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collectui/bdui",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Add BoardUI components to your project.",
   "license": "MIT",
   "type": "module",

package/src/add.js

@@ -3,6 +3,7 @@
 import { spawn } from "child_process";
 import ora from "ora";
 import c from "./color.js";
+import { itemHints } from "./hints.js";
 import { detectProject, installCommand } from "./project.js";
 import { fetchIndex, fetchItem } from "./registry.js";
 import { writeItemFiles } from "./write.js";
@@ -95,6 +96,7 @@ export async function cmdAdd(names, flags) {
 	const deps = new Map(); // pkgName → 带 版本的 spec(去重,优先带版本形式)
 	const nextImports = new Set();
 	let wrote = 0;
+	let skippedExisting = 0;
 	writeItemFiles.lastWroteStyles = false;
 
 	for (const item of resolved.values()) {
@@ -110,7 +112,12 @@ export async function cmdAdd(names, flags) {
 			for (const m of (f.content ?? "").matchAll(/from\s+["'](next\/[a-z-]+)/g))
 				nextImports.add(m[1]);
 		}
-		wrote += await writeItemFiles(item, outRoot, flags);
+		const r = await writeItemFiles(item, outRoot, flags);
+		wrote += r.wrote;
+		skippedExisting += r.skippedExisting;
+		// 源码特征提示(不写死:特征随官方源码演进,官方修好提示自动消失)
+		for (const h of itemHints(item))
+			console.log(c.yellow(`  ${item.name}: ${h}`));
 	}
 
 	if (deps.size) {
@@ -139,13 +146,23 @@ export async function cmdAdd(names, flags) {
 	}
 	console.log(c.green(`\n✓ ${wrote} file(s) written.`));
 	if (wrote === 0) {
-		console.log(
-			c.yellow(
-				"  warn  nothing was written — every file was skipped, or the registry entry ships no component source (upstream entry may be broken)"
-			)
-		);
+		if (skippedExisting > 0) {
+			// 全部跳过=已装过,不是上游坏了(盲测 r2 P7 误报「may be broken」)
+			console.log(
+				c.yellow(
+					`  already installed (${skippedExisting} file(s) exist) — pass --overwrite to update`
+				)
+			);
+		} else {
+			console.log(
+				c.yellow(
+					"  warn  nothing was written — every file was skipped, or the registry entry ships no component source (upstream entry may be broken)"
+				)
+			);
+		}
 	}
-	if (nextImports.size) {
+	// Next 项目里 next/link 是一等公民,提示反而是噪音(盲测 #10)
+	if (nextImports.size && !project.deps?.next) {
 		console.log(
 			c.yellow(
 				`\nNote: ${[...nextImports].sort().join(", ")} imported by installed files — these only compile in a Next.js project.`

package/src/hints.js

@@ -0,0 +1,22 @@
+// 条目提示(2026-10-26 盲测 r2 P2)——基于内容特征检测,不写死条目名:
+// 官方源码随时会变,特征还在才提示,官方修好提示自动消失(用户铁律:
+// 官方源码透传不改写,上游问题顶多提示,且提示不能写死)。
+
+/**
+ * 按条目当前源码特征给出安装/使用提示;无特征命中返回 []。
+ * @param {object} item registry 条目(files[].content)
+ * @returns {string[]}
+ */
+export function itemHints(item) {
+	const hints = [];
+	const src = (item.files ?? []).map((f) => f.content ?? "").join("\n");
+
+	// render 期读当前时间(new Date() / react-aria .toDate()):Next.js 16
+	// Cache Components 预渲染会炸,官方目前 calendar 系如此
+	if (/\bnew Date\(\)|\.toDate\(/.test(src)) {
+		hints.push(
+			"Note: this item reads the current time while rendering (per current registry source). On Next.js 16 Cache Components, wrap it in <Suspense> or `next build` prerendering fails."
+		);
+	}
+	return hints;
+}

package/src/init.js

@@ -1,7 +1,8 @@
 // `bdui init` — 对齐 boardui init:装 foundations(cx/theme/typography/globals)
 // + agent 规则(AGENTS.md + .cursor/rules),内容全部来自 registry(与官方同源)
 
-import { existsSync } from "fs";
+import { execSync } from "child_process";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
 import ora from "ora";
 import path from "path";
 import { installPackages, pkgBaseName } from "./add.js";
@@ -29,9 +30,31 @@ function frameworkSetup(project, cwd) {
 
 	if (!has("tailwindcss")) pkgs.push("tailwindcss");
 	if (project.deps?.next) {
-		// Next.js:官方模板自带 @/ alias 与 @types/node;仅补缺失的 tailwind 管道
-		if (!has("@tailwindcss/postcss")) pkgs.push("@tailwindcss/postcss");
-		return { pkgs, notes };
+		// Next.js:官方模板自带 @/ alias 与 @types/node;仅补缺失的 tailwind 管道。
+		// postcss 配置是硬前提:模板没带 Tailwind 时 postcss.config 不存在,
+		// @tailwindcss/postcss 装了也不接管,组件样式静默失效(next build 只给
+		// "Unknown at rule: @apply" 警告仍报成功)——缺配置就补 v4 标准形态。
+		// 反向同理(CNA 16 默认 @tailwindcss/turbopack 管道):已走 turbopack
+		// 就不再注入 postcss,避免双管道并存困惑(盲测 r2 P13)
+		const hasTurbopackTw = has("@tailwindcss/turbopack");
+		if (!(hasTurbopackTw || has("@tailwindcss/postcss")))
+			pkgs.push("@tailwindcss/postcss");
+		const writes = [];
+		if (!hasTurbopackTw) {
+			const hasPostcssCfg = [
+				"postcss.config.mjs",
+				"postcss.config.js",
+				"postcss.config.cjs",
+				"postcss.config.ts",
+			].some((f) => existsSync(path.join(cwd, f)));
+			if (!hasPostcssCfg)
+				writes.push({
+					file: "postcss.config.mjs",
+					content:
+						'const config = {\n  plugins: { "@tailwindcss/postcss": {} },\n};\n\nexport default config;\n',
+				});
+		}
+		return { pkgs, notes, writes };
 	}
 	const viteConfig = [
 		"vite.config.ts",
@@ -59,7 +82,7 @@ function frameworkSetup(project, cwd) {
 			].join("\n")
 		);
 	}
-	return { pkgs, notes };
+	return { pkgs, notes, writes: [] };
 }
 
 export async function cmdInit(flags) {
@@ -68,8 +91,10 @@ export async function cmdInit(flags) {
 	if (!project.pkg)
 		throw new Error("No package.json found — run inside your app project.");
 
+	// alias 不在此行展示:tsconfig 的 @/ 别名与实际落位(components/base/<group>)
+	// 口径不同,曾让客户误读(盲测 #6);落位在 ✓ 行明示。src= 是内部术语,给人话(r2 P10)
 	console.log(
-		`${c.cyan("init")}   detected ${project.packageManager}, src=${project.usesSrcDir}, alias=${project.alias}`
+		`${c.cyan("init")}   detected ${project.packageManager}, source root: ${project.usesSrcDir ? "src/" : "project root"}`
 	);
 
 	// npm 依赖:foundation 用到的 + 可选 pro 依赖(官方 --pro 同款集)+ 框架适配
@@ -95,7 +120,131 @@ export async function cmdInit(flags) {
 					deps.set(pkgName, dep);
 			}
 		}
-		wrote += await writeItemFiles(item, outRoot, flags);
+		wrote += (await writeItemFiles(item, outRoot, flags)).wrote;
+	}
+
+	// 框架管道配置(postcss.config.mjs 等):样式静默失效的根因修复(盲测 #1)
+	for (const w of setup.writes ?? []) {
+		const target = path.join(cwd, w.file);
+		if (existsSync(target)) continue;
+		writeFileSync(target, w.content);
+		console.log(
+			`  ${c.green("add")}    ${w.file} (Tailwind v4 PostCSS pipeline)`
+		);
+	}
+
+	// .mcp.json 常嵌 license key(MCP 官方形态)——git 仓库防一次 commit 泄漏(盲测 #3)
+	const gitignore = path.join(cwd, ".gitignore");
+	if (existsSync(path.join(cwd, ".git")) || existsSync(gitignore)) {
+		const cur = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+		if (!/^\s*\.mcp\.json\s*$/m.test(cur)) {
+			appendFileSync(
+				gitignore,
+				`${cur && !cur.endsWith("\n") ? "\n" : ""}\n# BoardUI MCP config (contains your license key)\n.mcp.json\n`
+			);
+			console.log(
+				`  ${c.green("add")}    .gitignore += .mcp.json (license key leak guard)`
+			);
+		}
+		// 已跟踪的 .mcp.json:gitignore 挡不住,防"已安全"错觉(盲测 r2 P8)
+		try {
+			execSync("git ls-files --error-unmatch .mcp.json", {
+				cwd,
+				stdio: "ignore",
+			});
+			console.log(
+				c.yellow(
+					"  warn  .mcp.json is already tracked by git — .gitignore does not untrack it. Run: git rm --cached .mcp.json (and rotate the key if it was ever pushed)"
+				)
+			);
+		} catch {}
+	}
+
+	// 样式入口接线:优先「替换」模板旧 globals 导入而非并排追加——两份
+	// @import \"tailwindcss\" = Tailwind 双编译(~75KB 冗余 CSS)+旧 body Arial
+	// 覆盖 BoardUI 排版(盲测 r2 P3);旧文件非 Tailwind 入口才走追加(盲测 #7)
+	const layoutFile = [
+		"app/layout.tsx",
+		"app/layout.ts",
+		"app/layout.jsx",
+		"app/layout.js",
+	]
+		.map((f) => path.join(project.sourceRoot, f))
+		.find((p) => existsSync(p));
+	let stylesWired = false;
+	let fontsHint = "";
+	if (layoutFile) {
+		const rel = path.relative(cwd, layoutFile);
+		let content = readFileSync(layoutFile, "utf8");
+		if (!content.includes("@/styles/globals.css")) {
+			const lines = content.split("\n");
+			const oldIdx = lines.findIndex((l) =>
+				/^\s*import\s+["']\.\/globals\.css["'];?\s*$/.test(l)
+			);
+			const oldGlobals = path.join(project.sourceRoot, "app/globals.css");
+			const oldIsTw =
+				existsSync(oldGlobals) &&
+				readFileSync(oldGlobals, "utf8").includes('@import "tailwindcss"');
+			if (oldIdx !== -1 && oldIsTw) {
+				lines[oldIdx] = 'import "@/styles/globals.css";';
+				console.log(
+					`  ${c.green("add")}    ${rel}: replaced "./globals.css" → "@/styles/globals.css" (old file was a second Tailwind entry; merge custom styles into BoardUI's if needed)`
+				);
+			} else {
+				// 插到最后一个顶层 import 之后;没有 import 则插到文件头
+				let at = 0;
+				for (let i = 0; i < lines.length; i++)
+					if (/^import[\s{"']/.test(lines[i])) at = i + 1;
+				lines.splice(at, 0, 'import "@/styles/globals.css";');
+				console.log(
+					`  ${c.green("add")}    ${rel}: import "@/styles/globals.css"`
+				);
+			}
+			content = lines.join("\n");
+		}
+		stylesWired = true;
+		// 字体接线(r2 P4):theme.css 期望 --font-inter/--font-mono-source 由
+		// next/font 暴露,模板默认 Geist 不定义它们,注入 Inter + JetBrains Mono
+		if (!content.includes("--font-inter")) {
+			const lines = content.split("\n");
+			let at = 0;
+			for (let i = 0; i < lines.length; i++)
+				if (/^import[\s{"']/.test(lines[i])) at = i + 1;
+			lines.splice(
+				at,
+				0,
+				'import { Inter, JetBrains_Mono } from "next/font/google";',
+				'const bduiInter = Inter({ subsets: ["latin"], variable: "--font-inter" });',
+				'const bduiMono = JetBrains_Mono({ subsets: ["latin"], variable: "--font-mono-source" });'
+			);
+			let next = lines.join("\n");
+			const vars = "${bduiInter.variable} ${bduiMono.variable}";
+			const tag = next.match(/<html[^>]*>/);
+			if (!tag) {
+				fontsHint =
+					"could not find <html> in the layout — attach bduiInter/bduiMono variable classNames manually";
+			} else if (tag[0].includes("className={`")) {
+				next = next.replace("className={`", `className={\`${vars} `);
+			} else {
+				const cm = tag[0].match(/className="([^"]*)"/);
+				if (cm) {
+					next = next.replace(
+						`className="${cm[1]}"`,
+						"className={`" + (cm[1] ? `${cm[1]} ` : "") + vars + "`}"
+					);
+				} else {
+					next = next.replace(
+						tag[0],
+						tag[0].replace(/>$/, ` className={\`${vars}\`}>`)
+					);
+				}
+			}
+			content = next;
+			console.log(
+				`  ${c.green("add")}    ${rel}: Inter + JetBrains Mono via next/font (--font-inter / --font-mono-source)`
+			);
+		}
+		writeFileSync(layoutFile, content);
 	}
 
 	// agent 规则(AGENTS.md + .cursor/rules/boardui.mdc)
@@ -118,11 +267,22 @@ export async function cmdInit(flags) {
 			throw e;
 		}
 	}
-	console.log(c.green(`\n✓ ${wrote} foundation file(s) written.`));
+	// relative 同目录返回 ""/拼接句号曾显示成 "written to .."(盲测 r2 P10)
+	const dest = path.relative(cwd, outRoot);
+	console.log(
+		c.green(
+			`\n✓ ${wrote} foundation file(s) written to ${
+				dest === "" || dest === "." ? "the project root" : dest
+			}.`
+		)
+	);
 	for (const note of setup.notes) console.log(c.yellow(`\n${note}\n`));
 	for (const line of ruleLines) console.log(line);
+	if (fontsHint) console.log(c.yellow(`  warn  fonts: ${fontsHint}`));
 	console.log(
-		`  ${c.dim('Note: import the styles in your root layout or global css: import "@/styles/globals.css";')}`
+		stylesWired
+			? `  ${c.dim('Note: BoardUI styles wired into your root layout (import "@/styles/globals.css").')}`
+			: `  ${c.dim('Note: import the styles in your root layout or global css: import "@/styles/globals.css";')}`
 	);
 	console.log(
 		c.green(

package/src/list.js

@@ -17,9 +17,11 @@ export async function cmdList() {
 	};
 	for (const [key, group] of groups) {
 		console.log(c.bold(labels[key] ?? key));
-		const width = Math.max(...group.map((i) => i.name.length)) + 2;
+		// Pro 标记:混排时无从分辨 Pro/免费(盲测 #5),对齐 MCP list 的 (pro) 口径
+		const label = (i) => (i.pro ? `${i.name} (pro)` : i.name);
+		const width = Math.max(...group.map((i) => label(i).length)) + 2;
 		for (const item of group) {
-			const name = item.name.padEnd(width);
+			const name = label(item).padEnd(width);
 			console.log(`  ${name}${item.description ?? ""}`);
 		}
 		console.log();

package/src/mcp.js

@@ -8,6 +8,7 @@ import path from "path";
 import { createInterface } from "readline";
 import { z } from "zod";
 import { cmdAdd } from "./add.js";
+import { itemHints } from "./hints.js";
 import { detectProject } from "./project.js";
 import { fetchIndex, fetchItem } from "./registry.js";
 
@@ -184,16 +185,40 @@ async function dispatch(name, args, captured, serverKey) {
 				`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,
-					"```"
-				);
+			// 全量源码输出(盲测 r2 P6:工具描述承诺 every file 却只回第一个)。
+			// 超大组件(整页模板)按文件逐个给,累计超限后剩余只列路径——
+			// 需要时 agent 可 install_components 落盘后再读文件。
+			const SRC_BUDGET = 150_000;
+			let used = 0;
+			for (const f of item.files ?? []) {
+				if (!f.content) continue;
+				if (used + f.content.length > SRC_BUDGET) {
+					lines.push(
+						"",
+						`(remaining files omitted for size: ${
+							(item.files ?? [])
+								.filter(
+									(x) =>
+										x.content &&
+										x !== f &&
+										used + x.content?.length > SRC_BUDGET
+								)
+								.map((x) => x.path)
+								.join(", ") || f.path
+						} — install_components writes them to disk)`
+					);
+					break;
+				}
+				used += f.content.length;
+				const lang = (f.path ?? "").endsWith(".ts")
+					? "ts"
+					: (f.path ?? "").endsWith(".css")
+						? "css"
+						: "tsx";
+				lines.push("", `## Source: ${f.path}`, "```" + lang, f.content, "```");
 			}
+			// 源码特征提示(内容检测,不写死;官方修好自动消失)
+			for (const h of itemHints(item)) lines.push("", `> ${h}`);
 			return lines.filter(Boolean).join("\n");
 		}
 
@@ -219,6 +244,8 @@ async function dispatch(name, args, captured, serverKey) {
 			}
 			if (!(meta.example || meta.snippets?.length))
 				lines.push("", "No usage examples recorded for this item.");
+			// 源码特征提示(不写死条目名:特征随官方源码演进,官方修好自动消失)
+			for (const h of itemHints(item)) lines.push("", `> ${h}`);
 			return lines.filter((x) => x !== undefined).join("\n");
 		}
 
@@ -343,6 +370,11 @@ async function call(name, args, serverKey) {
 
 export async function cmdMcp(options = {}) {
 	const serverKey = options.key ?? undefined; // `bdui mcp --key <key>`:整会话兜底,见 loadItem 注释
+	// stderr 提示(stdio 协议,stdout 必须干净):key 常嵌 .mcp.json,防 commit 泄漏(盲测 #3)
+	if (serverKey)
+		console.error(
+			"[bdui] tip: if this key is embedded in .mcp.json, keep that file out of git (add it to .gitignore)."
+		);
 	const rl = createInterface({ input: process.stdin });
 	const write = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
 

package/src/registry.js

@@ -57,6 +57,9 @@ export async function fetchItem(name, key) {
 			} catch {}
 			throw new Error(message);
 		}
-		return response.json();
+		const item = await response.json();
+		// pro 通道拿到的条目缺 pro:true(服务端不回显)——补上,落盘输出标 (pro)(盲测 r2 P13)
+		item.pro = true;
+		return item;
 	}
 }

package/src/write.js

@@ -27,6 +27,7 @@ async function confirmOverwrite(target, flags, state) {
 
 export async function writeItemFiles(item, outRoot, flags = {}) {
 	let wrote = 0;
+	let skippedExisting = 0;
 	let wroteStyles = false;
 	const state = { all: false };
 	for (const file of item.files ?? []) {
@@ -39,6 +40,7 @@ export async function writeItemFiles(item, outRoot, flags = {}) {
 		}
 		const target = path.join(outRoot, rel);
 		if (existsSync(target) && !(await confirmOverwrite(target, flags, state))) {
+			skippedExisting++;
 			console.log(
 				`  ${pc.yellow("skip")}    ${path.relative(process.cwd(), target)} (exists)`
 			);
@@ -52,7 +54,32 @@ export async function writeItemFiles(item, outRoot, flags = {}) {
 			`  ${pc.green("add")}    ${path.relative(process.cwd(), target)}${item.pro ? pc.cyan(" (pro)") : ""}`
 		);
 	}
+	// 二进制 assets(base64):Pro 模板的头像/logo 等图片资源(盲测 r2 P1)
+	for (const asset of item.assets ?? []) {
+		const rel = path.normalize(asset.path ?? "");
+		if (rel.startsWith("..") || path.isAbsolute(rel)) {
+			console.log(`  ${pc.red("skip")}    unsafe path in asset: ${asset.path}`);
+			continue;
+		}
+		const target = path.join(outRoot, "public", rel);
+		if (existsSync(target) && !(await confirmOverwrite(target, flags, state))) {
+			skippedExisting++;
+			console.log(
+				`  ${pc.yellow("skip")}    ${path.relative(process.cwd(), target)} (exists)`
+			);
+			continue;
+		}
+		mkdirSync(path.dirname(target), { recursive: true });
+		writeFileSync(target, Buffer.from(asset.content ?? "", "base64"));
+		wrote++;
+		console.log(
+			`  ${pc.green("add")}    ${path.relative(
+				process.cwd(),
+				target
+			)}${item.pro ? pc.cyan(" (pro)") : ""} (asset)`
+		);
+	}
 	writeItemFiles.lastWroteStyles =
 		writeItemFiles.lastWroteStyles || wroteStyles;
-	return wrote;
+	return { wrote, skippedExisting };
 }