dsh-plugin-discover 0.0.0-stage → 1.0.0

package/lib/compat.js

@@ -0,0 +1,157 @@
+/**
+ * Minimal semantic-version comparison and DSH runtime detection. The catalog
+ * stores ordinary npm ranges; anything this parser does not understand is
+ * reported as `unknown`, which the balanced preset deliberately lets through.
+ */
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+/** Parse a semantic version; null when malformed. */
+export function parseVersion(value) {
+  if (typeof value !== 'string') return null
+  const match = VERSION_RE.exec(value.trim())
+  if (!match) return null
+  const prerelease = match[4] ? match[4].split('.') : []
+  if (prerelease.some(part => part === '')) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease,
+  }
+}
+
+function compareIdentifier(a, b) {
+  const aNumeric = /^\d+$/.test(a)
+  const bNumeric = /^\d+$/.test(b)
+  if (aNumeric && bNumeric) return Number(a) - Number(b)
+  if (aNumeric) return -1
+  if (bNumeric) return 1
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+/** Compare two semantic versions: <0, 0, or >0. Malformed input sorts first. */
+export function compareVersions(a, b) {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  if (!left && !right) return 0
+  if (!left) return -1
+  if (!right) return 1
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] - right[key]
+  }
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0
+  if (left.prerelease.length === 0) return 1
+  if (right.prerelease.length === 0) return -1
+  const length = Math.max(left.prerelease.length, right.prerelease.length)
+  for (let index = 0; index < length; index += 1) {
+    const l = left.prerelease[index]
+    const r = right.prerelease[index]
+    if (l === undefined) return -1
+    if (r === undefined) return 1
+    const compared = compareIdentifier(l, r)
+    if (compared !== 0) return compared
+  }
+  return 0
+}
+
+function upperBound(version, kind) {
+  const parsed = parseVersion(version)
+  if (!parsed) return null
+  const { major, minor, patch } = parsed
+  if (kind === '^') {
+    if (major > 0) return `${major + 1}.0.0-0`
+    if (minor > 0) return `0.${minor + 1}.0-0`
+    return `0.0.${patch + 1}-0`
+  }
+  if (kind === '~') return `${major}.${minor + 1}.0-0`
+  return null
+}
+
+function satisfiesComparator(version, comparator) {
+  const match = /^(\^|~|>=|<=|>|<|=)?\s*(.+)$/.exec(comparator.trim())
+  if (!match) return null
+  const operator = match[1] ?? '='
+  const target = match[2].trim()
+  if (target === '' || target === '*' || target === 'x' || target === 'X') return true
+  if (!parseVersion(target)) return null
+  if (operator === '=') return compareVersions(version, target) === 0
+  if (operator === '>') return compareVersions(version, target) > 0
+  if (operator === '>=') return compareVersions(version, target) >= 0
+  if (operator === '<') return compareVersions(version, target) < 0
+  if (operator === '<=') return compareVersions(version, target) <= 0
+  const upper = upperBound(target, operator)
+  if (!upper) return null
+  return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0
+}
+
+/**
+ * Check a version against a range. Returns `true`, `false`, or `null` for a
+ * range this parser does not understand.
+ */
+export function satisfiesRange(version, range) {
+  if (typeof version !== 'string' || typeof range !== 'string') return null
+  if (!parseVersion(version)) return null
+  const groups = range.split('||').map(group => group.trim()).filter(Boolean)
+  if (groups.length === 0) return null
+  let understood = false
+  for (const group of groups) {
+    const comparators = group.split(/\s+/).filter(Boolean)
+    let all = true
+    let anyUnknown = false
+    for (const comparator of comparators) {
+      const result = satisfiesComparator(version, comparator)
+      if (result === null) { anyUnknown = true; all = false; break }
+      understood = true
+      if (!result) { all = false; break }
+    }
+    if (all && !anyUnknown) return true
+  }
+  return understood ? false : null
+}
+
+let detected
+
+/** Guess the running DSH version without importing Host packages. */
+export function detectRuntimeVersion() {
+  if (detected !== undefined) return detected
+  if (process.env.DSH_VERSION && parseVersion(process.env.DSH_VERSION)) {
+    detected = process.env.DSH_VERSION
+    return detected
+  }
+  const roots = new Set()
+  const add = value => { if (typeof value === 'string' && value.trim() !== '') roots.add(value) }
+  add(process.cwd())
+  add(process.env.DSH_PROFILE_DIR)
+  add(process.env.DSH_HOME)
+  try { add(dirname(fileURLToPath(import.meta.url))) } catch {}
+  const require = createRequire(import.meta.url)
+  const manifests = [
+    '@deepseek-ai/dsh-app-boot/package.json',
+    '@deepseek-ai/dsh/package.json',
+    '@deepseek-ai/dsh-cli/package.json',
+  ]
+  for (const root of roots) {
+    for (const manifest of manifests) {
+      try {
+        const file = require.resolve(manifest, { paths: [root] })
+        const value = JSON.parse(readFileSync(file, 'utf8'))
+        if (value && parseVersion(value.version)) {
+          detected = value.version
+          return detected
+        }
+      } catch {}
+    }
+  }
+  detected = null
+  return detected
+}
+
+/** Reset the detection cache (tests only). */
+export function resetRuntimeVersionCache() {
+  detected = undefined
+}

package/lib/filters.js

@@ -0,0 +1,105 @@
+/**
+ * Hard filtering by security, verification, and DSH compatibility. Missing
+ * fields are "unknown", not "failed": they pass and stay annotated.
+ */
+import { satisfiesRange } from './compat.js'
+
+export const PRESETS = ['strict', 'balanced', 'loose', 'off']
+export const DEFAULT_PRESET = 'balanced'
+
+function isAudited(record) {
+  return record?.security?.status === 'audited'
+}
+
+function riskOf(record) {
+  return record?.security?.riskLevel ?? 'unknown'
+}
+
+/** Security gate for one preset. Unknown security never fails a preset. */
+export function securityAllowed(record, preset) {
+  if (preset === 'strict') return isAudited(record) && riskOf(record) === 'low'
+  if (preset === 'off') return !(isAudited(record) && riskOf(record) === 'critical')
+  if (preset === 'loose') {
+    const risk = riskOf(record)
+    return !(isAudited(record) && (risk === 'high' || risk === 'critical'))
+  }
+  if (!isAudited(record)) return true
+  const risk = riskOf(record)
+  return risk !== 'high' && risk !== 'critical'
+}
+
+/** Verification gate. `0` disables the level floor for the balanced preset. */
+export function verificationAllowed(record, preset, minVerificationLevel = 4) {
+  if (preset === 'strict') return record?.verification?.level === 5
+  if (preset !== 'balanced') return true
+  const minimum = Number.isFinite(minVerificationLevel) ? minVerificationLevel : 4
+  if (minimum <= 0) return true
+  const level = record?.verification?.level
+  return typeof level !== 'number' ? true : level >= minimum
+}
+
+/** Compatibility state: true, false, or null for unknown. */
+export function compatibilityOf(record, runtimeVersion) {
+  const range = record?.dshRange
+  if (typeof range !== 'string' || range.trim() === '') return null
+  if (typeof runtimeVersion !== 'string' || runtimeVersion === '') return null
+  return satisfiesRange(runtimeVersion, range)
+}
+
+/** Compatibility gate: balanced admits unknown, strict does not. */
+export function compatibilityAllowed(record, preset, runtimeVersion) {
+  if (preset === 'strict') return compatibilityOf(record, runtimeVersion) === true
+  if (preset === 'loose' || preset === 'off') return true
+  return compatibilityOf(record, runtimeVersion) !== false
+}
+
+/** Evaluate one record against one preset. */
+export function evaluateRecord(record, { preset = DEFAULT_PRESET, minVerificationLevel = 4, runtimeVersion = null } = {}) {
+  if (!securityAllowed(record, preset)) return { ok: false, droppedBy: 'security' }
+  if (!verificationAllowed(record, preset, minVerificationLevel)) return { ok: false, droppedBy: 'verification' }
+  if (!compatibilityAllowed(record, preset, runtimeVersion)) return { ok: false, droppedBy: 'compat' }
+  return { ok: true }
+}
+
+/** Apply one preset to every record. */
+export function filterRecords(records, options = {}) {
+  const { preset = DEFAULT_PRESET, minVerificationLevel = 4, runtimeVersion = null } = options
+  const allowed = new Uint8Array(records.length)
+  const droppedBy = { security: 0, compatibility: 0, verification: 0 }
+  let kept = 0
+  for (let index = 0; index < records.length; index += 1) {
+    const result = evaluateRecord(records[index], { preset, minVerificationLevel, runtimeVersion })
+    if (result.ok) {
+      allowed[index] = 1
+      kept += 1
+    } else if (result.droppedBy === 'compat') {
+      droppedBy.compatibility += 1
+    } else {
+      droppedBy[result.droppedBy] += 1
+    }
+  }
+  return { allowed, kept, droppedBy }
+}
+
+/**
+ * Apply the requested preset, relaxing one step at a time until at least three
+ * candidates survive. The caller reports `relaxedFrom` when this happens.
+ */
+export function selectFilter(records, options = {}) {
+  const { preset = DEFAULT_PRESET, minVerificationLevel = 4, runtimeVersion = null, minCandidates = 3 } = options
+  const start = PRESETS.includes(preset) ? preset : DEFAULT_PRESET
+  const startIndex = PRESETS.indexOf(start)
+  for (let index = startIndex; index < PRESETS.length; index += 1) {
+    const candidate = PRESETS[index]
+    const result = filterRecords(records, { preset: candidate, minVerificationLevel, runtimeVersion })
+    if (result.kept >= minCandidates || candidate === 'off') {
+      return {
+        preset: candidate,
+        relaxedFrom: candidate === start ? null : start,
+        ...result,
+      }
+    }
+  }
+  const fallback = filterRecords(records, { preset: 'off', minVerificationLevel, runtimeVersion })
+  return { preset: 'off', relaxedFrom: start, ...fallback }
+}

package/lib/model-client.js

@@ -0,0 +1,163 @@
+/**
+ * Client for the optional model package's line-delimited JSON server. The
+ * server owns the ~500 MB ONNX/tokenizer RSS; the Host only holds vectors.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+
+/** The optional model package is not installed or its server is missing. */
+export class ModelUnavailableError extends Error {
+  constructor(message = 'model package is not installed') {
+    super(message)
+    this.name = 'ModelUnavailableError'
+    this.code = 'MODEL_UNAVAILABLE'
+  }
+}
+
+/** Resolve the server entry through the index pointer, then the profile. */
+export function resolveModelServer(indexDir) {
+  try {
+    const pointer = JSON.parse(readFileSync(join(indexDir, 'model.json'), 'utf8'))
+    if (pointer && typeof pointer.server === 'string' && existsSync(pointer.server)) return pointer.server
+  } catch {}
+  const profileDir = process.env.DSH_PROFILE_DIR
+  if (profileDir) {
+    try {
+      const require = createRequire(join(profileDir, 'package.json'))
+      const server = require.resolve('dsh-plugin-discover-model/server.js')
+      if (existsSync(server)) return server
+    } catch {}
+  }
+  return null
+}
+
+/** Spawned model server with request/response correlation and idle respawn. */
+export class ModelClient {
+  constructor(serverPath, { timeoutMs = 60_000 } = {}) {
+    this.serverPath = serverPath
+    this.timeoutMs = timeoutMs
+    this.child = null
+    this.pending = new Map()
+    this.nextId = 1
+    this.stderr = ''
+    this.closed = false
+    this.embeddedDocs = 0
+    // Recycling is an escape hatch for pathological environments, not the
+    // default: the model is capped at four ONNX threads instead of all cores.
+    this.recycleDocs = Number(process.env.DSH_MODEL_RECYCLE_DOCS) || 0
+  }
+
+  /** Stop this child after a bounded number of documents; the next request respawns. */
+  recycle() {
+    this.failAll(new ModelUnavailableError('model client recycled'))
+    if (this.child) {
+      try { this.child.kill() } catch {}
+      this.child = null
+    }
+    this.embeddedDocs = 0
+  }
+
+  start() {
+    if (this.child) return
+    if (this.closed) throw new ModelUnavailableError('model client is disposed')
+    const env = { ...process.env }
+    if (process.versions.electron) env.ELECTRON_RUN_AS_NODE = '1'
+    const command = process.env.DSH_PLUGIN_DISCOVER_NODE || process.execPath
+    let child
+    try {
+      child = spawn(command, [this.serverPath], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+        env,
+      })
+    } catch (error) {
+      throw new ModelUnavailableError(`cannot start model server: ${error.message}`)
+    }
+    this.child = child
+    createInterface({ input: child.stdout, crlfDelay: Infinity }).on('line', line => {
+      const text = line.trim()
+      if (text === '') return
+      let response
+      try {
+        response = JSON.parse(text)
+      } catch {
+        return
+      }
+      const pending = this.pending.get(response.id)
+      if (!pending) return
+      this.pending.delete(response.id)
+      clearTimeout(pending.timer)
+      if (typeof response.error === 'string') pending.reject(new Error(response.error))
+      else pending.resolve(response)
+    })
+    child.stderr.on('data', chunk => {
+      this.stderr = `${this.stderr}${chunk.toString()}`.slice(-4000)
+    })
+    child.on('error', error => {
+      if (this.child !== child) return
+      this.failAll(new ModelUnavailableError(`model server error: ${error.message}`))
+      this.child = null
+    })
+    child.on('exit', code => {
+      if (this.child !== child) return
+      this.failAll(new ModelUnavailableError(
+        `model server exited (${code})${this.stderr ? `: ${this.stderr.slice(-500)}` : ''}`,
+      ))
+      this.child = null
+    })
+  }
+
+  failAll(error) {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer)
+      pending.reject(error)
+      this.pending.delete(id)
+    }
+  }
+
+  request(op, payload, timeoutMs = this.timeoutMs) {
+    this.start()
+    const id = this.nextId++
+    const line = `${JSON.stringify({ id, op, ...payload })}\n`
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`model server request timed out after ${timeoutMs} ms`))
+      }, timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      try {
+        this.child.stdin.write(line)
+      } catch (error) {
+        clearTimeout(timer)
+        this.pending.delete(id)
+        reject(new ModelUnavailableError(`cannot write to model server: ${error.message}`))
+      }
+    })
+  }
+
+  async embed(texts, kind = 'passage') {
+    if (this.recycleDocs > 0 && this.embeddedDocs >= this.recycleDocs) this.recycle()
+    const response = await this.request('embed', { texts, kind }, Math.max(this.timeoutMs, 120_000))
+    if (!Array.isArray(response.vectors)) throw new Error('model server returned no vectors')
+    this.embeddedDocs += texts.length
+    if (this.recycleDocs > 0 && this.embeddedDocs >= this.recycleDocs) this.recycle()
+    return response.vectors.map(vector => Float32Array.from(vector))
+  }
+
+  async truncate(text, maxTokens = 384) {
+    const response = await this.request('truncate', { text, maxTokens })
+    return { text: String(response.text ?? ''), tokens: Number(response.tokens ?? 0) }
+  }
+
+  dispose() {
+    this.closed = true
+    this.failAll(new ModelUnavailableError('model client disposed'))
+    if (this.child) {
+      try { this.child.kill() } catch {}
+      this.child = null
+    }
+  }
+}