@done-coding/cli-utils 0.8.2-alpha.0 → 0.8.2-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/cli-utils",
-  "version": "0.8.2-alpha.0",
+  "version": "0.8.2-alpha.2",
   "description": "cli utils",
   "private": false,
   "module": "es/index.mjs",
@@ -47,7 +47,6 @@
     "@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.8.3",
@@ -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": "b09dd794f69ba2dafe22a3519d712d059c2eb376"
+  "gitHead": "7683cce31678dfecc6b35014f9658ad8b59f0c97"
 }

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';
@@ -34,6 +36,9 @@ export declare const addPackageConfig: ({ patchConfig, rootDir, }: {
     rootDir: string;
 }) => void;
 
+/** 允许输出日志到控制台 */
+export declare const allowConsoleLog: () => boolean;
+
 /**
  * 申请使用临时目录
  * ---
@@ -123,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;
@@ -155,15 +163,76 @@ 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 { _get }
-
-/** 快捷获取答案 */
-export declare const getAnswerSwift: <V = unknown, T extends string = string>(key: T, 
+/** 格式化日志流写入格式 */
+export declare const formatLogSteamWrite: ({ stream, type, content, }: {
+    /** 流类型 */
+    stream: WriteStream;
+    /** 日志类型 */
+    type: LogTypeEnum;
+    /** 日志内容 */
+    content: string;
+}) => boolean;
+
+/** 生成 获取答案的快捷函数 */
+export declare const generateGetAnswerSwiftFn: ({ isMCP, presetAnswer, }: Pick<GetAnswerOptions<unknown, string>, "isMCP" | "presetAnswer">) => <V = unknown, T extends string = string>(key: T, 
 /** 表单问询配置 */
-questionConfig: Parameters<typeof prompts<T>>[0]) => Promise<V>;
+questionConfig?: Parameters<typeof prompts<T>>[0], 
+/** 默认值 */
+defaultValue?: V) => Promise<V | undefined>;
+
+export { _get }
 
 /**
  * 获取答案 考虑mcp情况
@@ -171,18 +240,29 @@ questionConfig: Parameters<typeof prompts<T>>[0]) => Promise<V>;
  * mcp 只拿预设值，非mcp优先拿默认值
  * 有预设值的场景: MCP
  */
-export declare const getAnswerWithMCP: <V = unknown, T extends string = string>({ isMCP, key, presetAnswer, defaultValue, questionConfig, }: {
+export declare const getAnswer: <V = unknown, T extends string = string>({ isMCP, key, presetAnswer, defaultValue, questionConfig, }: GetAnswerOptions<V, T>) => GetAnswerResult<V, T, typeof questionConfig>;
+
+/** 获取答案 考虑mcp情况 的选项 */
+export declare interface GetAnswerOptions<V, T extends string> {
     /** 是否mcp场景 */
-    isMCP: boolean;
+    isMCP?: boolean;
     /** 表单key */
     key: T;
     /** 预设答案所在的对象 */
-    presetAnswer?: object & { [K in T]: any; };
+    presetAnswer?: object & {
+        [K in T]?: any;
+    };
     /** 默认值 */
     defaultValue?: V;
     /** 表单问询配置 */
-    questionConfig: Parameters<typeof prompts<T>>[0];
-}) => Promise<V>;
+    questionConfig?: Parameters<typeof prompts<T>>[0];
+}
+
+/** 获取答案结果类型 */
+export declare type GetAnswerResult<V, T extends string, Q extends GetAnswerOptions<V, T>["questionConfig"]> = Promise<Q extends undefined ? V | undefined : V>;
+
+/** 获取调用模式 */
+export declare const getCallMode: () => EnvConfigCallModeEnum;
 
 /** 获取cli模块【临时】目录[绝对路径] */
 export declare const getCliModuleTempDir: (moduleName: string) => string;
@@ -209,6 +289,9 @@ export declare const getCurrentBranchLastCommitList: ({ count, }?: {
 /** 获取当前分支名 */
 export declare const getCurrentBranchName: () => string | undefined;
 
+/** 获取自身进程日志文件名 */
+export declare const getCurrentProcessLogFileName: () => string;
+
 /** 获取编辑器类型 */
 export declare const getEditorType: () => Promise<any>;
 
@@ -244,8 +327,18 @@ export declare const getLastReflogList: ({ count, filterItem, }?: {
     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;
     /** /步骤 */
@@ -258,13 +351,30 @@ 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;
@@ -285,6 +395,9 @@ export declare const getRootScriptName: ({ rootScriptName, packageJson, }: {
     packageJson?: Pick<PackageJson, "name" | "bin">;
 }) => string | undefined;
 
+/** 获取安全路径 */
+export declare const getSafePath: (path?: string) => string;
+
 /** 获取是否使用默认配置 */
 export declare const getUseDefaultConfig: () => Promise<any>;
 
@@ -464,6 +577,19 @@ 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, }?: {
     /** 文件已生成 */
@@ -474,6 +600,9 @@ export declare const initHandlerCommon: <T>(content: T, argv: CliHandlerArgv<Ini
 /** 是http git地址 */
 export declare const isHttpGitUrl: (url: string) => boolean;
 
+/** 是mcp模式 */
+export declare const isMcpMode: () => boolean;
+
 /** 是 ssh git地址 */
 export declare const isSshGitUrl: (url: string) => boolean;
 
@@ -481,6 +610,8 @@ export { json5 }
 
 /** 日志 */
 export declare const log: ((type: LogTypeEnum, ...messages: unknown[]) => void) & {
+    /** 系统 */
+    system: (...messages: unknown[]) => void;
     /** 成功 */
     success: (...messages: unknown[]) => void;
     /** /步骤 */
@@ -493,24 +624,30 @@ 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"
 }
 
 /**
@@ -538,6 +675,22 @@ export declare interface PackageJson {
     peerDependencies?: Record<string, string>;
 }
 
+/**
+ * 参数转cli参数
+ * -----
+ * yargs 参数格式：
+ * --key=value
+ */
+export declare const params2cliParams: (params: Record<string, any>) => string;
+
+/** 路径是否安全 */
+export declare const pathIsSafe: (path?: string) => boolean;
+
+/** 进程值变量初始值 */
+export declare interface ProcessValueInit<T> {
+    value: T;
+}
+
 export { PromptAnswers }
 
 export { PromptChoice }
@@ -659,7 +812,18 @@ 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>(...args: Parameters<typeof prompts<T>>) => Promise<prompts.Answers<T>>;