@wwkit/shared 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bluesliu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @wwkit/shared
+
+Shared utilities for @wwkit packages.
+
+## config-loader
+
+多层配置加载器：内置 `config.json5` + 环境变量注入内容 + 用户 `config.json5` 合并（用户优先）。
+
+**默认行为（无需配置）**：
+- **深合并**（`deepMerge`），嵌套配置只覆盖用户改写的字段，保留其余默认
+- 结果默认解析 `{env:XXX}` 占位符（安全实践：密钥用环境变量引用，不落盘明文）
+
+**可选层（通过选项开启）**：
+- `envContentVar`：指定环境变量名，其内容作为"注入配置"这一层参与合并（同样走深合并+占位符解析）
+- `envDirVar`：指定环境变量名，其值覆盖用户配置目录
+
+```js
+import { createConfigLoader, getXdgConfigDir } from '@wwkit/shared'
+
+const loader = createConfigLoader({
+  builtinConfigPath: path.join(__dirname, 'config.json5'),
+  userConfigDir: getXdgConfigDir('cft'),
+  envContentVar: 'MY_CONFIG_CONTENT',   // 可选
+  envDirVar: 'MY_CONFIG_DIR',           // 可选
+})
+
+loader.copyBuiltinConfig()  // 复制内置→用户目录（不覆盖已存在）
+const cfg = loader.getConfig()  // 深合并 + 占位符解析
+```
+
+### 导出的工具函数
+
+- `deepMerge(base, override)` — 深合并（嵌套对象合并，数组/标量覆盖）
+- `resolveEnvVars(value, env?)` — 递归解析 `{env:XXX}` 占位符
+- `getXdgConfigDir(subdir)` — `~/.config/<subdir>` 或 `$XDG_CONFIG_HOME/<subdir>`

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@wwkit/shared",
+  "version": "1.0.1",
+  "author": "bluesliu <langcai163@163.com>",
+  "description": "Shared utilities for @wwkit packages — config loader, platform detection",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "jest": {
+    "transform": {},
+    "testMatch": [
+      "**/tests/unit/**/*.test.js"
+    ]
+  },
+  "keywords": [
+    "wwkit",
+    "shared",
+    "config"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "json5": "^2.2.3"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/unit",
+    "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/unit",
+    "release": "pnpm version patch && pnpm publish"
+  }
+}

package/src/config-loader.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import process from 'node:process'
+import JSON5 from 'json5'
+
+const ENV_PATTERN = /\{env:(\w+)\}/
+
+/**
+ * 递归合并对象，override 优先，嵌套对象深合并（数组/标量直接覆盖）。
+ */
+export function deepMerge(base, override) {
+  const merged = { ...(base ?? {}) }
+  for (const [key, value] of Object.entries(override ?? {})) {
+    if (value && typeof value === 'object' && !Array.isArray(value)
+        && merged[key] && typeof merged[key] === 'object' && !Array.isArray(merged[key])) {
+      merged[key] = deepMerge(merged[key], value)
+    } else {
+      merged[key] = value
+    }
+  }
+  return merged
+}
+
+/**
+ * 递归解析字符串中的 {env:XXX} 占位符，替换为环境变量值（未设置则为空串）。
+ */
+export function resolveEnvVars(value, env = process.env) {
+  if (typeof value === 'string') {
+    return value.replace(ENV_PATTERN, (_, name) => env[name] ?? '')
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => resolveEnvVars(v, env))
+  }
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) out[k] = resolveEnvVars(v, env)
+    return out
+  }
+  return value
+}
+
+/**
+ * 多层配置加载器：内置 config.json5 + 用户 config.json5 + 环境变量注入内容（优先级从低到高）。
+ *
+ * 默认行为（无需配置）：
+ *   - 深合并（deepMerge），非浅合并
+ *   - 结果默认解析 {env:XXX} 占位符
+ *
+ * 可选层（通过选项开启）：
+ *   - envContentVar: 指定环境变量名，其内容作为"注入配置"这一层参与合并（优先级最高，同样走深合并+占位符解析）
+ *   - envDirVar:     指定环境变量名，其值覆盖用户配置目录
+ *
+ * 用法：
+ *   const loader = createConfigLoader({
+ *     builtinConfigPath: path.join(__dirname, 'config.json5'),
+ *     userConfigDir: getXdgConfigDir('cft'),
+ *   })
+ *   loader.copyBuiltinConfig()  // 复制内置→用户目录（不覆盖已存在）
+ *   const cfg = loader.getConfig()
+ */
+export function createConfigLoader({ builtinConfigPath, userConfigDir, envContentVar = null, envDirVar = null }) {
+  const getUserDir = () => (envDirVar ? (process.env[envDirVar] ?? userConfigDir) : userConfigDir)
+  const getUserConfigPath = () => path.join(getUserDir(), 'config.json5')
+
+  function loadJson5(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) return {}
+    try {
+      return JSON5.parse(fs.readFileSync(filePath, 'utf-8'))
+    } catch {
+      return {}
+    }
+  }
+
+  function loadContent(content) {
+    if (!content) return {}
+    try {
+      return JSON5.parse(content)
+    } catch {
+      return {}
+    }
+  }
+
+  function getConfig() {
+    const builtin = loadJson5(builtinConfigPath)
+    const user = loadJson5(getUserConfigPath())
+    let merged = deepMerge(builtin, user)
+    if (envContentVar) {
+      merged = deepMerge(merged, loadContent(process.env[envContentVar]))
+    }
+    return resolveEnvVars(merged)
+  }
+
+  function copyBuiltinConfig() {
+    const dir = getUserDir()
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+    const userPath = getUserConfigPath()
+    if (!fs.existsSync(userPath) && fs.existsSync(builtinConfigPath)) {
+      fs.copyFileSync(builtinConfigPath, userPath)
+      return true
+    }
+    return false
+  }
+
+  return {
+    getConfig,
+    copyBuiltinConfig,
+    userConfigDir: getUserDir(),
+    userConfigPath: getUserConfigPath(),
+  }
+}
+
+/**
+ * 获取 XDG 配置目录下的子路径。
+ * ~/.config/<subdir>  或  $XDG_CONFIG_HOME/<subdir>
+ */
+export function getXdgConfigDir(subdir) {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config')
+  return path.join(xdg, subdir)
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createConfigLoader, getXdgConfigDir, deepMerge, resolveEnvVars } from './config-loader.js'