brutx-vue

brutx-vue

将 Neo-Brutalist 风格的 Vue 3 UI 组件添加到你的项目中。

English

安装

运行 brutx-vue 需要 Node.js 22.0+。用户项目可使用 npm、yarn、pnpm 或 bun；本仓库开发和发布的维护环境要求另见根 README。

# 使用 pnpm
pnpm add -D brutx-vue

# 使用 npm
npm install -D brutx-vue

# 使用 yarn
yarn add -D brutx-vue

# 使用 bun
bun add -D brutx-vue

或无需安装直接运行：

npx brutx-vue@latest init

命令

brutx-vue init

在你的项目中初始化 BrutxUI。该命令会执行以下操作：

1. 检测项目类型（Vite + Vue、Nuxt 等）
2. 检测 Tailwind CSS 版本（v3 / v4）
3. 自动发现 Tailwind 配置、CSS 入口文件及 tsconfig.json 中的路径别名
4. 交互式引导完成配置
5. 生成 components.json 配置文件
6. 创建 cn() 工具函数（clsx + tailwind-merge）
7. 将 Neo-Brutalist CSS 设计令牌和工具类注入全局 CSS
8. 安装基础依赖（clsx、tailwind-merge、class-variance-authority、@lucide/vue、reka-ui）
9. 自动检测 monorepo 工作区，支持将依赖安装到工作区根目录

brutx-vue init [options]

brutx-vue add [components...]

将组件添加到你的项目中。该命令会执行以下操作：

1. 验证项目已初始化（components.json 存在）
2. 递归解析组件依赖（拓扑排序）
3. 写入组件源码文件并替换导入别名
4. 安装所需的 npm 依赖

# 添加指定组件
brutx-vue add button card input

# 添加全部组件
brutx-vue add --all

# 交互式选择
brutx-vue add

版本锁定

使用 @ 语法将组件锁定到指定版本：

brutx-vue add button@1.2.0

这会映射到注册表中对应的 GitHub 分支。

brutx-vue update [components...]

将已安装组件更新到注册表最新版本。自动检测本地修改并提供选择性更新。

# 更新指定组件
brutx-vue update button card

# 更新全部过期组件
brutx-vue update --all

# 模拟运行
brutx-vue update --dry-run

brutx-vue list

列出项目中已安装的所有组件，包括文件数量和依赖信息。

brutx-vue list
brutx-vue list --json

brutx-vue info <component>

查看指定组件的详细信息，包括注册表文件、依赖、本地安装状态等。

brutx-vue info button
brutx-vue info button --json

brutx-vue remove <components...>

移除已安装的组件。删除组件目录并自动清理不再被其他组件引用的孤立文件（composables、locales、lib 等）。

# 移除单个组件
brutx-vue remove button

# 移除多个组件
brutx-vue remove button card input

# 模拟运行
brutx-vue remove button --dry-run

brutx-vue create <project-name>

快速创建一个预配置好的 Vue 3 + BrutxUI 项目。自动完成脚手架搭建、依赖安装和 BrutxUI 初始化。

# 使用默认模板（Vite + Vue 3 + TypeScript）
brutx-vue create my-app

# 使用 Nuxt 模板
brutx-vue create my-app --template nuxt

# 指定包管理器
brutx-vue create my-app --package-manager npm

brutx-vue doctor

检查项目健康状态并诊断配置问题。验证 components.json、CSS 令牌、别名目录、依赖安装、cn() 函数等。支持自动修复。

# 检查项目状态
brutx-vue doctor

# 自动修复可修复的问题
brutx-vue doctor --fix

# 仅执行指定修复
brutx-vue doctor --fix-only AddConfigVersion

# 生成 CycloneDX 1.5 SBOM 物料清单
brutx-vue doctor --sbom

# 离线模式下跳过网络探测
brutx-vue doctor --offline

# JSON 格式输出
brutx-vue doctor --json

brutx-vue diff [components...]

对比本地已安装组件与注册表最新版本的差异，生成 unified diff 报告。

# 对比指定组件
brutx-vue diff button

# 对比全部已安装组件
brutx-vue diff --all

# JSON 格式输出
brutx-vue diff --json

全局选项

以下选项适用于所有命令，需放在子命令之前：

brutx-vue [global-options] <command> [command-options]

全局 dry-run

--dry-run 全局 flag 激活所有命令的 dry-run 语义，也可通过 BRUTX_DRY_RUN=1 环境变量激活：

# 以下两条等价
BRUTX_DRY_RUN=1 brutx-vue add button
brutx-vue --dry-run add button

verbose 等级

通过 -v/-vv/-vvv 或 BRUTX_VERBOSE=<n> 控制输出详细程度：

审计日志

add/remove/update/diff 命令执行后会在 .brutx/audit.log 追加一条 JSONL 记录，包含时间戳、命令、组件、源、成功状态等信息。doctor 会读取最近 5 条失败记录作为诊断线索。

配置文件

运行 init 后，项目根目录会生成 components.json：

{
  "$schema": "https://brutx-vue.com/schema.json",
  "$version": 1,
  "style": "brutalism",
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/assets/main.css"
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "composables": "@/composables"
  }
}

• $version — 配置文件版本号，用于 doctor 命令检测是否需要迁移
• aliases.composables — 组合式函数的导入别名路径

项目检测

CLI 会自动检测以下信息：

安全

• 所有文件操作均通过 isSafePath() 校验，防止路径穿越攻击
• 注册表本地读取时检查工作目录边界
• 组件文件路径在写入前经过规范化和验证
• verifyWrittenPath() 在写入时验证文件实际路径，防御 TOCTOU（Time-of-Check-to-Time-of-Use）攻击

Node.js 编程式 API

brutx-vue 提供一套类型完备的 Node.js 编程式服务门面，可在自定义构建脚本、CI 工作流或自动化 Agent 工具中直接调用：

import {
    diagnose,
    repair,
    DiagnosticEngine,
    generateProjectSbom,
    diffComponents,
    initializeProjectFiles,
    writeComponentFiles,
    removeComponents,
} from 'brutx-vue';

// 1. 无副作用只读健康诊断巡检
const report = await diagnose({
    cwd: process.cwd(),
    categories: ['config', 'tailwind', 'structure', 'integrity'],
});
console.log(`Passed: ${report.summary.passed}, Errors: ${report.summary.errors}`);

// 2. 单事务确定性拓扑自愈
if (report.hasErrors) {
    const repairReport = await repair({
        cwd: process.cwd(),
        dryRun: false,
    });
    console.log(`Applied ${repairReport.applied.length} fixes.`);
}

// 3. 导出项目级 CycloneDX 1.5 SBOM
const sbom = await generateProjectSbom({
    cwd: process.cwd(),
    outputPath: 'brutx-sbom.json',
});

开发

# 构建
pnpm build

# 监听模式
pnpm dev

# 运行测试
pnpm test

# 本地运行 CLI
pnpm start

架构与分发机制

• CLI 源码交付原理：详见 分发与公开 API 契约。
• 全局设计令牌同构生成：详见 生成与构建机制。
• Monorepo 架构：详见 项目架构总览。

许可证

基于 MIT 许可证 开源。