dsh-plugin-resolver 0.0.0-stage → 0.1.0

package/logic/install.js

@@ -0,0 +1,303 @@
+// Reloadable module: local dependencies carry this module's `?v=` query.
+const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
+const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
+const { dshHome, dirExists, runProcess } = await import(__q('util.js'))
+const { registryBase } = await import(__q('resolve.js'))
+/**
+ * Installation: drive the profile's plugin manager, build GitHub-only sources,
+ * and verify what actually landed.
+ *
+ * The manager owns `package.json`, the lockfile and the activation lifecycle;
+ * this module never edits profile files itself. Registry packages therefore go
+ * straight through `installBundle`, and a source checkout is only ever handed
+ * to it as a `link:` spec after the build produced the package's main entry.
+ *
+ * @module dsh-plugin-resolver/lib/install
+ */
+
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+/** Longest a source install may run before the tool reports a timeout. */
+const BUILD_TIMEOUT_MS = 20 * 60 * 1000
+const TARBALL_TIMEOUT_MS = 5 * 60 * 1000
+
+/**
+ * The `pluginManager` service, or a clear failure.
+ *
+ * @param {any} ctx
+ * @returns {any}
+ */
+export function managerOf(ctx) {
+  const manager = ctx.get('pluginManager')
+  if (!manager || typeof manager.installBundle !== 'function') {
+    throw new Error('the pluginManager service is not mounted in this profile, so installs are unavailable')
+  }
+  return manager
+}
+
+/**
+ * Condense one manager ChangeResult for tool output.
+ *
+ * @param {any} change
+ * @returns {{applied: boolean, application: string, stage: string, error?: string, pendingBuilds: string[], logPath?: string, exitCode?: number}}
+ */
+export function summarizeChange(change) {
+  const summary = {
+    applied: change?.application === 'applied',
+    application: String(change?.application ?? 'failed'),
+    stage: String(change?.stage ?? 'install'),
+    pendingBuilds: Array.isArray(change?.pendingBuilds) ? change.pendingBuilds : [],
+    bundle: typeof change?.bundle === 'string' ? change.bundle : null,
+  }
+  if (change?.error) {
+    const diagnostic = typeof change.error.diagnostic === 'string' ? change.error.diagnostic : ''
+    summary.error = `${change.error.code ?? 'error'}${diagnostic ? `: ${tail(diagnostic, 700)}` : ''}`
+  }
+  if (change?.packageResult) {
+    summary.logPath = change.packageResult.logPath
+    summary.exitCode = change.packageResult.exitCode
+    if (!summary.error && change.packageResult.exitCode !== 0) {
+      summary.error = `pnpm exited ${change.packageResult.exitCode}: ${tail(change.packageResult.output, 700)}`
+    }
+  }
+  return summary
+}
+
+/** Last `limit` characters, flattened. */
+function tail(text, limit) {
+  const flat = String(text ?? '').trim()
+  return flat.length <= limit ? flat : `鈥?{flat.slice(-limit)}`
+}
+
+/**
+ * Install one registry-resolved package spec.
+ *
+ * @param {any} manager
+ * @param {{spec: string, registry?: string | null}} plan
+ * @returns {Promise<{change: any, summary: ReturnType<typeof summarizeChange>}>}
+ */
+export async function installRegistry(manager, plan) {
+  const options = { enabled: true }
+  if (typeof plan.registry === 'string' && plan.registry !== '') options.registry = plan.registry
+  const change = await manager.installBundle(plan.spec, options)
+  return { change, summary: summarizeChange(change) }
+}
+
+/**
+ * Read the installed package manifest through the profile's hoisted
+ * `node_modules`, which also tells us whether the package declares a client
+ * half. The profile directory comes from the environment when the host exposes
+ * it; otherwise the standard `$DSH_HOME/profiles/<name>` layout is tried.
+ *
+ * @param {string} packageName
+ * @returns {Promise<any | undefined>}
+ */
+export async function installedManifest(packageName) {
+  const candidates = []
+  if (process.env.DSH_PROFILE_DIR) candidates.push(process.env.DSH_PROFILE_DIR)
+  const home = process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : null
+  if (home) {
+    const profile = process.env.DSH_PROFILE && process.env.DSH_PROFILE !== '' ? process.env.DSH_PROFILE : 'web'
+    candidates.push(path.join(home, 'profiles', profile))
+  }
+  for (const profileDir of candidates) {
+    try {
+      return JSON.parse(await readFile(path.join(profileDir, 'node_modules', packageName, 'package.json'), 'utf8'))
+    } catch {
+      // try the next candidate
+    }
+  }
+  return undefined
+}
+
+/**
+ * Verify a package after installation: loader entry, bundle selection, and
+ * whether a client half exists (asked of the live client module table first,
+ * because that is what actually decides whether a refresh will show it).
+ *
+ * @param {any} ctx
+ * @param {any} manager
+ * @param {string} packageName
+ * @returns {Promise<{entry?: any, bundle?: any, manifest?: any, hasClient: boolean, clientSource: string}>}
+ */
+export async function verifyInstall(ctx, manager, packageName) {
+  let entry
+  let bundle
+  try {
+    const plugins = await manager.listPlugins()
+    entry = plugins.find(
+      (plugin) =>
+        plugin.moduleName === packageName ||
+        (typeof plugin.moduleName === 'string' && plugin.moduleName.endsWith(`/${packageName}`)),
+    )
+  } catch {
+    entry = undefined
+  }
+  try {
+    const bundles = await manager.listBundles()
+    bundle = bundles.find((item) => item.name === packageName)
+  } catch {
+    bundle = undefined
+  }
+  let hasClient = false
+  let clientSource = 'none'
+  const clientModules = ctx.get('clientModules')
+  if (clientModules && typeof clientModules.clientPath === 'function') {
+    try {
+      hasClient = Boolean(clientModules.clientPath(packageName))
+      if (hasClient) clientSource = 'client table'
+    } catch {
+      // fall through to the manifest
+    }
+  }
+  const manifest = await installedManifest(packageName)
+  if (!hasClient && manifest?.dsh?.client) {
+    hasClient = true
+    clientSource = 'manifest'
+  }
+  return { entry, bundle, manifest, hasClient, clientSource }
+}
+
+/** Locate a pnpm executable usable for a source build. */
+export function resolvePnpm() {
+  const home = dshHome()
+  const candidates =
+    process.platform === 'win32'
+      ? [path.join(home, '.desktop-bin', 'pnpm.cmd'), path.join(home, '..', '..', '.desktop-bin', 'pnpm.cmd')]
+      : [path.join(home, '.desktop-bin', 'pnpm')]
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  return process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
+}
+
+/**
+ * Ensure the GitHub checkout exists, downloading the repository tarball once.
+ *
+ * @param {{repo: string, ref: string | null}} plan
+ * @param {{githubProxy?: string}} options
+ * @returns {Promise<{dir: string, from: 'checkout' | 'download'}>}
+ */
+export async function ensureCheckout(plan, options = {}) {
+  const slug = plan.repo
+  const safe = slug.replace(/[^A-Za-z0-9._-]+/g, '__')
+  const root = path.join(dshHome(), 'plugin-sources', safe)
+  if (dirExists(path.join(root, 'package.json')) || dirExists(path.join(root, '.git'))) {
+    return { dir: root, from: 'checkout' }
+  }
+  const refs = plan.ref ? [plan.ref] : ['main', 'master']
+  const attempts = []
+  for (const ref of refs) {
+    const urls = [`https://codeload.github.com/${slug}/tar.gz/refs/heads/${ref}`]
+    if (options.githubProxy) urls.push(`${options.githubProxy.replace(/\/+$/, '')}/${urls[0]}`)
+    for (const url of urls) {
+      try {
+        const bytes = await download(url)
+        const temp = path.join(dshHome(), 'cache', 'plugin-resolver', `src-${safe}-${Date.now()}`)
+        await rm(temp, { recursive: true, force: true })
+        await mkdir(temp, { recursive: true })
+        const tarball = path.join(temp, 'repo.tar.gz')
+        await writeFile(tarball, bytes)
+        const extractDir = path.join(temp, 'extract')
+        await mkdir(extractDir, { recursive: true })
+        const tar = process.platform === 'win32' ? 'tar.exe' : 'tar'
+        const extracted = await runProcess(tar, ['-xzf', tarball, '-C', extractDir], { timeoutMs: 120_000 })
+        if (extracted.code !== 0) throw new Error(`tar exited ${extracted.code}`)
+        const children = (await readdir(extractDir, { withFileTypes: true })).filter((item) => item.isDirectory())
+        if (children.length !== 1) throw new Error('unexpected tarball layout')
+        await rm(root, { recursive: true, force: true })
+        await mkdir(path.dirname(root), { recursive: true })
+        await rename(path.join(extractDir, children[0].name), root)
+        await rm(temp, { recursive: true, force: true })
+        return { dir: root, from: 'download' }
+      } catch (error) {
+        attempts.push(`${url} -> ${error.message}`)
+      }
+    }
+  }
+  throw new Error(`could not download ${slug}: ${attempts.join(' | ')}`)
+}
+
+/** Download a URL into memory with a bounded timeout. */
+async function download(url) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TARBALL_TIMEOUT_MS)
+  try {
+    const response = await fetch(url, { signal: controller.signal, redirect: 'follow' })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    return Buffer.from(await response.arrayBuffer())
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Build a GitHub-only plugin from its checkout when the package ships no
+ * built output, then install it as a `link:` package.
+ *
+ * @param {any} manager
+ * @param {any} plan a resolution of kind `github`
+ * @param {{githubProxy?: string, skipBuild?: boolean, log?: (line: string) => void}} options
+ * @returns {Promise<{packageName: string, packageDir: string, built: boolean, steps: string[], change: any, summary: ReturnType<typeof summarizeChange>}>}
+ */
+export async function installGithubSource(manager, plan, options = {}) {
+  const log = options.log ?? (() => {})
+  const steps = []
+  const checkout = await ensureCheckout(plan, options)
+  steps.push(`checkout: ${checkout.dir} (${checkout.from})`)
+  log(`${checkout.from === 'download' ? 'download' : 'reuse'} ${plan.repo}`)
+
+  const packageDir = plan.subpath ? path.join(checkout.dir, plan.subpath) : checkout.dir
+  if (!dirExists(packageDir)) throw new Error(`subpath "${plan.subpath}" does not exist in ${plan.repo}`)
+  const manifestPath = path.join(packageDir, 'package.json')
+  if (!existsSync(manifestPath)) throw new Error(`${packageDir} has no package.json`)
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  const packageName = typeof manifest.name === 'string' ? manifest.name : null
+  if (!packageName) throw new Error(`${manifestPath} has no package name`)
+
+  const mainEntry = typeof manifest.main === 'string' && manifest.main !== '' ? manifest.main : 'index.js'
+  const builtPath = path.join(packageDir, mainEntry)
+  let built = existsSync(builtPath)
+  if (!built && options.skipBuild === true) {
+    throw new Error(`${packageName} ships no build output (${mainEntry} missing) and building was disabled`)
+  }
+  if (!built) {
+    if (!manifest.scripts || typeof manifest.scripts.build !== 'string') {
+      throw new Error(
+        `${packageName} ships no build output and declares no "build" script; nothing this plugin can build automatically`,
+      )
+    }
+    const pnpm = resolvePnpm()
+    const registry = registryBase(plan.registry)
+    const env = { npm_config_registry: registry, CI: '1' }
+    const install = await runProcess(pnpm, ['install', '--no-frozen-lockfile'], {
+      cwd: checkout.dir,
+      env,
+      timeoutMs: BUILD_TIMEOUT_MS,
+      onLine: log,
+    })
+    if (install.code !== 0) {
+      throw new Error(`dependency install failed (exit ${install.code}): ${tail(install.output, 900)}`)
+    }
+    steps.push(`deps: pnpm install in ${checkout.dir}`)
+    const build = await runProcess(pnpm, ['run', 'build'], {
+      cwd: packageDir,
+      env,
+      timeoutMs: BUILD_TIMEOUT_MS,
+      onLine: log,
+    })
+    if (build.code !== 0) {
+      throw new Error(`build failed (exit ${build.code}): ${tail(build.output, 900)}`)
+    }
+    steps.push(`build: pnpm run build in ${packageDir}`)
+    built = existsSync(builtPath)
+    if (!built) throw new Error(`build finished but ${mainEntry} still does not exist`)
+  }
+  log(`install link:${packageDir}`)
+  const change = await manager.installBundle(`link:${packageDir}`, { enabled: true })
+  steps.push(`install: link:${packageDir}`)
+  return { packageName, packageDir, built, steps, change, summary: summarizeChange(change) }
+}
+

package/logic/resolve.js

@@ -0,0 +1,396 @@
+// Reloadable module: local dependencies carry this module's `?v=` query.
+const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
+const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
+const { baseName, githubSpecOf, normalizeCatalog, repoSlugOf, searchCatalog } = await import(__q('catalog.js'))
+const { compareVersions, satisfies, sortVersionsDesc, parseVersion } = await import(__q('semver.js'))
+const { fetchJson } = await import(__q('util.js'))
+/**
+ * Resolution: what a target names, which concrete version is DSH-compatible,
+ * which registry to ask, and which install path applies.
+ *
+ * This is the decision layer the tools call before any mutation. It never
+ * touches the profile beyond reading the manager's own inventory.
+ *
+ * @module dsh-plugin-resolver/lib/resolve
+ */
+
+
+/** A package name, optionally with an explicit version. */
+const NPM_TARGET_RE = /^(@[^/@\s]+\/[^@\s]+|[^@/\s#]+)(?:@([^\s]+))?$/
+
+/** Clear hints that the target is already a concrete install spec. */
+const EXPLICIT_SPEC_RE = /^(github:|git\+|file:|link:|https?:\/\/|\.{0,2}[\\/])/i
+
+/**
+ * Read the running DSH core version from the manager's own bundle inventory.
+ *
+ * @param {any} manager the `pluginManager` service
+ * @returns {Promise<string | null>}
+ */
+export async function runtimeVersion(manager) {
+  try {
+    const bundles = await manager.listBundles()
+    const preferred = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh']
+    for (const name of preferred) {
+      const hit = bundles.find((bundle) => bundle.name === name && typeof bundle.version === 'string')
+      if (hit) return hit.version
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Pick the registry asked first: the Host's own probe when mounted, else the
+ * manager's configured registry, else null (pnpm's own configuration).
+ *
+ * @param {any} ctx cordis context
+ * @param {any} manager
+ * @returns {Promise<string | null>}
+ */
+export async function chooseRegistry(ctx, manager) {
+  const probe = ctx.get('pluginRegistryProbe')
+  if (probe && typeof probe.fastest === 'function') {
+    try {
+      const fastest = await probe.fastest()
+      if (typeof fastest === 'string' && fastest !== '') return fastest
+    } catch {
+      // fall through to the configured registry
+    }
+  }
+  try {
+    const registries = await manager.registries()
+    if (registries?.resolved) return registries.resolved
+    if (typeof registries?.registry === 'string') return registries.registry
+  } catch {
+    // fall through
+  }
+  return null
+}
+
+/** A concrete base URL for registry HTTP reads. */
+export function registryBase(registry) {
+  if (typeof registry === 'string' && /^https?:\/\//i.test(registry)) return registry.replace(/\/+$/, '')
+  return 'https://registry.npmjs.org'
+}
+
+/** Encode a scoped package name for a registry path. */
+export function encodePackageName(name) {
+  return name.startsWith('@') ? name.replace('/', '%2f') : name
+}
+
+/**
+ * Fetch a package document from a registry.
+ *
+ * @param {string} name
+ * @param {string} registry
+ * @returns {Promise<{name: string, versions: Record<string, any>, tags: Record<string, string>}>}
+ */
+export async function npmPackage(name, registry) {
+  const base = registryBase(registry)
+  const doc = await fetchJson(`${base}/${encodePackageName(name)}`, { timeoutMs: 30_000 })
+  if (!doc || typeof doc !== 'object' || typeof doc.versions !== 'object') {
+    throw new Error(`registry returned no version document for ${name}`)
+  }
+  return { name, versions: doc.versions ?? {}, tags: doc['dist-tags'] ?? {} }
+}
+
+/**
+ * Choose the newest published version that accepts the running DSH version.
+ *
+ * Only non-optional `@deepseek-ai/*` peers and an `engines.dsh` range are
+ * treated as runtime constraints: a plugin declares its DSH support line there
+ * independently of what a caret over a `0.x` prerelease happens to permit.
+ *
+ * @param {{versions: Record<string, any>, tags: Record<string, string>}} doc
+ * @param {string | null} runtime
+ * @returns {{version: string | null, reason: string, rejected: Array<{version: string, reason: string}>}}
+ */
+export function chooseCompatibleVersion(doc, runtime) {
+  const all = Object.keys(doc.versions).filter((version) => parseVersion(version) !== null)
+  const rejected = []
+  if (all.length === 0) return { version: null, reason: 'no published version', rejected }
+  const ordered = sortVersionsDesc(all)
+  if (runtime === null) {
+    const latest = doc.tags.latest ?? ordered[0]
+    return { version: latest, reason: 'DSH runtime version unknown; trusting the registry latest tag', rejected }
+  }
+  for (const version of ordered) {
+    const manifest = doc.versions[version] ?? {}
+    if (manifest.deprecated) {
+      if (rejected.length < 4) rejected.push({ version, reason: 'deprecated' })
+      continue
+    }
+    const constraint = peerConstraint(manifest, runtime)
+    if (constraint.ok) {
+      return {
+        version,
+        reason: `newest of ${all.length} published versions whose DSH peer range accepts ${runtime}`,
+        rejected,
+      }
+    }
+    if (rejected.length < 4) rejected.push({ version, reason: constraint.reason })
+  }
+  return { version: null, reason: `no published version accepts DSH ${runtime}`, rejected }
+}
+
+/**
+ * Check one published version's runtime constraints against the running DSH.
+ *
+ * Only the Host's own `@deepseek-ai/dsh*` packages share the runtime version
+ * line. Sibling libraries such as `@deepseek-ai/cordis` or
+ * `@deepseek-ai/schemastery` have their own version numbers and are therefore
+ * not runtime constraints.
+ *
+ * @param {any} manifest
+ * @param {string} runtime
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+function peerConstraint(manifest, runtime) {
+  const peers = manifest.peerDependencies ?? {}
+  const optional = manifest.peerDependenciesMeta ?? {}
+  const checked = []
+  for (const [name, range] of Object.entries(peers)) {
+    if (name !== '@deepseek-ai/dsh' && !name.startsWith('@deepseek-ai/dsh-')) continue
+    if (optional[name]?.optional === true) continue
+    if (typeof range !== 'string' || range.trim() === '') continue
+    checked.push(`${name}@${range}`)
+    if (!satisfies(runtime, range)) {
+      return { ok: false, reason: `${name} needs ${range}, host is ${runtime}` }
+    }
+  }
+  const engine = manifest.engines?.dsh
+  if (typeof engine === 'string' && engine !== '') {
+    checked.push(`engines.dsh ${engine}`)
+    if (!satisfies(runtime, engine)) return { ok: false, reason: `engines.dsh wants ${engine}, host is ${runtime}` }
+  }
+  return { ok: true, reason: checked.length > 0 ? checked.join('; ') : 'no DSH constraint' }
+}
+
+/**
+ * Split `name@version`, leaving a scoped package intact.
+ *
+ * @param {string} target
+ * @returns {{name: string, version: string | null} | null}
+ */
+export function parseNpmTarget(target) {
+  const match = NPM_TARGET_RE.exec(target.trim())
+  if (!match) return null
+  return { name: match[1], version: match[2] ?? null }
+}
+
+/**
+ * Parse a GitHub shorthand into its repository, revision and subpath.
+ *
+ * @param {string} spec
+ * @returns {{repo: string, owner: string, name: string, ref: string | null, subpath: string | null} | null}
+ */
+export function parseGithubSpec(spec) {
+  const match = /^github:([^/\s#]+)\/([^/\s#]+)(?:#([^\s]*))?$/i.exec(spec.trim())
+  if (!match) return null
+  let ref = null
+  let subpath = null
+  for (const selector of (match[3] ?? '').split('&')) {
+    if (selector === '') continue
+    const pathMatch = /^path:\/?(.+)$/.exec(selector)
+    if (pathMatch) {
+      subpath = pathMatch[1].replace(/\\/g, '/').replace(/^\/+|\/+$/g, '')
+      continue
+    }
+    if (/^[0-9a-f]{40}$/i.test(selector)) continue
+    if (selector.startsWith('semver:')) {
+      ref = null
+      continue
+    }
+    if (selector.trim() !== '') ref = selector.trim()
+  }
+  return { repo: `${match[1]}/${match[2]}`, owner: match[1], name: match[2], ref, subpath }
+}
+
+/**
+ * Resolve one target into an actionable plan without mutating anything.
+ *
+ * @param {any} ctx
+ * @param {any} manager
+ * @param {string} target user input: catalog name, npm name, name@version, or a spec
+ * @param {{owner?: string, version?: string, registry?: string, catalog?: CatalogEntry[]}} [options]
+ * @returns {Promise<Resolution>}
+ */
+export async function resolveTarget(ctx, manager, target, options = {}) {
+  const trimmed = String(target ?? '').trim()
+  if (trimmed === '') throw new Error('empty target')
+  const registry = options.registry ?? (await chooseRegistry(ctx, manager))
+  const runtime = await runtimeVersion(manager)
+  const notes = []
+
+  if (EXPLICIT_SPEC_RE.test(trimmed)) {
+    const gh = parseGithubSpec(trimmed)
+    if (gh) return await resolveGithub(manager, gh, { registry, runtime, notes, target: trimmed })
+    return {
+      kind: 'spec',
+      spec: trimmed,
+      name: null,
+      version: null,
+      registry,
+      runtime,
+      notes: ['installed verbatim through the profile plugin manager'],
+    }
+  }
+
+  const parsed = parseNpmTarget(trimmed)
+  if (!parsed) throw new Error(`cannot parse "${trimmed}" as a package name or spec`)
+  const explicitVersion = options.version ?? parsed.version
+  let name = parsed.name
+  let catalogEntry = null
+
+  const catalog = options.catalog ?? []
+  if (catalog.length > 0) {
+    const { matches } = searchCatalog(catalog, name, { limit: 12 })
+    const exact = matches.filter(({ entry }) => baseName(entry).toLowerCase() === name.toLowerCase())
+    const pool = exact.length > 0 ? exact.map(({ entry }) => entry) : []
+    if (pool.length > 0) {
+      let chosen = pool
+      if (options.owner) {
+        const wanted = options.owner.toLowerCase()
+        chosen = pool.filter((entry) => entry.owner.toLowerCase() === wanted)
+        if (chosen.length === 0) {
+          throw new Error(
+            `catalog has no "${name}" by owner "${options.owner}". Owners: ${pool
+              .map((entry) => entry.owner || 'unknown')
+              .join(', ')}`,
+          )
+        }
+      }
+      if (chosen.length > 1) {
+        return {
+          kind: 'ambiguous',
+          name,
+          registry,
+          runtime,
+          candidates: chosen.map((entry) => ({
+            name: baseName(entry),
+            owner: entry.owner,
+            stars: entry.stars,
+            npm: entry.npm,
+            install: entry.install,
+            url: entry.url,
+            description: entry.description,
+          })),
+          notes: ['several catalog entries share this name; re-run with owner or a full spec'],
+        }
+      }
+      catalogEntry = chosen[0]
+      if (catalogEntry.npm) name = catalogEntry.npm
+      else {
+        const spec = githubSpecOf(catalogEntry)
+        if (spec) {
+          const gh = parseGithubSpec(spec)
+          if (gh) {
+            notes.push(`catalog entry ${catalogEntry.name} is GitHub-only (no npm package)`)
+            return await resolveGithub(manager, gh, { registry, runtime, notes, target: spec, catalogEntry })
+          }
+        }
+        notes.push(`catalog entry ${catalogEntry.name} has no usable source; falling back to the npm name`)
+      }
+    }
+  }
+
+  if (explicitVersion) {
+    return {
+      kind: 'npm',
+      name,
+      spec: `${name}@${explicitVersion}`,
+      version: explicitVersion,
+      registry,
+      runtime,
+      catalogEntry,
+      notes: [...notes, 'explicit version requested; compatibility not checked'],
+    }
+  }
+
+  let doc = null
+  try {
+    doc = await npmPackage(name, registry)
+  } catch (error) {
+    notes.push(`registry lookup failed (${error.message}); install will resolve the version itself`)
+    return { kind: 'npm', name, spec: name, version: null, registry, runtime, catalogEntry, notes }
+  }
+  const chosen = chooseCompatibleVersion(doc, runtime)
+  if (chosen.version === null) {
+    throw new Error(
+      `${name} has no version compatible with DSH ${runtime ?? 'unknown'}. ` +
+        `Nearest rejects: ${chosen.rejected.map((item) => `${item.version} (${item.reason})`).join('; ') || 'none'}`,
+    )
+  }
+  if (chosen.rejected.length > 0) {
+    notes.push(
+      `skipped newer incompatible versions: ${chosen.rejected.map((item) => `${item.version} (${item.reason})`).join('; ')}`,
+    )
+  }
+  return {
+    kind: 'npm',
+    name,
+    spec: `${name}@${chosen.version}`,
+    version: chosen.version,
+    latest: doc.tags?.latest ?? null,
+    registry,
+    runtime,
+    catalogEntry,
+    notes: [...notes, chosen.reason],
+    rejected: chosen.rejected,
+  }
+}
+
+/**
+ * Plan a GitHub-source install.
+ *
+ * @param {any} manager
+ * @param {{repo: string, owner: string, name: string, ref: string | null, subpath: string | null}} gh
+ * @param {{registry: string | null, runtime: string | null, notes: string[], target: string, catalogEntry?: any}} context
+ * @returns {Promise<Resolution>}
+ */
+async function resolveGithub(manager, gh, context) {
+  const slug = gh.repo
+  const label = gh.subpath ? `${slug}/${gh.subpath}` : slug
+  return {
+    kind: 'github',
+    repo: slug,
+    owner: gh.owner,
+    name: gh.name,
+    ref: gh.ref,
+    subpath: gh.subpath,
+    spec: context.target,
+    version: null,
+    registry: context.registry,
+    runtime: context.runtime,
+    catalogEntry: context.catalogEntry ?? null,
+    notes: [
+      ...context.notes,
+      `GitHub source build: ${label}${gh.ref ? ` @ ${gh.ref}` : ''}`,
+      'source checkout is built locally (pnpm install + build) and then linked into the profile',
+    ],
+    label,
+  }
+}
+
+/**
+ * @typedef {object} Resolution
+ * @property {'npm' | 'github' | 'spec' | 'ambiguous'} kind
+ * @property {string} spec
+ * @property {string | null} name
+ * @property {string | null} version
+ * @property {string | null} registry
+ * @property {string | null} runtime
+ * @property {string[]} notes
+ * @property {Array<{name: string, owner: string, stars: number, npm: string | null, install: string | null, url: string, description: string}>} [candidates]
+ * @property {Array<{version: string, reason: string}>} [rejected]
+ * @property {any} [catalogEntry]
+ * @property {string} [repo]
+ * @property {string | null} [ref]
+ * @property {string | null} [subpath]
+ * @property {string} [latest]
+ */
+
+export { normalizeCatalog, compareVersions, repoSlugOf, githubSpecOf }
+