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

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

@@ -0,0 +1,430 @@
+import { type Connector, type ConnectorTemplateSpec, type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDatabase, KernelDb, SourceFormat } from "../db/kernel-schema.js";
+import type { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import type { ExtensionInstalls } from "../extensions/installs.js";
+import type { AdminExtensionView } from "../extensions/permission-view.js";
+import type { StorageService } from "../storage/storage.service.js";
+import type { TranslationReport } from "./claude/report.js";
+import type { PluginImport, PluginReview } from "./plugin-import.js";
+/** Item policy (C22): allow (default for new imports) / needs_approval / disabled (no new installs; existing ones stay). */
+export type CatalogPolicy = "allow" | "needs_approval" | "disabled";
+/** A catalog item (list entry). Every item is a plugin. */
+export interface CatalogItemView {
+    id: string;
+    name: string;
+    publisher: string;
+    displayName: LocalizedName | null;
+    description: string;
+    policy: CatalogPolicy;
+    latestVersion: string;
+    /** Every version, newest first (semver; equal but for build metadata: the later import first). */
+    versions: string[];
+    /**
+     * Orgs that installed it: orgs with an installed plugin install of the item, plus, when its latest
+     * version has an extension, orgs that enabled that extension.
+     */
+    installs: number;
+    /** The latest version's source (file / npm / marketplace). */
+    source: string;
+    /**
+     * The marketplace an item was imported from (`official` or an enterprise marketplace id); null
+     * when imported by hand or when that marketplace was deleted.
+     */
+    marketplaceId: string | null;
+    /**
+     * The item's highest compatible version in its marketplace (when enabled); null when the item was
+     * not imported from a marketplace, the marketplace is disabled or the entry is gone.
+     */
+    latestMarketplaceVersion: string | null;
+    /**
+     * `latestMarketplaceVersion` is newer than the newest imported version (the UI shows "newer
+     * version"; never imported automatically).
+     */
+    newerInMarketplace: boolean;
+    /**
+     * An entry of its marketplace has a version already imported, but its source now differs from
+     * what was recorded (another commit or integrity): "content changed at the same version" (spec
+     * §5.3). Importing it again records `<version>+git.<sha12>` / `+sha256.<12>`.
+     */
+    contentChanged: boolean;
+    updatedAt: string;
+}
+/**
+ * A git source as recorded (spec §5.1: the actual host, repo and commit, and whether it follows a
+ * branch, i.e. no commit was pinned). `path` is `.` for the repo root.
+ */
+export interface GitSourceDetail {
+    host: string;
+    repo: string;
+    path: string;
+    ref?: string;
+    commit: string;
+    followsBranch: boolean;
+    /**
+     * The git tree oid of the plugin's directory at `commit` (equal oids, equal files: a monorepo
+     * commit that leaves the directory alone keeps it). Absent before phase A1 task 4's fix round.
+     */
+    tree?: string;
+}
+/** Where a catalog version came from: a git location, an archive URL (origin + path), an npm registry. */
+export type SourceDetail = GitSourceDetail | {
+    url: string;
+} | {
+    registry: string;
+};
+/** The source kinds of a catalog version. */
+export type CatalogVersionSource = "file" | "npm" | "marketplace" | "git" | "bootstrap";
+/** One version of an item. */
+export interface CatalogItemVersionView {
+    version: string;
+    source: CatalogVersionSource;
+    sourceRef: string;
+    integrity: string | null;
+    /** The content digest of the imported files (null for a version imported before phase A1). */
+    contentDigest: string | null;
+    /** Where it came from (null for an upload, or a version imported before phase A1). */
+    sourceDetail: SourceDetail | null;
+    /** The normalized plugin.json (skills and connector templates listed). */
+    manifest: PluginManifest;
+    /** Files stored under the version's object prefix (skills, connector templates, icons). */
+    files: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+    size: number;
+    /** The extension's package in the package store (null without an extension). */
+    extensionSha256: string | null;
+    /** `claude-code`: translated from a Claude Code plugin. */
+    sourceFormat: SourceFormat;
+    /** The translation report of a Claude Code plugin (null for a native plugin). */
+    translation: TranslationReport | null;
+    /** The root LICENSE text (null without one, or before phase B). */
+    licenseText: string | null;
+    /** The root LICENSE was longer than 64 KiB (or not UTF-8), so `licenseText` is null. */
+    licenseTruncated: boolean;
+    importedBy: string | null;
+    importedAt: string;
+}
+/** Item detail (deleted items included: `deletedAt` set). */
+export interface CatalogItemDetail {
+    /** `packageName` is null for a git plugin without package.json. */
+    item: CatalogItemView & {
+        packageName: string | null;
+        deletedAt: string | null;
+    };
+    versions: CatalogItemVersionView[];
+}
+export interface CatalogServiceDeps {
+    db: KernelDb;
+    config: () => KernelConfig;
+    installs: Pick<ExtensionInstalls, "fetchMarketplacePackage" | "fetchProvenance">;
+    ops: Pick<ExtensionAdminOps, "install">;
+    /** Plugin import (a marketplace entry goes through its prepare). */
+    pluginImport: Pick<PluginImport, "prepare" | "prepareGit">;
+    /** The token of an enterprise marketplace (sent only to its URL's origin). */
+    marketplaceToken: (marketplaceId: string) => Promise<string | undefined>;
+    /** Downloads a marketplace archive source, verified against its integrity. */
+    fetchArchive: (archive: {
+        url: string;
+        integrity: string;
+    }, signal?: AbortSignal) => Promise<{
+        bytes: Uint8Array;
+        integrity: string;
+    }>;
+}
+/** Audits carry the PAT when a personal token made the call. */
+export interface ActorOpts {
+    actorTokenId?: string;
+}
+type Trx = Transaction<KernelDatabase>;
+/**
+ * The marketplace's permission summary differs from the keys computed from the package (a warning,
+ * never a refusal; C26): `missing` = asked by the package, not listed; `extra` = listed, not asked.
+ * null when they agree, the marketplace gave no summary or the plugin has no extension.
+ */
+export type PermissionsMismatch = {
+    missing: string[];
+    extra: string[];
+} | null;
+/**
+ * The result of {@link CatalogService.importFromMarketplace}: a staging id and the review (HTTP
+ * 200), confirmed with `POST /api/v1/admin/catalog/imports/:stagingId/confirm`.
+ */
+export interface MarketplaceImportResult {
+    stagingId: string;
+    review: PluginReview;
+    permissionsMismatch: PermissionsMismatch;
+}
+/** An archive URL as recorded (origin + path): a query string or fragment may carry a token. */
+export declare const archiveRef: (url: string) => string;
+/** `<host>/<owner>` of a repo URL (the publisher of a skills-only plugin without a marketplace owner). */
+export declare function repoOwner(url: string): string;
+/**
+ * The version of a git plugin that has none (spec §5.3): `0.0.0-git.g<sha12>`. The `g` keeps the
+ * prerelease identifier alphanumeric: twelve hex characters that happen to be all digits with a
+ * leading zero are not valid semver.
+ */
+export declare const gitFallbackVersion: (commit: string) => string;
+/**
+ * The object storage prefix of one import (relative to `deployment/`):
+ * `directory/<itemId>/<version>/<importId>/`. Each import gets a new `importId`, so the losing one of
+ * two concurrent imports of the same version never overwrites the committed version's files; reads
+ * always go through the `object_prefix` stored on the version row. Build metadata's `+` is written
+ * as `_` (a `+` in a key can turn into a space through URL query encoding).
+ */
+export declare const catalogObjectPrefix: (itemId: string, version: string, importId: string) => string;
+/** Default / largest page size of the list. */
+export declare const CATALOG_LIST_DEFAULT_LIMIT = 200;
+export declare const CATALOG_LIST_MAX_LIMIT = 1000;
+/**
+ * Enterprise catalog items (D9 / C21 / C22, `/api/v1/admin/catalog/*`, enterprise admins only). One
+ * kind: every item is a plugin (spec §4), imported through {@link PluginImport} (prepare -> confirm,
+ * one review); this service lists and shows items, changes policy, deletes, installs an item's
+ * extension on the deployment, and prepares marketplace imports. Stateless, shared by every replica.
+ */
+export declare class CatalogService {
+    private readonly d;
+    constructor(d: CatalogServiceDeps);
+    /**
+     * Prepares the import of one marketplace entry (C25 / C26, spec §5.2): `version` defaults to the
+     * newest compatible version the marketplace lists for `name`; the entry must be compatible with
+     * the host (`marketplace.incompatible`); an npm source is downloaded from the configured registry
+     * and an archive source from its URL, both always verified against the marketplace's integrity
+     * (`marketplace.integrity_mismatch`, nothing written). A `path` source is read from the git
+     * marketplace's repository at its last refreshed commit (an http marketplace has none:
+     * `marketplace.path_unsupported`); a `git` source at its pinned `commit`, else at its `ref`'s head
+     * now, recorded; both through {@link PluginImport.prepareGit} with source `git` and
+     * `source_detail` (host, repo, path, ref, commit, followsBranch). A git / archive host outside
+     * `marketplaces.allowedHosts` -> `marketplace.host_not_allowed`. The marketplace token goes only
+     * to the marketplace URL's origin. The package must match the entry (name, version, npm package:
+     * `marketplace.package_mismatch`), then the same review as any plugin import
+     * ({@link PluginImport.prepare}) with source `marketplace` (ref `<marketplaceId>:<npm>@<version>`
+     * or `<marketplaceId>:<archive URL>`; git: `<marketplaceId>:<repo>@<commit>[:<path>]`), confirmed with
+     * `POST /api/v1/admin/catalog/imports/:stagingId/confirm`. Marketplace missing ->
+     * `marketplace.not_found`; disabled, or the entry / version missing -> `marketplace.entry_not_found`.
+     */
+    importFromMarketplace(actor: string, input: {
+        marketplaceId: string;
+        name: string;
+        version?: string;
+    }, opts?: ActorOpts & {
+        signal?: AbortSignal;
+    }): Promise<MarketplaceImportResult>;
+    /**
+     * Prepares the import of one plugin straight from git (spec §5.1, a one-off like an upload: no
+     * marketplace is created and no updates are tracked): `url` is an https git URL or `owner/repo`
+     * (GitHub), `ref` a branch / tag / commit (default the remote HEAD), `path` the plugin's directory
+     * (default the root). The commit is resolved and recorded (`source_detail`), then the same review
+     * as any plugin import. A skills-only directory without plugin.json is named after the last
+     * segment of `path` (else of the repo URL) and published by the repo owner.
+     */
+    importFromGit(actor: string | null, input: {
+        url: string;
+        ref?: string;
+        path?: string;
+    }, opts?: ActorOpts & {
+        signal?: AbortSignal;
+    }): Promise<{
+        stagingId: string;
+        review: PluginReview;
+    }>;
+    /** Resolves the commit and reads the plugin's files; git failures become API errors. */
+    private readGit;
+    /**
+     * Item list (deleted items excluded by default), ordered by name, id. Paging: `limit`
+     * defaults to {@link CATALOG_LIST_DEFAULT_LIMIT}, at most {@link CATALOG_LIST_MAX_LIMIT}, `offset`
+     * defaults to 0; use the returned array directly when only the first page is needed.
+     */
+    list(q?: {
+        includeDeleted?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<CatalogItemView[]>;
+    /** Same as {@link list}, plus the offset of the next page (null when there is none). */
+    page(q?: {
+        includeDeleted?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: CatalogItemView[];
+        nextOffset: number | null;
+    }>;
+    /** Item detail (with every version; deleted items too). Missing -> `catalog.item_not_found`. */
+    get(itemId: string): Promise<CatalogItemDetail>;
+    /**
+     * Changes the policy (audit `catalog.policy_changed`, not written when unchanged). Deleted /
+     * missing -> `catalog.item_not_found`.
+     */
+    setPolicy(actor: string, itemId: string, policy: CatalogPolicy, opts?: ActorOpts): Promise<CatalogItemView>;
+    /**
+     * Deletes the item (soft delete, audit `catalog.removed`; requests still pending are cancelled in
+     * the same transaction): versions and stored files are kept (installed components still refer to
+     * them), organizations no longer see it; the same name can later be imported again as a new
+     * item. Deleted / missing -> `catalog.item_not_found`.
+     */
+    remove(actor: string, itemId: string, opts?: ActorOpts): Promise<void>;
+    /**
+     * Installs the extension of one version of an item on the deployment
+     * (`ExtensionAdminOps.install`: a new install is disabled, a version change keeps the desired
+     * state; audit `extension.installed`), with the install record linked to the item (F-AA). The
+     * returned status may be `pending_approval` when the version's permissions are not approved yet.
+     * A version without an extension -> `catalog.no_extension`; item or version missing ->
+     * `catalog.item_not_found`.
+     */
+    installToDeployment(actor: string, itemId: string, version: string, opts?: ActorOpts): Promise<AdminExtensionView>;
+    private view;
+}
+/**
+ * Checks a connector template against the loaded connector `c` (problem paths start with `at`): the
+ * endpoint matches its `endpointSchema` and carries no credential-like headers / query / URL user
+ * info (the same rule as connector installs); every `editableEndpoint` path exists in the endpoint
+ * schema.
+ */
+export declare function templateProblems(c: Connector, t: ConnectorTemplateSpec, at: string): string[];
+/** Writes the files to `deployment/<prefix><path>` ({@link PUT_CONCURRENCY} at a time). */
+export declare function putCatalogFiles(storage: StorageService, prefix: string, files: {
+    path: string;
+    size: number;
+    data: Uint8Array;
+}[]): Promise<void>;
+/** Compares the marketplace's permission summary with the computed keys ({@link PermissionsMismatch}). */
+export declare function permissionsMismatch(declared: string[] | undefined, actual: string[] | undefined): PermissionsMismatch;
+/** The fields the list shows (the item's publisher / description / displayName). */
+export interface CatalogListing {
+    publisher: string;
+    description: string;
+    displayName: LocalizedName | null;
+}
+/** Input of {@link writeCatalogVersion}. */
+export interface CatalogVersionWrite {
+    /** null: the CLI (no account). */
+    actor: string | null;
+    actorTokenId?: string;
+    name: string;
+    /** null: a git plugin without package.json. */
+    packageName: string | null;
+    /**
+     * The version recorded (from {@link precheckCatalogImport}: the plugin's own, or with build
+     * metadata when that release was imported with other content).
+     */
+    version: string;
+    /** The content digest of the plugin's files. */
+    contentDigest: string;
+    /** The normalized plugin.json. */
+    manifest: PluginManifest;
+    listing: CatalogListing;
+    /** The id of the item to create when there is none yet (the one the storage prefix used). */
+    newItemId: string;
+    source: {
+        source: CatalogVersionSource;
+        ref: string;
+        integrity?: string;
+        detail?: SourceDetail;
+    };
+    /** Imported from a marketplace: the item records it. */
+    marketplaceId?: string;
+    objectPrefix: string | null;
+    extensionSha256: string | null;
+    files: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+    size: number;
+    /** The format the plugin was read from (default `capybara`). */
+    sourceFormat?: SourceFormat;
+    /** The translation report of a Claude Code plugin. */
+    translation?: TranslationReport | null;
+    /** The root LICENSE text. */
+    licenseText?: string | null;
+    /** The root LICENSE was too long (or not UTF-8) to store. */
+    licenseTruncated?: boolean;
+    /** Merged into the detail of the `catalog.imported` audit. */
+    auditDetail?: Record<string, unknown>;
+}
+/** Takes the transaction-level advisory lock of an item name (concurrent imports of it serialize). */
+export declare function lockCatalogName(trx: Trx, name: string): Promise<void>;
+/**
+ * The identity of a git source, `<host>/<repo>:<path>` (host lower case, no `.git`), or null when
+ * the source is not git. An item without package.json is identified by it instead of a package name.
+ */
+export declare function gitIdentity(detail: SourceDetail | undefined): string | null;
+/** What is being imported, as far as the version conflict rules need it. */
+export interface ImportIdentity {
+    packageName: string | null;
+    /** The plugin's own version (plugin.json, else the fallback of spec §5.3). */
+    version: string;
+    contentDigest: string;
+    integrity?: string;
+    detail?: SourceDetail;
+    marketplaceId?: string;
+}
+type ExistingVersion = {
+    version: string;
+    content_digest: string | null;
+    integrity: string | null;
+};
+/**
+ * The version a new import records (Decision 6, spec §5.3): the plugin's own version, unless that
+ * release is already imported. A version of the same release (equal but for build metadata) with
+ * the same content (digest; for versions without one, the same integrity) -> `catalog.version_exists`
+ * "already imported"; other content -> `<version>+git.<sha12>` (git) or `+sha256.<12>` (any other
+ * source, the digest's first 12 hex), never overwriting the imported version. A git commit already
+ * recorded with other content (a Claude Code plugin whose marketplace entry changed while its own
+ * commit did not, see `claudeContentDigest`) falls back to `+sha256.<12>`.
+ */
+export declare function recordedVersion(existing: ExistingVersion[], p: ImportIdentity): string;
+/**
+ * Conflict precheck before writing (no lock; {@link writeCatalogVersion}'s re-check inside the
+ * transaction is final): an item with the same name from another npm package (or, without one,
+ * another git source) -> `catalog.name_conflict`; the release already imported with the same
+ * content -> `catalog.version_exists`. Returns the existing item (undefined when there is none) and
+ * the version to record ({@link recordedVersion}).
+ */
+export declare function precheckCatalogImport(db: KernelDb, name: string, p: ImportIdentity): Promise<{
+    existing: {
+        id: string;
+    } | undefined;
+    version: string;
+}>;
+/**
+ * Writes a catalog version in the caller's transaction (the caller has re-checked the enterprise
+ * admin): takes the name's advisory lock, checks conflicts again (the same source; no version of
+ * the release with the same content; `version` not taken meanwhile), creates the item when there is
+ * none or adds the version (latest and display fields change only for a newer version, a version
+ * equal but for build metadata being newer as the later import), and writes the version row (with
+ * its content digest) and the `catalog.imported` audit. Returns the item id.
+ */
+export declare function writeCatalogVersion(trx: Trx, w: CatalogVersionWrite): Promise<string>;
+/**
+ * An extension name belongs to the npm package that first installed it (`extension_name_owners`,
+ * Ruling P3): when another package owns it, the import is refused right away with
+ * `extension.name_conflict` (the same code as at install), instead of failing only at deploy time.
+ */
+export declare function assertPluginNameOwner(db: KernelDb | Trx, name: string, packageName: string | null): Promise<void>;
+/** What the marketplace says about a marketplace-imported item. */
+export interface MarketplaceStatus {
+    /** See {@link CatalogItemView.latestMarketplaceVersion}. */
+    latest: string | null;
+    /** See {@link CatalogItemView.contentChanged}. */
+    contentChanged: boolean;
+}
+export declare function itemView(i: {
+    id: string;
+    name: string;
+    publisher: string;
+    display_name: LocalizedName | null;
+    description: string;
+    policy: CatalogPolicy;
+    latest_version: string;
+    marketplace_id?: string | null;
+    updated_at: Date;
+}, versions: {
+    version: string;
+    source: string;
+    imported_at?: Date;
+}[], installs?: number, marketplace?: MarketplaceStatus): CatalogItemView;
+export {};