dsh-plugin-upgrader 1.0.0 → 1.0.2

package/lib/host/manager.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The slice of the host services this plugin uses.
+ *
+ * The published `@deepseek-ai/dsh-plugin-manager` types describe the manager as
+ * the DSH shell sees it, including branded ids and fields this plugin never
+ * touches. Depending on the whole surface would tie the build to one exact
+ * runtime build, so the plugin declares the handful of methods it calls and
+ * accepts the live service structurally. The shapes below follow the runtime
+ * contract and are the only place a contract change has to be edited.
+ *
+ * @module dsh-plugin-upgrader/lib/manager
+ */
+/** Reasons a profile control cannot modify its target. */
+export type ReadOnlyReason = 'management-required' | 'unaddressable';
+/** Localizable management failure. */
+export interface ManagementError {
+    code: string;
+    diagnostic?: string;
+}
+/** Display metadata a bundle manifest can carry, per language. */
+export interface LocalizedMeta {
+    title?: unknown;
+    description?: unknown;
+    icon?: unknown;
+}
+/** One row a bundle's patch declares. */
+export interface BundleRowInfo {
+    rowId: string;
+    moduleName: string;
+    entryId?: string;
+}
+/** One shipped, profile-installed, or discoverable on-demand bundle. */
+export interface BundleInfo {
+    name: string;
+    official: boolean;
+    availability: 'installation' | 'profile' | 'missing';
+    installTarget?: {
+        spec: string;
+        version: string;
+    };
+    version?: string;
+    meta?: LocalizedMeta;
+    description?: string;
+    enabled: boolean;
+    installed: boolean;
+    source?: string;
+    optional: boolean;
+    removable: boolean;
+    readOnlyReason?: ReadOnlyReason;
+    error?: ManagementError;
+    rows: BundleRowInfo[];
+    overrides: string[];
+}
+/** How a package operation failed. */
+export type InstallFailureKind = 'pnpm-missing' | 'timeout' | 'not-found' | 'no-matching-version' | 'network' | 'disk-full' | 'permission' | 'build-blocked' | 'integrity' | 'unknown';
+/** Package operation completion. */
+export interface PackageResult {
+    exitCode: number;
+    output: string;
+    truncated: boolean;
+    logPath: string;
+    kind?: InstallFailureKind;
+    timedOut?: boolean;
+}
+/** Persisted change and its application outcome. */
+export interface ChangeResult {
+    changed: boolean;
+    application: 'applied' | 'restart-required' | 'overridden' | 'failed' | 'cancelled';
+    restartReason?: string;
+    stage: 'install' | 'enable' | 'remove';
+    target: string;
+    enabled?: boolean;
+    error?: ManagementError;
+    warnings?: string[];
+    packageResult?: PackageResult;
+    bundle?: string;
+    version?: string;
+    pendingBuilds?: string[];
+    approvedBuilds?: string[];
+    registries?: (string | null)[];
+    failedAt?: 'registry' | 'spec-host';
+}
+/** What one installation asks for. */
+export interface InstallBundleOptions {
+    enabled?: boolean;
+    saveExact?: boolean;
+    requestId?: string;
+    approvedBuilds?: string[];
+    registry?: string | null;
+}
+/** What `registries()` reports. */
+export interface RegistriesReport {
+    registry: string | null;
+    fallbackRegistries: readonly string[];
+    resolved: string | null;
+}
+/** One step of a batch job, as the browser sends it. */
+export interface StepRecord {
+    name: string;
+    version: string;
+    action?: 'upgrade' | 'switch';
+    enabled?: boolean;
+    approveBuilds?: string[];
+}
+/** The manager methods this plugin calls. */
+export interface PluginManager {
+    listBundles(): Promise<BundleInfo[]>;
+    registries(): Promise<RegistriesReport>;
+    installBundle(spec: string, options?: InstallBundleOptions): Promise<ChangeResult>;
+    removeBundle(name: string): Promise<ChangeResult>;
+    setBundleEnabled(name: string, enabled: boolean): Promise<ChangeResult>;
+    cancelInstall(requestId: string): Promise<{
+        status: 'cancelled' | 'too-late' | 'not-running';
+    }>;
+}
+/** The host plugin context, as far as this plugin reads it. */
+export interface HostContext {
+    get(name: string, strict: false): unknown;
+    effect(callback: () => () => void, label?: string): void;
+    webServer: WebServer;
+}
+/** The host web-server service. */
+export interface WebServer {
+    register(route: WebRoute): () => void;
+}
+/** One route the plugin contributes. */
+export interface WebRoute {
+    kind: 'exact' | 'prefix';
+    /** Absolute pathname, no trailing slash. */
+    path: string;
+    handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void | Promise<void>;
+}
+/** One cached packument, as the overview cache stores it. */
+export interface PackumentEntryLike {
+    at: number;
+    data: unknown;
+}
+/** One cached tag lookup, as the overview cache stores it. */
+export interface TagEntryLike {
+    at: number;
+    tags?: Set<string>;
+    error?: string;
+}
+/**
+ * Narrow `unknown` to the manager, without asserting the whole surface blindly.
+ *
+ * @param value - whatever the context returned.
+ * @returns the manager, or `undefined` when the service is absent.
+ */
+export declare function asPluginManager(value: unknown): PluginManager | undefined;
+//# sourceMappingURL=manager.d.ts.map

package/lib/host/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/host/manager.ts"],"names":[],"mappings":"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"}

package/lib/host/manager.js

@@ -0,0 +1,28 @@
+/**
+ * The slice of the host services this plugin uses.
+ *
+ * The published `@deepseek-ai/dsh-plugin-manager` types describe the manager as
+ * the DSH shell sees it, including branded ids and fields this plugin never
+ * touches. Depending on the whole surface would tie the build to one exact
+ * runtime build, so the plugin declares the handful of methods it calls and
+ * accepts the live service structurally. The shapes below follow the runtime
+ * contract and are the only place a contract change has to be edited.
+ *
+ * @module dsh-plugin-upgrader/lib/manager
+ */
+/**
+ * Narrow `unknown` to the manager, without asserting the whole surface blindly.
+ *
+ * @param value - whatever the context returned.
+ * @returns the manager, or `undefined` when the service is absent.
+ */
+export function asPluginManager(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.listBundles !== 'function' || typeof candidate.installBundle !== 'function') {
+        return undefined;
+    }
+    return candidate;
+}
+//# sourceMappingURL=manager.js.map

package/lib/host/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/host/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA2JH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACjE,MAAM,SAAS,GAAG,KAA+B,CAAA;IACjD,IAAI,OAAO,SAAS,CAAC,WAAW,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;QACjG,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,SAA0B,CAAA;AACnC,CAAC"}

package/lib/host/overview.d.ts

@@ -0,0 +1,52 @@
+import { type SourceKind } from './bundle.ts';
+import { type PackumentEntry, type TagEntry, type VersionRow } from './registry.ts';
+import type { BundleInfo, HostContext, ManagementError, RegistriesReport, ReadOnlyReason } from './manager.ts';
+/** One installed bundle, flattened for the tab. */
+export interface OverviewRow {
+    name: string;
+    version?: string;
+    official: boolean;
+    availability: BundleInfo['availability'];
+    installed: boolean;
+    enabled: boolean;
+    removable: boolean;
+    managed: boolean;
+    source?: string;
+    kind: SourceKind;
+    title: string;
+    description?: string;
+    icon?: string;
+    readOnlyReason?: ReadOnlyReason;
+    error: ManagementError | null;
+    latest?: string;
+    repoUrl?: string;
+    upgradable: boolean;
+    versions: VersionRow[];
+    tags: Record<string, string>;
+    totalVersions: number;
+    versionError?: string;
+}
+/** The whole overview response body. */
+export interface Overview {
+    generatedAt: number;
+    registry: string;
+    registries: RegistriesReport;
+    runtimeVersion: string | null;
+    bundles: OverviewRow[];
+}
+/** Options for one overview build. */
+export interface OverviewOptions {
+    force?: boolean;
+    locale?: 'zh' | 'en';
+}
+/**
+ * Build the overview the tab renders.
+ *
+ * @param ctx - the plugin context.
+ * @param cache - packument cache.
+ * @param tagCache - repository tag cache.
+ * @param options - refresh + language.
+ * @returns the overview payload.
+ */
+export declare function buildOverview(ctx: HostContext, cache: Map<string, PackumentEntry>, tagCache: Map<string, TagEntry>, options: OverviewOptions): Promise<Overview>;
+//# sourceMappingURL=overview.d.ts.map

package/lib/host/overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../src/host/overview.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkD,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7F,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAK9G,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC,CAAA;IACxC,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,EAAE,UAAU,EAAE,CAAA;IACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,wCAAwC;AACxC,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,gBAAgB,CAAA;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC/B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAyFnB"}

package/lib/host/overview.js

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

package/lib/host/overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.js","sourceRoot":"","sources":["../../src/host/overview.ts"],"names":[],"mappings":"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"}

package/lib/host/registry.d.ts

@@ -0,0 +1,116 @@
+import { type PackumentLike, type RepoManifest } from './repo.ts';
+/** How long one registry packument stays fresh. */
+export declare const PACKUMENT_TTL_MS: number;
+/** Registry lookups must not hang a page render. */
+export declare const PACKUMENT_TIMEOUT_MS: number;
+/** Version lists are capped so one huge package cannot flood the tab. */
+export declare const MAX_VERSIONS = 80;
+/**
+ * How long one repository's tag list stays fresh. The GitHub API allows 60
+ * unauthenticated requests an hour and one tag list costs a request per 100
+ * tags, so this is deliberately much longer than the packument TTL.
+ */
+export declare const TAGS_TTL_MS: number;
+/** A failed tag lookup is retried sooner than a good one is refreshed. */
+export declare const TAGS_RETRY_MS: number;
+/** Tag lookups must not hang a page render. */
+export declare const TAGS_TIMEOUT_MS: number;
+/** A version manifest, as far as this module reads it. */
+export interface VersionManifest extends RepoManifest {
+    deprecated?: unknown;
+    engines?: {
+        dsh?: unknown;
+    } | undefined;
+    dsh?: {
+        engines?: {
+            dsh?: unknown;
+        };
+    } | undefined;
+}
+/** The packument fields this module reads beyond {@link PackumentLike}. */
+export interface FullPackument extends PackumentLike {
+    versions?: Record<string, VersionManifest | undefined> | undefined;
+    time?: Record<string, unknown> | undefined;
+}
+/** One cached packument. */
+export interface PackumentEntry {
+    at: number;
+    data: unknown;
+}
+/** One cached tag lookup. */
+export interface TagEntry {
+    at: number;
+    tags?: Set<string>;
+    error?: string;
+}
+/** One version line the tab renders. */
+export interface VersionRow {
+    version: string;
+    time?: string;
+    deprecated?: string;
+    engine?: string;
+    current: boolean;
+    latest: boolean;
+    /** A GitHub path such as `/releases/tag/v1.2.3`, relative to `repoUrl`. */
+    url?: string;
+}
+/** The packument slice the tab renders. */
+export interface ShapedPackument {
+    latest?: string;
+    repoUrl?: string;
+    versions: VersionRow[];
+    tags: Record<string, string>;
+    totalVersions?: number;
+    versionError?: string;
+}
+/**
+ * Fetch one package's packument, with a short-lived cache.
+ *
+ * @param base - registry base URL.
+ * @param packageName - package name.
+ * @param cache - shared cache.
+ * @param force - bypass a fresh cache entry.
+ * @returns the document or a reason.
+ */
+export declare function fetchPackument(base: string, packageName: string, cache: Map<string, PackumentEntry>, force: boolean): Promise<{
+    data?: unknown;
+    error?: string;
+}>;
+/**
+ * Read a repository's tag names from the GitHub API.
+ *
+ * The git ref advertisement (`/info/refs?service=git-upload-pack`) would avoid
+ * the rate limit but stalls for most repositories behind this network, while the
+ * REST list answers in well under a second. Only the first page is read: the
+ * version list itself is capped at 80 newest rows, and tags are ordered newest
+ * first, so a repository with more than 100 tags still resolves every row that
+ * can be shown.
+ *
+ * @param repoUrl - the repository URL.
+ * @param at - the time the lookup started.
+ * @returns the outcome.
+ */
+export declare function fetchTags(repoUrl: string, at: number): Promise<TagEntry>;
+/**
+ * The tag names of a repository, cached.
+ *
+ * A tag list is the only way to know whether `/releases/tag/v<version>` exists.
+ * A failed lookup is cached too, but for less time: the tab must still render
+ * (with repository-level links) while GitHub is rate limiting.
+ *
+ * @param repoUrl - the repository URL.
+ * @param cache - shared cache.
+ * @param force - bypass a fresh cache entry.
+ * @returns the tag names, or `undefined` when unknown.
+ */
+export declare function cachedTags(repoUrl: string, cache: Map<string, TagEntry>, force: boolean): Promise<Set<string> | undefined>;
+/**
+ * Trim one packument down to what the tab renders.
+ *
+ * @param packument - the full registry document.
+ * @param installedVersion - the version in the profile.
+ * @param tagNames - the repository's tag names, when known.
+ * @returns the slice.
+ */
+export declare function shapePackument(packument: FullPackument | undefined, installedVersion: string | undefined, tagNames: ReadonlySet<string> | undefined): ShapedPackument;
+//# sourceMappingURL=registry.d.ts.map

package/lib/host/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/host/registry.ts"],"names":[],"mappings":"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"}

package/lib/host/registry.js

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