dsh-plugin-discover 0.0.0-stage → 1.0.0

package/lib/build.js

@@ -0,0 +1,145 @@
+/**
+ * Build one immutable index directory and publish it by switching `current`.
+ * The build downloads only the two public directories, writes records and a
+ * manifest, and never touches the previous published index.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  acquireLock, cleanupOldIndexes, createIndexDir, publishCurrent,
+} from './store.js'
+import { buildRecords, CATALOG_URL, DSH_SO_URL } from './normalize.js'
+import { detectRuntimeVersion } from './compat.js'
+
+const PACKAGE_VERSION = (() => {
+  try {
+    const file = fileURLToPath(new URL('../package.json', import.meta.url))
+    return JSON.parse(readFileSync(file, 'utf8')).version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+})()
+
+async function fetchJson(url, { timeoutMs = 120_000 } = {}) {
+  const response = await fetch(url, {
+    headers: { 'user-agent': `dsh-plugin-discover/${PACKAGE_VERSION}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`)
+  return await response.json()
+}
+
+function validateDshSo(value) {
+  if (!value || typeof value !== 'object' || !Array.isArray(value.plugins)) {
+    throw new Error('dsh.so index has no plugins array')
+  }
+  if (typeof value.generatedAt !== 'string' && typeof value.generated !== 'string') {
+    throw new Error('dsh.so index has no generatedAt')
+  }
+  return value
+}
+
+function validateCatalog(value) {
+  if (!value || typeof value !== 'object' || !Array.isArray(value.plugins)) return null
+  if (value.format !== 1) return null
+  return value
+}
+
+function writeText(path, content) {
+  writeFileSync(path, content, 'utf8')
+}
+
+/**
+ * Build the index.
+ * @param {{ indexDir: string, onProgress?: (message: string) => void, now?: Date }} options
+ */
+export async function buildIndex({ indexDir, onProgress = () => {}, now = new Date() }) {
+  mkdirSync(indexDir, { recursive: true })
+  const lock = acquireLock(indexDir, { now: Date.now() })
+  if (!lock.ok) {
+    return {
+      ok: false,
+      busy: true,
+      lock: lock.lock,
+      message: '另一个建库进程正在运行',
+    }
+  }
+  let created = null
+  try {
+    onProgress('[1/4] 下载 dsh.so 索引…')
+    const dshSo = validateDshSo(await fetchJson(DSH_SO_URL, { timeoutMs: 180_000 }))
+    onProgress(`[2/4] dsh.so ${dshSo.plugins.length} 条；下载 dsh-plugin-catalog…`)
+
+    let catalog = null
+    let catalogError = null
+    try {
+      catalog = validateCatalog(await fetchJson(CATALOG_URL, { timeoutMs: 90_000 }))
+      if (!catalog) catalogError = 'catalog 格式不是 format 1'
+    } catch (error) {
+      catalogError = error instanceof Error ? error.message : String(error)
+    }
+    if (catalogError) onProgress(`[2/4] catalog 不可用，继续用 dsh.so：${catalogError}`)
+
+    onProgress('[3/4] 归一化、去重、合并…')
+    const built = buildRecords(dshSo, catalog)
+    created = createIndexDir(indexDir, now)
+    const recordsFile = join(created.dir, 'records.json')
+    writeText(recordsFile, JSON.stringify(built.records))
+    const generatedAt = built.sources.dshSo.generatedAt
+    const manifest = {
+      format: 1,
+      package: 'dsh-plugin-discover',
+      version: PACKAGE_VERSION,
+      builtAt: new Date().toISOString(),
+      generatedAt,
+      runtimeVersion: detectRuntimeVersion(),
+      sources: built.sources,
+      stats: built.stats,
+      attribution: 'Powered by dsh.so — DSH Developer Hub',
+      license: 'CC-BY-4.0 (index data)',
+      catalogError,
+    }
+    writeText(join(created.dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+    writeText(join(created.dir, 'README.txt'), [
+      'dsh-plugin-discover local index',
+      '',
+      'Index data: dsh.so — DSH Developer Hub (https://www.dsh.so), CC-BY-4.0.',
+      'Catalog data: dsh-plugin-catalog, CC0-1.0.',
+      'Keep the generatedAt timestamp when redistributing the data.',
+      'This directory contains no model weights and no executables.',
+      '',
+    ].join('\n'))
+    onProgress(`[4/4] 写入 ${built.stats.cards} 张卡片，切换 current…`)
+    publishCurrent(indexDir, created.name)
+    const removed = cleanupOldIndexes(indexDir, created.name)
+    onProgress(`完成：${built.stats.cards} 张卡片，数据截至 ${String(generatedAt).slice(0, 10)}`)
+    return {
+      ok: true,
+      dir: created.dir,
+      name: created.name,
+      manifest,
+      stats: built.stats,
+      removed,
+    }
+  } catch (error) {
+    if (created) {
+      try { rmSync(created.dir, { recursive: true, force: true }) } catch {}
+    }
+    throw error
+  } finally {
+    lock.release()
+  }
+}
+
+/** Freshness policy: whether an existing index should be refreshed automatically. */
+export function isStale(manifest, policy = 'daily', now = Date.now()) {
+  if (policy === 'off') return false
+  if (!manifest) return policy !== 'off'
+  const builtAt = Date.parse(manifest.builtAt ?? '')
+  if (!Number.isFinite(builtAt)) return true
+  const age = now - builtAt
+  if (policy === 'manual') return false
+  if (policy === 'weekly') return age > 7 * 86_400_000
+  return age > 86_400_000
+}

package/lib/cli.js

@@ -0,0 +1,495 @@
+#!/usr/bin/env node
+/**
+ * Command line entry for building, inspecting, and querying the local index.
+ * This is a standalone package bin; DSH has no plugin-contributed `dsh`
+ * subcommand, so `dsh plugin add` installs the package and this bin runs
+ * beside it.
+ */
+import { parseArgs } from 'node:util'
+import { createHash } from 'node:crypto'
+import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { defaultIndexDir } from './paths.js'
+import { buildIndex } from './build.js'
+import {
+  isLockStale, readBuildLog, readLock, readManifest, readRecords,
+} from './store.js'
+import { createSearcher, explain, search } from './search.js'
+import { textReport } from './report.js'
+import { PRESETS } from './filters.js'
+import { detectRuntimeVersion } from './compat.js'
+
+const USAGE = `dsh-plugin-discover — local DSH plugin index
+
+Usage:
+  dsh-plugin-discover build   [--index-dir <dir>] [--json] [--quiet]
+  dsh-plugin-discover status  [--index-dir <dir>] [--json]
+  dsh-plugin-discover search  <query> [--alt <text>]... [--limit <n>]
+                              [--preset strict|balanced|loose|off]
+                              [--min-verification <0-5>] [--explain <id>] [--json]
+  dsh-plugin-discover model status [--index-dir <dir>] [--profile <name>] [--json]
+  dsh-plugin-discover model pull   [--spec <spec>] [--profile <name>]
+                                   [--index-dir <dir>] [--dry-run] [--no-verify] [--json]
+
+Options:
+  --index-dir <dir>   Override the index directory. Must match the plugin's indexDir.
+  --alt <text>        A query rewrite; repeat up to three times.
+  --json              Print machine-readable JSON.
+  --quiet             Suppress build progress.
+  --spec <spec>       Model package spec for model pull, such as
+                      link:D:\\path\\to\\model or file:D:\\path\\model.tgz.
+  --profile <name>    DSH profile for model pull (default: DSH_PROFILE or web).
+  --dry-run           Print the model install command without running it.
+  --no-verify         Skip SHA-256 verification of the model package.
+  -h, --help          Show this help.
+
+Default index directory: %LOCALAPPDATA%\\dsh-plugin-discover (Windows),
+~/Library/Caches/dsh-plugin-discover (macOS),
+\${XDG_CACHE_HOME:-~/.cache}/dsh-plugin-discover (Linux).
+
+The optional model package is not downloaded automatically. \`model pull\`
+installs it explicitly; the tool never installs anything.
+`
+
+function resolveIndexDir(value) {
+  const configured = typeof value === 'string' && value.trim() !== ''
+    ? value.trim()
+    : (process.env.DSH_PLUGIN_DISCOVER_INDEX_DIR || defaultIndexDir())
+  return configured
+}
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return '?'
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`
+  return `${(bytes / 1024 / 1024).toFixed(1)} MiB`
+}
+
+function printStatus(indexDir, json) {
+  const current = readManifest(indexDir)
+  const lock = readLock(indexDir)
+  const activeLock = lock && !isLockStale(lock) ? lock : null
+  const recordsSize = (() => {
+    try { return statSync(join(indexDir, current?.name ?? '', 'records.json')).size } catch { return null }
+  })()
+  const value = {
+    indexDir,
+    hasIndex: current !== null,
+    current: current?.name ?? null,
+    builtAt: current?.manifest?.builtAt ?? null,
+    generatedAt: current?.manifest?.sources?.dshSo?.generatedAt ?? null,
+    cards: current?.manifest?.stats?.cards ?? 0,
+    sources: current?.manifest?.sources ?? null,
+    stats: current?.manifest?.stats ?? null,
+    recordsBytes: recordsSize,
+    building: activeLock !== null,
+    lock: activeLock,
+    lastBuildLog: readBuildLog(indexDir).slice(-2000),
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+    return
+  }
+  const lines = [
+    `索引目录：${indexDir}`,
+    `当前索引：${current?.name ?? '（无）'}`,
+    `卡片数量：${value.cards}`,
+    `数据截至：${value.generatedAt ? String(value.generatedAt).slice(0, 10) : '（未知）'}`,
+    `建库时间：${value.builtAt ?? '（无）'}`,
+    `记录文件：${recordsSize === null ? '（无）' : formatBytes(recordsSize)}`,
+    `来源：${value.sources ? Object.entries(value.sources).filter(([, source]) => source?.ok).map(([name]) => name).join(', ') : '（无）'}`,
+    `建库中：${value.building ? `是（PID ${activeLock?.pid ?? '?'}）` : '否'}`,
+    `DSH 版本：${detectRuntimeVersion() ?? '（未检测到）'}`,
+  ]
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+function printReport(value, current) {
+  const report = textReport(value, { manifest: current?.manifest ?? null })
+  process.stdout.write(`${report}\n`)
+}
+
+function profileDirOf(profile) {
+  const name = profile || process.env.DSH_PROFILE || 'web'
+  if (process.env.DSH_PROFILE_DIR && (!process.env.DSH_PROFILE || process.env.DSH_PROFILE === name)) {
+    return { profile: name, dir: process.env.DSH_PROFILE_DIR }
+  }
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  return { profile: name, dir: join(home, 'profiles', name) }
+}
+
+function resolveInstalledModel(profileDir) {
+  const manifestFile = join(profileDir, 'package.json')
+  if (!existsSync(manifestFile)) return null
+  try {
+    const require = createRequire(manifestFile)
+    const manifestPath = require.resolve('dsh-plugin-discover-model/manifest.json')
+    const packageDir = dirname(manifestPath)
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    const pkg = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'))
+    return { packageDir, version: pkg.version, manifest }
+  } catch {
+    return null
+  }
+}
+
+function readModelPointer(indexDir) {
+  try {
+    const value = JSON.parse(readFileSync(join(indexDir, 'model.json'), 'utf8'))
+    return value && typeof value === 'object' ? value : null
+  } catch {
+    return null
+  }
+}
+
+function runtimeDependency(packageDir, name) {
+  try {
+    const require = createRequire(join(packageDir, 'package.json'))
+    const entry = require.resolve(name)
+    let version = null
+    try {
+      const pkg = JSON.parse(readFileSync(join(dirname(entry), '..', 'package.json'), 'utf8'))
+      version = pkg.version ?? null
+    } catch {}
+    return { installed: true, entry, version }
+  } catch {
+    return { installed: false }
+  }
+}
+
+function modelStatusValue({ profile, profileDir, indexDir }) {
+  const installed = resolveInstalledModel(profileDir)
+  const pointer = readModelPointer(indexDir)
+  const value = {
+    profile,
+    profileDir,
+    indexDir,
+    pointerPath: join(indexDir, 'model.json'),
+    installed: installed !== null,
+    packageDir: installed?.packageDir ?? null,
+    version: installed?.version ?? null,
+    manifest: installed?.manifest ?? null,
+    runtime: installed
+      ? {
+          tokenizer: runtimeDependency(installed.packageDir, '@huggingface/tokenizers'),
+          onnxruntime: runtimeDependency(installed.packageDir, 'onnxruntime-node'),
+        }
+      : null,
+    pointer,
+    pointerMatches: Boolean(
+      installed && pointer && typeof pointer.packageDir === 'string'
+      && pointer.packageDir.toLowerCase() === installed.packageDir.toLowerCase()),
+  }
+  if (installed) {
+    const modelBytes = installed.manifest?.files?.['model_quantized.onnx']?.bytes ?? null
+    const tokenizerBytes = installed.manifest?.files?.['tokenizer.json']?.bytes ?? null
+    value.modelBytes = modelBytes
+    value.tokenizerBytes = tokenizerBytes
+  }
+  return value
+}
+
+function printModelStatus(value, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+    return
+  }
+  const lines = [
+    `模型包：${value.installed ? '已安装' : '未安装'}`,
+    `profile：${value.profile}（${value.profileDir}）`,
+    `索引目录：${value.indexDir}`,
+    `指针文件：${value.pointerPath}${value.pointerMatches ? '（已记录）' : '（未记录或与安装目录不一致）'}`,
+  ]
+  if (value.installed) {
+    lines.push(`包目录：${value.packageDir}`)
+    lines.push(`版本：${value.version}`)
+    lines.push(`模型：${value.modelBytes ? formatBytes(value.modelBytes) : '（manifest 无大小）'}`)
+    lines.push(`tokenizer：${value.tokenizerBytes ? formatBytes(value.tokenizerBytes) : '（manifest 无大小）'}`)
+    lines.push(`tokenizer 运行时：${value.runtime.tokenizer.installed ? '已安装' : '缺失'}`)
+    lines.push(`ONNX 运行时：${value.runtime.onnxruntime.installed ? '已安装' : '缺失'}`)
+    if (value.pointerMatches) lines.push(`安装时间：${value.pointer.installedAt ?? '（未记录）'}`)
+  } else {
+    lines.push('拉取：dsh-plugin-discover model pull --spec <模型包 spec>')
+  }
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
+
+async function sha256File(file) {
+  const hash = createHash('sha256')
+  for await (const chunk of createReadStream(file)) hash.update(chunk)
+  return hash.digest('hex')
+}
+
+async function verifyModelFiles(packageDir, manifest, verifyHashes) {
+  const errors = []
+  const files = manifest?.files && typeof manifest.files === 'object' ? manifest.files : {}
+  for (const [name, expected] of Object.entries(files)) {
+    const file = join(packageDir, name)
+    if (!existsSync(file)) {
+      errors.push(`${name}: missing`)
+      continue
+    }
+    const size = statSync(file).size
+    if (Number.isFinite(expected.bytes) && size !== expected.bytes) {
+      errors.push(`${name}: size ${size} != ${expected.bytes}`)
+    }
+    if (verifyHashes && typeof expected.sha256 === 'string') {
+      const hash = await sha256File(file)
+      if (hash.toLowerCase() !== expected.sha256.toLowerCase()) {
+        errors.push(`${name}: sha256 mismatch`)
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, hashes: verifyHashes, files: Object.keys(files).length }
+}
+
+function installModelPackage(spec, profileDir, dryRun) {
+  if (!/^[^\s;&|<>^"]+$/.test(spec)) {
+    throw new Error('模型包 spec 不能包含空白或 shell 元字符')
+  }
+  if (dryRun) return { dryRun: true, display: `pnpm add ${spec}` }
+  const result = process.platform === 'win32'
+    ? spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', `pnpm add ${spec}`], {
+        cwd: profileDir, stdio: 'inherit', windowsHide: true,
+      })
+    : spawnSync('pnpm', ['add', spec], { cwd: profileDir, stdio: 'inherit' })
+  return {
+    dryRun: false,
+    status: result.status,
+    signal: result.signal,
+    error: result.error ? String(result.error.message ?? result.error) : null,
+  }
+}
+
+function buildModelPointer(packageDir, version, manifest) {
+  return {
+    format: 1,
+    package: 'dsh-plugin-discover-model',
+    version,
+    packageDir,
+    server: join(packageDir, 'server.js'),
+    manifest: join(packageDir, 'manifest.json'),
+    model: join(packageDir, 'model_quantized.onnx'),
+    tokenizer: join(packageDir, 'tokenizer.json'),
+    dimensions: manifest?.dimensions ?? null,
+    maxTokens: manifest?.maxTokens ?? null,
+    installedAt: new Date().toISOString(),
+  }
+}
+
+function writeModelPointer(indexDir, pointer) {
+  mkdirSync(indexDir, { recursive: true })
+  const file = join(indexDir, 'model.json')
+  writeFileSync(file, `${JSON.stringify(pointer, null, 2)}\n`)
+  return file
+}
+
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const command = argv[0]
+  if (!command || command === '-h' || command === '--help' || command === 'help') {
+    process.stdout.write(USAGE)
+    return 0
+  }
+
+  if (command === 'build') {
+    const { values } = parseArgs({
+      args: argv.slice(1),
+      options: {
+        'index-dir': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        quiet: { type: 'boolean', default: false },
+      },
+      allowPositionals: true,
+    })
+    const indexDir = resolveIndexDir(values['index-dir'])
+    const result = await buildIndex({
+      indexDir,
+      onProgress: message => { if (!values.quiet) process.stderr.write(`${message}\n`) },
+    })
+    if (values.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    else if (result.busy) process.stdout.write(`跳过：另一个建库进程正在运行（PID ${result.lock?.pid ?? '?'}）\n`)
+    else {
+      process.stdout.write(`索引已发布：${result.name}\n`)
+      process.stdout.write(`卡片：${result.stats.cards} · 数据截至：${String(result.manifest.sources.dshSo.generatedAt).slice(0, 10)}\n`)
+    }
+    return result.ok || result.busy ? 0 : 1
+  }
+
+  if (command === 'status') {
+    const { values } = parseArgs({
+      args: argv.slice(1),
+      options: {
+        'index-dir': { type: 'string' },
+        json: { type: 'boolean', default: false },
+      },
+      allowPositionals: true,
+    })
+    printStatus(resolveIndexDir(values['index-dir']), values.json)
+    return 0
+  }
+
+  if (command === 'model') {
+    const sub = argv[1]
+    if (sub !== 'status' && sub !== 'pull') {
+      process.stderr.write('usage: dsh-plugin-discover model status|pull [options]\n')
+      return 2
+    }
+    const { values } = parseArgs({
+      args: argv.slice(2),
+      options: {
+        'index-dir': { type: 'string' },
+        profile: { type: 'string' },
+        spec: { type: 'string' },
+        'dry-run': { type: 'boolean', default: false },
+        'no-verify': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+      },
+      allowPositionals: true,
+    })
+    const indexDir = resolveIndexDir(values['index-dir'])
+    const { profile, dir } = profileDirOf(values.profile)
+
+    if (sub === 'status') {
+      printModelStatus(modelStatusValue({ profile, profileDir: dir, indexDir }), values.json)
+      return 0
+    }
+
+    const spec = values.spec
+      || process.env.DSH_PLUGIN_DISCOVER_MODEL_SPEC
+      || 'dsh-plugin-discover-model@0.1.0'
+    if (!existsSync(dir)) {
+      process.stderr.write(`profile 目录不存在：${dir}\n`)
+      return 1
+    }
+    if (values['dry-run']) {
+      try {
+        const dry = installModelPackage(spec, dir, true)
+        if (values.json) process.stdout.write(`${JSON.stringify({ spec, profile, profileDir: dir, ...dry }, null, 2)}\n`)
+        else process.stdout.write(`cd ${dir}\n${dry.display}\n`)
+        return 0
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+        return 1
+      }
+    }
+
+    let install
+    try {
+      install = installModelPackage(spec, dir, false)
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+      return 1
+    }
+    if (install.error) {
+      process.stderr.write(`模型包安装失败：${install.error}\n`)
+      return 1
+    }
+    const installed = resolveInstalledModel(dir)
+    if (!installed) {
+      process.stderr.write(`模型包安装后仍无法解析（pnpm exit ${install.status}）；检查 pnpm 输出与 profile 依赖。\n`)
+      return 1
+    }
+    const verification = await verifyModelFiles(
+      installed.packageDir,
+      installed.manifest,
+      !values['no-verify'],
+    )
+    if (!verification.ok) {
+      process.stderr.write(`模型包校验失败：\n- ${verification.errors.join('\n- ')}\n`)
+      return 1
+    }
+    // pnpm exits non-zero when it ignores a dependency's build script. The
+    // design deliberately does not bypass that approval; the prebuilt CPU
+    // binary works, so a verified package is still a success with a warning.
+    const warning = install.status !== 0
+      ? `pnpm exit ${install.status}；如果这是 ERR_PNPM_IGNORED_BUILDS，onnxruntime-node 的 postinstall 被跳过，预编译二进制仍可用。`
+      : null
+    const pointer = buildModelPointer(installed.packageDir, installed.version, installed.manifest)
+    let pointerPath
+    try {
+      pointerPath = writeModelPointer(indexDir, pointer)
+    } catch (error) {
+      process.stderr.write(`写入 model.json 失败：${error instanceof Error ? error.message : String(error)}\n`)
+      return 1
+    }
+    const status = modelStatusValue({ profile, profileDir: dir, indexDir })
+    if (values.json) {
+      process.stdout.write(`${JSON.stringify({
+        spec,
+        profile,
+        profileDir: dir,
+        install,
+        warning,
+        verification,
+        pointerPath,
+        pointer,
+        status,
+      }, null, 2)}\n`)
+    } else {
+      process.stdout.write(`模型包已安装：${installed.packageDir}\n`)
+      process.stdout.write(`校验：${verification.files} 个文件${verification.hashes ? '，SHA-256 通过' : '（仅大小）'}\n`)
+      if (warning) process.stdout.write(`注意：${warning}\n`)
+      process.stdout.write(`已记录：${pointerPath}\n`)
+      printModelStatus(status, false)
+    }
+    return 0
+  }
+
+  if (command === 'search') {
+    const { values, positionals } = parseArgs({
+      args: argv.slice(1),
+      options: {
+        'index-dir': { type: 'string' },
+        alt: { type: 'string', multiple: true, default: [] },
+        limit: { type: 'string', default: '10' },
+        preset: { type: 'string', default: 'balanced' },
+        'min-verification': { type: 'string', default: '4' },
+        explain: { type: 'string' },
+        json: { type: 'boolean', default: false },
+      },
+      allowPositionals: true,
+    })
+    const query = positionals.join(' ').trim()
+    if (query === '' && !values.explain) {
+      process.stderr.write('search requires a query (or --explain <id>)\n')
+      return 2
+    }
+    const indexDir = resolveIndexDir(values['index-dir'])
+    const records = readRecords(indexDir)
+    if (!records) {
+      process.stderr.write(`没有可用索引：${indexDir}\n先执行：dsh-plugin-discover build\n`)
+      return 1
+    }
+    const manifest = readManifest(indexDir)
+    const preset = PRESETS.includes(values.preset) ? values.preset : 'balanced'
+    const limit = Math.min(20, Math.max(1, Number(values.limit) || 10))
+    const searcher = createSearcher(records.records, { runtimeVersion: detectRuntimeVersion() })
+    const value = values.explain
+      ? explain(searcher, values.explain, { query })
+      : await search(searcher, {
+          query,
+          queryAlts: values.alt,
+          limit,
+          preset,
+          minVerificationLevel: Number(values['min-verification']) || 0,
+          indexDir,
+        })
+    if (values.json) process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+    else printReport(value, manifest)
+    return 0
+  }
+
+  process.stderr.write(`unknown command: ${command}\n\n${USAGE}`)
+  return 2
+}
+
+const code = await main().catch(error => {
+  process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`)
+  return 1
+})
+process.exitCode = code