@wwkit/opm 1.0.13 → 1.0.15

package/README.md

@@ -67,6 +67,7 @@ pnpm opm <command> [args] [options]
 | `ftp <action>` | FTP 文件管理（上传/rsync/下载） |
 | `ensure <runtime> [version]` | 确保运行时已安装（node/php/python） |
 | `ping <host|proxy|registry>` | 验证主机、代理或所有 registry 的可访问性 |
+| `env <action>` | 环境变量管理（list/get/set，跨平台：Unix profile / Windows user 级注册表） |
 | `config [section]` | 查看常用配置（proxy + 各 registry 段，段名动态生成） |
 | `opencode <action>` | opencode 运维命令（安装/升级/清理/env）；裸 `opm opencode` 启动 TUI |
 | `harness <action>` | @wwkit/harness 插件管理（安装/升级/list/status/env/dir） |
@@ -532,6 +533,37 @@ opm ping registry -d                   # 输出完整 JSON 数组
 > `opm ping proxy` 从 `proxy.active` 解析代理 URL，提取主机名后 ping。
 > `opm ping registry` 遍历所有含 `registry` 配置的工具，并行 ping 各 active 地址的主机。
 
+### env
+
+```bash
+opm env list                         # 列出 opm 管理的环境变量（含配置文件路径）
+opm env list --all                   # 追加 process.env 全量，每条标注 managed: true/false
+opm env get PATH                     # 根据 key 取值（先查 opm 管理源，回退 process.env）
+opm env set FOO bar                  # 设置环境变量（替换已存在的）
+opm env set MY_API_KEY secret123     # 设置 API 密钥
+opm env search api                   # 按关键词匹配 key 或 value（忽略大小写）
+opm env search api --all             # 同时搜索 process.env
+opm env help                         # 通用介绍
+```
+
+输出格式：默认输出**简化文本**（list/search 按来源分组：`配置文件路径` 行 + `key = value` 行；get/set 输出单行 `key = value`）；加 `-j/--json` 输出完整 JSON。
+
+```bash
+opm env list                         # 简化文本（按来源分组）
+opm env list --json                  # JSON 数组
+opm env get PATH                     # 简化：PATH = /usr/bin:/bin
+opm env get PATH --json              # JSON 对象（含 source/scope）
+opm env set FOO bar                  # 简化：FOO = bar
+opm env set FOO bar --json           # JSON 对象（含 written/source）
+opm env search api                   # 简化：匹配项按来源分组
+opm env search api --json            # JSON 数组
+```
+
+> `list`/`search` 默认只作用于 `opm env set` 管理的变量（Unix 的 `# >>> wwkit NAME >>>` 标记块 / Windows manifest）；`--all` 在其基础上追加 `process.env` 全量，并给每条标注 `managed: true/false` 与来源。
+> `search <keyword>` 匹配 key 或 value 是否包含关键词（忽略大小写），可用 `-q/--query` 替代位置参数。
+> 跨平台：Unix 读写 shell profile（`.zshrc`/`.bashrc`/`.profile`/fish config），用 `# >>> wwkit NAME >>>` 标记块管理；Windows 用 `setx` 写 user 级注册表（`HKCU\Environment`），`list` 用 `reg query` 读取。
+> Windows 上 `setx` 不留标记，opm 通过 `~/.config/opm/env-managed.json` 记录哪些 user 级变量由 opm 管理；`set` 始终写入 user 级（无需管理员权限）。
+
 ### opencode
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwkit/opm",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "author": "bluesliu <langcai163@163.com>",
   "description": "Unified CLI — package management (npm/pip/dnf/apt) + config view + opencode maintenance",
   "type": "module",
@@ -35,7 +35,16 @@
     "basic-ftp": "^6.2.1",
     "extract-zip": "^2.0.1",
     "systeminformation": "^5.23.0",
-    "@wwkit/shared": "1.0.17"
+    "@wwkit/shared": "1.0.20"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "transform": {},
+    "testMatch": [
+      "**/tests/**/*.test.js"
+    ]
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -45,8 +54,8 @@
     "postinstall": "node scripts/postinstall.js",
     "check": "node --check bin/index.js",
     "start": "node bin/index.js",
-    "test": "node --test \"tests/**/*.test.js\"",
-    "test:all": "node --test \"tests/**/*.test.js\"",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests",
+    "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests",
     "doc": "node -e \"import('./src/cli/doc.js').then(m => m.generateDocHtml({ open: false }))\"",
     "release": "node ../../packages/shared/bin/release-pkg.js"
   }

package/src/binaries/base.js

@@ -17,7 +17,7 @@ import path from 'node:path'
 import { parseFlags } from '../cli/helpers/args.js'
 import { output } from '../formatter.js'
 import { getActiveRegistry, setActiveRegistry, getPresets, getActiveProxy, getUserConfigDir } from '../config.js'
-import { fetchText, downloadToFile } from '../managers/http.js'
+import { fetchText, downloadToFile } from '@wwkit/shared'
 import { getOs, OS_TYPES } from './platform.js'
 import { find as findExe } from './exefinder.js'
 import { verify as verifyDeps } from './depchecker.js'

package/src/cli/groups/env.js

@@ -0,0 +1,451 @@
+/**
+ * env 命令组 — 跨平台环境变量便捷管理
+ *
+ * 用法：
+ *   opm env list [--all]      列出 opm 管理的环境变量（含配置文件路径）；--all 追加 process.env 全量
+ *   opm env get <key>         根据 key 取值（先查 opm 管理的配置源，回退 process.env）
+ *   opm env set <key> <value> 设置值（替换已存在的）
+ *   opm env help              通用介绍
+ *
+ * 跨平台策略（复用 @wwkit/shared 的 Shell）：
+ *   Unix:    读写 shell profile（bash/zsh/fish），用 `# >>> wwkit NAME >>>` 标记块管理
+ *   Windows: setx 写 user 级注册表；list 用 reg query 读取；用 manifest 文件
+ *            （~/.config/opm/env-managed.json）识别哪些 user 级变量由 opm 管理
+ *            （setx 不留标记，无法从注册表本身区分）
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { Shell } from '@wwkit/shared'
+import { parseFlags } from '../helpers/args.js'
+import { output } from '../../formatter.js'
+import { getUserConfigDir } from '../../config.js'
+
+/** Windows 注册表环境变量键路径 */
+const WIN_USER_KEY = 'HKCU\\Environment'
+
+/** manifest 文件名（Windows 记录 opm 管理的 user 级变量 key） */
+const MANIFEST_FILE = 'env-managed.json'
+
+/**
+ * 反转 Shell.setEnvVar 的转义（[$`\\"] → \\$&）
+ * @param {string} s
+ * @returns {string}
+ */
+function unescapeEnvValue(s) {
+  return s.replace(/\\([$`\\"])/g, '$1')
+}
+
+/**
+ * 从一行 export/set 语句中提取变量值
+ * @param {string} line
+ * @param {string} key
+ * @returns {string|null}
+ */
+function parseEnvLine(line, key) {
+  const exportQuoted = line.match(new RegExp(`^export\\s+${key}="(.*)"\\s*$`))
+  if (exportQuoted) return unescapeEnvValue(exportQuoted[1])
+  const fishQuoted = line.match(new RegExp(`^set -gx\\s+${key}\\s+"(.*)"\\s*$`))
+  if (fishQuoted) return unescapeEnvValue(fishQuoted[1])
+  const exportBare = line.match(new RegExp(`^export\\s+${key}=(\\S+)\\s*$`))
+  if (exportBare) return exportBare[1]
+  const fishBare = line.match(new RegExp(`^set -gx\\s+${key}\\s+(\\S+)\\s*$`))
+  if (fishBare) return fishBare[1]
+  return null
+}
+
+/**
+ * 解析 profile 文件内容中的 wwkit 标记块，提取 opm 管理的环境变量
+ * @param {string} content
+ * @returns {{ key: string, value: string }[]}
+ */
+export function parseEnvBlocks(content) {
+  if (!content) return []
+  const lines = content.split('\n')
+  const result = []
+  let i = 0
+  while (i < lines.length) {
+    const marker = lines[i].match(/^# >>> wwkit (\S+) >>>/)
+    if (marker) {
+      const key = marker[1]
+      // 块体：标记行之后到下一个 wwkit 标记或 EOF 之间的非空非注释行
+      let j = i + 1
+      while (j < lines.length && lines[j].trim() === '') j++
+      if (j < lines.length && !lines[j].startsWith('# >>> wwkit')) {
+        const value = parseEnvLine(lines[j], key)
+        if (value !== null) result.push({ key, value })
+      }
+      i = j + 1
+    } else {
+      i++
+    }
+  }
+  return result
+}
+
+/**
+ * 解析 Windows `reg query` 输出，提取环境变量条目
+ * @param {string} output
+ * @returns {{ key: string, type: string, value: string }[]}
+ */
+export function parseRegOutput(output) {
+  if (!output) return []
+  const result = []
+  for (const line of output.split(/\r?\n/)) {
+    const m = line.match(/^\s+(\S+)\s+(REG_\S+)\s+(.*)$/)
+    if (m) result.push({ key: m[1], type: m[2], value: m[3] })
+  }
+  return result
+}
+
+/**
+ * 校验环境变量名合法性（字母/下划线开头，后接字母数字下划线）
+ * @param {string} key
+ * @returns {boolean}
+ */
+export function isValidEnvKey(key) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)
+}
+
+export class EnvGroup {
+  /**
+   * @param {{ shell?: Shell, configDir?: string }} [opts] - shell/configDir 注入用于测试
+   */
+  constructor(opts = {}) {
+    this.name = 'env'
+    this.desc = 'Manage environment variables (list/get/set) across platforms'
+    this.shell = opts.shell || new Shell()
+    this.configDir = opts.configDir || ''
+  }
+
+  /** @returns {string} manifest 文件绝对路径 */
+  _manifestPath() {
+    const dir = this.configDir || getUserConfigDir()
+    return path.join(dir, MANIFEST_FILE)
+  }
+
+  /**
+   * 读取 manifest 中的 opm 管理 key 集合（Windows 用）
+   * @returns {Set<string>}
+   */
+  _readManifest() {
+    try {
+      const raw = fs.readFileSync(this._manifestPath(), 'utf8')
+      const data = JSON.parse(raw)
+      return new Set(Array.isArray(data.keys) ? data.keys : [])
+    } catch {
+      return new Set()
+    }
+  }
+
+  /**
+   * 将 key 登记到 manifest（Windows set 时调用）
+   * @param {string} key
+   */
+  _addManagedKey(key) {
+    const keys = this._readManifest()
+    keys.add(key)
+    const dir = this.configDir || getUserConfigDir()
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(this._manifestPath(), JSON.stringify({ keys: [...keys] }, null, 2), 'utf8')
+  }
+
+  /**
+   * 列出 opm 管理的环境变量（默认 list 的数据源）
+   * Unix: 解析所有 profile 的 wwkit 标记块
+   * Windows: 读 manifest → 查 user 级注册表当前值
+   * @returns {object[]}
+   */
+  _managedItems() {
+    return this.shell.isWindows ? this._listWindowsManaged() : this._listUnix()
+  }
+
+  _listUnix() {
+    const items = []
+    for (const { path: profilePath, syntax } of this.shell.getProfiles()) {
+      let content = ''
+      try {
+        content = fs.readFileSync(profilePath, 'utf8')
+      } catch {}
+      for (const { key, value } of parseEnvBlocks(content)) {
+        items.push({ key, value, scope: 'user', source: profilePath, syntax })
+      }
+    }
+    return items
+  }
+
+  _listWindowsManaged() {
+    const managedKeys = this._readManifest()
+    if (managedKeys.size === 0) return []
+    const userVars = this._regQuery(WIN_USER_KEY)
+    const byKey = new Map(userVars.map((v) => [v.key, v]))
+    const items = []
+    for (const key of managedKeys) {
+      const v = byKey.get(key)
+      if (v) {
+        items.push({ key, value: v.value, scope: 'user', source: 'registry (user)', type: v.type })
+      } else {
+        // manifest 登记过但注册表中已不存在（外部删除）——标注缺失
+        items.push({ key, value: null, scope: 'user', source: 'registry (user)', missing: true })
+      }
+    }
+    return items
+  }
+
+  _regQuery(keyPath) {
+    try {
+      const result = spawnSync('reg', ['query', keyPath], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+      if (result.status !== 0) return []
+      return parseRegOutput(result.stdout || '')
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * --all：opm 管理的 ∪ process.env 全量，每条标注 managed
+   * @returns {object[]}
+   */
+  _listAll() {
+    const managedItems = this._managedItems()
+    const seen = new Set()
+    const items = []
+    for (const m of managedItems) {
+      items.push({ key: m.key, value: m.value, managed: true, source: m.source, scope: m.scope })
+      seen.add(m.key)
+    }
+    for (const [key, value] of Object.entries(process.env)) {
+      if (!seen.has(key)) {
+        items.push({ key, value, managed: false, source: 'process.env' })
+        seen.add(key)
+      }
+    }
+    return items
+  }
+
+  async run(argv) {
+    const [action, ...rest] = argv
+
+    if (!action || action === '-h' || action === '--help' || action === 'help') {
+      this.printHelp()
+      return
+    }
+
+    const parsed = parseFlags(rest)
+
+    switch (action) {
+      case 'list':
+        return this._list(parsed)
+      case 'get':
+        return this._get(parsed)
+      case 'set':
+        return this._set(parsed)
+      case 'search':
+        return this._search(parsed)
+      default:
+        console.error(`Unknown action: ${action}`)
+        this.printHelp()
+        process.exit(1)
+    }
+  }
+
+  /**
+   * 是否输出 JSON（--json / -j）
+   * @param {{ flags: object, positional: string[] }} parsed
+   * @returns {boolean}
+   */
+  _useJson(parsed) {
+    return parsed.flags.json === 'true' || parsed.flags.j === 'true'
+  }
+
+  /**
+   * 统一输出：--json 走 JSON，否则走 plain 格式化函数
+   * @param {{ flags: object, positional: string[] }} parsed
+   * @param {*} data - JSON 输出数据
+   * @param {() => string} plain - 简化字符串输出函数
+   */
+  _out(parsed, data, plain) {
+    if (this._useJson(parsed)) {
+      output(data)
+    } else {
+      console.log(plain())
+    }
+  }
+
+  /**
+   * list 简化格式：按 source 分组，每组标题为来源，下面 key = value 行
+   * @param {object[]} items
+   * @returns {string}
+   */
+  _formatListPlain(items) {
+    const groups = []
+    const groupMap = new Map()
+    for (const item of items) {
+      const source = item.source || 'unknown'
+      if (!groupMap.has(source)) {
+        const g = { source, entries: [] }
+        groupMap.set(source, g)
+        groups.push(g)
+      }
+      groupMap.get(source).entries.push(item)
+    }
+    return groups
+      .map((g) => [
+        g.source,
+        ...g.entries.map((e) => `${e.key} = ${e.value === null || e.value === undefined ? '(not set)' : e.value}`),
+      ].join('\n'))
+      .join('\n\n')
+  }
+
+  /**
+   * 列出环境变量
+   * 默认: 只显示 opm 管理的（Unix 标记块 / Windows manifest）
+   * --all: 追加 process.env 全量，每条标注 managed: true/false
+   * 输出: 默认简化文本（按 source 分组），--json 输出 JSON
+   * @param {{ flags: object, positional: string[] }} parsed
+   */
+  async _list(parsed) {
+    const all = parsed.flags.all === 'true' || parsed.flags.a === 'true'
+    const items = all ? this._listAll() : this._managedItems()
+    this._out(parsed, items, () => this._formatListPlain(items))
+  }
+
+  /**
+   * 根据 key 取值：先查 opm 管理的配置源，回退 process.env
+   * 输出: 默认 `key = value`（未找到 `key = (not found)`），--json 输出 JSON
+   * @param {{ flags: object, positional: string[] }} parsed
+   */
+  async _get(parsed) {
+    const key = parsed.positional[0] || parsed.flags.k || parsed.flags.key || ''
+    if (!key) {
+      console.error('Usage: opm env get <key>')
+      console.error('Missing required <key>')
+      process.exit(1)
+    }
+
+    const configured = this._managedItems()
+    const hit = configured.find((e) => e.key === key)
+    if (hit) {
+      this._out(parsed, { key, value: hit.value, found: true, source: hit.source, scope: hit.scope }, () => `${key} = ${hit.value}`)
+      return
+    }
+
+    if (process.env[key] !== undefined) {
+      const value = process.env[key]
+      this._out(parsed, { key, value, found: true, source: 'process.env' }, () => `${key} = ${value}`)
+      return
+    }
+
+    this._out(parsed, { key, value: null, found: false }, () => `${key} = (not found)`)
+  }
+
+  /**
+   * 设置环境变量（替换已存在的）
+   * Unix: 写入 shell profile 标记块；Windows: setx 写 user 级注册表 + manifest 登记
+   * @param {{ flags: object, positional: string[] }} parsed
+   */
+  async _set(parsed) {
+    const key = parsed.positional[0] || parsed.flags.k || parsed.flags.key || ''
+    const value = parsed.positional[1] ?? parsed.flags.v ?? parsed.flags.value ?? ''
+
+    if (!key) {
+      console.error('Usage: opm env set <key> <value>')
+      console.error('Missing required <key>')
+      process.exit(1)
+    }
+    if (!isValidEnvKey(key)) {
+      console.error(`Invalid env key: "${key}" (must start with letter/underscore, only letters/digits/underscore)`)
+      process.exit(1)
+    }
+    if (parsed.positional.length < 2 && !(parsed.flags.v || parsed.flags.value)) {
+      console.error('Usage: opm env set <key> <value>')
+      console.error('Missing required <value>')
+      process.exit(1)
+    }
+
+    const written = this.shell.setEnvVar(key, value)
+    if (this.shell.isWindows) {
+      this._addManagedKey(key)
+    }
+    const source = this.shell.isWindows
+      ? 'registry (user)'
+      : this.shell.getProfiles().map((p) => p.path)
+    const result = { key, value, written, source }
+    this._out(parsed, result, () => `${key} = ${value}${written ? '' : ' (no change)'}`)
+  }
+
+  /**
+   * 按关键词搜索环境变量（匹配 key 或 value，忽略大小写）
+   * 默认: 在 opm 管理的变量中搜索；--all 扩展至 process.env 全量
+   * 输出: 默认简化文本（按 source 分组），--json 输出 JSON
+   * @param {{ flags: object, positional: string[] }} parsed
+   */
+  async _search(parsed) {
+    const keyword = parsed.positional[0] || parsed.flags.q || parsed.flags.query || ''
+    if (!keyword) {
+      console.error('Usage: opm env search <keyword>')
+      console.error('Missing required <keyword>')
+      process.exit(1)
+    }
+
+    const all = parsed.flags.all === 'true' || parsed.flags.a === 'true'
+    const source = all ? this._listAll() : this._managedItems()
+    const kw = keyword.toLowerCase()
+    const matches = source.filter((e) => {
+      const k = String(e.key).toLowerCase()
+      const v = e.value === null || e.value === undefined ? '' : String(e.value).toLowerCase()
+      return k.includes(kw) || v.includes(kw)
+    })
+    this._out(parsed, matches, () => this._formatListPlain(matches))
+  }
+
+  printHelp() {
+    console.log(`
+Usage: opm env <action> [args] [options]
+
+Actions:
+  list [--all]            List opm-managed env vars with their config file path
+                          (default: only vars set via "opm env set";
+                           --all appends all process.env vars, each tagged managed: true/false)
+  get <key>               Get value by key (checks opm-managed sources first, then process.env)
+  set <key> <value>       Set value, replacing any existing one
+                          (Unix: shell profile marker block; Windows: setx user-level registry)
+  search <keyword> [--all]  Search env vars whose key or value contains keyword (case-insensitive)
+                          (default: opm-managed vars; --all also searches process.env)
+  help                    Show this help
+
+Options:
+  -k, --key <name>        Key (alternative to positional for get/set)
+  -v, --value <val>       Value (alternative to positional for set)
+  -q, --query <kw>        Keyword (alternative to positional for search)
+  -a, --all               Also list all process.env vars (tagged managed: true/false)
+  -j, --json              Output JSON (default: plain text)
+  -h, --help              Show this help
+
+Output:
+  default (no -j)         Plain text: list groups by source then "key = value" lines;
+                          get/set print a single "key = value" line
+  -j / --json             JSON object/array with full metadata
+
+Platform behavior:
+  Unix     read/write shell profiles (.zshrc/.bashrc/.profile/fish config)
+           via "# >>> wwkit NAME >>>" marker blocks
+  Windows  read/write user-level registry (HKCU\\Environment); writes via setx;
+           opm-managed keys tracked in ~/.config/opm/env-managed.json
+
+Examples:
+  opm env list
+  opm env list --all              # all process.env vars, tagged managed
+  opm env get PATH
+  opm env set FOO bar
+  opm env set MY_API_KEY secret123
+  opm env search api              # match key or value containing "api" (case-insensitive)
+  opm env search api --all        # also search process.env
+  opm env help
+`)
+  }
+}