@chatcode/cco-market 1.45.1

package/src/catalog-local-match.ts

@@ -0,0 +1,144 @@
+/**
+ * Catalog matching for locally linked / file: installs. Shared by the host
+ * restore route and the Market client so both refuse the same wrong guesses.
+ */
+
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/
+
+function validSubpath(subpath: string): boolean {
+  if (!/^[A-Za-z0-9_./-]+$/.test(subpath)) return false
+  return !subpath.split('/').some(seg => seg === '' || seg === '.' || seg === '..')
+}
+
+/**
+ * Keys a catalog URL contributes to restore matching.
+ * A `/tree/` entry is ONLY its exact `#path:` id — never the bare repo —
+ * so a collection-root identity cannot select a sibling subpackage.
+ */
+function catalogMatchKeys(url: string): { path: string | null; repo: string | null } {
+  const m = /^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\/tree\/[^/]+\/(.+?))?\/?$/.exec(url)
+  if (m === null || !REPO_RE.test(m[1]!)) return { path: null, repo: null }
+  const subpath = m[2] ?? null
+  if (subpath !== null && !validSubpath(subpath)) return { path: null, repo: null }
+  const repo = m[1]!.toLowerCase()
+  return subpath === null
+    ? { path: null, repo }
+    : { path: `${repo}#path:/${subpath.toLowerCase()}`, repo: null }
+}
+
+function catalogEntryMatchesHints(
+  url: string,
+  hintSet: ReadonlySet<string>,
+): boolean {
+  const keys = catalogMatchKeys(url)
+  return (keys.path !== null && hintSet.has(keys.path))
+    || (keys.repo !== null && hintSet.has(keys.repo))
+}
+
+/**
+ * The catalog entry a locally linked / file: install should restore to.
+ * Exact `#path:` identities win, then collection-root identities against
+ * root-only catalog rows, then a unique name/npm match when nothing
+ * contradicts it. A bare repo identity never selects a root row while
+ * `/tree/` siblings exist for that repo — the checkout did not say which
+ * package it is, and guessing wrong installs a different plugin.
+ * Same-named forks without identities or a matching hint stay unmatched
+ * rather than guessing; declared repo evidence that matches nothing in the
+ * catalog must not fall back to a coincidental unique name.
+ */
+export function findCatalogEntryForLocal<T extends { name: string; npm?: string | null; url: string }>(
+  plugins: readonly T[],
+  name: string,
+  identities: readonly string[] = [],
+  hints: readonly string[] = [],
+): T | null {
+  const nameKey = name.toLowerCase()
+  const byName = plugins.filter(plugin =>
+    plugin.name.toLowerCase() === nameKey
+    || (typeof plugin.npm === 'string' && plugin.npm.toLowerCase() === nameKey),
+  )
+  const identitySet = new Set(identities.map(value => value.toLowerCase()))
+  const hintSet = new Set(hints.map(value => value.toLowerCase()))
+  const treeRepos = new Set<string>()
+  for (const plugin of plugins) {
+    const keys = catalogMatchKeys(plugin.url)
+    if (keys.path !== null) treeRepos.add(keys.path.slice(0, keys.path.indexOf('#path:/')))
+  }
+  if (identitySet.size > 0) {
+    const pathHit = plugins.find(plugin => {
+      const keys = catalogMatchKeys(plugin.url)
+      return keys.path !== null && identitySet.has(keys.path)
+    })
+    if (pathHit !== undefined) return pathHit
+    const rootHit = plugins.find(plugin => {
+      const keys = catalogMatchKeys(plugin.url)
+      if (keys.repo === null || !identitySet.has(keys.repo)) return false
+      return !treeRepos.has(keys.repo) || byName.includes(plugin)
+    })
+    if (rootHit !== undefined) return rootHit
+    return null
+  }
+  if (byName.length === 1) {
+    const only = byName[0]!
+    if (hintSet.size > 0 && !catalogEntryMatchesHints(only.url, hintSet)) return null
+    return only
+  }
+  if (byName.length > 1 && hintSet.size > 0) {
+    const hinted = byName.find(plugin => catalogEntryMatchesHints(plugin.url, hintSet))
+    if (hinted !== undefined) return hinted
+  }
+  return null
+}
+
+function catalogEntriesByName<T extends { name: string; npm?: string | null }>(
+  plugins: readonly T[],
+  name: string,
+): T[] {
+  const nameKey = name.toLowerCase()
+  return plugins.filter(plugin =>
+    plugin.name.toLowerCase() === nameKey
+    || (typeof plugin.npm === 'string' && plugin.npm.toLowerCase() === nameKey),
+  )
+}
+
+export type CatalogRestoreReason = 'no-catalog' | 'repo-mismatch'
+
+/**
+ * Why a local restore was blocked, when findCatalogEntryForLocal returned
+ * null — and, when it matched, whether anything but the NAME agreed.
+ *
+ * `verified` is the difference between "put this back where it came from"
+ * and "install the catalog's plugin that happens to share this name". A
+ * local checkout with no declared repo — no git remote, no `repository`
+ * field — gives the market nothing to match on, so a unique same-named
+ * catalog entry is a guess. Usually a good one (#429: the local copy IS a
+ * tweaked copy of that entry). Not always: @liuwenji007 reported a fork of
+ * their own `dsh-humanizer` restored to a different author's plugin of the
+ * same name (#485), which is someone else's code arriving under a button
+ * labelled "restore".
+ *
+ * The match is kept, because refusing it would break the ordinary case, and
+ * the caller is told not to present it as a certainty.
+ */
+export function resolveCatalogRestore<T extends { name: string; npm?: string | null; url: string }>(
+  plugins: readonly T[],
+  name: string,
+  identities: readonly string[] = [],
+  hints: readonly string[] = [],
+): { ok: true; entry: T; verified: boolean } | { ok: false; reason: CatalogRestoreReason } {
+  const entry = findCatalogEntryForLocal(plugins, name, identities, hints)
+  if (entry !== null) {
+    // Evidence is what every other branch of the matcher requires; the
+    // name-only branch is reachable only when there is none of it.
+    const verified = identities.length > 0 || hints.length > 0
+    return { ok: true, entry, verified }
+  }
+  const byName = catalogEntriesByName(plugins, name)
+  if (byName.length === 0) return { ok: false, reason: 'no-catalog' }
+  const identitySet = new Set(identities.map(value => value.toLowerCase()))
+  const hintSet = new Set(hints.map(value => value.toLowerCase()))
+  if (identitySet.size > 0 || hintSet.size > 0) return { ok: false, reason: 'repo-mismatch' }
+  // Only ambiguous same-name rows reach here: a unique name with no evidence
+  // would have matched inside findCatalogEntryForLocal.
+  return { ok: false, reason: 'no-catalog' }
+}

package/src/catalog-npm.ts

@@ -0,0 +1,120 @@
+/**
+ * Reading the plugin catalog out of a published npm package.
+ *
+ * The catalog's own host is the thing being worked around. `plugins.json` is
+ * served from GitHub Pages, and the public GitHub proxies that make GitHub
+ * usable from mainland China refuse any hostname that is not github.com's
+ * own — measured: the project domain comes back 403. So the file cannot be
+ * carried through the same route as everything else while it lives there.
+ *
+ * Published to npm it can be. Every China npm mirror already carries it, it
+ * is the same infrastructure the plugins themselves arrive on, and it needs
+ * no service that did not already have to work. It also gains a version
+ * number, which the origin never had: a catalog build that ships bad data
+ * can be rolled back instead of only being fixed forwards.
+ *
+ * Mirrors rewrite `dist.tarball` to point at themselves, so following that
+ * field is what keeps the download on the mirror rather than bouncing back
+ * to the origin registry — verified against the Tencent mirror, which serves
+ * its own host in that field.
+ */
+
+import { gunzipSync } from 'node:zlib'
+import { marketFetch } from './net.ts'
+
+/** Long enough for a multi-megabyte tarball on a slow link, short enough to fall back. */
+const TIMEOUT_MS = 20_000
+
+/**
+ * A tar entry header, as far as this needs to read one.
+ *
+ * Written out rather than pulled from a dependency: the format is 512-byte
+ * headers with the name at offset 0 and an octal size at 124, and a reader
+ * for one known filename is shorter than the argument for adding a package
+ * to a plugin's runtime.
+ */
+const NAME_OFFSET = 0
+const NAME_LENGTH = 100
+const SIZE_OFFSET = 124
+const SIZE_LENGTH = 12
+const TYPE_OFFSET = 156
+const BLOCK = 512
+
+/**
+ * One file's bytes from a gzipped tar, or null when it is not in there.
+ *
+ * @param gz - the gzipped tarball.
+ * @param wanted - the exact entry name, npm-style (`package/plugins.json`).
+ */
+export function fileFromTarball(gz: Buffer, wanted: string): Buffer | null {
+  const buf = gunzipSync(gz)
+  let offset = 0
+  while (offset + BLOCK <= buf.length) {
+    const name = buf.toString('utf8', offset + NAME_OFFSET, offset + NAME_OFFSET + NAME_LENGTH).replace(/\0.*$/s, '')
+    // Two consecutive empty headers end a tar; one is enough to stop here.
+    if (name === '') break
+    const rawSize = buf.toString('ascii', offset + SIZE_OFFSET, offset + SIZE_OFFSET + SIZE_LENGTH).replace(/\0.*$/s, '').trim()
+    const size = Number.parseInt(rawSize, 8)
+    if (!Number.isFinite(size) || size < 0) break
+    const type = String.fromCharCode(buf[offset + TYPE_OFFSET] ?? 0)
+    offset += BLOCK
+    // '0' and NUL both mean a regular file; anything else (directories,
+    // links, pax headers) is skipped rather than mistaken for content.
+    if ((type === '0' || type === '\0') && name === wanted) {
+      return buf.subarray(offset, offset + size)
+    }
+    offset += Math.ceil(size / BLOCK) * BLOCK
+  }
+  return null
+}
+
+/** What a registry says about a package's newest release. */
+interface Packument {
+  version?: unknown
+  dist?: { tarball?: unknown }
+}
+
+/**
+ * The catalog carried by a published package, and the version it came from.
+ *
+ * The version doubles as the cache validator — a better one than an ETag,
+ * because it is meaningful to a human reading a log and it is the thing a
+ * rollback would change.
+ *
+ * @param registry - registry base, no trailing slash.
+ * @param pkg - package name.
+ * @param known - a version already held, to skip re-downloading.
+ * @returns the parsed JSON and its version, or `{ version, data: null }` when
+ *   the published version is the one already held.
+ * @throws when the package, the tarball or the file inside it cannot be read.
+ */
+export async function catalogFromPackage(
+  registry: string,
+  pkg: string,
+  known?: string,
+  /** The entry to extract; the catalog package carries `plugins.json`, companions theirs. */
+  file = 'package/plugins.json',
+): Promise<{ version: string; data: unknown | null }> {
+  const metaRes = await marketFetch(`${registry}/${encodeURIComponent(pkg)}/latest`, {
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    headers: { accept: 'application/json', 'user-agent': 'ChatCode-CLI-Market' },
+  })
+  if (!metaRes.ok) throw new Error(`HTTP ${String(metaRes.status)} reading ${pkg} metadata`)
+  const meta = (await metaRes.json()) as Packument
+  const version = typeof meta.version === 'string' ? meta.version : null
+  const tarball = typeof meta.dist?.tarball === 'string' ? meta.dist.tarball : null
+  if (version === null || tarball === null) throw new Error(`${pkg} metadata names no version or tarball`)
+  // Nothing changed, so nothing to download. The whole point of putting the
+  // catalog on a mirror is the bytes it saves; re-fetching a package we
+  // already hold would give most of them back.
+  if (known !== undefined && known === version) return { version, data: null }
+
+  // Follow `dist.tarball` rather than composing a URL. A mirror rewrites
+  // this field to its own host, and composing one would send the download
+  // back to the origin registry the region exists to avoid.
+  const tarRes = await marketFetch(tarball, { signal: AbortSignal.timeout(TIMEOUT_MS) })
+  if (!tarRes.ok) throw new Error(`HTTP ${String(tarRes.status)} reading ${pkg} tarball`)
+  const bytes = fileFromTarball(Buffer.from(await tarRes.arrayBuffer()), file)
+  if (bytes === null) throw new Error(`${pkg}@${version} carries no ${file}`)
+  return { version, data: JSON.parse(bytes.toString('utf8')) as unknown }
+}

package/src/changelog.ts

@@ -0,0 +1,282 @@
+/**
+ * Update notes: what changed between an installed version and HEAD.
+ *
+ * Every byte of GitHub data comes from the catalog side's daily probe,
+ * published as the `dsh-plugin-updates` package (origin fallback
+ * `updates.json` beside `plugins.json`). The market asks GitHub for nothing:
+ * anonymous REST quota is shared per egress IP and already unreliable behind
+ * common proxies, and this data is wanted by thousands of markets but
+ * produced perfectly well once a day by one probe.
+ *
+ * What the catalog cannot know is where each user's installed version sits,
+ * so slicing the commit tail at that boundary happens here: the same sha the
+ * update check resolved (`current`) marks where "new" begins. A tail that
+ * does not contain it means the range is wider than the tail — those are
+ * labelled recent commits rather than pretending to be an exact interval.
+ * Plugins with neither notes nor commits fall back to npm publish times, and
+ * a plugin nothing answers for gets a neutral "no notes" — absence of release
+ * notes is the ordinary condition of small plugins, not a defect.
+ */
+
+import { fileFromTarball } from './catalog-npm.ts'
+import { marketFetch } from './net.ts'
+import { activeRegion, routesFor } from './regions.ts'
+import { profileDir, readInstalled, readLockCommits } from './profile.ts'
+import { lookupRepoFromUrl, repoOfTarget } from './sources.ts'
+import { checkUpdates } from './updates.ts'
+import { loadRegistry } from './registry.ts'
+import { compatibilityEnv } from './home-paths.ts'
+
+const UPDATES_PACKAGE = 'dsh-plugin-updates'
+const UPDATES_FILE = 'package/updates.json'
+/** The origin copy sits beside plugins.json on the catalog host. */
+const ORIGIN_UPDATES = compatibilityEnv(
+  process.env,
+  'CHATCODE_CLI_MARKET_UPDATES_ORIGIN',
+  'DSHM_UPDATES_ORIGIN',
+) ?? 'https://awesome-dsh-plugin.com/updates.json'
+/** Notes are produced daily; re-checking hourly bounds staleness without churn. */
+const NOTES_TTL_MS = 60 * 60 * 1000
+const TIMEOUT_MS = 15_000
+
+export interface ReleaseNotes {
+  tag: string | null
+  name: string | null
+  publishedAt: string | null
+  url: string | null
+  body: string
+}
+
+export interface CommitNote {
+  sha: string
+  message: string
+  date: string | null
+}
+
+interface UpdatesEntry {
+  release?: ReleaseNotes | null
+  commits?: CommitNote[]
+}
+
+interface UpdatesPayload {
+  count?: number
+  updates?: Record<string, UpdatesEntry>
+}
+
+let notesCache: { at: number; data: UpdatesPayload } | null = null
+
+/**
+ * The update-notes payload from whichever route the region serves.
+ *
+ * Same source order as the catalog itself — the npm package first where one
+ * exists (its mirror reach is the reason the package exists), then the
+ * origin. Version-keyed like the catalog too: an unchanged payload costs one
+ * packument read per TTL, not a tarball.
+ */
+export async function loadUpdateNotes(force = false): Promise<UpdatesPayload> {
+  if (!force && notesCache !== null && Date.now() - notesCache.at < NOTES_TTL_MS) {
+    return notesCache.data
+  }
+  const routes = routesFor(activeRegion())
+  const attempt = async (): Promise<UpdatesPayload> => {
+    // The npm package, on the region's registry — mirrors rewrite dist.tarball
+    // to themselves, so following that field keeps the download local.
+    const metaRes = await marketFetch(`${routes.npmRegistry}/${encodeURIComponent(UPDATES_PACKAGE)}/latest`, {
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      headers: { accept: 'application/json', 'user-agent': 'ChatCode-CLI-Market' },
+    })
+    if (!metaRes.ok) throw new Error(`HTTP ${String(metaRes.status)} reading ${UPDATES_PACKAGE} metadata`)
+    const meta = await metaRes.json() as { dist?: { tarball?: unknown } }
+    const tarball = typeof meta.dist?.tarball === 'string' ? meta.dist.tarball : null
+    if (tarball === null) throw new Error(`${UPDATES_PACKAGE} names no tarball`)
+    const tarRes = await marketFetch(tarball, { signal: AbortSignal.timeout(TIMEOUT_MS) })
+    if (!tarRes.ok) throw new Error(`HTTP ${String(tarRes.status)} reading ${UPDATES_PACKAGE} tarball`)
+    const bytes = fileFromTarball(Buffer.from(await tarRes.arrayBuffer()), UPDATES_FILE)
+    if (bytes === null) throw new Error(`${UPDATES_PACKAGE} carries no ${UPDATES_FILE}`)
+    return JSON.parse(bytes.toString('utf8')) as UpdatesPayload
+  }
+  const attemptOrigin = async (): Promise<UpdatesPayload> => {
+    const res = await marketFetch(ORIGIN_UPDATES, {
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      headers: { accept: 'application/json', 'user-agent': 'ChatCode-CLI-Market' },
+    })
+    if (!res.ok) throw new Error(`HTTP ${String(res.status)} reading ${ORIGIN_UPDATES}`)
+    return await res.json() as UpdatesPayload
+  }
+  // Two independent sources, each tried twice — the same retry economics as
+  // the catalog loader, for the same transient-loss reasons.
+  let lastError: unknown = null
+  for (const attemptFn of [attempt, attemptOrigin]) {
+    for (let i = 0; i < 2; i++) {
+      try {
+        const data = await attemptFn()
+        notesCache = { at: Date.now(), data }
+        return data
+      } catch (error) {
+        lastError = error
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error('update notes unavailable')
+}
+
+/** Drop the cached payload (nothing currently invalidates it mid-process). */
+export function invalidateUpdateNotes(): void {
+  notesCache = null
+}
+
+/**
+ * Slice the commit tail at the installed sha.
+ *
+ * @returns the commits newer than `installed`, and whether the boundary was
+ *   actually found — `found === false` means the range is wider than the tail
+ *   (or history diverged), so callers must label the result "recent" rather
+ *   than exact.
+ */
+export function sliceCommitsAt(items: CommitNote[], installed: string | null): { items: CommitNote[]; found: boolean } {
+  if (installed === null) return { items, found: false }
+  const out: CommitNote[] = []
+  for (const commit of items) {
+    if (commit.sha === installed) return { items: out, found: true }
+    out.push(commit)
+  }
+  return { items: out, found: false }
+}
+
+/** The repo url key an entry's update notes live under, or null. */
+export function repoKeyOf(spec: string): string | null {
+  const repo = repoOfTarget(spec)?.split('#')[0] ?? null
+  return repo === null ? null : `https://github.com/${repo}`
+}
+
+/**
+ * Look an entry up by its catalog url.
+ *
+ * The catalog keys entries by the url as listed (author's casing preserved);
+ * the market resolves repos to lowercase (as every other consumer of
+ * `repoOfTarget` sees them). Match case-insensitively so the two sides never
+ * disagree over a capital letter.
+ */
+export function entryForRepo(payload: UpdatesPayload, key: string): UpdatesEntry | undefined {
+  const direct = payload.updates?.[key]
+  if (direct !== undefined) return direct
+  const lower = key.toLowerCase()
+  for (const [k, v] of Object.entries(payload.updates ?? {})) {
+    if (k.toLowerCase() === lower) return v
+  }
+  return undefined
+}
+
+/**
+ * Publish times for an npm package's recent versions, newest first.
+ *
+ * The last resort before "no notes": authors who ship neither releases nor
+ * informative commits still usually tag versions, and "0.4.0 landed three
+ * days ago" beats nothing. Reads the full packument once and caches it —
+ * the doc is heavy, and a user may open the dialog twice.
+ */
+const timesCache = new Map<string, { at: number; data: { version: string; date: string }[] }>()
+const TIMES_TTL_MS = 30 * 60 * 1000
+
+export async function npmPublishTimes(name: string): Promise<{ version: string; date: string }[]> {
+  const hit = timesCache.get(name)
+  if (hit !== undefined && Date.now() - hit.at < TIMES_TTL_MS) return hit.data
+  const registry = routesFor(activeRegion()).npmRegistry
+  const res = await marketFetch(`${registry}/${encodeURIComponent(name)}`, {
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    headers: { accept: 'application/json', 'user-agent': 'ChatCode-CLI-Market' },
+  })
+  if (!res.ok) throw new Error(`HTTP ${String(res.status)} reading ${name}`)
+  const doc = await res.json() as { time?: Record<string, string> }
+  const time = doc.time ?? {}
+  const data = Object.entries(time)
+    .filter(([version]) => version !== 'created' && version !== 'modified')
+    .sort(([, a], [, b]) => Date.parse(b) - Date.parse(a))
+    .slice(0, 5)
+    .map(([version, date]) => ({ version, date }))
+  timesCache.set(name, { at: Date.now(), data })
+  return data
+}
+
+/** Everything the dialog renders for one plugin, already resolved. */
+export interface UpdateNotes {
+  kind: 'release' | 'commits' | 'npm' | 'none'
+  /** Present for `release`: the author's own notes for the latest release. */
+  release?: ReleaseNotes
+  /** Present for `commits`: the tail, sliced when the boundary was found. */
+  commits?: { items: CommitNote[]; found: boolean }
+  /** Present for `npm`: recent versions with their publish dates. */
+  npmTimes?: { version: string; date: string }[]
+}
+
+/**
+ * Resolve the notes for one installed plugin, or `{ kind: 'none' }`.
+ *
+ * Never throws: every failure along the way degrades to the next tier, the
+ * same contract the issue promised — a dialog that cannot load its data shows
+ * a neutral statement, not an error.
+ */
+export async function updateNotesFor(
+  profile: string,
+  explicitDir: string | undefined,
+  name: string,
+): Promise<UpdateNotes> {
+  const activeProfileDir = profileDir(profile, explicitDir)
+  const spec = readInstalled(profile, activeProfileDir)[name]
+  if (spec === undefined || spec.startsWith('link:') || spec.startsWith('file:')) {
+    return { kind: 'none' }
+  }
+  try {
+    const payload = await loadUpdateNotes()
+    let key = repoKeyOf(spec)
+    // If the spec is a Release asset URL (catalog format), try to extract
+    // the repo from the URL directly. This handles npm-installed plugins
+    // whose profile spec is the npm name but the catalog entry uses a
+    // Release asset tarball URL.
+    if (key === null) {
+      key = lookupRepoFromUrl(spec)
+    }
+    // If the spec is an npm package name (not a GitHub URL), look up the
+    // catalog to find the corresponding GitHub repo URL.
+    if (key === null) {
+      try {
+        const registry = await loadRegistry()
+        const plugin = registry.plugins.find(p => p.name === name)
+        if (plugin !== undefined) {
+          key = plugin.url
+        }
+      } catch {
+        // Catalog unavailable; fall through to npm times.
+      }
+    }
+    const entry = key === null ? undefined : entryForRepo(payload, key)
+    // Both tiers below need the installed sha for github-kind installs.
+    // For Release asset URLs and catalog lookups, checkUpdates doesn't
+    // recognize the spec, so we read the lockfile directly using the repo key.
+    let current: string | null = null
+    if (key !== null && key.startsWith('https://github.com/')) {
+      const repo = key.slice('https://github.com/'.length).split('#')[0]!.toLowerCase()
+      current = readLockCommits(profile, activeProfileDir).get(repo) ?? null
+    } else {
+      const statuses = await checkUpdates(profile, false, explicitDir).catch(() => null)
+      current = statuses?.[name]?.current ?? null
+    }
+
+    if (entry?.release !== undefined && entry.release !== null && (entry.release.body !== '' || entry.release.tag !== null)) {
+      return { kind: 'release', release: entry.release }
+    }
+    if (entry?.commits !== undefined && entry.commits.length > 0) {
+      return { kind: 'commits', commits: sliceCommitsAt(entry.commits, current) }
+    }
+    if (key === null) {
+      // Not a github-sourced plugin at all: npm times are the only tier left.
+      return { kind: 'npm', npmTimes: await npmPublishTimes(name) }
+    }
+    // A github plugin whose repo answered nothing — releases 404 AND the log
+    // came back empty. Rare enough to just say so rather than ask npm about a
+    // name that may not even exist there.
+    return { kind: 'none' }
+  } catch {
+    return { kind: 'none' }
+  }
+}

package/src/channels.ts

@@ -0,0 +1,70 @@
+/**
+ * The market's release channels: which build of ITSELF it offers.
+ *
+ * Only the market follows this. Other plugins are never pulled from a
+ * prerelease on the strength of a setting the user made about the market —
+ * opting into early builds is volunteering to try THIS plugin early, not to
+ * be handed every other author's unreleased work.
+ *
+ * The model lives in its own module because it is the part with rules
+ * rather than plumbing: three channels, one of them hidden, a mapping to
+ * npm dist-tags, and a resolution order that has already been got wrong
+ * once (see `resolveChannel`).
+ */
+
+/** A channel the market can follow. */
+export type Channel = 'stable' | 'beta' | 'dev'
+
+/**
+ * The npm dist-tag each channel installs from.
+ *
+ * `dev` is published straight from a branch with no git tag behind it, so a
+ * version carries a timestamp and a short SHA (`1.15.0-dev.20260818-3f1432e`)
+ * and is never reused. That is what makes a dev build disposable: nothing in
+ * the repository's history refers to it.
+ */
+export const DIST_TAG: Record<Channel, string> = {
+  stable: 'latest',
+  beta: 'beta',
+  dev: 'dev',
+}
+
+/**
+ * Every channel a user may pick. All three, always.
+ *
+ * `dev` was behind a developer-mode switch for one version, on the reasoning
+ * that a build published straight off a branch should not sit beside
+ * "stable" looking like a third degree of caution. The switch cost more than
+ * it bought: a stored mode, a route to change it, a rule for what happens to
+ * a dev choice when it is turned off, and a control whose own purpose needed
+ * explaining. A plainly labelled option a user can read is simpler than a
+ * hidden one plus the machinery that hides it — the label does the work the
+ * gate was doing.
+ */
+export const CHANNELS: readonly Channel[] = ['stable', 'beta', 'dev']
+
+/** Narrow an untrusted value to a Channel, or null. */
+export function asChannel(value: unknown): Channel | null {
+  return value === 'stable' || value === 'beta' || value === 'dev' ? value : null
+}
+
+/**
+ * Which channel applies right now.
+ *
+ * A choice on record always wins — including "stable" while a prerelease is
+ * running, which is the only way back off a channel. Only the ABSENCE of a
+ * choice is derived, and then from what is actually running: installing
+ * `dshmarket@beta` by hand IS the subscription, and treating that as
+ * "stable" costs updates rather than just clarity — on the stable channel
+ * `latest` (1.13.1) is not newer than an installed 1.14.0-beta.1, so the
+ * market answers "up to date" and the next beta is never offered.
+ *
+ * Which makes `undefined` load-bearing: it has to survive both the settings
+ * schema (no `.default`) and state.json (field omitted) or "never chose"
+ * silently becomes "chose stable".
+ *
+ */
+export function resolveChannel(setting: Channel | undefined, version: string): Channel {
+  if (setting !== undefined) return setting
+  return version.includes('-') ? 'beta' : 'stable'
+}