@ruan-cat/utils 4.20.0 → 4.22.0

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@ruan-cat/utils",
-  "version": "4.20.0",
+  "version": "4.22.0",
   "description": "阮喵喵工具集合。默认提供js文件，也直接提供ts文件。",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "bin": {
+    "ruan-cat-utils": "./dist/cli/index.js",
+    "move-vercel-output-to-root": "./dist/cli/move-vercel-output-to-root.js"
+  },
   "homepage": "https://utils.ruancat6312.top",
   "bugs": {
     "url": "https://github.com/ruan-cat/monorepo/issues"
@@ -29,6 +33,7 @@
       "types": "./dist/node-esm/index.d.ts",
       "import": "./dist/node-esm/index.js"
     },
+    "./monorepo": "./src/monorepo/index.ts",
     "./unplugin-vue-router": "./src/unplugin-vue-router/index.ts",
     "./vite-plugin-autogeneration-import-file": "./src/vite-plugin-autogeneration-import-file/index.ts",
     "./vueuse": "./src/vueuse/index.ts",
@@ -65,31 +70,31 @@
   ],
   "dependencies": {
     "@vueuse/integrations": "^13.9.0",
-    "axios": "^1.13.2",
+    "axios": "^1.13.6",
     "consola": "^3.4.2",
-    "lodash-es": "^4.17.21",
-    "pnpm-workspace-yaml": "^1.4.3",
+    "lodash-es": "^4.17.23",
+    "pnpm-workspace-yaml": "^1.6.0",
     "tinyglobby": "^0.2.15"
   },
   "devDependencies": {
     "@antfu/utils": "^9.3.0",
     "@types/js-yaml": "^4.0.9",
     "@types/lodash-es": "^4.17.12",
-    "@types/node": "^22.19.0",
-    "@types/qs": "^6.14.0",
-    "automd": "^0.4.2",
+    "@types/node": "^22.19.15",
+    "@types/qs": "^6.15.0",
+    "automd": "^0.4.3",
     "commander": "^13.1.0",
-    "js-yaml": "^4.1.0",
-    "qs": "^6.14.0",
-    "tsup": "^8.5.0",
+    "js-yaml": "^4.1.1",
+    "qs": "^6.15.0",
+    "tsup": "^8.5.1",
     "type-plus": "^7.6.2",
-    "typedoc": "^0.28.14",
-    "typedoc-plugin-frontmatter": "^1.3.0",
-    "typedoc-plugin-markdown": "^4.9.0",
+    "typedoc": "^0.28.17",
+    "typedoc-plugin-frontmatter": "^1.3.1",
+    "typedoc-plugin-markdown": "^4.10.0",
     "typescript": "^5.9.3",
-    "unplugin-auto-import": "^20.2.0",
+    "unplugin-auto-import": "^21.0.0",
     "unplugin-vue-router": "^0.16.1",
-    "vite-plugin-autogeneration-import-file": "^3.0.0",
+    "vite-plugin-autogeneration-import-file": "^3.0.1",
     "vitepress": "^1.6.4"
   },
   "peerDependencies": {
@@ -120,6 +125,7 @@
   "scripts": {
     "build": "tsup",
     "prebuild": "automd",
+    "move-vercel-output-to-root": "tsx ./src/node-esm/scripts/move-vercel-output-to-root/index.ts",
     "docs:dev": "turbo docs:dev",
     "build:docs": "turbo do-build-docs",
     "typedoc": "typedoc --options typedoc.config.mjs",

package/src/cli/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @ruan-cat/utils CLI 入口
+ *
+ * @description
+ * 本文件是 @ruan-cat/utils 包的统一 CLI 入口。
+ * 通过 package.json 的 bin 字段暴露为 `ruan-cat-utils` 命令。
+ *
+ * 用法：
+ *   npx ruan-cat-utils <command> [options]
+ *
+ * 支持的子命令：
+ *   move-vercel-output-to-root  将子包的 .vercel/output 搬运到 monorepo 根目录
+ */
+
+import consola from "consola";
+import {
+	getMoveVercelOutputToRootHelpText,
+	runMoveVercelOutputToRootCli,
+} from "../node-esm/scripts/move-vercel-output-to-root/index";
+
+const CLI_NAME = "ruan-cat-utils";
+
+function printMainHelp() {
+	const helpText = [
+		`${CLI_NAME} - @ruan-cat/utils 命令行工具`,
+		"",
+		"用法：",
+		`  ${CLI_NAME} <command> [options]`,
+		"",
+		"可用命令：",
+		"  move-vercel-output-to-root  将子包的 .vercel/output 搬运到 monorepo 根目录",
+		"",
+		"全局选项：",
+		"  -h, --help                  查看帮助信息",
+		"  -v, --version               查看版本号",
+		"",
+		"示例：",
+		`  ${CLI_NAME} move-vercel-output-to-root`,
+		`  ${CLI_NAME} move-vercel-output-to-root --dry-run`,
+		`  ${CLI_NAME} move-vercel-output-to-root --root-dir ../../..`,
+	].join("\n");
+
+	console.log(helpText);
+}
+
+function printVersion() {
+	// 动态读取版本号会引入额外复杂度，这里直接输出包名提示用户查看
+	console.log(`${CLI_NAME} (from @ruan-cat/utils)`);
+	console.log("运行 'npm list @ruan-cat/utils' 查看当前安装的版本。");
+}
+
+function main() {
+	const args = process.argv.slice(2);
+	const command = args[0];
+
+	if (!command || command === "--help" || command === "-h") {
+		printMainHelp();
+		return;
+	}
+
+	if (command === "--version" || command === "-v") {
+		printVersion();
+		return;
+	}
+
+	switch (command) {
+		case "move-vercel-output-to-root": {
+			const subArgs = args.slice(1);
+			try {
+				runMoveVercelOutputToRootCli(subArgs);
+			} catch (error) {
+				consola.error(error instanceof Error ? error.message : String(error));
+				process.exitCode = 1;
+			}
+			break;
+		}
+
+		default: {
+			consola.error(`未知命令：${command}`);
+			console.log("");
+			printMainHelp();
+			process.exitCode = 1;
+		}
+	}
+}
+
+main();

package/src/cli/move-vercel-output-to-root.ts

@@ -0,0 +1,17 @@
+/**
+ * move-vercel-output-to-root 快捷命令入口
+ *
+ * @description
+ * 本文件是 `move-vercel-output-to-root` bin 命令的直接入口。
+ * 安装 @ruan-cat/utils 后，可以直接通过 `npx move-vercel-output-to-root` 调用。
+ */
+
+import consola from "consola";
+import { runMoveVercelOutputToRootCli } from "../node-esm/scripts/move-vercel-output-to-root/index";
+
+try {
+	runMoveVercelOutputToRootCli();
+} catch (error) {
+	consola.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+}

package/src/monorepo/index.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 import * as fs from "node:fs";
 import { globSync } from "tinyglobby";
 import { load } from "js-yaml";
@@ -17,6 +17,33 @@ function pathChange(path: string) {
 	// return normalizePath(path);
 }
 
+/**
+ * 从给定目录开始，向上查找 monorepo 根目录。
+ * @description
+ * 通过查找 `pnpm-workspace.yaml` 文件来定位 monorepo 根目录。
+ * 该函数适用于脚本在 monorepo 子包内运行的场景。
+ *
+ * @param startDir 起始查找目录，默认值为 `process.cwd()`
+ * @returns 找到的 monorepo 根目录绝对路径；若未找到则返回 `null`
+ */
+export function findMonorepoRoot(startDir: string = process.cwd()): string | null {
+	let currentDir = resolve(startDir);
+	const fileSystemRoot = parse(currentDir).root;
+
+	while (true) {
+		const workspaceConfigPath = join(currentDir, "pnpm-workspace.yaml");
+		if (fs.existsSync(workspaceConfigPath)) {
+			return currentDir;
+		}
+
+		if (currentDir === fileSystemRoot) {
+			return null;
+		}
+
+		currentDir = dirname(currentDir);
+	}
+}
+
 /**
  * 判断目标项目是否是 monorepo 格式的项目
  * @description

package/src/node-esm/index.ts

@@ -1,6 +1,7 @@
 export * from "./ruan-cat-pkg-info";
 
 export * from "./scripts/clean";
+export * from "./scripts/move-vercel-output-to-root";
 export * from "./yaml-to-md";
 
 // 导出 monorepo 相关工具函数（仅限 Node.js 环境）

package/src/node-esm/scripts/move-vercel-output-to-root/index.test.ts

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import {
+	moveVercelOutputToRoot,
+	parseMoveVercelOutputToRootCliArgs,
+	resolveMoveVercelOutputToRootOptions,
+} from "./index";
+
+function createMonorepoFixture() {
+	const tempRoot = fs.mkdtempSync(path.join(tmpdir(), "move-vercel-output-to-root-"));
+	const packageDir = path.join(tempRoot, "packages", "demo-app");
+	const packageOutputDir = path.join(packageDir, ".vercel", "output");
+	const rootOutputDir = path.join(tempRoot, ".vercel", "output");
+
+	fs.mkdirSync(packageOutputDir, { recursive: true });
+	fs.mkdirSync(rootOutputDir, { recursive: true });
+	fs.writeFileSync(path.join(tempRoot, "pnpm-workspace.yaml"), "packages:\n  - packages/*\n", "utf8");
+	fs.writeFileSync(path.join(packageDir, "package.json"), '{"name":"demo-app"}', "utf8");
+	fs.writeFileSync(path.join(packageOutputDir, "config.json"), '{"version":3}', "utf8");
+	fs.mkdirSync(path.join(packageOutputDir, "functions"), { recursive: true });
+	fs.writeFileSync(path.join(packageOutputDir, "functions", "index.func"), "hello", "utf8");
+	fs.writeFileSync(path.join(rootOutputDir, "stale.txt"), "old", "utf8");
+
+	return {
+		tempRoot,
+		packageDir,
+		packageOutputDir,
+		rootOutputDir,
+	};
+}
+
+describe("move-vercel-output-to-root", () => {
+	const temporaryDirectories = new Set<string>();
+
+	beforeEach(() => {
+		temporaryDirectories.clear();
+	});
+
+	afterEach(() => {
+		for (const tempDirectory of temporaryDirectories) {
+			fs.rmSync(tempDirectory, {
+				force: true,
+				recursive: true,
+			});
+		}
+	});
+
+	describe("resolveMoveVercelOutputToRootOptions", () => {
+		test("应该能从子包目录自动解析 monorepo 根目录与默认路径", () => {
+			const fixture = createMonorepoFixture();
+			temporaryDirectories.add(fixture.tempRoot);
+
+			const resolvedOptions = resolveMoveVercelOutputToRootOptions({
+				cwd: fixture.packageDir,
+			});
+
+			expect(resolvedOptions.monorepoRoot).toBe(fixture.tempRoot);
+			expect(resolvedOptions.sourceDir).toBe(path.join(fixture.packageDir, ".vercel", "output"));
+			expect(resolvedOptions.targetDir).toBe(path.join(fixture.tempRoot, ".vercel", "output"));
+			expect(resolvedOptions.skipClean).toBe(false);
+			expect(resolvedOptions.dryRun).toBe(false);
+		});
+
+		test("当 sourceDir 和 targetDir 解析到同一路径时应该抛出错误", () => {
+			const fixture = createMonorepoFixture();
+			temporaryDirectories.add(fixture.tempRoot);
+
+			expect(() =>
+				resolveMoveVercelOutputToRootOptions({
+					cwd: fixture.packageDir,
+					targetDir: path.relative(fixture.tempRoot, fixture.packageOutputDir),
+				}),
+			).toThrow("源目录和目标目录解析到了同一路径");
+		});
+	});
+
+	describe("moveVercelOutputToRoot", () => {
+		test("默认应该清空根目录旧产物并复制当前子包的 vercel 输出目录内容", () => {
+			const fixture = createMonorepoFixture();
+			temporaryDirectories.add(fixture.tempRoot);
+
+			const result = moveVercelOutputToRoot({
+				cwd: fixture.packageDir,
+			});
+
+			expect(result.copied).toBe(true);
+			expect(fs.existsSync(path.join(fixture.rootOutputDir, "stale.txt"))).toBe(false);
+			expect(fs.readFileSync(path.join(fixture.rootOutputDir, "config.json"), "utf8")).toBe('{"version":3}');
+			expect(fs.readFileSync(path.join(fixture.rootOutputDir, "functions", "index.func"), "utf8")).toBe("hello");
+		});
+
+		test("dry-run 模式下不应该修改根目录内容", () => {
+			const fixture = createMonorepoFixture();
+			temporaryDirectories.add(fixture.tempRoot);
+
+			const result = moveVercelOutputToRoot({
+				cwd: fixture.packageDir,
+				dryRun: true,
+			});
+
+			expect(result.copied).toBe(false);
+			expect(fs.existsSync(path.join(fixture.rootOutputDir, "stale.txt"))).toBe(true);
+			expect(fs.existsSync(path.join(fixture.rootOutputDir, "config.json"))).toBe(false);
+		});
+
+		test("应该支持自定义 sourceDir 与 targetDir", () => {
+			const fixture = createMonorepoFixture();
+			temporaryDirectories.add(fixture.tempRoot);
+
+			const customSourceDir = path.join(fixture.packageDir, "custom-output");
+			const customTargetDir = path.join(fixture.tempRoot, "deploy-output");
+			fs.mkdirSync(customSourceDir, { recursive: true });
+			fs.writeFileSync(path.join(customSourceDir, "routes.json"), '{"routes":[]}', "utf8");
+
+			const result = moveVercelOutputToRoot({
+				cwd: fixture.packageDir,
+				sourceDir: "custom-output",
+				targetDir: "deploy-output",
+			});
+
+			expect(result.sourceDir).toBe(customSourceDir);
+			expect(result.targetDir).toBe(customTargetDir);
+			expect(fs.readFileSync(path.join(customTargetDir, "routes.json"), "utf8")).toBe('{"routes":[]}');
+		});
+	});
+
+	describe("parseMoveVercelOutputToRootCliArgs", () => {
+		test("应该正确解析命令行参数", () => {
+			const parsedOptions = parseMoveVercelOutputToRootCliArgs([
+				"--root-dir",
+				"../../..",
+				"--source-dir",
+				".vercel/output",
+				"--target-dir",
+				"deploy-output",
+				"--skip-clean",
+				"--dry-run",
+			]);
+
+			expect(parsedOptions).toEqual({
+				rootDir: "../../..",
+				sourceDir: ".vercel/output",
+				targetDir: "deploy-output",
+				skipClean: true,
+				dryRun: true,
+			});
+		});
+	});
+});

package/src/node-esm/scripts/move-vercel-output-to-root/index.ts

@@ -0,0 +1,286 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import consola from "consola";
+import { findMonorepoRoot } from "../../../monorepo";
+
+export interface MoveVercelOutputToRootOptions {
+	/**
+	 * 运行目录。
+	 * 默认值为 `process.cwd()`。
+	 */
+	cwd?: string;
+
+	/**
+	 * monorepo 根目录。
+	 * 不传时会从 `cwd` 开始，向上查找 `pnpm-workspace.yaml`。
+	 */
+	rootDir?: string;
+
+	/**
+	 * 子包内构建产物目录。
+	 * 相对路径基于 `cwd` 解析。
+	 *
+	 * @default ".vercel/output"
+	 */
+	sourceDir?: string;
+
+	/**
+	 * monorepo 根目录内的目标输出目录。
+	 * 相对路径基于 monorepo 根目录解析。
+	 *
+	 * @default ".vercel/output"
+	 */
+	targetDir?: string;
+
+	/**
+	 * 是否跳过目标目录清理。
+	 *
+	 * @default false
+	 */
+	skipClean?: boolean;
+
+	/**
+	 * 仅打印解析结果，不实际复制文件。
+	 *
+	 * @default false
+	 */
+	dryRun?: boolean;
+}
+
+export interface ResolvedMoveVercelOutputToRootOptions {
+	cwd: string;
+	monorepoRoot: string;
+	sourceDir: string;
+	targetDir: string;
+	skipClean: boolean;
+	dryRun: boolean;
+}
+
+export interface MoveVercelOutputToRootResult extends ResolvedMoveVercelOutputToRootOptions {
+	copied: boolean;
+}
+
+/**
+ * 将路径解析为绝对路径。
+ */
+function resolvePathFromBase(baseDir: string, inputPath: string) {
+	if (path.isAbsolute(inputPath)) {
+		return path.normalize(inputPath);
+	}
+
+	return path.resolve(baseDir, inputPath);
+}
+
+/**
+ * 解析 monorepo 根目录。
+ */
+function resolveMonorepoRoot(cwd: string, rootDir?: string) {
+	if (rootDir) {
+		const resolvedRoot = resolvePathFromBase(cwd, rootDir);
+		const workspaceConfigPath = path.join(resolvedRoot, "pnpm-workspace.yaml");
+		if (!fs.existsSync(workspaceConfigPath)) {
+			throw new Error(`指定的 rootDir 不是有效的 monorepo 根目录：${resolvedRoot}。缺少 pnpm-workspace.yaml。`);
+		}
+		return resolvedRoot;
+	}
+
+	const detectedRoot = findMonorepoRoot(cwd);
+	if (detectedRoot) {
+		return detectedRoot;
+	}
+
+	throw new Error(`无法从当前目录向上定位 monorepo 根目录：${cwd}。请显式传入 --root-dir 参数。`);
+}
+
+/**
+ * 解析脚本所需的全部路径。
+ */
+export function resolveMoveVercelOutputToRootOptions(
+	options: MoveVercelOutputToRootOptions = {},
+): ResolvedMoveVercelOutputToRootOptions {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const monorepoRoot = resolveMonorepoRoot(cwd, options.rootDir);
+	const sourceDir = resolvePathFromBase(cwd, options.sourceDir ?? ".vercel/output");
+	const targetDir = resolvePathFromBase(monorepoRoot, options.targetDir ?? ".vercel/output");
+
+	if (sourceDir === targetDir) {
+		throw new Error(`源目录和目标目录解析到了同一路径：${sourceDir}。请调整 sourceDir 或 targetDir。`);
+	}
+
+	return {
+		cwd,
+		monorepoRoot,
+		sourceDir,
+		targetDir,
+		skipClean: options.skipClean ?? false,
+		dryRun: options.dryRun ?? false,
+	};
+}
+
+/**
+ * 复制目录内容，而不是把源目录本身嵌套复制进去。
+ */
+function copyDirectoryContents(sourceDir: string, targetDir: string) {
+	fs.mkdirSync(targetDir, { recursive: true });
+
+	for (const entryName of fs.readdirSync(sourceDir)) {
+		const sourceEntry = path.join(sourceDir, entryName);
+		const targetEntry = path.join(targetDir, entryName);
+		fs.cpSync(sourceEntry, targetEntry, {
+			force: true,
+			recursive: true,
+		});
+	}
+}
+
+/**
+ * 将当前子包内的 `.vercel/output` 移动到 monorepo 根目录。
+ * @description
+ * 该函数服务于 Vercel 在 monorepo 场景下的部署：
+ * 1. 构建仍在子包目录内执行
+ * 2. 产物默认出现在子包的 `.vercel/output`
+ * 3. Vercel 却要求在 monorepo 根目录下读取 `.vercel/output`
+ */
+export function moveVercelOutputToRoot(options: MoveVercelOutputToRootOptions = {}): MoveVercelOutputToRootResult {
+	const resolvedOptions = resolveMoveVercelOutputToRootOptions(options);
+
+	if (!fs.existsSync(resolvedOptions.sourceDir)) {
+		throw new Error(`源目录不存在，无法搬运 Vercel 构建产物：${resolvedOptions.sourceDir}。请先在子包内完成构建。`);
+	}
+
+	if (!fs.statSync(resolvedOptions.sourceDir).isDirectory()) {
+		throw new Error(`源路径不是目录：${resolvedOptions.sourceDir}`);
+	}
+
+	consola.info("move-vercel-output-to-root 解析结果");
+	consola.log(`- cwd: ${resolvedOptions.cwd}`);
+	consola.log(`- monorepoRoot: ${resolvedOptions.monorepoRoot}`);
+	consola.log(`- sourceDir: ${resolvedOptions.sourceDir}`);
+	consola.log(`- targetDir: ${resolvedOptions.targetDir}`);
+	consola.log(`- skipClean: ${resolvedOptions.skipClean}`);
+	consola.log(`- dryRun: ${resolvedOptions.dryRun}`);
+
+	if (resolvedOptions.dryRun) {
+		consola.info("dry-run 模式：仅输出路径信息，不执行复制。");
+		return {
+			...resolvedOptions,
+			copied: false,
+		};
+	}
+
+	if (!resolvedOptions.skipClean) {
+		fs.rmSync(resolvedOptions.targetDir, {
+			force: true,
+			recursive: true,
+		});
+	}
+
+	copyDirectoryContents(resolvedOptions.sourceDir, resolvedOptions.targetDir);
+
+	consola.success(`已将 ${resolvedOptions.sourceDir} 搬运到 ${resolvedOptions.targetDir}`);
+
+	return {
+		...resolvedOptions,
+		copied: true,
+	};
+}
+
+/**
+ * 解析命令行参数。
+ */
+export function parseMoveVercelOutputToRootCliArgs(args: string[]): MoveVercelOutputToRootOptions & { help?: boolean } {
+	const options: MoveVercelOutputToRootOptions & { help?: boolean } = {};
+	const readFlagValue = (flagName: string, currentIndex: number) => {
+		const value = args[currentIndex + 1];
+		if (!value || value.startsWith("--")) {
+			throw new Error(`参数 ${flagName} 缺少对应的值。`);
+		}
+
+		return value;
+	};
+
+	for (let index = 0; index < args.length; index += 1) {
+		const currentArg = args[index];
+
+		switch (currentArg) {
+			case "--root-dir":
+				options.rootDir = readFlagValue(currentArg, index);
+				index += 1;
+				break;
+			case "--source-dir":
+				options.sourceDir = readFlagValue(currentArg, index);
+				index += 1;
+				break;
+			case "--target-dir":
+				options.targetDir = readFlagValue(currentArg, index);
+				index += 1;
+				break;
+			case "--skip-clean":
+				options.skipClean = true;
+				break;
+			case "--dry-run":
+				options.dryRun = true;
+				break;
+			case "--help":
+			case "-h":
+				options.help = true;
+				break;
+			default:
+				throw new Error(`不支持的参数：${currentArg}`);
+		}
+	}
+
+	return options;
+}
+
+/**
+ * CLI 帮助信息。
+ */
+export function getMoveVercelOutputToRootHelpText() {
+	return [
+		"move-vercel-output-to-root [options]",
+		"",
+		"选项：",
+		"  --root-dir <path>    显式指定 monorepo 根目录",
+		"  --source-dir <path>  指定子包内构建产物目录，默认 .vercel/output",
+		"  --target-dir <path>  指定根目录内目标目录，默认 .vercel/output",
+		"  --skip-clean         跳过目标目录清理",
+		"  --dry-run            仅打印路径解析结果，不执行复制",
+		"  -h, --help           查看帮助信息",
+	].join("\n");
+}
+
+/**
+ * 执行 CLI。
+ */
+export function runMoveVercelOutputToRootCli(args: string[] = process.argv.slice(2)) {
+	const cliOptions = parseMoveVercelOutputToRootCliArgs(args);
+
+	if (cliOptions.help) {
+		console.log(getMoveVercelOutputToRootHelpText());
+		return;
+	}
+
+	moveVercelOutputToRoot(cliOptions);
+}
+
+function isRunningAsCli() {
+	const currentFilePath = fileURLToPath(import.meta.url);
+	const entryPath = process.argv[1];
+
+	if (!entryPath) {
+		return false;
+	}
+
+	return path.resolve(entryPath) === currentFilePath;
+}
+
+if (isRunningAsCli()) {
+	try {
+		runMoveVercelOutputToRootCli();
+	} catch (error) {
+		consola.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+}