@chatcode/cco-market 1.45.1

package/lib/themes.js

@@ -0,0 +1,102 @@
+/**
+ * Theme lifecycle: classifying installed packages as themes (by the
+ * registry's theme category), live-toggling bundle-layer entries through
+ * the loader, and keeping exactly one theme active with the choice
+ * persisted across restarts.
+ */
+import { loadRegistry, pluginCategories } from './registry.js';
+import { hotMount, hotUnmount, listHotMounts, writeDisabled } from './hot.js';
+import { logEvent } from './log.js';
+import { profileDir, readInstalled } from './profile.js';
+import { repoOf } from './sources.js';
+/**
+ * Create the theme manager. `disabledThemes` is the live, shared set of
+ * themes the user switched off — the caller owns reading it at boot and
+ * replaying it; the manager mutates and persists it on switches.
+ */
+export function createThemeManager(host, profile, disabledThemes, explicitDir) {
+    const activeProfileDir = profileDir(profile, explicitDir);
+    /** Installed package names classified as themes by the registry's theme category. */
+    async function installedThemeNames() {
+        const names = new Set();
+        try {
+            const registry = await loadRegistry();
+            const themeEntries = registry.plugins.filter(p => pluginCategories(p).includes('theme'));
+            const themeNames = new Set(themeEntries.map(p => p.name));
+            const themeRepos = new Set(themeEntries.map(p => repoOf(p.url)).filter((r) => r !== null).map(r => r.toLowerCase()));
+            for (const [name, spec] of Object.entries(readInstalled(profile, activeProfileDir))) {
+                if (themeNames.has(name)) {
+                    names.add(name);
+                    continue;
+                }
+                const match = /github:([^#\s]+)/.exec(String(spec).toLowerCase());
+                if (match !== null && themeRepos.has(match[1]))
+                    names.add(name);
+            }
+        }
+        catch { /* registry unavailable — nothing classifies as a theme */ }
+        return names;
+    }
+    /**
+     * Live-toggle a bundle-layer plugin through its loader entry. Bundle trees
+     * are in-memory (write is a no-op), so this never touches any file — the
+     * market persists the choice itself and replays it at boot.
+     * @returns true when a matching live entry was found and updated.
+     */
+    async function setEntryDisabled(name, disabledFlag) {
+        let found = false;
+        for (const entry of host.loader.entries()) {
+            if (entry.options.name !== name)
+                continue;
+            // A disable can land while the entry's init is still in flight: the
+            // options flip but the finishing init brings the fiber up anyway, and a
+            // plain re-update no-ops on the empty diff. Force the update and verify
+            // the live state, retrying until reality matches the flag.
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try {
+                    await entry.update({ disabled: disabledFlag ? true : null }, false, true);
+                    found = true;
+                }
+                catch (error) {
+                    logEvent('warn', 'toggle', `${name}: entry update failed — ${error instanceof Error ? error.message : String(error)}`);
+                    break;
+                }
+                const live = entry.fiber !== undefined;
+                if (live !== disabledFlag)
+                    break;
+                await new Promise(resolvePromise => setTimeout(resolvePromise, 200));
+            }
+            logEvent('info', 'toggle', `${name} -> ${disabledFlag ? 'off' : 'on'}: fiber=${String(entry.fiber !== undefined)}`);
+        }
+        if (!found)
+            logEvent('info', 'toggle', `${name}: no loader entry matched`);
+        return found;
+    }
+    /**
+     * Make `name` the one active theme: deactivate every other installed theme
+     * (market hot mounts unmount; bundle-layer entries live-disable) and bring
+     * it up. The choice persists in state.json and is replayed at boot.
+     */
+    async function activateTheme(name) {
+        const themes = await installedThemeNames();
+        for (const other of themes) {
+            if (other === name)
+                continue;
+            if (listHotMounts().includes(other)) {
+                await hotUnmount(other);
+                disabledThemes.add(other);
+            }
+            else if (await setEntryDisabled(other, true)) {
+                disabledThemes.add(other);
+            }
+        }
+        disabledThemes.delete(name);
+        writeDisabled(activeProfileDir, disabledThemes);
+        if (listHotMounts().includes(name))
+            return true;
+        if (await setEntryDisabled(name, false))
+            return true;
+        return (await hotMount(host, activeProfileDir, name)).ok;
+    }
+    return { installedThemeNames, setEntryDisabled, activateTheme };
+}

package/lib/trial.js

@@ -0,0 +1,116 @@
+/**
+ * Trial validation for composition changes — issue #98 (phase 3), the
+ * "trial boot" half of #19 reduced to what is safe and offline: before any
+ * bundle-order or preset change is written to the profile, replay the
+ * composition with the CANDIDATE order using the same entry-list machinery
+ * the real boot uses (src/check.ts's buildBundleLayers + composeLayers), and
+ * refuse the change when the composed tree would fail to boot (duplicate
+ * loader entry ids, unresolvable bundle layers, unparseable patches).
+ *
+ * No process, no network, no writes to the profile: the real profile is only
+ * read; if the candidate is bad, the failure is reported and nothing is
+ * applied (the caller then skips the write-back entirely).
+ *
+ * Issue #125 review: the CURRENT composition is replayed alongside the
+ * candidate, so the response also carries a current-vs-candidate diff
+ * (overrides / orphans / duplicates the reorder introduces) — not just
+ * whether it boots.
+ *
+ * Bundle resolution is deliberately SHARED with the check report
+ * (check.ts's buildBundleLayers): the dsh installation anchor first, then
+ * Node's module search from the profile (workspace-root hoisting) — so the
+ * trial can never disagree with the diagnostics about what a bundle is or
+ * where it lives, and official bundles resolve even when they are only
+ * hoisted to the workspace root.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildBundleLayers, composeLayers, findDshInstallDir, parsePatchFile, } from './check.js';
+import { resolveDshHome } from './home-paths.js';
+import { mergeOrder, readBundleStack } from './order.js';
+/**
+ * Replay the profile composition with `newCommunityOrder` (the candidate
+ * community-bundle order; official bundles keep their exact positions) and
+ * report anything that would break the boot. Pure read.
+ */
+export function trialValidate(profileDir, newCommunityOrder, options = {}) {
+    const errors = [];
+    const warnings = [];
+    const current = readBundleStack(profileDir);
+    // Same merge the apply path uses (order.ts mergeOrder): the trial replays
+    // EXACTLY the stack a successful apply would write.
+    const merged = mergeOrder(current.bundles, newCommunityOrder);
+    if (!merged.ok) {
+        return {
+            ok: false, errors: [{ layer: '(order)', message: merged.error }], warnings,
+            duplicates: [], rows: [],
+            diff: { overrides: [], orphans: [], duplicates: [] },
+        };
+    }
+    const candidate = merged.bundles;
+    // Shared bundle-layer build — identical resolution to analyzeProfile
+    // (dsh install anchor first, then Node module search from the profile).
+    let specs = {};
+    try {
+        const manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'));
+        specs = manifest.dependencies ?? {};
+    }
+    catch { /* specs stay empty — sources read as '(not a direct dependency)' */ }
+    const dshInstall = options.dshInstallDir !== undefined ? options.dshInstallDir : findDshInstallDir();
+    // Same user/home patch layers as the boot (and the check report) — shared
+    // by BOTH compositions.
+    const patchLayers = [];
+    const userPatchPath = join(profileDir, 'cordis.patch.yml');
+    if (existsSync(userPatchPath)) {
+        const patches = parsePatchFile(userPatchPath);
+        patchLayers.push({ label: 'user-patch', kind: 'user', patches: patches ?? [], parseError: null });
+        if (patches === null)
+            errors.push({ layer: 'user-patch', message: 'cordis.patch.yml is not a valid entry list / cordis.patch.yml 不是合法的条目列表' });
+    }
+    const home = resolveDshHome(options.homeDir);
+    const homePatchPath = join(home, 'cordis.patch.yml');
+    if (existsSync(homePatchPath)) {
+        const patches = parsePatchFile(homePatchPath);
+        patchLayers.push({ label: 'home-patch', kind: 'home', patches: patches ?? [], parseError: null });
+        if (patches === null)
+            errors.push({ layer: 'home-patch', message: 'home cordis.patch.yml is not a valid entry list / 全局 cordis.patch.yml 不是合法的条目列表' });
+    }
+    /** Compose the loader tree for one bundle order (current or candidate). */
+    const compose = (bundleOrder) => {
+        const built = buildBundleLayers(profileDir, bundleOrder, specs, dshInstall);
+        return { built, composed: composeLayers([...built.layers, ...patchLayers]) };
+    };
+    const currentState = compose(current.bundles);
+    const candidateState = compose(candidate);
+    const composed = candidateState.composed;
+    for (const bundle of candidateState.built.bundles) {
+        if (bundle.error !== null)
+            errors.push({ layer: bundle.name, message: bundle.error });
+        if (bundle.parseError !== null)
+            errors.push({ layer: bundle.name, message: bundle.parseError });
+    }
+    for (const dup of composed.duplicates) {
+        errors.push({ layer: dup.layers.join(' / '), message: `duplicate loader entry id ${JSON.stringify(dup.id)} (${dup.count} rows) / 重复的 loader 条目 id ${JSON.stringify(dup.id)}` });
+    }
+    for (const orphan of composed.orphans) {
+        warnings.push({ layer: orphan.layer, message: `${orphan.id}: ${orphan.reason}` });
+    }
+    // Issue #125 review: what does the reorder CHANGE? Compare the candidate
+    // composition against the current one — only candidate-introduced
+    // overrides / orphans / duplicates are reported.
+    const currentDupIds = new Set(currentState.composed.duplicates.map(d => d.id));
+    const sameOverride = (a, b) => a.id === b.id && a.layer === b.layer && a.overriddenLayers.join('\u0000') === b.overriddenLayers.join('\u0000');
+    const diff = {
+        overrides: composed.overrides.filter(o => !currentState.composed.overrides.some(c => sameOverride(o, c))),
+        orphans: composed.orphans.filter(o => !currentState.composed.orphans.some(c => c.id === o.id && c.layer === o.layer)),
+        duplicates: composed.duplicates.filter(d => !currentDupIds.has(d.id)),
+    };
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        duplicates: composed.duplicates,
+        rows: composed.rows.map(row => ({ id: row.id, layer: row.layer })),
+        diff,
+    };
+}

package/lib/types/accelerate.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Resolving a GitHub install through a region's proxy without proxying the
+ * tarball pnpm records.
+ *
+ * pnpm does not fetch `github:owner/repo` with `git clone`; it resolves the
+ * shortcut and downloads a tarball from codeload.github.com. That rules out
+ * the usual `git config insteadOf` trick — there is no git command to
+ * redirect.
+ *
+ * Prefix-proxying that tarball used to save substantial time, but pnpm 11's
+ * fail-closed lockfile checks changed the safety boundary. A URL shaped like
+ * `https://proxy/https://codeload.github.com/.../<commit>` no longer has the
+ * codeload hostname, so pnpm treats it as an ordinary remote tarball and
+ * requires an integrity hash that its GitHub resolver does not write. The
+ * result is ERR_PNPM_MISSING_TARBALL_INTEGRITY on the install itself (#385).
+ * Disabling that check or minting a checksum from whatever the proxy served
+ * would weaken pnpm's supply-chain protection, so neither is acceptable.
+ *
+ * The safe middle ground is to resolve HEAD through the regional proxy, then
+ * hand pnpm a commit-pinned `github:owner/repo#<sha>` target. The ref lookup
+ * still avoids a slow or unreachable GitHub metadata request; pnpm itself
+ * fetches the canonical codeload URL, records it as `gitHosted: true`, and
+ * keeps its integrity policy intact.
+ *
+ * - **The commit has to be pinned.** The profile reads each plugin's
+ *   installed commit back out of the lockfile by matching a codeload URL
+ *   ending in a 40-character SHA (src/profile.ts). A `HEAD` tarball installs
+ *   perfectly and then reports no version forever. So this resolves the SHA
+ *   first, and a rewrite that cannot get one does not happen.
+ * - **Build-script approval has to keep matching.** `gitAllowBuildsKey`
+ *   (src/sources.ts) derives its stable key from the repo, and the pinned
+ *   GitHub form preserves that identity.
+ *
+ * Catalog subpath entries are left alone: `#path:` identifies a different
+ * package inside the repo, so the acceleration step never rewrites that
+ * fragment. Collection roots discovered after install preserve the resolved
+ * commit and add their subpath as pnpm's second `&path:` selector.
+ *
+ * Every SHA-lookup failure falls back to the original target. Acceleration
+ * is an optimisation, and an optimisation that can fail an install is a bug.
+ */
+import { type Region } from './regions.ts';
+/**
+ * The commit `HEAD` points at, from git's own ref advertisement.
+ *
+ * This is the endpoint `git clone` reads before it fetches anything, and it
+ * is the right one here for two measured reasons. It is not the REST API, so
+ * it does not consume the 60-requests-per-hour unauthenticated quota that a
+ * user installing a handful of plugins could plausibly exhaust. And it
+ * survives the proxy: over five consecutive tries from an unproxied mainland
+ * connection it answered 200 in ~1.2s every time, while the REST API through
+ * the same proxy returned 200, 200, then 403 — a proxy that rate-limits the
+ * API path would silently drop every install back to the slow route.
+ *
+ * The response is git's pkt-line format, whose first ref line carries
+ * `<sha> HEAD\0<capabilities>`. Read with a pattern rather than a parser:
+ * one 40-character hex string followed by `HEAD` is unambiguous in this
+ * payload, and a length-prefix reader would be more code to get wrong.
+ *
+ * The same advertisement lists every branch and tag, which is what `ref`
+ * uses. A plugin installed from `github:owner/repo#publish` is not asking
+ * about the default branch at all, and answering with it made the market
+ * report an update forever (#446) — the two SHAs simply never match. Both
+ * namespaces are searched because pnpm accepts a tag there too, branches
+ * first since that is what the reports are about.
+ * @param ref - branch or tag to resolve, or undefined for the default branch.
+ */
+export declare function headCommit(repo: string, proxy: string | null, signal?: AbortSignal, ref?: string): Promise<string | null>;
+/**
+ * The current `HEAD` commit for a repo, on whichever route the region uses.
+ *
+ * Wraps the timeout so callers outside the install path — the build-script
+ * approval below, which needs a commit-pinned key — do not each reinvent it.
+ */
+export declare function resolveHeadCommit(repo: string, region: Region, env?: NodeJS.ProcessEnv, ref?: string): Promise<string | null>;
+/**
+ * The install target to actually hand pnpm, given the region in force.
+ *
+ * @param target - what `installTargetFor` produced.
+ * @param region - the download region.
+ * @param env - environment, for the proxy override.
+ * @returns a commit-pinned GitHub shortcut when one route resolves HEAD,
+ *   otherwise `target` unchanged.
+ */
+export declare function acceleratedTarget(target: string, region: Region, env?: NodeJS.ProcessEnv): Promise<string>;

package/lib/types/agents.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Optional host-provided agent inventory: lets the market refuse plugin
+ * mutations while a live agent is mid-turn. Mutating `node_modules` under a
+ * running agent replaces files the running plugin modules may still read or
+ * lazily import — the update "succeeds" while old code and new files mix.
+ */
+export interface RunningAgentLike {
+    id?: unknown;
+    status?: unknown;
+}
+export interface AgentsServiceLike {
+    list(): RunningAgentLike[];
+}
+export type AgentsLookup = () => AgentsServiceLike | undefined;
+/**
+ * Ids of the host's currently running agents, or [] when the host has no
+ * agents service. Only a positive `status === 'running'` blocks an update —
+ * unknown statuses are treated as not running, so a future agent
+ * implementation with different wording fails open (the market stays
+ * usable) instead of wedging the plugin page.
+ */
+export declare function runningAgentIds(agents: AgentsServiceLike | undefined): string[];

package/lib/types/backup.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Portable profile backups: configuration only, never installed packages.
+ *
+ * The profile directory is plain user data — aside from package.json it can
+ * hold API keys (config.toml), tokens, or the WebDAV password when stored
+ * server-side. Backups therefore behave like `dsh export` and carry the same
+ * credential-warning disclaimer in the UI (review #63).
+ */
+export declare const BACKUP_FORMAT = "dsh-profile-backup";
+export declare const MAX_BACKUP_BYTES: number;
+/** File names that routinely contain credentials (backup exports).
+ *  Values are never masked in place — the export is one-to-one for
+ *  faithful restores — but presence is surfaced by the UI warning. */
+export declare const SECRET_FILE_HINTS: RegExp;
+/** Count of exported files whose names look like they carry credentials. */
+export declare function secretFileCount(profile: string, explicitDir?: string): number;
+export type BackupFile = {
+    path: 'package.json';
+    json: Record<string, unknown>;
+} | {
+    path: string;
+    lines: string[];
+};
+export interface ProfileBackup {
+    format: typeof BACKUP_FORMAT;
+    version: 0.2;
+    createdAt: string;
+    profile: string;
+    files: BackupFile[];
+}
+/** Serialize every profile file except dependencies, lock state, and market cache. */
+export interface BackupOptions {
+    /** Partial export: only these plugins (dependency names) are kept. */
+    includeDeps?: string[];
+    /**
+     * With includeDeps, also carry the profile's other configuration files.
+     * Config files are profile-scoped and cannot be attributed to individual
+     * plugins, so this is all-or-nothing — the UI warns about secrets before
+     * enabling it (the backup itself is one-to-one, never masked).
+     */
+    includeConfig?: boolean;
+}
+/**
+ * Serialize every profile file except dependencies, lock state, and market
+ * cache — or, with {@link BackupOptions.includeDeps}, only the manifest with
+ * the selected plugins (plus, optionally, the other config files).
+ */
+export declare function createProfileBackup(profile: string, explicitDir?: string, opts?: BackupOptions): ProfileBackup;
+export declare function validatedBackup(value: unknown): ProfileBackup;
+/** Atomically overwrite backed-up files and return a rollback for install failure. */
+export declare function restoreProfileBackup(profile: string, value: unknown, explicitDir?: string): {
+    files: number;
+    rollback(): void;
+};
+interface PublicAddress {
+    address: string;
+    family: 4 | 6;
+}
+/**
+ * Ancestor collection URLs of a WebDAV file, outermost first.
+ * `https://dav.example/a/b/x.json` → [`https://dav.example/a/`, `https://dav.example/a/b/`].
+ * The server root itself is never included — it always exists, and some
+ * providers reject MKCOL on it.
+ */
+export declare function webdavParentCollections(url: string): string[];
+/**
+ * Upload the backup, creating missing parent collections first (#102).
+ *
+ * WebDAV servers do not create intermediate collections implicitly, so a PUT
+ * into a folder that does not exist yet fails — Jianguoyun answers 404, which
+ * read as "sync is broken" rather than "make the folder first". MKCOL on an
+ * existing collection answers 405, which is success for our purposes; any
+ * other failure is left to the PUT to report, since some providers restrict
+ * MKCOL while still accepting the upload.
+ */
+export declare function uploadWebdav(url: string, username: string, password: string, backup: ProfileBackup): Promise<void>;
+/** Refuse non-global IPv4 targets, including metadata and carrier NAT ranges. */
+export declare function isPublicIpv4(ip: string): boolean;
+/** Only public internet target hostnames are reachable for WebDAV. */
+export declare function isPublicHostname(hostname: string): boolean;
+/**
+ * Whether a WebDAV hostname may be fetched: public https targets only.
+ * Exported for tests.
+ */
+export declare function isPublicTarget(hostname: string): boolean;
+/** Only global-unicast IPv6 is usable for a server-side WebDAV connection. */
+export declare function isPublicIpv6(ip: string): boolean;
+/** Resolve once, reject every unsafe answer, and return the address to pin. */
+export declare function resolvePublicAddress(hostname: string): Promise<PublicAddress>;
+export declare function downloadWebdav(url: string, username: string, password: string): Promise<unknown>;
+export interface PluginSelection {
+    deps: Record<string, string>;
+    bundles: string[];
+}
+/**
+ * The selected plugins' dependency specs and bundle entries from a backup's
+ * manifest. Only string specs survive — everything else in the manifest is
+ * untrusted and ignored (partial restore touches nothing but these).
+ */
+export declare function extractPluginSelection(backup: ProfileBackup, includeDeps: string[]): PluginSelection;
+/**
+ * Merge a backup's manifest into the profile's current manifest so a restore
+ * never deletes plugins the target machine already has: current deps stay,
+ * backup specs win on name conflicts; bundle lists are unioned. When
+ * `selection` is given, only the selected plugins are merged in.
+ */
+/**
+ * Dependencies whose spec points at an absolute local path — `link:/Users/…`
+ * or `file:/home/…` (#205 by @Rudyy898).
+ *
+ * These are perfectly valid on the machine that wrote them and meaningless
+ * anywhere else, so a backup carrying one restores a manifest that `pnpm
+ * install` cannot satisfy: the path does not exist on the new machine and
+ * the whole restore fails on it.
+ *
+ * Reported, NOT rewritten. Turning `link:/Users/me/dev/plugin` into
+ * something portable means deciding where those files should live and
+ * whether to carry them at all, which is a design question and not
+ * something a restore should answer on the user's behalf. Naming them lets
+ * the operator decide before the install runs — which is the part that was
+ * missing.
+ *
+ * Relative `file:./vendor/x` specs are left alone: they resolve against the
+ * profile directory, which the restore recreates, so they travel fine.
+ */
+export declare function unportableDeps(dependencies: unknown): Array<{
+    name: string;
+    spec: string;
+}>;
+export declare function mergeRestoreManifest(backupManifest: Record<string, unknown>, current: Record<string, unknown>, selection?: PluginSelection): Record<string, unknown>;
+export {};

package/lib/types/catalog-local-match.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Catalog matching for locally linked / file: installs. Shared by the host
+ * restore route and the Market client so both refuse the same wrong guesses.
+ */
+/**
+ * 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 declare function findCatalogEntryForLocal<T extends {
+    name: string;
+    npm?: string | null;
+    url: string;
+}>(plugins: readonly T[], name: string, identities?: readonly string[], hints?: readonly string[]): T | null;
+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 declare 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;
+};

package/lib/types/catalog-npm.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function fileFromTarball(gz: Buffer, wanted: string): Buffer | null;
+/**
+ * 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 declare function catalogFromPackage(registry: string, pkg: string, known?: string, 
+/** The entry to extract; the catalog package carries `plugins.json`, companions theirs. */
+file?: string): Promise<{
+    version: string;
+    data: unknown | null;
+}>;

package/lib/types/changelog.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+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>;
+}
+/**
+ * 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 declare function loadUpdateNotes(force?: boolean): Promise<UpdatesPayload>;
+/** Drop the cached payload (nothing currently invalidates it mid-process). */
+export declare function invalidateUpdateNotes(): void;
+/**
+ * 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 declare function sliceCommitsAt(items: CommitNote[], installed: string | null): {
+    items: CommitNote[];
+    found: boolean;
+};
+/** The repo url key an entry's update notes live under, or null. */
+export declare function repoKeyOf(spec: string): string | null;
+/**
+ * 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 declare function entryForRepo(payload: UpdatesPayload, key: string): UpdatesEntry | undefined;
+export declare function npmPublishTimes(name: string): Promise<{
+    version: string;
+    date: string;
+}[]>;
+/** 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 declare function updateNotesFor(profile: string, explicitDir: string | undefined, name: string): Promise<UpdateNotes>;
+export {};