@chatcode/cco-market 1.45.1

package/src/region-probe.ts

@@ -0,0 +1,97 @@
+/**
+ * Deciding a download region by asking the network, once.
+ *
+ * The alternative was reading the system time zone, and it is wrong for
+ * exactly the people who most need this to work: someone in Shanghai behind
+ * a corporate proxy or a VPN reaches the official registry perfectly well
+ * and would be routed onto mirrors they do not need, while a Chinese-locale
+ * machine sitting in Singapore would be routed onto mirrors that are further
+ * away than the origin. A time zone says where a clock is. It does not say
+ * what the network can reach, which is the only question here.
+ *
+ * So the probe measures the thing itself: it asks both registries for the
+ * same small document and takes whichever answers first. That is
+ * self-correcting in a way a lookup table cannot be — the machine behind the
+ * proxy measures fast official access and stays global, without anyone
+ * having to enumerate the exceptions.
+ *
+ * It runs ONCE, when no region has ever been decided, and its answer is
+ * persisted as the decision. Re-probing every boot would let a market
+ * silently change routes between runs, which is the kind of behaviour that
+ * makes "it was fast yesterday" impossible to debug.
+ */
+
+import { logEvent } from './log.ts'
+import { marketFetch } from './net.ts'
+import { REGIONS, routesFor, type Region } from './regions.ts'
+
+/**
+ * What to ask each registry for.
+ *
+ * The market's own package: present on every npm mirror worth using, and
+ * small — the `latest` document is a few KB, against ~320KB for the full
+ * packument. A probe that downloads a third of a megabyte to answer "which
+ * of these is closer" has spent more than the answer is worth.
+ */
+const PROBE_PATH = 'dshmarket/latest'
+
+/**
+ * Ask every region's registry the same question; return whichever answers
+ * first.
+ *
+ * First-past-the-post rather than a latency comparison, deliberately. From
+ * inside China the official registry usually does answer eventually, so
+ * "did it fail" is the wrong test and "which came back first" is the right
+ * one. From outside, the mainland mirror is reachable but further, and the
+ * same rule picks global. One rule, both directions, no thresholds to tune.
+ *
+ * @param timeoutMs - how long to wait before giving up on all of them.
+ * @param env - environment, for the registry overrides.
+ * @returns the winning region, or `global` when nothing answered — an
+ *   unreachable network is not evidence for switching routes.
+ */
+export async function probeRegion(timeoutMs = 2500, env: NodeJS.ProcessEnv = process.env): Promise<Region> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => { controller.abort() }, timeoutMs)
+  const ask = async (region: Region): Promise<Region> => {
+    const base = routesFor(region, env).npmRegistry
+    const res = await marketFetch(`${base}/${PROBE_PATH}`, {
+      signal: controller.signal,
+      headers: { accept: 'application/json', 'user-agent': 'ChatCode-CLI-Market' },
+    })
+    if (!res.ok) throw new Error(`HTTP ${String(res.status)}`)
+    // Read the body before declaring a winner. Headers can arrive from a
+    // captive portal or a proxy that then stalls, and a region chosen on a
+    // response that never finished would be chosen on nothing.
+    await res.arrayBuffer()
+    return region
+  }
+  try {
+    return await Promise.any(REGIONS.map(ask))
+  } catch {
+    return 'global'
+  } finally {
+    clearTimeout(timer)
+    // Stop the losers. Their answer can no longer change anything, and a
+    // request left running past the decision is a request nobody will read.
+    controller.abort()
+  }
+}
+
+/**
+ * The region to run under, probing only if nothing has ever decided one.
+ *
+ * @param stored - the region already on record, or undefined.
+ * @returns the region, and whether this call decided it (which is what earns
+ *   the user a one-time notice explaining the choice).
+ */
+export async function resolveRegion(
+  stored: Region | undefined,
+  timeoutMs?: number,
+  env?: NodeJS.ProcessEnv,
+): Promise<{ region: Region; probed: boolean }> {
+  if (stored !== undefined) return { region: stored, probed: false }
+  const region = await probeRegion(timeoutMs, env)
+  logEvent('info', 'region', `no region on record; network check chose ${region}`)
+  return { region, probed: true }
+}

package/src/regions.ts

@@ -0,0 +1,310 @@
+/**
+ * Download regions: which route the market's own network requests take.
+ *
+ * Almost every external request the market makes lands on npm's registry or
+ * on GitHub — the plugin catalog, update checks, package downloads, author
+ * avatars, README screenshots. From mainland China several of those can be
+ * slow, which is why this is ONE setting rather than a
+ * row of them: "npm mirror", "GitHub proxy" and "image proxy" are three
+ * spellings of a single question the user is actually being asked, which is
+ * where they are.
+ *
+ * The routing table is the single source of truth. Every consumer asks it
+ * rather than reaching for a hardcoded host, so adding a region is a table
+ * entry instead of a search across six modules.
+ *
+ * Each route has a ChatCode-first environment escape hatch, with the former
+ * `DSHM_*` spelling retained only as a compatibility input.
+ * (src/registry.ts). The China route has service-specific public-proxy
+ * fallbacks; those come and go, and a user whose routes have died needs a way
+ * out that is not "wait for the next release".
+ */
+
+/** A region the market can download from. */
+export type Region = 'global' | 'china'
+
+/** Every region a user may pick. */
+export const REGIONS: readonly Region[] = ['global', 'china']
+
+/** Narrow an untrusted value to a Region, or null. */
+export function asRegion(value: unknown): Region | null {
+  return value === 'global' || value === 'china' ? value : null
+}
+
+/**
+ * The npm registry the market and pnpm read, no trailing slash.
+ *
+ * Exported because callers need to tell "this region uses the default" from
+ * "this region names a mirror" — the difference between leaving a spawned
+ * pnpm's registry alone and setting it.
+ */
+export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org'
+const NPM_CHINA = 'https://mirrors.cloud.tencent.com/npm'
+
+/**
+ * First public prefix used for unauthenticated GitHub reads, no trailing slash.
+ * Authenticated API calls and canonical codeload tarballs never use it.
+ *
+ * What this proxy accepts is a list of GitHub SERVICES, not a hostname test.
+ * The previous note here said it "refuses anything that is not a github.com
+ * hostname", which #460 by @Homplex measured as wrong in both directions —
+ * re-measured 2026-09-01:
+ *
+ *   https://raw.githubusercontent.com/…   200   ← not a github.com hostname
+ *   https://github.com/owner/repo         403   ← is one
+ *   https://example.com/                  403
+ *
+ * So a plain repository page is refused while raw content is served. Do not
+ * reason about this proxy from the hostname; check the specific service, and
+ * re-measure rather than infer, because the policy is the operator's and can
+ * change under us. That fragility is the substance of #460's actual request
+ * (a mirror list and a visible setting), which is tracked separately.
+ */
+const GITHUB_PROXY_CHINA = 'https://gh-proxy.com'
+const GITHUB_PROXY_CHINA_FALLBACK = 'https://ghfast.top'
+
+/** GitHub transports that fail independently on filtered networks. */
+export type GithubService = 'git' | 'raw' | 'avatar'
+
+/** A prefix proxy, or null for the canonical GitHub address. */
+export type GithubRoute = string | null
+
+/** Ordered candidates per GitHub service. */
+export type GithubRoutes = Record<GithubService, GithubRoute[]>
+
+/**
+ * The catalog's stable public address.
+ *
+ * A custom domain rather than the repository path, deliberately: it survives
+ * the repo being renamed or moved, and Pages puts a CDN in front of it.
+ */
+const CATALOG_OFFICIAL = 'https://awesome-dsh-plugin.com/plugins.json'
+
+/**
+ * One place the catalog can be read from.
+ *
+ * Two kinds because the two routes are genuinely different transports, not
+ * two URLs. The npm route reads a published package — which is what lets the
+ * catalog ride the same mirror as everything else, and gives it a version
+ * number that can be rolled back when a bad build ships.
+ */
+export type CatalogSource =
+  | { kind: 'url'; url: string }
+  | { kind: 'npm'; registry: string; pkg: string }
+
+/** Where one region sends each kind of request. `null` means "go direct". */
+export interface RegionRoutes {
+  /** npm registry base, no trailing slash. */
+  npmRegistry: string
+  /** Prefix proxy for github.com-family URLs, or null to go direct. */
+  githubProxy: string | null
+  /** Ordered routes per service; every list ends in a direct escape path. */
+  githubRoutes: GithubRoutes
+  /**
+   * Where to look for the catalog, in order. Later entries are fallbacks.
+   *
+   * The catalog is the FIRST request the market makes, so a mirror that has
+   * gone down must mean a slow market rather than an empty one — every
+   * region ends its list at an address that has always worked.
+   */
+  catalog: CatalogSource[]
+}
+
+/**
+ * The npm package carrying `plugins.json`.
+ *
+ * A package rather than a file URL, because the catalog's own host is the
+ * problem being solved: it is served from GitHub Pages, and the public
+ * GitHub proxies refuse hostnames that are not github.com's own. Published
+ * to npm, it reaches mainland China through the same mirror as every plugin
+ * — no extra service to depend on, and nothing new that can go down.
+ *
+ * Its own package rather than a file added to `awesome-dsh-plugin`: npm
+ * force-includes README files whatever the `files` field says, and that
+ * package's two generated READMEs come to ~1MB. Attaching the catalog to it
+ * would have spent on the wire exactly what this exists to save (measured:
+ * 772KB attached, 413KB standing alone — the latter matching the gzipped
+ * origin almost exactly).
+ */
+const CATALOG_PACKAGE = 'dsh-plugin-catalog'
+
+const ROUTES: Record<Region, RegionRoutes> = {
+  global: {
+    npmRegistry: DEFAULT_NPM_REGISTRY,
+    githubProxy: null,
+    githubRoutes: { git: [null], raw: [null], avatar: [null] },
+    catalog: [{ kind: 'url', url: CATALOG_OFFICIAL }],
+  },
+  china: {
+    npmRegistry: NPM_CHINA,
+    githubProxy: GITHUB_PROXY_CHINA,
+    // Filtering is service-shaped, not GitHub-shaped. Raw content commonly
+    // needs help while git advertisements and avatars remain reachable, so
+    // putting one global order on all three only trades one outage for
+    // needless proxy traffic on the paths that still work.
+    githubRoutes: {
+      raw: [GITHUB_PROXY_CHINA, GITHUB_PROXY_CHINA_FALLBACK, null],
+      git: [null, GITHUB_PROXY_CHINA, GITHUB_PROXY_CHINA_FALLBACK],
+      avatar: [null, GITHUB_PROXY_CHINA, GITHUB_PROXY_CHINA_FALLBACK],
+    },
+    // The package, then the origin. There is deliberately no
+    // raw.githubusercontent step between them: `plugins.json` is a build
+    // artifact that the site publishes to Pages and never commits, so that
+    // path is a guaranteed 404 and would only spend two attempts proving it.
+    catalog: [
+      { kind: 'npm', registry: NPM_CHINA, pkg: CATALOG_PACKAGE },
+      { kind: 'url', url: CATALOG_OFFICIAL },
+    ],
+  },
+}
+
+/** Read a ChatCode-first environment override, treating blanks as unset. */
+function override(env: NodeJS.ProcessEnv, currentName: string, legacyName: string): string | null {
+  const current = env[currentName]
+  if (current !== undefined && current.trim() !== '') return current.trim().replace(/\/+$/, '')
+  const legacy = env[legacyName]
+  return legacy !== undefined && legacy.trim() !== '' ? legacy.trim().replace(/\/+$/, '') : null
+}
+
+/**
+ * Normalize a user-maintained prefix, or reject it.
+ *
+ * Public mirrors receive the complete destination URL in their path. Only
+ * HTTPS prefixes without embedded credentials or query fragments are safe to
+ * persist and show again in the settings UI.
+ */
+export function normalizeGithubProxy(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const raw = value.trim()
+  if (raw === '' || raw.includes('\\')) return null
+  try {
+    const parsed = new URL(raw)
+    if (parsed.protocol !== 'https:' || parsed.username !== '' || parsed.password !== '') return null
+    if (parsed.search !== '' || parsed.hash !== '') return null
+    const path = parsed.pathname.replace(/\/+$/u, '')
+    return `${parsed.origin}${path}`
+  } catch {
+    return null
+  }
+}
+
+let customGithubProxy: string | null = null
+const preferredGithubRoutes = new Map<GithubService, GithubRoute>()
+
+/** Apply (or clear) the persisted UI escape route. */
+export function setCustomGithubProxy(proxy: string | null): void {
+  const next = proxy === null ? null : normalizeGithubProxy(proxy)
+  if (next === customGithubProxy) return
+  customGithubProxy = next
+  resetGithubRoutePreferences()
+}
+
+/** Whether the operator-owned environment variable disables UI changes. */
+export function githubProxyManaged(env: NodeJS.ProcessEnv = process.env): boolean {
+  return override(env, 'CHATCODE_CLI_MARKET_GITHUB_PROXY', 'DSHM_GITHUB_PROXY') !== null
+}
+
+/** Remember one verified route without changing other GitHub services. */
+export function rememberGithubRoute(service: GithubService, route: GithubRoute): void {
+  preferredGithubRoutes.set(service, route)
+}
+
+/** Forget learned winners after the configured candidates change. */
+export function resetGithubRoutePreferences(): void {
+  preferredGithubRoutes.clear()
+}
+
+/**
+ * The routes for a region, with environment overrides applied.
+ *
+ * Overrides win over the table because they are the user's statement about
+ * their own network, and they are the way out when a public proxy dies.
+ *
+ * `CHATCODE_CLI_MARKET_REGISTRY_URL` names the catalog URL. The former
+ * `DSHM_REGISTRY_URL` spelling keeps the same meaning as a compatibility
+ * input. When set, either form
+ * when set it REPLACES the source list rather than heading it: someone
+ * pointing the market at their own catalog does not want it quietly
+ * reverting to ours.
+ */
+export function routesFor(region: Region, env: NodeJS.ProcessEnv = process.env): RegionRoutes {
+  const base = ROUTES[region]
+  const npmMirror = override(env, 'CHATCODE_CLI_MARKET_NPM_MIRROR', 'DSHM_NPM_MIRROR')
+  const githubProxy = override(env, 'CHATCODE_CLI_MARKET_GITHUB_PROXY', 'DSHM_GITHUB_PROXY') ?? customGithubProxy
+  const catalog = override(env, 'CHATCODE_CLI_MARKET_REGISTRY_URL', 'DSHM_REGISTRY_URL')
+  const registry = npmMirror ?? base.npmRegistry
+  const githubRoutes: GithubRoutes = githubProxy === null
+    ? {
+        git: [...base.githubRoutes.git],
+        raw: [...base.githubRoutes.raw],
+        avatar: [...base.githubRoutes.avatar],
+      }
+    : { git: [githubProxy, null], raw: [githubProxy, null], avatar: [githubProxy, null] }
+  return {
+    npmRegistry: registry,
+    githubProxy: githubProxy ?? base.githubProxy,
+    githubRoutes,
+    // A named catalog REPLACES the list rather than joining it. Someone
+    // pointing the market at their own catalog does not want it quietly
+    // reverting to ours when theirs is briefly unreachable — that is how a
+    // fixture-backed test ends up asserting against the live registry.
+    catalog: catalog !== null
+      ? [{ kind: 'url', url: catalog }]
+      // Rebuilt against the resolved registry, so an npm override moves the
+      // catalog to the same mirror it moved everything else to.
+      : base.catalog.map(source => (source.kind === 'npm' ? { ...source, registry } : source)),
+  }
+}
+
+/** Ordered candidates with this process's last verified winner first. */
+export function githubRoutesFor(
+  service: GithubService,
+  region: Region = activeRegion(),
+  env: NodeJS.ProcessEnv = process.env,
+): GithubRoute[] {
+  const routes = routesFor(region, env).githubRoutes[service]
+  if (!preferredGithubRoutes.has(service)) return routes
+  const preferred = preferredGithubRoutes.get(service)!
+  const index = routes.findIndex(route => route === preferred)
+  if (index <= 0) return routes
+  return [routes[index]!, ...routes.slice(0, index), ...routes.slice(index + 1)]
+}
+
+/**
+ * The region this process is running under.
+ *
+ * One piece of module state rather than a parameter threaded through the
+ * catalog, the theme manager, update checks and every pnpm spawn: the region
+ * is a property of the running market, not of any single question asked of
+ * it, and the call graphs that need it are several frames deep.
+ *
+ * Consumers that must react to a CHANGE (dropping a cache gathered from the
+ * other registry) keep their own setter beside this one; this holds the
+ * answer for everyone who only needs to read it.
+ */
+let active: Region = 'global'
+
+/** The region in force. */
+export function activeRegion(): Region {
+  return active
+}
+
+/** Set the region in force. Callers are responsible for their own caches. */
+export function setActiveRegion(region: Region): void {
+  active = region
+}
+
+/**
+ * Wrap a github.com-family URL in a prefix proxy.
+ *
+ * The proxy takes the full absolute URL as its path (`{proxy}/{url}`) rather
+ * than a rewritten hostname, so the same joining rule works for every
+ * GitHub service a caller has explicitly allowed through public routes.
+ *
+ * @param proxy - the prefix, or null to go direct.
+ * @param url - an absolute https URL on a github.com-family host.
+ * @returns the proxied URL, or `url` unchanged when there is no proxy.
+ */
+export function throughProxy(proxy: string | null, url: string): string {
+  return proxy === null ? url : `${proxy}/${url}`
+}

package/src/registry.ts

@@ -0,0 +1,250 @@
+/**
+ * Registry access: the curated list from awesome-dsh-plugin.com, fetched
+ * fresh on every request. See `loadRegistry` for why there is nothing
+ * behind it any more.
+ */
+
+import { configuredProxy, marketFetch } from './net.ts'
+import { catalogFromPackage } from './catalog-npm.ts'
+import { activeRegion, routesFor, type CatalogSource, type Region } from './regions.ts'
+
+export interface RegistryPlugin {
+  name: string
+  owner: string
+  url: string
+  /** One legacy category id or several category ids. */
+  category: string | string[]
+  description: Record<string, string>
+  npm?: string | null
+  tarball?: string | null
+  stars?: number | null
+  /**
+   * npm downloads in the last 30 days, when the entry has a published
+   * package. `null`/absent means "no npm package" — a coverage gap, not a
+   * zero — so sorting must not read it as "less popular than 0".
+   */
+  downloads?: number | null
+  install: string
+  added: string
+  /**
+   * Catalog-side deprecation flags (#60): supplied by awesome-dsh-plugin,
+   * absent for every normal entry — the market only consumes them, so a
+   * catalog without the fields behaves exactly as before.
+   */
+  deprecated?: boolean
+  /** Catalog name of the suggested replacement plugin, when deprecated. */
+  replacement?: string
+}
+
+/**
+ * Category ids for one catalog entry, de-duplicated in declaration order.
+ *
+ * Catalog JSON is an external input, so malformed array members are omitted
+ * here and an entry with no usable category is rejected by `asRegistry`.
+ */
+export function pluginCategories(plugin: Pick<RegistryPlugin, 'category'>): string[] {
+  const values: unknown[] = Array.isArray(plugin.category) ? plugin.category : [plugin.category]
+  const categories: string[] = []
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (typeof value !== 'string' || value === '' || seen.has(value)) continue
+    seen.add(value)
+    categories.push(value)
+  }
+  return categories
+}
+
+export interface Registry {
+  updated: string
+  count: number
+  categories: Record<string, Record<string, string>>
+  plugins: RegistryPlugin[]
+}
+
+/**
+ * Where the curated list comes from now lives in the region routing table
+ * (src/regions.ts), because it is one of several addresses that move
+ * together when a user changes download region.
+ *
+ * `DSHM_REGISTRY_URL` keeps its meaning there, unchanged: overridable
+ * through the process environment ONLY — the layer-3 e2e points it at a
+ * local fixture catalog so the install route can be driven end to end
+ * without publishing anything.
+ *
+ * This does not weaken the install route's registry check. That check exists
+ * to stop a malicious PAGE from POSTing an arbitrary source at the local
+ * server; a page cannot set environment variables, and anyone who can set
+ * this process's environment already controls the process. What the override
+ * changes is WHICH list is curated, never WHETHER the check runs.
+ */
+
+/**
+ * How long to wait for the catalog.
+ *
+ * Generous on purpose. It used to be 4s with a bundled snapshot behind it,
+ * so a slow link quietly became a 39%-smaller catalog. Now that a failure is
+ * reported rather than papered over, cutting off a link that WOULD have
+ * answered is the expensive mistake — 282KB over TLS from a far-away network
+ * is not a 4-second job.
+ */
+const FETCH_TIMEOUT_MS = 15_000
+
+/**
+ * The catalog we were last served, with the validator identifying it.
+ *
+ * This is NOT the cache that was removed, and the difference is the whole
+ * point. That cache SKIPPED the request for an hour and answered from
+ * memory — it asserted freshness without ever asking. This asks the origin
+ * every single time; the validator only lets the origin answer "still the
+ * same" (304) instead of resending a megabyte. Freshness is verified on
+ * every call either way, so `data` below is only ever returned when the
+ * server has just confirmed it is current.
+ *
+ * In memory rather than on disk: a restart is rare enough that paying one
+ * full download for it costs nothing, and a file would be one more thing
+ * that can be found on a machine and mistaken for the catalog itself.
+ *
+ * Measured against the live origin (GitHub Pages behind Fastly, which
+ * serves both `etag` and `last-modified`): 295 KB and 1.3s unconditional,
+ * 0 bytes and 0.5s for a 304. The reporter whose fetch took 9.9s was
+ * downloading the full 1.07 MB every time they opened the market.
+ */
+let served: {
+  /** Which source issued this, so a validator is never sent to another one. */
+  key: string
+  etag: string | null
+  modified: string | null
+  /** The published version, for the npm route — its equivalent of an ETag. */
+  version: string | null
+  data: Registry
+} | null = null
+
+/** Identity of a catalog source, for scoping the validator to its origin. */
+function sourceKey(source: CatalogSource): string {
+  return source.kind === 'npm' ? `npm:${source.registry}/${source.pkg}` : `url:${source.url}`
+}
+
+/** A parsed catalog, or a thrown explanation of why it is not one. */
+function asRegistry(value: unknown): Registry {
+  const data = value as Registry
+  if (!Array.isArray(data.plugins) || data.plugins.length === 0) throw new Error('the catalog came back empty')
+  const plugins = data.plugins.map((plugin, index) => {
+    const category = pluginCategories(plugin)
+    if (category.length === 0) throw new Error(`catalog plugin ${String(index)} carries no usable category`)
+    return { ...plugin, category }
+  })
+  return { ...data, plugins }
+}
+
+/**
+ * Drop what we remember, so the next call is unconditional.
+ *
+ * Exists for tests: the memo is module state, and a spec that asserted a
+ * 304 would otherwise leak a validator into the next one.
+ */
+export function forgetCatalog(): void {
+  served = null
+}
+
+/**
+ * The catalog, revalidated every time it is asked for.
+ *
+ * There used to be three answers here — live, a one-hour in-memory cache,
+ * and a snapshot bundled into the npm package — and only the first was
+ * correct. The other two were indistinguishable from it on screen, so a
+ * machine that could not reach the registry browsed the publish-time file
+ * (839 entries against 1367 live, and frozen forever for anyone on an older
+ * release), while a machine that COULD reach it still saw an hour-old
+ * listing of a catalog that grows by ~250 entries a day.
+ *
+ * For a catalog, stale is not a degraded answer, it is a wrong one: a plugin
+ * published this morning reads as "does not exist". So there is one source
+ * now, and a failure is a failure — the caller reports it and offers a
+ * retry, which is a state the user can act on. In particular a network
+ * failure is NEVER answered from `served`: an origin that cannot be reached
+ * has not confirmed anything, and quietly handing back the last catalog
+ * would rebuild exactly the fallback this replaced.
+ * @throws when the catalog cannot be fetched or does not look like one.
+ */
+export async function loadRegistry(region: Region = activeRegion()): Promise<Registry> {
+  const started = Date.now()
+  let last: unknown
+  let attempts = 0
+  // Sources in order, each a fallback for the one before it. The catalog is
+  // the FIRST request the market makes, so a mirror that has gone down must
+  // mean a slow market rather than an empty one — the list ends at the
+  // address that has always worked.
+  for (const source of routesFor(region).catalog) {
+    const key = sourceKey(source)
+    // Two attempts each. A catalog fetch crossing a long, lossy path fails
+    // transiently often enough that one retry is worth more than the second
+    // or two it costs — and with nothing behind this call any more, a
+    // transient failure is a market with no plugins in it.
+    for (let attempt = 0; attempt < 2; attempt++) {
+      attempts += 1
+      try {
+        // A validator only ever goes back to the source that issued it.
+        // Carried across a region switch it could earn a "not modified" from
+        // an origin whose body we have never seen.
+        const reusable = served?.key === key ? served : null
+        if (source.kind === 'npm') {
+          const { version, data } = await catalogFromPackage(
+            source.registry, source.pkg, reusable?.version ?? undefined,
+          )
+          // `data === null` means the published version is the one in hand.
+          if (data === null && reusable !== null) return reusable.data
+          if (data === null) throw new Error('the catalog package reported no change with nothing to reuse')
+          const parsed = asRegistry(data)
+          served = { key, etag: null, modified: null, version, data: parsed }
+          return parsed
+        }
+        // ETag first: it is exact, while a date has one-second resolution and
+        // a catalog republished twice within the same second would validate
+        // as unchanged. Only one is sent — an origin given both must satisfy
+        // both, which turns a weak ETag match into an unnecessary 200.
+        const headers: Record<string, string> = {}
+        if (reusable?.etag != null) headers['if-none-match'] = reusable.etag
+        else if (reusable?.modified != null) headers['if-modified-since'] = reusable.modified
+
+        const res = await marketFetch(source.url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers })
+        if (res.status === 304) {
+          // Only reachable when we sent a validator, so `reusable` is present.
+          // Guarded anyway: answering a 304 with nothing to reuse would
+          // otherwise surface as a confusing parse error on an empty body.
+          if (reusable === null) throw new Error('the catalog answered "not modified" with nothing to revalidate')
+          return reusable.data
+        }
+        if (!res.ok) throw new Error(`HTTP ${String(res.status)}`)
+        const data = asRegistry(await res.json())
+        served = {
+          key, etag: res.headers.get('etag'), modified: res.headers.get('last-modified'), version: null, data,
+        }
+        return data
+      } catch (error) {
+        last = error
+      }
+    }
+  }
+  throw new Error(describeFetchFailure(last, Date.now() - started, attempts))
+}
+
+/**
+ * A catalog failure with the facts needed to classify it, in the message
+ * itself.
+ *
+ * The market shows this string and the log export carries it, so it is the
+ * whole of what a bug report will contain. "The operation was aborted due to
+ * timeout" alone cannot distinguish a slow link from a blocked one from a
+ * proxy this process cannot use — and Node's `fetch` ignores HTTP_PROXY
+ * entirely (measured on Node 25), so a machine whose only route out is a
+ * proxy fails here every time while every other tool on it works.
+ */
+export function describeFetchFailure(error: unknown, elapsedMs: number, attempts = 2): string {
+  const reason = error instanceof Error ? error.message : String(error)
+  const proxy = configuredProxy()
+  const parts = [`${reason} (${String(Math.round(elapsedMs / 1000))}s, ${String(attempts)} attempts)`]
+  if (proxy !== null) {
+    parts.push(`tried through the configured proxy ${proxy.replace(/\/\/[^@]*@/u, '//***@')}`)
+  }
+  return parts.join(' · ')
+}