@collectui/bdui 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collectui/bdui",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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,11 +146,20 @@ 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)"
+				)
+			);
+		}
 	}
 	// Next 项目里 next/link 是一等公民,提示反而是噪音(盲测 #10)
 	if (nextImports.size && !project.deps?.next) {

package/src/hints.js

@@ -0,0 +1,23 @@
+// 条目提示(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
+	// Cache Components 下,这类组件参与 prerender 时可能炸 build(是否炸取
+	// 决于该组件是否在预渲染路径渲染——实测未渲染于预渲染页时不炸)
+	if (/\bnew Date\(\)|\.toDate\(/.test(src)) {
+		hints.push(
+			"Note: this item reads the current time while rendering (per current registry source). Under Next.js Cache Components it can fail `next build` prerendering when it renders during prerender — wrap in <Suspense> if that happens (or preemptively)."
+		);
+	}
+	return hints;
+}

package/src/init.js

@@ -1,6 +1,7 @@
 // `bdui init` — 对齐 boardui init:装 foundations(cx/theme/typography/globals)
 // + agent 规则(AGENTS.md + .cursor/rules),内容全部来自 registry(与官方同源)
 
+import { execSync } from "child_process";
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
 import ora from "ora";
 import path from "path";
@@ -32,21 +33,27 @@ function frameworkSetup(project, cwd) {
 		// Next.js:官方模板自带 @/ alias 与 @types/node;仅补缺失的 tailwind 管道。
 		// postcss 配置是硬前提:模板没带 Tailwind 时 postcss.config 不存在,
 		// @tailwindcss/postcss 装了也不接管,组件样式静默失效(next build 只给
-		// "Unknown at rule: @apply" 警告仍报成功)——缺配置就补 v4 标准形态
-		if (!has("@tailwindcss/postcss")) pkgs.push("@tailwindcss/postcss");
-		const hasPostcssCfg = [
-			"postcss.config.mjs",
-			"postcss.config.js",
-			"postcss.config.cjs",
-			"postcss.config.ts",
-		].some((f) => existsSync(path.join(cwd, f)));
+		// "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 (!hasPostcssCfg)
-			writes.push({
-				file: "postcss.config.mjs",
-				content:
-					'const config = {\n  plugins: { "@tailwindcss/postcss": {} },\n};\n\nexport default config;\n',
-			});
+		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 = [
@@ -85,9 +92,9 @@ export async function cmdInit(flags) {
 		throw new Error("No package.json found — run inside your app project.");
 
 	// alias 不在此行展示:tsconfig 的 @/ 别名与实际落位(components/base/<group>)
-	// 口径不同,曾让客户误读(2026-10-26 盲测 #6);落位在 ✓ 行明示
+	// 口径不同,曾让客户误读(盲测 #6);落位在 ✓ 行明示。src= 是内部术语,给人话(r2 P10)
 	console.log(
-		`${c.cyan("init")}   detected ${project.packageManager}, src=${project.usesSrcDir}`
+		`${c.cyan("init")}   detected ${project.packageManager}, source root: ${project.usesSrcDir ? "src/" : "project root"}`
 	);
 
 	// npm 依赖:foundation 用到的 + 可选 pro 依赖(官方 --pro 同款集)+ 框架适配
@@ -113,7 +120,7 @@ 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)
@@ -139,9 +146,23 @@ export async function cmdInit(flags) {
 				`  ${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 {}
 	}
 
-	// 样式入口自动接线:根布局存在且未引入时补 import,免手动 Note(盲测 #7)
+	// 样式入口接线:优先「替换」模板旧 globals 导入而非并排追加——两份
+	// @import \"tailwindcss\" = Tailwind 双编译(~75KB 冗余 CSS)+旧 body Arial
+	// 覆盖 BoardUI 排版(盲测 r2 P3);旧文件非 Tailwind 入口才走追加(盲测 #7)
 	const layoutFile = [
 		"app/layout.tsx",
 		"app/layout.ts",
@@ -151,23 +172,101 @@ export async function cmdInit(flags) {
 		.map((f) => path.join(project.sourceRoot, f))
 		.find((p) => existsSync(p));
 	let stylesWired = false;
+	let fontsHint = "";
 	if (layoutFile) {
-		const src = readFileSync(layoutFile, "utf8");
-		if (src.includes("@/styles/globals.css")) {
-			stylesWired = true;
-		} else {
-			const lines = src.split("\n");
-			// 插到最后一个顶层 import 之后;没有 import 则插到文件头
+		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 oldContent = existsSync(oldGlobals)
+				? readFileSync(oldGlobals, "utf8")
+				: "";
+			// 接管条件(r3 🔴 实测:no-tailwind CNA 的 body Arial 直接声明压过
+			// html 继承的 --font-inter,只追加不接管=全站 Arial):旧 globals 是
+			// Tailwind 入口或 CNA 默认存量(--background/--foreground 签名,含
+			// tailwind/no-tailwind 两形态)即替换;不像模板的自定义文件才追加
+			const oldIsTw = oldContent.includes('@import "tailwindcss"');
+			const oldIsCnaStock =
+				oldContent.includes("--background") &&
+				oldContent.includes("--foreground");
+			if (oldIdx !== -1 && (oldIsTw || oldIsCnaStock)) {
+				lines[oldIdx] = 'import "@/styles/globals.css";';
+				console.log(
+					`  ${c.green("add")}    ${rel}: replaced "./globals.css" → "@/styles/globals.css" (old file was a stock scaffold stylesheet whose body rules would override BoardUI; merge any custom styles into BoardUI's)`
+				);
+			} 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")) {
+			// 清理模板残留的 Geist 字体(注入 Inter 后纯属浪费带宽,r3 伴随问题)
+			const geistImport =
+				'import { Geist, Geist_Mono } from "next/font/google";';
+			if (content.includes(geistImport) && content.includes("geistSans")) {
+				content = content
+					.replace(geistImport + "\n", "")
+					.replace(/const geistSans = Geist\(\{[\s\S]*?\}\);?\n+/, "")
+					.replace(/const geistMono = Geist_Mono\(\{[\s\S]*?\}\);?\n+/, "")
+					.replace(/\$\{geistSans\.variable\}\s*/g, "")
+					.replace(/\$\{geistMono\.variable\}\s*/g, "");
+				console.log(
+					`  ${c.green("add")}    ${rel}: removed leftover Geist fonts (Inter takes over)`
+				);
+			}
+			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 "@/styles/globals.css";');
-			writeFileSync(layoutFile, lines.join("\n"));
-			stylesWired = true;
+			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")}    ${path.relative(cwd, layoutFile)}: import "@/styles/globals.css"`
+				`  ${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)
@@ -190,13 +289,18 @@ export async function cmdInit(flags) {
 			throw e;
 		}
 	}
+	// relative 同目录返回 ""/拼接句号曾显示成 "written to .."(盲测 r2 P10)
+	const dest = path.relative(cwd, outRoot);
 	console.log(
 		c.green(
-			`\n✓ ${wrote} foundation file(s) written to ${path.relative(cwd, outRoot) || "."}.`
+			`\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(
 		stylesWired
 			? `  ${c.dim('Note: BoardUI styles wired into your root layout (import "@/styles/globals.css").')}`

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");
 		}
 

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 };
 }