@ruan-cat/utils 4.19.0 → 4.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruan-cat/utils",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "阮喵喵工具集合。默认提供js文件，也直接提供ts文件。",
   "type": "module",
   "main": "./src/index.ts",
@@ -29,6 +29,8 @@
       "types": "./dist/node-esm/index.d.ts",
       "import": "./dist/node-esm/index.js"
     },
+    "./monorepo": "./src/monorepo/index.ts",
+    "./move-vercel-output-to-root": "./src/node-esm/scripts/move-vercel-output-to-root/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,30 +67,31 @@
   ],
   "dependencies": {
     "@vueuse/integrations": "^13.9.0",
-    "axios": "^1.13.2",
+    "axios": "^1.13.6",
     "consola": "^3.4.2",
-    "tinyglobby": "^0.2.15",
-    "lodash-es": "^4.17.21"
+    "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": {
@@ -119,6 +122,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/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 [
+		"tsx @ruan-cat/utils/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;
+	}
+}

package/src/types/pnpm-workspace.yaml.shim.ts

@@ -1,22 +1,10 @@
+import type { PnpmWorkspaceYamlSchema } from "pnpm-workspace-yaml";
+
 /**
  * pnpm-workspace.yaml 文件的类型声明
  * @description
- * 设计理由
- *
- * 主要是为了让该文件被解析后，能够有一个基础的类型声明
+ * 现在是 pnpm-workspace-yaml 提供的 `PnpmWorkspaceYamlSchema` 类型
  *
- * 按理说这个东西应该有别人封装好的类型的，肯定因为我没找到。
- *
- * 未来应该找到这样的类型声明库，直接复用别人的就好了，不要自己写了。
+ * @see https://github.com/antfu/pnpm-workspace-utils/blob/main/packages/pnpm-workspace-yaml/src/index.ts#L4
  */
-export interface PnpmWorkspace {
-	/**
-	 * 包的匹配语法字符串
-	 *
-	 * @example
-	 * ["packages/**", "demos/**", "utils"]
-	 */
-	packages?: string[];
-
-	catalog?: string[];
-}
+export type PnpmWorkspace = PnpmWorkspaceYamlSchema;