@done-coding/cli-utils 0.8.1 → 0.8.2-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/cli-utils",
-  "version": "0.8.1",
+  "version": "0.8.2-alpha.1",
   "description": "cli utils",
   "private": false,
   "module": "es/index.mjs",
@@ -47,10 +47,9 @@
     "@types/pinyin": "^2.10.0",
     "@types/prompts": "^2.4.6",
     "@types/semver": "^7.5.3",
-    "@types/uuid": "^10.0.0",
     "@types/yargs": "^17.0.28",
     "rimraf": "^6.0.1",
-    "typescript": "^5.2.2",
+    "typescript": "^5.8.3",
     "vite": "^4.4.11",
     "vite-plugin-dts": "^3.6.0"
   },
@@ -67,8 +66,7 @@
     "pinyin": "^2.11.2",
     "prompts": "^2.4.2",
     "semver": "^7.5.4",
-    "uuid": "^11.1.0",
     "yargs": "^17.7.2"
   },
-  "gitHead": "0930f800167c04a86b56eae9741872dd51bec0c6"
+  "gitHead": "660e39fc523e4eba1ea621e3c59122f98015a2de"
 }

package/types/index.d.ts

@@ -1,6 +1,8 @@
 import type { ArgumentsCamelCase } from 'yargs';
 import type { CommandModule } from 'yargs';
 import _curry from 'lodash.curry';
+import { ExecSyncOptions } from 'node:child_process';
+import fs from 'node:fs';
 import _get from 'lodash.get';
 import json5 from 'json5';
 import { Answers as PromptAnswers } from 'prompts';
@@ -14,7 +16,7 @@ import prompts from 'prompts';
 import { PromptType } from 'prompts';
 import { ValueOrFunc as PromptValueOrFunc } from 'prompts';
 import _set from 'lodash.set';
-import { v4 as uuidv4 } from 'uuid';
+import type { WriteStream } from 'node:fs';
 import yargs from 'yargs';
 import type { Argv as YargsArgv } from 'yargs';
 import type { Options as YargsOptions } from 'yargs';
@@ -30,10 +32,13 @@ export declare const addHuskyHooks: <H extends string>({ hookNames, rootDir, get
 
 /** 添加package.json配置 */
 export declare const addPackageConfig: ({ patchConfig, rootDir, }: {
-    patchConfig?: Record<string, any> | undefined;
+    patchConfig?: Record<string, any>;
     rootDir: string;
 }) => void;
 
+/** 允许输出日志到控制台 */
+export declare const allowConsoleLog: () => boolean;
+
 /**
  * 申请使用临时目录
  * ---
@@ -43,15 +48,17 @@ export declare const applyUseTempDir: <T>({ dir, fn, endClear, exitClear, }: {
     dir: string;
     fn: (dir: string) => T;
     /** 结束时移除临时目录 */
-    endClear?: boolean | undefined;
+    endClear?: boolean;
     /** 退出信号是否移除临时目录 */
-    exitClear?: boolean | undefined;
+    exitClear?: boolean;
 }) => T;
 
 export { ArgumentsCamelCase }
 
 /** 文件或文件夹是否存在(同步) */
-export declare const assetIsExits: (assetPath: string) => boolean;
+export declare const assetIsExits: (
+/** 资源路径 */
+assetPath: string) => boolean;
 
 /**
  * 检查路径是否存在（包括文件、目录、符号链接）
@@ -121,6 +128,9 @@ export declare function decryptAES({ encryptedText, secretKey, }: {
     secretKey: string;
 }): string;
 
+/** done-coding 全局环境配置symbol */
+declare const DONE_CONFIG_ENV_CONFIG_GLOBAL_SYMBOL: unique symbol;
+
 /** done-coding-cli 全局配置 */
 export declare type DoneCodingCliGlobalConfig = {
     [K in DoneCodingCliGlobalConfigKeyEnum]: string;
@@ -153,11 +163,97 @@ export declare function encryptAES({ text, secretKey, }: {
     secretKey: string;
 }): string;
 
+/**
+ * 环境配置
+ * ----
+ * !!! 不应包含token等敏感信息， 只作为通过环境变量标识及相关 如标记mcp调用场景及相关日志行为等
+ * ----
+ * !!! 不作为主要的通信方式
+ */
+export declare interface EnvConfig {
+    /** 调用模式 */
+    callMode: EnvConfigCallModeEnum;
+    /** 系列
+     * ----
+     * 规划的系列 会有 cli 、server等
+     * 默认会是 `${DONE_CODING_SERIES_DEFAULT}`
+     */
+    series: string;
+    /** 是否允许日志输出到控制台 */
+    consoleLog: boolean;
+    /** 日志输出路径 */
+    logOutputDir: string;
+    /**
+     * 进程日志文件名列表
+     * ----
+     * 新进程的日志从左侧进栈
+     */
+    processLogFileNameList: string[];
+}
+
+/** 环境配置 - 调用模式枚举 */
+export declare enum EnvConfigCallModeEnum {
+    DEFAULT = "DEFAULT",
+    MCP = "MCP"
+}
+
+/**
+ * 环境配置 在进程中 key的初始值枚举
+ */
+export declare enum EnvConfigProcessKeyEnum {
+    /**
+     * 全局配置镜像
+     */
+    GLOBAL_CONFIG_IMAGE = "GLOBAL_CONFIG_IMAGE"
+}
+
+/**
+ * 工业级同步执行分发日志 (2026 稳定版)
+ */
+export declare const execSyncWithLogDispatch: (command: string, options?: ExecSyncOptions) => string | Buffer;
+
 /** 文件添加执行权限 */
 export declare const fileAddX: (filePath: string) => void;
 
+/** 格式化日志流写入格式 */
+export declare const formatLogSteamWrite: ({ stream, type, content, }: {
+    /** 流类型 */
+    stream: WriteStream;
+    /** 日志类型 */
+    type: LogTypeEnum;
+    /** 日志内容 */
+    content: string;
+}) => boolean;
+
 export { _get }
 
+/** 快捷获取答案 */
+export declare const getAnswerSwift: <V = unknown, T extends string = string>(key: T, 
+/** 表单问询配置 */
+questionConfig: Parameters<typeof prompts<T>>[0]) => Promise<V>;
+
+/**
+ * 获取答案 考虑mcp情况
+ * ----
+ * mcp 只拿预设值，非mcp优先拿默认值
+ * 有预设值的场景: MCP
+ */
+export declare const getAnswerWithMCP: <V = unknown, T extends string = string>({ isMCP, key, presetAnswer, defaultValue, questionConfig, }: {
+    /** 是否mcp场景 */
+    isMCP: boolean;
+    /** 表单key */
+    key: T;
+    /** 预设答案所在的对象 */
+    presetAnswer?: object & { [K in T]: any; };
+    /** 默认值 */
+    defaultValue?: V;
+    /** 表单问询配置 */
+    questionConfig: Parameters<typeof prompts<T>>[0];
+}) => Promise<V>;
+
+/** 获取调用模式 */
+export declare const getCallMode: () => EnvConfigCallModeEnum;
+
 /** 获取cli模块【临时】目录[绝对路径] */
 export declare const getCliModuleTempDir: (moduleName: string) => string;
 
@@ -170,19 +266,22 @@ export declare const getCommitByHookName: ({ hookName, rootDir, }: {
 /** 获取配置文件通用选项 */
 export declare const getConfigFileCommonOptions: ({ configPathDefault, rootDirDefault, }: {
     configPathDefault: string;
-    rootDirDefault?: string | undefined;
+    rootDirDefault?: string;
 }) => Record<keyof ConfigFileCommonOptions, YargsOptions>;
 
 /** 获取当前分支最近提交列表 */
 export declare const getCurrentBranchLastCommitList: ({ count, }?: {
-    count?: number | undefined;
+    count?: number;
     /** 某个hash之后的提交 */
-    afterHash?: string | undefined;
+    afterHash?: string;
 }) => GitLogItemInfo[];
 
 /** 获取当前分支名 */
 export declare const getCurrentBranchName: () => string | undefined;
 
+/** 获取自身进程日志文件名 */
+export declare const getCurrentProcessLogFileName: () => string;
+
 /** 获取编辑器类型 */
 export declare const getEditorType: () => Promise<any>;
 
@@ -199,20 +298,37 @@ export declare interface GetGitLastCommitParams {
     remoteAlias?: GitRemoteInfo["alias"];
 }
 
+/**
+ * 获取git路径
+ * ---
+ * @param projectPath 项目路径
+ */
+export declare const getGitPath: (projectPath: string) => string;
+
 /** 获取git项目目录 */
 export declare const getGitProjectDir: (rootDir: string) => string;
 
 /** 获取最后的reflog */
 export declare const getLastReflogList: ({ count, filterItem, }?: {
-    count?: number | undefined;
+    count?: number;
     /** 某个hash之后的提交 */
-    afterHash?: string | undefined;
+    afterHash?: string;
     /** 过滤函数 */
-    filterItem?: ((item: GitReflogItemInfoRaw) => boolean) | undefined;
+    filterItem?: (item: GitReflogItemInfoRaw) => boolean;
 }) => GitReflogItemInfo[];
 
+/**
+ * 获取日志文件夹
+ * ----
+ * 绝对路径
+ * @param persistent 是否持久话
+ */
+export declare const getLogOutputDir: (persistent?: boolean) => string;
+
 /** 获取输出文字 */
 export declare const getLogText: ((type: LogTypeEnum, ...messages: unknown[]) => string) & {
+    /** 系统 */
+    system: (...messages: unknown[]) => string;
     /** 成功 */
     success: (...messages: unknown[]) => string;
     /** /步骤 */
@@ -225,17 +341,34 @@ export declare const getLogText: ((type: LogTypeEnum, ...messages: unknown[]) =>
     error: (...messages: unknown[]) => string;
     /** 跳过 */
     skip: (...messages: unknown[]) => string;
+    /** 表格 */
+    table: (...messages: unknown[]) => string;
 };
 
+/** 格式: 2026-01-18 11:38:05 */
+export declare const getLogTime: () => string;
+
+/** 通过 LogTypeEnum 枚举值或者key */
+export declare const getLogTypeByValue: (value: LogTypeEnum) => string;
+
 /** 获取package.json文件内容 */
 export declare const getPackageJson: <R extends PackageJson>({ rootDir, }: {
     rootDir: string;
 }) => R;
 
+/** 获取父级进程日志文件名 */
+export declare const getParentProcessLogFileName: () => string | undefined;
+
+/** 获取环境变量 */
+export declare const getProcessEnv: <T>(keyInit: EnvConfigProcessKeyEnum, defaultValue?: T) => T | undefined;
+
+/** 获取当前进程对应的日志流 */
+export declare const getProcessLogStream: () => XFsWriteStream;
+
 /** 获取依赖包版本 */
 export declare const getRelyPkgVersion: <R extends PackageJson>({ rootDir, pkgJson, pkgName, isDevPkg, }: {
     rootDir: string;
-    pkgJson?: R | undefined;
+    pkgJson?: R;
     pkgName: string;
     /** 是开发依赖包 */
     isDevPkg: boolean;
@@ -248,10 +381,13 @@ export declare const getRootDirOptions: (rootDirDefault?: string) => {
 
 /** 获取根命令名称 */
 export declare const getRootScriptName: ({ rootScriptName, packageJson, }: {
-    rootScriptName?: string | undefined;
-    packageJson?: Pick<PackageJson, "name" | "bin"> | undefined;
+    rootScriptName?: string;
+    packageJson?: Pick<PackageJson, "name" | "bin">;
 }) => string | undefined;
 
+/** 获取安全路径 */
+export declare const getSafePath: (path?: string) => string;
+
 /** 获取是否使用默认配置 */
 export declare const getUseDefaultConfig: () => Promise<any>;
 
@@ -431,16 +567,32 @@ export declare const initConfigFile: <T>(content: T, argv: CliHandlerArgv<InitCo
 /** 初始化文件选项 */
 export declare type InitConfigFileOptions = ConfigFileCommonOptions;
 
+/**
+ * 初始化环境配置
+ * ---
+ * !!! 顶级进程才调用且只能调用一次
+ * 非顶级进程调用会忽略入参 即优先使用父级设置的进程配置
+ * ---
+ * 即顶级进程调用
+ * 非顶级进程通过进程环境继承
+ */
+export declare const initEnvConfig: ({ series, ...otherConfig }: Partial<Pick<EnvConfig, "callMode" | "consoleLog"> & {
+    series: string;
+}>) => EnvConfig;
+
 /** 初始化配置文件通用处理器 */
 export declare const initHandlerCommon: <T>(content: T, argv: CliHandlerArgv<InitConfigFileOptions>, { onFileGenerated, edit, }?: {
     /** 文件已生成 */
-    onFileGenerated?: ((path: string) => void) | undefined;
-    edit?: boolean | undefined;
+    onFileGenerated?: (path: string) => void;
+    edit?: boolean;
 }) => Promise<void>;
 
 /** 是http git地址 */
 export declare const isHttpGitUrl: (url: string) => boolean;
 
+/** 是mcp模式 */
+export declare const isMcpMode: () => boolean;
+
 /** 是 ssh git地址 */
 export declare const isSshGitUrl: (url: string) => boolean;
 
@@ -448,6 +600,8 @@ export { json5 }
 
 /** 日志 */
 export declare const log: ((type: LogTypeEnum, ...messages: unknown[]) => void) & {
+    /** 系统 */
+    system: (...messages: unknown[]) => void;
     /** 成功 */
     success: (...messages: unknown[]) => void;
     /** /步骤 */
@@ -460,32 +614,40 @@ export declare const log: ((type: LogTypeEnum, ...messages: unknown[]) => void)
     error: (...messages: unknown[]) => void;
     /** 跳过 */
     skip: (...messages: unknown[]) => void;
+    /** 表格 */
+    table: (...messages: unknown[]) => void;
 };
 
 export declare type LogParams = [type: LogTypeEnum, ...messages: unknown[]];
 
 /** 日志类型 */
-declare enum LogTypeEnum {
+export declare enum LogTypeEnum {
+    /** 系统 */
+    SYSTEM = "magenta",
     /** 成功 */
-    SUCCESS = "green",
+    SUCCESS = "greenBright",
     /** 步骤 */
     STAGE = "blue",
     /** 提示信息 */
-    INFO = "cyan",
+    INFO = "white",
     /** 警告 */
     WARN = "yellow",
     /** 错误 */
-    ERROR = "red",
+    ERROR = "redBright",
     /** 跳过 */
-    SKIP = "gray"
+    SKIP = "dim",
+    /** ---- 表格 ---- */
+    TABLE = "table"
 }
 
 /**
  * 查找目标文件或目录
  */
-export declare const lookForParentTarget: (target: string, { currentDir, isFindFarthest, }?: {
-    currentDir?: string | undefined;
-    isFindFarthest?: boolean | undefined;
+export declare const lookForParentTarget: (
+/** 目标文件或目录 */
+target: string, { currentDir, isFindFarthest, }?: {
+    currentDir?: string;
+    isFindFarthest?: boolean;
 }) => string | undefined;
 
 /** 用编辑器打开文件 */
@@ -503,6 +665,14 @@ export declare interface PackageJson {
     peerDependencies?: Record<string, string>;
 }
 
+/** 路径是否安全 */
+export declare const pathIsSafe: (path?: string) => boolean;
+
+/** 进程值变量初始值 */
+export declare interface ProcessValueInit<T> {
+    value: T;
+}
+
 export { PromptAnswers }
 
 export { PromptChoice }
@@ -525,7 +695,7 @@ export { PromptValueOrFunc }
 export declare const pushGitPublishInfoToRemote: ({ branchName, version, remoteInfo, }: {
     branchName: string;
     version: string;
-    remoteInfo?: GitRemoteInfo | undefined;
+    remoteInfo?: GitRemoteInfo;
 }) => void;
 
 /** 读取(某个模块)配置 */
@@ -550,7 +720,7 @@ export declare const readCliModuleAssetsConfig: <R>({ moduleName, onSuccess, }:
 }) => Promise<R>;
 
 /** 读取配置文件 */
-export declare const readConfigFile: <T>(options: ReadConfigFileOptions, onNotExists?: (() => T) | undefined) => Promise<T>;
+export declare const readConfigFile: <T>(options: ReadConfigFileOptions, onNotExists?: () => T) => Promise<T>;
 
 /** 读取配置文件选项 */
 export declare type ReadConfigFileOptions = ConfigFileCommonOptions;
@@ -562,24 +732,32 @@ export declare const readFile: (assetPath: string) => string;
 export declare const readFileAsync: (assetPath: string) => Promise<string>;
 
 /** 读取json文件[同步] */
-export declare const readJsonFile: <T>(assetPath: string, defaultValue?: T | undefined) => T;
+export declare const readJsonFile: <T>(assetPath: string, defaultValue?: T) => T;
 
 /** 读取json文件[异步] */
-export declare const readJsonFileAsync: <T>(assetPath: string, defaultValue?: T | undefined) => Promise<T>;
+export declare const readJsonFileAsync: <T>(assetPath: string, defaultValue?: T) => Promise<T>;
 
 /**
  * 删除资源 (同步)
  * ---
  * 无论文件还是文件夹
  */
-export declare const removeAsset: (assetPath: string, force?: boolean) => void;
+export declare const removeAsset: (
+/** 资源路径 */
+assetPath: string, 
+/** 是否要强删除 */
+force?: boolean) => void;
 
 /**
  * 删除资源 (异步)
  * ---
  * 无论文件还是文件夹
  */
-export declare const removeAssetAsync: (assetPath: string, force?: boolean) => Promise<void>;
+export declare const removeAssetAsync: (
+/** 资源路径 */
+assetPath: string, 
+/** 是否要强删除 */
+force?: boolean) => Promise<void>;
 
 /** 解析checkoutInfo */
 export declare const resolveCheckoutInfoByRefInfo: (message: string) => {
@@ -596,6 +774,13 @@ export declare const resolveMergeInfoByGitReflogAction: () => GitMergeBranchInfo
 /** 从reflog type解析合并信息 */
 export declare const resolveMergeInfoByRefType: (type: string) => GitMergeBranchInfo | undefined;
 
+/**
+ * 移除git控制 - 异步
+ * @param projectPath
+ * @returns
+ */
+export declare const rmGitCtrlAsync: (projectPath: string) => Promise<void>;
+
 export { _set }
 
 /** 子cli信息 */
@@ -609,10 +794,21 @@ export declare const SUPPORT_GET_COMMIT_BY_HOOKS_NAMES: readonly [HooksNameEnum.
 
 export declare type SupportGetCommitByHookName = (typeof SUPPORT_GET_COMMIT_BY_HOOKS_NAMES)[number];
 
-export { uuidv4 }
+export declare const uuidv4: () => `${string}-${string}-${string}-${string}-${string}`;
+
+/**
+ * fs.WriteStream 确实没有直接声明 fd 属性（虽然运行时它确实存在）。这是因为 fd 是由底层的物理文件句柄分配的，其类型定义在内部较为隐蔽。
+ */
+declare interface XFsWriteStream extends fs.WriteStream {
+    fd?: number;
+}
+
+export declare interface XGlobalThis {
+    [DONE_CONFIG_ENV_CONFIG_GLOBAL_SYMBOL]: EnvConfig;
+}
 
 /** prompts 拓展 */
-export declare const xPrompts: <T extends string = string>(questions: prompts.PromptObject<T> | prompts.PromptObject<T>[], options?: prompts.Options | undefined) => Promise<prompts.Answers<T>>;
+export declare const xPrompts: <T extends string = string>(...args: Parameters<typeof prompts<T>>) => Promise<prompts.Answers<T>>;
 
 export { YargsArgv }