@tu-design/cli 0.5.6 → 0.5.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -25,6 +25,12 @@ const nodeNpmChannel = {
25
25
  return JSON.parse(readFileSync(npmItemPath(name), "utf8"));
26
26
  }
27
27
  };
28
+ /**
29
+ * 定位 npm 通道的组件 registry item 文件:依赖包内 dist/registry/vue/<name>.json,
30
+ * 经包自身的 package.json resolve 定位,天然兼容 pnpm 等非扁平 node_modules 布局。
31
+ * @param name - 组件名
32
+ * @returns registry item JSON 的绝对路径
33
+ */
28
34
  function npmItemPath(name) {
29
35
  const pkgJson = createRequire(import.meta.url).resolve("@tu-design/vue/package.json");
30
36
  return join(dirname(pkgJson), "dist/registry/vue", `${name}.json`);
@@ -34,6 +40,9 @@ function npmItemPath(name) {
34
40
  /**
35
41
  * 统一 JSON 解析报错:裸 SyntaxError 不含文件名,用户无从下手;这里补上来源。
36
42
  * label 用面向用户的文件名(如 `components.json`),而不是绝对路径。
43
+ * @param text - 待解析的 JSON 文本
44
+ * @param label - 报错时展示的来源文件名
45
+ * @returns 解析结果(unknown,由调用方校验收窄)
37
46
  */
38
47
  function parseJson(text, label) {
39
48
  try {
@@ -54,6 +63,12 @@ const ALIAS_KEYS = [
54
63
  "ui",
55
64
  "lib"
56
65
  ];
66
+ /**
67
+ * 校验 components.json 结构:framework 必须为 "vue",registry、aliases 四键、
68
+ * tailwind.css 必须为字符串;缺失或非法字段一次性汇总报错,避免用户逐次修。
69
+ * @param raw - JSON 反序列化结果(任意形态)
70
+ * @returns 校验通过的项目配置
71
+ */
57
72
  function validateConfig(raw) {
58
73
  if (typeof raw !== "object" || raw === null) throw new Error(`${CONFIG_FILE} 内容不是 JSON 对象`);
59
74
  const obj = raw;
@@ -70,6 +85,11 @@ function validateConfig(raw) {
70
85
  if (missing.length > 0) throw new Error(`${CONFIG_FILE} 缺少或非法字段:${missing.join("、")}`);
71
86
  return raw;
72
87
  }
88
+ /**
89
+ * 生成 init 写入的默认配置:别名指向约定的 src 布局,tailwind.css 用常见默认路径。
90
+ * @param registry - 用户经 --registry 指定(或默认)的 registry URL
91
+ * @returns 默认 ComponentsConfig
92
+ */
73
93
  function defaultConfig(registry) {
74
94
  return {
75
95
  framework: "vue",
@@ -83,14 +103,31 @@ function defaultConfig(registry) {
83
103
  tailwind: { css: "src/assets/main.css" }
84
104
  };
85
105
  }
106
+ /**
107
+ * 拼接项目根下 components.json 的完整路径。
108
+ * @param cwd - 项目根目录
109
+ * @returns 配置文件路径
110
+ */
86
111
  function configPath(cwd) {
87
112
  return `${cwd}/${CONFIG_FILE}`;
88
113
  }
114
+ /**
115
+ * 读取并校验项目配置;文件缺失时抛错提示先运行 init。
116
+ * @param io - IO 通道
117
+ * @param cwd - 项目根目录
118
+ * @returns 校验通过的 ComponentsConfig
119
+ */
89
120
  function loadConfig(io, cwd) {
90
121
  const path = configPath(cwd);
91
122
  if (!io.exists(path)) throw new Error(`未找到 ${CONFIG_FILE},请先运行 \`tu-design init\``);
92
123
  return validateConfig(parseJson(io.readFile(path), CONFIG_FILE));
93
124
  }
125
+ /**
126
+ * 将配置以两空格缩进 JSON 写入 components.json,末尾补换行。
127
+ * @param io - IO 通道
128
+ * @param cwd - 项目根目录
129
+ * @param config - 要写入的项目配置
130
+ */
94
131
  function saveConfig(io, cwd, config) {
95
132
  io.writeFile(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`);
96
133
  }
@@ -128,12 +165,15 @@ const AGENTS_MD_SOURCE = `# tu-design AI 协作规则
128
165
  //#endregion
129
166
  //#region src/lib/generated-sources.ts
130
167
  const TOKENS_CSS_SOURCE = "/* tu-design 官方 tokens —— Tailwind CSS v4 主题(shadcn v4 集合扩展)。\n *\n * 主题桥接:语义色优先消费应用级 --app-* CSS 变量(应用主题系统写入),\n * 未定义时回落官方 oklch 值 —— 无主题系统的项目观感与上游一致,零破坏。\n * 契约(--app-* 全集见各项目主题包,如 @repo/themes):\n * - --app-bg-page/surface/raised/hover → --background/--card/--popover/--muted/--accent\n * - --app-text-1/2/3 → --foreground 及各 *-foreground/--muted-foreground\n * (text-3 上游零消费,供应用侧直接使用)\n * - --app-accent/-contrast → --primary(+foreground)/--ring\n * - --app-border → --border/--input(dark 模式建议低不透明度值,如 #FFFFFF1A,对齐上游风格)\n * - --secondary/-foreground 有意不桥接(上游定位即中性灰)\n * - --app-destructive/success/warning/info → 状态色三件套:实色、-soft 浅底(未定义回落\n * color-mix 派生)、-foreground 前景(深色实色场景如 dark destructive 白字对比 borderline,\n * 建议应用侧显式定义覆盖)\n * - .dark 块同样桥接,兜底为官方暗色 oklch;--*-soft 在 .dark 内重复声明:\n * 自定义属性按声明处求值后继承,不在 .dark 重声明将无法响应暗色的实色变化。\n */\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:where(.dark, .dark *));\n\n:root {\n --background: var(--app-bg-page, oklch(1 0 0));\n --foreground: var(--app-text-1, oklch(0.145 0 0));\n --card: var(--app-bg-raised, oklch(1 0 0));\n --card-foreground: var(--app-text-1, oklch(0.145 0 0));\n --popover: var(--app-bg-raised, oklch(1 0 0));\n --popover-foreground: var(--app-text-1, oklch(0.145 0 0));\n --primary: var(--app-accent, oklch(0.205 0 0));\n --primary-foreground: var(--app-accent-contrast, oklch(0.985 0 0));\n --secondary: oklch(0.97 0 0);\n --secondary-foreground: oklch(0.205 0 0);\n --muted: var(--app-bg-surface, oklch(0.97 0 0));\n --muted-foreground: var(--app-text-2, oklch(0.556 0 0));\n --accent: var(--app-bg-hover, oklch(0.97 0 0));\n --accent-foreground: var(--app-text-1, oklch(0.205 0 0));\n --destructive: var(--app-destructive, oklch(0.577 0.245 27.325));\n --destructive-soft: var(\n --app-destructive-soft,\n color-mix(in oklab, var(--destructive) 10%, transparent)\n );\n --destructive-foreground: var(--app-destructive-foreground, oklch(0.985 0 0));\n --success: var(--app-success, oklch(0.596 0.145 163.225));\n --success-soft: var(--app-success-soft, color-mix(in oklab, var(--success) 10%, transparent));\n --success-foreground: var(--app-success-foreground, oklch(0.985 0 0));\n --warning: var(--app-warning, oklch(0.666 0.179 58.318));\n --warning-soft: var(--app-warning-soft, color-mix(in oklab, var(--warning) 12%, transparent));\n --warning-foreground: var(--app-warning-foreground, oklch(0.985 0 0));\n --info: var(--app-info, oklch(0.546 0.245 262.881));\n --info-soft: var(--app-info-soft, color-mix(in oklab, var(--info) 12%, transparent));\n --info-foreground: var(--app-info-foreground, oklch(0.985 0 0));\n --border: var(--app-border, oklch(0.922 0 0));\n --input: var(--app-border, oklch(0.922 0 0));\n --ring: var(--app-accent, oklch(0.708 0 0));\n --radius: 0.625rem;\n /* 层叠序:表体 sticky < 表头普通列 sticky(fill/virtual 表头钉住,z-20 由 TableRender theadThClass 提供)\n < 表头 sticky < 浮层/弹窗(同级浮层按 DOM 挂载次序叠放;表头 fixed 列经 stickyStyle inline style 消费 --z-sticky-head) */\n --z-sticky: 10;\n --z-sticky-head: 30;\n --z-overlay: 50;\n}\n\n.dark {\n --background: var(--app-bg-page, oklch(0.145 0 0));\n --foreground: var(--app-text-1, oklch(0.985 0 0));\n --card: var(--app-bg-raised, oklch(0.205 0 0));\n --card-foreground: var(--app-text-1, oklch(0.985 0 0));\n --popover: var(--app-bg-raised, oklch(0.269 0 0));\n --popover-foreground: var(--app-text-1, oklch(0.985 0 0));\n --primary: var(--app-accent, oklch(0.922 0 0));\n --primary-foreground: var(--app-accent-contrast, oklch(0.205 0 0));\n --secondary: oklch(0.269 0 0);\n --secondary-foreground: oklch(0.985 0 0);\n --muted: var(--app-bg-surface, oklch(0.269 0 0));\n --muted-foreground: var(--app-text-2, oklch(0.708 0 0));\n --accent: var(--app-bg-hover, oklch(0.371 0 0));\n --accent-foreground: var(--app-text-1, oklch(0.985 0 0));\n --destructive: var(--app-destructive, oklch(0.704 0.191 22.216));\n --destructive-soft: var(\n --app-destructive-soft,\n color-mix(in oklab, var(--destructive) 10%, transparent)\n );\n --destructive-foreground: var(--app-destructive-foreground, oklch(0.985 0 0));\n --success: var(--app-success, oklch(0.696 0.17 162.48));\n --success-soft: var(--app-success-soft, color-mix(in oklab, var(--success) 10%, transparent));\n --success-foreground: var(--app-success-foreground, oklch(0.985 0 0));\n --warning: var(--app-warning, oklch(0.769 0.188 70.08));\n --warning-soft: var(--app-warning-soft, color-mix(in oklab, var(--warning) 12%, transparent));\n --warning-foreground: var(--app-warning-foreground, oklch(0.205 0 0));\n --info: var(--app-info, oklch(0.623 0.214 259.815));\n --info-soft: var(--app-info-soft, color-mix(in oklab, var(--info) 12%, transparent));\n --info-foreground: var(--app-info-foreground, oklch(0.985 0 0));\n --border: var(--app-border, oklch(1 0 0 / 10%));\n --input: var(--app-border, oklch(1 0 0 / 15%));\n --ring: var(--app-accent, oklch(0.556 0 0));\n}\n\n@theme inline {\n --radius-sm: calc(var(--radius) - 4px);\n --radius-md: calc(var(--radius) - 2px);\n --radius-lg: var(--radius);\n --radius-xl: calc(var(--radius) + 4px);\n --radius-2xl: calc(var(--radius) + 6px);\n --color-background: var(--background);\n --color-foreground: var(--foreground);\n --color-card: var(--card);\n --color-card-foreground: var(--card-foreground);\n --color-popover: var(--popover);\n --color-popover-foreground: var(--popover-foreground);\n --color-primary: var(--primary);\n --color-primary-foreground: var(--primary-foreground);\n --color-secondary: var(--secondary);\n --color-secondary-foreground: var(--secondary-foreground);\n --color-muted: var(--muted);\n --color-muted-foreground: var(--muted-foreground);\n --color-accent: var(--accent);\n --color-accent-foreground: var(--accent-foreground);\n --color-destructive: var(--destructive);\n --color-destructive-soft: var(--destructive-soft);\n --color-destructive-foreground: var(--destructive-foreground);\n --color-success: var(--success);\n --color-success-foreground: var(--success-foreground);\n --color-success-soft: var(--success-soft);\n --color-warning: var(--warning);\n --color-warning-foreground: var(--warning-foreground);\n --color-warning-soft: var(--warning-soft);\n --color-info: var(--info);\n --color-info-foreground: var(--info-foreground);\n --color-info-soft: var(--info-soft);\n --color-border: var(--border);\n --color-input: var(--input);\n --color-ring: var(--ring);\n}\n\n/* 全局边框色兜底,对齐 shadcn v4 官方 tokens(上游另含 outline-ring/50,此处仅移植 border):\n 裸 border 类不再回退 currentColor,而是使用 --border token。 */\n@layer base {\n * {\n border-color: var(--color-border);\n }\n}\n";
131
- const CN_UTIL_SOURCE = "import { clsx, type ClassValue } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\nexport function cn(...inputs: ClassValue[]) {\n return twMerge(clsx(inputs));\n}\n";
168
+ const CN_UTIL_SOURCE = "import { clsx, type ClassValue } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * 合并 Tailwind CSS 类名:clsx 组合条件类名,tailwind-merge 消解冲突规则。\n * @param inputs - 任意数量的类名值(字符串、数组或对象)\n * @returns 消解冲突后的类名字符串\n */\nexport function cn(...inputs: ClassValue[]) {\n return twMerge(clsx(inputs));\n}\n";
132
169
  //#endregion
133
170
  //#region src/lib/alias.ts
134
171
  /**
135
172
  * 将 paths 合并进 tsconfig 文本。优先 JSON round-trip;
136
173
  * JSONC(带注释等无法解析)时回退纯文本插入,保留原注释。
174
+ * @param source - tsconfig 文件原始文本
175
+ * @param paths - 要合并的 compilerOptions.paths 映射
176
+ * @returns 合并后的 tsconfig 文本
137
177
  */
138
178
  function mergeTsconfigPaths(source, paths) {
139
179
  let parsed;
@@ -153,8 +193,11 @@ function mergeTsconfigPaths(source, paths) {
153
193
  return `${JSON.stringify(root, null, 2)}\n`;
154
194
  }
155
195
  /**
156
- * JSONC 回退:在 "compilerOptions": { 后做纯文本插入,保留注释;
196
+ * JSONC 回退:在 "compilerOptions" 对象的开括号后做纯文本插入,保留注释;
157
197
  * 已有 paths 或结构不识别时返回原文(调用方提示手动配置)。
198
+ * @param source - tsconfig 文件原始文本
199
+ * @param paths - 要插入的 compilerOptions.paths 映射
200
+ * @returns 插入后的文本;无法安全插入时为原文
158
201
  */
159
202
  function insertPathsText(source, paths) {
160
203
  if (/"paths"\s*:/.test(source)) return source;
@@ -168,8 +211,11 @@ function insertPathsText(source, paths) {
168
211
  * 将 alias 注入 vite 配置文本(纯字符串变换,无 AST):
169
212
  * - 已有 alias 对象 → 在对象首行后追加键
170
213
  * - 有 resolve 无 alias → 在 resolve 块内补 alias
171
- * - 都没有 → 在 defineConfig({ 后插入 resolve 块
214
+ * - 都没有 → 在 defineConfig 的配置对象开头插入 resolve 块
172
215
  * - 无 defineConfig / 结构不识别 → 返回原文(调用方打印手动指引)
216
+ * @param source - vite.config.ts 原始文本
217
+ * @param alias - 要注入的 alias 键值(find → replacement)
218
+ * @returns 注入后的配置文本
173
219
  */
174
220
  function mergeViteAlias(source, alias) {
175
221
  if (!source.includes("defineConfig(")) return source;
@@ -190,6 +236,14 @@ function mergeViteAlias(source, alias) {
190
236
  const block = `\n resolve: {\n alias: {\n${entry} },\n },`;
191
237
  return `${source.slice(0, insertAt)}${block}${source.slice(insertAt)}`;
192
238
  }
239
+ /**
240
+ * 为项目配置 `@/` 路径别名(init 收尾步骤):依次改写 tsconfig.json / tsconfig.app.json
241
+ * 的 compilerOptions.paths 与 vite.config.ts 的 resolve.alias。文件不存在则跳过,
242
+ * 结构不识别时保持原文。
243
+ * @param io - IO 通道
244
+ * @param cwd - 项目根目录
245
+ * @param aliasRoot - 别名指向的源码根目录(相对项目根)
246
+ */
193
247
  function applyAliases(io, cwd, aliasRoot) {
194
248
  const paths = { "@/*": [`./${aliasRoot}/*`] };
195
249
  for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
@@ -217,6 +271,13 @@ const RUNTIME_DEPS = [
217
271
  "class-variance-authority",
218
272
  "tw-animate-css"
219
273
  ];
274
+ /**
275
+ * 判定项目是否满足 Tailwind CSS v4 前置条件:依赖中存在 tailwindcss 4.x 版本声明
276
+ * (容忍 ~ 前缀等写法),且全局 CSS 已引入 tailwindcss。二者缺一即 false。
277
+ * @param pkg - package.json 反序列化结果(取 dependencies 与 devDependencies)
278
+ * @param globalCss - 全局 CSS 文件内容
279
+ * @returns 满足 v4 前置条件返回 true
280
+ */
220
281
  function detectTailwindV4(pkg, globalCss) {
221
282
  const tw = {
222
283
  ...pkg.dependencies,
@@ -225,6 +286,13 @@ function detectTailwindV4(pkg, globalCss) {
225
286
  if (!tw || !/^[~^]?4\./.test(tw)) return false;
226
287
  return globalCss.includes("@import \"tailwindcss\"");
227
288
  }
289
+ /**
290
+ * 将 tokens 合并进用户全局 CSS:已含 dark variant 定制视为用户自管,原样返回;
291
+ * 否则在 `import "tailwindcss";` 语句之后插入 tokens(无该语句则追加到文件尾部)。
292
+ * @param userCss - 用户全局 CSS 内容
293
+ * @param tokensCss - tokens CSS 内容
294
+ * @returns 合并后的 CSS 内容;无需合并时为原文
295
+ */
228
296
  function mergeTokensCss(userCss, tokensCss) {
229
297
  if (userCss.includes("@custom-variant dark")) return userCss;
230
298
  const idx = userCss.indexOf("@import \"tailwindcss\";");
@@ -232,6 +300,11 @@ function mergeTokensCss(userCss, tokensCss) {
232
300
  const end = idx + 22;
233
301
  return `${userCss.slice(0, end)}\n${tokensCss}${userCss.slice(end)}`;
234
302
  }
303
+ /**
304
+ * 以 POSIX 分隔符拼接路径片段:首段去尾斜杠、其余段去两端斜杠,空段剔除。
305
+ * @param parts - 路径片段(依次为从根到叶)
306
+ * @returns 拼接后的 POSIX 路径
307
+ */
235
308
  function joinPosix(...parts) {
236
309
  return parts.map((p, i) => i === 0 ? p.replace(/\/+$/, "") : p.replace(/^\/+|\/+$/g, "")).filter((p) => p.length > 0).join("/");
237
310
  }
@@ -244,6 +317,14 @@ const CSS_PROBE = [
244
317
  "src/App.css",
245
318
  "style.css"
246
319
  ];
320
+ /**
321
+ * 探测实际生效的全局 CSS 路径:优先配置(或默认)路径,依次尝试常见位置,
322
+ * 取第一个存在且含 tailwindcss 引入语句的文件;全部未命中则回退配置值。
323
+ * @param io - IO 通道
324
+ * @param cwd - 项目根目录
325
+ * @param configured - 配置的 CSS 相对路径(--css 或默认值)
326
+ * @returns 实际生效的 CSS 相对路径
327
+ */
247
328
  function probeCssPath(io, cwd, configured) {
248
329
  for (const rel of [configured, ...CSS_PROBE]) {
249
330
  const full = joinPosix(cwd, rel);
@@ -251,6 +332,15 @@ function probeCssPath(io, cwd, configured) {
251
332
  }
252
333
  return configured;
253
334
  }
335
+ /**
336
+ * 运行 init 命令:校验 Tailwind v4 环境 → 写/验 components.json → 注入 cn 工具与
337
+ * tokens CSS → 按需写入 AGENTS.md → 配置路径别名。components.json 已存在时只校验不覆盖;
338
+ * AGENTS.md 已存在或显式关闭时跳过(不覆盖用户自定义内容)。
339
+ * @param io - IO 通道
340
+ * @param cwd - 项目根目录
341
+ * @param opts - init 选项(registry 地址、alias 根目录、CSS 路径、AGENTS.md 开关)
342
+ * @returns 写入路径与跳过情况的摘要
343
+ */
254
344
  function runInit(io, cwd, opts) {
255
345
  const aliasRoot = opts.aliasRoot ?? "src";
256
346
  const config = defaultConfig(opts.registry);
@@ -295,11 +385,18 @@ const ITEM_TYPES = [
295
385
  * override(--registry)优先于 components.json。
296
386
  * 去掉尾部 `/`:拼接处是 `${url}/${name}.json`,用户从浏览器地址栏复制带斜杠的 URL
297
387
  * 会拼出 `//button.json`,不少静态托管据此 404。
388
+ * @param config - 项目 components.json 配置(registry 字段为默认通道)
389
+ * @param override - 命令行 --registry 显式覆盖的 URL(缺省用 config.registry)
390
+ * @returns 去掉尾部斜杠后的 registry 基础 URL
298
391
  */
299
392
  function resolveRegistryUrl(config, override) {
300
393
  return (override ?? config.registry).replace(/\/+$/, "");
301
394
  }
302
- /** registry item 最小结构校验(name/type/files),files 逐文件校验形态。 */
395
+ /**
396
+ * registry item 最小结构校验(name/type/files),files 逐文件校验形态。
397
+ * @param raw - registry item JSON 反序列化结果(任意形态)
398
+ * @returns 校验通过并收窄类型后的 RegistryItem
399
+ */
303
400
  function validateRegistryItem(raw) {
304
401
  if (typeof raw !== "object" || raw === null) throw new Error("registry item 不是 JSON 对象");
305
402
  const obj = raw;
@@ -313,6 +410,11 @@ function validateRegistryItem(raw) {
313
410
  if (obj.version !== void 0 && typeof obj.version !== "string") throw new Error(`registry item ${String(obj.name)} 的 version 字段必须是字符串,得到 ${obj.version === null ? "null" : typeof obj.version}`);
314
411
  return raw;
315
412
  }
413
+ /**
414
+ * 提取任意抛出值的可读信息:Error 取 message,其余值字符串化。
415
+ * @param error - catch 捕获的任意值
416
+ * @returns 错误消息文本
417
+ */
316
418
  function reasonOf(error) {
317
419
  return error instanceof Error ? error.message : String(error);
318
420
  }
@@ -320,6 +422,11 @@ function reasonOf(error) {
320
422
  * 双通道解析:URL 优先(fetch `${registryUrl}/${name}.json`),
321
423
  * 失败 / 404 / 校验不过时回退 npm 通道;双失败抛错含组件名与 URL 通道的真实原因
322
424
  * (吞掉原因会让用户去查 npm,问题其实出在 registry 网络或 JSON 损坏)。
425
+ * @param fetcher - URL 通道实现(HTTP 拉取 JSON)
426
+ * @param registryUrl - registry 基础 URL(已去尾斜杠)
427
+ * @param npm - npm 通道(读取本地依赖包内 registry 数据)
428
+ * @param name - 组件名
429
+ * @returns 校验通过的组件 registry item
323
430
  */
324
431
  async function fetchItem(fetcher, registryUrl, npm, name) {
325
432
  const url = `${registryUrl}/${name}.json`;
@@ -340,13 +447,22 @@ const PM_NAMES = [
340
447
  "yarn",
341
448
  "bun"
342
449
  ];
343
- /** agent 形如 "pnpm@9.15.0";未知/缺失返回 null,由调用方决定降级方式。 */
450
+ /**
451
+ * agent 形如 "pnpm@9.15.0";未知/缺失返回 null,由调用方决定降级方式。
452
+ * @param agent - npm_config_user_agent 环境变量的原始值
453
+ * @returns 识别出的包管理器名;缺失或不认识时为 null
454
+ */
344
455
  function parsePackageManager(agent) {
345
456
  if (!agent) return null;
346
457
  const name = agent.split("@")[0] ?? agent;
347
458
  return PM_NAMES.includes(name) ? name : null;
348
459
  }
349
- /** 由 cwd 锁文件推断包管理器(纯 IO 路径,可在 memIo 下测试)。 */
460
+ /**
461
+ * 由 cwd 锁文件推断包管理器(纯 IO 路径,可在 memIo 下测试)。
462
+ * @param io - IO 通道(探测锁文件是否存在)
463
+ * @param cwd - 项目目录
464
+ * @returns 按锁文件优先级(pnpm → yarn → bun)判定的包管理器,均无则 npm
465
+ */
350
466
  function detectPackageManagerFromLockfiles(io, cwd) {
351
467
  if (io.exists(`${cwd}/pnpm-lock.yaml`)) return "pnpm";
352
468
  if (io.exists(`${cwd}/yarn.lock`)) return "yarn";
@@ -357,6 +473,9 @@ function detectPackageManagerFromLockfiles(io, cwd) {
357
473
  * 项目包管理器的唯一判定口径(init 与 add 共用,避免两条命令对同一项目给出不同答案):
358
474
  * `packageManager` 字段(Corepack 声明的意图)优先,其次锁文件(实际使用证据),最后 npm。
359
475
  * package.json 缺失或不可解析时静默降级——报错是 init 自己的前置校验职责。
476
+ * @param io - IO 通道(读 package.json 与探测锁文件)
477
+ * @param cwd - 项目目录
478
+ * @returns 判定出的包管理器
360
479
  */
361
480
  function detectPackageManagerForProject(io, cwd) {
362
481
  const pkgPath = `${cwd}/package.json`;
@@ -367,6 +486,13 @@ function detectPackageManagerForProject(io, cwd) {
367
486
  } catch {}
368
487
  return detectPackageManagerFromLockfiles(io, cwd);
369
488
  }
489
+ /**
490
+ * 组装依赖安装命令 argv:各包管理器的子命令与 dev 标志存在差异(bun 用 -d,其余 -D)。
491
+ * @param pm - 目标包管理器
492
+ * @param deps - 依赖 spec 列表(name 或 name@version)
493
+ * @param dev - 是否安装为开发依赖
494
+ * @returns 可直接交给子进程执行的命令参数数组
495
+ */
370
496
  function buildInstallCommand(pm, deps, dev) {
371
497
  const base = {
372
498
  pnpm: ["pnpm", "add"],
@@ -383,6 +509,15 @@ function buildInstallCommand(pm, deps, dev) {
383
509
  const cmd = [...base[pm], ...deps];
384
510
  return dev ? [...cmd, devFlag[pm]] : cmd;
385
511
  }
512
+ /**
513
+ * 在项目目录安装依赖(默认按锁文件自动探测包管理器);空依赖列表直接跳过,
514
+ * 不产生子进程。
515
+ * @param io - 含 exec 的 IO 通道
516
+ * @param cwd - 执行安装的项目目录
517
+ * @param deps - 依赖 spec 列表(name 或 name@version)
518
+ * @param dev - 是否安装为开发依赖
519
+ * @param pm - 包管理器(缺省按 cwd 锁文件推断)
520
+ */
386
521
  function installDependencies(io, cwd, deps, dev, pm = detectPackageManagerFromLockfiles(io, cwd)) {
387
522
  if (deps.length === 0) return;
388
523
  io.exec(buildInstallCommand(pm, deps, dev));
@@ -391,10 +526,19 @@ function installDependencies(io, cwd, deps, dev, pm = detectPackageManagerFromLo
391
526
  //#region src/lib/lockfile.ts
392
527
  /** 组件版本记录文件,位于项目根(components.json 旁)。 */
393
528
  const LOCKFILE_NAME = "components.lock.json";
529
+ /**
530
+ * 计算文本内容的 sha256 十六进制摘要(逐字节精确口径)。
531
+ * @param content - 文本内容
532
+ * @returns sha256 摘要(hex 字符串)
533
+ */
394
534
  function hashContent(content) {
395
535
  return createHash("sha256").update(content, "utf8").digest("hex");
396
536
  }
397
- /** 刻意不含 installedAt 之类时间戳字段:跨机器安装会产生 VCS diff 噪音。 */
537
+ /**
538
+ * 刻意不含 installedAt 之类时间戳字段:跨机器安装会产生 VCS diff 噪音。
539
+ * @param raw - lockfile JSON 反序列化结果(任意形态)
540
+ * @returns 校验并规整后的 Lockfile
541
+ */
398
542
  function validateLockfile(raw) {
399
543
  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new Error(`${LOCKFILE_NAME} 内容不是 JSON 对象`);
400
544
  const obj = raw;
@@ -424,7 +568,12 @@ function validateLockfile(raw) {
424
568
  packages: out
425
569
  };
426
570
  }
427
- /** 文件缺失 → 空 lockfile;存在但 JSON/结构非法 → throw(损坏的 lockfile 不能静默当空处理)。 */
571
+ /**
572
+ * 文件缺失 → 空 lockfile;存在但 JSON/结构非法 → throw(损坏的 lockfile 不能静默当空处理)。
573
+ * @param io - IO 通道
574
+ * @param root - 项目根目录
575
+ * @returns 当前项目的组件 lockfile(无记录时 packages 为空对象)
576
+ */
428
577
  function readLockfile(io, root) {
429
578
  const path = `${root}/${LOCKFILE_NAME}`;
430
579
  if (!io.exists(path)) return {
@@ -433,6 +582,12 @@ function readLockfile(io, root) {
433
582
  };
434
583
  return validateLockfile(parseJson(io.readFile(path), LOCKFILE_NAME));
435
584
  }
585
+ /**
586
+ * 将 lockfile 以两空格缩进 JSON 写入项目根(components.lock.json),末尾补换行。
587
+ * @param io - IO 通道
588
+ * @param root - 项目根目录
589
+ * @param lockfile - 要写入的 lockfile 数据
590
+ */
436
591
  function writeLockfile(io, root, lockfile) {
437
592
  io.writeFile(`${root}/${LOCKFILE_NAME}`, `${JSON.stringify(lockfile, null, 2)}\n`);
438
593
  }
@@ -502,12 +657,22 @@ function rewriteContent(content, filePath, aliasRoot) {
502
657
  }
503
658
  //#endregion
504
659
  //#region src/lib/write.ts
660
+ /**
661
+ * 返回目录的父目录(POSIX 路径);根目录 "/" 没有父级。
662
+ * @param dir - 目录路径
663
+ * @returns 父目录路径;已是根目录时为 null
664
+ */
505
665
  function parentDir(dir) {
506
666
  if (dir === "/") return null;
507
667
  const idx = dir.lastIndexOf("/");
508
668
  return idx <= 0 ? "/" : dir.slice(0, idx);
509
669
  }
510
- /** 自 cwd 向上找最近的 components.json;到文件系统根仍无 → 抛错提示 init。 */
670
+ /**
671
+ * 自 cwd 向上找最近的 components.json;到文件系统根仍无 → 抛错提示 init。
672
+ * @param io - IO 通道
673
+ * @param cwd - 起始目录
674
+ * @returns 命中 components.json 的项目根目录
675
+ */
511
676
  function findProjectRoot(io, cwd) {
512
677
  let dir = cwd.replace(/\\/g, "/");
513
678
  for (;;) {
@@ -524,6 +689,10 @@ function findProjectRoot(io, cwd) {
524
689
  * 绝对路径、盘符路径、或逸出 aliasRoot 的 `..` 一律拒绝,否则一个恶意/损坏的
525
690
  * registry 项能把源码写到项目外(`~/.bashrc`、`/etc/…`)。
526
691
  * 逐段归一后仍留在 aliasRoot 内的 `..`(如 `components/ui/../../x.ts`)允许。
692
+ * @param target - registry item 声明的目标相对路径
693
+ * @param config - 项目配置(预留 alias 语义扩展位)
694
+ * @param aliasRoot - 组件源码落点根目录
695
+ * @returns 拼接 aliasRoot 后的安全路径
527
696
  */
528
697
  function resolveTarget(target, config, aliasRoot) {
529
698
  const root = aliasRoot.replace(/\\/g, "/").replace(/\/+$/, "");
@@ -542,6 +711,15 @@ function resolveTarget(target, config, aliasRoot) {
542
711
  if (segs.length === 0) throw new Error(`registry target 解析后为空:${target}`);
543
712
  return `${root}/${segs.join("/")}`;
544
713
  }
714
+ /**
715
+ * 将 registry item 列表展开为逐文件写入计划(路径解析 + 已存在标记);
716
+ * 单个文件 target 非法时报错点名所属 registry 项与文件,便于定位数据源。
717
+ * @param items - 拓扑排序后的 registry item 列表
718
+ * @param io - IO 通道(探测目标文件是否已存在)
719
+ * @param aliasRoot - 组件源码落点根目录
720
+ * @param config - 项目配置
721
+ * @returns 逐文件写入计划
722
+ */
545
723
  function planWrites(items, io, aliasRoot, config) {
546
724
  const plans = [];
547
725
  for (const item of items) for (const file of item.files) {
@@ -563,6 +741,10 @@ function planWrites(items, io, aliasRoot, config) {
563
741
  * 覆盖安全语义:归一化内容比对(sha256,空白不敏感)优先于存在性判断——
564
742
  * 内容相同的重复安装不算冲突,静默跳过;只有「存在且归一化内容不同」才进入
565
743
  * 覆盖询问 / conflict 分支。空白不敏感:用户 fmt 重排不触发覆盖询问。
744
+ * @param plans - 写入计划列表
745
+ * @param io - IO 通道
746
+ * @param opts - 覆盖策略(overwrite 直接覆盖;confirm 逐文件询问用户)
747
+ * @returns 各类文件处置结果的清单
566
748
  */
567
749
  async function writeFiles(plans, io, opts) {
568
750
  const result = {
@@ -602,6 +784,13 @@ async function writeFiles(plans, io, opts) {
602
784
  }
603
785
  //#endregion
604
786
  //#region src/lib/add-core.ts
787
+ /**
788
+ * 按依赖拓扑序展开 registry item:registryDependencies 先于自身解析,已解析项去重,
789
+ * 循环引用抛错并给出完整环路。
790
+ * @param names - 入口组件名列表
791
+ * @param fetchOne - 单组件拉取函数(调用方注入 URL/npm 双通道实现)
792
+ * @returns 拓扑序(依赖在前)的 registry item 列表
793
+ */
605
794
  async function resolveTopo(names, fetchOne) {
606
795
  const out = [];
607
796
  const visited = /* @__PURE__ */ new Set();
@@ -622,6 +811,12 @@ async function resolveTopo(names, fetchOne) {
622
811
  for (const name of names) await visit(name);
623
812
  return out;
624
813
  }
814
+ /**
815
+ * 汇总 item 列表的 dependencies / devDependencies:registry 数组形式为 name@version
816
+ * 完整 spec,按完整 spec 去重并保持出现顺序。
817
+ * @param items - registry item 列表
818
+ * @returns 去重后的运行时与开发依赖 spec 列表
819
+ */
625
820
  function collectDeps(items) {
626
821
  const dependencies = [];
627
822
  const devDependencies = [];
@@ -637,7 +832,11 @@ function collectDeps(items) {
637
832
  devDependencies
638
833
  };
639
834
  }
640
- /** add / diff 共用:由项目根推出组件源码落点根(aliasRoot)。 */
835
+ /**
836
+ * add / diff 共用:由项目根推出组件源码落点根(aliasRoot)。
837
+ * @param root - 项目根目录
838
+ * @returns 项目根下的默认源码根目录(src)
839
+ */
641
840
  function aliasRootOf(root) {
642
841
  return `${root}/src`;
643
842
  }
@@ -647,7 +846,7 @@ function aliasRootOf(root) {
647
846
  * @param io IO 通道(读 lockfile)
648
847
  * @param root 项目根
649
848
  * @param names 显式组件名(可为空数组)
650
- * @param opts.all 是否全量展开
849
+ * @param all 是否全量展开
651
850
  * @returns 参与组件名
652
851
  */
653
852
  function resolveNames(io, root, names, all) {
@@ -767,6 +966,14 @@ async function runAdd(io, cwd, names, opts) {
767
966
  * 3. 本地 === 上次安装 → updatable(本地干净,可安全覆盖)
768
967
  * 4. 线上 === 上次安装 → modified(远端没动,本地改的)
769
968
  * 5. 三方互不相同 → conflict
969
+ * @param io - IO 通道(读 lockfile 与本地组件文件)
970
+ * @param fetcher - URL 通道实现(HTTP 拉取 JSON)
971
+ * @param registryUrl - registry 基础 URL
972
+ * @param npm - npm 回退通道
973
+ * @param root - 项目根目录
974
+ * @param config - 项目配置(target 解析用)
975
+ * @param names - 指定比对的组件名;缺省比对 lockfile 全部记录
976
+ * @returns 逐组件的比对结果;单组件拉取失败不中断,记入 error 字段
770
977
  */
771
978
  async function diffComponents(io, fetcher, registryUrl, npm, root, config, names) {
772
979
  const lockfile = readLockfile(io, root);
@@ -816,7 +1023,11 @@ async function diffComponents(io, fetcher, registryUrl, npm, root, config, names
816
1023
  }
817
1024
  //#endregion
818
1025
  //#region src/lib/version.ts
819
- /** 从 package.json 原始文本解析版本号(纯函数,便于测试)。 */
1026
+ /**
1027
+ * 从 package.json 原始文本解析版本号(纯函数,便于测试)。
1028
+ * @param raw - package.json 文件的原始文本
1029
+ * @returns 解析出的 version 字段字符串
1030
+ */
820
1031
  function parsePkgVersion(raw) {
821
1032
  const parsed = JSON.parse(raw);
822
1033
  if (typeof parsed.version !== "string" || parsed.version.length === 0) throw new Error("package.json 缺少 version 字段");
@@ -824,7 +1035,11 @@ function parsePkgVersion(raw) {
824
1035
  }
825
1036
  //#endregion
826
1037
  //#region src/index.ts
827
- /** 唯一的子进程执行实现:init / add 都走它,失败原因由 stdio 直接透传给用户。 */
1038
+ /**
1039
+ * 唯一的子进程执行实现:init / add 都走它,失败原因由 stdio 直接透传给用户。
1040
+ * @param cwd - 子进程工作目录(项目根)
1041
+ * @returns 执行命令数组(argv)的闭包;非零退出码时抛错
1042
+ */
828
1043
  function execIn(cwd) {
829
1044
  return (cmd) => {
830
1045
  if (spawnSync(cmd[0], cmd.slice(1), {
@@ -833,6 +1048,11 @@ function execIn(cwd) {
833
1048
  }).status !== 0) throw new Error(`命令执行失败:${cmd.join(" ")}`);
834
1049
  };
835
1050
  }
1051
+ /**
1052
+ * 组装带 exec 能力的 IO 通道:文件操作复用 nodeIo,exec 绑定到指定工作目录。
1053
+ * @param cwd - 子进程工作目录(项目根)
1054
+ * @returns 含 exec 的 IO 通道
1055
+ */
836
1056
  function makeExecIo(cwd) {
837
1057
  return {
838
1058
  ...nodeIo,
@@ -990,7 +1210,11 @@ program.command("diff [components...]").description("比对本地组件与线上
990
1210
  process.exitCode = 1;
991
1211
  }
992
1212
  });
993
- /** MCP 错误统一转 isError 结果(stdout 只承载 JSON-RPC,消息文本放 content)。 */
1213
+ /**
1214
+ * MCP 错误统一转 isError 结果(stdout 只承载 JSON-RPC,消息文本放 content)。
1215
+ * @param error - catch 捕获的任意值
1216
+ * @returns JSON-RPC 响应的 isError 内容块
1217
+ */
994
1218
  function mcpError(error) {
995
1219
  return {
996
1220
  isError: true,
@@ -1000,6 +1224,10 @@ function mcpError(error) {
1000
1224
  }]
1001
1225
  };
1002
1226
  }
1227
+ /**
1228
+ * 线上 URL 通道实现:fetch 拉取 JSON,非 2xx 抛含状态码与 URL 的错误。
1229
+ * @returns RegistryFetcher(fetchJson 拉取并解析 JSON)
1230
+ */
1003
1231
  function registryHttpFetcher() {
1004
1232
  return { async fetchJson(url) {
1005
1233
  const res = await fetch(url);
@@ -1014,7 +1242,7 @@ program.command("mcp").description("启动 MCP Server(stdio,仅查询组件
1014
1242
  import("@modelcontextprotocol/sdk/server/mcp.js"),
1015
1243
  import("@modelcontextprotocol/sdk/server/stdio.js"),
1016
1244
  import("zod"),
1017
- import("./mcp-core-Ct8Xf-FY.mjs")
1245
+ import("./mcp-core-p5-PsUz8.mjs")
1018
1246
  ]);
1019
1247
  const fetcher = registryHttpFetcher();
1020
1248
  const server = new McpServer({
@@ -2,16 +2,28 @@ import { t as validateRegistryItem } from "./index.mjs";
2
2
  //#region src/lib/mcp-core.ts
3
3
  /** 组件名只允许小写字母、数字与连字符:防路径穿越与 URL 注入。 */
4
4
  const NAME_RE = /^[a-z0-9-]+$/;
5
- /** registry URL 尾斜杠会让拼接变成 //name.json,多数静态托管据此 404。 */
5
+ /**
6
+ * registry URL 尾斜杠会让拼接变成 //name.json,多数静态托管据此 404。
7
+ * @param registryUrl - registry 基础 URL
8
+ * @returns 去掉尾部斜杠后的 URL
9
+ */
6
10
  function trimUrl(registryUrl) {
7
11
  return registryUrl.replace(/\/+$/, "");
8
12
  }
13
+ /**
14
+ * 提取任意抛出值的可读信息:Error 取 message,其余值字符串化。
15
+ * @param error - catch 捕获的任意值
16
+ * @returns 错误消息文本
17
+ */
9
18
  function reasonOf(error) {
10
19
  return error instanceof Error ? error.message : String(error);
11
20
  }
12
21
  /**
13
22
  * 拉取 registry 索引(GET `${registryUrl}/registry.json`),过滤只留 registry:ui 组件。
14
23
  * 最小形态校验:items 为数组、每项 name 为 string;错误消息中文且含 URL,便于定位数据源问题。
24
+ * @param fetcher - URL 通道实现(HTTP 拉取 JSON)
25
+ * @param registryUrl - registry 基础 URL
26
+ * @returns registry:ui 组件的精简索引项列表
15
27
  */
16
28
  async function fetchRegistryIndex(fetcher, registryUrl) {
17
29
  const url = `${trimUrl(registryUrl)}/registry.json`;
@@ -34,7 +46,13 @@ async function fetchRegistryIndex(fetcher, registryUrl) {
34
46
  description: typeof item.description === "string" ? item.description : ""
35
47
  }));
36
48
  }
37
- /** 在 name / title / description 上做大小写不敏感子串过滤(空 query 返回全部)。 */
49
+ /**
50
+ * 在 name / title / description 上做大小写不敏感子串过滤(空 query 返回全部)。
51
+ * @param fetcher - URL 通道实现(HTTP 拉取 JSON)
52
+ * @param registryUrl - registry 基础 URL
53
+ * @param query - 检索子串(大小写不敏感)
54
+ * @returns 命中的索引项列表
55
+ */
38
56
  async function searchComponents(fetcher, registryUrl, query) {
39
57
  const entries = await fetchRegistryIndex(fetcher, registryUrl);
40
58
  const q = query.toLowerCase();
@@ -45,6 +63,10 @@ async function searchComponents(fetcher, registryUrl, query) {
45
63
  * 只走线上 URL 通道并复用 validateRegistryItem 校验,不用 fetchItem 的 npm 回退——
46
64
  * MCP 是只读查询面,npm 本地回退会让查询结果取决于安装缓存,语义混乱。
47
65
  * 返回项附加 installHint,引导 AI 用 CLI 安装而不是复制源码。
66
+ * @param fetcher - URL 通道实现(HTTP 拉取 JSON)
67
+ * @param registryUrl - registry 基础 URL
68
+ * @param name - 组件名(仅小写字母、数字与连字符)
69
+ * @returns 校验通过的 registry item,附 installHint 安装提示
48
70
  */
49
71
  async function getComponent(fetcher, registryUrl, name) {
50
72
  if (!NAME_RE.test(name)) throw new Error(`非法组件名 ${name}:只允许小写字母、数字与连字符`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tu-design/cli",
3
- "version": "0.5.6",
3
+ "version": "0.5.8",
4
4
  "description": "tu-design CLI:初始化并按 registry 分发组件源码到用户项目(shadcn 模式)。",
5
5
  "keywords": [
6
6
  "cli",
@@ -35,7 +35,7 @@
35
35
  },
36
36
  "dependencies": {
37
37
  "@modelcontextprotocol/sdk": "^1.32.2",
38
- "@tu-design/vue": "0.5.6",
38
+ "@tu-design/vue": "0.5.8",
39
39
  "commander": "^15",
40
40
  "picocolors": "^1",
41
41
  "prompts": "^2",