@wwkit/opm 1.0.9 → 1.0.11

package/src/harnesses/base.js

@@ -2,7 +2,12 @@
  * AI harness 统一命令组基类
  *
  * 各 harness（opencode / claude / …）共享同一套命令：
- *   version / installed / install / uninstall / upgrade / config / clear / dir
+ *   version / installed / install / uninstall / upgrade / config / clear / dir / env
+ * 内容型 harness（harness/@wwkit/harness 插件）额外提供：
+ *   list（列出 skills/agents/commands） / status（安装 + env 健康检查）
+ *
+ * 支持的动作按 cfg 能力动态裁剪（_supportedActions）：只有 cfg 提供了对应的
+ * 实现（list/status/clear/getConfigFile/getEnvVars）时才出现在帮助与路由中。
  *
  * install/uninstall/upgrade 委托 NpmManager（global），自动使用 opm 配置的
  * npm registry 镜像与 proxy，而非裸 npm。
@@ -25,7 +30,9 @@ const ACTIONS = {
   upgrade:    { desc: 'Upgrade to latest via npm -g (uses opm npm registry + proxy)' },
   config:     { desc: 'Show config file content' },
   clear:      { desc: 'Clear sessions / data' },
-  dir:        { desc: 'Show data / db / log / config paths' },
+  dir:        { desc: 'Show install / data / db / log / config paths' },
+  list:       { desc: 'List installed content (skills/agents/commands)' },
+  status:     { desc: 'Show install status + environment health' },
   env:        { desc: 'Show harness environment variables' },
   help:       { desc: 'Show this help' },
 }
@@ -35,12 +42,15 @@ const ACTIONS = {
  * @property {string} name - harness 名（命令名）
  * @property {string} desc - 描述
  * @property {string} npmPackage - npm 全局包名
- * @property {() => string|null} getConfigFile - 配置文件路径
- * @property {() => string} getDataDir - 数据目录
- * @property {() => string} getDbPath - DB 路径
- * @property {() => string} getLogPath - 日志路径
- * @property {(argv: string[]) => Promise<void>} clear - 清理实现
+ * @property {() => string|null} [getConfigFile] - 配置文件路径
+ * @property {() => string} [getDataDir] - 数据目录
+ * @property {() => string} [getDbPath] - DB 路径
+ * @property {() => string} [getLogPath] - 日志路径
+ * @property {(argv: string[]) => Promise<void>} [clear] - 清理实现
  * @property {string[][]} [clearOptions] - clear 子选项帮助 [flag, desc]
+ * @property {() => Promise<Object>} [list] - 列出包内容（skills/agents/commands）
+ * @property {() => Promise<Object>} [status] - 安装/环境健康检查
+ * @property {() => Promise<Object>} [dirInfo] - 自定义 dir 输出（覆盖默认 npm install 路径）
  */
 
 export class HarnessGroup {
@@ -62,9 +72,19 @@ export class HarnessGroup {
     }
 
     if (!action || !ACTIONS[action]) {
+      if (!this.cfg.open) {
+        this.printHelp()
+        return
+      }
       return this._open(argv)
     }
 
+    if (!this._supportedActions().includes(action)) {
+      console.error(`Action "${action}" is not supported for ${this.cfg.name}`)
+      this.printHelp()
+      process.exit(1)
+    }
+
     switch (action) {
       case 'version':
         return this._version()
@@ -82,6 +102,10 @@ export class HarnessGroup {
         return this._clear(rest)
       case 'dir':
         return this._dir()
+      case 'list':
+        return this._list()
+      case 'status':
+        return this._status()
       case 'env':
         return this._env()
       default:
@@ -91,6 +115,23 @@ export class HarnessGroup {
     }
   }
 
+  /**
+   * 本 harness 支持的动作列表（按 cfg 能力动态裁剪）
+   * @returns {string[]}
+   * @private
+   */
+  _supportedActions() {
+    return Object.keys(ACTIONS).filter((sig) => {
+      if (sig === 'help') return true
+      if (sig === 'list') return Boolean(this.cfg.list)
+      if (sig === 'status') return Boolean(this.cfg.status)
+      if (sig === 'clear') return Boolean(this.cfg.clear)
+      if (sig === 'config') return Boolean(this.cfg.getConfigFile)
+      if (sig === 'env') return Boolean(this.cfg.getEnvVars)
+      return true
+    })
+  }
+
   /**
    * 解析 proxy（-p/--proxy 优先，否则回退配置 active proxy）
    * @param {string[]} argv
@@ -152,6 +193,22 @@ export class HarnessGroup {
     output({ file, content })
   }
 
+  async _list() {
+    if (!this.cfg.list) {
+      output({ name: this.cfg.name, error: 'list not supported for this harness' })
+      return
+    }
+    output(await this.cfg.list())
+  }
+
+  async _status() {
+    if (!this.cfg.status) {
+      output({ name: this.cfg.name, error: 'status not supported for this harness' })
+      return
+    }
+    output(await this.cfg.status())
+  }
+
   async _clear(rest) {
     const parsed = parseFlags(rest)
     if (parsed.flags.help === 'true') {
@@ -162,6 +219,10 @@ export class HarnessGroup {
   }
 
   async _dir() {
+    if (this.cfg.dirInfo) {
+      output(await this.cfg.dirInfo())
+      return
+    }
     const npm = new NpmManager()
     const npmResult = await npm.isInstalled(this.cfg.npmPackage, { global: true })
     const configFile = this.cfg.getConfigFile()
@@ -218,18 +279,34 @@ export class HarnessGroup {
   }
 
   printHelp() {
-    const actionLines = Object.entries(ACTIONS)
-      .map(([sig, { desc }]) => `  ${sig.padEnd(12)} ${desc}`)
+    const actionLines = this._supportedActions()
+      .map((sig) => `  ${sig.padEnd(12)} ${ACTIONS[sig].desc}`)
       .join('\n')
 
     let clearSection = ''
-    if (this.cfg.clearOptions && this.cfg.clearOptions.length > 0) {
+    if (this._supportedActions().includes('clear') && this.cfg.clearOptions && this.cfg.clearOptions.length > 0) {
       const optLines = this.cfg.clearOptions
         .map(([flag, desc]) => `  ${flag.padEnd(20)} ${desc}`)
         .join('\n')
       clearSection = `\nClear options:\n${optLines}\n`
     }
 
+    const supported = this._supportedActions()
+    const examples = [
+      '  opm ' + this.cfg.name + ' version',
+      '  opm ' + this.cfg.name + ' install',
+      '  opm ' + this.cfg.name + ' upgrade',
+      ...(supported.includes('list') ? [`  opm ${this.cfg.name} list`] : []),
+      ...(supported.includes('status') ? [`  opm ${this.cfg.name} status`] : []),
+      ...(supported.includes('env') ? [`  opm ${this.cfg.name} env`] : []),
+      ...(supported.includes('dir') ? [`  opm ${this.cfg.name} dir`] : []),
+    ]
+    if (this.cfg.open) {
+      examples.push(`  opm ${this.cfg.name}                           Launch TUI in current directory`)
+      examples.push(`  opm ${this.cfg.name} -d /path/to/project`)
+      examples.push(`  opm ${this.cfg.name} -c config --agent work    Pass through args to opencode`)
+    }
+
     console.log(`
 Usage: opm ${this.cfg.name} <action> [options]
 
@@ -242,16 +319,7 @@ Options:
   -h, --help          Show this help
 
 Examples:
-  opm ${this.cfg.name} version
-  opm ${this.cfg.name} install
-  opm ${this.cfg.name} upgrade
-  opm ${this.cfg.name} config
-  opm ${this.cfg.name} clear
-  opm ${this.cfg.name} dir
-  opm ${this.cfg.name} env
-  opm ${this.cfg.name}                           Launch TUI in current directory
-  opm ${this.cfg.name} -d /path/to/project
-  opm ${this.cfg.name} -c config --agent work    Pass through args to opencode
+${examples.join('\n')}
 `)
   }
 }

package/src/harnesses/harness/index.js

@@ -0,0 +1,132 @@
+/**
+ * @wwkit/harness harness 配置
+ *
+ * @wwkit/harness 是 opencode 插件包（skills/agents/commands/scripts），
+ * 通过 npm 全局安装；postinstall 设置 OPENCODE_CONFIG_DIR 指向包根目录，
+ * 使 opencode 自动加载其 skills/agents/commands。
+ *
+ * 与 opencode（AI agent CLI）不同：无独立配置文件、无 DB/日志/会话，
+ * 因此不支持 config/clear；而提供 list（列出包内容）与 status（健康检查）。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { NpmManager } from '../../managers/npm.js'
+
+const CONTENT_DIRS = ['skills', 'agents', 'commands']
+const ENV_VARS = ['OPENCODE_CONFIG_DIR', 'OPENCODE_EXPERIMENTAL_LSP_TOOL']
+const NAME = 'harness'
+const NPM_PACKAGE = '@wwkit/harness'
+
+/**
+ * 已安装的 @wwkit/harness 全局包信息
+ * @returns {Promise<{ installed: boolean, version?: string, path?: string }>}
+ * @private
+ */
+async function getInstalled() {
+  const npm = new NpmManager()
+  return npm.isInstalled(NPM_PACKAGE, { global: true })
+}
+
+/**
+ * 读取 env 变量当前值
+ * @returns {Record<string, string>}
+ */
+export function getEnvVars() {
+  const result = {}
+  for (const key of ENV_VARS) {
+    result[key] = process.env[key] || ''
+  }
+  return result
+}
+
+/**
+ * 列出包根目录下 skills/agents/commands 内容
+ * @param {string} root - 已安装包根目录
+ * @returns {Record<string, string[]>}
+ */
+export function readContentDirs(root) {
+  const result = {}
+  for (const dir of CONTENT_DIRS) {
+    const full = path.join(root, dir)
+    result[dir] = fs.existsSync(full) ? fs.readdirSync(full).sort() : []
+  }
+  return result
+}
+
+/**
+ * list：列出安装包提供的 skills/agents/commands
+ * @returns {Promise<Object>}
+ */
+async function list() {
+  const installed = await getInstalled()
+  if (!installed.installed || !installed.path) {
+    return { name: NAME, installed: false, hint: `Run \`opm ${NAME} install\` to install ${NPM_PACKAGE}` }
+  }
+  const content = readContentDirs(installed.path)
+  const counts = {}
+  for (const dir of CONTENT_DIRS) counts[dir] = content[dir].length
+  return { name: NAME, installed: true, version: installed.version, install: installed.path, counts, ...content }
+}
+
+/**
+ * status：健康检查（安装 + env + 内容目录完整性）
+ * @returns {Promise<Object>}
+ */
+async function status() {
+  const installed = await getInstalled()
+  const env = getEnvVars()
+  if (!installed.installed || !installed.path) {
+    return {
+      name: NAME,
+      installed: false,
+      ok: false,
+      env,
+      hint: `Run \`opm ${NAME} install\` to install ${NPM_PACKAGE}`,
+    }
+  }
+  const content = readContentDirs(installed.path)
+  const contentOk = {}
+  for (const dir of CONTENT_DIRS) contentOk[dir] = content[dir].length > 0
+  const envDirOk = env.OPENCODE_CONFIG_DIR === installed.path
+  const envLspOk = env.OPENCODE_EXPERIMENTAL_LSP_TOOL === 'true'
+  const ok = envDirOk && envLspOk && Object.values(contentOk).every(Boolean)
+  return {
+    name: NAME,
+    installed: true,
+    version: installed.version,
+    ok,
+    envDirOk,
+    envLspOk,
+    contentDirs: contentOk,
+    env,
+    ...(!ok ? { hint: 'Environment or content is not fully ready, see fields above' } : {}),
+  }
+}
+
+/**
+ * dir：安装路径 + skills/agents/commands 目录
+ * @returns {Promise<Object>}
+ */
+async function dirInfo() {
+  const installed = await getInstalled()
+  if (!installed.installed || !installed.path) {
+    return { name: NAME, install: '', hint: `Run \`opm ${NAME} install\` to install ${NPM_PACKAGE}` }
+  }
+  const paths = { install: installed.path }
+  for (const dir of CONTENT_DIRS) {
+    paths[dir] = path.join(installed.path, dir)
+  }
+  return { name: NAME, ...paths }
+}
+
+export const harnessCfg = {
+  name: NAME,
+  desc: '@wwkit/harness opencode plugin (skills/agents/commands)',
+  npmPackage: NPM_PACKAGE,
+  envVars: ENV_VARS,
+  getEnvVars,
+  list,
+  status,
+  dirInfo,
+}

package/src/harnesses/opencode/index.js

@@ -4,7 +4,7 @@
  * opencode 是 AI coding agent，通过 npm 全局包 opencode-ai 安装（binary: opencode）。
  * 数据目录跨平台（db.js），会话清理复用 clear.js。
  * env 命令管理 OPENCODE_CONFIG_DIR / OPENCODE_CONFIG_CONTENT 环境变量。
- * open 命令在指定工作目录启动 opencode TUI（自动注入 env 变量）。
+ * 裸 `opm opencode`（或带透传 args）在指定工作目录启动 opencode TUI（自动注入 env 变量）。
  */
 
 import fs from 'node:fs'

package/src/index.js

@@ -11,6 +11,7 @@ export { PackageGroup, RuntimeGroup } from './cli/groups/package.js'
 export { ConfigGroup } from './cli/groups/config.js'
 export { HarnessGroup } from './harnesses/base.js'
 export { opencodeHarness } from './harnesses/opencode/index.js'
+export { harnessCfg } from './harnesses/harness/index.js'
 export { BinaryGroup } from './binaries/base.js'
 export { CftGroup } from './binaries/cft/index.js'
 export { NvmGroup } from './cli/groups/nvm.js'

package/src/managers/node.js

@@ -68,6 +68,22 @@ export function installNvm(proxy) {
   }
 }
 
+/**
+ * 解析 nvm ls 输出为已安装版本列表
+ * @param {string} out
+ * @returns {{ name: string, version: string, current: boolean }[]}
+ */
+export function parseNvmInstalled(out) {
+  const items = []
+  for (const line of out.split('\n')) {
+    const m = line.match(/^(->)?\s*v(\d+\.\d+\.\d+)\b/)
+    if (m) {
+      items.push({ name: `v${m[2]}`, version: m[2], current: !!m[1] })
+    }
+  }
+  return items
+}
+
 export class NodeManager extends RuntimeManager {
   constructor() {
     super({
@@ -127,14 +143,7 @@ export class NodeManager extends RuntimeManager {
    * @private
    */
   _parseInstalled(out) {
-    const items = []
-    for (const line of out.split('\n')) {
-      const m = line.match(/^(->)?\s*v(\d+\.\d+\.\d+)\b/)
-      if (m) {
-        items.push({ name: `v${m[2]}`, version: m[2], current: !!m[1] })
-      }
-    }
-    return items
+    return parseNvmInstalled(out)
   }
 
   /**

package/src/managers/php.js

@@ -70,6 +70,22 @@ export function installPhpenv() {
   }
 }
 
+/**
+ * 解析 phpenv versions 输出为已安装版本列表
+ * @param {string} out
+ * @returns {{ name: string, version: string, current: boolean }[]}
+ */
+export function parsePhpenvInstalled(out) {
+  const items = []
+  for (const line of out.split('\n')) {
+    const m = line.match(/^(\*)?\s+(\d+\.\d+\.\d+)\b/)
+    if (m) {
+      items.push({ name: m[2], version: m[2], current: !!m[1] })
+    }
+  }
+  return items
+}
+
 export class PhpManager extends RuntimeManager {
   constructor() {
     super({
@@ -134,14 +150,7 @@ export class PhpManager extends RuntimeManager {
    * @private
    */
   _parseInstalled(out) {
-    const items = []
-    for (const line of out.split('\n')) {
-      const m = line.match(/^(\*)?\s+(\d+\.\d+\.\d+)\b/)
-      if (m) {
-        items.push({ name: m[2], version: m[2], current: !!m[1] })
-      }
-    }
-    return items
+    return parsePhpenvInstalled(out)
   }
 
   /**

package/src/managers/python.js

@@ -67,6 +67,23 @@ export function installUv(proxy) {
   return { action: 'installed', hint: 'Restart shell or ensure ~/.local/bin is in PATH' }
 }
 
+/**
+ * 解析 uv python list --only-installed 输出为已安装版本列表
+ * 输出格式: cpython-3.12.4-linux-x86_64-gnu     /path/to/python
+ * @param {string} out
+ * @returns {{ name: string, version: string, current: boolean }[]}
+ */
+export function parseUvInstalled(out) {
+  const items = []
+  for (const line of out.split('\n')) {
+    const m = line.match(/cpython-(\d+\.\d+\.\d+)/)
+    if (m) {
+      items.push({ name: m[1], version: m[1], current: false })
+    }
+  }
+  return items
+}
+
 export class PythonManager extends RuntimeManager {
   constructor() {
     super({
@@ -129,14 +146,7 @@ export class PythonManager extends RuntimeManager {
    * @private
    */
   _parseInstalled(out) {
-    const items = []
-    for (const line of out.split('\n')) {
-      const m = line.match(/cpython-(\d+\.\d+\.\d+)/)
-      if (m) {
-        items.push({ name: m[1], version: m[1], current: false })
-      }
-    }
-    return items
+    return parseUvInstalled(out)
   }
 
   /**