@chatcode/cco-market 1.45.1

package/lib/region-probe.js

@@ -0,0 +1,93 @@
+/**
+ * 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.js';
+import { marketFetch } from './net.js';
+import { REGIONS, routesFor } from './regions.js';
+/**
+ * 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 = process.env) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    const ask = async (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, timeoutMs, env) {
+    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/lib/regions.js

@@ -0,0 +1,253 @@
+/**
+ * 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".
+ */
+/** Every region a user may pick. */
+export const REGIONS = ['global', 'china'];
+/** Narrow an untrusted value to a Region, or null. */
+export function asRegion(value) {
+    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';
+/**
+ * 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';
+/**
+ * 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 = {
+    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, currentName, legacyName) {
+    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) {
+    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 = null;
+const preferredGithubRoutes = new Map();
+/** Apply (or clear) the persisted UI escape route. */
+export function setCustomGithubProxy(proxy) {
+    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 = process.env) {
+    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, route) {
+    preferredGithubRoutes.set(service, route);
+}
+/** Forget learned winners after the configured candidates change. */
+export function resetGithubRoutePreferences() {
+    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, env = process.env) {
+    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 = 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, region = activeRegion(), env = process.env) {
+    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 = 'global';
+/** The region in force. */
+export function activeRegion() {
+    return active;
+}
+/** Set the region in force. Callers are responsible for their own caches. */
+export function setActiveRegion(region) {
+    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, url) {
+    return proxy === null ? url : `${proxy}/${url}`;
+}

package/lib/registry.js

@@ -0,0 +1,204 @@
+/**
+ * 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.js';
+import { catalogFromPackage } from './catalog-npm.js';
+import { activeRegion, routesFor } from './regions.js';
+/**
+ * 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) {
+    const values = Array.isArray(plugin.category) ? plugin.category : [plugin.category];
+    const categories = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== 'string' || value === '' || seen.has(value))
+            continue;
+        seen.add(value);
+        categories.push(value);
+    }
+    return categories;
+}
+/**
+ * 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 = null;
+/** Identity of a catalog source, for scoping the validator to its origin. */
+function sourceKey(source) {
+    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) {
+    const data = value;
+    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() {
+    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 = activeRegion()) {
+    const started = Date.now();
+    let last;
+    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 = {};
+                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, elapsedMs, attempts = 2) {
+    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(' · ');
+}