@collectui/bdui 0.1.11 → 0.2.0

package/package.json

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

package/src/add.js

@@ -2,6 +2,7 @@
 
 import { spawn } from "child_process";
 import ora from "ora";
+import { readSavedKey, resolveKey } from "./auth.js";
 import c from "./color.js";
 import { itemHints } from "./hints.js";
 import { detectProject, installCommand } from "./project.js";
@@ -60,8 +61,8 @@ export async function cmdAdd(names, flags) {
 		return;
 	}
 
-	// 递归收集:name → item(公共 + pro),依赖闭包先装;pro 用 --key
-	const key = flags.key;
+	// 递归收集:name → item(公共 + pro),依赖闭包先装;pro 的 key 三级解析(flag/env/login 落盘)
+	const key = resolveKey(flags.key);
 	const resolved = new Map();
 	const missing = [];
 	async function collect(name) {
@@ -177,4 +178,12 @@ export async function cmdAdd(names, flags) {
 			)
 		);
 	}
+	// 显式 --key 且本机未存过:一次性引导 login(存过/已用 login 就不再唠叨)
+	if (flags.key && !readSavedKey()) {
+		console.log(
+			c.dim(
+				`\nTip: run \`bdui login --key <key>\` once — future commands won't need --key on this machine.`
+			)
+		);
+	}
 }

package/src/auth.js

@@ -0,0 +1,124 @@
+// `bdui login/logout` — license key 落盘一次,后续命令自动携带(本机级,0600,不进任何项目仓库)
+// 取 key 优先级:--key 显式 flag > BDUI_KEY env > login 落盘文件
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "fs";
+import os from "os";
+import path from "path";
+import prompts from "prompts";
+import c from "./color.js";
+import { proRegistryBaseUrl } from "./registry.js";
+
+// 验证探针:借一个必不存在的条目名打 Pro 端点。服务端路由先鉴权(requireValidKey)
+// 后查条目,所以 404 = key 已通过鉴权,无需下载任何真实条目(零开销验证)。
+const PROBE_NAME = "license-check-probe";
+
+export function licenseFile() {
+	const dir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+	return path.join(dir, "bdui", "license.json");
+}
+
+export function readSavedKey() {
+	try {
+		return JSON.parse(readFileSync(licenseFile(), "utf8")).key ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** 统一取 key:flag(显式当次指定永远赢) > env(CI) > login 落盘 */
+export function resolveKey(flagKey) {
+	return flagKey ?? process.env.BDUI_KEY ?? readSavedKey();
+}
+
+function saveKey(key) {
+	const file = licenseFile();
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(
+		file,
+		`${JSON.stringify({ key, savedAt: new Date().toISOString() }, null, 2)}\n`
+	);
+	chmodSync(file, 0o600);
+	return file;
+}
+
+// 401 = key 不存在/无效;423 = 暂停/封禁;429 = 限流;其余(5xx/网络)按"暂不可验证"处理
+async function verifyKey(key) {
+	try {
+		const res = await fetch(`${proRegistryBaseUrl()}/${PROBE_NAME}`, {
+			headers: { Authorization: `Bearer ${key}` },
+		});
+		if (res.status === 404 || res.status === 200) return { ok: true };
+		if (res.status === 401)
+			return {
+				ok: false,
+				message: "Invalid license key — check it and try again.",
+			};
+		if (res.status === 423)
+			return {
+				ok: false,
+				message:
+					"This key is suspended or banned — contact your platform or administrator.",
+			};
+		if (res.status === 429)
+			return {
+				ok: false,
+				message: "Key check rate-limited — try again in a moment.",
+			};
+		return {
+			ok: false,
+			message: `Could not verify the key (registry returned ${res.status}). Try again.`,
+		};
+	} catch {
+		return {
+			ok: false,
+			message: "Could not reach the registry to verify the key. Try again.",
+		};
+	}
+}
+
+export async function cmdLogin(flags) {
+	let key = flags.key?.trim();
+	if (!key && process.stdin.isTTY) {
+		const r = await prompts({
+			type: "password",
+			name: "key",
+			message: "BoardUI license key:",
+		});
+		key = r?.key?.trim();
+	}
+	if (!key)
+		throw new Error("No key provided — run: bdui login --key <license-key>");
+
+	const replaced = Boolean(readSavedKey());
+	console.log(`${c.cyan("login")}  verifying key…`);
+	const verdict = await verifyKey(key);
+	if (!verdict.ok) throw new Error(verdict.message);
+
+	const file = saveKey(key);
+	console.log(
+		c.green(
+			`✓ license key verified${replaced ? " (replaced the previously saved one)" : ""} and saved to ${file}`
+		)
+	);
+	console.log(
+		c.dim(
+			"  add / skill / mcp now work without --key on this machine. Remove it anytime with: bdui logout"
+		)
+	);
+}
+
+export async function cmdLogout() {
+	const file = licenseFile();
+	if (!existsSync(file)) {
+		console.log("No saved license key on this machine.");
+		return;
+	}
+	rmSync(file);
+	console.log(c.green(`✓ saved license key removed (${file})`));
+}

package/src/cli.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { readFileSync } from "fs";
 import { cmdAdd } from "./add.js";
+import { cmdLogin, cmdLogout } from "./auth.js";
 import { cmdInit } from "./init.js";
 import { cmdList } from "./list.js";
 import { cmdMcp } from "./mcp.js";
@@ -38,13 +39,26 @@ export async function run(argv) {
 		)
 		.action(cmdInit);
 
+	program
+		.command("login")
+		.description(
+			"Save your BoardUI license key once (verified, 0600, this machine only) — add/skill/mcp then work without --key."
+		)
+		.option("-k, --key <key>", "license key (prompts for it when omitted)")
+		.action(cmdLogin);
+
+	program
+		.command("logout")
+		.description("Remove the license key saved by `bdui login`.")
+		.action(cmdLogout);
+
 	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)"
+			"license key for Pro components (or run `bdui login` once to save it on this machine)"
 		)
 		.option(
 			"-p, --path <path>",
@@ -66,11 +80,11 @@ export async function run(argv) {
 	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)."
+			"Start the BoardUI MCP server (stdio) so AI agents can browse and install components. Pass --key to unlock Pro items for the whole session, or run `bdui login` once and start it without."
 		)
 		.option(
 			"-k, --key <key>",
-			"license key for Pro components, active for this server session (nothing is saved)"
+			"license key for Pro components, active for this server session (or use the key saved by `bdui login`)"
 		)
 		.action((options) => cmdMcp(options));
 
@@ -91,7 +105,7 @@ export async function run(argv) {
 		.option("-f, --force", "overwrite an existing install (how you update)")
 		.option(
 			"-k, --key <key>",
-			"license key when the skill entry is Pro (single command, nothing is saved)"
+			"license key when the skill entry is Pro (or use the key saved by `bdui login`)"
 		)
 		.action(cmdSkill);
 

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 { licenseFile, readSavedKey } from "./auth.js";
 import { itemHints } from "./hints.js";
 import { detectProject } from "./project.js";
 import { fetchIndex, fetchItem } from "./registry.js";
@@ -38,7 +39,7 @@ const SCHEMAS = {
 			.string()
 			.optional()
 			.describe(
-				"License key for Pro items; optional when the server was started with --key."
+				"License key for Pro items; optional when the server was started with --key or a key was saved via `bdui login`."
 			),
 	}),
 	get_usage_examples: z.object({
@@ -51,7 +52,7 @@ const SCHEMAS = {
 			.string()
 			.optional()
 			.describe(
-				"License key for Pro items (same as `add --key`); optional when the server was started with --key."
+				"License key for Pro items (same as `add --key`); optional when the server was started with --key or a key was saved via `bdui login`."
 			),
 		overwrite: z.boolean().optional(),
 		installDependencies: z.boolean().optional(),
@@ -118,8 +119,8 @@ function groupLabel(t) {
 	);
 }
 
-// serverKey:`bdui mcp --key <key>` 启动内嵌(.mcp.json args),整会话兜底;
-// 调用级 key 参数优先。两者都不落盘,请求结束即消失。
+// serverKey:`bdui mcp --key <key>` 启动内嵌(.mcp.json args)或 `bdui login` 落盘,
+// 整会话兜底;调用级 key 参数优先。
 async function loadItem(name, key, serverKey) {
 	return fetchItem(name, key ?? serverKey);
 }
@@ -137,10 +138,9 @@ async function dispatch(name, args, captured, serverKey) {
 				"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>].",
+				"Pro items need a license key. Recommended: save it once with `npx -y @collectui/bdui login --key <key>` — stored at ~/.config/bdui/license.json (0600, this machine only), and every later CLI command and MCP session is unlocked without passing anything.",
+				"Alternatives (nothing stored): pass `key` per call to install_components (same as the CLI's `add --key <license-key>`), or start this server with `npx -y @collectui/bdui mcp --key <key>` (embed it in the args block of your MCP config).",
+				"CLI equivalents: npx @collectui/bdui init | list | add <name> [--key <key>] | skill | mcp [--key <key>] | login | logout.",
 			].join("\n");
 
 		case "list_components": {
@@ -369,12 +369,14 @@ 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)
+	const serverKey = options.key ?? readSavedKey(); // `bdui mcp --key` 内嵌 or `bdui login` 落盘,见 loadItem 注释
+	// stderr 提示(stdio 协议,stdout 必须干净):显式 --key 常嵌 .mcp.json,防 commit 泄漏(盲测 #3)
+	if (options.key)
 		console.error(
 			"[bdui] tip: if this key is embedded in .mcp.json, keep that file out of git (add it to .gitignore)."
 		);
+	else if (serverKey)
+		console.error(`[bdui] using saved key from ${licenseFile()}`);
 	const rl = createInterface({ input: process.stdin });
 	const write = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
 

package/src/registry.js

@@ -1,7 +1,7 @@
 // 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 覆盖,本机不存任何状态。
+// Pro:   GET {BASE}/api/pro/r/<name>   Bearer <key>(resolveKey 三级解析:--key flag > BDUI_KEY env > `bdui login` 落盘;校验/缓存/熔断全在服务端)
+// 端点内置,不提供 env 覆盖。
 const BASE = "https://boardui.collectui.pro";
 
 export const registryBaseUrl = () => `${BASE}/r`;
@@ -43,7 +43,7 @@ export async function fetchItem(name, key) {
 		if (error?.status !== 404 && error?.status !== 401) throw error;
 		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.`
+				`"${name}" is a BoardUI Pro component. Run \`bdui login --key <license-key>\` once to save your key on this machine, or pass --key <license-key> to this command. The key is distributed by your platform or administrator.`
 			);
 		}
 		const response = await fetch(`${proRegistryBaseUrl()}/${name}`, {

package/src/skill.js

@@ -1,6 +1,7 @@
 // `bdui skill` — 从 registry 拉 skill 条目(SKILL.md + references)写入目标目录
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
 import path from "path";
+import { resolveKey } from "./auth.js";
 import c from "./color.js";
 import { fetchItem } from "./registry.js";
 
@@ -15,7 +16,7 @@ export async function cmdSkill(flags) {
 		target = path.join(home, ".agents", "skills", "boardui");
 	else target = path.join(process.cwd(), ".claude", "skills", "boardui");
 
-	const skill = await fetchItem("skill", flags.key);
+	const skill = await fetchItem("skill", resolveKey(flags.key));
 	if (existsSync(target) && !flags.force) {
 		throw new Error(
 			`${target} already exists — pass --force to overwrite (how you update).`

package/src/write.js

@@ -31,9 +31,15 @@ export async function writeItemFiles(item, outRoot, flags = {}) {
 	let wroteStyles = false;
 	const state = { all: false };
 	for (const file of item.files ?? []) {
+		// 空元素/空路径守卫:官方条目实发过 assets:[null] 同型数据(2026-11-06
+		// sidebar 实测 EISDIR),空 path 会让 target 落在 outRoot/public 目录本身
+		if (!file?.path) {
+			console.log(`  ${pc.yellow("skip")}    file entry without a path`);
+			continue;
+		}
 		// 路径守卫:file.path 不得逃逸 outRoot(防 ../ 遍历;信任官方 registry
 		// 前提下是纵深防御,与 shadcn 同水位再进一步)
-		const rel = path.normalize(file.path ?? "");
+		const rel = path.normalize(file.path);
 		if (rel.startsWith("..") || path.isAbsolute(rel)) {
 			console.log(`  ${pc.red("skip")}    unsafe path in item: ${file.path}`);
 			continue;
@@ -56,7 +62,13 @@ export async function writeItemFiles(item, outRoot, flags = {}) {
 	}
 	// 二进制 assets(base64):Pro 模板的头像/logo 等图片资源(盲测 r2 P1)
 	for (const asset of item.assets ?? []) {
-		const rel = path.normalize(asset.path ?? "");
+		// 空元素/空路径守卫:官方 sidebar 条目实发 assets:[null]——null 直接读 path
+		// 抛 TypeError,空 path 则 target 落在 public 目录本身 writeFileSync 抛 EISDIR
+		if (!asset?.path) {
+			console.log(`  ${pc.yellow("skip")}    asset entry without a path`);
+			continue;
+		}
+		const rel = path.normalize(asset.path);
 		if (rel.startsWith("..") || path.isAbsolute(rel)) {
 			console.log(`  ${pc.red("skip")}    unsafe path in asset: ${asset.path}`);
 			continue;