@h-ai/core 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/{core-types-_JqVAGGT.d.ts → core-types-Irg7caTy.d.ts}

@@ -330,7 +330,88 @@ declare const zodValidation: {
  * if (!result.success) result.error.message
  * ```
  */
-declare const config$1: ConfigFn;
+declare const config$1: {
+    loadEnvFiles(_options: {
+        mode: string;
+        envDir?: string;
+    }): HaiResult<Record<string, string>>;
+    load<T>(_name: string, _filePath: string, _schema?: ZodType<T>): HaiResult<T>;
+    validate<T>(_name: string, _schema: ZodType<T>): HaiResult<T>;
+    get<T>(_name: string): T | undefined;
+    getOrThrow<T>(_name: string): T;
+    reload(_name: string): HaiResult<unknown>;
+    has(_name: string): boolean;
+    clear(_name?: string): void;
+    keys(): string[];
+    watch<T = unknown>(_name: string, callback: WatchCallback<T>): () => void;
+    unwatch(_name?: string): void;
+    isWatching(_name: string): boolean;
+};
+
+/** 通用环境配置：来源合并、结构覆盖与无损 dotenv 编解码，不依赖业务模块。 */
+
+/**
+ * 单个环境来源中的字面变量，undefined 表示未设置。
+ * @example 模块内部上下文
+ * ```ts
+ * const values: Environment = { HAI_APP_NAME: 'Example' }
+ * ```
+ */
+type Environment = Record<string, string | undefined>;
+/**
+ * 从低到高合并来源；高来源父项删除旧细项，同来源始终先父后子。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+ * ```
+ */
+declare function mergeEnv(layers: readonly Environment[]): Record<string, string>;
+/**
+ * dotenv 使用 Node 字面规则；补齐生成器双引号的 JSON 转义，拒绝同文件重复键。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = parseEnvironment('HAI_APP_NAME=Example\n')
+ * ```
+ */
+declare function parseEnvironment(text: string): Record<string, string>;
+/**
+ * 所有值均按字面量编码；排序让模块 JSON 位于其细项之前。
+ * @example 模块内部上下文
+ * ```ts
+ * const text = stringifyEnv({ HAI_APP_NAME: 'Example' })
+ * ```
+ */
+declare function stringifyEnv(values: Record<string, string>, options?: {
+    target?: 'node' | 'compose';
+}): string;
+/**
+ * 在给定结构上解析环境变量；父对象提供基础值，具体路径继续覆盖。
+ * @example 模块内部上下文
+ * ```ts
+ * const result = resolveEnvironment({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+ * ```
+ */
+declare function resolveEnvironment(options: {
+    name: string;
+    value: unknown;
+    environment?: Environment;
+    schema?: ZodType;
+    shape?: Readonly<Record<string, unknown>>;
+    missing?: 'error' | 'empty';
+}, literal?: boolean): HaiResult<unknown>;
+/**
+ * 默认展开对象，数组与动态键字典保留 JSON；不做模块名称判断。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+ * ```
+ */
+declare function toEnv(options: {
+    prefix: string;
+    value: unknown;
+    schema?: ZodType;
+    shape?: Readonly<Record<string, unknown>>;
+}): Record<string, string>;
 
 /**
  * 配置管理对象。
@@ -341,10 +422,67 @@ declare const config$1: ConfigFn;
  * ```
  */
 declare const config: {
+    /**
+     * 合并从低到高的环境来源；高来源父项替换旧节点，同来源细项覆盖父 JSON。
+     * @param layers - 按优先级排列的字面变量。
+     * @returns 合并后的变量，可能含秘密。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+     * ```
+     */
+    mergeEnv: typeof mergeEnv;
+    /**
+     * 解析 dotenv 字面文本，拒绝重复键，不执行 shell 或变量展开。
+     * @param text - dotenv 文本，可能包含秘密。
+     * @returns 字面变量；重复键抛出不含变量值的错误。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.parseEnv('HAI_APP_NAME=Example\n')
+     * ```
+     */
+    parseEnv: typeof parseEnvironment;
+    /**
+     * 无损编码 dotenv，父变量排在细项前；含秘密时只能写入受保护文件。
+     * @param values - 字面变量，不进行脱敏。
+     * @param options - 输出语法目标，默认 Node dotenv。
+     * @param options.target - Compose 目标同时处理其美元符号插值规则。
+     * @returns dotenv 文本；非法变量名抛错。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.stringifyEnv({ HAI_APP_NAME: 'Example' })
+     * ```
+     */
+    stringifyEnv: typeof stringifyEnv;
+    /**
+     * 按已有结构或 Schema 解析父 JSON 和细项，不修改缓存或进程环境。
+     * @param options - 配置名、原始结构、变量、可选 Schema 和缺失插值规则。
+     * @returns 解析结果；调用方仍须执行最终 Schema 校验。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.resolve({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+     * ```
+     */
+    resolve: (options: Parameters<typeof resolveEnvironment>[0]) => HaiResult<unknown>;
+    /**
+     * 默认将对象展开为细项；数组、动态字典和空对象保留 JSON。
+     * @param options - 完整变量前缀、配置值和可选 Schema。
+     * @returns 字面环境变量，不脱敏；非法名称抛错。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+     * ```
+     */
+    toEnv: typeof toEnv;
     /**
      * 读取 dotenv 文件并按统一顺序合并，不修改进程环境。
      *
-     * 优先级：已有进程环境 > .env.local > .env.<mode> > .env。
+     * 优先级：已有进程环境 > .env.<mode>.local > .env.local > .env.<mode> > .env。
      * development/production 分别映射到 dev/prod；不存在的文件跳过。
      * 返回值可能包含私有配置，仅在 Node 启动/构建边界注入，不下发浏览器。
      * @param options - 文件所在目录及环境模式
@@ -2194,6 +2332,8 @@ interface CoreOptions {
      * ```
      */
     configDir?: string;
+    /** 宿主显式提供模块 Schema，供扫描时识别可选字段和环境变量类型；Core 不注册业务模块。 */
+    configSchemas?: Readonly<Record<string, z.ZodType>>;
     /** 是否启用配置文件监听（默认 false） */
     watchConfig?: boolean;
 }

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { W as NodeCoreFunctions } from './core-types-_JqVAGGT.js';
-export { A as AccessCondition, a as AccessConditionSchema, b as AccessDecision, c as AccessFunctions, d as ArrayFn, e as AsyncFn, f as BrowserConfigFn, B as BrowserCoreFunctions, C as ConfigFn, g as CoreConfig, h as CoreConfigSchema, i as CoreFunctions, j as CoreLogger, k as CoreOptions, l as CreateNotInitializedKitFn, E as Env, m as EnvSchema, n as ErrorFn, o as ErrorInfo, p as ErrorInfoValue, H as HaiCommonError, q as HaiConfigError, r as HaiError, s as HaiErrorDef, t as HaiResult, I as I18nFn, u as IdFn, v as InterpolationParams, L as Locale, w as LocaleInfo, x as LocaleMessages, y as LogContext, z as LogFormat, D as LogFormatSchema, F as LogLevel, G as LogLevelSchema, J as LogObserver, K as LogRecord, M as Logger, N as LoggerFunctions, O as LoggerOptions, P as LoggingConfig, Q as LoggingConfigSchema, R as MatchHandlers, S as MessageDictionary, T as MessageOptions, U as ModuleFn, V as ModuleRuntime, X as NotInitializedKit, Y as ObjectFn, Z as PaginatedResult, _ as PaginationOptions, $ as PaginationOptionsInput, a0 as RequestAccessCheck, a1 as RequestAccessConfigInput, a2 as RequestAccessConfigSchema, a3 as RequestAccessPolicy, a4 as RequestAccessPolicySchema, a5 as RequestContext, a6 as RequestEncryptionMode, a7 as RuntimeStep, a8 as SanitizeFn, a9 as SanitizeSensitiveFieldsOptions, aa as SensitiveKeyMatcher, ab as StringFn, ac as TimeFn, ad as TrustedProxies, ae as TrustedProxiesSchema, af as TypeUtilFn, ag as ValidationFormError, ah as WatchCallback, ai as ZodMessageGetter, aj as ZodValidationFn, ak as ZodValidationMessageKey, al as err, am as ok } from './core-types-_JqVAGGT.js';
+import { W as NodeCoreFunctions } from './core-types-Irg7caTy.js';
+export { A as AccessCondition, a as AccessConditionSchema, b as AccessDecision, c as AccessFunctions, d as ArrayFn, e as AsyncFn, f as BrowserConfigFn, B as BrowserCoreFunctions, C as ConfigFn, g as CoreConfig, h as CoreConfigSchema, i as CoreFunctions, j as CoreLogger, k as CoreOptions, l as CreateNotInitializedKitFn, E as Env, m as EnvSchema, n as ErrorFn, o as ErrorInfo, p as ErrorInfoValue, H as HaiCommonError, q as HaiConfigError, r as HaiError, s as HaiErrorDef, t as HaiResult, I as I18nFn, u as IdFn, v as InterpolationParams, L as Locale, w as LocaleInfo, x as LocaleMessages, y as LogContext, z as LogFormat, D as LogFormatSchema, F as LogLevel, G as LogLevelSchema, J as LogObserver, K as LogRecord, M as Logger, N as LoggerFunctions, O as LoggerOptions, P as LoggingConfig, Q as LoggingConfigSchema, R as MatchHandlers, S as MessageDictionary, T as MessageOptions, U as ModuleFn, V as ModuleRuntime, X as NotInitializedKit, Y as ObjectFn, Z as PaginatedResult, _ as PaginationOptions, $ as PaginationOptionsInput, a0 as RequestAccessCheck, a1 as RequestAccessConfigInput, a2 as RequestAccessConfigSchema, a3 as RequestAccessPolicy, a4 as RequestAccessPolicySchema, a5 as RequestContext, a6 as RequestEncryptionMode, a7 as RuntimeStep, a8 as SanitizeFn, a9 as SanitizeSensitiveFieldsOptions, aa as SensitiveKeyMatcher, ab as StringFn, ac as TimeFn, ad as TrustedProxies, ae as TrustedProxiesSchema, af as TypeUtilFn, ag as ValidationFormError, ah as WatchCallback, ai as ZodMessageGetter, aj as ZodValidationFn, ak as ZodValidationMessageKey, al as err, am as ok } from './core-types-Irg7caTy.js';
 import 'zod';
 
 /**