dsh-plugin-upgrader 1.0.0 → 1.0.2

package/src/lib/overview.js

@@ -1,108 +0,0 @@
-/**
- * The overview payload the Versions tab renders.
- *
- * One request answers everything the tab needs — installed bundles, their
- * published versions, which of them are upgradable — because a per-bundle
- * request would turn one page open into a dozen round trips.
- *
- * @module dsh-plugin-upgrader/lib/overview
- */
-
-import { compareVersions } from './version.js'
-import { repoUrlOf } from './repo.js'
-import { inlineIcon, pickText, registryBase, sourceKind } from './bundle.js'
-import { cachedTags, fetchPackument, shapePackument } from './registry.js'
-
-/** Inline data-URL icons above this size are dropped from the overview payload. */
-const INLINE_ICON_LIMIT = 2048
-
-/**
- * Build the overview the tab renders.
- * @param {any} ctx - the plugin context.
- * @param {Map<string, { at: number, data: any }>} cache - packument cache.
- * @param {Map<string, { at: number, tags?: Set<string>, error?: string }>} tagCache - repository tag cache.
- * @param {{ force?: boolean, locale?: 'zh' | 'en' }} options - refresh + language.
- * @returns {Promise<any>} the overview payload.
- */
-export async function buildOverview(ctx, cache, tagCache, options) {
-  const manager = ctx.get('pluginManager', false)
-  if (manager === undefined || manager === null) {
-    throw Object.assign(new Error('plugin manager unavailable'), { status: 503 })
-  }
-  const [bundles, registries] = await Promise.all([manager.listBundles(), manager.registries()])
-  const base = registryBase(registries)
-  const locale = options.locale === 'zh' ? 'zh' : 'en'
-
-  const rows = await Promise.all(
-    bundles.filter((bundle) => bundle.installed === true).map(async (bundle) => {
-      const kind = sourceKind(bundle.source)
-      /** Official rows live inside the installation and cannot be replaced. */
-      const managed = bundle.availability === 'profile' && bundle.installed === true
-      const entry = {
-        name: bundle.name,
-        version: bundle.version,
-        official: bundle.official === true,
-        availability: bundle.availability,
-        installed: bundle.installed === true,
-        enabled: bundle.enabled === true,
-        removable: bundle.removable === true,
-        managed,
-        source: bundle.source,
-        kind,
-        title: pickText(bundle.meta?.title, locale) ?? bundle.name,
-        description: pickText(bundle.meta?.description ?? bundle.description, locale),
-        icon: inlineIcon(bundle.meta?.icon, INLINE_ICON_LIMIT),
-        readOnlyReason: bundle.readOnlyReason,
-        error: bundle.error ?? null,
-        latest: undefined,
-        repoUrl: undefined,
-        upgradable: false,
-        versions: [],
-        tags: {},
-        totalVersions: 0,
-        versionError: undefined,
-      }
-      if (!managed || bundle.version === undefined) {
-        entry.versionError = managed ? 'version unknown' : 'not a profile-managed package'
-        return entry
-      }
-      if (kind !== 'registry' && kind !== 'unknown') {
-        entry.versionError = `${kind} source: no registry history`
-        return entry
-      }
-      const { data, error } = await fetchPackument(base, bundle.name, cache, options.force === true)
-      if (error !== undefined || data === undefined) {
-        entry.versionError = error ?? 'registry lookup failed'
-        return entry
-      }
-      const repoUrl = repoUrlOf(data)
-      const tagNames = repoUrl === undefined
-        ? undefined
-        : await cachedTags(repoUrl, tagCache, options.force === true)
-      const shaped = shapePackument(bundle.name, data, bundle.version, tagNames)
-      entry.latest = shaped.latest
-      entry.repoUrl = shaped.repoUrl
-      entry.versions = shaped.versions
-      entry.tags = shaped.tags
-      entry.totalVersions = shaped.totalVersions ?? shaped.versions.length
-      entry.versionError = shaped.versionError
-      entry.upgradable =
-        entry.latest !== undefined && compareVersions(entry.latest, bundle.version) > 0
-      return entry
-    }),
-  )
-
-  rows.sort((left, right) => {
-    if (left.upgradable !== right.upgradable) return left.upgradable ? -1 : 1
-    if (left.managed !== right.managed) return left.managed ? -1 : 1
-    return left.name.localeCompare(right.name)
-  })
-
-  return {
-    generatedAt: Date.now(),
-    registry: base,
-    registries,
-    runtimeVersion: ctx.get('dshVersion', false) ?? null,
-    bundles: rows,
-  }
-}

package/src/lib/registry.js

@@ -1,188 +0,0 @@
-/**
- * Registry and GitHub lookups.
- *
- * The browser half cannot reach npm reliably (CORS, private registries, tokens)
- * and cannot reach the GitHub API at all without leaking rate limits to every
- * page load, so both lookups happen here, behind a cache.
- *
- * @module dsh-plugin-upgrader/lib/registry
- */
-
-import { compareVersions, releasePathOf } from './version.js'
-import { githubUrlOf } from './repo.js'
-
-/** How long one registry packument stays fresh. */
-export const PACKUMENT_TTL_MS = 5 * 60 * 1000
-
-/** Registry lookups must not hang a page render. */
-export const PACKUMENT_TIMEOUT_MS = 10 * 1000
-
-/** Version lists are capped so one huge package cannot flood the tab. */
-export const MAX_VERSIONS = 80
-
-/**
- * How long one repository's tag list stays fresh. The GitHub API allows 60
- * unauthenticated requests an hour and one tag list costs a request per 100
- * tags, so this is deliberately much longer than the packument TTL.
- */
-export const TAGS_TTL_MS = 30 * 60 * 1000
-
-/** A failed tag lookup is retried sooner than a good one is refreshed. */
-export const TAGS_RETRY_MS = 5 * 60 * 1000
-
-/** Tag lookups must not hang a page render. */
-export const TAGS_TIMEOUT_MS = 8 * 1000
-
-/**
- * Fetch one package's packument, with a short-lived cache.
- * @param {string} base - registry base URL.
- * @param {string} packageName - package name.
- * @param {Map<string, { at: number, data: any }>} cache - shared cache.
- * @param {boolean} force - bypass a fresh cache entry.
- * @returns {Promise<{ data?: any, error?: string }>} the document or a reason.
- */
-export async function fetchPackument(base, packageName, cache, force) {
-  const key = `${base}|${packageName}`
-  const hit = cache.get(key)
-  if (force !== true && hit !== undefined && Date.now() - hit.at < PACKUMENT_TTL_MS) {
-    return { data: hit.data }
-  }
-  const url = `${base}/${packageName.startsWith('@') ? '@' + encodeURIComponent(packageName.slice(1)) : encodeURIComponent(packageName)}`
-  try {
-    const response = await fetch(url, {
-      headers: { accept: 'application/json' },
-      signal: AbortSignal.timeout(PACKUMENT_TIMEOUT_MS),
-    })
-    if (!response.ok) {
-      return { error: `registry ${response.status}${response.status === 404 ? ' (not found)' : ''}` }
-    }
-    const data = await response.json()
-    cache.set(key, { at: Date.now(), data })
-    return { data }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    return { error: `registry unreachable: ${message}` }
-  }
-}
-
-/**
- * Read a repository's tag names from the GitHub API.
- *
- * The git ref advertisement (`/info/refs?service=git-upload-pack`) would avoid
- * the rate limit but stalls for most repositories behind this network, while the
- * REST list answers in well under a second. Only the first page is read: the
- * version list itself is capped at 80 newest rows, and tags are ordered newest
- * first, so a repository with more than 100 tags still resolves every row that
- * can be shown.
- *
- * @param {string} repoUrl - the repository URL.
- * @param {number} at - the time the lookup started.
- * @returns {Promise<{ tags?: Set<string>, error?: string, at: number }>} the outcome.
- */
-export async function fetchTags(repoUrl, at) {
-  const match = /^https?:\/\/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?\/?$/.exec(repoUrl)
-  if (match === null) return { error: 'not a github repository', at }
-  const [, owner, repo] = match
-  try {
-    const response = await fetch(
-      `https://api.github.com/repos/${owner}/${repo}/tags?per_page=100`,
-      {
-        headers: { accept: 'application/vnd.github+json', 'user-agent': 'dsh-plugin-upgrader' },
-        signal: AbortSignal.timeout(TAGS_TIMEOUT_MS),
-      },
-    )
-    if (!response.ok) {
-      const suffix = response.status === 403 || response.status === 429 ? ' (rate limited)' : ''
-      return { error: `github ${response.status}${suffix}`, at }
-    }
-    const list = await response.json()
-    if (!Array.isArray(list)) return { error: 'github returned no tag list', at }
-    const tags = new Set()
-    for (const entry of list) {
-      if (typeof entry?.name === 'string') tags.add(entry.name)
-    }
-    return { tags, at }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    return { error: `github unreachable: ${message}`, at }
-  }
-}
-
-/**
- * The tag names of a repository, cached.
- *
- * A tag list is the only way to know whether `/releases/tag/v<version>` exists.
- * A failed lookup is cached too, but for less time: the tab must still render
- * (with repository-level links) while GitHub is rate limiting.
- *
- * @param {string} repoUrl - the repository URL.
- * @param {Map<string, { at: number, tags?: Set<string>, error?: string }>} cache - shared cache.
- * @param {boolean} force - bypass a fresh cache entry.
- * @returns {Promise<Set<string> | undefined>} the tag names, or undefined when unknown.
- */
-export async function cachedTags(repoUrl, cache, force) {
-  const hit = cache.get(repoUrl)
-  if (hit !== undefined && force !== true) {
-    const ttl = hit.tags === undefined ? TAGS_RETRY_MS : TAGS_TTL_MS
-    if (Date.now() - hit.at < ttl) return hit.tags
-  }
-  const outcome = await fetchTags(repoUrl, Date.now())
-  cache.set(repoUrl, outcome)
-  return outcome.tags
-}
-
-/**
- * Trim one packument down to what the tab renders.
- * @param {string} packageName - the package asked for.
- * @param {any} packument - the full registry document.
- * @param {string | undefined} installedVersion - the version in the profile.
- * @param {Set<string> | undefined} tagNames - the repository's tag names, when known.
- * @returns {{
- *   latest?: string,
- *   repoUrl?: string,
- *   versions: any[],
- *   tags: Record<string, string>,
- *   totalVersions?: number,
- *   versionError?: string,
- * }} the slice.
- */
-export function shapePackument(packageName, packument, installedVersion, tagNames) {
-  const versionsRecord = packument?.versions
-  if (versionsRecord === null || typeof versionsRecord !== 'object') {
-    return { versions: [], tags: {}, versionError: 'registry returned no versions' }
-  }
-  const tags = packument['dist-tags'] !== null && typeof packument['dist-tags'] === 'object'
-    ? packument['dist-tags']
-    : {}
-  const newest = tags.latest
-  const timeRecord = packument.time !== null && typeof packument.time === 'object' ? packument.time : {}
-  const names = Object.keys(versionsRecord)
-  const newestManifest = typeof newest === 'string' ? versionsRecord[newest] : undefined
-  const repoUrl = githubUrlOf(packument, newestManifest)
-  const rows = names.map((version) => {
-    const manifest = versionsRecord[version] ?? {}
-    const engine = manifest?.engines?.dsh ?? manifest?.dsh?.engines?.dsh
-    return {
-      version,
-      time: typeof timeRecord[version] === 'string' ? timeRecord[version] : undefined,
-      deprecated: typeof manifest.deprecated === 'string' ? manifest.deprecated : undefined,
-      engine: typeof engine === 'string' ? engine : undefined,
-      current: version === installedVersion,
-      latest: version === newest,
-      url: repoUrl === undefined ? undefined : releasePathOf(tagNames, version),
-    }
-  })
-  rows.sort((left, right) => compareVersions(right.version, left.version))
-  const kept = rows.slice(0, MAX_VERSIONS)
-  const currentRow = rows.find((row) => row.current === true)
-  if (currentRow !== undefined && !kept.includes(currentRow)) kept.push(currentRow)
-  return {
-    latest: typeof newest === 'string' ? newest : undefined,
-    repoUrl,
-    versions: kept,
-    tags: Object.fromEntries(
-      Object.entries(tags).filter(([, value]) => typeof value === 'string'),
-    ),
-    totalVersions: rows.length,
-  }
-}

package/src/lib/repo.js

@@ -1,91 +0,0 @@
-/**
- * Repository-URL normalisation.
- *
- * A registry packument can declare its `repository` in half a dozen shapes, and
- * the tab only ever wants one thing out of it: the https URL of the project
- * page. Turning that into data is pure work, so it lives here rather than in
- * the request handler.
- *
- * @module dsh-plugin-upgrader/lib/repo
- */
-
-/**
- * Turn any of the shapes npm allows for `repository` into an https URL.
- * Handles `owner/repo`, `github:owner/repo`, `git@host:owner/repo.git`,
- * `git+https://…`, and plain URLs; returns `undefined` for anything else.
- * @param {unknown} raw - the manifest field.
- * @returns {string | undefined} an https URL without a trailing slash.
- */
-export function normalizeRepoUrl(raw) {
-  const text = typeof raw === 'string'
-    ? raw
-    : raw !== null && typeof raw === 'object' && typeof (/** @type {any} */ (raw).url) === 'string'
-      ? /** @type {any} */ (raw).url
-      : undefined
-  if (text === undefined) return undefined
-  let value = text.trim()
-  if (value === '') return undefined
-
-  const shorthand = /^(?:github:)?([\w.-]+\/[\w.-]+)$/.exec(value)
-  if (shorthand !== null) value = `https://github.com/${shorthand[1]}`
-  else if (value.startsWith('git@')) value = `https://${value.slice(4).replace(':', '/')}`
-  else if (value.startsWith('ssh://git@')) value = `https://${value.slice('ssh://git@'.length)}`
-  else value = value.replace(/^git\+/, '')
-
-  value = value.replace(/\.git$/, '').replace(/\/+$/, '')
-  try {
-    const parsed = new URL(value)
-    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return undefined
-    parsed.hash = ''
-    parsed.search = ''
-    return parsed.toString().replace(/\/+$/, '')
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * Is this a github.com URL?
- * @param {string} url - an absolute URL.
- * @returns {boolean} whether the host is GitHub.
- */
-export function isGithubUrl(url) {
-  try {
-    return /^(www\.)?github\.com$/.test(new URL(url).hostname)
-  } catch {
-    return false
-  }
-}
-
-/**
- * The project page a user would recognise as "the plugin's GitHub".
- * `repository` wins; `homepage`/`bugs` are only used when they point at GitHub,
- * so a marketing site never stands in for the source link.
- * @param {any} packument - the registry document.
- * @param {{ repository?: unknown, homepage?: unknown, bugs?: unknown } | undefined} manifest - one version manifest.
- * @returns {string | undefined} an https GitHub URL.
- */
-export function githubUrlOf(packument, manifest) {
-  const direct = [
-    normalizeRepoUrl(manifest?.repository),
-    normalizeRepoUrl(packument?.repository),
-  ].find((url) => url !== undefined && url !== null && isGithubUrl(url))
-  if (direct !== undefined) return direct
-  const fallbacks = [
-    normalizeRepoUrl(packument?.homepage),
-    normalizeRepoUrl(manifest?.homepage),
-    normalizeRepoUrl(packument?.bugs),
-  ]
-  return fallbacks.find((url) => url !== undefined && url !== null && isGithubUrl(url))
-}
-
-/**
- * The repository a packument points at, independent of any version row.
- * @param {any} packument - the registry document.
- * @returns {string | undefined} an https GitHub URL.
- */
-export function repoUrlOf(packument) {
-  const latest = packument?.['dist-tags']?.latest
-  const manifest = typeof latest === 'string' ? packument?.versions?.[latest] : undefined
-  return githubUrlOf(packument, manifest)
-}

package/src/lib/version.js

@@ -1,107 +0,0 @@
-/**
- * Version ordering and release-link helpers.
- *
- * Everything here is pure: no I/O, no clock, no ambient state. The host half
- * uses it to sort published versions and to decide which GitHub page a version
- * line opens, and the test suite exercises it directly.
- *
- * @module dsh-plugin-upgrader/lib/version
- */
-
-/**
- * Parse a semver string into comparable parts.
- * @param {string} value - a version like `1.2.3-rc.1`.
- * @returns {{ major: number, minor: number, patch: number, pre: string[] } | null} parts, or null.
- */
-export function parseVersion(value) {
-  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
-    String(value ?? '').trim(),
-  )
-  if (match === null) return null
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    pre: match[4] === undefined ? [] : match[4].split('.'),
-  }
-}
-
-/**
- * Compare two prerelease identifier lists, semver order.
- * @param {string[]} left - identifiers of the left version.
- * @param {string[]} right - identifiers of the right version.
- * @returns {number} negative, zero, or positive.
- */
-export function comparePre(left, right) {
-  if (left.length === 0 && right.length === 0) return 0
-  if (left.length === 0) return 1
-  if (right.length === 0) return -1
-  const length = Math.max(left.length, right.length)
-  for (let index = 0; index < length; index += 1) {
-    const a = left[index]
-    const b = right[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
-      continue
-    }
-    if (aNumeric) return -1
-    if (bNumeric) return 1
-    if (a !== b) return a < b ? -1 : 1
-  }
-  return 0
-}
-
-/**
- * Compare two versions, semver order; unparsable pairs compare equal.
- * @param {string} left - left version.
- * @param {string} right - right version.
- * @returns {number} negative when left is older.
- */
-export function compareVersions(left, right) {
-  const a = parseVersion(left)
-  const b = parseVersion(right)
-  if (a === null || b === null) return 0
-  return (
-    a.major - b.major ||
-    a.minor - b.minor ||
-    a.patch - b.patch ||
-    comparePre(a.pre, b.pre)
-  )
-}
-
-/**
- * The tag a published version was released under.
- * @param {string} version - the published version.
- * @returns {string} `v<version>` unless the version already carries the `v`.
- */
-export function tagOf(version) {
-  return version.startsWith('v') ? version : `v${version}`
-}
-
-/**
- * The GitHub path a version line opens.
- *
- * Users read a version line as "what did this release change", so the target is
- * the release page. That only resolves when the repository actually tagged the
- * version — `dsh-pet` publishes 59 versions with 8 tags — so the tag list
- * decides, and a version without a tag of its own falls back to the repository's
- * release feed rather than to a page GitHub would answer with 404. When the tag
- * list cannot be read at all (rate limit, offline) the same feed is the only
- * honest answer: guessing a tag would make one link in six a dead end.
- *
- * The result is the `releases` tail only: the row already carries the project
- * URL, and repeating it on all ~80 rows costs tens of kilobytes.
- *
- * @param {Set<string> | undefined} tags - the repository's tag names, when known.
- * @param {string} version - the published version.
- * @returns {string} a protocol-relative path such as `/releases/tag/v1.2.3`.
- */
-export function releasePathOf(tags, version) {
-  const tag = tagOf(version)
-  return tags?.has(tag) === true ? `/releases/tag/${tag}` : '/releases'
-}