@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/catalog/git-source.d.ts

@@ -115,13 +115,21 @@ export type ReadGitTreeOptions = GitOptions & {
  * {@link readGitTree}, plus the git tree oids of directories at the same commit: `trees` gets the
  * files read and returns directory paths relative to the repository root (`.` is the root); each
  * one that exists and is a directory gets its tree oid (equal oids mean equal contents, so a
- * plugin directory that did not change keeps its oid across commits).
+ * plugin directory that did not change keeps its oid across commits). `blobs` likewise names more
+ * files (paths relative to the root, from the same fetched commit, nothing else is downloaded):
+ * each that exists as a plain file of at most `maxBytes` is in `blobs` of the result; a missing
+ * path, a directory, a symlink, a submodule or a larger file is left out (never an error).
  */
 export declare function readGitTreeAndOids(loc: GitLocation & {
     commit: string;
 }, o: ReadGitTreeOptions & {
     trees?: (files: Map<string, Uint8Array>) => string[];
+    blobs?: {
+        paths: (files: Map<string, Uint8Array>) => string[];
+        maxBytes: number;
+    };
 }): Promise<{
     files: Map<string, Uint8Array>;
     trees: Map<string, string>;
+    blobs: Map<string, Uint8Array>;
 }>;

package/dist/catalog/git-source.js

@@ -373,7 +373,10 @@ export async function readGitTree(loc, o) {
  * {@link readGitTree}, plus the git tree oids of directories at the same commit: `trees` gets the
  * files read and returns directory paths relative to the repository root (`.` is the root); each
  * one that exists and is a directory gets its tree oid (equal oids mean equal contents, so a
- * plugin directory that did not change keeps its oid across commits).
+ * plugin directory that did not change keeps its oid across commits). `blobs` likewise names more
+ * files (paths relative to the root, from the same fetched commit, nothing else is downloaded):
+ * each that exists as a plain file of at most `maxBytes` is in `blobs` of the result; a missing
+ * path, a directory, a symlink, a submodule or a larger file is left out (never an error).
  */
 export async function readGitTreeAndOids(loc, o) {
     if (!SHA_RE.test(loc.commit))
@@ -509,7 +512,31 @@ export async function readGitTreeAndOids(loc, o) {
             if (oid !== undefined)
                 trees.set(dir, oid);
         }
-        return { files: sorted, trees };
+        const blobs = new Map();
+        const wanted = o.blobs;
+        for (const path of wanted?.paths(sorted).slice(0, GIT_LIMITS.maxFiles) ?? []) {
+            const want = pathSegments(path);
+            if (want === undefined || want.length === 0 || blobs.has(path))
+                continue;
+            let oid = c.tree;
+            for (const [i, seg] of want.entries()) {
+                const { tree: entries } = await git.readTree({ fs, gitdir, oid, cache });
+                const e = entries.find((x) => x.path === seg);
+                const last = i === want.length - 1;
+                oid =
+                    e !== undefined && e.mode !== "120000" && e.type === (last ? "blob" : "tree")
+                        ? e.oid
+                        : undefined;
+                if (oid === undefined)
+                    break;
+            }
+            if (oid === undefined)
+                continue;
+            const { blob } = await git.readBlob({ fs, gitdir, oid, cache });
+            if (wanted !== undefined && blob.byteLength <= wanted.maxBytes)
+                blobs.set(path, blob);
+        }
+        return { files: sorted, trees, blobs };
     }
     catch (e) {
         throw mapError(e, op, o, what);

package/dist/catalog/job-ids.d.ts

@@ -0,0 +1,45 @@
+/** The catalog's periodic jobs (a leaf module: no imports). */
+/**
+ * Periodic marketplace refresh (C26), every `marketplaces.refreshIntervalMinutes` (a
+ * `@LockedInterval`, once per tick across replicas): refreshes each enabled marketplace in turn.
+ */
+export declare const MARKETPLACES_REFRESH_JOB = "catalogs-refresh";
+/** The BullMQ repeatable scheduler the refresh had before it became `@LockedInterval` (retired). */
+export declare const MARKETPLACES_REFRESH_SCHEDULER_ID = "catalogs-refresh-every";
+/**
+ * Hourly cleanup of plugin import staging (T25, F-AE; a `@LockedCron`): deletes expired (24-hour)
+ * staging rows and their object storage prefixes (`PluginImport.cleanupExpired`).
+ */
+export declare const PLUGIN_STAGING_CLEANUP_JOB = "app-staging-cleanup";
+/** The BullMQ repeatable scheduler the cleanup had before it became `@LockedCron` (retired). */
+export declare const PLUGIN_STAGING_CLEANUP_SCHEDULER_ID = "app-staging-cleanup-hourly";
+/**
+ * The one-off job that takes out the extension of a removed org-owned plugin (spec §14, P3-20,
+ * P3-21; `OwnedPluginCleanup.run`), on `cap-kernel-maintenance`.
+ */
+export declare const OWNED_PLUGIN_CLEANUP_JOB = "owned-plugin-cleanup";
+/** The daily `@LockedCron` repairing lost {@link OWNED_PLUGIN_CLEANUP_JOB} enqueues. */
+export declare const OWNED_PLUGIN_CLEANUP_SWEEP_JOB = "owned-plugin-cleanup-sweep";
+/** The data of an {@link OWNED_PLUGIN_CLEANUP_JOB}. */
+export interface OwnedPluginCleanupData {
+    itemId: string;
+}
+/**
+ * The cleanup job of one removed item: id `owned-plugin-cleanup-<itemId>` (no `:`: item ids are
+ * UUIDs), removed when done so a later enqueue of the same item is not swallowed; the job is
+ * idempotent, so a few retries are safe.
+ */
+export declare function ownedPluginCleanupJob(itemId: string): {
+    name: string;
+    data: OwnedPluginCleanupData;
+    opts: {
+        jobId: string;
+        attempts: number;
+        backoff: {
+            type: "exponential";
+            delay: number;
+        };
+        removeOnComplete: true;
+        removeOnFail: true;
+    };
+};

package/dist/catalog/job-ids.js

@@ -0,0 +1,40 @@
+/** The catalog's periodic jobs (a leaf module: no imports). */
+/**
+ * Periodic marketplace refresh (C26), every `marketplaces.refreshIntervalMinutes` (a
+ * `@LockedInterval`, once per tick across replicas): refreshes each enabled marketplace in turn.
+ */
+export const MARKETPLACES_REFRESH_JOB = "catalogs-refresh";
+/** The BullMQ repeatable scheduler the refresh had before it became `@LockedInterval` (retired). */
+export const MARKETPLACES_REFRESH_SCHEDULER_ID = "catalogs-refresh-every";
+/**
+ * Hourly cleanup of plugin import staging (T25, F-AE; a `@LockedCron`): deletes expired (24-hour)
+ * staging rows and their object storage prefixes (`PluginImport.cleanupExpired`).
+ */
+export const PLUGIN_STAGING_CLEANUP_JOB = "app-staging-cleanup";
+/** The BullMQ repeatable scheduler the cleanup had before it became `@LockedCron` (retired). */
+export const PLUGIN_STAGING_CLEANUP_SCHEDULER_ID = "app-staging-cleanup-hourly";
+/**
+ * The one-off job that takes out the extension of a removed org-owned plugin (spec §14, P3-20,
+ * P3-21; `OwnedPluginCleanup.run`), on `cap-kernel-maintenance`.
+ */
+export const OWNED_PLUGIN_CLEANUP_JOB = "owned-plugin-cleanup";
+/** The daily `@LockedCron` repairing lost {@link OWNED_PLUGIN_CLEANUP_JOB} enqueues. */
+export const OWNED_PLUGIN_CLEANUP_SWEEP_JOB = "owned-plugin-cleanup-sweep";
+/**
+ * The cleanup job of one removed item: id `owned-plugin-cleanup-<itemId>` (no `:`: item ids are
+ * UUIDs), removed when done so a later enqueue of the same item is not swallowed; the job is
+ * idempotent, so a few retries are safe.
+ */
+export function ownedPluginCleanupJob(itemId) {
+    return {
+        name: OWNED_PLUGIN_CLEANUP_JOB,
+        data: { itemId },
+        opts: {
+            jobId: `${OWNED_PLUGIN_CLEANUP_JOB}-${itemId}`,
+            attempts: 3,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    };
+}

package/dist/catalog/jobs.d.ts

@@ -0,0 +1,27 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { MarketplacesService } from "./marketplaces.service.js";
+import { PluginImport } from "./plugin-import.js";
+/**
+ * The catalog's periodic jobs, each run once per tick across replicas: the marketplace refresh
+ * (`catalogs-refresh`, every `marketplaces.refreshIntervalMinutes` and once after the start:
+ * `@LockedInterval` with `runOnStart`) and the
+ * hourly cleanup of expired plugin import staging (`app-staging-cleanup`: `@LockedCron`).
+ */
+export declare class CatalogJobs {
+    private readonly marketplaces;
+    private readonly imports;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(marketplaces: MarketplacesService, imports: PluginImport, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    /**
+     * Refreshes every enabled marketplace in turn (overall deadline
+     * {@link MARKETPLACES_REFRESH_DEADLINE_MS}; the job's signal aborts it: the stop, or the run
+     * lock lost).
+     */
+    refreshMarketplaces(stop?: AbortSignal): Promise<void>;
+    /** Deletes expired staging rows and their objects. */
+    cleanupStaging(): Promise<void>;
+}

package/dist/catalog/jobs.js

@@ -0,0 +1,70 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { LockedInterval } from "../infra/schedule/locked-interval.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MARKETPLACES_REFRESH_JOB, PLUGIN_STAGING_CLEANUP_JOB } from "./job-ids.js";
+import { MARKETPLACES_REFRESH_DEADLINE_MS, MarketplacesService } from "./marketplaces.service.js";
+import { PluginImport } from "./plugin-import.js";
+/**
+ * The catalog's periodic jobs, each run once per tick across replicas: the marketplace refresh
+ * (`catalogs-refresh`, every `marketplaces.refreshIntervalMinutes` and once after the start:
+ * `@LockedInterval` with `runOnStart`) and the
+ * hourly cleanup of expired plugin import staging (`app-staging-cleanup`: `@LockedCron`).
+ */
+let CatalogJobs = class CatalogJobs {
+    marketplaces;
+    imports;
+    config;
+    lockService;
+    log;
+    constructor(marketplaces, imports, config, lockService, log) {
+        this.marketplaces = marketplaces;
+        this.imports = imports;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    /**
+     * Refreshes every enabled marketplace in turn (overall deadline
+     * {@link MARKETPLACES_REFRESH_DEADLINE_MS}; the job's signal aborts it: the stop, or the run
+     * lock lost).
+     */
+    async refreshMarketplaces(stop) {
+        const deadline = AbortSignal.timeout(MARKETPLACES_REFRESH_DEADLINE_MS);
+        await this.marketplaces.refreshAll(stop ? AbortSignal.any([deadline, stop]) : deadline);
+    }
+    /** Deletes expired staging rows and their objects. */
+    async cleanupStaging() {
+        const n = await this.imports.cleanupExpired();
+        if (n > 0)
+            this.log.info("expired plugin imports cleaned up", { count: n });
+    }
+};
+__decorate([
+    LockedInterval(MARKETPLACES_REFRESH_JOB, (c) => c.marketplaces.refreshIntervalMinutes * 60_000, 
+    // a fresh deployment's marketplaces are refreshed right after the start
+    { runOnStart: true })
+], CatalogJobs.prototype, "refreshMarketplaces", null);
+__decorate([
+    LockedCron("0 * * * *", { name: PLUGIN_STAGING_CLEANUP_JOB })
+], CatalogJobs.prototype, "cleanupStaging", null);
+CatalogJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(MarketplacesService)),
+    __param(1, Inject(PluginImport)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], CatalogJobs);
+export { CatalogJobs };

package/dist/catalog/locks.d.ts

@@ -0,0 +1,24 @@
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * Serializes the writes of one marketplace's cached entries and refresh status (a refresh's
+ * result against concurrent refreshes and the admin's changes). Joins the caller's transaction
+ * (`mandatory`), which holds the lock until it ends.
+ */
+export declare class CatalogSourceLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(marketplaceId: string): Promise<void>;
+}
+/**
+ * Serializes the imports of one catalog item name (the conflict re-check and the item / version
+ * write of a confirm), including a first import that has no item row to lock yet. Joins the
+ * caller's transaction (`mandatory`).
+ */
+export declare class CatalogItemLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(name: string): Promise<void>;
+}

package/dist/catalog/locks.js

@@ -0,0 +1,63 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * Serializes the writes of one marketplace's cached entries and refresh status (a refresh's
+ * result against concurrent refreshes and the admin's changes). Joins the caller's transaction
+ * (`mandatory`), which holds the lock until it ends.
+ */
+let CatalogSourceLock = class CatalogSourceLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(marketplaceId) {
+        await this.xactLock.lock(`capybara.catalog-source:${marketplaceId}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], CatalogSourceLock.prototype, "lock", null);
+CatalogSourceLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], CatalogSourceLock);
+export { CatalogSourceLock };
+/**
+ * Serializes the imports of one catalog item name (the conflict re-check and the item / version
+ * write of a confirm), including a first import that has no item row to lock yet. Joins the
+ * caller's transaction (`mandatory`).
+ */
+let CatalogItemLock = class CatalogItemLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(name) {
+        await this.xactLock.lock(`capybara.directory-item:${name}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], CatalogItemLock.prototype, "lock", null);
+CatalogItemLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], CatalogItemLock);
+export { CatalogItemLock };

package/dist/catalog/marketplace-fetch.d.ts

@@ -3,7 +3,7 @@ import type { KernelConfig } from "../config/schema.js";
 import { type LookupFn, NetDeniedError, type NetPolicy } from "../net/public-address.js";
 /**
  * Fetching a marketplace manifest `marketplace.json` (C26, spec §5.2) and a marketplace's archive
- * sources. The URLs come from an enterprise admin or the config, but responses are always hostile
+ * sources. The URLs come from a super admin or the config, but responses are always hostile
  * input:
  * - https only (`allowInsecureLoopback`, tests only, allows http on loopback addresses), no user
  *   info in the URL;

package/dist/catalog/marketplace-icons.d.ts

@@ -0,0 +1,64 @@
+import { type MarketplaceEntry } from "@capybara-hq/plugin-sdk";
+import { type LookupFn, type NetPolicy } from "../net/public-address.js";
+/**
+ * Marketplace entry icons (maintainer decision 2026-11-08; plugin component management spec §16):
+ * the icon a marketplace entry names for its plugin before it is imported. An entry's `icon` is an
+ * https URL or a path in a git marketplace's repository (SDK `MarketplaceEntry.icon`). The refresh
+ * reads each one (a URL through `net/safeFetch` under the marketplace network rules and
+ * `marketplaces.allowedHosts`, never with the marketplace token; a path from the commit it fetched
+ * anyway), keeps those that really are an svg / png of at most 64 KiB in `marketplace_icons`, and
+ * the admin market list serves them like plugin icons (`sendCatalogIcon`). A failed or invalid
+ * icon is only logged: the entry has no icon and the list shows its initial.
+ */
+/** The timeout of one icon download. */
+export declare const MARKETPLACE_ICON_TIMEOUT_MS = 10000;
+/** At most this many icon URLs are downloaded per refresh (the rest wait for the next one). */
+export declare const MARKETPLACE_ICON_FETCHES_MAX = 100;
+/** How long after a failed download an icon URL is tried again (by a later refresh). */
+export declare const MARKETPLACE_ICON_RETRY_MS: number;
+/** Parallel icon downloads of one refresh. */
+export declare const MARKETPLACE_ICON_CONCURRENCY = 4;
+/** The largest icon (the plugin icon limit). */
+export declare const MARKETPLACE_ICON_MAX_BYTES: number;
+/** A stored icon: its content type and sha256 (the address the admin route serves it at). */
+export interface CheckedIcon {
+    contentType: "image/svg+xml" | "image/png";
+    sha256: string;
+    data: Uint8Array;
+}
+/**
+ * Whether `data` is an icon the kernel serves, by the extension of `name` (a URL's path or a
+ * repository path) and its content, like a plugin icon ({@link iconProblem}): the checked icon, or
+ * the problem (English).
+ */
+export declare function checkMarketplaceIcon(name: string, data: Uint8Array): CheckedIcon | string;
+/**
+ * Downloads one icon URL under the marketplace network rules (https, public addresses or
+ * `allowPrivateHosts`, `net.httpsProxy`, no redirects, {@link MARKETPLACE_ICON_TIMEOUT_MS}, at
+ * most {@link MARKETPLACE_ICON_MAX_BYTES}) and checks it: the icon, or why it was not kept. Never
+ * throws (an abort of `signal` is a problem too).
+ */
+export declare function fetchMarketplaceIcon(url: string, o: {
+    net: NetPolicy;
+    signal: AbortSignal;
+    lookup?: LookupFn;
+}): Promise<CheckedIcon | string>;
+/**
+ * The repository paths (relative to the root, without `./`) of the icons a git marketplace's
+ * manifest names, read leniently (the manifest is validated afterwards); for a single-plugin repo
+ * (no manifest) the root `plugin.json`'s icon. At most `max` paths.
+ */
+export declare function gitIconPaths(files: Map<string, Uint8Array>, manifestPath: string, maxIndexBytes: number, max: number): string[];
+/**
+ * The icons a refresh has to have for `entries` of a marketplace of `form`, as the entries write
+ * them (the stored `ref`): repository paths `./…` (git marketplaces only; an http marketplace has
+ * no repository) and URLs, each once.
+ */
+export declare function wantedIcons(entries: Pick<MarketplaceEntry, "icon">[], form: "http" | "git"): {
+    paths: Set<string>;
+    urls: Set<string>;
+};
+/** The admin route of a stored icon (content addressed: the URL changes with the bytes). */
+export declare const marketplaceIconUrl: (sourceId: string, sha256: string) => string;
+/** The org browse route of a stored icon (org admins of `orgId`, like the org browse). */
+export declare const orgMarketplaceIconUrl: (orgId: string) => (sourceId: string, sha256: string) => string;

package/dist/catalog/marketplace-icons.js

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { MARKETPLACE_ICON_RE, MARKETPLACE_LIMITS, marketplaceEntryIcon, PLUGIN_MANIFEST_FILE, } from "@capybara-hq/plugin-sdk";
+import { NetDeniedError } from "../net/public-address.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { packagePath } from "../packages/tgz.js";
+import { marketplaceUrlProblem } from "./marketplace-fetch.js";
+import { iconProblem } from "./plugin-package.js";
+/**
+ * Marketplace entry icons (maintainer decision 2026-11-08; plugin component management spec §16):
+ * the icon a marketplace entry names for its plugin before it is imported. An entry's `icon` is an
+ * https URL or a path in a git marketplace's repository (SDK `MarketplaceEntry.icon`). The refresh
+ * reads each one (a URL through `net/safeFetch` under the marketplace network rules and
+ * `marketplaces.allowedHosts`, never with the marketplace token; a path from the commit it fetched
+ * anyway), keeps those that really are an svg / png of at most 64 KiB in `marketplace_icons`, and
+ * the admin market list serves them like plugin icons (`sendCatalogIcon`). A failed or invalid
+ * icon is only logged: the entry has no icon and the list shows its initial.
+ */
+/** The timeout of one icon download. */
+export const MARKETPLACE_ICON_TIMEOUT_MS = 10_000;
+/** At most this many icon URLs are downloaded per refresh (the rest wait for the next one). */
+export const MARKETPLACE_ICON_FETCHES_MAX = 100;
+/** How long after a failed download an icon URL is tried again (by a later refresh). */
+export const MARKETPLACE_ICON_RETRY_MS = 6 * 3600_000;
+/** Parallel icon downloads of one refresh. */
+export const MARKETPLACE_ICON_CONCURRENCY = 4;
+/** The largest icon (the plugin icon limit). */
+export const MARKETPLACE_ICON_MAX_BYTES = MARKETPLACE_LIMITS.iconBytes;
+/**
+ * Whether `data` is an icon the kernel serves, by the extension of `name` (a URL's path or a
+ * repository path) and its content, like a plugin icon ({@link iconProblem}): the checked icon, or
+ * the problem (English).
+ */
+export function checkMarketplaceIcon(name, data) {
+    if (!MARKETPLACE_ICON_RE.test(name))
+        return `${name} is not a .svg or .png file`;
+    const problem = iconProblem(name, data);
+    if (problem !== undefined)
+        return problem;
+    return {
+        contentType: /\.svg$/i.test(name) ? "image/svg+xml" : "image/png",
+        sha256: createHash("sha256").update(data).digest("hex"),
+        data,
+    };
+}
+/**
+ * Downloads one icon URL under the marketplace network rules (https, public addresses or
+ * `allowPrivateHosts`, `net.httpsProxy`, no redirects, {@link MARKETPLACE_ICON_TIMEOUT_MS}, at
+ * most {@link MARKETPLACE_ICON_MAX_BYTES}) and checks it: the icon, or why it was not kept. Never
+ * throws (an abort of `signal` is a problem too).
+ */
+export async function fetchMarketplaceIcon(url, o) {
+    const problem = marketplaceUrlProblem(url, o.net.allowInsecureLoopback);
+    if (problem !== null)
+        return `invalid icon URL: ${problem}`;
+    const target = new URL(url);
+    const signal = AbortSignal.any([o.signal, AbortSignal.timeout(MARKETPLACE_ICON_TIMEOUT_MS)]);
+    try {
+        const res = await safeFetch(target.href, { signal }, o.net, {
+            maxBytes: MARKETPLACE_ICON_MAX_BYTES,
+            ...(o.lookup !== undefined && { lookup: o.lookup }),
+        });
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => { });
+            return `the icon URL responded with HTTP ${res.status}`;
+        }
+        const data = new Uint8Array(await res.arrayBuffer());
+        return checkMarketplaceIcon(target.pathname, data);
+    }
+    catch (e) {
+        if (e instanceof NetDeniedError)
+            return `icon download refused: ${e.message}`;
+        return `cannot fetch the icon: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/**
+ * The repository paths (relative to the root, without `./`) of the icons a git marketplace's
+ * manifest names, read leniently (the manifest is validated afterwards); for a single-plugin repo
+ * (no manifest) the root `plugin.json`'s icon. At most `max` paths.
+ */
+export function gitIconPaths(files, manifestPath, maxIndexBytes, max) {
+    const json = (raw) => {
+        if (raw === undefined || raw.byteLength > maxIndexBytes)
+            return undefined;
+        try {
+            return JSON.parse(new TextDecoder().decode(raw));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const paths = new Set();
+    const manifest = json(files.get(manifestPath));
+    if (files.has(manifestPath)) {
+        if (!Array.isArray(manifest?.plugins))
+            return [];
+        for (const p of manifest.plugins) {
+            const icon = p?.icon;
+            if (typeof icon === "string" && icon.startsWith("./") && MARKETPLACE_ICON_RE.test(icon)) {
+                paths.add(icon.slice(2));
+            }
+            if (paths.size >= max)
+                break;
+        }
+        return [...paths];
+    }
+    const icon = json(files.get(PLUGIN_MANIFEST_FILE))?.icon;
+    return typeof icon === "string" && MARKETPLACE_ICON_RE.test(icon) ? [packagePath(icon)] : [];
+}
+/**
+ * The icons a refresh has to have for `entries` of a marketplace of `form`, as the entries write
+ * them (the stored `ref`): repository paths `./…` (git marketplaces only; an http marketplace has
+ * no repository) and URLs, each once.
+ */
+export function wantedIcons(entries, form) {
+    const paths = new Set();
+    const urls = new Set();
+    for (const e of entries) {
+        const icon = marketplaceEntryIcon(e);
+        if (icon === null)
+            continue;
+        if ("url" in icon)
+            urls.add(icon.url);
+        else if (form === "git")
+            paths.add(`./${icon.path}`);
+    }
+    return { paths, urls };
+}
+/** The admin route of a stored icon (content addressed: the URL changes with the bytes). */
+export const marketplaceIconUrl = (sourceId, sha256) => `/api/v1/admin/marketplaces/${encodeURIComponent(sourceId)}/icons/${sha256}`;
+/** The org browse route of a stored icon (org admins of `orgId`, like the org browse). */
+export const orgMarketplaceIconUrl = (orgId) => (sourceId, sha256) => `/api/v1/orgs/${encodeURIComponent(orgId)}/marketplaces/${encodeURIComponent(sourceId)}/icons/${sha256}`;