@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,340 @@
+import { type Logger, 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 ClaudeEntryOverlay } from "./claude/manifest.js";
+import { type MarketplaceSkipReason } from "./claude/marketplace.js";
+/** 官方清单来源的 id。 */
+export declare const OFFICIAL_MARKETPLACE_ID = "official";
+/** 拉取一份清单的超时。 */
+export declare const MARKETPLACE_FETCH_TIMEOUT_MS = 30000;
+/**
+ * Overall deadline of the periodic refresh of every marketplace (each URL also has its own
+ * {@link MARKETPLACE_FETCH_TIMEOUT_MS}).
+ */
+export declare const MARKETPLACES_REFRESH_DEADLINE_MS = 600000;
+/** `entries()` 一次最多返回的条目数。 */
+export declare const MARKETPLACE_ENTRIES_MAX = 5000;
+/**
+ * At most this many branch heads are resolved per refresh (entries that follow a git branch and
+ * are already imported; spec §5.3 "content changed at the same version").
+ */
+export declare const MARKETPLACE_HEADS_MAX = 50;
+/** A marketplace's form: `http` (a marketplace.json URL) or `git` (a repository, spec §5.1). */
+export type MarketplaceForm = "http" | "git";
+/** 一个清单来源（后台列表）。令牌不回显，只给 `hasToken`。 */
+export interface MarketplaceView {
+    id: string;
+    name: string;
+    url: string;
+    form: MarketplaceForm;
+    /** The ref a git marketplace follows (null: the remote HEAD; always null for http). */
+    ref: string | null;
+    /** The commit of a git marketplace's last successful refresh (null for http or before one). */
+    lastCommit: string | null;
+    mirrors: string[];
+    builtin: boolean;
+    /** 生效的启用状态（official 还要配置 `marketplaces.official.enabled` 为 true）。 */
+    enabled: boolean;
+    /** official 被配置关闭（离线模式）；企业清单恒为 false。 */
+    disabledByConfig: boolean;
+    hasToken: boolean;
+    etag: string | null;
+    lastRefreshedAt: string | null;
+    lastStatus: "ok" | "error" | "never";
+    lastError: string | null;
+    entryCount: number;
+    /** Entries the last successful refresh could not store (a Claude marketplace's npm sources, …). */
+    skipped: {
+        name: string;
+        reason: MarketplaceSkipReason;
+    }[];
+    createdAt: string;
+}
+/**
+ * Why a marketplace entry cannot be imported: `host_not_allowed` when its git / archive source is
+ * on a host outside `marketplaces.allowedHosts`; `path_needs_git_marketplace` for a `path` source
+ * of a marketplace fetched over http (a path is read from the marketplace's own repository).
+ */
+export type MarketplaceEntryUnimportable = "host_not_allowed" | "path_needs_git_marketplace";
+/** A marketplace entry (admin browsing). One entry is one version of a plugin. */
+export interface MarketplaceEntryView {
+    sourceId: string;
+    sourceName: string;
+    name: string;
+    /** The entry's version (`version`, else the npm source's); null when it has none (the plugin's own). */
+    version: string | null;
+    summary: {
+        en: string;
+        zh?: string;
+    };
+    minKernel: string | null;
+    homepage: string | null;
+    permissions: {
+        keys: string[];
+        sensitive: string[];
+    } | null;
+    source: MarketplaceSource;
+    /** `claude-code` for an entry of a Claude Code marketplace (`.claude-plugin/marketplace.json`). */
+    format: "capybara" | "claude-code";
+    /** `minKernel` is satisfied by this deployment. */
+    compatible: boolean;
+    /** The kernel can import this entry's source now. */
+    importable: boolean;
+    reason?: MarketplaceEntryUnimportable;
+    /** Imported as a catalog item (a non-deleted item with the same name) and its versions. */
+    adopted: {
+        itemId: string;
+        versions: string[];
+    } | null;
+    /** Adopted, and this compatible entry 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
+     * imported (for an entry without a version: a version from the same git location), but none of
+     * them has the commit or integrity the entry points at now (a branch-following git entry: the
+     * branch head of the last refresh; a path entry: the marketplace's last commit). Importing it
+     * again records `<version>+git.<sha12>` / `+sha256.<12>`.
+     */
+    contentChanged: boolean;
+}
+export interface MarketplacesServiceDeps {
+    db: KernelDb;
+    config: () => KernelConfig;
+    keyring: Keyring;
+    log: Pick<Logger, "info" | "warn" | "error">;
+    /** 测试可调短。 */
+    fetchTimeoutMs?: number;
+}
+export interface ActorOpts {
+    actorTokenId?: string;
+}
+/** A plugin name from a repo URL or path segment (lower case, invalid characters as `-`). */
+export declare function pluginNameFrom(segment: string): string;
+/** Where an entry's plugin is now (columns of the entry row and its marketplace). */
+export interface EntryAt {
+    /** The marketplace listing the entry. */
+    marketplaceId: string;
+    /** The branch head of a branch-following git entry (the last refresh's; null: unknown). */
+    headCommit: string | null;
+    /**
+     * The git tree oid of the entry's plugin directory (a path entry: at the marketplace's last
+     * commit; a git entry with a path: at its head); null: unknown.
+     */
+    treeOid: string | null;
+    /** The marketplace URL and last commit (path entries read the marketplace's repository). */
+    url: string;
+    lastCommit: string | null;
+}
+/** A catalog version as an entry is compared with (columns of `catalog_item_versions`). */
+export interface ImportedAs {
+    version: string;
+    source: string;
+    source_ref: string;
+    integrity: string | null;
+    source_detail: unknown;
+}
+/**
+ * Whether the content of an entry changed at a version already imported from the same source (see
+ * {@link MarketplaceEntryView.contentChanged}). Only versions imported from what the entry points
+ * at count: a git / path entry -> the same git location (host, repo, path); an archive -> an
+ * archive from the same URL or listed by this marketplace; npm -> the same package version, from this marketplace or straight from npm, with an
+ * integrity. Of those, the entry's release (all of them for an entry without a version). Changed
+ * when none of them matches what the entry points at now: npm / archive by integrity; git / path
+ * by tree oid when both sides know it (a monorepo commit elsewhere changes nothing), else by
+ * commit. Unknown (no head or last commit) -> false.
+ */
+export declare function entryContentChanged(e: MarketplaceEntry, at: EntryAt, versions: readonly ImportedAs[]): boolean;
+/** A branch-following git entry whose head a refresh resolves. */
+type FollowingEntry = MarketplaceEntry & {
+    source: {
+        git: {
+            url: string;
+            ref?: string;
+            path?: string;
+        };
+    };
+};
+/**
+ * Which entries a refresh resolves the branch head of: git entries without a pinned commit, on a
+ * host `marketplaces.allowedHosts` lets through, with a version imported from the same git
+ * location (of the entry's release; any, for an entry without a version), at most `max`, by name.
+ */
+export declare function headsToResolve(entries: readonly MarketplaceEntry[], imported: readonly (ImportedAs & {
+    name: string;
+})[], config: KernelConfig, max: number): FollowingEntry[];
+/** 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";
+};
+/** Whether this deployment satisfies the entry's `minKernel`. */
+export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;
+/**
+ * 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
+ * (a `.json` URL included) is an http marketplace.json URL. `form` given wins.
+ */
+export declare function marketplaceForm(url: string, form?: MarketplaceForm): {
+    form: MarketplaceForm;
+    url: string;
+};
+/** The host a git / archive entry downloads from (lower case), undefined for npm / path. */
+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;
+/** What an import needs to know about the marketplace of an entry. */
+export interface MarketplaceOfEntry {
+    url: string;
+    form: MarketplaceForm;
+    ref: string | null;
+    lastCommit: string | null;
+    ownerName: string | null;
+    builtin: boolean;
+}
+/** 来源是否生效：本身启用，official 还要配置没关。 */
+export declare const sourceEffective: (row: {
+    builtin: boolean;
+    enabled: boolean;
+}, config: KernelConfig) => boolean;
+/**
+ * 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`;
+ * 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<{
+    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
+ * marketplace (config `marketplaces.official.*`, synced at startup into the marketplace with id
+ * `official`) and enterprise 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
+ * status `error`. A status change audits `marketplace.refreshed` and logs once. Stateless, shared
+ * by every replica.
+ */
+export declare class MarketplacesService {
+    private readonly d;
+    constructor(d: MarketplacesServiceDeps);
+    /**
+     * 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
+     * replica at start; idempotent. A changed URL or form drops the ETag and the last git commit, so
+     * the next refresh reads everything (the entries stay until then). A git URL with mirrors is a
+     * config error (the config schema refuses it first; checked again here for configs built
+     * without the schema).
+     */
+    syncOfficialFromConfig(): Promise<void>;
+    /** 全部来源（official 在前，其余按创建时间）。 */
+    list(): Promise<MarketplaceView[]>;
+    get(id: string): Promise<MarketplaceView>;
+    /**
+     * Adds an enterprise 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.
+     */
+    add(actor: string, input: {
+        name: string;
+        url: string;
+        form?: MarketplaceForm;
+        ref?: string;
+        mirrors?: string[];
+        token?: string;
+    }, opts?: ActorOpts): Promise<MarketplaceView>;
+    /**
+     * Updates an enterprise 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
+     * gets its form from {@link marketplaceForm} unless `form` is given. `ref: null` follows the
+     * remote HEAD. Switching the form clears the other form's field (the ref when becoming http,
+     * the mirrors when becoming git) unless the patch sets it.
+     */
+    update(actor: string, id: string, patch: {
+        name?: string;
+        url?: string;
+        form?: MarketplaceForm;
+        ref?: string | null;
+        mirrors?: string[];
+        enabled?: boolean;
+        token?: string | null;
+    }, opts?: ActorOpts): Promise<MarketplaceView>;
+    /**
+     * Deletes an enterprise 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`.
+     */
+    remove(actor: string, id: string, opts?: ActorOpts): Promise<void>;
+    /**
+     * Refreshes one marketplace: the main URL, then the mirrors (with If-None-Match, at most
+     * `marketplaces.maxIndexBytes`); 304 keeps the entries, a valid 200 replaces them as a whole; when all
+     * fail the old entries are kept with status `error`. A disabled marketplace -> 409 `conflict`.
+     * A status change audits `marketplace.refreshed {from, to}` (a periodic refresh has no actor) and
+     * logs once. If the URL / mirrors changed during the fetch: the result is discarded and nothing is
+     * written (M-1).
+     * `throwOnError` (manual refresh): after recording the status, a failure throws 502 —
+     * `marketplace.invalid` when some URL returned an invalid manifest, else `marketplace.fetch_failed`
+     * (the message gives each URL's failure).
+     */
+    refresh(id: string, signal: AbortSignal, actor?: string, opts?: ActorOpts & {
+        throwOnError?: boolean;
+    }): 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
+     * `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
+     * `.capybara-plugin/plugin.json`, `.claude-plugin/plugin.json` or `skills/`) becomes one entry
+     * with source path `.`, named by plugin.json or, for a skills-only repo, by the repo name
+     * (Decision 3). Throws {@link GitSourceError} or {@link MarketplaceInvalidError}.
+     */
+    private fetchGit;
+    /**
+     * Resolves the branch heads of the entries {@link headsToResolve} picks (at most
+     * {@link MARKETPLACE_HEADS_MAX} per refresh), each through the network rules with the fetch
+     * timeout; the token goes only to the marketplace URL's origin. For an entry with a path whose
+     * head is not a commit already imported from it, the head is fetched too, for the tree oid of
+     * that directory (equal oids: unchanged although the repo moved). A failed lookup leaves the
+     * 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). */
+    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>;
+    /**
+     * Browses entries (enabled marketplaces only): filtered by marketplace, `q` matches a substring of
+     * the name / npm package name / summary (case-insensitive). Ordered by name, version (newest
+     * first), marketplace, at most {@link MARKETPLACE_ENTRIES_MAX}; `truncated` means there are more
+     * (the UI suggests narrowing the filter).
+     */
+    entries(q?: {
+        marketplaceId?: string;
+        q?: string;
+    }): Promise<{
+        items: MarketplaceEntryView[];
+        truncated: boolean;
+    }>;
+    /**
+     * Replaces the entries of a marketplace; `trees` (a git marketplace) gives each path entry the
+     * tree oid of its directory.
+     */
+    private replaceEntries;
+    private views;
+    private secrets;
+    private checkName;
+    private checkUrls;
+    /** A git marketplace has no mirrors; only a git marketplace has a ref. */
+    private checkGitFields;
+    private checkToken;
+}
+export {};