@fredwsw/frontend-rules 1.0.0 → 1.0.1

package/README.md

@@ -1,302 +1,52 @@
-# `@sanshui/frontend-rules` 使用说明
+# frontend-rules
 
-本文档说明如何把当前仓库的规则模板打包成一个可执行 npm 包，并通过 `pnpm dlx` 在其他项目一键同步到项目根目录。
+一个用于将最新 `.cursor` 规则同步到当前项目根目录的小工具。
 
-## 目标
+## 快速开始
 
-- 发布一个包：`@sanshui/frontend-rules`
-- 在任意项目根目录执行：
+在你的项目根目录执行：
 
 ```bash
-pnpm dlx @sanshui/frontend-rules@latest
+pnpm dlx @fredwsw/frontend-rules@latest
 ```
 
-- 自动将包内模板按需同步到当前项目根目录：
-  - 规则和技能同步到 `.cursor`
-  - 组件库文档同步到 `docs`
+## 使用前提
 
----
+- 已安装 Node.js `>=18`
+- 已安装 `pnpm`
+- 当前命令行所在目录是你希望应用规则的项目根目录
 
-## 一、建议的包结构
+## 执行后会发生什么
 
-新建一个用于发布的仓库（或就在当前仓库整理），结构建议如下：
+- 工具会引导你选择需要的规则模板
+- 将选中的规则文件写入当前项目（通常是 `.cursor/rules` 相关目录）
+- 如果目标文件已存在，按工具提示处理覆盖或更新
 
-```text
-frontend-rules/
-  bin/
-    cli.js
-  template/
-    rules/
-      common.mdc
-      uv-ui-docs.mdc
-      ...
-    docs/
-      uv-ui-docs/
-      ...
-    skills/
-      ...
-  package.json
-  README.md
-```
-
-说明：
-
-- `template/rules`：规则文件模板。
-- `template/docs`：组件库文档模板，按用户选择复制。
-- `template/skills`：技能模板。
-- `bin/cli.js`：`pnpm dlx` 实际执行入口。
-
----
-
-## 二、`package.json` 示例
-
-> 包名改成你的正式名：`@sanshui/frontend-rules`
-
-```json
-{
-  "name": "@sanshui/frontend-rules",
-  "version": "1.0.0",
-  "description": "Sync latest .cursor rules into project root",
-  "type": "module",
-  "bin": {
-    "frontend-rules": "./bin/cli.js"
-  },
-  "files": [
-    "bin",
-    "template",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@inquirer/prompts": "^7.8.4",
-    "fs-extra": "^11.2.0"
-  },
-  "license": "MIT"
-}
-```
-
----
-
-## 三、`bin/cli.js` 示例
-
-> 作用：基础规则与技能始终复制到 `.cursor`，组件库文档支持交互多选后按需复制到项目根目录 `docs`。支持 `--dry-run`。
-
-```js
-#!/usr/bin/env node
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
-import fs from "fs-extra";
-import { checkbox } from "@inquirer/prompts";
-
-const cwd = process.cwd();
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const root = path.resolve(__dirname, "..");
-const sourceDir = path.join(root, "template");
-const cursorTargetDir = path.join(cwd, ".cursor");
-const docsTargetRootDir = path.join(cwd, "docs");
-const args = new Set(process.argv.slice(2));
-const dryRun = args.has("--dry-run");
-const allLibs = args.has("--all-libs");
-const libsArg = [...args].find((arg) => arg.startsWith("--libs="));
-
-function parseLibsArg() {
-  if (!libsArg) {
-    return null;
-  }
-  const value = libsArg.slice("--libs=".length).trim();
-  if (!value) {
-    return [];
-  }
-  return value.split(",").map((item) => item.trim()).filter(Boolean);
-}
-
-async function getLibraryOptions() {
-  const docsRoot = path.join(sourceDir, "docs");
-  const exists = await fs.pathExists(docsRoot);
-  if (!exists) {
-    return [];
-  }
-  const entries = await fs.readdir(docsRoot, { withFileTypes: true });
-  return entries.filter((entry) => entry.isDirectory()).map((entry) => {
-    const docsDirName = entry.name;
-    return {
-      key: docsDirName.replace(/-docs$/i, ""),
-      docsDirName,
-      docsSourcePath: path.join(docsRoot, docsDirName),
-      ruleFileName: `${docsDirName}.mdc`,
-      ruleSourcePath: path.join(sourceDir, "rules", `${docsDirName}.mdc`),
-    };
-  });
-}
-
-async function promptLibraries(options) {
-  if (options.length === 0) {
-    return [];
-  }
-  if (!process.stdin.isTTY) {
-    return options;
-  }
-  const selectedKeys = await checkbox({
-    message: "请选择组件库（方向键移动，空格勾选，回车确认）",
-    choices: options.map((option) => ({ name: option.key, value: option.key })),
-  });
-  if (!selectedKeys || selectedKeys.length === 0) {
-    return [];
-  }
-  return options.filter((option) => new Set(selectedKeys).has(option.key));
-}
+## 推荐用法
 
-async function resolveSelectedLibraries(options) {
-  if (allLibs) {
-    return options;
-  }
-  const parsedLibKeys = parseLibsArg();
-  if (parsedLibKeys !== null) {
-    return options.filter((option) => new Set(parsedLibKeys).has(option.key));
-  }
-  return promptLibraries(options);
-}
-
-async function copyWithDryRun(from, to) {
-  if (dryRun) {
-    console.log("[frontend-rules] copy:", from, "->", to);
-    return;
-  }
-  await fs.copy(from, to, { overwrite: true, recursive: true });
-}
-
-async function main() {
-  await fs.ensureDir(cursorTargetDir);
-  await fs.ensureDir(docsTargetRootDir);
-
-  await copyWithDryRun(path.join(sourceDir, "rules", "common.mdc"), path.join(cursorTargetDir, "rules", "common.mdc"));
-  await copyWithDryRun(path.join(sourceDir, "skills"), path.join(cursorTargetDir, "skills"));
-
-  const options = await getLibraryOptions();
-  const selectedLibraries = await resolveSelectedLibraries(options);
-  for (const library of selectedLibraries) {
-    await copyWithDryRun(library.docsSourcePath, path.join(docsTargetRootDir, library.docsDirName));
-    if (await fs.pathExists(library.ruleSourcePath)) {
-      await copyWithDryRun(library.ruleSourcePath, path.join(cursorTargetDir, "rules", library.ruleFileName));
-    }
-  }
-}
-
-main();
-```
-
----
-
-## 四、本地联调
-
-在包仓库目录执行：
+每次想同步最新规则时，直接重复执行：
 
 ```bash
-pnpm install
-node ./bin/cli.js --dry-run
-node ./bin/cli.js
+pnpm dlx @fredwsw/frontend-rules@latest
 ```
 
-然后检查当前目录是否生成/更新了：
-
-- `.cursor/rules`
-- `.cursor/skills`
-- `docs/<组件库>-docs`
+这样无需全局安装，始终使用最新版本。
 
----
+## 常见问题
 
-## 五、发布到 npm
+### 1) 提示 `pnpm` 命令不存在
 
-1. 登录 npm（首次）
+请先安装 pnpm：
 
 ```bash
-npm login
+npm i -g pnpm
 ```
 
-2. 发布（Scoped 包通常建议公开）
-
-```bash
-npm publish --access public
-```
-
-3. 后续更新流程
-
-```bash
-# 修改 template/.cursor 内容后
-npm version patch
-npm publish --access public
-```
-
----
-
-## 六、在其他项目中使用
-
-进入目标项目根目录，执行：
-
-```bash
-pnpm dlx @sanshui/frontend-rules@latest
-```
-
-常用变体：
-
-```bash
-# 只预览，不落盘（若你实现了 --dry-run 参数）
-pnpm dlx @sanshui/frontend-rules@latest --dry-run
-
-# 不交互，直接选择全部组件库
-pnpm dlx @sanshui/frontend-rules@latest --all-libs
-
-# 不交互，指定组件库（可多选，逗号分隔）
-pnpm dlx @sanshui/frontend-rules@latest --libs=uv-ui,first-ui
-```
-
----
-
-## 七、推荐约定（团队协作）
-
-- 把 `.cursor` 规则维护统一放在 `@sanshui/frontend-rules`，业务仓库不各自散改。
-- 每次规则更新都发版，业务仓库按需执行 `pnpm dlx ...@latest` 同步。
-- 若业务仓库存在少量本地特化，可约定放在单独文件并在同步后手动合并。
-
----
-
-## 八、常见问题
-
-### 1）`pnpm dlx` 没拿到最新版本？
-
-- 显式指定 `@latest`：
-
-```bash
-pnpm dlx @sanshui/frontend-rules@latest
-```
-
-- 确认刚发布版本已在 npm 可见。
-
-### 2）会不会覆盖本地 `.cursor`？
-
-- 当前示例是覆盖策略（`overwrite: true`）。
-- 如果你想保守一点，可扩展参数：
-  - `--force` 才覆盖
-  - 默认仅拷贝不存在文件
-  - 或执行前先备份到 `.cursor.bak-时间戳`
-
-### 3）如何控制复制哪些组件库文档？
-
-- 交互模式下支持方向键上下移动、空格勾选、回车确认（基于 `@inquirer/prompts`）。
-- 非交互可用 `--libs=uv-ui,first-ui`。
-- 全量组件库可用 `--all-libs`。
-
----
+### 2) 提示 Node 版本过低
 
-## 九、最小执行清单
+请升级 Node.js 到 `18` 或更高版本后重试。
 
-1. 准备 `template/rules`、`template/docs`、`template/skills` 模板目录。  
-2. 写好 `bin/cli.js` 复制逻辑。  
-3. 配置 `package.json` 的 `name`、`bin`、`files`。  
-4. `npm publish --access public`。  
-5. 在业务项目运行：`pnpm dlx @sanshui/frontend-rules@latest`，按提示多选组件库。
+### 3) 我应该在什么目录执行命令？
 
+在你要应用规则的项目根目录执行命令。  
+例如你的业务项目目录，而不是这个工具包源码目录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fredwsw/frontend-rules",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Sync latest .cursor rules into project root",
   "type": "module",
   "bin": {