dsh-plugin-resolver 0.0.0-stage → 0.1.0

package/logic/semver.js

@@ -0,0 +1,227 @@
+/**
+ * The slice of semver this plugin needs: parse versions, compare them, and
+ * decide whether a version satisfies a range.
+ *
+ * Semantics intentionally match the Host's own compatibility preflight, which
+ * compares with `includePrerelease: true`: prerelease versions are ordinary
+ * values, so `0.2.0-rc.2` satisfies `^0.2.0-rc.2` but not `^0.2.1-rc.1`.
+ *
+ * @module dsh-plugin-resolver/lib/semver
+ */
+
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+/**
+ * Parse a full semver version.
+ *
+ * @param {unknown} value
+ * @returns {{major: number, minor: number, patch: number, pre: string[]} | null}
+ */
+export function parseVersion(value) {
+  const match = VERSION_RE.exec(String(value ?? '').trim())
+  if (!match) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    pre: match[4] ? match[4].split('.') : [],
+  }
+}
+
+/**
+ * Compare two parsed versions.
+ *
+ * @param {{major: number, minor: number, patch: number, pre: string[]}} left
+ * @param {{major: number, minor: number, patch: number, pre: string[]}} right
+ * @returns {number} -1, 0, or 1
+ */
+export function compareParsed(left, right) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1
+  }
+  if (left.pre.length === 0 && right.pre.length === 0) return 0
+  if (left.pre.length === 0) return 1
+  if (right.pre.length === 0) return -1
+  const length = Math.max(left.pre.length, right.pre.length)
+  for (let index = 0; index < length; index += 1) {
+    const a = left.pre[index]
+    const b = right.pre[index]
+    if (a === undefined) return -1
+    if (b === undefined) return 1
+    const aNumeric = /^\d+$/.test(a)
+    const bNumeric = /^\d+$/.test(b)
+    if (aNumeric && bNumeric) {
+      const delta = Number(a) - Number(b)
+      if (delta !== 0) return delta < 0 ? -1 : 1
+    } else if (aNumeric) return -1
+    else if (bNumeric) return 1
+    else if (a !== b) return a < b ? -1 : 1
+  }
+  return 0
+}
+
+/**
+ * Compare two version strings.
+ *
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function compareVersions(left, right) {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  if (!a || !b) return 0
+  return compareParsed(a, b)
+}
+
+/**
+ * Parse a possibly partial version such as `1`, `1.2`, `^1.2.3-rc.1`.
+ *
+ * @param {string} raw
+ * @returns {{major: number, minor: number, patch: number, pre: string[], minorGiven: boolean, patchGiven: boolean} | null}
+ */
+function parsePartial(raw) {
+  const text = raw.trim().replace(/^v/, '')
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(text)
+  if (!match) return null
+  return {
+    major: Number(match[1]),
+    minor: match[2] === undefined ? 0 : Number(match[2]),
+    patch: match[3] === undefined ? 0 : Number(match[3]),
+    pre: match[4] ? match[4].split('.') : [],
+    minorGiven: match[2] !== undefined,
+    patchGiven: match[3] !== undefined,
+  }
+}
+
+const LOWER = { major: 0, minor: 0, patch: 0, pre: [] }
+
+/** Full parse of a version-like token, or null when it is a wildcard. */
+function asVersion(partial) {
+  if (!partial) return null
+  return { major: partial.major, minor: partial.minor, patch: partial.patch, pre: partial.pre }
+}
+
+/**
+ * Upper bound of a caret range. The `-0` prerelease mirrors node-semver's
+ * `includePrerelease: true` desugaring: it excludes prereleases of the next
+ * minor/major, which is exactly the trap that silently disables a plugin whose
+ * caret range was written against the previous support line.
+ */
+function caretUpper(partial) {
+  if (partial.major > 0 || !partial.minorGiven) {
+    return { major: partial.major + 1, minor: 0, patch: 0, pre: ['0'] }
+  }
+  if (partial.minor > 0 || !partial.patchGiven) {
+    return { major: 0, minor: partial.minor + 1, patch: 0, pre: ['0'] }
+  }
+  return { major: 0, minor: 0, patch: partial.patch + 1, pre: ['0'] }
+}
+
+/** Upper bound of a tilde range, with the same prerelease ceiling. */
+function tildeUpper(partial) {
+  return partial.minorGiven
+    ? { major: partial.major, minor: partial.minor + 1, patch: 0, pre: ['0'] }
+    : { major: partial.major + 1, minor: 0, patch: 0, pre: ['0'] }
+}
+
+/** Upper bound of a bare partial range: `1.2` means `>=1.2.0 <1.3.0`. */
+function partialUpper(partial) {
+  if (partial.minorGiven && partial.patchGiven) return null
+  return partial.minorGiven
+    ? { major: partial.major, minor: partial.minor + 1, patch: 0, pre: ['0'] }
+    : { major: partial.major + 1, minor: 0, patch: 0, pre: ['0'] }
+}
+
+/**
+ * Whether one whitespace-separated comparator set matches.
+ *
+ * @param {{major: number, minor: number, patch: number, pre: string[]}} version
+ * @param {string} set
+ * @returns {boolean}
+ */
+function matchesSet(version, set) {
+  const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(set.trim())
+  if (hyphen) {
+    const lower = asVersion(parsePartial(hyphen[1]))
+    const upperPartial = parsePartial(hyphen[2])
+    const upper = asVersion(upperPartial)
+    if (!lower || !upper) return false
+    return compareParsed(version, lower) >= 0 && compareParsed(version, upper) <= 0
+  }
+  const tokens = set.trim().split(/\s+/).filter(Boolean)
+  if (tokens.length === 0) return true
+  for (const token of tokens) {
+    if (token === '*' || token === 'x' || token === 'X') continue
+    const operatorMatch = /^(\^|~|>=|<=|>|<|=)?\s*(.*)$/.exec(token)
+    if (!operatorMatch) return false
+    const operator = operatorMatch[1] ?? ''
+    const raw = operatorMatch[2]
+    if (raw === '' || raw === '*' || raw === 'x' || raw === 'X') continue
+    const partial = parsePartial(raw)
+    if (!partial) return false
+    const point = asVersion(partial)
+    if (operator === '^') {
+      if (compareParsed(version, point) < 0) return false
+      if (compareParsed(version, caretUpper(partial)) >= 0) return false
+    } else if (operator === '~') {
+      if (compareParsed(version, point) < 0) return false
+      if (compareParsed(version, tildeUpper(partial)) >= 0) return false
+    } else if (operator === '>=') {
+      if (compareParsed(version, point) < 0) return false
+    } else if (operator === '>') {
+      if (compareParsed(version, point) <= 0) return false
+    } else if (operator === '<=') {
+      if (compareParsed(version, point) > 0) return false
+    } else if (operator === '<') {
+      if (compareParsed(version, point) >= 0) return false
+    } else if (operator === '=') {
+      if (compareParsed(version, point) !== 0) return false
+    } else {
+      // Bare token: an exact version, or a partial range such as `1.2`.
+      const upper = partialUpper(partial)
+      if (upper === null) {
+        if (compareParsed(version, point) !== 0) return false
+      } else {
+        if (compareParsed(version, point) < 0) return false
+        if (compareParsed(version, upper) >= 0) return false
+      }
+    }
+  }
+  return true
+}
+
+/**
+ * Whether `version` satisfies `range`.
+ *
+ * @param {string} version
+ * @param {string} range
+ * @returns {boolean}
+ */
+export function satisfies(version, range) {
+  const parsed = parseVersion(version)
+  if (!parsed) return false
+  const text = String(range ?? '').trim()
+  if (text === '' || text === '*' || text === 'x') return true
+  for (const alternative of text.split('||')) {
+    if (matchesSet(parsed, alternative.trim())) return true
+  }
+  return false
+}
+
+/**
+ * Sort version strings newest first.
+ *
+ * @param {string[]} versions
+ * @returns {string[]}
+ */
+export function sortVersionsDesc(versions) {
+  return [...versions].sort((a, b) => compareVersions(b, a))
+}
+
+/** Lowest version above another, used only for error messages. */
+export function isValidVersion(value) {
+  return parseVersion(value) !== null
+}
+
+export { LOWER }

package/logic/util.js

@@ -0,0 +1,193 @@
+/**
+ * Small host-side utilities: DSH home discovery, cached JSON, HTTP JSON, and a
+ * Windows-aware child-process runner. No host package imports on purpose.
+ *
+ * @module dsh-plugin-resolver/lib/util
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+/** Absolute DSH home for the running host. */
+export function dshHome() {
+  return process.env.DSH_HOME && process.env.DSH_HOME !== ''
+    ? process.env.DSH_HOME
+    : path.join(homedir(), '.dsh')
+}
+
+/** Cache directory owned by this plugin. */
+export function cacheDir() {
+  return path.join(dshHome(), 'cache', 'plugin-resolver')
+}
+
+/**
+ * Read a JSON file, returning undefined when absent or unparsable.
+ *
+ * @param {string} file
+ * @returns {Promise<any>}
+ */
+export async function readJson(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Write a JSON file, creating parent directories.
+ *
+ * @param {string} file
+ * @param {unknown} value
+ * @returns {Promise<void>}
+ */
+export async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true })
+  await writeFile(file, JSON.stringify(value), 'utf8')
+}
+
+/**
+ * Fetch and parse JSON with a hard timeout.
+ *
+ * @param {string} url
+ * @param {{timeoutMs?: number, headers?: Record<string, string>}} [options]
+ * @returns {Promise<any>}
+ */
+export async function fetchJson(url, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 30_000
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { accept: 'application/json', 'user-agent': 'dsh-plugin-resolver', ...(options.headers ?? {}) },
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`)
+    return await response.json()
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Fetch raw bytes with a hard timeout.
+ *
+ * @param {string} url
+ * @param {{timeoutMs?: number}} [options]
+ * @returns {Promise<Buffer>}
+ */
+export async function fetchBuffer(url, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 60_000
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      redirect: 'follow',
+      headers: { 'user-agent': 'dsh-plugin-resolver' },
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`)
+    return Buffer.from(await response.arrayBuffer())
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Trim a one-line description for compact tool output. */
+export function oneLine(text, limit = 120) {
+  if (typeof text !== 'string') return ''
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`
+}
+
+/** Format a star count compactly. */
+export function stars(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n <= 0) return 'new'
+  return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n)
+}
+
+/**
+ * Run a child process and collect its output.
+ *
+ * `.cmd`/`.bat` shims on Windows go through `cmd.exe`, because Node cannot
+ * spawn them directly; every other executable is spawned without a shell so
+ * arguments keep their exact boundaries.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: Record<string, string>, timeoutMs?: number, onLine?: (line: string) => void}} [options]
+ * @returns {Promise<{code: number, output: string, timedOut: boolean}>}
+ */
+export function runProcess(command, args, options = {}) {
+  const isShim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(command)
+  const file = isShim ? process.env.COMSPEC || 'cmd.exe' : command
+  const argv = isShim
+    ? ['/d', '/s', '/c', quoteCommandLine([command, ...args])]
+    : args
+  return new Promise((resolve) => {
+    let output = ''
+    let settled = false
+    let timedOut = false
+    const child = spawn(file, argv, {
+      cwd: options.cwd,
+      env: { ...process.env, ...(options.env ?? {}) },
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const timer = options.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true
+          child.kill()
+        }, options.timeoutMs)
+      : undefined
+    const append = (chunk) => {
+      const text = String(chunk)
+      output += text
+      if (options.onLine) {
+        for (const line of text.split(/\r?\n/)) {
+          if (line.trim() !== '') options.onLine(line.trimEnd())
+        }
+      }
+      if (output.length > 400_000) output = output.slice(-200_000)
+    }
+    child.stdout?.on('data', append)
+    child.stderr?.on('data', append)
+    child.on('error', (error) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      resolve({ code: 127, output: `${output}\n${error.message}`.trim(), timedOut })
+    })
+    child.on('close', (code) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      resolve({ code: code ?? 1, output, timedOut })
+    })
+  })
+}
+
+/** Quote an argv for the Windows `cmd.exe /s /c` fallback. */
+function quoteCommandLine(argv) {
+  return argv
+    .map((part) => {
+      const value = String(part)
+      if (value === '') return '""'
+      if (!/[\s"&|<>^]/.test(value)) return value
+      return `"${value.replace(/"/g, '""')}"`
+    })
+    .join(' ')
+}
+
+/** True when a directory exists. */
+export function dirExists(target) {
+  try {
+    return existsSync(target)
+  } catch {
+    return false
+  }
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "dsh-plugin-resolver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Agent-facing DSH plugin resolver: search the catalog, pick a version the running DSH accepts, install (registry or GitHub-source build), and verify - no trial and error.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "host",
+    "logic",
+    "cordis.patch.yml",
+    "README.md",
+    "BENCHMARK.md",
+    "ABLATION.md"
+  ],
+  "scripts": {
+    "test": "node test/selftest.mjs && node test/harness.mjs",
+    "bench": "node test/benchmark.mjs",
+    "ablate": "node test/ablation.mjs"
+  },
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.0-rc.2 <0.3.0"
+  },
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "plugin-manager",
+    "plugin-installer",
+    "resolver",
+    "catalog"
+  ],
+  "author": "sakikoTGW",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sakikoTGW/dsh-plugin-resolver.git"
+  },
+  "homepage": "https://github.com/sakikoTGW/dsh-plugin-resolver#readme",
+  "bugs": {
+    "url": "https://github.com/sakikoTGW/dsh-plugin-resolver/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}