@peiyanlu/cli-utils 0.0.4 → 0.0.6

package/dist/index.mjs

@@ -0,0 +1,1115 @@
+import { existsSync, readFileSync } from "node:fs";
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { EOL } from "node:os";
+import { join, resolve } from "node:path";
+import { exec, execSync, spawn, spawnSync } from "node:child_process";
+import { styleText } from "node:util";
+
+//#region src/enums.ts
+let PkgManager = /* @__PURE__ */ function(PkgManager$1) {
+	PkgManager$1["NPM"] = "npm";
+	PkgManager$1["YARN"] = "yarn";
+	PkgManager$1["PNPM"] = "pnpm";
+	return PkgManager$1;
+}({});
+/**
+* @deprecated Use `ConfirmResult` instead.
+*/
+let YesOrNo = /* @__PURE__ */ function(YesOrNo$1) {
+	YesOrNo$1["Yes"] = "yes";
+	YesOrNo$1["No"] = "no";
+	YesOrNo$1["Ignore"] = "ignore";
+	return YesOrNo$1;
+}({});
+let ConfirmResult = /* @__PURE__ */ function(ConfirmResult$1) {
+	ConfirmResult$1["YES"] = "yes";
+	ConfirmResult$1["NO"] = "no";
+	ConfirmResult$1["IGNORE"] = "ignore";
+	return ConfirmResult$1;
+}({});
+let HttpLibrary = /* @__PURE__ */ function(HttpLibrary$1) {
+	HttpLibrary$1["EXPRESS"] = "express";
+	HttpLibrary$1["FASTIFY"] = "fastify";
+	HttpLibrary$1["KOA"] = "koa";
+	HttpLibrary$1["HONO"] = "hono";
+	return HttpLibrary$1;
+}({});
+
+//#endregion
+//#region src/styleText.ts
+const dim = (text) => styleText(["dim"], text);
+const red = (text) => styleText(["red"], text);
+
+//#endregion
+//#region src/shell.ts
+/** 异步执行 `spawn` 获取字符串类型的结果 */
+const spawnAsync = (cmd, args, options) => {
+	return new Promise((resolve$1, reject) => {
+		const { trim, error, dryRun, ...others } = options ?? {};
+		const fullCmd = stringifyArgs([cmd, ...args]);
+		if (dryRun) {
+			console.log(`${dim("[dry-run]")} ${fullCmd}`);
+			return resolve$1(void 0);
+		}
+		const child = spawn(cmd, args, { ...others });
+		let stdout = "";
+		child.stdout?.setEncoding("utf-8");
+		child.stdout?.on("data", (d) => {
+			stdout += trim ? d.trim() : d;
+		});
+		let stderr = "";
+		child.stderr?.setEncoding("utf-8");
+		child.stderr?.on("data", (d) => {
+			stderr += trim ? d.trim() : d;
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code !== 0) {
+				const msg = `${red("spawnAsync")} ${dim(fullCmd)} ${stderr}`;
+				if (error === "log") {
+					console.error(msg);
+					return resolve$1(void 0);
+				}
+				if (error === "throw") return reject(new Error(msg));
+				return resolve$1(void 0);
+			}
+			resolve$1(stdout);
+		});
+	});
+};
+/** 异步执行 `exec` 获取字符串类型的结果 */
+const execAsync = (cmd, argsOrOptions, maybeOptions) => {
+	return new Promise((resolve$1, reject) => {
+		let command;
+		let options;
+		if (Array.isArray(argsOrOptions)) {
+			command = stringifyArgs([cmd, ...argsOrOptions]);
+			options = maybeOptions;
+		} else {
+			command = cmd;
+			options = argsOrOptions;
+		}
+		const { trim, dryRun, error, ...others } = options ?? {};
+		if (dryRun) {
+			console.log(`${dim("[dry-run]")} ${command}`);
+			return resolve$1(void 0);
+		}
+		exec(command, { ...others }, (err, stdout, stderr) => {
+			if (err) {
+				const msg = `${red("execAsync")} ${dim(command)} ${stderr || err.message}`;
+				if (error === "log") {
+					console.error(msg);
+					return resolve$1(void 0);
+				}
+				if (error === "throw") return reject(new Error(msg));
+				return resolve$1(void 0);
+			}
+			resolve$1(trim ? stdout.trim() : stdout);
+		});
+	});
+};
+/** 执行 `spawnSync` 获取字符串类型的结果 */
+const spawnSyncWithString = (cmd, args, options) => {
+	const { trim, error, dryRun, ...others } = options ?? {};
+	const fullCmd = stringifyArgs([cmd, ...args]);
+	if (dryRun) {
+		console.log(`${dim("[dry-run]")} ${fullCmd}`);
+		return;
+	}
+	const { stdout, stderr, status, error: err } = spawnSync(cmd, args, {
+		encoding: "utf-8",
+		...others
+	});
+	if (status !== 0 || err) {
+		const detail = err?.message || stderr?.toString?.() || "";
+		const msg = `${red("spawnSync")} ${dim(fullCmd)} ${detail}`;
+		if (error === "log") {
+			console.error(msg);
+			return;
+		}
+		if (error === "throw") throw new Error(msg);
+		return;
+	}
+	return trim ? stdout.trim() : stdout;
+};
+/** 执行 `execSync` 获取字符串类型的结果 */
+const execSyncWithString = (cmd, argsOrOptions, maybeOptions) => {
+	let command;
+	let options;
+	if (Array.isArray(argsOrOptions)) {
+		command = stringifyArgs([cmd, ...argsOrOptions]);
+		options = maybeOptions;
+	} else {
+		command = cmd;
+		options = argsOrOptions;
+	}
+	const { trim, dryRun, error, ...others } = options ?? {};
+	if (dryRun) {
+		console.log(`${dim("[dry-run]")} ${command}`);
+		return;
+	}
+	try {
+		const stdout = execSync(command, {
+			encoding: "utf-8",
+			...others
+		});
+		return trim ? stdout.trim() : stdout;
+	} catch (e) {
+		const stderr = e?.stderr?.toString?.() || e?.message || "";
+		const msg = `${red("execSync")} ${dim(command)} ${stderr}`;
+		if (error === "log") {
+			console.error(msg);
+			return;
+		}
+		if (error === "throw") throw new Error(msg);
+		return;
+	}
+};
+/** 基于 {@link spawnAsync} 实现 */
+const runGit = async (args, options = { trim: true }) => {
+	return spawnAsync("git", args, options);
+};
+/** 基于 {@link spawnSyncWithString} 实现 */
+const runGitSync = (args, options) => {
+	return spawnSyncWithString("git", args, { ...options });
+};
+/** 基于 {@link execAsync} 实现 */
+const runNpm = (args, options = { trim: true }) => {
+	return execAsync("npm", args, options);
+};
+/** 基于 {@link execSyncWithString} 实现 */
+const runNpmSync = (args, options) => {
+	return execSyncWithString("npm", args, { ...options });
+};
+/** 基于 {@link spawnAsync} 实现 */
+const runNode = (args, options) => {
+	return spawnAsync("node", args, options);
+};
+/** 基于 {@link spawnSyncWithString} 实现 */
+const runNodeSync = (args, options) => {
+	return spawnSyncWithString("node", args, options);
+};
+/** 支持所有支持 `--version` 命令的脚本查看版本 */
+const checkVersion = async (cmd) => {
+	return execAsync(`${cmd} --version`);
+};
+
+//#endregion
+//#region src/utils.ts
+const isValidPackageName = (packageName) => {
+	return /^(?:@[a-z\d\-*~][a-z\d\-*._~]*\/)?[a-z\d\-~][a-z\d\-._~]*$/.test(packageName);
+};
+const toValidPackageName = (packageName) => packageName.trim().toLowerCase().replace(/\s+/g, "-").replace(/^[._]/, "").replace(/[^a-z\d\-~]+/g, "-");
+const toValidProjectName = (projectName) => projectName.trim().replace(/\/+$/g, "");
+const emptyDir = async (dir, ignore = []) => {
+	if (!existsSync(dir)) return false;
+	for (const file of await readdir(dir)) {
+		if (ignore.includes(file)) continue;
+		await rm(resolve(dir, file), {
+			recursive: true,
+			force: true
+		});
+	}
+	return true;
+};
+const isEmpty = async (path, ignore = []) => {
+	return (await readdir(path)).filter((f) => !ignore.includes(f)).length === 0;
+};
+const editFile = async (file, callback) => {
+	if (!existsSync(file)) return;
+	return writeFile(file, callback(await readFile(file, "utf-8")), "utf-8");
+};
+const editJsonFile = (file, callback) => {
+	return editFile(file, (str) => {
+		try {
+			const json = JSON.parse(str);
+			callback(json);
+			return JSON.stringify(json, null, 2);
+		} catch (e) {
+			console.error(e);
+			return str;
+		}
+	});
+};
+const readSubDirs = async (source, ignore = []) => {
+	return (await readdir(source, { withFileTypes: true })).filter((k) => k.isDirectory() && !ignore.includes(k.name)).map((dir) => dir.name);
+};
+const copyDirAsync = async (src, dest, options) => {
+	await mkdir(dest, { recursive: true });
+	const entries = await readdir(src, { withFileTypes: true });
+	for (const entry of entries) {
+		const name = entry.name;
+		const isDir = entry.isDirectory();
+		const { rename = {}, skips = [] } = options;
+		const relName = rename[name] ?? name;
+		if (skips.some((rule) => rule(name, isDir))) continue;
+		const from = join(src, name);
+		const to = join(dest, relName);
+		if (isDir) await copyDirAsync(from, to, options);
+		else await copyFile(from, to);
+	}
+};
+const readJsonFile = (file) => {
+	if (!existsSync(file)) return {};
+	try {
+		return JSON.parse(readFileSync(file, "utf-8"));
+	} catch (e) {
+		return {};
+	}
+};
+const getPackageInfo = (pkgName, getPkgDir) => {
+	const pkgDir = resolve(getPkgDir(pkgName));
+	const pkgPath = resolve(pkgDir, "package.json");
+	return {
+		pkg: readJsonFile(pkgPath),
+		pkgDir,
+		pkgPath
+	};
+};
+/** 通过包管理器执行脚本时生效 UserAgent: `process.env.npm_config_user_agent` */
+const pkgFromUserAgent = (userAgent) => {
+	if (!userAgent) return void 0;
+	const [name, version] = userAgent.split(" ")[0].split("/");
+	return {
+		name,
+		version
+	};
+};
+/** 同步执行 Node CLI（用于测试环境） */
+const runCliForTest = (path, args = [], options) => {
+	return runNodeSync([path, ...args], {
+		env: {
+			...process.env,
+			_VITE_TEST_CLI: "true"
+		},
+		...options
+	});
+};
+/** 判断测试文件（夹） */
+const isTestFile = (name) => {
+	return [
+		/(^|[\\/])(test(s?)|__test(s?)__)([\\/]|$)/,
+		/\.([a-zA-Z0-9]+-)?(test|spec)\.m?(ts|js)$/,
+		/^vitest([-.])(.*)\.m?(ts|js)$/
+	].some((reg) => reg.test(name));
+};
+/** 解析 Github 链接获取 owner 和 repo */
+const parseGitHubRepo = (url) => {
+	const match = url.trim().match(/github(?:\.com)?[:/](.+?)\/(.+?)(?:[#/?].+?)?(?:\.git)?$/);
+	return match ? match.slice(1, 3) : [];
+};
+/** 基于 EOL 的可多换行函数 */
+const eol = (n = 1) => EOL.repeat(n);
+/** 多空格函数 */
+const space = (n = 1) => " ".repeat(n);
+/** 将字符串以空格分割为数组 */
+const parseArgs = (args) => args.trim() ? args.trim().split(space()) : [];
+/** 将数组以空格拼接为字符串 */
+const stringifyArgs = (args) => args.length ? args.join(space()) : "";
+/** 去掉模板字符串首尾换行 */
+const trimTemplate = (str) => str.replace(/^\s*\n+|\n+\s*$/g, "");
+/** 生成 GitHub 仓库主页地址 */
+const getGithubUrl = (owner, repo) => {
+	return `https://github.com/${owner}/${repo}`;
+};
+/** 生成 GitHub Release 页面地址 */
+const getGithubReleaseUrl = (owner, repo, tag) => {
+	return `${getGithubUrl(owner, repo)}/releases/tag/${encodeURIComponent(tag)}`;
+};
+/** 生成 npm 包指定版本的详情页地址 */
+const getPackageUrl = (pkg, version) => {
+	return `https://www.npmjs.com/package/${pkg}/v/${version}`;
+};
+
+//#endregion
+//#region src/joinUrl.ts
+function joinUrl(input) {
+	const temps = Array.isArray(input) ? input : [...arguments];
+	if (temps.length === 0) return "";
+	const result = [];
+	const parts = [...temps];
+	/** 协议正则 */
+	const PROTOCOL_RE = /^[^/:]+:\/*$/;
+	const FILE_PROTOCOL_RE = /^file:\/\/\//;
+	if (PROTOCOL_RE.test(parts[0]) && parts.length > 1) {
+		parts[1] = parts[0] + parts[1];
+		parts.shift();
+	}
+	if (FILE_PROTOCOL_RE.test(parts[0])) parts[0] = parts[0].replace(/^([^/:]+):\/*/, "$1:///");
+	else parts[0] = parts[0].replace(/^([^/:]+):\/*/, "$1://");
+	parts.forEach((part, index) => {
+		if (!part) return;
+		let segment = part;
+		if (index > 0) segment = segment.replace(/^\/+/, "");
+		if (index < parts.length - 1) segment = segment.replace(/\/+$/, "");
+		else segment = segment.replace(/\/+$/, "/");
+		result.push(segment);
+	});
+	let url = result.join("/");
+	url = url.replace(/\/(\?|&|#[^!])/g, "$1");
+	const [base, ...queryParts] = url.split("?");
+	url = base + (queryParts.length ? "?" + queryParts.join("&") : "");
+	return url;
+}
+
+//#endregion
+//#region src/git.ts
+/** 判断指定目录是否是 git 仓库 */
+const isGitRepo = async (dir = ".") => {
+	const target = resolve(process.cwd(), dir);
+	return "true" === await runGit([
+		"-C",
+		target,
+		"rev-parse",
+		"--is-inside-work-tree"
+	]).catch((err) => {
+		if (err?.message?.includes("safe.directory")) console.warn(`⚠️ Git safe.directory restrictions: Please run:\ngit config --global --add safe.directory ${target}`);
+		return false;
+	});
+};
+/** 获取指定的 git 配置 */
+const getGitConfig = (key, global = true) => {
+	return runGit([
+		"config",
+		...global ? ["--global"] : [],
+		key
+	]);
+};
+/** 获取 git 远程地址 */
+const getGitRemoteUrl = async (remoteName = "origin") => {
+	return runGit([
+		"remote",
+		"get-url",
+		remoteName
+	]).catch((_) => runGit([
+		"config",
+		"--get",
+		`remote.${remoteName}.url`
+	]));
+};
+/** 获取当前分支 */
+const getCurrentBranch = async () => {
+	let branch = await runGit(["branch", "--show-current"]);
+	if (!branch) {
+		branch = await runGit([
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		]);
+		if (branch === "HEAD") return void 0;
+	}
+	return branch;
+};
+/** 获取分支关联的远程地址 */
+const getRemoteForBranch = (branch) => {
+	return runGit([
+		"config",
+		"--get",
+		`branch.${branch}.remote`
+	]);
+};
+/** 获取关联的所有远程地址 */
+const getAllRemotes = async () => {
+	return (await runGit(["remote"]))?.split("\n").filter(Boolean) ?? [];
+};
+/** 获取默认的远程地址 */
+const getDefaultRemote = async (branch) => {
+	const targetBranch = branch || await getCurrentBranch();
+	return targetBranch ? await getRemoteForBranch(targetBranch) : void 0;
+};
+/** 获取默认远程地址之外的远程地址 */
+const getOtherRemotes = async (branch) => {
+	const defaultRemote = await getDefaultRemote(branch);
+	return (await getAllRemotes()).filter((r) => r !== defaultRemote);
+};
+/** 提取所有分支 */
+const fetchAllBranch = (remoteName = "origin") => {
+	return runGit([
+		"fetch",
+		remoteName,
+		"--recurse-submodules=no",
+		"--prune"
+	]);
+};
+/**
+* 获取本地所有 tag
+* @returns {Promise<string[]>}
+* @defaults git tag --list
+*/
+const getLocalTags = async () => {
+	const tags = await runGit(["tag", "--list"]);
+	return tags ? tags.split("\n").filter(Boolean) : [];
+};
+/** 获取远程 tags */
+const getSortedTags = async (match = "*", exclude = "*-beta.*", sort = "v:refname", count = 0) => {
+	const res = await runGit([
+		"for-each-ref",
+		"--format=%(refname:short)",
+		`--sort=-${sort}`,
+		`--exclude=${exclude}`,
+		`--count=${count}`,
+		`refs/tags/${match}`
+	]);
+	return res ? res.split("\n").filter(Boolean) : [];
+};
+/**
+* 获取远程（或所有 refs）中的 tag
+* 使用 for-each-ref 以支持版本号排序
+* @param {string} match 默认 *
+* @param {string} exclude 默认 beta
+* @returns {Promise<string[]>}
+* @defaults git for-each-ref --sort=-v:refname --format=%(refname:short) refs/tags/<match>
+*/
+const getRemoteTags = async (match = "*", exclude = "*-beta.*") => {
+	return getSortedTags(match, exclude);
+};
+/**
+* 获取当前工作区状态（不包含未跟踪文件）
+* @returns {Promise<string | undefined>}
+* @defaults git status --short --untracked-files=no
+*/
+const getStatus = () => {
+	return runGit([
+		"status",
+		"--short",
+		"--untracked-files=no"
+	], { trim: false });
+};
+/**
+* 为 git status / changeset 输出添加颜色
+*
+* M -> 黄色（修改）
+* A -> 绿色（新增）
+* D -> 红色（删除）
+* @param {string} log git status --short 输出
+* @returns {string}
+*/
+const coloredChangeset = (log) => {
+	const colorStatusChar = (ch) => {
+		switch (ch) {
+			case "M": return `\x1b[33m${ch}\x1b[0m\x1b[2m`;
+			case "A": return `\x1b[32m${ch}\x1b[0m\x1b[2m`;
+			case "D": return `\x1b[31m${ch}\x1b[0m\x1b[2m`;
+			default: return ch;
+		}
+	};
+	const colorStatus = (status) => status.split("").map(colorStatusChar).join("");
+	return log.split("\n").filter(Boolean).map((line) => {
+		const status = line.slice(0, 2);
+		const file = line.slice(3);
+		return `${colorStatus(status)} ${file}`;
+	}).join("\n");
+};
+/**
+* 获取当前分支对应的远程信息
+* @returns {Promise<{remoteName: string, remoteUrl: string | undefined}>}
+*/
+const getRemote = async () => {
+	const branch = await getCurrentBranch();
+	const remoteName = branch && await getRemoteForBranch(branch) || "origin";
+	return {
+		remoteName,
+		remoteUrl: await runGit([
+			"remote",
+			"get-url",
+			remoteName
+		]).catch((_) => runGit([
+			"config",
+			"--get",
+			`remote.${remoteName}.url`
+		]))
+	};
+};
+/**
+* 获取最新 tag
+*
+* 默认：
+* - 匹配所有 tag
+* - 排除 beta 版本
+* @param {string} match 默认 *
+* @param {string} exclude 默认 beta
+* @returns {Promise<string | undefined>}
+*/
+const getLatestTag = async (match = "*", exclude = "*-beta.*") => {
+	const [latestTag] = await getSortedTags(match, exclude, void 0, 1);
+	return latestTag;
+};
+/**
+* 获取上一个 tag
+*
+* 默认：
+* - 匹配所有 tag
+* - 排除 beta 版本
+* @param {string} latestTag
+* @param {string} match 默认 *
+* @param {string} exclude 默认 beta
+* @returns {Promise<string | undefined>}
+*/
+const getPreviousTag = async (latestTag, match = "*", exclude = "*-beta.*") => {
+	const all = await getSortedTags(match, exclude, void 0, 2);
+	return all[all.findIndex((k) => latestTag === k) + 1];
+};
+/**
+* 计算 changelog 的 commit 范围
+* @param {boolean} isIncrement 是否为版本递增发布
+* @param {string} match tag match
+* @param {string} exclude tag exclude
+* @returns {Promise<{from: string, to: string}>}
+*/
+const resolveChangelogRange = async (isIncrement = true, match = "*", exclude = "*-beta.*") => {
+	const latestTag = await getLatestTag(match, exclude);
+	if (!latestTag) return {
+		from: "",
+		to: "HEAD"
+	};
+	const previousTag = await getPreviousTag(latestTag);
+	if (!isIncrement && previousTag) return {
+		from: previousTag,
+		to: `${latestTag}^1`
+	};
+	return {
+		from: latestTag,
+		to: "HEAD"
+	};
+};
+/**
+* 将短 hash 解析为完整 hash
+* @param {string} short
+* @returns {Promise<string | undefined>}
+*/
+const getFullHash = (short) => {
+	return runGit(["rev-parse", short]);
+};
+/**
+* 获取指定范围内的 commit 日志
+* @param {string} from
+* @param {string} to
+* @param {string} scope 文件或目录范围
+* @returns {Promise<string | undefined>}
+*/
+const getLog = async (from = "", to = "HEAD", scope) => {
+	const cmd = ["log", `--pretty=format:* %s (%h)`];
+	if (from) cmd.push(`${from}...${to}`);
+	if (scope) cmd.push(...["--", scope]);
+	return runGit(cmd, { trim: false });
+};
+/**
+* 判断工作区是否干净（无未提交修改）
+* @returns {Promise<boolean>}
+*/
+const isWorkingDirClean = async () => {
+	return (await runGit(["status", "-s"]))?.length === 0;
+};
+/** 判断字符串是否为合法 remote 名称 */
+const isRemoteName = (remoteName) => {
+	return remoteName && !remoteName.includes("/");
+};
+/** 判断当前分支是否已设置 upstream */
+const hasUpstreamBranch = async () => {
+	const branch = await runGit([
+		"for-each-ref",
+		"--format=%(upstream:short)",
+		await runGit(["symbolic-ref", "HEAD"])
+	]);
+	return Boolean(branch);
+};
+/** 获取 push 所需的 upstream 参数 */
+const getUpstreamArgs = async (remoteName, branch) => {
+	const hasUpstream = await hasUpstreamBranch();
+	const target = branch || await getCurrentBranch();
+	if (!hasUpstream) return [
+		"--set-upstream",
+		remoteName,
+		target
+	];
+	return [remoteName, target];
+};
+/** 统计自最新 tag 以来的提交数量 */
+const countCommitsSinceLatestTag = async () => {
+	const latestTag = await getLatestTag();
+	return runGit([
+		"rev-list",
+		latestTag ? `${latestTag}...HEAD` : "HEAD",
+		"--count"
+	]).then(Number);
+};
+/** git add（包含未追踪文件） */
+const gitAddAll = async (args = []) => {
+	await runGit([
+		"add",
+		"--all",
+		...args
+	]);
+};
+/** git add（仅已追踪文件） */
+const gitAddTracked = async (args = []) => {
+	await runGit([
+		"add",
+		"--update",
+		...args
+	]);
+};
+/** git commit */
+const gitCommit = async (message, args = []) => {
+	await runGit([
+		"commit",
+		"--message",
+		message,
+		...args
+	]);
+};
+/** git commit amend */
+const gitCommitAmend = async (message, args = []) => {
+	await runGit([
+		"commit",
+		"--amend",
+		"--message",
+		message,
+		...args
+	]);
+};
+/** 创建 annotated tag */
+const gitTagAnnotated = async (tag, message = tag, args = []) => {
+	await runGit([
+		"tag",
+		"--annotate",
+		"--message",
+		message,
+		tag,
+		...args
+	]);
+};
+/** 创建 lightweight tag */
+const gitTagLightweight = async (tag, message = tag, args = []) => {
+	await runGit([
+		"tag",
+		"--message",
+		message,
+		tag,
+		...args
+	]);
+};
+/**
+* 推送 tag 到远程
+* @param {string} remoteName
+* @param {string} tag
+* @param {string[]} args
+* @returns {Promise<string | undefined>}
+* @defaults git push <remoteName> refs/tags/<tag>
+*/
+const pushTag = async (remoteName, tag, args = []) => {
+	await runGit([
+		"push",
+		remoteName,
+		`refs/tags/${tag}`,
+		...args
+	]);
+};
+/**
+* 推送分支到远程
+* 自动处理 upstream 设置
+* @param {string} remoteName
+* @param {string} branch
+* @param {string[]} args
+* @returns {Promise<string | undefined>}
+*/
+const pushBranch = async (remoteName, branch, args = []) => {
+	await runGit([
+		"push",
+		...await getUpstreamArgs(remoteName, branch),
+		...args
+	]);
+};
+/**
+* 撤销【工作区】中某个文件的修改（未暂存的改动）
+* - 不影响暂存区
+* - 不影响提交历史
+* - ⚠️ 会丢弃该文件当前未暂存的修改
+*
+* 等价命令：git restore <file>
+*/
+const restoreFile = async (file) => {
+	await runGit(["restore", file]);
+};
+/**
+* 撤销【工作区】中所有未暂存的修改
+* - 不影响暂存区
+* - 不影响提交历史
+* - ⚠️ 会丢弃所有未暂存的修改
+*
+* 等价命令：git restore .
+*/
+const restoreAll = async () => {
+	await runGit(["restore", "."]);
+};
+/**
+* 将某个文件从【暂存区】移回【工作区】
+* - 保留文件修改
+* - 仅取消 git add 的效果
+*
+* 等价命令：git restore --staged <file>
+*/
+const unstageFile = async (file) => {
+	await runGit([
+		"restore",
+		"--staged",
+		file
+	]);
+};
+/**
+* 取消所有文件的暂存状态
+* - 保留所有文件修改
+* - 清空暂存区
+*
+* 等价命令：git restore --staged .
+*/
+const unstageAll = async () => {
+	await runGit([
+		"restore",
+		"--staged",
+		"."
+	]);
+};
+/**
+* 丢弃某个文件的所有修改（暂存 + 未暂存）
+* - 先取消暂存
+* - 再撤销工作区修改
+* - ⚠️ 修改内容将彻底丢失
+*
+* 等价操作：
+*   git restore --staged <file>
+*   git restore <file>
+*/
+const discardFile = async (file) => {
+	await unstageFile(file);
+	await restoreFile(file);
+};
+/**
+* 丢弃所有修改（包括暂存和未暂存的文件）
+*
+* 作用：
+* - 将暂存区和工作区全部重置到当前 HEAD 提交状态
+* - 丢弃所有未提交的更改，无法恢复（除非使用 reflog）
+*
+* ⚠️ 高风险操作，请确保已备份重要修改
+*
+* 等价命令：
+*   git reset --hard HEAD
+*/
+const discardAll = async () => {
+	await runGit([
+		"reset",
+		"--hard",
+		"HEAD"
+	]);
+};
+/**
+* 撤销最近的 commit（软回退）
+* - 提交历史回退
+* - 修改内容保留
+* - 修改仍在【暂存区】
+*
+* 常用于：刚提交但还想改点东西
+*
+* 等价命令：git reset --soft HEAD~<count>
+*/
+const resetSoft = async (count = 1) => {
+	await runGit([
+		"reset",
+		"--soft",
+		`HEAD~${count}`
+	]);
+};
+/**
+* 撤销最近的 commit（混合回退，默认行为）
+* - 提交历史回退
+* - 修改内容保留
+* - 修改回到【工作区】，不再暂存
+*
+* 等价命令：git reset --mixed HEAD~<count>
+*/
+const resetMixed = async (count = 1) => {
+	await runGit([
+		"reset",
+		"--mixed",
+		`HEAD~${count}`
+	]);
+};
+/**
+* 撤销最近的 commit（强制回退）
+* - 提交历史回退
+* - ⚠️ 所有修改全部丢弃
+*
+* ⚠️ 高危操作，请谨慎使用
+*
+* 等价命令：git reset --hard HEAD~<count>
+*/
+const resetHard = async (count = 1) => {
+	await runGit([
+		"reset",
+		"--hard",
+		`HEAD~${count}`
+	]);
+};
+/**
+* 安全撤销一个已提交（并可能已 push）的 commit
+* - 不改写提交历史
+* - 生成一个新的反向提交
+*
+* 适用于：公共分支 / 已推送到远端
+*
+* 等价命令：git revert <commit>
+*/
+const revertCommit = async (hash) => {
+	await runGit(["revert", hash]);
+};
+/**
+* 将某个文件恢复到指定 commit 的状态
+* - 仅影响该文件
+* - 会覆盖当前工作区中的该文件
+* - 不自动提交
+*
+* 等价命令：git restore --source=<commit> <file>
+*/
+const restoreFileFromCommit = async (file, commit) => {
+	await runGit([
+		"restore",
+		`--source=${commit}`,
+		file
+	]);
+};
+/**
+* 将当前目录下的所有文件恢复到指定 commit 的状态
+*
+* 行为说明：
+* - 仅影响【工作区（Working Tree）】
+* - 不影响暂存区（Index）
+* - 不修改提交历史
+*
+* ⚠️ 风险提示：
+* - 会覆盖当前工作区中的所有文件
+* - 所有未暂存的修改将被永久丢弃
+*
+* 适用场景：
+* - 批量回退文件内容到某个历史版本
+* - 修复误操作、误格式化、误生成文件等情况
+*
+* 等价命令：
+*   git restore --source=<commit> .
+*/
+const restoreFromCommit = async (commit) => {
+	await runGit([
+		"restore",
+		`--source=${commit}`,
+		"."
+	]);
+};
+const deleteTag = async (tag) => {
+	await runGit([
+		"tag",
+		"--delete",
+		tag
+	]);
+};
+/** {@link restoreAll} 的同步版本 */
+const restoreAllSync = async () => {
+	runGitSync(["restore", "."]);
+};
+const deleteTagSync = async (tag) => {
+	runGitSync([
+		"tag",
+		"--delete",
+		tag
+	]);
+};
+const discardAllSync = async () => {
+	runGitSync([
+		"reset",
+		"--hard",
+		"HEAD"
+	]);
+};
+const resetHardSync = async (count = 1) => {
+	runGitSync([
+		"reset",
+		"--hard",
+		`HEAD~${count}`
+	]);
+};
+const gitUndo = {
+	file: {
+		restore: restoreFile,
+		unstage: unstageFile,
+		discard: discardFile
+	},
+	all: {
+		restore: restoreAll,
+		unstage: unstageAll,
+		discard: discardAll
+	},
+	reset: {
+		soft: resetSoft,
+		mixed: resetMixed,
+		hard: resetHard
+	},
+	revert: revertCommit
+};
+
+//#endregion
+//#region src/npm.ts
+const DEFAULT_TAG = "latest";
+const DEFAULT_ACCESS = "public";
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+const accessArg = (access = DEFAULT_ACCESS) => {
+	return ["--access", access];
+};
+const registryArg = (registry = DEFAULT_REGISTRY) => {
+	return ["--registry", registry];
+};
+const tagArg = (tag = DEFAULT_TAG) => {
+	return ["--tag", tag];
+};
+/**
+* 获取 npm registry
+* @param {string} pkgDir
+* @returns {Promise<string>}
+* @defaults https://registry.npmjs.org/
+*/
+const getRegistry = async (pkgDir) => {
+	const n = (r) => r.endsWith("/") ? r : `${r}/`;
+	const { publishConfig = {} } = readJsonFile(join(pkgDir, "package.json"));
+	const { registry } = publishConfig;
+	if (registry) return n(registry);
+	const res = await runNpm([
+		"config",
+		"get",
+		"registry"
+	], { cwd: pkgDir });
+	if (res) return n(res);
+	return "https://registry.npmjs.org/";
+};
+/**
+* 获取 publish access
+* @param {string} pkgDir
+* @returns {Promise<string>}
+* @defaults scoped: restricted; unscoped: public
+*/
+const getAccess = async (pkgDir) => {
+	const { name, publishConfig = {} } = readJsonFile(join(pkgDir, "package.json"));
+	const { access } = publishConfig;
+	return access || (name.startsWith("@") ? "restricted" : "public");
+};
+/**
+* 检查与仓库的连接
+* @param {string} registry
+* @returns {Promise<boolean>}
+* @defaults npm ping --registry https://registry.npmjs.org/
+*/
+const pingRegistry = async (registry) => {
+	return void 0 !== await runNpm(["ping", ...registryArg(registry)]);
+};
+/**
+* 获取已登录用户
+* @param {string} registry
+* @returns {Promise<string | undefined>}
+* @defaults npm whoami --registry https://registry.npmjs.org/
+*/
+const getAuthenticatedUser = (registry) => {
+	return runNpm(["whoami", ...registryArg(registry)]);
+};
+/**
+* 用户是否拥有写入权限
+* @param {string} pkg
+* @param {string} user
+* @param {string} registry
+* @returns {Promise<boolean>}
+* @defaults npm access list collaborators <pkg> --json
+* npm access ls-collaborators <pkg> --json
+*/
+const hasWriteAccess = async (pkg, user, registry) => {
+	const res = await runNpm([
+		"access",
+		"list",
+		"collaborators",
+		pkg,
+		"--json",
+		...registryArg(registry)
+	]).catch((_) => runNpm([
+		"access",
+		"ls-collaborators",
+		pkg,
+		"--json",
+		...registryArg(registry)
+	]));
+	return (JSON.parse(res ?? "{}")[user] ?? "").includes("read-write");
+};
+/**
+* 获取指定包的版本
+* @param {string} pkg pkgName pkgName@tag
+* @param {string} registry
+* @returns {Promise<string | undefined>}
+* @defaults npm view <pkg> version
+*/
+const getPublishedVersion = (pkg, registry) => {
+	return runNpm([
+		"view",
+		pkg,
+		"version",
+		...registryArg(registry)
+	]);
+};
+/**
+* 获取所有已发布的 dist-tags
+* @param {string} pkg
+* @param {string} registry
+* @returns {Promise<string[]>}
+* @defaults npm view <pkg> dist-tags --json
+*/
+const getDistTags = async (pkg, registry) => {
+	const res = await runNpm([
+		"view",
+		pkg,
+		"dist-tags",
+		"--json",
+		...registryArg(registry)
+	]);
+	return Object.keys(JSON.parse(res || "{}"));
+};
+/**
+* 更新包版本号
+* @param {string} version
+* @param {string[]} args
+* @param {string} cwd
+* @returns {Promise<string | undefined>}
+* @defaults npm version <version> --workspaces=false --no-git-tag-version --allow-same-version
+*/
+const bumpPackageVersion = (version, args = [], cwd = ".") => {
+	return runNpm([
+		"version",
+		version,
+		"--workspaces=false",
+		"--no-git-tag-version",
+		"--allow-same-version",
+		...args
+	], { cwd });
+};
+/**
+* 发布
+* @param {{access?: string, registry?: string, tag?: string, args?: string[], cwd?: string}} options
+* @returns {Promise<string | undefined>}
+* @defaults npm publish --tag latest --access public --registry https://registry.npmjs.org/ --workspaces=false
+*/
+const publishPackage = (options) => {
+	const { tag, access, registry, args = [], cwd = "." } = options ?? {};
+	return runNpm([
+		"publish",
+		...tagArg(tag),
+		...accessArg(access),
+		...registryArg(registry),
+		"--workspaces=false",
+		...args
+	], { cwd });
+};
+
+//#endregion
+export { ConfirmResult, DEFAULT_ACCESS, DEFAULT_REGISTRY, DEFAULT_TAG, HttpLibrary, PkgManager, YesOrNo, accessArg, bumpPackageVersion, checkVersion, coloredChangeset, copyDirAsync, countCommitsSinceLatestTag, deleteTag, deleteTagSync, discardAll, discardAllSync, discardFile, editFile, editJsonFile, emptyDir, eol, execAsync, execSyncWithString, fetchAllBranch, getAccess, getAllRemotes, getAuthenticatedUser, getCurrentBranch, getDefaultRemote, getDistTags, getFullHash, getGitConfig, getGitRemoteUrl, getGithubReleaseUrl, getGithubUrl, getLatestTag, getLocalTags, getLog, getOtherRemotes, getPackageInfo, getPackageUrl, getPreviousTag, getPublishedVersion, getRegistry, getRemote, getRemoteForBranch, getRemoteTags, getSortedTags, getStatus, getUpstreamArgs, gitAddAll, gitAddTracked, gitCommit, gitCommitAmend, gitTagAnnotated, gitTagLightweight, gitUndo, hasUpstreamBranch, hasWriteAccess, isEmpty, isGitRepo, isRemoteName, isTestFile, isValidPackageName, isWorkingDirClean, joinUrl, parseArgs, parseGitHubRepo, pingRegistry, pkgFromUserAgent, publishPackage, pushBranch, pushTag, readJsonFile, readSubDirs, registryArg, resetHard, resetHardSync, resetMixed, resetSoft, resolveChangelogRange, restoreAll, restoreAllSync, restoreFile, restoreFileFromCommit, restoreFromCommit, revertCommit, runCliForTest, runGit, runGitSync, runNode, runNodeSync, runNpm, runNpmSync, space, spawnAsync, spawnSyncWithString, stringifyArgs, tagArg, toValidPackageName, toValidProjectName, trimTemplate, unstageAll, unstageFile };