sparkdesign 0.0.1 → 0.1.10

package/README.md

@@ -1,9 +1,193 @@
 # sparkdesign
 
-> Package name reserved for future development.
+Spark Design 按需引入 CLI：将组件**源码**复制到当前项目，支持在项目内自由修改。
 
-This package is currently a placeholder. The actual implementation will be coming soon.
+**当前版本**：`0.1.6` · 设计系统主包：[sparkdesign](https://www.npmjs.com/package/sparkdesign)
 
-## Author
+---
+
+## 快速开始
+
+### 步骤 1：添加组件
+
+在项目根目录执行：
+
+```bash
+npx sparkdesign add button
+```
+
+添加多个组件时在命令后追加组件名，例如：`npx sparkdesign add button tooltip dropdown-menu`。
+
+> 输出目录由 **components.json** 的 `aliases.ui` 决定（默认 `@/components/ui` → `src/components/ui/`）。执行 add 时会在终端打印当前配置与目标目录，修改 `components.json` 后再次 add 即可生效。
+>
+> - Foundation：`<目标目录>/basic/*.tsx`
+> - Chat：`<目标目录>/chat/*.tsx`
+> - 例如默认：`src/components/ui/basic/button.tsx`、`src/components/ui/chat/chat-input/index.tsx`
+
+### 步骤 2：引入设计 token
+
+CLI 会生成 `src/qoder-tokens.css`，组件样式依赖其中的设计变量。请在**应用入口**引入一次：
+
+> **注意**：组件样式需在 **Tailwind CSS 4** 环境下才能正确生效（token 使用 `@theme` 生成工具类）。请确保项目使用 Tailwind 4，并在**同一份会被 Tailwind 处理的 CSS 入口**中引入 token（详见下方「按需引入完整说明」）。
+
+**Vite / CRA（入口为 main.tsx 或 main.jsx）：**
+
+在 `src/main.tsx`（或 `src/main.jsx`）顶部添加：
+
+```ts
+import './qoder-tokens.css'
+```
+
+**Next.js（App Router）：**
+
+在 `src/app/layout.tsx` 中与其他 import 一并添加：
+
+```ts
+import '../qoder-tokens.css'
+```
+
+（若 layout 位于 `src/app/layout.tsx` 使用 `../qoder-tokens.css`，位于 `app/layout.tsx` 则使用 `./qoder-tokens.css`。）
+
+### 步骤 3：使用组件
+
+默认会生成 `src/components/ui/basic/<name>.tsx`（Foundation）或 `src/components/ui/chat/<name>/`（Chat），因此导入路径在默认配置下为：
+
+- **Foundation**：`import { X } from '@/components/ui/basic/<组件名>'`
+- **Chat**：`import { X } from '@/components/ui/chat/<组件名>'`
+
+（若你修改了 `aliases.ui`，把上面路径中的 `@/components/ui` 换成你的 alias 即可。）
+
+```tsx
+// 默认 aliases.ui = @/components/ui 时：
+import { Button } from '@/components/ui/basic/button'
+
+function App() {
+  return (
+    <div>
+      <Button variant="primary">点击</Button>
+    </div>
+  )
+}
+```
+
+可选：在根节点设置 `data-theme` 与 `data-style`（如 `<div data-theme="light" data-style="neutral">`），不设置则使用默认值。
+
+---
+
+## 按需引入完整说明（与 Showcase 一致）
+
+要让按需引入的组件**样式与官方 Showcase 完全一致**，需满足以下环境与配置。
+
+### 环境要求
+
+| 项目 | 要求 |
+|------|------|
+| **Tailwind 版本** | 必须使用 **Tailwind CSS 4**。设计 token 使用 Tailwind 4 的 `@theme` 语法，将 CSS 变量映射为工具类（如 `h-7`、`bg-primary`、`rounded-md`）。使用 Tailwind 3 时这些类不会生成，组件样式会异常。 |
+| **安装** | `npm install tailwindcss@^4 @tailwindcss/vite`（Vite 项目）；或使用 `@tailwindcss/cli` 做预编译。 |
+
+### Token 引入的两种方式
+
+| 方式 | 何时用 | Token 如何生效 |
+|------|--------|----------------|
+| **先 init** | 希望 token 直接写进现有 CSS 入口、少一步手动 import 时 | 执行 `npx sparkdesign init`，CLI 会把 **theme.css + scale.css** 的内容注入到 `src/app/globals.css` 或 `src/index.css`，无需再单独引入 token 文件。 |
+| **直接 add** | 不想改现有流程、先装组件再补样式时 | 执行 `npx sparkdesign add button` 会生成 **`src/qoder-tokens.css`**。须在**应用入口**（如 `main.tsx`、`layout.tsx`）添加一行：`import './qoder-tokens.css'`（路径按实际入口位置调整，如 Next.js 可为 `import '../qoder-tokens.css'`）。 |
+
+无论哪种方式，**token 必须处在「会被 Tailwind 处理的同一份 CSS 管线」中**（即包含 `@import "tailwindcss"` 的那份 CSS 或其 import 链中），这样 `@theme` 才会被 Tailwind 4 读取并生成对应工具类。
+
+### CSS 入口配置（与 Showcase 一致）
+
+1. **顺序**：先 `@import "tailwindcss"`，再引入 token（或包含 token 的文件）。
+2. **扫描组件目录**：Showcase 会扫描组件所在目录以生成 `h-7`、`w-9` 等工具类。按需引入后组件在你项目里，需让 Tailwind 扫描到这些文件。在**同一份 CSS 入口**中增加 `@source` 指向组件目录（路径对应你当前的 `aliases.ui`）。
+
+**最小可用的入口 CSS 示例**（Vite 项目，组件默认在 `src/components/ui`）：
+
+```css
+@import "tailwindcss";
+@source "../components/ui";
+@import "./qoder-tokens.css";
+```
+
+若你已通过 **init** 把 token 写入了本文件，则无需再写 `@import "./qoder-tokens.css"`，只需保留 `@import "tailwindcss"` 和 `@source "../components/ui"` 即可。
+
+### 主题与布局风格（可选）
+
+与 Showcase 一样切换主题/风格时，在根节点设置：
+
+- **`data-theme`**：颜色主题，如 `light`、`dark`。
+- **`data-style`**：布局风格，如 `neutral`、`compact`、`soft`、`sharp`、`dense`。
+
+示例：`<div data-theme="light" data-style="neutral">`。不设置则使用默认值。
+
+---
+
+## 命令说明
+
+| 命令 | 说明 |
+|------|------|
+| `npx sparkdesign add button` | 添加 button 到 `src/components/ui/`（默认），并自动创建缺失的 config、token 文件、utils |
+| `npx sparkdesign add button tooltip dropdown-menu` | 一次添加多个组件 |
+| `npx sparkdesign init` | 先做一次「完整初始化」：选择布局风格、**组件存放目录（相对 src，默认 components）**、是否安装依赖；token 会写进现有 CSS 入口 |
+| `npx sparkdesign list` | 列出所有可添加的组件名 |
+| `npx sparkdesign diff button` | 对比本地 button 和最新模板的差异 |
+| `npx sparkdesign add button --overwrite` | 覆盖已有组件文件 |
+
+---
+
+## 支持的组件
+
+**支持的组件 = CLI 包内 `registry/meta.json` 的全部条目**（覆盖当前 registry 的 Foundation + Chat 组件实现）。
+
+权威列表请运行：
+
+```bash
+npx sparkdesign list
+```
+
+示例（Foundation + Chat 混合添加）：
+
+```bash
+npx sparkdesign add button select dropdown-menu tooltip
+npx sparkdesign add chat-input response markdown
+```
+
+> 说明：tokens（`registry/tokens/*.css`）与 `registry/lib/utils.ts` 由 `init` 或首次 `add` 时的“初始化逻辑”处理，不作为单组件条目列出。
+
+---
+
+## init 与 add 的选用
+
+- **直接 add**（推荐）：执行 `npx sparkdesign add button` 会生成 `src/qoder-tokens.css`，按步骤 2 在入口添加 `import './qoder-tokens.css'` 即可。
+- **先 init 再 add**：执行 `npx sparkdesign init` 时会询问**组件存放目录**（相对 src，如 `components` 或 `ui`），并写入 `components.json` 的 `aliases.components` 与 **`aliases.ui`**（默认 `@/components/ui`）。之后 add 会按该配置输出到对应目录（如 `src/components/ui/`），并将 token 写入现有 `globals.css` / `index.css`。
+
+两种方式择一使用即可。若要**与官方 Showcase 样式完全一致**，请同时满足上文「按需引入完整说明」中的 Tailwind 4 与 CSS 入口配置（含 `@source` 扫描组件目录）。
+
+---
+
+## 生成文件说明
+
+| 文件 | 何时出现 | 说明 |
+|------|----------|------|
+| `components.json` | add 或 init | 配置：`style`、`aliases.components`、`aliases.utils`、**`aliases.ui`**（组件安装目录，默认 **`@/components/ui`**）。修改 **`aliases.ui`** 可改变 add 的输出目录；再次 add 时终端会打印目标目录以确认生效。 |
+| `src/qoder-tokens.css` | 直接 add 且项目中尚无 token 时 | 设计 token 文件（theme + scale），须在**与 Tailwind 同一管线的入口**中引入一次，且项目需使用 Tailwind 4 |
+| `src/lib/utils.ts` | add 或 init 且不存在时 | 工具函数 `cn()`，供组件使用 |
+| `src/<aliases.ui 解析路径>/basic/*.tsx`<br>`src/<aliases.ui 解析路径>/chat/*.tsx` | add 对应组件时 | 组件源码（路径由 `aliases.ui` 决定，默认 `src/components/ui/`），可按需修改 |
+
+---
+
+## 依赖
+
+- **样式生效前提**：组件样式依赖设计 token 与 Tailwind 工具类，项目须使用 **Tailwind CSS 4**（见上文「按需引入完整说明」）。若未使用 Tailwind 4，token 中的 `@theme` 不会生效，`h-7`、`bg-primary` 等类不会生成。
+- **运行时依赖**：组件会用到 `class-variance-authority`、`clsx`（以及部分组件需要 `tailwind-merge`、`@radix-ui/*` 等）。若执行 `npx sparkdesign add button` 后出现依赖缺失，请在项目根目录执行：
+
+```bash
+npm install class-variance-authority clsx tailwind-merge
+```
+
+使用 tooltip、dropdown-menu 等组件时，按提示安装 `@radix-ui/react-tooltip`、`@radix-ui/react-dropdown-menu` 等依赖。
+
+---
+
+## 安装目录配置
+
+支持 **`aliases.ui`** 作为组件安装目录，默认 **`@/components/ui`**；未设置时使用 `aliases.components + '/qoder'` 以兼容旧配置。**改安装位置只需改 `aliases.ui`**，`aliases.components` 一般不必改。详见 [CLI 配置说明](../docs/CLI配置说明.md)。
 
-cunyu666

package/dist/commands/add.js

@@ -0,0 +1,93 @@
+/**
+ * [INPUT]: components[] from argv, options.overwrite
+ * [OUTPUT]: void - 写入组件文件到用户项目
+ * [POS]: cli/src/commands/add.ts
+ *
+ * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import { execa } from 'execa';
+import { readConfig, writeConfig, getComponentsBaseAlias, resolveTargetDir } from '../utils/config.js';
+import { getRegistryRoot, getComponentMeta, getComponentSource } from '../utils/registry.js';
+import { stripL3Header, transformImports } from '../utils/transform.js';
+import { projectHasTokens, writeQoderTokensFile, getQoderTokensImportPath } from '../utils/tokens.js';
+export async function add(components, options = {}) {
+    const cwd = process.cwd();
+    const registryRoot = getRegistryRoot();
+    let config = await readConfig(cwd);
+    const hasConfig = await fs.pathExists(path.join(cwd, 'components.json'));
+    if (!hasConfig) {
+        await writeConfig(config, cwd);
+        console.log(chalk.green('✓'), 'Created components.json (default config)');
+    }
+    const hasTokens = await projectHasTokens(cwd);
+    if (!hasTokens) {
+        const { path: tokensPath, created } = await writeQoderTokensFile(cwd, registryRoot);
+        if (created) {
+            console.log(chalk.green('✓'), 'Created', tokensPath);
+        }
+        console.log(chalk.cyan('  To enable component styles, add to your app entry (e.g. main.tsx or layout.tsx):'));
+        console.log(chalk.yellow('  import'), chalk.white(`'${getQoderTokensImportPath()}'`));
+        console.log(chalk.gray('  (Paste the line above into your entry file.)'));
+        console.log(chalk.gray('  Or run'), chalk.cyan('npx sparkdesign init'), chalk.gray('for full setup with tokens in your CSS entry.'));
+    }
+    const utilsDest = path.join(cwd, 'src', 'lib', 'utils.ts');
+    if (!(await fs.pathExists(utilsDest))) {
+        const utilsTemplate = await fs.readFile(path.join(registryRoot, 'lib', 'utils.ts'), 'utf-8');
+        await fs.ensureDir(path.dirname(utilsDest));
+        await fs.writeFile(utilsDest, utilsTemplate, 'utf-8');
+        console.log(chalk.green('✓'), 'Created', utilsDest);
+    }
+    if (!components || components.length === 0) {
+        console.log(chalk.cyan('Usage:'), 'npx sparkdesign add button [tooltip] [dropdown-menu]');
+        console.log(chalk.cyan('List:'), 'npx sparkdesign list');
+        return;
+    }
+    const targetDir = resolveTargetDir(getComponentsBaseAlias(config), cwd);
+    await fs.ensureDir(targetDir);
+    const baseAlias = getComponentsBaseAlias(config);
+    console.log(chalk.gray('  组件安装目录:'), chalk.cyan(baseAlias));
+    console.log(chalk.gray('  目标目录:'), chalk.cyan(path.relative(cwd, targetDir) || targetDir));
+    console.log(chalk.gray('  (components.json → aliases.ui)'));
+    console.log('');
+    const allDeps = new Set();
+    for (const name of components) {
+        const meta = await getComponentMeta(registryRoot, name);
+        if (!meta) {
+            console.error(chalk.red('✗'), `Component "${name}" not found. Run npx sparkdesign list`);
+            continue;
+        }
+        for (const file of meta.files) {
+            const source = await getComponentSource(registryRoot, name, file);
+            const transformed = transformImports(stripL3Header(source), config.aliases);
+            // 保留相对路径，便于 chat/xxx 与 basic/xxx 的引用关系（对齐 ElevenLabs npx add message 的按需安装）
+            const destPath = path.join(targetDir, file);
+            const exists = await fs.pathExists(destPath);
+            if (exists && !options.overwrite) {
+                console.log(chalk.yellow('○'), name, 'already exists, skipped. Use --overwrite to replace.');
+                continue;
+            }
+            await fs.ensureDir(path.dirname(destPath));
+            await fs.writeFile(destPath, transformed, 'utf-8');
+            console.log(chalk.green('✓'), 'Added', name, '→', destPath);
+        }
+        if (meta.dependencies) {
+            meta.dependencies.forEach((d) => allDeps.add(d));
+        }
+    }
+    if (allDeps.size > 0) {
+        console.log('');
+        console.log(chalk.cyan('Installing dependencies...'));
+        const depsArray = Array.from(allDeps);
+        try {
+            await execa('npm', ['install', ...depsArray], { cwd, stdio: 'inherit' });
+            console.log(chalk.green('✓'), 'Installed', depsArray.length, 'dependencies');
+        }
+        catch {
+            console.log(chalk.yellow('○'), 'Auto-install failed. Run manually:');
+            console.log('  npm install', depsArray.join(' '));
+        }
+    }
+}

package/dist/commands/diff.js

@@ -0,0 +1,54 @@
+/**
+ * [INPUT]: component name from argv
+ * [OUTPUT]: void - 打印本地文件与注册表版本的 diff
+ * [POS]: cli/src/commands/diff.ts
+ *
+ * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import { diffLines } from 'diff';
+import { readConfig, getComponentsBaseAlias, resolveTargetDir } from '../utils/config.js';
+import { getRegistryRoot, getComponentMeta, getComponentSource } from '../utils/registry.js';
+import { stripL3Header, transformImports } from '../utils/transform.js';
+function printLineDiffs(changes) {
+    for (const part of changes) {
+        const lines = part.value.split('\n').filter((l, i, arr) => i < arr.length - 1 || l.length > 0);
+        const color = part.added ? chalk.green : part.removed ? chalk.red : chalk.gray;
+        const prefix = part.added ? '+' : part.removed ? '-' : ' ';
+        for (const line of lines) {
+            console.log(color(prefix + line));
+        }
+    }
+}
+export async function diffCmd(componentName) {
+    const cwd = process.cwd();
+    const config = await readConfig(cwd);
+    const registryRoot = getRegistryRoot();
+    const meta = await getComponentMeta(registryRoot, componentName);
+    if (!meta) {
+        console.error(chalk.red('✗'), `Component "${componentName}" not found. Run npx sparkdesign list`);
+        process.exit(1);
+    }
+    const targetDir = resolveTargetDir(getComponentsBaseAlias(config), cwd);
+    let hasDiff = false;
+    for (const file of meta.files) {
+        const localPath = path.join(targetDir, file);
+        const localExists = await fs.pathExists(localPath);
+        const registrySource = await getComponentSource(registryRoot, componentName, file);
+        const registryTransformed = transformImports(stripL3Header(registrySource), config.aliases);
+        const localContent = localExists ? await fs.readFile(localPath, 'utf-8') : '';
+        const changes = diffLines(localContent, registryTransformed);
+        const hasChanges = changes.some((c) => c.added || c.removed);
+        if (hasChanges) {
+            hasDiff = true;
+            console.log(chalk.cyan('---'), file);
+            printLineDiffs(changes);
+            console.log('');
+        }
+    }
+    if (!hasDiff) {
+        console.log(chalk.green('No differences for'), componentName);
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,96 @@
+/**
+ * [INPUT]: 无（从 process.cwd() 读取项目）
+ * [OUTPUT]: void - 写入 components.json、tokens、utils
+ * [POS]: cli/src/commands/init.ts
+ *
+ * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import prompts from 'prompts';
+import chalk from 'chalk';
+import { execa } from 'execa';
+import { writeConfig } from '../utils/config.js';
+import { getRegistryRoot } from '../utils/registry.js';
+import { ensureDesignTokens, projectHasTokens } from '../utils/tokens.js';
+const STYLES = [
+    { title: 'neutral（平衡标准）', value: 'neutral' },
+    { title: 'compact（紧凑）', value: 'compact' },
+    { title: 'soft（舒适）', value: 'soft' },
+    { title: 'sharp（几何）', value: 'sharp' },
+    { title: 'dense（密集）', value: 'dense' },
+];
+function resolveComponentsDir(aliasesComponents) {
+    const trimmed = aliasesComponents.replace(/^@\//, '');
+    return trimmed ? path.join('src', trimmed) : 'src/components';
+}
+export async function init() {
+    const cwd = process.cwd();
+    const registryRoot = getRegistryRoot();
+    const utilsTemplatePath = path.join(registryRoot, 'lib', 'utils.ts');
+    const answers = await prompts([
+        {
+            type: 'select',
+            name: 'style',
+            message: '选择布局风格 (data-style)',
+            choices: STYLES,
+            initial: 0,
+        },
+        {
+            type: 'text',
+            name: 'componentsDir',
+            message: '组件库放在哪个目录下？（我们会在此下创建 ui 子目录；如填 components 即 src/components/ui）',
+            initial: 'components',
+        },
+        {
+            type: 'confirm',
+            name: 'installDeps',
+            message: '是否安装依赖？(class-variance-authority, clsx, tailwind-merge)',
+            initial: true,
+        },
+    ]);
+    if (answers.style == null) {
+        process.exit(0);
+    }
+    const style = answers.style;
+    const rawDir = (answers.componentsDir ?? 'components').toString().trim().replace(/^src\/?/, '');
+    const componentsPath = rawDir || 'components';
+    const config = {
+        style,
+        aliases: {
+            components: `@/${componentsPath}`,
+            utils: '@/lib/utils',
+            ui: `@/${componentsPath}/ui`,
+        },
+    };
+    await writeConfig(config, cwd);
+    console.log(chalk.green('✓'), 'Created components.json');
+    const componentsDir = resolveComponentsDir(config.aliases.components);
+    const libDir = path.join(cwd, 'src', 'lib');
+    const utilsDest = path.join(libDir, 'utils.ts');
+    await fs.ensureDir(libDir);
+    const utilsTemplate = await fs.readFile(utilsTemplatePath, 'utf-8');
+    await fs.writeFile(utilsDest, utilsTemplate, 'utf-8');
+    console.log(chalk.green('✓'), 'Created', utilsDest);
+    const injected = await ensureDesignTokens(cwd, registryRoot);
+    if (injected) {
+        console.log(chalk.green('✓'), 'Added design tokens (theme + scale) to', injected);
+    }
+    else if (await projectHasTokens(cwd)) {
+        console.log(chalk.yellow('○'), 'Design tokens already present in project');
+    }
+    else {
+        console.log(chalk.yellow('○'), 'Could not inject tokens (no CSS entry found). Add theme/scale manually.');
+    }
+    if (answers.installDeps) {
+        try {
+            await execa('npm', ['install', 'class-variance-authority', 'clsx', 'tailwind-merge'], { cwd, stdio: 'inherit' });
+            console.log(chalk.green('✓'), 'Installed dependencies');
+        }
+        catch {
+            console.log(chalk.yellow('○'), 'Run manually: npm install class-variance-authority clsx tailwind-merge');
+        }
+    }
+    await fs.ensureDir(path.join(cwd, componentsDir));
+    console.log(chalk.green('✓'), 'Spark Design initialized. Run'), chalk.cyan('npx sparkdesign add button'), chalk.green('to add components.');
+}

package/dist/commands/list.js

@@ -0,0 +1,25 @@
+/**
+ * [INPUT]: 无
+ * [OUTPUT]: void - 打印注册表内所有组件名
+ * [POS]: cli/src/commands/list.ts
+ *
+ * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ */
+import chalk from 'chalk';
+import { getRegistryRoot, listComponents } from '../utils/registry.js';
+export async function list() {
+    const registryRoot = getRegistryRoot();
+    try {
+        const names = await listComponents(registryRoot);
+        if (names.length === 0) {
+            console.log('No components in registry.');
+            return;
+        }
+        console.log(chalk.cyan('Available components:'));
+        names.forEach((name) => console.log('  ', name));
+    }
+    catch (e) {
+        console.error(chalk.red('Failed to load registry:'), e.message);
+        process.exit(1);
+    }
+}

package/dist/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * [INPUT]: process.argv
+ * [OUTPUT]: void - 执行对应子命令并退出
+ * [POS]: cli/src/index.ts - Spark Design CLI 入口
+ *
+ * [PROTOCOL]:
+ * 1. 逻辑变更时同步更新此 Header
+ * 2. 子命令实现位于 commands/
+ */
+import { program } from 'commander';
+import { init } from './commands/init.js';
+import { add } from './commands/add.js';
+import { list } from './commands/list.js';
+import { diffCmd } from './commands/diff.js';
+program
+    .name('sparkdesign')
+    .description('Spark Design CLI - 按需添加组件（源码复制到当前项目）')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('初始化项目：写入 components.json、tokens、utils')
+    .action(init);
+program
+    .command('add [components...]')
+    .description('添加组件到当前项目')
+    .option('-o, --overwrite', '覆盖已存在的组件文件')
+    .action(add);
+program
+    .command('list')
+    .description('列出所有可用组件')
+    .action(list);
+program
+    .command('diff <component>')
+    .description('对比本地组件与注册表最新版本的差异')
+    .action(diffCmd);
+program.parse();

package/dist/utils/config.js

@@ -0,0 +1,53 @@
+/**
+ * [INPUT]: process.cwd() 下的 components.json
+ * [OUTPUT]: Config | 默认配置
+ * [POS]: cli/src/utils/config.ts
+ *
+ * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+const defaultConfig = {
+    style: 'neutral',
+    aliases: {
+        components: '@/components',
+        utils: '@/lib/utils',
+        ui: '@/components/ui',
+    },
+};
+/** 优先用 aliases.ui 作为组件安装目录，未设时用 components + '/qoder'（兼容旧配置） */
+export function getComponentsBaseAlias(config) {
+    return config.aliases.ui ?? config.aliases.components + '/qoder';
+}
+/** 将 alias 解析为绝对目录（如 @/components/qoder → cwd/src/components/qoder） */
+export function resolveTargetDir(aliasesBase, cwd) {
+    const withoutAlias = aliasesBase.replace(/^@\//, '').trim();
+    let base = withoutAlias || 'components';
+    base = base.replace(/^src\/?/, '') || 'components';
+    return path.join(cwd, 'src', base);
+}
+export async function readConfig(cwd = process.cwd()) {
+    const configPath = path.join(cwd, 'components.json');
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return {
+            style: parsed.style ?? defaultConfig.style,
+            aliases: {
+                components: parsed.aliases?.components ?? defaultConfig.aliases.components,
+                utils: parsed.aliases?.utils ?? defaultConfig.aliases.utils,
+                ui: parsed.aliases?.ui ?? defaultConfig.aliases.ui,
+            },
+        };
+    }
+    catch {
+        return defaultConfig;
+    }
+}
+export async function writeConfig(config, cwd = process.cwd()) {
+    const configPath = path.join(cwd, 'components.json');
+    await fs.writeJson(configPath, {
+        $schema: 'https://qoder.design/schema.json',
+        ...config,
+    }, { spaces: 2 });
+}

package/dist/utils/registry.js

@@ -0,0 +1,34 @@
+/**
+ * [INPUT]: 组件名、registry 根路径
+ * [OUTPUT]: meta、模板文件内容
+ * [POS]: cli/src/utils/registry.ts
+ *
+ * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** 开发时 src/utils/registry.ts -> 向上到 cli/ -> registry；构建后 dist/utils/registry.js -> 向上到 cli/ -> registry */
+export function getRegistryRoot() {
+    const distDir = path.resolve(__dirname, '..');
+    const cliRoot = path.resolve(distDir, '..');
+    return path.join(cliRoot, 'registry');
+}
+export async function loadMeta(registryRoot) {
+    const metaPath = path.join(registryRoot, 'meta.json');
+    const content = await fs.readFile(metaPath, 'utf-8');
+    return JSON.parse(content);
+}
+export async function getComponentMeta(registryRoot, componentName) {
+    const meta = await loadMeta(registryRoot);
+    return meta[componentName] ?? null;
+}
+export async function getComponentSource(registryRoot, componentName, relativePath) {
+    const fullPath = path.join(registryRoot, relativePath);
+    return fs.readFile(fullPath, 'utf-8');
+}
+export async function listComponents(registryRoot) {
+    const meta = await loadMeta(registryRoot);
+    return Object.keys(meta);
+}