@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/catalog/marketplaces.service.js

@@ -8,7 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { CATALOG_ITEM_NAME_RE, marketplaceEntryVersion, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, parsePluginManifest, SDK_VERSION, SEMVER_VERSION_RE, } from "@capybara-hq/plugin-sdk";
+import { CATALOG_ITEM_NAME_RE, marketplaceEntryDeprecation, marketplaceEntryVersion, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, parsePluginManifest, pluginDescription, SDK_VERSION, SEMVER_VERSION_RE, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
@@ -18,7 +18,7 @@ import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
 import { DEPLOYMENT_SECRETS_ORG } from "../extensions/deployment-config-store.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -30,6 +30,7 @@ import { CLAUDE_MARKETPLACE_FILE, parseClaudeMarketplace, } from "./claude/marke
 import { expandGitUrl, GitSourceError, gitErrorDetails, gitLocationIdentity, gitUrlIdentity, normalGitPath, readGitTreeAndOids, resolveGitCommit, } from "./git-source.js";
 import { CatalogSourceLock } from "./locks.js";
 import { fetchMarketplaceManifest, MarketplaceFetchError, MarketplaceInvalidError, marketplaceNetPolicy, marketplaceUrlProblem, } from "./marketplace-fetch.js";
+import { checkMarketplaceIcon, fetchMarketplaceIcon, gitIconPaths, MARKETPLACE_ICON_CONCURRENCY, MARKETPLACE_ICON_FETCHES_MAX, MARKETPLACE_ICON_MAX_BYTES, MARKETPLACE_ICON_RETRY_MS, marketplaceIconUrl, wantedIcons, } from "./marketplace-icons.js";
 import { compareVersions, newestFirst, sameRelease } from "./versions.js";
 /** 官方清单来源的 id。 */
 export const OFFICIAL_MARKETPLACE_ID = "official";
@@ -243,6 +244,20 @@ export function headsToResolve(entries, imported, config, max) {
 export const HOST_VERSIONS = { kernel: KERNEL_VERSION, sdk: SDK_VERSION };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export const entryCompatible = (e) => e.minKernel === undefined || semver.gte(HOST_VERSIONS.kernel, e.minKernel);
+/** Whether the marketplace marks the entry deprecated (`deprecated: true` or with a reason). */
+export const entryDeprecated = (e) => marketplaceEntryDeprecation(e) !== null;
+/**
+ * Refuses importing (or requesting) a deprecated marketplace entry: 409
+ * `marketplace.entry_deprecated`, its reason in the message and details.
+ */
+export function assertEntryNotDeprecated(e) {
+    const d = marketplaceEntryDeprecation(e);
+    if (d === null)
+        return;
+    const version = marketplaceEntryVersion(e);
+    throw new ApiError("marketplace.entry_deprecated", `${e.name}${version !== null ? `@${version}` : ""} is deprecated by its marketplace` +
+        `${d.reason !== null ? `: ${d.reason}` : ""}; import another version`, [{ entry: e.name, version, reason: d.reason }]);
+}
 /**
  * The form of a marketplace address (spec §5.1): `owner/repo` (expanded to GitHub), an https URL
  * whose path ends in `.git`, or any URL with `form: "git"` is a git repository; anything else
@@ -282,7 +297,7 @@ export function hostAllowed(host, config) {
     return allowed.length === 0 || allowed.includes(host.toLowerCase());
 }
 /** Why an entry is not importable from a marketplace of `form`, or undefined when it is. */
-function unimportable(e, form, config) {
+export function unimportable(e, form, config) {
     if ("path" in e.source && form !== "git")
         return "path_needs_git_marketplace";
     const host = entrySourceHost(e);
@@ -292,10 +307,30 @@ function unimportable(e, form, config) {
 }
 /** 来源是否生效：本身启用，official 还要配置没关。 */
 export const sourceEffective = (row, config) => row.enabled && (!row.builtin || config.marketplaces.official.enabled);
+/**
+ * The default entry of a marketplace plugin (`version` `""`: the entry without a version), the
+ * same order as the web's market row (`groupMarketplaceEntries`, apps/web/src/lib/catalog.ts):
+ * the newest `usable` versioned entry, a stable version before a prerelease; else the entry
+ * without a version that is not deprecated; else the newest versioned one that is not deprecated;
+ * else the entry without a version; else the newest.
+ */
+export function pickDefaultEntry(entries, o) {
+    const versioned = entries
+        .filter((e) => e.version !== "")
+        .sort((a, b) => newestFirst(a.version, b.version));
+    const bare = entries.filter((e) => e.version === "");
+    return (versioned.find((e) => o.usable(e) && semver.prerelease(e.version) === null) ??
+        versioned.find(o.usable) ??
+        bare.find((e) => !o.deprecated(e)) ??
+        versioned.find((e) => !o.deprecated(e)) ??
+        bare[0] ??
+        versioned[0]);
+}
 /**
  * Reads a marketplace entry for import: `version` given -> the entry listing that version; omitted
- * -> the newest compatible versioned entry, else the entry without a version, else the newest
- * versioned one (refused later as incompatible). Marketplace missing -> `marketplace.not_found`;
+ * -> {@link pickDefaultEntry} over the compatible, importable entries that are not deprecated
+ * (a fallback is refused later as incompatible or deprecated). Marketplace missing ->
+ * `marketplace.not_found`;
  * marketplace disabled (official offline included), entry or version missing ->
  * `marketplace.entry_not_found`.
  */
@@ -325,13 +360,13 @@ export async function loadMarketplaceEntry(db, config, sourceId, name, version)
         pickedRow = entries.find((e) => e.version === version);
     }
     else {
-        const versioned = entries
-            .filter((e) => e.version !== "")
-            .sort((a, b) => newestFirst(a.version, b.version));
-        pickedRow =
-            versioned.find((e) => entryCompatible(e.entry)) ??
-                entries.find((e) => e.version === "") ??
-                versioned[0];
+        pickedRow = pickDefaultEntry(entries, {
+            // compatible, importable, not deprecated
+            usable: (e) => entryCompatible(e.entry) &&
+                unimportable(e.entry, src.form, config) === undefined &&
+                !entryDeprecated(e.entry),
+            deprecated: (e) => entryDeprecated(e.entry),
+        });
     }
     const picked = pickedRow?.entry;
     if (!picked) {
@@ -353,9 +388,9 @@ export async function loadMarketplaceEntry(db, config, sourceId, name, version)
     };
 }
 /**
- * Marketplaces (D16 / C25 / C26, `/api/v1/admin/marketplaces/*`, enterprise admins only): the official
+ * Marketplaces (D16 / C25 / C26, `/api/v1/admin/marketplaces/*`, super admins only): the official
  * marketplace (config `marketplaces.official.*`, synced at startup into the marketplace with id
- * `official`) and enterprise marketplaces (PG, optional token in secrets). A refresh (maintenance
+ * `official`) and custom marketplaces (PG, optional token in secrets). A refresh (maintenance
  * job `catalogs-refresh` every `marketplaces.refreshIntervalMinutes` minutes, or manual) tries the main
  * URL and then the mirrors with If-None-Match; on success it replaces that marketplace's cached
  * entries as a whole, when all fail (an invalid manifest included) it keeps the previous ones with
@@ -371,7 +406,7 @@ let MarketplacesService = class MarketplacesService {
     log;
     txHost;
     constructor(kdb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
     adminLock, sourceLock, config, keyring, log, txHost) {
         this.kdb = kdb;
         this.adminLock = adminLock;
@@ -447,7 +482,7 @@ let MarketplacesService = class MarketplacesService {
         return (await this.views([row]))[0];
     }
     /**
-     * Adds an enterprise marketplace (audit `marketplace.added`). URL and mirrors must be https,
+     * Adds a custom marketplace (audit `marketplace.added`). URL and mirrors must be https,
      * without user info. The form follows {@link marketplaceForm}; a git marketplace may name a `ref`
      * (branch or tag, default the remote HEAD) and has no mirrors.
      */
@@ -462,6 +497,25 @@ let MarketplacesService = class MarketplacesService {
         await this.writeAdd(actor, id, { ...input, name, form, url }, opts);
         return this.get(id);
     }
+    /**
+     * The read-only checks of {@link add}, for the `Platform` tool's precheck (before the card): the
+     * name, URL and git fields as `add` checks them (throws `validation_failed`), then the source
+     * that has the same URL and ref already, if any (adding a duplicate is allowed; the tool points
+     * the agent at the existing source instead).
+     */
+    async checkAdd(input) {
+        this.checkName(input.name);
+        const { form, url } = marketplaceForm(input.url);
+        this.checkUrls(url, []);
+        this.checkGitFields(form, input.ref ?? null, []);
+        const same = await this.db
+            .selectFrom("marketplaces")
+            .select(["id", "name"])
+            .where("url", "=", url)
+            .where("ref", input.ref === undefined ? "is" : "=", input.ref ?? null)
+            .executeTakeFirst();
+        return same ?? null;
+    }
     async writeAdd(actor, id, input, opts) {
         const { name, url, form } = input;
         const t = this.db;
@@ -495,11 +549,12 @@ let MarketplacesService = class MarketplacesService {
                 ...(input.ref !== undefined && { ref: input.ref }),
                 mirrors: input.mirrors ?? [],
                 hasToken: input.token !== undefined,
+                ...opts.auditDetail,
             },
         });
     }
     /**
-     * Updates an enterprise marketplace (audit `marketplace.updated`, listing the changed fields, the
+     * Updates a custom marketplace (audit `marketplace.updated`, listing the changed fields, the
      * token's value never recorded; not written when unchanged). `token: null` clears the token.
      * Official only takes `enabled`, any other field -> `marketplace.builtin`. Changing the URL, form
      * or ref clears the ETag and the last commit (the next refresh reads everything again); a new URL
@@ -604,11 +659,12 @@ let MarketplacesService = class MarketplacesService {
                 ...(set.url !== undefined && { url: set.url }),
                 ...(set.form !== undefined && { form: set.form }),
                 ...(set.ref !== undefined && { ref: set.ref }),
+                ...opts.auditDetail,
             },
         });
     }
     /**
-     * Deletes an enterprise marketplace (audit `marketplace.removed`): its cached entries and token
+     * Deletes a custom marketplace (audit `marketplace.removed`): its cached entries and token
      * are deleted; imported catalog items are kept (their marketplace becomes null). Official can
      * only be disabled -> `marketplace.builtin`.
      */
@@ -632,7 +688,7 @@ let MarketplacesService = class MarketplacesService {
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
             action: "marketplace.removed",
             target: id,
-            detail: { name: row.name, url: row.url },
+            detail: { name: row.name, url: row.url, ...opts.auditDetail },
         });
     }
     /**
@@ -731,6 +787,24 @@ let MarketplacesService = class MarketplacesService {
             this.log.info("marketplace changed during refresh; result discarded", { marketplace: id });
             return this.get(id);
         }
+        if (outcome !== undefined) {
+            // a failed icon never fails the refresh: the entry shows its initial
+            try {
+                await this.syncIcons(row, outcome === "not_modified" ? undefined : outcome.icons, signal);
+                // only now is the commit fully synced: a refresh at it may be not_modified from here on
+                if (outcome !== "not_modified" && outcome.commit !== undefined) {
+                    await this.db
+                        .updateTable("marketplaces")
+                        .set({ icons_commit: outcome.commit })
+                        .where("id", "=", id)
+                        .where("last_commit", "=", outcome.commit)
+                        .execute();
+                }
+            }
+            catch (err) {
+                this.log.warn("marketplace icons not updated", { marketplace: id, err });
+            }
+        }
         if (from !== status) {
             if (status === "error") {
                 this.log.warn("marketplace refresh failed", { marketplace: id, error: lastError });
@@ -750,8 +824,9 @@ let MarketplacesService = class MarketplacesService {
     }
     /**
      * Reads a git marketplace (spec §5.1): resolves `ref` (default the remote HEAD); the same commit
-     * as the last refresh -> `not_modified` (nothing else is fetched). Otherwise only what the root
-     * needs is read, in this order: `.capybara-plugin/marketplace.json` (at most
+     * as the last refresh, whose path icons were stored too (`icons_commit`) -> `not_modified`
+     * (nothing else is fetched; a commit whose icons were not stored is read again). Otherwise only
+     * what the root needs is read, in this order: `.capybara-plugin/marketplace.json` (at most
      * `marketplaces.maxIndexBytes`, validated like an http manifest); `.claude-plugin/marketplace.json`
      * (a Claude Code marketplace: each entry's component fields and `strict` become its overlay, and
      * entries Capybara cannot store are `skipped`); else a single-plugin repo (the root has
@@ -769,12 +844,12 @@ let MarketplacesService = class MarketplacesService {
         };
         const loc = { url: row.url, ...(row.ref !== null && { ref: row.ref }) };
         const commit = await resolveGitCommit(loc, options);
-        if (commit === row.last_commit)
+        if (commit === row.last_commit && commit === row.icons_commit)
             return "not_modified";
         const MANIFEST = ".capybara-plugin/marketplace.json";
         let hasSkills = false;
         const dec = (b) => new TextDecoder().decode(b);
-        const { files, trees } = await readGitTreeAndOids({ url: row.url, commit }, {
+        const { files, trees, blobs: icons, } = await readGitTreeAndOids({ url: row.url, commit }, {
             ...options,
             include: (path, type) => {
                 if (path === "skills" && type === "tree")
@@ -790,6 +865,13 @@ let MarketplacesService = class MarketplacesService {
             trees: (read) => read.has(MANIFEST) || !read.has(CLAUDE_MARKETPLACE_FILE)
                 ? pathEntryDirs(read.get(MANIFEST), config.marketplaces.maxIndexBytes)
                 : claudePathEntryDirs(read.get(CLAUDE_MARKETPLACE_FILE), config.marketplaces.maxIndexBytes, config.marketplaces.allowInsecureLoopback),
+            // the icon files the entries name (a Claude Code marketplace names none)
+            blobs: {
+                paths: (read) => read.has(MANIFEST) || !read.has(CLAUDE_MARKETPLACE_FILE)
+                    ? gitIconPaths(read, MANIFEST, config.marketplaces.maxIndexBytes, MARKETPLACE_ICON_FETCHES_MAX)
+                    : [],
+                maxBytes: MARKETPLACE_ICON_MAX_BYTES,
+            },
         });
         const raw = files.get(MANIFEST);
         const claudeRaw = files.get(CLAUDE_MARKETPLACE_FILE);
@@ -847,9 +929,16 @@ let MarketplacesService = class MarketplacesService {
                 if ("errors" in m) {
                     throw new MarketplaceInvalidError(`the repository is a single plugin, but its ${PLUGIN_MANIFEST_FILE} is invalid: ${m.errors.slice(0, 5).join("; ")}`, m.errors);
                 }
+                const d = pluginDescription(m.description);
                 entry = {
                     name: m.name,
-                    summary: { en: m.description.slice(0, SUMMARY_MAX) },
+                    summary: {
+                        en: d.en.slice(0, SUMMARY_MAX),
+                        ...(d.zh !== undefined && { zh: d.zh.slice(0, SUMMARY_MAX) }),
+                    },
+                    ...(m.displayName !== undefined && { displayName: m.displayName }),
+                    // the plugin's own icon, read from the same commit
+                    ...(m.icon !== undefined && { icon: `./${normalGitPath(m.icon)}` }),
                     version: m.version,
                     source: { path: "." },
                 };
@@ -869,7 +958,7 @@ let MarketplacesService = class MarketplacesService {
             }
             manifest = { schemaVersion: 1, name: row.name, plugins: [entry] };
         }
-        return { manifest, etag: null, commit, trees };
+        return { manifest, etag: null, commit, trees, icons };
     }
     /**
      * Resolves the branch heads of the entries {@link headsToResolve} picks (at most
@@ -935,7 +1024,200 @@ let MarketplacesService = class MarketplacesService {
         }));
         return out;
     }
-    /** The token of an enterprise marketplace (undefined without one; official never has one). */
+    /**
+     * Brings the marketplace's stored icons (`marketplace_icons`) in line with its stored entries
+     * after a refresh (outside any transaction: downloads first, then one short write). A repository
+     * path (git marketplaces) is taken from `fresh`, the files of the commit just read, and kept as
+     * stored when the commit did not change (`fresh` undefined). A URL is downloaded only when it is
+     * not stored yet (its content is treated as fixed), at most {@link MARKETPLACE_ICON_FETCHES_MAX}
+     * per refresh, under the marketplace network rules and `marketplaces.allowedHosts`, never with
+     * the token. A failed download is remembered (`marketplace_icon_failures`) and retried only after
+     * {@link MARKETPLACE_ICON_RETRY_MS}, URLs never tried first, so broken URLs never starve the
+     * cap. An icon that is missing, too large or not a real svg / png is skipped and logged; icons
+     * (and failures) no entry names any more are deleted.
+     */
+    async syncIcons(row, fresh, signal) {
+        const config = this.config.get();
+        const entries = await this.db
+            .selectFrom("marketplace_entries")
+            .select("entry")
+            .where("source_id", "=", row.id)
+            .execute();
+        const { paths, urls } = wantedIcons(entries.map((r) => r.entry), row.form);
+        const have = new Set((await this.db
+            .selectFrom("marketplace_icons")
+            .select("ref")
+            .where("source_id", "=", row.id)
+            .execute()).map((r) => r.ref));
+        // the URLs that failed before, oldest failure first, and whether their backoff is over
+        const failures = await this.db
+            .selectFrom("marketplace_icon_failures")
+            .select([
+            "ref",
+            sql `failed_at <= now() - make_interval(secs => ${MARKETPLACE_ICON_RETRY_MS / 1000})`.as("due"),
+        ])
+            .where("source_id", "=", row.id)
+            .orderBy("failed_at")
+            .orderBy("ref")
+            .execute();
+        const failedBefore = new Map(failures.map((f) => [f.ref, f.due]));
+        const put = [];
+        const keep = new Set();
+        const problems = [];
+        for (const ref of paths) {
+            if (fresh === undefined) {
+                if (have.has(ref))
+                    keep.add(ref);
+                continue;
+            }
+            const data = fresh.get(ref.slice(2));
+            const r = data === undefined
+                ? `${ref} is not a file of at most ${MARKETPLACE_ICON_MAX_BYTES} bytes in the repository`
+                : checkMarketplaceIcon(ref, data);
+            if (typeof r === "string")
+                problems.push({ icon: ref, problem: r });
+            else
+                put.push({ ref, icon: r });
+        }
+        // IPv6 hostnames come bracketed from URL; allowedHosts entries are written without brackets
+        const hostOf = (url) => new URL(url).hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+        const neverTried = [];
+        for (const url of urls) {
+            if (have.has(url)) {
+                keep.add(url);
+                continue;
+            }
+            const host = hostOf(url);
+            if (!hostAllowed(host, config)) {
+                problems.push({ icon: url, problem: `${host} is not in marketplaces.allowedHosts` });
+            }
+            else if (!failedBefore.has(url)) {
+                neverTried.push(url);
+            }
+        }
+        // retries after the never-tried URLs, oldest failure first, within the cap
+        const retries = failures
+            .filter((f) => f.due && urls.has(f.ref) && !have.has(f.ref))
+            .map((f) => f.ref)
+            .filter((url) => hostAllowed(hostOf(url), config));
+        const toFetch = [...neverTried, ...retries].slice(0, MARKETPLACE_ICON_FETCHES_MAX);
+        const net = marketplaceNetPolicy(config);
+        const queue = [...toFetch];
+        const failed = [];
+        await Promise.all(Array.from({ length: Math.min(MARKETPLACE_ICON_CONCURRENCY, queue.length) }, async () => {
+            for (let url = queue.shift(); url !== undefined; url = queue.shift()) {
+                if (signal.aborted)
+                    return;
+                const r = await fetchMarketplaceIcon(url, { net, signal });
+                if (typeof r === "string") {
+                    problems.push({ icon: url, problem: r });
+                    // an aborted refresh says nothing about the URL
+                    if (!signal.aborted)
+                        failed.push(url);
+                }
+                else
+                    put.push({ ref: url, icon: r });
+            }
+        }));
+        if (problems.length > 0) {
+            this.log.warn("marketplace icons skipped", {
+                marketplace: row.id,
+                count: problems.length,
+                problems: problems.slice(0, 5),
+            });
+        }
+        const gone = [...have].filter((ref) => !keep.has(ref) && !put.some((p) => p.ref === ref));
+        // failures of URLs now stored or named by no entry
+        const cleared = [...failedBefore.keys()].filter((ref) => !urls.has(ref) || put.some((p) => p.ref === ref));
+        if (put.length > 0 || gone.length > 0 || failed.length > 0 || cleared.length > 0) {
+            await this.writeIcons(row.id, { put, gone, failed, cleared });
+        }
+    }
+    /**
+     * Writes a refresh's icons: upserts `put`, deletes `gone`, records the `failed` downloads and
+     * forgets the `cleared` failures (see {@link syncIcons}).
+     */
+    async writeIcons(id, w) {
+        const t = this.db;
+        if (w.gone.length > 0) {
+            await t
+                .deleteFrom("marketplace_icons")
+                .where("source_id", "=", id)
+                .where("ref", "in", w.gone)
+                .execute();
+        }
+        for (const { ref, icon } of w.put) {
+            const values = {
+                sha256: icon.sha256,
+                content_type: icon.contentType,
+                data: Buffer.from(icon.data),
+                fetched_at: sql `now()`,
+            };
+            await t
+                .insertInto("marketplace_icons")
+                .values({ source_id: id, ref, ...values })
+                .onConflict((oc) => oc.columns(["source_id", "ref"]).doUpdateSet(values))
+                .execute();
+        }
+        if (w.cleared.length > 0) {
+            await t
+                .deleteFrom("marketplace_icon_failures")
+                .where("source_id", "=", id)
+                .where("ref", "in", w.cleared)
+                .execute();
+        }
+        // sorted: two replicas refreshing at once lock the rows in the same order
+        for (const ref of [...w.failed].sort()) {
+            await t
+                .insertInto("marketplace_icon_failures")
+                .values({ source_id: id, ref })
+                .onConflict((oc) => oc.columns(["source_id", "ref"]).doUpdateSet({
+                failed_at: sql `now()`,
+                attempts: sql `marketplace_icon_failures.attempts + 1`,
+            }))
+                .execute();
+        }
+    }
+    /**
+     * A stored marketplace icon by its sha256 (the address the entries carry); not stored ->
+     * `catalog.icon_not_found`. Read from PG, never from the network. `browsable` (the org route):
+     * the marketplace must also be one the org browse lists (effective), else not found.
+     */
+    async icon(id, sha256, opts = {}) {
+        if (opts.browsable) {
+            // the org browse lists enabled marketplaces only (official also needs the config on)
+            const m = await this.db
+                .selectFrom("marketplaces")
+                .select(["builtin", "enabled"])
+                .where("id", "=", id)
+                .executeTakeFirst();
+            if (!m || !sourceEffective(m, this.config.get())) {
+                throw new ApiError("catalog.icon_not_found", "This marketplace has no such icon");
+            }
+        }
+        const row = /^[0-9a-f]{64}$/.test(sha256)
+            ? await this.db
+                .selectFrom("marketplace_icons")
+                .select(["content_type", "data"])
+                .where("source_id", "=", id)
+                .where("sha256", "=", sha256)
+                .limit(1)
+                .executeTakeFirst()
+            : undefined;
+        if (!row)
+            throw new ApiError("catalog.icon_not_found", "This marketplace has no such icon");
+        // checked again on read, like a catalog icon (`readCatalogIcon`): PG may have been changed
+        const data = new Uint8Array(row.data);
+        const checked = checkMarketplaceIcon(row.content_type === "image/svg+xml" ? "icon.svg" : "icon.png", data);
+        if (typeof checked === "string") {
+            throw new ApiError("internal", `Stored marketplace icon is invalid: ${checked}`);
+        }
+        if (checked.sha256 !== sha256) {
+            throw new ApiError("internal", "Stored marketplace icon does not match its recorded hash");
+        }
+        return { contentType: checked.contentType, data };
+    }
+    /** The token of a custom marketplace (undefined without one; official never has one). */
     async token(id) {
         return (await this.secrets().get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) ?? undefined;
     }
@@ -966,7 +1248,9 @@ let MarketplacesService = class MarketplacesService {
      * first), marketplace, at most {@link MARKETPLACE_ENTRIES_MAX}; `truncated` means there are more
      * (the UI suggests narrowing the filter).
      */
-    async entries(q = {}) {
+    async entries(q = {}, 
+    /** The URL of a stored marketplace icon (default: the admin route). */
+    iconUrl = marketplaceIconUrl) {
         const config = this.config.get();
         let query = this.db
             .selectFrom("marketplace_entries as e")
@@ -1000,6 +1284,8 @@ let MarketplacesService = class MarketplacesService {
                 eb(sql `coalesce(e.npm, '')`, "ilike", like),
                 eb(sql `e.entry->'summary'->>'en'`, "ilike", like),
                 eb(sql `coalesce(e.entry->'summary'->>'zh', '')`, "ilike", like),
+                eb(sql `coalesce(e.entry->'displayName'->>'en', '')`, "ilike", like),
+                eb(sql `coalesce(e.entry->'displayName'->>'zh', '')`, "ilike", like),
             ]));
         }
         const fetched = await query.execute();
@@ -1044,6 +1330,16 @@ let MarketplacesService = class MarketplacesService {
             a.imported.sort(newestFirst);
             a.versions = a.imported.map((v) => v.version);
         }
+        const iconRows = await this.db
+            .selectFrom("marketplace_icons")
+            .select(["source_id", "ref", "sha256"])
+            .where("source_id", "in", [...new Set(rows.map((r) => r.source_id))])
+            .execute();
+        const iconOf = new Map(iconRows.map((i) => [`${i.source_id}\0${i.ref}`, i.sha256]));
+        const iconUrlOf = (sourceId, ref) => {
+            const sha = ref === undefined ? undefined : iconOf.get(`${sourceId}\0${ref}`);
+            return sha === undefined ? null : iconUrl(sourceId, sha);
+        };
         const views = rows.map((r) => {
             const e = r.entry;
             const version = marketplaceEntryVersion(e);
@@ -1058,17 +1354,25 @@ let MarketplacesService = class MarketplacesService {
                 name: r.name,
                 version,
                 summary: e.summary,
+                displayName: e.displayName ?? null,
                 minKernel: e.minKernel ?? null,
                 homepage: e.homepage ?? null,
                 permissions: e.permissions ?? null,
                 source: e.source,
+                deprecated: marketplaceEntryDeprecation(e),
                 format: r.claude === null ? "capybara" : "claude-code",
                 compatible,
                 importable,
                 ...(reason !== undefined && { reason }),
                 adopted: adopted ? { itemId: adopted.itemId, versions: [...adopted.versions] } : null,
-                newerAvailable: compatible && version !== null && top !== undefined && compareVersions(version, top) > 0,
+                icon: iconUrlOf(r.source_id, e.icon),
+                newerAvailable: compatible &&
+                    !entryDeprecated(e) &&
+                    version !== null &&
+                    top !== undefined &&
+                    compareVersions(version, top) > 0,
                 contentChanged: adopted !== null &&
+                    !entryDeprecated(e) &&
                     entryContentChanged(e, {
                         marketplaceId: r.source_id,
                         headCommit: r.head_commit,
@@ -1155,6 +1459,7 @@ let MarketplacesService = class MarketplacesService {
                     from: cur.last_status,
                     to: status,
                     ...(lastError !== null && { error: lastError }),
+                    ...opts.auditDetail,
                 },
             });
         }
@@ -1272,6 +1577,9 @@ __decorate([
 __decorate([
     Transactional()
 ], MarketplacesService.prototype, "remove", null);
+__decorate([
+    Transactional()
+], MarketplacesService.prototype, "writeIcons", null);
 __decorate([
     Transactional()
 ], MarketplacesService.prototype, "recordRefresh", null);
@@ -1281,7 +1589,7 @@ __decorate([
 MarketplacesService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(EnterpriseAdminLock)),
+    __param(1, Inject(SuperAdminLock)),
     __param(2, Inject(CatalogSourceLock)),
     __param(3, Inject(KernelConfigService)),
     __param(4, Inject(KEYRING)),