@ruan-cat/utils 4.12.0 → 4.13.0

package/dist/node-esm/index.d.ts

@@ -39,14 +39,101 @@ declare function hasChangelogMd(): boolean;
  */
 declare function copyChangelogMd(/** 目标文件夹 */ target: string): void;
 
-/** 检查当前运行的根目录 是否存在 .claude/agents 文件夹 */
-declare function hasClaudeAgents(): boolean;
 /**
- * 将 .claude/agents 文件夹复制到指定要求的位置内
+ * 检查指定根目录是否存在 .claude/agents 文件夹
+ * @param options - 配置选项
+ * @param options.rootDir - 可选的根目录路径，支持相对路径（如 `../../../` 表示向上三级目录）。
+ *                          如果不传入，将自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录。
+ *                          相对路径会基于当前工作目录 (process.cwd()) 解析为绝对路径。
+ * @returns 是否存在 .claude/agents 文件夹
+ * @example
+ * // 自动检测 monorepo 根目录
+ * hasClaudeAgents()
+ *
+ * // 手动指定相对路径（从当前工作目录向上三级）
+ * hasClaudeAgents({ rootDir: '../../../' })
+ *
+ * // 手动指定绝对路径
+ * hasClaudeAgents({ rootDir: '/path/to/monorepo' })
+ */
+declare function hasClaudeAgents(options?: {
+    rootDir?: string;
+}): boolean;
+/**
+ * 将 .claude/agents 文件夹复制到指定位置的配置选项
+ */
+interface CopyClaudeAgentsOptions {
+    /**
+     * 目标文件夹路径（必须是相对路径，相对于当前工作目录）
+     * @description
+     * **重要**：此参数仅接受相对路径，不接受绝对路径（禁止以 `/` 或盘符如 `C:\` 开头）。
+     * 使用绝对路径会抛出错误，这是为了防止意外覆盖系统目录。
+     *
+     * 该地址是写相对路径的 不能写绝对路径，容易导致意外。
+     * vitepress 命令运行在 apps/admin 目录内，该地址是相对于该运行目录的。
+     * 比如期望将 `.claude/agents` 复制到 `apps/admin/src/docs/prompts/agents` 文件夹。
+     * 则写 `src/docs/prompts/agents` 即可。
+     *
+     * @throws {Error} 当传入绝对路径时抛出错误
+     * @example
+     * // ✅ 正确：相对路径
+     * "src/docs/prompts/agents"
+     * "dist/agents"
+     * "./public/claude"
+     *
+     * @example
+     * // ❌ 错误：绝对路径（会抛出错误）
+     * "/var/www/agents"           // Unix 绝对路径
+     * "C:\\Users\\agents"         // Windows 绝对路径
+     */
+    target: string;
+    /**
+     * 可选的根目录路径，支持相对路径（如 `../../../` 表示向上三级目录）
+     * @description
+     * - 如果不传入，将自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录
+     * - 相对路径会基于当前工作目录 (process.cwd()) 解析为绝对路径
+     * - 绝对路径将直接使用
+     * @example
+     * // 相对路径：向上三级目录
+     * '../../../'
+     *
+     * // 绝对路径
+     * '/absolute/path/to/monorepo'
+     */
+    rootDir?: string;
+}
+/**
+ * 将 .claude/agents 文件夹复制到指定位置
+ * @param options - 配置选项
+ * @throws {Error} 当 `options.target` 为绝对路径时抛出错误
  * @description
- * 该函数相当于实现 `cpx .claude/agents <target>` 命令
+ * 该函数相当于实现 `cpx .claude/agents <target>` 命令。
+ * 从根目录的 .claude/agents 复制到目标位置。
+ *
+ * **安全限制**：`target` 参数必须是相对路径，禁止使用绝对路径，以防止意外覆盖系统目录。
+ *
+ * @example
+ * // ✅ 自动检测 monorepo 根目录，复制到当前目录的 dist 文件夹
+ * copyClaudeAgents({ target: 'dist' })
+ *
+ * // ✅ 手动指定根目录为向上三级，复制到 build 文件夹
+ * copyClaudeAgents({
+ *   target: 'build',
+ *   rootDir: '../../../'
+ * })
+ *
+ * // ✅ 使用绝对路径指定根目录（rootDir 允许绝对路径）
+ * copyClaudeAgents({
+ *   target: 'dist',  // target 必须是相对路径
+ *   rootDir: '/absolute/path/to/monorepo'  // rootDir 可以是绝对路径
+ * })
+ *
+ * @example
+ * // ❌ 错误用法：target 使用绝对路径会抛出错误
+ * copyClaudeAgents({ target: '/var/www/agents' })  // 抛出 Error
+ * copyClaudeAgents({ target: 'C:\\Windows\\agents' })  // 抛出 Error
  */
-declare function copyClaudeAgents(/** 目标文件夹 */ target: string): void;
+declare function copyClaudeAgents(options: CopyClaudeAgentsOptions): void;
 
 /** 检查当前运行的根目录 是否存在文件名大写的 `README.md` 文件 */
 declare function hasCapitalReadmeMd(): boolean;
@@ -81,4 +168,4 @@ interface AddChangelog2docOptions<T = Record<string, any>> {
 /** 将变更日志添加到指定的文档目录内 并提供参数 */
 declare function addChangelog2doc<T>(options: AddChangelog2docOptions<T>): void;
 
-export { type AddChangelog2docOptions, type PackageInfo, type WriteYaml2mdParams, addChangelog2doc, clean, copyChangelogMd, copyClaudeAgents, copyReadmeMd, defaultCleanTargets, getRuanCatPkgInfo, hasCapitalReadmeMd, hasChangelogMd, hasClaudeAgents, hasLowerCaseReadmeMd, hasReadmeMd, writeYaml2md };
+export { type AddChangelog2docOptions, type CopyClaudeAgentsOptions, type PackageInfo, type WriteYaml2mdParams, addChangelog2doc, clean, copyChangelogMd, copyClaudeAgents, copyReadmeMd, defaultCleanTargets, getRuanCatPkgInfo, hasCapitalReadmeMd, hasChangelogMd, hasClaudeAgents, hasLowerCaseReadmeMd, hasReadmeMd, writeYaml2md };

package/dist/node-esm/index.js

@@ -141,20 +141,58 @@ function copyChangelogMd(target) {
 import fs2 from "fs";
 import path2 from "path";
 import consola4 from "consola";
-function hasClaudeAgents() {
-  const res = fs2.existsSync(path2.resolve(process.cwd(), ".claude/agents"));
-  if (!res) {
-    consola4.log("\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E3A\uFF1A", process.cwd());
-    consola4.warn("\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 .claude/agents \u6587\u4EF6\u5939");
+function findMonorepoRoot() {
+  let currentDir = process.cwd();
+  const root = path2.parse(currentDir).root;
+  while (currentDir !== root) {
+    const workspaceFile2 = path2.join(currentDir, "pnpm-workspace.yaml");
+    if (fs2.existsSync(workspaceFile2)) {
+      return currentDir;
+    }
+    currentDir = path2.dirname(currentDir);
   }
-  return res;
+  const workspaceFile = path2.join(root, "pnpm-workspace.yaml");
+  if (fs2.existsSync(workspaceFile)) {
+    return root;
+  }
+  return null;
 }
-function copyClaudeAgents(target) {
-  if (!hasClaudeAgents()) {
+function resolveRootDir(rootDir) {
+  if (rootDir) {
+    return path2.resolve(process.cwd(), rootDir);
+  }
+  const monorepoRoot = findMonorepoRoot();
+  if (monorepoRoot) {
+    return monorepoRoot;
+  }
+  return process.cwd();
+}
+function hasClaudeAgents(options) {
+  const root = resolveRootDir(options?.rootDir);
+  const claudeAgentsPath = path2.join(root, ".claude/agents");
+  const exists = fs2.existsSync(claudeAgentsPath);
+  if (!exists) {
+    consola4.log("\u68C0\u6D4B\u7684\u6839\u76EE\u5F55\u4E3A\uFF1A", root);
+    consola4.warn("\u8BE5\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 .claude/agents \u6587\u4EF6\u5939");
+  }
+  return exists;
+}
+function copyClaudeAgents(options) {
+  if (path2.isAbsolute(options.target)) {
+    const errorMessage = [
+      `target \u53C2\u6570\u4E0D\u5141\u8BB8\u4F7F\u7528\u7EDD\u5BF9\u8DEF\u5F84\uFF0C\u8FD9\u53EF\u80FD\u5BFC\u81F4\u610F\u5916\u7684\u6587\u4EF6\u8986\u76D6\u3002`,
+      `\u5F53\u524D\u4F20\u5165\u7684\u8DEF\u5F84: "${options.target}"`,
+      `\u8BF7\u4F7F\u7528\u76F8\u5BF9\u8DEF\u5F84\uFF0C\u4F8B\u5982: "src/docs/prompts/agents"`
+    ].join("\n");
+    consola4.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+  if (!hasClaudeAgents({ rootDir: options.rootDir })) {
     return;
   }
-  const source = path2.resolve(process.cwd(), ".claude/agents");
-  const destination = path2.resolve(process.cwd(), target);
+  const root = resolveRootDir(options.rootDir);
+  const source = path2.join(root, ".claude/agents");
+  const destination = path2.resolve(process.cwd(), options.target);
   fs2.mkdirSync(path2.dirname(destination), { recursive: true });
   fs2.cpSync(source, destination, { recursive: true });
   consola4.success(`\u5DF2\u6210\u529F\u590D\u5236 .claude/agents \u5230 ${destination}`);