@wwkit/opm 1.0.8 → 1.0.9

package/src/cli/groups/overlay.js

@@ -0,0 +1,169 @@
+/**
+ * overlay 命令组 — 将本地开发源码覆盖到全局 npm 安装位置
+ *
+ * 用途：跳过发布流程，把最近修改的代码放到实际包安装位置用于实际测试。
+ *
+ *   opm overlay                         覆盖 cwd 包到全局安装
+ *   opm overlay -f /path/to/pkg         指定源目录
+ *   opm overlay -t /custom/node_modules 指定目标目录
+ *   opm overlay --dry-run               预览将要复制的文件
+ *
+ * 逻辑：
+ * 1. 读取源目录 package.json 获取包名
+ * 2. 默认目标 = npm root -g，拼接 <globalRoot>/<pkgName>
+ * 3. 排除 node_modules/.git 等，逐文件复制（保留权限）
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execSync } from 'node:child_process'
+import { parseFlags } from '../helpers/args.js'
+import { output } from '../../formatter.js'
+
+const EXCLUDE = new Set(['node_modules', '.git', '.DS_Store', 'Thumbs.db'])
+
+export class OverlayGroup {
+  constructor() {
+    this.name = 'overlay'
+    this.desc = 'Overlay local package source onto global npm install (bypass publish)'
+  }
+
+  async run(argv) {
+    const parsed = parseFlags(argv)
+
+    if (parsed.flags.help === 'true' || parsed.flags.h === 'true' || parsed.positional[0] === 'help') {
+      this.printHelp()
+      return
+    }
+
+    const dryRun = parsed.flags['dry-run'] === 'true'
+
+    const from = path.resolve(parsed.flags.f || parsed.flags.from || process.cwd())
+    if (!fs.existsSync(from) || !fs.statSync(from).isDirectory()) {
+      output({ error: 'Source directory does not exist or is not a directory', from })
+      process.exit(1)
+    }
+    const srcPkgPath = path.join(from, 'package.json')
+    if (!fs.existsSync(srcPkgPath)) {
+      output({ error: 'No package.json in source directory root (not an npm project)', from, hint: 'Use -f/--to to specify a directory containing package.json' })
+      process.exit(1)
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(srcPkgPath, 'utf8'))
+    const pkgName = pkg.name
+    if (!pkgName) {
+      output({ error: 'package.json has no name field', from })
+      process.exit(1)
+    }
+
+    const to = parsed.flags.t || parsed.flags.to
+    let globalRoot
+    if (to) {
+      globalRoot = path.resolve(to)
+      if (path.basename(globalRoot) !== 'node_modules') {
+        output({ error: 'Target directory must end with "node_modules"', to: globalRoot, hint: 'Example: /usr/local/lib/node_modules' })
+        process.exit(1)
+      }
+      if (!fs.existsSync(globalRoot) || !fs.statSync(globalRoot).isDirectory()) {
+        output({ error: 'Target node_modules directory does not exist', to: globalRoot })
+        process.exit(1)
+      }
+    } else {
+      try {
+        globalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+      } catch {
+        output({ error: 'Failed to determine npm global root', hint: 'Use -t/--to to specify target directory' })
+        process.exit(1)
+      }
+    }
+
+    const targetDir = path.join(globalRoot, pkgName)
+    if (!fs.existsSync(targetDir)) {
+      output({
+        error: 'Target package not found in global install',
+        package: pkgName,
+        target: targetDir,
+        hint: `Install first: npm install -g ${pkgName}`,
+      })
+      process.exit(1)
+    }
+
+    const files = this._collectFiles(from)
+
+    if (dryRun) {
+      output({
+        package: pkgName,
+        from,
+        to: targetDir,
+        dryRun: true,
+        fileCount: files.length,
+        files: files.map((f) => path.relative(from, f)),
+      })
+      return
+    }
+
+    let copied = 0
+    for (const srcPath of files) {
+      const rel = path.relative(from, srcPath)
+      const destPath = path.join(targetDir, rel)
+      fs.mkdirSync(path.dirname(destPath), { recursive: true })
+      const stat = fs.statSync(srcPath)
+      fs.copyFileSync(srcPath, destPath)
+      fs.chmodSync(destPath, stat.mode)
+      copied++
+    }
+
+    output({
+      package: pkgName,
+      from,
+      to: targetDir,
+      fileCount: copied,
+    })
+  }
+
+  /**
+   * 递归收集源目录下所有文件（排除 EXCLUDE 集合）
+   * @param {string} dir
+   * @returns {string[]}
+   * @private
+   */
+  _collectFiles(dir) {
+    const result = []
+    const walk = (d) => {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        if (EXCLUDE.has(entry.name)) continue
+        const full = path.join(d, entry.name)
+        if (entry.isDirectory()) {
+          walk(full)
+        } else {
+          result.push(full)
+        }
+      }
+    }
+    walk(dir)
+    return result
+  }
+
+  printHelp() {
+    console.log(`
+Usage: opm overlay [options]
+
+Overlay local package source onto the global npm install location.
+Copies all files (except node_modules/.git) from source to target,
+overwriting existing files. Useful for testing local changes without
+publishing.
+
+Options:
+  -f, --from <dir>    Source package directory (default: current directory)
+  -t, --to <dir>      Target node_modules directory (default: npm root -g)
+  --dry-run           Preview files to copy without writing
+  -h, --help          Show this help
+
+Examples:
+  opm overlay                            Overlay cwd package to global install
+  opm overlay -f /path/to/package         Overlay specific package
+  opm overlay -t /custom/node_modules     Overlay to custom target
+  opm overlay --dry-run                   Preview what would be copied
+`)
+  }
+}

package/src/cli/groups/package.js

@@ -50,14 +50,13 @@ const MANAGER_DESC = {
 }
 
 const ACTIONS = {
-  version:    { desc: 'Show manager version' },
+  version:    { desc: 'Show manager or package version' },
   installed:  { desc: 'Check if the manager itself is installed' },
   registry:   { desc: 'Query or set registry/mirror address' },
   search:     { desc: 'Check if a package is available in the source' },
-  view:       { desc: 'Check if a package is already installed' },
+  view:       { desc: 'Check package in global and project scopes' },
   info:       { desc: 'Show package details' },
   versions:   { desc: 'List all available versions of a package' },
-  list:       { desc: 'List all installed packages' },
   outdated:   { desc: 'List outdated packages' },
   install:    { desc: 'Install a package' },
   uninstall:  { desc: 'Uninstall a package' },
@@ -105,8 +104,18 @@ export class PackageGroup {
 
     switch (action) {
       case 'version': {
-        const result = await manager.getVersion()
-        output((result.version || '').replace(/^v/, ''))
+        const name = positional[0]
+        if (name) {
+          const result = await manager.scopedInstalled(name, { proxy: opts.proxy })
+          output({
+            name: result.name,
+            global: { installed: result.global.installed, ...(result.global.version ? { version: result.global.version } : {}) },
+            project: { installed: result.project.installed, ...(result.project.version ? { version: result.project.version } : {}) },
+          })
+        } else {
+          const result = await manager.getVersion()
+          output((result.version || '').replace(/^v/, ''))
+        }
         break
       }
 
@@ -151,10 +160,10 @@ export class PackageGroup {
       case 'view': {
         const name = positional[0]
         if (!name) {
-          console.error(`Usage: opm ${this.name} view <name> [-g]`)
+          console.error(`Usage: opm ${this.name} view <name>`)
           process.exit(1)
         }
-        const result = await manager.isInstalled(name, { global: !!opts.global })
+        const result = await manager.scopedInstalled(name, { proxy: opts.proxy })
         output(result)
         break
       }
@@ -181,12 +190,6 @@ export class PackageGroup {
         break
       }
 
-      case 'list': {
-        const result = await manager.listInstalled({ global: !!opts.global })
-        output(result)
-        break
-      }
-
       case 'outdated': {
         const result = await manager.listOutdated({ global: !!opts.global, proxy: opts.proxy })
         output(result)
@@ -254,16 +257,15 @@ export class PackageGroup {
 Usage: opm ${this.name} <action> [args] [options]
 
 Actions:
-  version                   Show ${this.name} version
+  version [name]             Show manager version, or package version in global+project scopes
   installed                 Check if ${this.name} itself is installed
   registry                   Show active registry (from opm config)
   registry set <url|preset>  Set active registry (writes opm config)
   registry presets           List available mirror presets
   search <name> [version]    Check package availability in source
-  view <name> [-g]           Check if package is installed (local or global)
+  view <name>                Show package in global and project scopes
   info <name>                Show package details
   versions <name>            List all available versions
-  list [-g]                   List all installed packages
   outdated [-g]               List outdated packages
   install <name> [version]   Install a package
   uninstall <name>           Uninstall a package
@@ -285,7 +287,6 @@ Examples:
   opm ${this.name} view <name>
   opm ${this.name} info <name>
   opm ${this.name} versions <name>
-  opm ${this.name} list
   opm ${this.name} outdated
   opm ${this.name} install <name>
   opm ${this.name} uninstall <name>
@@ -363,7 +364,7 @@ export class RuntimeGroup extends PackageGroup {
       return
     }
 
-    const runtimeActions = new Set(['use', 'current', 'default', 'installed', 'dir', 'install', 'upgrade', 'search', 'versions'])
+    const runtimeActions = new Set(['use', 'current', 'default', 'installed', 'dir', 'install', 'upgrade', 'search', 'versions', 'version', 'view', 'list'])
     if (runtimeActions.has(action)) {
       const manager = MANAGERS[this.name]()
       const parsed = parseFlags(rest)
@@ -465,6 +466,29 @@ export class RuntimeGroup extends PackageGroup {
         break
       }
 
+      case 'version': {
+        const result = await manager.getVersion()
+        output((result.version || '').replace(/^v/, ''))
+        break
+      }
+
+      case 'view': {
+        const version = positional[0]
+        if (!version) {
+          console.error(`Usage: opm ${this.name} view <version>`)
+          process.exit(1)
+        }
+        const result = await manager.isInstalled(version, { global: false })
+        output(result)
+        break
+      }
+
+      case 'list': {
+        const result = await manager.listInstalled({ global: false })
+        output(result)
+        break
+      }
+
       default:
         return super._dispatch(manager, action, parsed, opts)
     }

package/src/cli/index.js

@@ -20,6 +20,7 @@ import { DockerGroup } from './groups/docker.js'
 import { EnsureGroup } from './groups/ensure.js'
 import { PingGroup } from './groups/ping.js'
 import { ProcGroup } from './groups/proc.js'
+import { OverlayGroup } from './groups/overlay.js'
 import { FtpGroup } from '../tools/ftp/index.js'
 import { GitGroup } from '../tools/git/index.js'
 import { ShareGroup } from '../tools/share/index.js'
@@ -62,6 +63,7 @@ const GROUPS = {
   ensure: new EnsureGroup(),
   ping: new PingGroup(),
   proc: new ProcGroup(),
+  overlay: new OverlayGroup(),
 }
 
 class CLI {

package/src/config.json5

@@ -227,6 +227,7 @@
     env: {
       OPENCODE_CONFIG_DIR: "{pkg:@wwkit/harness}",
       OPENCODE_CONFIG_CONTENT: "",
+      OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS: "true",
     },
   },
 

package/src/harnesses/opencode/index.js

@@ -21,7 +21,7 @@ const shell = new Shell()
 /**
  * opencode 专属环境变量名
  */
-const ENV_VARS = ['OPENCODE_CONFIG_DIR', 'OPENCODE_CONFIG_CONTENT']
+const ENV_VARS = ['OPENCODE_CONFIG_DIR', 'OPENCODE_CONFIG_CONTENT', 'OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS']
 
 /**
  * 查找 opencode 配置文件路径（优先 .jsonc，其次 .json）

package/src/index.js

@@ -21,6 +21,7 @@ export { WslGroup } from './cli/groups/wsl.js'
 export { DockerGroup } from './cli/groups/docker.js'
 export { PingGroup } from './cli/groups/ping.js'
 export { ProcGroup } from './cli/groups/proc.js'
+export { OverlayGroup } from './cli/groups/overlay.js'
 export { FtpGroup } from './tools/ftp/index.js'
 export { GitGroup } from './tools/git/index.js'
 export { ShareGroup } from './tools/share/index.js'

package/src/managers/apt.js

@@ -249,6 +249,9 @@ export class AptManager extends PackageManager {
   }
 
   async isInstalled(name, opts = {}) {
+    if (opts.global === false) {
+      return { name, installed: false, hint: 'no project scope (system-level manager)' }
+    }
     const args = ['query', '-W', '-f=${Status} ${Version}', name]
     const out = this._exec(args, { allowNonZero: true })
     const m = out.trim().match(/^install ok installed\s+(\S+)$/)
@@ -323,18 +326,6 @@ export class AptManager extends PackageManager {
     return { name, versions, registry }
   }
 
-  async listInstalled(opts = {}) {
-    const out = this._exec(['list', '--installed'], { allowNonZero: true })
-    const items = []
-    for (const line of this._parseLines(out)) {
-      const m = line.match(/^(\S+?)\/(?:\S+,)?now\s+(\S+)\s+(\S+)\s+\[/)
-      if (m) {
-        items.push({ name: m[1], version: m[2] })
-      }
-    }
-    return items
-  }
-
   async listOutdated(opts = {}) {
     const out = this._exec(['list', '--upgradable', ...this._proxyArgs(opts.proxy)], { allowNonZero: true })
     const items = []

package/src/managers/base.js

@@ -81,13 +81,27 @@ export class PackageManager {
   /**
    * 查询包是否已安装
    * @param {string} name - 包名
-   * @param {{ global?: boolean }} [opts] - 选项
-   * @returns {Promise<InstalledResult>}
+   * @param {{ global?: boolean }} [opts] - 选项；global: true = 全局/系统作用域，false/缺省 = 项目/当前作用域
+   * @returns {Promise<InstalledResult>} - name/installed/version?/path?；单作用域管理器对不支持的作用域返回 { name, installed: false, hint }
    */
   async isInstalled(name, opts) {
     throw new Error(`${this.name}: isInstalled not implemented`)
   }
 
+  /**
+   * 查询包在全局与项目双作用域的安装状态
+   * @param {string} name - 包名
+   * @param {{ proxy?: string }} [opts] - 选项
+   * @returns {Promise<{ name: string, global: InstalledResult, project: InstalledResult }>}
+   */
+  async scopedInstalled(name, opts = {}) {
+    const [global, project] = await Promise.all([
+      this.isInstalled(name, { ...opts, global: true }),
+      this.isInstalled(name, { ...opts, global: false }),
+    ])
+    return { name, global, project }
+  }
+
   /**
    * 查询包详情
    * @param {string} name - 包名
@@ -110,6 +124,7 @@ export class PackageManager {
 
   /**
    * 列出所有已安装包
+   * // 仅运行时管理器（node/php/python）实现；包管理器不再实现此方法
    * @param {{ global?: boolean }} [opts] - 选项
    * @returns {Promise<InstalledItem[]>}
    */

package/src/managers/brew.js

@@ -299,6 +299,9 @@ export class BrewManager extends PackageManager {
   }
 
   async isInstalled(name, opts = {}) {
+    if (opts.global === false) {
+      return { name, installed: false, hint: 'no project scope (system-level manager)' }
+    }
     const out = this._exec(['list', '--versions', name], { allowNonZero: true })
     const items = this._parseListVersions(out)
     const hit = items.find((i) => i.name === name)
@@ -337,11 +340,6 @@ export class BrewManager extends PackageManager {
     return { name, versions, registry }
   }
 
-  async listInstalled(opts = {}) {
-    const out = this._exec(['list', '--versions'], { allowNonZero: true })
-    return this._parseListVersions(out)
-  }
-
   async listOutdated(opts = {}) {
     const out = this._exec(['outdated', '--json=v2'], { allowNonZero: true, proxy: opts.proxy })
     return this._parseOutdatedJson(out)

package/src/managers/bun.js

@@ -269,24 +269,6 @@ export class BunManager extends PackageManager {
     return { name, versions, registry }
   }
 
-  async listInstalled(opts = {}) {
-    const args = ['pm', 'ls']
-    if (opts.global) args.push('-g')
-    try {
-      const out = this._exec(args, { allowNonZero: true })
-      const items = []
-      for (const line of out.split('\n')) {
-        const m = line.match(/([^\s]+)@([\d.]+)/)
-        if (m) {
-          items.push({ name: m[1], version: m[2], ...(opts.global ? { global: true } : {}) })
-        }
-      }
-      return items
-    } catch {
-      return []
-    }
-  }
-
   async listOutdated(opts = {}) {
     const args = ['outdated']
     if (opts.global) args.push('-g')

package/src/managers/composer.js

@@ -11,6 +11,7 @@
 
 import { execSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { PackageManager } from './base.js'
 import { fetchText } from './http.js'
@@ -197,7 +198,71 @@ export class ComposerManager extends PackageManager {
     }
   }
 
+  /**
+   * 获取 composer 全局 home 目录
+   *
+   * 优先级：$COMPOSER_HOME → ~/.config/composer → ~/.composer（旧版）
+   * @returns {string}
+   * @private
+   */
+  _getComposerHome() {
+    if (process.env.COMPOSER_HOME) return process.env.COMPOSER_HOME
+    const xdg = path.join(os.homedir(), '.config', 'composer')
+    if (fs.existsSync(xdg)) return xdg
+    return path.join(os.homedir(), '.composer')
+  }
+
+  /**
+   * 读取 composer 全局 installed.json
+   * @returns {object[]|null}
+   * @private
+   */
+  _readGlobalInstalledJson() {
+    const home = this._getComposerHome()
+    const p = path.join(home, 'vendor', 'composer', 'installed.json')
+    if (!fs.existsSync(p)) return null
+    try {
+      const data = JSON.parse(fs.readFileSync(p, 'utf8'))
+      return Array.isArray(data.packages) ? data.packages : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 通过 PATH 查找 bin 路径（Linux: which / Windows: where）
+   * @param {string} name - bin 名
+   * @returns {string|null} bin 路径或 null
+   * @private
+   */
+  _whichBin(name) {
+    const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`
+    try {
+      const out = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+      const lines = out.trim().split(/\r?\n/).filter(Boolean)
+      return lines[0] || null
+    } catch {
+      return null
+    }
+  }
+
   async isInstalled(name, opts = {}) {
+    if (opts.global === true) {
+      const packages = this._readGlobalInstalledJson()
+      if (packages) {
+        const pkg = packages.find((p) => p.name === name)
+        if (pkg) {
+          return { name, installed: true, version: pkg.version || 'unknown', global: true }
+        }
+      }
+
+      const binPath = this._whichBin(name)
+      if (binPath) {
+        return { name, installed: true, global: true, path: binPath }
+      }
+
+      return { name, installed: false, global: true }
+    }
     const packages = this._readInstalledJson()
     if (packages) {
       const pkg = packages.find((p) => p.name === name)
@@ -233,15 +298,6 @@ export class ComposerManager extends PackageManager {
     return { name, versions, registry }
   }
 
-  async listInstalled(opts = {}) {
-    const packages = this._readInstalledJson()
-    if (!packages) return []
-    return packages.map((p) => ({
-      name: p.name,
-      version: p.version || 'unknown',
-    }))
-  }
-
   async listOutdated(opts = {}) {
     const out = this._exec(['outdated', '--format=json'], { allowNonZero: true, proxy: opts.proxy })
     try {

package/src/managers/dnf.js

@@ -240,6 +240,9 @@ export class DnfManager extends PackageManager {
   }
 
   async isInstalled(name, opts = {}) {
+    if (opts.global === false) {
+      return { name, installed: false, hint: 'no project scope (system-level manager)' }
+    }
     const args = ['repoquery', '--installed', '--qf', '%{VERSION}-%{RELEASE}', name]
     const out = this._exec(args, { allowNonZero: true })
     const versions = this._parseLines(out)
@@ -316,18 +319,6 @@ export class DnfManager extends PackageManager {
     return { name, versions, registry }
   }
 
-  async listInstalled(opts = {}) {
-    const out = this._exec(['repoquery', '--installed', '--qf', '%{NAME} %{VERSION}-%{RELEASE}'], { allowNonZero: true })
-    const items = []
-    for (const line of this._parseLines(out)) {
-      const parts = line.split(/\s+/)
-      if (parts.length >= 2) {
-        items.push({ name: parts[0], version: parts[1] })
-      }
-    }
-    return items
-  }
-
   async listOutdated(opts = {}) {
     const args = ['list', '--upgrades', ...this._proxyArgs(opts.proxy)]
     const out = this._exec(args, { allowNonZero: true })