@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/case.mjs

@@ -0,0 +1,120 @@
+import { camelCase, capitalCase, constantCase, dotCase, kebabCase, pascalCase, pascalSnakeCase, pathCase, sentenceCase, snakeCase, trainCase } from "change-case";
+// src/case.ts
+/**
+* 字符串大小写风格转换工具。
+*
+* 所有方法均委托给 `change-case` 包实现，方法名去掉了原函数名的 `Case`
+* 后缀（如 `camelCase` → `camel`，`pascalSnakeCase` → `pascalSnake`）。
+*
+* 各方法的 `options` 参数会原样透传给 `change-case` 对应函数，
+* 类型分别为导出的 `XCaseCamelOptions`、`XCasePascalOptions`、
+* `XCasePascalSnakeOptions`、`XCaseCapitalOptions`、`XCaseConstantOptions`、
+* `XCaseDotOptions`、`XCaseKebabOptions`、`XCasePathOptions`、
+* `XCaseSentenceOptions`、`XCaseSnakeOptions`、`XCaseTrainOptions`，
+* 可配置 `locale`、`delimiter`、`split` 等（`camel`/`pascal` 额外支持
+* `mergeAmbiguousCharacters`）。
+*
+* 以 `Hello World` 为例，各方法的输出：
+* - `camel` → `helloWorld`
+* - `pascal` → `HelloWorld`
+* - `pascalSnake` → `Hello_World`
+* - `capital` → `Hello World`
+* - `constant` → `HELLO_WORLD`
+* - `dot` → `hello.world`
+* - `kebab` → `hello-world`
+* - `path` → `hello/world`
+* - `sentence` → `Hello world`
+* - `snake` → `hello_world`
+* - `train` → `Hello-World`
+*/
+var XCase = class {
+	/**
+	* 转换为 camelCase（小驼峰）命名。
+	*
+	* @example XCase.camel('Hello World') // 'helloWorld'
+	*/
+	static camel(text, options) {
+		return camelCase(text, options);
+	}
+	/**
+	* 转换为 PascalCase（大驼峰）命名。
+	*
+	* @example XCase.pascal('hello world') // 'HelloWorld'
+	*/
+	static pascal(text, options) {
+		return pascalCase(text, options);
+	}
+	/**
+	* 转换为 Pascal_Snake_Case（大驼峰 + 下划线）命名。
+	*
+	* @example XCase.pascalSnake('hello world') // 'Hello_World'
+	*/
+	static pascalSnake(text, options) {
+		return pascalSnakeCase(text, options);
+	}
+	/**
+	* 转换为 Capital Case（首字母大写的空格分隔）命名。
+	*
+	* @example XCase.capital('hello world') // 'Hello World'
+	*/
+	static capital(text, options) {
+		return capitalCase(text, options);
+	}
+	/**
+	* 转换为 CONSTANT_CASE（全大写下划线）命名。
+	*
+	* @example XCase.constant('hello world') // 'HELLO_WORLD'
+	*/
+	static constant(text, options) {
+		return constantCase(text, options);
+	}
+	/**
+	* 转换为 dot.case（点号分隔）命名。
+	*
+	* @example XCase.dot('hello world') // 'hello.world'
+	*/
+	static dot(text, options) {
+		return dotCase(text, options);
+	}
+	/**
+	* 转换为 kebab-case（短横线分隔）命名。
+	*
+	* @example XCase.kebab('Hello World') // 'hello-world'
+	*/
+	static kebab(text, options) {
+		return kebabCase(text, options);
+	}
+	/**
+	* 转换为 path/case（斜杠分隔）命名。
+	*
+	* @example XCase.path('hello world') // 'hello/world'
+	*/
+	static path(text, options) {
+		return pathCase(text, options);
+	}
+	/**
+	* 转换为 Sentence case（首字母大写的句子）命名。
+	*
+	* @example XCase.sentence('hello world') // 'Hello world'
+	*/
+	static sentence(text, options) {
+		return sentenceCase(text, options);
+	}
+	/**
+	* 转换为 snake_case（小写下划线）命名。
+	*
+	* @example XCase.snake('Hello World') // 'hello_world'
+	*/
+	static snake(text, options) {
+		return snakeCase(text, options);
+	}
+	/**
+	* 转换为 Train-Case（短横线分隔、各单词首字母大写）命名。
+	*
+	* @example XCase.train('hello world') // 'Hello-World'
+	*/
+	static train(text, options) {
+		return trainCase(text, options);
+	}
+};
+export { XCase };

package/lib/chinese.d.mts

@@ -0,0 +1,57 @@
+/**
+ * 中文拼音转换工具。
+ *
+ * 基于 `pinyin-pro` 实现，返回逐字的拼音数组：
+ * - `pinyin`：无声调拼音，如 `XChinese.pinyin('我们')` → `['wo', 'men']`；
+ * - `pinyinWithTone`：带声调拼音（声调标在韵母上），
+ *   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`；
+ * - `pinyinInitials`：拼音首字母缩写（小写字符串），
+ *   如 `XChinese.pinyinInitials('我们')` → `'wm'`。
+ *
+ * 处理规则：
+ * - 每个汉字对应数组中的一个拼音元素；
+ * - 非汉字字符（字母、数字、符号、空白等）原样保留在结果中；
+ * - 多音字按 `pinyin-pro` 默认的逆向最大匹配分词规则取常用读音；
+ * - 空字符串返回空数组 `[]`。
+ */
+export declare class XChinese {
+  /**
+   * 获取无声调拼音。
+   *
+   * @param text 要转换的汉语字符串，可混含非汉字字符。
+   * @returns 拼音字符串数组，每个汉字对应一个元素，非汉字原样保留。
+   *
+   * @example
+   * XChinese.pinyin('我们') // ['wo', 'men']
+   * XChinese.pinyin('我爱你') // ['wo', 'ai', 'ni']
+   * XChinese.pinyin('我爱ABC') // ['wo', 'ai', 'A', 'B', 'C']
+   */
+  static pinyin(text: string): string[];
+  /**
+   * 获取带声调拼音（声调标在韵母上，如 `wǒ`、`ài`、`nǐ`）。
+   *
+   * @param text 要转换的汉语字符串，可混含非汉字字符。
+   * @returns 拼音字符串数组，每个汉字对应一个带声调元素，非汉字原样保留。
+   *
+   * @example
+   * XChinese.pinyinWithTone('我们') // ['wǒ', 'men']
+   * XChinese.pinyinWithTone('我爱你') // ['wǒ', 'ài', 'nǐ']
+   */
+  static pinyinWithTone(text: string): string[];
+  /**
+   * 获取拼音首字母缩写（小写字符串）。
+   *
+   * 每个汉字取对应拼音的首字母，并统一转为小写；非汉字字符原样保留
+   * （其中的英文字母也会被转为小写，如 `ABC` → `abc`）。
+   *
+   * @param text 要转换的汉语字符串，可混含非汉字字符。
+   * @returns 小写拼音首字母字符串，例如 `'我们'` → `'wm'`、`'我爱你'` → `'wan'`。
+   *
+   * @example
+   * XChinese.pinyinInitials('我们') // 'wm'
+   * XChinese.pinyinInitials('我爱你') // 'wan'
+   * XChinese.pinyinInitials('我爱ABC') // 'waabc'
+   * XChinese.pinyinInitials('重庆') // 'cq'
+   */
+  static pinyinInitials(text: string): string;
+}

package/lib/chinese.mjs

@@ -0,0 +1,79 @@
+import { pinyin } from "pinyin-pro";
+// src/chinese.ts
+/**
+* 中文拼音转换工具。
+*
+* 基于 `pinyin-pro` 实现，返回逐字的拼音数组：
+* - `pinyin`：无声调拼音，如 `XChinese.pinyin('我们')` → `['wo', 'men']`；
+* - `pinyinWithTone`：带声调拼音（声调标在韵母上），
+*   如 `XChinese.pinyinWithTone('我们')` → `['wǒ', 'men']`；
+* - `pinyinInitials`：拼音首字母缩写（小写字符串），
+*   如 `XChinese.pinyinInitials('我们')` → `'wm'`。
+*
+* 处理规则：
+* - 每个汉字对应数组中的一个拼音元素；
+* - 非汉字字符（字母、数字、符号、空白等）原样保留在结果中；
+* - 多音字按 `pinyin-pro` 默认的逆向最大匹配分词规则取常用读音；
+* - 空字符串返回空数组 `[]`。
+*/
+var XChinese = class {
+	/**
+	* 获取无声调拼音。
+	*
+	* @param text 要转换的汉语字符串，可混含非汉字字符。
+	* @returns 拼音字符串数组，每个汉字对应一个元素，非汉字原样保留。
+	*
+	* @example
+	* XChinese.pinyin('我们') // ['wo', 'men']
+	* XChinese.pinyin('我爱你') // ['wo', 'ai', 'ni']
+	* XChinese.pinyin('我爱ABC') // ['wo', 'ai', 'A', 'B', 'C']
+	*/
+	static pinyin(text) {
+		return pinyin(text, {
+			type: "array",
+			toneType: "none"
+		});
+	}
+	/**
+	* 获取带声调拼音（声调标在韵母上，如 `wǒ`、`ài`、`nǐ`）。
+	*
+	* @param text 要转换的汉语字符串，可混含非汉字字符。
+	* @returns 拼音字符串数组，每个汉字对应一个带声调元素，非汉字原样保留。
+	*
+	* @example
+	* XChinese.pinyinWithTone('我们') // ['wǒ', 'men']
+	* XChinese.pinyinWithTone('我爱你') // ['wǒ', 'ài', 'nǐ']
+	*/
+	static pinyinWithTone(text) {
+		return pinyin(text, {
+			type: "array",
+			toneType: "symbol"
+		});
+	}
+	/**
+	* 获取拼音首字母缩写（小写字符串）。
+	*
+	* 每个汉字取对应拼音的首字母，并统一转为小写；非汉字字符原样保留
+	* （其中的英文字母也会被转为小写，如 `ABC` → `abc`）。
+	*
+	* @param text 要转换的汉语字符串，可混含非汉字字符。
+	* @returns 小写拼音首字母字符串，例如 `'我们'` → `'wm'`、`'我爱你'` → `'wan'`。
+	*
+	* @example
+	* XChinese.pinyinInitials('我们') // 'wm'
+	* XChinese.pinyinInitials('我爱你') // 'wan'
+	* XChinese.pinyinInitials('我爱ABC') // 'waabc'
+	* XChinese.pinyinInitials('重庆') // 'cq'
+	*/
+	static pinyinInitials(text) {
+		return pinyin(text, {
+			type: "string",
+			pattern: "first",
+			toneType: "none",
+			separator: "",
+			removeNonZh: false,
+			nonZh: "consecutive"
+		}).toLowerCase();
+	}
+};
+export { XChinese };

package/lib/cli.d.mts

@@ -0,0 +1,52 @@
+import { checkbox, confirm, editor, expand, input, number, password, rawlist, search, select } from "@inquirer/prompts";
+/**
+ * 命令行交互与表格输出工具。
+ *
+ * 基于 `@inquirer/prompts` 与 `cli-table3` 封装：
+ * - 以静态属性的形式直接透出 `input`、`select`、`checkbox`、`confirm`、
+ *   `search`、`password`、`expand`、`editor`、`number`、`rawlist` 等交互提问函数，
+ *   签名与返回类型与 `@inquirer/prompts` 保持一致；
+ * - `table`：将二维数组渲染为对齐的文本表格。
+ */
+export declare class XCli {
+  /** 发起一次文本输入交互，返回 `Promise<string>`。 */
+  static input: typeof input;
+  /** 发起一次单选交互，返回选中项的值。 */
+  static select: typeof select;
+  /** 发起一次多选交互，返回选中项的数组。 */
+  static checkbox: typeof checkbox;
+  /** 发起一次是/否确认交互，返回 `Promise<boolean>`。 */
+  static confirm: typeof confirm;
+  /** 发起一次带搜索过滤的单选交互，返回选中项的值。 */
+  static search: typeof search;
+  /** 发起一次隐藏输入的密码交互，返回 `Promise<string>`。 */
+  static password: typeof password;
+  /** 发起一次可展开选项的交互，返回选中项的值。 */
+  static expand: typeof expand;
+  /** 打开外部编辑器进行文本输入，返回 `Promise<string>`。 */
+  static editor: typeof editor;
+  /** 发起一次数字输入交互，返回数字结果（未强制必填时可能为 `undefined`）。 */
+  static number: typeof number;
+  /** 发起一次原始列表单选交互，返回选中项的值。 */
+  static rawlist: typeof rawlist;
+  /**
+   * 将二维数组渲染为对齐的文本表格。
+   *
+   * 返回纯文本（不含 ANSI 颜色码），保证在任意终端环境下输出一致。
+   *
+   * @param data 表格行数据，每行为一个单元格数组。
+   * @returns 使用 Unicode 边框绘制的表格字符串。
+   *
+   * @example
+   * XCli.table([
+   *   ['姓名', '年龄'],
+   *   ['张三', '18'],
+   * ])
+   * // ┌──────┬──────┐
+   * // │ 姓名 │ 年龄 │
+   * // ├──────┼──────┤
+   * // │ 张三 │ 18   │
+   * // └──────┴──────┘
+   */
+  static table(data: any[][]): string;
+}

package/lib/cli.mjs

@@ -0,0 +1,62 @@
+import { checkbox, confirm, editor, expand, input, number, password, rawlist, search, select } from "@inquirer/prompts";
+import Table from "cli-table3";
+// src/cli.ts
+/**
+* 命令行交互与表格输出工具。
+*
+* 基于 `@inquirer/prompts` 与 `cli-table3` 封装：
+* - 以静态属性的形式直接透出 `input`、`select`、`checkbox`、`confirm`、
+*   `search`、`password`、`expand`、`editor`、`number`、`rawlist` 等交互提问函数，
+*   签名与返回类型与 `@inquirer/prompts` 保持一致；
+* - `table`：将二维数组渲染为对齐的文本表格。
+*/
+var XCli = class {
+	/** 发起一次文本输入交互，返回 `Promise<string>`。 */
+	static input = input;
+	/** 发起一次单选交互，返回选中项的值。 */
+	static select = select;
+	/** 发起一次多选交互，返回选中项的数组。 */
+	static checkbox = checkbox;
+	/** 发起一次是/否确认交互，返回 `Promise<boolean>`。 */
+	static confirm = confirm;
+	/** 发起一次带搜索过滤的单选交互，返回选中项的值。 */
+	static search = search;
+	/** 发起一次隐藏输入的密码交互，返回 `Promise<string>`。 */
+	static password = password;
+	/** 发起一次可展开选项的交互，返回选中项的值。 */
+	static expand = expand;
+	/** 打开外部编辑器进行文本输入，返回 `Promise<string>`。 */
+	static editor = editor;
+	/** 发起一次数字输入交互，返回数字结果（未强制必填时可能为 `undefined`）。 */
+	static number = number;
+	/** 发起一次原始列表单选交互，返回选中项的值。 */
+	static rawlist = rawlist;
+	/**
+	* 将二维数组渲染为对齐的文本表格。
+	*
+	* 返回纯文本（不含 ANSI 颜色码），保证在任意终端环境下输出一致。
+	*
+	* @param data 表格行数据，每行为一个单元格数组。
+	* @returns 使用 Unicode 边框绘制的表格字符串。
+	*
+	* @example
+	* XCli.table([
+	*   ['姓名', '年龄'],
+	*   ['张三', '18'],
+	* ])
+	* // ┌──────┬──────┐
+	* // │ 姓名 │ 年龄 │
+	* // ├──────┼──────┤
+	* // │ 张三 │ 18   │
+	* // └──────┴──────┘
+	*/
+	static table(data) {
+		const table = new Table({ style: {
+			head: [],
+			border: []
+		} });
+		table.push(...data);
+		return table.toString();
+	}
+};
+export { XCli };

package/lib/clipboard.d.mts

@@ -0,0 +1,50 @@
+/**
+ * 剪贴板文本/HTML 读写工具。
+ *
+ * 说明：
+ * - `readText` / `writeText` 使用 `clipboardy`，跨平台处理纯文本；
+ * - `readHtml` / `writeHtml` 在不同平台走不同实现：
+ *   - macOS：`osascript` + AppleScript HTML 数据；
+ *   - Windows：`powershell` + `HTML Format`（CF_HTML）；
+ *   - 其他平台：抛出不支持错误。
+ */
+export declare class XClipboard {
+  /**
+   * 构建 Windows CF_HTML 文本。
+   *
+   * 参考规范中 Start/End 偏移均按字节计数（UTF-8）。
+   */
+  private static toWindowsCfHtml;
+  /**
+   * 从 Windows `HTML Format` 文本中提取 fragment。
+   *
+   * 若缺少偏移字段，会尝试用标记提取；再失败时返回原始文本。
+   */
+  private static fromWindowsCfHtml;
+  /**
+   * 将 PowerShell 脚本编码为 `-EncodedCommand` 可执行格式（UTF-16LE）。
+   */
+  private static buildPowerShellCommand;
+  /**
+   * 读取纯文本剪贴板内容。
+   */
+  static readText(): Promise<string>;
+  /**
+   * 读取 HTML 剪贴板内容（macOS / Windows）。
+   *
+   * - macOS：读取 AppleScript `«data HTML...»` 十六进制文本并解码；
+   * - Windows：读取 `HTML Format`（CF_HTML）并提取 fragment。
+   */
+  static readHtml(): Promise<string>;
+  /**
+   * 写入纯文本到剪贴板。
+   */
+  static writeText(text: string): Promise<void>;
+  /**
+   * 写入 HTML 到剪贴板（macOS / Windows）。
+   *
+   * - macOS：将 HTML 编码为十六进制后写入 AppleScript HTML 数据；
+   * - Windows：封装为 CF_HTML（`HTML Format`）后调用 PowerShell 写入。
+   */
+  static writeHtml(html: string): Promise<void>;
+}

package/lib/clipboard.mjs

@@ -0,0 +1,122 @@
+import { XCmd } from "./cmd.mjs";
+import clipboardy from "clipboardy";
+// src/clipboard.ts
+/**
+* 剪贴板文本/HTML 读写工具。
+*
+* 说明：
+* - `readText` / `writeText` 使用 `clipboardy`，跨平台处理纯文本；
+* - `readHtml` / `writeHtml` 在不同平台走不同实现：
+*   - macOS：`osascript` + AppleScript HTML 数据；
+*   - Windows：`powershell` + `HTML Format`（CF_HTML）；
+*   - 其他平台：抛出不支持错误。
+*/
+var XClipboard = class XClipboard {
+	/**
+	* 构建 Windows CF_HTML 文本。
+	*
+	* 参考规范中 Start/End 偏移均按字节计数（UTF-8）。
+	*/
+	static toWindowsCfHtml(fragmentHtml) {
+		const htmlPrefix = "<!DOCTYPE html><html><body><!--StartFragment-->";
+		const html = `${htmlPrefix}${fragmentHtml}<!--EndFragment--></body></html>`;
+		const startHtml = Buffer.byteLength("Version:0.9\r\nStartHTML:0000000000\r\nEndHTML:0000000000\r\nStartFragment:0000000000\r\nEndFragment:0000000000\r\n", "utf8");
+		const startFragment = startHtml + Buffer.byteLength(htmlPrefix, "utf8");
+		const endFragment = startFragment + Buffer.byteLength(fragmentHtml, "utf8");
+		const endHtml = startHtml + Buffer.byteLength(html, "utf8");
+		const pad = (num) => num.toString().padStart(10, "0");
+		return `${`Version:0.9\r
+StartHTML:${pad(startHtml)}\r\nEndHTML:${pad(endHtml)}\r\nStartFragment:${pad(startFragment)}\r\nEndFragment:${pad(endFragment)}\r\n`}${html}`;
+	}
+	/**
+	* 从 Windows `HTML Format` 文本中提取 fragment。
+	*
+	* 若缺少偏移字段，会尝试用标记提取；再失败时返回原始文本。
+	*/
+	static fromWindowsCfHtml(value) {
+		const startMatch = value.match(/StartFragment:(\d+)/);
+		const endMatch = value.match(/EndFragment:(\d+)/);
+		if (startMatch && endMatch) {
+			const start = Number(startMatch[1]);
+			const end = Number(endMatch[1]);
+			if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+				const bytes = Buffer.from(value, "utf8");
+				if (start >= 0 && end <= bytes.length) return bytes.subarray(start, end).toString("utf8");
+			}
+		}
+		const markerMatch = value.match(/<!--StartFragment-->([\s\S]*?)<!--EndFragment-->/);
+		if (markerMatch) return markerMatch[1];
+		return value;
+	}
+	/**
+	* 将 PowerShell 脚本编码为 `-EncodedCommand` 可执行格式（UTF-16LE）。
+	*/
+	static buildPowerShellCommand(script) {
+		return `powershell -NoProfile -NonInteractive -STA -EncodedCommand ${Buffer.from(script, "utf16le").toString("base64")}`;
+	}
+	/**
+	* 读取纯文本剪贴板内容。
+	*/
+	static async readText() {
+		return clipboardy.read();
+	}
+	/**
+	* 读取 HTML 剪贴板内容（macOS / Windows）。
+	*
+	* - macOS：读取 AppleScript `«data HTML...»` 十六进制文本并解码；
+	* - Windows：读取 `HTML Format`（CF_HTML）并提取 fragment。
+	*/
+	static async readHtml() {
+		if (process.platform === "darwin") {
+			const { result: hex } = await XCmd.exec(`osascript -e "the clipboard as «class HTML»"`);
+			const normalized = hex.trim();
+			const matched = normalized.match(/^«data HTML([0-9a-fA-F]*)»$/);
+			if (!matched) throw new Error(`读取剪贴板 HTML 失败，返回内容格式无效: ${normalized}`);
+			return Buffer.from(matched[1], "hex").toString();
+		}
+		if (process.platform === "win32") {
+			const command = XClipboard.buildPowerShellCommand([
+				"[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+				"Add-Type -AssemblyName System.Windows.Forms",
+				"$data = [System.Windows.Forms.Clipboard]::GetData('HTML Format')",
+				"if ($null -eq $data) { return }",
+				"Write-Output $data"
+			].join("; "));
+			const { result } = await XCmd.exec(command);
+			return XClipboard.fromWindowsCfHtml(result.trim());
+		}
+		throw new Error(`当前平台不支持读取 HTML 剪贴板: ${process.platform}`);
+	}
+	/**
+	* 写入纯文本到剪贴板。
+	*/
+	static async writeText(text) {
+		await clipboardy.write(text);
+	}
+	/**
+	* 写入 HTML 到剪贴板（macOS / Windows）。
+	*
+	* - macOS：将 HTML 编码为十六进制后写入 AppleScript HTML 数据；
+	* - Windows：封装为 CF_HTML（`HTML Format`）后调用 PowerShell 写入。
+	*/
+	static async writeHtml(html) {
+		if (process.platform === "darwin") {
+			const hex = Buffer.from(html).toString("hex");
+			await XCmd.exec(`osascript -e "set the clipboard to «data HTML${hex}»"`);
+			return;
+		}
+		if (process.platform === "win32") {
+			const cfHtml = XClipboard.toWindowsCfHtml(html);
+			const cfHtmlBase64 = Buffer.from(cfHtml, "utf8").toString("base64");
+			const command = XClipboard.buildPowerShellCommand([
+				"$cfHtml = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('" + cfHtmlBase64 + "'))",
+				"Add-Type -AssemblyName System.Windows.Forms",
+				"[System.Windows.Forms.Clipboard]::SetData('HTML Format', $cfHtml)"
+			].join("; "));
+			await XCmd.exec(command);
+			return;
+		}
+		throw new Error(`当前平台不支持写入 HTML 剪贴板: ${process.platform}`);
+	}
+};
+export { XClipboard };

package/lib/cmd.d.mts

@@ -0,0 +1,38 @@
+import { ChildProcess } from "node:child_process";
+export interface XCmdExecOptions {
+  /** 命令执行目录；不传时使用当前进程工作目录。 */
+  cwd?: string;
+  /** 额外环境变量；会覆盖同名系统环境变量。 */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * 子进程标准 IO 策略。
+   *
+   * - `ignore`（默认）：不向当前终端输出，但会在结果中返回 `stdout/stderr`；
+   * - `inherit`：直连当前终端，适合需要实时查看输出的命令。
+   */
+  stdio?: 'inherit' | 'ignore';
+}
+export type XCmdExecResult = Promise<{
+  /** 命令执行成功时的标准输出文本（stdout）。 */
+  result: string;
+}> & {
+  /** 外部终止当前子进程的方法。 */
+  kill: ChildProcess['kill'];
+};
+export declare class XCmd {
+  /**
+   * 执行一条 shell 命令。
+   *
+   * 典型用法：
+   * - `await XCmd.exec('npm run build')`
+   * - `await XCmd.exec('fnm i 24')`
+   *
+   * 行为说明：
+   * 1. 默认 `stdio = 'ignore'`，适合静默执行命令，并将 `stdout` 作为结果返回；
+   * 2. 可通过 `cwd` 指定执行目录；
+   * 3. 可通过 `env` 传入额外环境变量（会与当前进程环境合并）；
+   * 4. 返回值是“可 kill 的 Promise”，可在外部中断进程；
+   * 5. 子进程非零退出时会抛出包含退出码/信号和错误输出的异常，方便定位失败原因。
+   */
+  static exec(command: string, options?: XCmdExecOptions): XCmdExecResult;
+}

package/lib/cmd.mjs

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+// src/cmd.ts
+var XCmd = class {
+	/**
+	* 执行一条 shell 命令。
+	*
+	* 典型用法：
+	* - `await XCmd.exec('npm run build')`
+	* - `await XCmd.exec('fnm i 24')`
+	*
+	* 行为说明：
+	* 1. 默认 `stdio = 'ignore'`，适合静默执行命令，并将 `stdout` 作为结果返回；
+	* 2. 可通过 `cwd` 指定执行目录；
+	* 3. 可通过 `env` 传入额外环境变量（会与当前进程环境合并）；
+	* 4. 返回值是“可 kill 的 Promise”，可在外部中断进程；
+	* 5. 子进程非零退出时会抛出包含退出码/信号和错误输出的异常，方便定位失败原因。
+	*/
+	static exec(command, options) {
+		const shouldInheritStdio = options?.stdio === "inherit";
+		const child = spawn(command, {
+			cwd: options?.cwd,
+			env: {
+				...process.env,
+				...options?.env
+			},
+			stdio: shouldInheritStdio ? "inherit" : "pipe",
+			shell: true
+		});
+		let stdout = "";
+		let stderr = "";
+		if (!shouldInheritStdio) {
+			child.stdout?.on("data", (chunk) => {
+				stdout += chunk.toString();
+			});
+			child.stderr?.on("data", (chunk) => {
+				stderr += chunk.toString();
+			});
+		}
+		const promise = new Promise((resolve, reject) => {
+			child.once("error", reject);
+			child.once("close", (code, signal) => {
+				if (code === 0) {
+					resolve({ result: stdout });
+					return;
+				}
+				reject(/* @__PURE__ */ new Error(`Command failed: "${command}" (code: ${code ?? "null"}, signal: ${signal ?? "null"}, stderr: ${stderr.trim() || "empty"})`));
+			});
+		});
+		return Object.assign(promise, { kill: child.kill.bind(child) });
+	}
+};
+export { XCmd };