@peiyanlu/cli-utils 0.0.4 → 0.0.6

package/dist/index.d.cts

@@ -0,0 +1,525 @@
+import { ExecOptions, ExecSyncOptions, SpawnOptions, SpawnSyncOptions } from "node:child_process";
+
+//#region src/enums.d.ts
+declare enum PkgManager {
+  NPM = "npm",
+  YARN = "yarn",
+  PNPM = "pnpm",
+}
+/**
+ * @deprecated Use `ConfirmResult` instead.
+ */
+declare enum YesOrNo {
+  Yes = "yes",
+  No = "no",
+  Ignore = "ignore",
+}
+declare enum ConfirmResult {
+  YES = "yes",
+  NO = "no",
+  IGNORE = "ignore",
+}
+declare enum HttpLibrary {
+  EXPRESS = "express",
+  FASTIFY = "fastify",
+  KOA = "koa",
+  HONO = "hono",
+}
+//#endregion
+//#region src/types.d.ts
+interface CopyOptions {
+  rename?: Record<string, string>;
+  skips?: ((name: string, isDir: boolean) => boolean)[];
+}
+type CliOptions<T = string | boolean> = Record<string, T>;
+interface PkgInfo {
+  name: string;
+  version: string;
+}
+interface ExecResultOptions {
+  /** 去掉结果的首尾空格 */
+  trim?: boolean;
+  /** 仅打印命令，不实际执行命令 */
+  dryRun?: boolean;
+  /** log: 打印错误信息，返回 undefined; throw: 抛出错误; ignore: 返回 undefined */
+  error?: 'log' | 'throw' | 'ignore';
+}
+type SpawnAsyncWithStringOptions = SpawnOptions & ExecResultOptions;
+type ExecAsyncWithStringOptions = Omit<ExecOptions, 'encoding'> & ExecResultOptions;
+type SpawnSyncWithStringOptions = Omit<SpawnSyncOptions, 'encoding'> & ExecResultOptions;
+type ExecSyncWithStringOptions = Omit<ExecSyncOptions, 'encoding'> & ExecResultOptions;
+//#endregion
+//#region src/utils.d.ts
+declare const isValidPackageName: (packageName: string) => boolean;
+declare const toValidPackageName: (packageName: string) => string;
+declare const toValidProjectName: (projectName: string) => string;
+declare const emptyDir: (dir: string, ignore?: string[]) => Promise<boolean>;
+declare const isEmpty: (path: string, ignore?: string[]) => Promise<boolean>;
+declare const editFile: (file: string, callback: (content: string) => string) => Promise<void>;
+declare const editJsonFile: <T extends Record<string, any>>(file: string, callback: (json: T) => void) => Promise<void>;
+declare const readSubDirs: (source: string, ignore?: string[]) => Promise<string[]>;
+declare const copyDirAsync: (src: string, dest: string, options: CopyOptions) => Promise<void>;
+declare const readJsonFile: <T extends Record<string, any>>(file: string) => T;
+declare const getPackageInfo: (pkgName: string, getPkgDir: (pkg: string) => string) => {
+  pkg: {
+    name: string;
+    version: string;
+    private?: boolean;
+    publishConfig?: {
+      access: string;
+      registry: string;
+      [key: string]: string;
+    };
+  };
+  pkgDir: string;
+  pkgPath: string;
+};
+/** 通过包管理器执行脚本时生效 UserAgent: `process.env.npm_config_user_agent` */
+declare const pkgFromUserAgent: (userAgent: string | undefined) => PkgInfo | undefined;
+/** 同步执行 Node CLI（用于测试环境） */
+declare const runCliForTest: (path: string, args?: string[], options?: SpawnSyncWithStringOptions) => string | undefined;
+/** 判断测试文件（夹） */
+declare const isTestFile: (name: string) => boolean;
+/** 解析 Github 链接获取 owner 和 repo */
+declare const parseGitHubRepo: (url: string) => string[];
+/** 基于 EOL 的可多换行函数 */
+declare const eol: (n?: number) => string;
+/** 多空格函数 */
+declare const space: (n?: number) => string;
+/** 将字符串以空格分割为数组 */
+declare const parseArgs: (args: string) => string[];
+/** 将数组以空格拼接为字符串 */
+declare const stringifyArgs: (args: string[]) => string;
+/** 去掉模板字符串首尾换行 */
+declare const trimTemplate: (str: string) => string;
+/** 生成 GitHub 仓库主页地址 */
+declare const getGithubUrl: (owner: string, repo: string) => string;
+/** 生成 GitHub Release 页面地址 */
+declare const getGithubReleaseUrl: (owner: string, repo: string, tag: string) => string;
+/** 生成 npm 包指定版本的详情页地址 */
+declare const getPackageUrl: (pkg: string, version: string) => string;
+//#endregion
+//#region src/shell.d.ts
+/** 异步执行 `spawn` 获取字符串类型的结果 */
+declare const spawnAsync: (cmd: string, args: string[], options?: SpawnAsyncWithStringOptions) => Promise<string | undefined>;
+type ExecAsync = {
+  (cmd: string, options?: ExecAsyncWithStringOptions): Promise<string | undefined>;
+  (cmd: string, args: string[], options?: ExecAsyncWithStringOptions): Promise<string | undefined>;
+};
+/** 异步执行 `exec` 获取字符串类型的结果 */
+declare const execAsync: ExecAsync;
+/** 执行 `spawnSync` 获取字符串类型的结果 */
+declare const spawnSyncWithString: (cmd: string, args: string[], options?: SpawnSyncWithStringOptions) => string | undefined;
+type ExecSync = {
+  (cmd: string, options?: ExecAsyncWithStringOptions): string | undefined;
+  (cmd: string, args: string[], options?: ExecAsyncWithStringOptions): string | undefined;
+};
+/** 执行 `execSync` 获取字符串类型的结果 */
+declare const execSyncWithString: ExecSync;
+/** 基于 {@link spawnAsync} 实现 */
+declare const runGit: (args: string[], options?: SpawnAsyncWithStringOptions) => Promise<string | undefined>;
+/** 基于 {@link spawnSyncWithString} 实现 */
+declare const runGitSync: (args: string[], options?: SpawnSyncWithStringOptions) => string | undefined;
+/** 基于 {@link execAsync} 实现 */
+declare const runNpm: (args: string[], options?: ExecAsyncWithStringOptions) => Promise<string | undefined>;
+/** 基于 {@link execSyncWithString} 实现 */
+declare const runNpmSync: (args: string[], options?: ExecSyncWithStringOptions) => string | undefined;
+/** 基于 {@link spawnAsync} 实现 */
+declare const runNode: (args: string[], options: SpawnAsyncWithStringOptions) => Promise<string | undefined>;
+/** 基于 {@link spawnSyncWithString} 实现 */
+declare const runNodeSync: (args: string[], options: SpawnSyncWithStringOptions) => string | undefined;
+/** 支持所有支持 `--version` 命令的脚本查看版本 */
+declare const checkVersion: (cmd: string) => Promise<string | undefined>;
+//#endregion
+//#region src/joinUrl.d.ts
+declare function joinUrl(...args: string[]): string;
+declare function joinUrl(input: readonly string[]): string;
+//#endregion
+//#region src/git.d.ts
+/** 判断指定目录是否是 git 仓库 */
+declare const isGitRepo: (dir?: string) => Promise<boolean>;
+/** 获取指定的 git 配置 */
+declare const getGitConfig: (key: string, global?: boolean) => Promise<string | undefined>;
+/** 获取 git 远程地址 */
+declare const getGitRemoteUrl: (remoteName?: string) => Promise<string | undefined>;
+/** 获取当前分支 */
+declare const getCurrentBranch: () => Promise<string | undefined>;
+/** 获取分支关联的远程地址 */
+declare const getRemoteForBranch: (branch: string) => Promise<string | undefined>;
+/** 获取关联的所有远程地址 */
+declare const getAllRemotes: () => Promise<string[]>;
+/** 获取默认的远程地址 */
+declare const getDefaultRemote: (branch?: string) => Promise<string | undefined>;
+/** 获取默认远程地址之外的远程地址 */
+declare const getOtherRemotes: (branch?: string) => Promise<string[]>;
+/** 提取所有分支 */
+declare const fetchAllBranch: (remoteName?: string) => Promise<string | undefined>;
+/**
+ * 获取本地所有 tag
+ * @returns {Promise<string[]>}
+ * @defaults git tag --list
+ */
+declare const getLocalTags: () => Promise<string[]>;
+/** 获取远程 tags */
+declare const getSortedTags: (match?: string, exclude?: string, sort?: "v:refname" | "creatordate", count?: number) => Promise<string[]>;
+/**
+ * 获取远程（或所有 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>
+ */
+declare const getRemoteTags: (match?: string, exclude?: string) => Promise<string[]>;
+/**
+ * 获取当前工作区状态（不包含未跟踪文件）
+ * @returns {Promise<string | undefined>}
+ * @defaults git status --short --untracked-files=no
+ */
+declare const getStatus: () => Promise<string | undefined>;
+/**
+ * 为 git status / changeset 输出添加颜色
+ *
+ * M -> 黄色（修改）
+ * A -> 绿色（新增）
+ * D -> 红色（删除）
+ * @param {string} log git status --short 输出
+ * @returns {string}
+ */
+declare const coloredChangeset: (log: string) => string;
+/**
+ * 获取当前分支对应的远程信息
+ * @returns {Promise<{remoteName: string, remoteUrl: string | undefined}>}
+ */
+declare const getRemote: () => Promise<{
+  remoteName: string;
+  remoteUrl: string | undefined;
+}>;
+/**
+ * 获取最新 tag
+ *
+ * 默认：
+ * - 匹配所有 tag
+ * - 排除 beta 版本
+ * @param {string} match 默认 *
+ * @param {string} exclude 默认 beta
+ * @returns {Promise<string | undefined>}
+ */
+declare const getLatestTag: (match?: string, exclude?: string) => Promise<string | undefined>;
+/**
+ * 获取上一个 tag
+ *
+ * 默认：
+ * - 匹配所有 tag
+ * - 排除 beta 版本
+ * @param {string} latestTag
+ * @param {string} match 默认 *
+ * @param {string} exclude 默认 beta
+ * @returns {Promise<string | undefined>}
+ */
+declare const getPreviousTag: (latestTag: string, match?: string, exclude?: string) => Promise<string | undefined>;
+/**
+ * 计算 changelog 的 commit 范围
+ * @param {boolean} isIncrement 是否为版本递增发布
+ * @param {string} match tag match
+ * @param {string} exclude tag exclude
+ * @returns {Promise<{from: string, to: string}>}
+ */
+declare const resolveChangelogRange: (isIncrement?: boolean, match?: string, exclude?: string) => Promise<{
+  from: string;
+  to: string;
+}>;
+/**
+ * 将短 hash 解析为完整 hash
+ * @param {string} short
+ * @returns {Promise<string | undefined>}
+ */
+declare const getFullHash: (short: string) => Promise<string | undefined>;
+/**
+ * 获取指定范围内的 commit 日志
+ * @param {string} from
+ * @param {string} to
+ * @param {string} scope 文件或目录范围
+ * @returns {Promise<string | undefined>}
+ */
+declare const getLog: (from?: string, to?: string, scope?: string) => Promise<string | undefined>;
+/**
+ * 判断工作区是否干净（无未提交修改）
+ * @returns {Promise<boolean>}
+ */
+declare const isWorkingDirClean: () => Promise<boolean>;
+/** 判断字符串是否为合法 remote 名称 */
+declare const isRemoteName: (remoteName: string) => boolean | "";
+/** 判断当前分支是否已设置 upstream */
+declare const hasUpstreamBranch: () => Promise<boolean>;
+/** 获取 push 所需的 upstream 参数 */
+declare const getUpstreamArgs: (remoteName: string, branch?: string) => Promise<string[]>;
+/** 统计自最新 tag 以来的提交数量 */
+declare const countCommitsSinceLatestTag: () => Promise<number>;
+/** git add（包含未追踪文件） */
+declare const gitAddAll: (args?: string[]) => Promise<void>;
+/** git add（仅已追踪文件） */
+declare const gitAddTracked: (args?: string[]) => Promise<void>;
+/** git commit */
+declare const gitCommit: (message: string, args?: string[]) => Promise<void>;
+/** git commit amend */
+declare const gitCommitAmend: (message: string, args?: string[]) => Promise<void>;
+/** 创建 annotated tag */
+declare const gitTagAnnotated: (tag: string, message?: string, args?: string[]) => Promise<void>;
+/** 创建 lightweight tag */
+declare const gitTagLightweight: (tag: string, message?: string, args?: string[]) => Promise<void>;
+/**
+ * 推送 tag 到远程
+ * @param {string} remoteName
+ * @param {string} tag
+ * @param {string[]} args
+ * @returns {Promise<string | undefined>}
+ * @defaults git push <remoteName> refs/tags/<tag>
+ */
+declare const pushTag: (remoteName: string, tag: string, args?: string[]) => Promise<void>;
+/**
+ * 推送分支到远程
+ * 自动处理 upstream 设置
+ * @param {string} remoteName
+ * @param {string} branch
+ * @param {string[]} args
+ * @returns {Promise<string | undefined>}
+ */
+declare const pushBranch: (remoteName: string, branch?: string, args?: string[]) => Promise<void>;
+/**
+ * 撤销【工作区】中某个文件的修改（未暂存的改动）
+ * - 不影响暂存区
+ * - 不影响提交历史
+ * - ⚠️ 会丢弃该文件当前未暂存的修改
+ *
+ * 等价命令：git restore <file>
+ */
+declare const restoreFile: (file: string) => Promise<void>;
+/**
+ * 撤销【工作区】中所有未暂存的修改
+ * - 不影响暂存区
+ * - 不影响提交历史
+ * - ⚠️ 会丢弃所有未暂存的修改
+ *
+ * 等价命令：git restore .
+ */
+declare const restoreAll: () => Promise<void>;
+/**
+ * 将某个文件从【暂存区】移回【工作区】
+ * - 保留文件修改
+ * - 仅取消 git add 的效果
+ *
+ * 等价命令：git restore --staged <file>
+ */
+declare const unstageFile: (file: string) => Promise<void>;
+/**
+ * 取消所有文件的暂存状态
+ * - 保留所有文件修改
+ * - 清空暂存区
+ *
+ * 等价命令：git restore --staged .
+ */
+declare const unstageAll: () => Promise<void>;
+/**
+ * 丢弃某个文件的所有修改（暂存 + 未暂存）
+ * - 先取消暂存
+ * - 再撤销工作区修改
+ * - ⚠️ 修改内容将彻底丢失
+ *
+ * 等价操作：
+ *   git restore --staged <file>
+ *   git restore <file>
+ */
+declare const discardFile: (file: string) => Promise<void>;
+/**
+ * 丢弃所有修改（包括暂存和未暂存的文件）
+ *
+ * 作用：
+ * - 将暂存区和工作区全部重置到当前 HEAD 提交状态
+ * - 丢弃所有未提交的更改，无法恢复（除非使用 reflog）
+ *
+ * ⚠️ 高风险操作，请确保已备份重要修改
+ *
+ * 等价命令：
+ *   git reset --hard HEAD
+ */
+declare const discardAll: () => Promise<void>;
+/**
+ * 撤销最近的 commit（软回退）
+ * - 提交历史回退
+ * - 修改内容保留
+ * - 修改仍在【暂存区】
+ *
+ * 常用于：刚提交但还想改点东西
+ *
+ * 等价命令：git reset --soft HEAD~<count>
+ */
+declare const resetSoft: (count?: number) => Promise<void>;
+/**
+ * 撤销最近的 commit（混合回退，默认行为）
+ * - 提交历史回退
+ * - 修改内容保留
+ * - 修改回到【工作区】，不再暂存
+ *
+ * 等价命令：git reset --mixed HEAD~<count>
+ */
+declare const resetMixed: (count?: number) => Promise<void>;
+/**
+ * 撤销最近的 commit（强制回退）
+ * - 提交历史回退
+ * - ⚠️ 所有修改全部丢弃
+ *
+ * ⚠️ 高危操作，请谨慎使用
+ *
+ * 等价命令：git reset --hard HEAD~<count>
+ */
+declare const resetHard: (count?: number) => Promise<void>;
+/**
+ * 安全撤销一个已提交（并可能已 push）的 commit
+ * - 不改写提交历史
+ * - 生成一个新的反向提交
+ *
+ * 适用于：公共分支 / 已推送到远端
+ *
+ * 等价命令：git revert <commit>
+ */
+declare const revertCommit: (hash: string) => Promise<void>;
+/**
+ * 将某个文件恢复到指定 commit 的状态
+ * - 仅影响该文件
+ * - 会覆盖当前工作区中的该文件
+ * - 不自动提交
+ *
+ * 等价命令：git restore --source=<commit> <file>
+ */
+declare const restoreFileFromCommit: (file: string, commit: string) => Promise<void>;
+/**
+ * 将当前目录下的所有文件恢复到指定 commit 的状态
+ *
+ * 行为说明：
+ * - 仅影响【工作区（Working Tree）】
+ * - 不影响暂存区（Index）
+ * - 不修改提交历史
+ *
+ * ⚠️ 风险提示：
+ * - 会覆盖当前工作区中的所有文件
+ * - 所有未暂存的修改将被永久丢弃
+ *
+ * 适用场景：
+ * - 批量回退文件内容到某个历史版本
+ * - 修复误操作、误格式化、误生成文件等情况
+ *
+ * 等价命令：
+ *   git restore --source=<commit> .
+ */
+declare const restoreFromCommit: (commit: string) => Promise<void>;
+declare const deleteTag: (tag: string) => Promise<void>;
+/** {@link restoreAll} 的同步版本 */
+declare const restoreAllSync: () => Promise<void>;
+declare const deleteTagSync: (tag: string) => Promise<void>;
+declare const discardAllSync: () => Promise<void>;
+declare const resetHardSync: (count?: number) => Promise<void>;
+declare const gitUndo: {
+  file: {
+    restore: (file: string) => Promise<void>;
+    unstage: (file: string) => Promise<void>;
+    discard: (file: string) => Promise<void>;
+  };
+  all: {
+    restore: () => Promise<void>;
+    unstage: () => Promise<void>;
+    discard: () => Promise<void>;
+  };
+  reset: {
+    soft: (count?: number) => Promise<void>;
+    mixed: (count?: number) => Promise<void>;
+    hard: (count?: number) => Promise<void>;
+  };
+  revert: (hash: string) => Promise<void>;
+};
+//#endregion
+//#region src/npm.d.ts
+declare const DEFAULT_TAG: string;
+declare const DEFAULT_ACCESS: string;
+declare const DEFAULT_REGISTRY: string;
+declare const accessArg: (access?: string) => string[];
+declare const registryArg: (registry?: string) => string[];
+declare const tagArg: (tag?: string) => string[];
+/**
+ * 获取 npm registry
+ * @param {string} pkgDir
+ * @returns {Promise<string>}
+ * @defaults https://registry.npmjs.org/
+ */
+declare const getRegistry: (pkgDir: string) => Promise<string>;
+/**
+ * 获取 publish access
+ * @param {string} pkgDir
+ * @returns {Promise<string>}
+ * @defaults scoped: restricted; unscoped: public
+ */
+declare const getAccess: (pkgDir: string) => Promise<"restricted" | "public">;
+/**
+ * 检查与仓库的连接
+ * @param {string} registry
+ * @returns {Promise<boolean>}
+ * @defaults npm ping --registry https://registry.npmjs.org/
+ */
+declare const pingRegistry: (registry?: string) => Promise<boolean>;
+/**
+ * 获取已登录用户
+ * @param {string} registry
+ * @returns {Promise<string | undefined>}
+ * @defaults npm whoami --registry https://registry.npmjs.org/
+ */
+declare const getAuthenticatedUser: (registry?: string) => Promise<string | undefined>;
+/**
+ * 用户是否拥有写入权限
+ * @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
+ */
+declare const hasWriteAccess: (pkg: string, user: string, registry?: string) => Promise<boolean>;
+/**
+ * 获取指定包的版本
+ * @param {string} pkg pkgName pkgName@tag
+ * @param {string} registry
+ * @returns {Promise<string | undefined>}
+ * @defaults npm view <pkg> version
+ */
+declare const getPublishedVersion: (pkg: string, registry?: string) => Promise<string | undefined>;
+/**
+ * 获取所有已发布的 dist-tags
+ * @param {string} pkg
+ * @param {string} registry
+ * @returns {Promise<string[]>}
+ * @defaults npm view <pkg> dist-tags --json
+ */
+declare const getDistTags: (pkg: string, registry?: string) => Promise<string[]>;
+/**
+ * 更新包版本号
+ * @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
+ */
+declare const bumpPackageVersion: (version: string, args?: string[], cwd?: string) => Promise<string | undefined>;
+/**
+ * 发布
+ * @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
+ */
+declare const publishPackage: (options?: {
+  access?: string;
+  registry?: string;
+  tag?: string;
+  args?: string[];
+  cwd?: string;
+}) => Promise<string | undefined>;
+//#endregion
+export { CliOptions, ConfirmResult, CopyOptions, DEFAULT_ACCESS, DEFAULT_REGISTRY, DEFAULT_TAG, ExecAsyncWithStringOptions, ExecResultOptions, ExecSyncWithStringOptions, HttpLibrary, PkgInfo, PkgManager, SpawnAsyncWithStringOptions, SpawnSyncWithStringOptions, 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 };