@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/catalog/marketplaces.service.d.ts

@@ -1,9 +1,15 @@
-import { type Logger, type MarketplaceEntry, type MarketplaceSource } from "@capybara-hq/plugin-sdk";
+import { type MarketplaceEntry, type MarketplaceSource } from "@capybara-hq/plugin-sdk";
 import { type KernelConfig } from "../config/schema.js";
 import { type Keyring } from "../ctx/secrets.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.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";
+import type { KernelLogger } from "../log.js";
 import { type ClaudeEntryOverlay } from "./claude/manifest.js";
 import { type MarketplaceSkipReason } from "./claude/marketplace.js";
+import { CatalogSourceLock } from "./locks.js";
 /** 官方清单来源的 id。 */
 export declare const OFFICIAL_MARKETPLACE_ID = "official";
 /** 拉取一份清单的超时。 */
@@ -68,6 +74,11 @@ export interface MarketplaceEntryView {
         en: string;
         zh?: string;
     };
+    /** The entry's display name (copied from the plugin's `plugin.json`); null without one. */
+    displayName: {
+        zh: string;
+        en: string;
+    } | null;
     minKernel: string | null;
     homepage: string | null;
     permissions: {
@@ -77,6 +88,13 @@ export interface MarketplaceEntryView {
     source: MarketplaceSource;
     /** `claude-code` for an entry of a Claude Code marketplace (`.claude-plugin/marketplace.json`). */
     format: "capybara" | "claude-code";
+    /**
+     * The marketplace deprecates this version (`deprecated`, spec ruling Task 13): its reason, `null`
+     * without one; `null` when not deprecated. Importing it is refused (`marketplace.entry_deprecated`).
+     */
+    deprecated: {
+        reason: string | null;
+    } | null;
     /** `minKernel` is satisfied by this deployment. */
     compatible: boolean;
     /** The kernel can import this entry's source now. */
@@ -87,7 +105,17 @@ export interface MarketplaceEntryView {
         itemId: string;
         versions: string[];
     } | null;
-    /** Adopted, and this compatible entry is newer than the newest imported version (never automatic). */
+    /**
+     * The icon to show (a kernel URL behind the super admin gate), null without one: the entry's
+     * marketplace icon as stored by the last refresh (`GET /api/v1/admin/marketplaces/:id/icons/:sha256`);
+     * the entries routes replace it with the catalog item's own icon when the plugin is imported
+     * and the reader may see it. The org browse route gives the org routes of both.
+     */
+    icon: string | null;
+    /**
+     * Adopted, and this compatible entry, not deprecated, is newer than the newest imported version
+     * (never automatic).
+     */
     newerAvailable: boolean;
     /**
      * "Content changed at the same version" (spec §5.3): a version of this entry's release is
@@ -98,16 +126,10 @@ export interface MarketplaceEntryView {
      */
     contentChanged: boolean;
 }
-export interface MarketplacesServiceDeps {
-    db: KernelDb;
-    config: () => KernelConfig;
-    keyring: Keyring;
-    log: Pick<Logger, "info" | "warn" | "error">;
-    /** 测试可调短。 */
-    fetchTimeoutMs?: number;
-}
 export interface ActorOpts {
     actorTokenId?: string;
+    /** Merged into the audit detail (a write made through the Platform tool: `via`, …). */
+    auditDetail?: Record<string, unknown>;
 }
 /** A plugin name from a repo URL or path segment (lower case, invalid characters as `-`). */
 export declare function pluginNameFrom(segment: string): string;
@@ -166,10 +188,17 @@ export declare function headsToResolve(entries: readonly MarketplaceEntry[], imp
 /** The host versions (an entry's `minKernel` is judged against them). */
 export declare const HOST_VERSIONS: {
     readonly kernel: string;
-    readonly sdk: "0.1.0-rc.0";
+    readonly sdk: "0.1.0-rc.7";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;
+/** Whether the marketplace marks the entry deprecated (`deprecated: true` or with a reason). */
+export declare const entryDeprecated: (e: MarketplaceEntry) => boolean;
+/**
+ * Refuses importing (or requesting) a deprecated marketplace entry: 409
+ * `marketplace.entry_deprecated`, its reason in the message and details.
+ */
+export declare function assertEntryNotDeprecated(e: MarketplaceEntry): void;
 /**
  * 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
@@ -183,6 +212,8 @@ export declare function marketplaceForm(url: string, form?: MarketplaceForm): {
 export declare function entrySourceHost(e: Pick<MarketplaceEntry, "source">): string | undefined;
 /** Whether `marketplaces.allowedHosts` lets an entry download from `host` (empty: any host). */
 export declare function hostAllowed(host: string, config: KernelConfig): boolean;
+/** Why an entry is not importable from a marketplace of `form`, or undefined when it is. */
+export declare function unimportable(e: MarketplaceEntry, form: MarketplaceForm, config: KernelConfig): MarketplaceEntryUnimportable | undefined;
 /** What an import needs to know about the marketplace of an entry. */
 export interface MarketplaceOfEntry {
     url: string;
@@ -197,23 +228,37 @@ export declare const sourceEffective: (row: {
     builtin: boolean;
     enabled: boolean;
 }, config: KernelConfig) => boolean;
+/**
+ * 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 declare function pickDefaultEntry<T extends {
+    version: string;
+}>(entries: readonly T[], o: {
+    usable: (e: T) => boolean;
+    deprecated: (e: T) => boolean;
+}): T | undefined;
 /**
  * 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`.
  */
-export declare function loadMarketplaceEntry(db: KernelDb, config: KernelConfig, sourceId: string, name: string, version?: string): Promise<{
+export declare function loadMarketplaceEntry(db: KernelSchemaDb, config: KernelConfig, sourceId: string, name: string, version?: string): Promise<{
     entry: MarketplaceEntry;
     marketplace: MarketplaceOfEntry;
     /** The overlay of an entry of a Claude Code marketplace. */
     claude?: ClaudeEntryOverlay;
 }>;
 /**
- * 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
@@ -221,8 +266,19 @@ export declare function loadMarketplaceEntry(db: KernelDb, config: KernelConfig,
  * by every replica.
  */
 export declare class MarketplacesService {
-    private readonly d;
-    constructor(d: MarketplacesServiceDeps);
+    private readonly kdb;
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    private readonly adminLock;
+    private readonly sourceLock;
+    private readonly config;
+    private readonly keyring;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock: SuperAdminLock, sourceLock: CatalogSourceLock, config: KernelConfigService, keyring: Keyring, log: KernelLogger, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
     /**
      * Creates / updates the official marketplace from config (name, URL, its form per
      * {@link marketplaceForm}, mirrors; the admin's enable switch is left alone). Called by every
@@ -236,7 +292,7 @@ export declare class MarketplacesService {
     list(): Promise<MarketplaceView[]>;
     get(id: string): Promise<MarketplaceView>;
     /**
-     * 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.
      */
@@ -249,7 +305,22 @@ export declare class MarketplacesService {
         token?: string;
     }, opts?: ActorOpts): Promise<MarketplaceView>;
     /**
-     * Updates an enterprise marketplace (audit `marketplace.updated`, listing the changed fields, the
+     * 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).
+     */
+    checkAdd(input: {
+        name: string;
+        url: string;
+        ref?: string;
+    }): Promise<{
+        id: string;
+        name: string;
+    } | null>;
+    private writeAdd;
+    /**
+     * 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
@@ -266,8 +337,9 @@ export declare class MarketplacesService {
         enabled?: boolean;
         token?: string | null;
     }, opts?: ActorOpts): Promise<MarketplaceView>;
+    private writeUpdate;
     /**
-     * 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`.
      */
@@ -288,8 +360,9 @@ export declare class MarketplacesService {
     }): Promise<MarketplaceView>;
     /**
      * 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
@@ -307,7 +380,36 @@ export declare class MarketplacesService {
      * entry unknown (never fails the refresh). Returns `name\0version` -> head.
      */
     private resolveHeads;
-    /** 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.
+     */
+    private syncIcons;
+    /**
+     * Writes a refresh's icons: upserts `put`, deletes `gone`, records the `failed` downloads and
+     * forgets the `cleared` failures (see {@link syncIcons}).
+     */
+    private writeIcons;
+    /**
+     * 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.
+     */
+    icon(id: string, sha256: string, opts?: {
+        browsable?: boolean;
+    }): Promise<{
+        contentType: "image/svg+xml" | "image/png";
+        data: Uint8Array;
+    }>;
+    /** The token of a custom marketplace (undefined without one; official never has one). */
     token(id: string): Promise<string | undefined>;
     /** Refreshes every effective marketplace (maintenance job `catalogs-refresh`), one failing not stopping the rest. */
     refreshAll(signal: AbortSignal): Promise<void>;
@@ -320,16 +422,24 @@ export declare class MarketplacesService {
     entries(q?: {
         marketplaceId?: string;
         q?: string;
-    }): Promise<{
+    }, 
+    /** The URL of a stored marketplace icon (default: the admin route). */
+    iconUrl?: (sourceId: string, sha256: string) => string): Promise<{
         items: MarketplaceEntryView[];
         truncated: boolean;
     }>;
+    /**
+     * Writes a refresh's result under the marketplace's lock (entries, heads, status, the status
+     * change audit); `stale` when the marketplace changed during the fetch (nothing is written).
+     */
+    private recordRefresh;
     /**
      * Replaces the entries of a marketplace; `trees` (a git marketplace) gives each path entry the
      * tree oid of its directory.
      */
     private replaceEntries;
     private views;
+    /** The deployment secrets on the current context's handle (the transaction, else the pool). */
     private secrets;
     private checkName;
     private checkUrls;