@wwkit/opm 1.0.14 → 1.0.16

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
+`)
+  }
+}

package/src/cli/groups/package.js

@@ -57,7 +57,6 @@ const ACTIONS = {
   view:       { desc: 'Check package in global and project scopes' },
   info:       { desc: 'Show package details' },
   versions:   { desc: 'List all available versions of a package' },
-  outdated:   { desc: 'List outdated packages' },
   install:    { desc: 'Install a package' },
   uninstall:  { desc: 'Uninstall a package' },
   upgrade:    { desc: 'Upgrade a package' },
@@ -99,6 +98,26 @@ export class PackageGroup {
     await this._dispatch(manager, action, parsed, { global, proxy })
   }
 
+  /**
+   * 打印当前 registry 和 proxy（诊断信息，输出到 stderr）
+   * 在涉及网络请求的命令执行前调用，便于连接失败时定位。
+   * 输出到 stderr 不污染 JSON stdout。
+   * @param {PackageManager} manager
+   * @param {string} [proxy]
+   * @private
+   */
+  async _printEndpoint(manager, proxy) {
+    try {
+      const { registry } = await manager.getRegistry()
+      if (registry) {
+        console.error(`[opm] registry: ${registry}`)
+      }
+    } catch {}
+    if (proxy) {
+      console.error(`[opm] proxy: ${proxy}`)
+    }
+  }
+
   async _dispatch(manager, action, parsed, opts) {
     const { positional } = parsed
 
@@ -152,6 +171,7 @@ export class PackageGroup {
           console.error(`Usage: opm ${this.name} search <name> [version]`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.searchPackage(name, version, { proxy: opts.proxy })
         output(result)
         break
@@ -174,6 +194,7 @@ export class PackageGroup {
           console.error(`Usage: opm ${this.name} info <name>`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.packageInfo(name, { proxy: opts.proxy })
         output(result)
         break
@@ -185,17 +206,12 @@ export class PackageGroup {
           console.error(`Usage: opm ${this.name} versions <name>`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.packageVersions(name, { proxy: opts.proxy })
         output(result)
         break
       }
 
-      case 'outdated': {
-        const result = await manager.listOutdated({ global: !!opts.global, proxy: opts.proxy })
-        output(result)
-        break
-      }
-
       case 'install': {
         const name = positional[0]
         const version = positional[1]
@@ -203,6 +219,7 @@ export class PackageGroup {
           console.error(`Usage: opm ${this.name} install <name> [version]`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.install(name, version, { global: !!opts.global, proxy: opts.proxy })
         output(result)
         break
@@ -225,6 +242,7 @@ export class PackageGroup {
           console.error(`Usage: opm ${this.name} upgrade <name>`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.upgrade(name, { global: !!opts.global, proxy: opts.proxy })
         output(result)
         break
@@ -266,7 +284,6 @@ Actions:
   view <name>                Show package in global and project scopes
   info <name>                Show package details
   versions <name>            List all available versions
-  outdated [-g]               List outdated packages
   install <name> [version]   Install a package
   uninstall <name>           Uninstall a package
   upgrade <name>             Upgrade a package to latest
@@ -276,7 +293,7 @@ Actions:
 
 Options:
   -g, --global    Global operation (npm: global node_modules; pip: system Python)
-  -p, --proxy <url>  Proxy address (search/info/versions/outdated/install/upgrade);
+  -p, --proxy <url>  Proxy address (search/info/versions/install/upgrade);
                   overrides config proxy.active when provided
   -h, --help      Show this help
 
@@ -287,7 +304,6 @@ Examples:
   opm ${this.name} view <name>
   opm ${this.name} info <name>
   opm ${this.name} versions <name>
-  opm ${this.name} outdated
   opm ${this.name} install <name>
   opm ${this.name} uninstall <name>
   opm ${this.name} upgrade <name>
@@ -438,12 +454,14 @@ export class RuntimeGroup extends PackageGroup {
           console.error(`Usage: opm ${this.name} install <version>`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.install(this.name, version, { proxy: opts.proxy })
         output(result)
         break
       }
 
       case 'upgrade': {
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.upgrade(this.name, { proxy: opts.proxy })
         output(result)
         break
@@ -455,12 +473,14 @@ export class RuntimeGroup extends PackageGroup {
           console.error(`Usage: opm ${this.name} search <version>`)
           process.exit(1)
         }
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.searchPackage(this.name, version, { proxy: opts.proxy })
         output(result)
         break
       }
 
       case 'versions': {
+        await this._printEndpoint(manager, opts.proxy)
         const result = await manager.packageVersions(this.name, { proxy: opts.proxy })
         output(result)
         break