dsh-plugin-resolver 0.0.0-stage → 0.1.0

package/logic/api.js

@@ -0,0 +1,270 @@
+/**
+ * Reloadable logic entry: every tool body lives here, behind one cache-busted
+ * import. The host shell asks for this module with `?v=<logic mtime>` on each
+ * call, so editing any file under `logic/` takes effect on the next tool call
+ * without restarting the host.
+ *
+ * Nothing in here touches the loader or the tool registry; it receives the
+ * profile's `pluginManager` and a Cordis context and returns plain text.
+ *
+ * @module dsh-plugin-resolver/logic/api
+ */
+
+// Local dependencies carry this module's own `?v=` query, so one cache-busted
+// import of `api.js` reloads catalog/resolve/install/util together.
+const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
+const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
+const { baseName, loadCatalog, searchCatalog } = await import(__q('catalog.js'))
+const { installGithubSource, installRegistry, verifyInstall } = await import(__q('install.js'))
+const { resolveTarget } = await import(__q('resolve.js'))
+const { oneLine, stars } = await import(__q('util.js'))
+
+/** Catalog load honoring the `refresh` flag and config overrides. */
+async function catalogFor(options, refresh) {
+  try {
+    const combined = { ...options }
+    if (refresh) return await loadCatalog(combined, { force: true })
+    return await loadCatalog(combined)
+  } catch (error) {
+    return { entries: [], fetchedAt: 0, fromCache: false, source: 'unavailable', error: error?.message ?? String(error) }
+  }
+}
+
+/** Bundle names already installed in this profile. */
+async function installedNames(manager) {
+  const set = new Set()
+  if (!manager) return set
+  try {
+    const bundles = await manager.listBundles()
+    for (const bundle of bundles) {
+      if (bundle?.installed && typeof bundle.name === 'string') set.add(bundle.name)
+    }
+  } catch {
+    // inventory is best-effort
+  }
+  return set
+}
+
+/**
+ * `plugin_search`: rank catalog entries and keep same-name ambiguity visible.
+ *
+ * @param {any} ctx
+ * @param {any} manager
+ * @param {Record<string, unknown>} options
+ * @param {any} args
+ * @returns {Promise<{text: string}>}
+ */
+export async function pluginSearch(ctx, manager, options, args) {
+  const query = String(args?.query ?? '').trim()
+  if (query === '') return { text: 'plugin_search needs a non-empty query.' }
+  const installed = await installedNames(manager)
+  const catalog = await catalogFor(options, args?.refresh === true)
+  if (catalog.entries.length === 0) {
+    return { text: `Catalog is unavailable right now: ${catalog.error ?? 'empty catalog'}` }
+  }
+  const { matches, ambiguous } = searchCatalog(catalog.entries, query, {
+    limit: Number(args?.limit) || 8,
+    installed,
+  })
+  if (matches.length === 0) {
+    return { text: `No catalog entry matches "${query}" (${catalog.entries.length} entries, ${catalog.fromCache ? 'cached' : 'fresh'}).` }
+  }
+  const lines = [
+    `${matches.length} match(es) for "${query}" — catalog ${catalog.entries.length} entries, ${catalog.fromCache ? 'cached' : `fresh from ${catalog.source}`}:`,
+    '',
+  ]
+  matches.forEach(({ entry, installed: isInstalled }, index) => {
+    lines.push(`${index + 1}. ${entry.name}  ★${stars(entry.stars)}  owner=${entry.owner || '?'}${isInstalled ? '  [installed]' : ''}`)
+    if (entry.npm) lines.push(`   npm: ${entry.npm}${entry.version ? `@${entry.version}` : ''}`)
+    else lines.push('   npm: (not published — GitHub source)')
+    if (entry.install) lines.push(`   install: ${entry.install}`)
+    if (entry.description) lines.push(`   ${oneLine(entry.description, 150)}`)
+  })
+  if (ambiguous) {
+    lines.push('', 'Same name has several owners. Disambiguate with owner or a full spec, e.g. owner="wqty123".')
+  }
+  return { text: lines.join('\n') }
+}
+
+/**
+ * `plugin_resolve`: produce the install plan without mutating anything.
+ */
+export async function pluginResolve(ctx, manager, options, args) {
+  if (!manager) return { text: 'The pluginManager service is not mounted in this profile; resolve is unavailable.' }
+  const catalog = await catalogFor(options, args?.refresh === true)
+  const plan = await resolveTarget(ctx, manager, String(args?.target ?? ''), {
+    owner: typeof args?.owner === 'string' ? args.owner : undefined,
+    version: typeof args?.version === 'string' ? args.version : undefined,
+    registry: typeof args?.registry === 'string' && args.registry !== '' ? args.registry : options.registry,
+    catalog: catalog.entries,
+  })
+  return { text: formatPlan(plan, 'resolve') }
+}
+
+/**
+ * `plugin_install`: resolve, install through the manager, verify, and report
+ * whether a refresh or restart is needed.
+ */
+export async function pluginInstall(ctx, manager, options, args) {
+  if (!manager) return { text: 'The pluginManager service is not mounted in this profile; install is unavailable.' }
+  try {
+    const catalog = await catalogFor(options, args?.refresh === true)
+    const plan = await resolveTarget(ctx, manager, String(args?.target ?? ''), {
+      owner: typeof args?.owner === 'string' ? args.owner : undefined,
+      version: typeof args?.version === 'string' ? args.version : undefined,
+      registry: typeof args?.registry === 'string' && args.registry !== '' ? args.registry : options.registry,
+      catalog: catalog.entries,
+    })
+    if (plan.kind === 'ambiguous') return { text: formatPlan(plan, 'install') }
+
+    const lines = [formatPlan(plan, 'install'), '']
+    const logLines = []
+    let packageName = plan.name
+    let steps = []
+    let application = 'unknown'
+
+    if (plan.kind === 'github') {
+      const result = await installGithubSource(manager, plan, {
+        githubProxy: options.githubProxy,
+        skipBuild: args?.skipBuild === true,
+        log: (line) => {
+          logLines.push(line)
+          if (logLines.length > 12) logLines.shift()
+        },
+      })
+      packageName = result.packageName
+      steps = result.steps
+      application = result.summary.application
+      lines.push(`install: ${result.summary.application} (${result.summary.stage})`)
+      if (result.summary.error) lines.push(`error: ${result.summary.error}`)
+      if (steps.length > 0) lines.push(`steps: ${steps.join(' → ')}`)
+    } else {
+      const { summary } = await installRegistry(manager, plan)
+      application = summary.application
+      if (packageName === null && summary.bundle) packageName = summary.bundle
+      lines.push(`install: ${summary.application} (${summary.stage})`)
+      if (summary.error) lines.push(`error: ${summary.error}`)
+      if (summary.pendingBuilds.length > 0) {
+        lines.push(`pending build scripts (needs approval): ${summary.pendingBuilds.join(', ')}`)
+      }
+    }
+
+    if (packageName) {
+      const health = await verifyInstall(ctx, manager, packageName)
+      lines.push('', 'verification:')
+      if (health.entry) {
+        const phase = health.entry.fiberPhase ?? 'unknown'
+        const flag = phase === 'active' ? 'OK' : phase === 'failed' ? 'FAILED' : phase
+        lines.push(`- loader entry ${health.entry.entryId}: enabled=${health.entry.enabled} fiberPhase=${phase} [${flag}]`)
+      } else {
+        lines.push('- loader entry: not found — the host half may need a restart to mount')
+      }
+      if (health.bundle) {
+        lines.push(`- bundle: ${health.bundle.name}@${health.bundle.version ?? '?'} enabled=${health.bundle.enabled}`)
+      }
+      lines.push(`- package: ${packageName}${health.hasClient ? ` (client half via ${health.clientSource})` : ' (host-only)'}`)
+      const next = []
+      if (application === 'restart-required') {
+        next.push('restart DSH fully: replacing an already-mounted plugin cannot be hot-swapped safely')
+      }
+      if (health.entry?.fiberPhase === 'failed') next.push('host half failed to load; inspect the harness log for the error')
+      if (health.hasClient && application !== 'restart-required') next.push('client half exists: refresh the GUI (Ctrl+R) to load it')
+      if (health.entry?.fiberPhase === 'active' && !health.hasClient && application !== 'restart-required') {
+        next.push('host-only: no GUI refresh required')
+      }
+      if (next.length > 0) lines.push('', `next: ${next.join('; ')}`)
+    }
+    if (logLines.length > 0) lines.push('', `build log (tail):\n  ${logLines.join('\n  ')}`)
+    return { text: lines.join('\n') }
+  } catch (error) {
+    return { text: `plugin_install failed: ${error?.message ?? String(error)}` }
+  }
+}
+
+/**
+ * `plugin_status`: third-party bundles and their loader entries.
+ */
+export async function pluginStatus(ctx, manager, options, args) {
+  if (!manager) return { text: 'The pluginManager service is not mounted in this profile; status is unavailable.' }
+  const filter = String(args?.query ?? '').trim().toLowerCase()
+  const lines = []
+  try {
+    const bundles = await manager.listBundles()
+    const installed = bundles.filter((bundle) => bundle.installed && !String(bundle.name).startsWith('@deepseek-ai/'))
+    lines.push(`installed third-party bundles: ${installed.length}`)
+    for (const bundle of installed) {
+      if (filter !== '' && !String(bundle.name).toLowerCase().includes(filter)) continue
+      lines.push(`- ${bundle.name}@${bundle.version ?? '?'} enabled=${bundle.enabled} optional=${bundle.optional}`)
+      const rows = Array.isArray(bundle.rows) ? bundle.rows.filter((row) => row.entryId) : []
+      if (rows.length > 0) lines.push(`  rows: ${rows.map((row) => `${row.entryId}(${row.moduleName})`).join(', ')}`)
+    }
+  } catch (error) {
+    lines.push(`bundle inventory failed: ${error.message}`)
+  }
+  try {
+    const plugins = await manager.listPlugins()
+    const thirdParty = plugins.filter((plugin) => {
+      const name = String(plugin.moduleName ?? '')
+      return name !== '' && !name.startsWith('@deepseek-ai/') && !name.startsWith('file:///')
+    })
+    lines.push('', `third-party loader entries: ${thirdParty.length}`)
+    for (const plugin of thirdParty) {
+      if (filter !== '' && !plugin.moduleName.toLowerCase().includes(filter)) continue
+      lines.push(`- ${plugin.entryId}: ${plugin.moduleName} enabled=${plugin.enabled} fiberPhase=${plugin.fiberPhase ?? 'null'}`)
+    }
+  } catch (error) {
+    lines.push(`plugin inventory failed: ${error.message}`)
+  }
+  return { text: lines.join('\n') }
+}
+
+/**
+ * Render a resolution plan as compact text.
+ *
+ * @param {any} plan
+ * @param {'resolve' | 'install'} mode
+ * @returns {string}
+ */
+export function formatPlan(plan, mode) {
+  if (plan.kind === 'ambiguous') {
+    const lines = [`"${plan.name}" is ambiguous: ${plan.candidates.length} catalog entries share this name.`, '']
+    plan.candidates.forEach((candidate, index) => {
+      lines.push(
+        `${index + 1}. owner=${candidate.owner || '?'}  ★${stars(candidate.stars)}  ${
+          candidate.npm ? `npm: ${candidate.npm}` : 'npm: (GitHub source)'
+        }`,
+      )
+      if (candidate.install) lines.push(`   install: ${candidate.install}`)
+      if (candidate.description) lines.push(`   ${oneLine(candidate.description, 130)}`)
+    })
+    lines.push('', `Re-run ${mode === 'install' ? 'plugin_install' : 'plugin_resolve'} with owner="<owner>" or a full spec.`)
+    return lines.join('\n')
+  }
+  const lines = []
+  const runtime = plan.runtime ?? 'unknown'
+  lines.push(`target kind: ${plan.kind}   running DSH: ${runtime}`)
+  if (plan.name) lines.push(`package: ${plan.name}${plan.version ? `@${plan.version}` : ''}`)
+  if (plan.spec) lines.push(`install spec: ${plan.spec}`)
+  if (plan.registry) lines.push(`registry: ${plan.registry}`)
+  else lines.push('registry: pnpm default (no first registry named)')
+  if (plan.latest && plan.latest !== plan.version) lines.push(`latest published: ${plan.latest} (not used: incompatible or newer)`)
+  if (plan.kind === 'github') {
+    lines.push(`source: github.com/${plan.repo}${plan.ref ? ` @ ${plan.ref}` : ''}${plan.subpath ? ` (${plan.subpath})` : ''}`)
+  }
+  if (plan.catalogEntry) {
+    lines.push(`catalog: ${plan.catalogEntry.name} by ${plan.catalogEntry.owner || '?'} ★${stars(plan.catalogEntry.stars)}`)
+    if (plan.catalogEntry.description) lines.push(`about: ${oneLine(plan.catalogEntry.description, 160)}`)
+  }
+  if (Array.isArray(plan.rejected) && plan.rejected.length > 0) {
+    lines.push('skipped versions:')
+    for (const item of plan.rejected) lines.push(`- ${item.version}: ${item.reason}`)
+  }
+  if (Array.isArray(plan.notes) && plan.notes.length > 0) {
+    lines.push('notes:')
+    for (const note of plan.notes) lines.push(`- ${note}`)
+  }
+  if (mode === 'install') lines.push('', 'proceeding with install…')
+  return lines.join('\n')
+}
+
+export { baseName }

package/logic/catalog.js

@@ -0,0 +1,281 @@
+// Reloadable module: every local dependency is imported with this module's own
+// `?v=` query, so a cache-busted entry import reloads the whole graph together.
+const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
+const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
+const { cacheDir, dirExists, fetchBuffer, fetchJson, oneLine, readJson, writeJson } = await import(__q('util.js'))
+/**
+ * The community plugin catalog: fetch, normalize, cache, and search it.
+ *
+ * The curated list is the same one the in-app market reads. Its home is a
+ * GitHub Pages URL, which is slow and sometimes unreachable from mainland
+ * China, so the primary source is the `dsh-plugin-catalog` npm package: every
+ * npm mirror carries it, and the `dist.tarball` field keeps the download on
+ * whichever registry answered. The origin URL stays as the last fallback for
+ * deployments that cannot reach a registry.
+ *
+ * Same display names repeat across owners, which is why search keeps the owner
+ * in view and reports ambiguity instead of guessing.
+ *
+ * @module dsh-plugin-resolver/lib/catalog
+ */
+
+import { gunzipSync } from 'node:zlib'
+import path from 'node:path'
+
+const DEFAULT_CATALOG_URL = 'https://awesome-dsh-plugin.com/plugins.json'
+const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000
+const CATALOG_PACKAGE = 'dsh-plugin-catalog'
+const DEFAULT_CATALOG_REGISTRIES = ['https://registry.npmmirror.com', 'https://registry.npmjs.org']
+
+/**
+ * Load the catalog: fresh cache first, then the npm carrier, then the origin.
+ *
+ * @param {{catalogUrl?: string, catalogTtlMs?: number, catalogRegistries?: string[], registry?: string}} options
+ * @param {{force?: boolean}} [control]
+ * @returns {Promise<{entries: CatalogEntry[], fetchedAt: number, fromCache: boolean, source: string, version?: string, error?: string}>}
+ */
+export async function loadCatalog(options, control = {}) {
+  const file = path.join(cacheDir(), 'catalog.json')
+  const ttl = options.catalogTtlMs ?? DEFAULT_TTL_MS
+  if (!control.force) {
+    const cached = await readJson(file)
+    if (cached && Array.isArray(cached.entries) && Number.isFinite(cached.fetchedAt)) {
+      if (Date.now() - cached.fetchedAt < ttl) {
+        return {
+          entries: cached.entries,
+          fetchedAt: cached.fetchedAt,
+          fromCache: true,
+          source: typeof cached.source === 'string' ? cached.source : 'cache',
+          version: cached.version,
+        }
+      }
+    }
+  }
+
+  const attempts = []
+  const registries = [
+    ...(Array.isArray(options.catalogRegistries) ? options.catalogRegistries : []),
+    options.registry,
+    ...DEFAULT_CATALOG_REGISTRIES,
+  ].filter((value, index, list) => typeof value === 'string' && value !== '' && list.indexOf(value) === index)
+
+  for (const registry of registries) {
+    try {
+      const carried = await catalogFromPackage(registry)
+      const entries = normalizeCatalog(carried.raw)
+      const fetchedAt = Date.now()
+      await writeJson(file, { fetchedAt, source: 'npm', version: carried.version, entries })
+      return { entries, fetchedAt, fromCache: false, source: 'npm', version: carried.version }
+    } catch (error) {
+      attempts.push(`${registry}: ${error.message}`)
+    }
+  }
+
+  const urls = [options.catalogUrl, DEFAULT_CATALOG_URL].filter(
+    (value, index, list) => typeof value === 'string' && value !== '' && list.indexOf(value) === index,
+  )
+  for (const url of urls) {
+    try {
+      const raw = await fetchJson(url, { timeoutMs: 180_000 })
+      const entries = normalizeCatalog(raw)
+      const fetchedAt = Date.now()
+      await writeJson(file, { fetchedAt, source: 'url', entries })
+      return { entries, fetchedAt, fromCache: false, source: 'url' }
+    } catch (error) {
+      attempts.push(`${url}: ${error.message}`)
+    }
+  }
+
+  return {
+    entries: [],
+    fetchedAt: 0,
+    fromCache: false,
+    source: 'unavailable',
+    error: `catalog unavailable (${attempts.join(' | ')})`,
+  }
+}
+
+/**
+ * Read `plugins.json` out of the published catalog package via one registry.
+ *
+ * @param {string} registry
+ * @returns {Promise<{raw: any, version: string | null}>}
+ */
+async function catalogFromPackage(registry) {
+  const base = registry.replace(/\/+$/, '')
+  const meta = await fetchJson(`${base}/${CATALOG_PACKAGE}/latest`, { timeoutMs: 20_000 })
+  const version = typeof meta?.version === 'string' ? meta.version : null
+  const tarball = typeof meta?.dist?.tarball === 'string' ? meta.dist.tarball : null
+  if (tarball === null) throw new Error('package metadata names no tarball')
+  const bytes = await fetchBuffer(tarball, { timeoutMs: 90_000 })
+  const file = fileFromTarball(bytes, 'package/plugins.json')
+  if (file === null) throw new Error('catalog package carries no package/plugins.json')
+  return { raw: JSON.parse(file.toString('utf8')), version }
+}
+
+/**
+ * Extract one regular file from a gzipped tar.
+ *
+ * @param {Buffer} gz
+ * @param {string} wanted
+ * @returns {Buffer | null}
+ */
+export function fileFromTarball(gz, wanted) {
+  const buffer = gunzipSync(gz)
+  const BLOCK = 512
+  let offset = 0
+  while (offset + BLOCK <= buffer.length) {
+    const name = buffer
+      .toString('utf8', offset, offset + 100)
+      .replace(/\0[\s\S]*$/, '')
+    if (name === '') break
+    const rawSize = buffer
+      .toString('ascii', offset + 124, offset + 136)
+      .replace(/\0[\s\S]*$/, '')
+      .trim()
+    const size = Number.parseInt(rawSize, 8)
+    if (!Number.isFinite(size) || size < 0) break
+    const type = String.fromCharCode(buffer[offset + 156] ?? 0)
+    offset += BLOCK
+    if ((type === '0' || type === '\0') && name === wanted) {
+      return buffer.subarray(offset, offset + size)
+    }
+    offset += Math.ceil(size / BLOCK) * BLOCK
+  }
+  return null
+}
+
+/**
+ * Normalize one raw catalog payload.
+ *
+ * @typedef {object} CatalogEntry
+ * @property {string} name display name, possibly `name#subpath`
+ * @property {string} owner repository owner
+ * @property {string} url repository URL
+ * @property {string | null} npm published npm package name
+ * @property {string | null} version catalogued version
+ * @property {number} stars
+ * @property {string | null} install the documented install command
+ * @property {string} description one-line, English preferred
+ * @property {string} category
+ * @property {string} added
+ *
+ * @param {any} raw
+ * @returns {CatalogEntry[]}
+ */
+export function normalizeCatalog(raw) {
+  const list = Array.isArray(raw) ? raw : raw?.plugins ?? raw?.entries ?? []
+  const entries = []
+  for (const item of list) {
+    if (!item || typeof item.name !== 'string' || item.name === '') continue
+    entries.push({
+      name: item.name,
+      owner: typeof item.owner === 'string' ? item.owner : '',
+      url: typeof item.url === 'string' ? item.url : '',
+      npm: typeof item.npm === 'string' && item.npm !== '' ? item.npm : null,
+      version: typeof item.version === 'string' && item.version !== '' ? item.version : null,
+      stars: Number(item.stars) || 0,
+      install: typeof item.install === 'string' ? item.install : null,
+      description: oneLine(item.description?.en ?? item.description?.zh ?? '', 160),
+      category: typeof item.category === 'string' ? item.category : '',
+      added: typeof item.added === 'string' ? item.added : '',
+    })
+  }
+  return entries
+}
+
+/** Base display name without the monorepo subpath suffix. */
+export function baseName(entry) {
+  const at = entry.name.indexOf('#')
+  return at === -1 ? entry.name : entry.name.slice(0, at)
+}
+
+/**
+ * Rank catalog entries for one query.
+ *
+ * Scoring prefers an exact display name, then a shared prefix, then tokens in
+ * the name/owner/description; star count only breaks ties. Same-name results
+ * are all returned so the caller can present the ambiguity instead of guessing.
+ *
+ * @param {CatalogEntry[]} entries
+ * @param {string} query
+ * @param {{limit?: number, installed?: Set<string>}} [options]
+ * @returns {{matches: Array<{entry: CatalogEntry, score: number, installed: boolean}>, ambiguous: boolean}}
+ */
+export function searchCatalog(entries, query, options = {}) {
+  const limit = Math.max(1, Math.min(options.limit ?? 8, 25))
+  const raw = String(query ?? '').trim().toLowerCase()
+  if (raw === '') return { matches: [], ambiguous: false }
+  const tokens = raw.split(/[\s/]+/).filter(Boolean)
+  const matches = []
+  for (const entry of entries) {
+    const name = entry.name.toLowerCase()
+    const base = baseName(entry).toLowerCase()
+    const owner = entry.owner.toLowerCase()
+    const npmName = (entry.npm ?? '').toLowerCase()
+    const description = entry.description.toLowerCase()
+    let score = 0
+    if (base === raw) score = 1000
+    else if (name === raw) score = 990
+    else if (base.startsWith(raw)) score = 700
+    else if (name.startsWith(raw)) score = 690
+    else if (npmName !== '' && npmName === raw) score = 800
+    else if (name.includes(raw)) score = 400
+    else if (owner === raw) score = 350
+    else if (description.includes(raw)) score = 120
+    else {
+      let tokenHits = 0
+      for (const token of tokens) {
+        if (name.includes(token)) tokenHits += 1
+        else if (owner.includes(token)) tokenHits += 0.5
+        else if (description.includes(token)) tokenHits += 0.25
+      }
+      if (tokenHits === 0) continue
+      score = 200 + tokenHits * 20
+    }
+    score += Math.min(entry.stars, 10_000) / 100_000
+    if (entry.npm && options.installed?.has(entry.npm)) score += 0.5
+    matches.push({ entry, score, installed: Boolean(entry.npm && options.installed?.has(entry.npm)) })
+  }
+  matches.sort((a, b) => b.score - a.score || b.entry.stars - a.entry.stars)
+  const limited = matches.slice(0, limit)
+  const names = new Map()
+  for (const { entry } of limited) {
+    const key = baseName(entry).toLowerCase()
+    names.set(key, (names.get(key) ?? 0) + 1)
+  }
+  const ambiguous = [...names.values()].some((count) => count > 1)
+  return { matches: limited, ambiguous }
+}
+
+/** Extract `github:owner/repo#...` from a documented install command. */
+export function githubSpecOf(entry) {
+  if (entry.install) {
+    const match = /github:[^\s"']+/.exec(entry.install)
+    if (match) return match[0]
+  }
+  const urlMatch = /^https:\/\/github\.com\/([^/]+)\/([^/]+)(?:\/tree\/[^/]+\/(.+))?/.exec(entry.url)
+  if (!urlMatch) return null
+  const subpath = urlMatch[3] ? `#path:/${urlMatch[3]}` : ''
+  return `github:${urlMatch[1]}/${urlMatch[2]}${subpath}`
+}
+
+/** Extract the repository slug (`owner/repo`) for a catalog entry. */
+export function repoSlugOf(entry) {
+  const match = /github\.com\/([^/]+)\/([^/]+)/.exec(entry.url ?? '')
+  if (!match) return null
+  return `${match[1]}/${match[2].replace(/\.git$/, '')}`
+}
+
+/** Repository checkout directory for a GitHub source build. */
+export function sourceDirOf(repoSlug) {
+  const safe = repoSlug.replace(/[^A-Za-z0-9._-]+/g, '__')
+  const home = process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : ''
+  return path.join(home, 'plugin-sources', safe)
+}
+
+/** Whether a repository checkout already exists. */
+export function hasSourceCheckout(dir) {
+  return dir !== '' && dirExists(dir)
+}
+