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

package/dist/catalog/marketplaces.schemas.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { MARKETPLACE_MAX_MIRRORS } from "../config/schema.js";
+export const MarketplaceUrl = z.string().min(1).max(2000);
+export const MarketplaceForm = z.enum(["http", "git"]);
+export const MarketplaceRef = z.string().min(1).max(256);
+export const MarketplaceAddBody = z.object({
+    name: z.string().min(1).max(100),
+    url: MarketplaceUrl,
+    form: MarketplaceForm.optional(),
+    ref: MarketplaceRef.optional(),
+    mirrors: z.array(MarketplaceUrl).max(MARKETPLACE_MAX_MIRRORS).optional(),
+    token: z.string().min(1).max(4096).optional(),
+});
+export const MarketplaceEntriesQuery = z.object({
+    sourceId: z.string().min(1).max(100).optional(),
+    q: z.string().max(200).optional(),
+});
+export const MarketplacePatchBody = z
+    .object({
+    name: z.string().min(1).max(100).optional(),
+    url: MarketplaceUrl.optional(),
+    form: MarketplaceForm.optional(),
+    ref: MarketplaceRef.nullable().optional(),
+    mirrors: z.array(MarketplaceUrl).max(MARKETPLACE_MAX_MIRRORS).optional(),
+    enabled: z.boolean().optional(),
+    token: z.string().min(1).max(4096).nullable().optional(),
+})
+    .strict();
+export const MarketplaceImportBody = z.object({ version: z.string().min(1).max(256).optional() });
+/** `:id` of a marketplace as the routes take it (`@Param`). */
+export const MarketplaceIdPathParams = z.object({ id: z.string().min(1) });
+/** `:id` and the entry `:name` of the import route (`@Param`). */
+export const MarketplaceEntryPathParams = MarketplaceIdPathParams.extend({
+    name: z.string().min(1),
+});
+export const MARKETPLACE_ROUTES = [
+    { route: "GET /api/v1/admin/marketplaces" },
+    { route: "POST /api/v1/admin/marketplaces", body: MarketplaceAddBody },
+    { route: "GET /api/v1/orgs/:orgId/marketplaces/entries", query: MarketplaceEntriesQuery },
+    { route: "GET /api/v1/admin/marketplaces/entries", query: MarketplaceEntriesQuery },
+    {
+        route: "PATCH /api/v1/admin/marketplaces/:id",
+        params: MarketplaceIdPathParams,
+        body: MarketplacePatchBody,
+    },
+    { route: "DELETE /api/v1/admin/marketplaces/:id", params: MarketplaceIdPathParams },
+    { route: "POST /api/v1/admin/marketplaces/:id/refresh", params: MarketplaceIdPathParams },
+    {
+        route: "POST /api/v1/admin/marketplaces/:id/entries/:name/import",
+        params: MarketplaceEntryPathParams,
+        body: MarketplaceImportBody,
+    },
+];

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

@@ -2,7 +2,7 @@ import { type MarketplaceEntry, type MarketplaceSource } from "@capybara-hq/plug
 import { type KernelConfig } from "../config/schema.js";
 import { type Keyring } from "../ctx/secrets.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.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";
@@ -74,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: {
@@ -83,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. */
@@ -93,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
@@ -106,6 +128,8 @@ export interface MarketplaceEntryView {
 }
 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;
@@ -164,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.14";
 };
 /** 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
@@ -181,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;
@@ -195,10 +228,24 @@ 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`.
  */
@@ -209,9 +256,9 @@ export declare function loadMarketplaceEntry(db: KernelSchemaDb, config: KernelC
     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
@@ -220,7 +267,7 @@ export declare function loadMarketplaceEntry(db: KernelSchemaDb, config: KernelC
  */
 export declare class MarketplacesService {
     private readonly 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. */
     private readonly adminLock;
     private readonly sourceLock;
     private readonly config;
@@ -228,8 +275,8 @@ export declare class MarketplacesService {
     private readonly log;
     readonly txHost: TransactionHost;
     constructor(kdb: KernelDb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
-    adminLock: EnterpriseAdminLock, sourceLock: CatalogSourceLock, config: KernelConfigService, keyring: Keyring, log: KernelLogger, txHost: TransactionHost);
+    /** 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();
     /**
@@ -245,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.
      */
@@ -257,9 +304,23 @@ export declare class MarketplacesService {
         mirrors?: string[];
         token?: string;
     }, opts?: ActorOpts): Promise<MarketplaceView>;
+    /**
+     * 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 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
@@ -278,7 +339,7 @@ export declare class MarketplacesService {
     }, 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`.
      */
@@ -299,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
@@ -318,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>;
@@ -331,7 +422,9 @@ 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;
     }>;