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

package/dist/catalog/catalog-items.d.ts

@@ -0,0 +1,290 @@
+import type { Connector, ConnectorTemplateSpec, LocalizedName, PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelSchemaDb, SourceFormat } from "../db/kernel-schema.js";
+import type { ExtensionAdmin } from "../extensions/admin-view.js";
+import type { StorageService } from "../storage/storage.service.js";
+import type { CatalogItemView, CatalogPolicy, CatalogVersionSource, ComponentCounts, PermissionsMismatch, SourceDetail } from "./catalog.service.js";
+import type { TranslationReport } from "./claude/report.js";
+import { type ImportedAs } from "./marketplaces.service.js";
+import { type Owner } from "./ownership.js";
+import type { PluginScope } from "./scope.js";
+/**
+ * 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;
+/**
+ * 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 {
+    /**
+     * A new version of an org-owned item: `latest_version` (and the listing) stays where it is; it
+     * moves only when the version is applied or confirmed (ruling P3-34). The version row is
+     * written not applied (`applied_at` null, ruling P3-52) until {@link markVersionApplied}.
+     */
+    keepLatest?: boolean;
+    /** 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>;
+}
+/**
+ * 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;
+/**
+ * An org's own version imported but not applied (pre-flight F4, ruling P3-12): the live item named
+ * `name` owned by `ownerOrgId` (same package) has a version of the release of `p.version` with the
+ * same content digest and no extension, other than the platform's version. Uploading it again
+ * retries its update instead of `catalog.version_exists`. undefined otherwise.
+ */
+export declare function unappliedOwnVersion(db: KernelSchemaDb, name: string, ownerOrgId: string, p: Pick<ImportIdentity, "packageName" | "version" | "contentDigest">): Promise<{
+    itemId: string;
+    version: string;
+} | undefined>;
+/** 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: KernelSchemaDb, name: string, p: ImportIdentity): Promise<{
+    existing: {
+        id: string;
+    } | undefined;
+    version: string;
+}>;
+/**
+ * Writes a catalog version in the caller's transaction (`db` is its handle; the caller has
+ * re-checked the super admin and holds the name's {@link CatalogItemLock}): 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(db: KernelSchemaDb, w: CatalogVersionWrite): Promise<{
+    id: string;
+    created: boolean;
+}>;
+/**
+ * Records that `version` of the item was applied or confirmed (ruling P3-52), in the caller's
+ * transaction: from then on it may serve other orgs and the generic update. Idempotent.
+ */
+export declare function markVersionApplied(db: KernelSchemaDb, itemId: string, version: string): Promise<void>;
+/**
+ * Whether a version may serve other orgs, dependency resolution and the generic update (ruling
+ * P3-52): applied or confirmed, and never rejected, whoever owns the item now.
+ */
+export declare function versionUsable(v: {
+    applied_at: Date | null;
+    rejected_at: Date | null;
+}): boolean;
+/**
+ * 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, details `[{ owner }]`: the owner of the
+ * package holding it), instead of failing only at deploy time.
+ */
+export declare function assertPluginNameOwner(db: KernelSchemaDb, name: string, packageName: string | null): Promise<void>;
+/** A catalog version as {@link marketplaceLatest} compares it with its marketplace entries. */
+type RecordedVersion = ImportedAs & {
+    imported_at?: Date;
+};
+/** 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;
+}
+/**
+ * For each marketplace-imported item, its marketplace (when enabled): the version to update to
+ * (the highest compatible, importable, non-deprecated stable version listed, a prerelease only
+ * when no such stable version exists, as the market rows fold them), and whether a compatible,
+ * non-deprecated entry's content changed at an imported version.
+ */
+export declare function marketplaceLatest(db: KernelSchemaDb, config: KernelConfig, items: {
+    id: string;
+    name: string;
+    marketplace_id?: string | null;
+}[], versions: ReadonlyMap<string, readonly RecordedVersion[]>): Promise<Map<string, MarketplaceStatus>>;
+/** Org install counts per item (see {@link CatalogItemView.installs}). */
+export declare function countInstalls(db: KernelSchemaDb, items: {
+    id: string;
+    name: string;
+    latest_version: string;
+}[], versions: ReadonlyMap<string, {
+    version: string;
+    extension_sha256: string | null;
+}[]>): Promise<Map<string, number>>;
+/**
+ * Every id is a live org (`validation_failed` naming the unknown ones otherwise): the orgs of a
+ * `named` scope.
+ */
+export declare function assertOrgsExist(db: KernelSchemaDb, orgs: readonly string[]): Promise<void>;
+/** The scope facts of an item's admin view (see {@link CatalogItemView}). */
+export interface ItemScopeFacts {
+    scopeOrgs: string[];
+    enabledOrgs: number;
+    /** Orgs whose admin switched an `all` item off (0 for other scopes and builtin items). */
+    offCount: number;
+    pending: boolean;
+    /** The digest `confirm` takes (null unless pending and readable). */
+    permissionsHash: string | null;
+    /** The platform, or the org that owns the item (ruling P3-1). */
+    owner: Owner;
+}
+/** The facts of a view that shows none of the scope facts, only the item's owner. */
+export declare function ownerOnlyFacts(owner: Owner): ItemScopeFacts;
+/** What an item with an extension needs confirming (see {@link itemConfirmations}). */
+export type ItemConfirmations = ReadonlyMap<string, {
+    pending: boolean;
+    permissionsHash: string | null;
+}>;
+/**
+ * Per item id: is its extension waiting for a person's confirmation (pending) and the permission
+ * digest to confirm. Pending when the extension is not installed on the deployment, when the
+ * installed version's permission set is not covered by the stored snapshot, or (a builtin item)
+ * when the snapshot is the bootstrap step's, never confirmed by a person. Items whose latest
+ * version has no extension are never pending.
+ */
+export declare function itemConfirmations(admin: ExtensionAdmin, items: {
+    id: string;
+    name: string;
+    builtin: boolean;
+    latest_version: string;
+    owner_org_id: string | null;
+    pending_version: string | null;
+}[], versions: ReadonlyMap<string, {
+    version: string;
+    extension_sha256: string | null;
+}[]>): Promise<ItemConfirmations>;
+/**
+ * Per item: the orgs of its `named` list, the orgs it is on in (a live plugin install; every org for
+ * a builtin item) and whether it is pending (`confirmations`, see {@link itemConfirmations}).
+ */
+export declare function itemScopeFacts(db: KernelSchemaDb, items: {
+    id: string;
+    name: string;
+    scope: PluginScope;
+    builtin: boolean;
+    latest_version: string;
+    owner_org_id: string | null;
+}[], confirmations: ItemConfirmations): Promise<Map<string, ItemScopeFacts>>;
+export declare function itemView(i: {
+    id: string;
+    name: string;
+    publisher: string;
+    display_name: LocalizedName | null;
+    description: string;
+    policy: CatalogPolicy;
+    scope: PluginScope;
+    builtin: boolean;
+    disabled: boolean;
+    shown_to_others: boolean;
+    latest_version: string;
+    marketplace_id?: string | null;
+    updated_at: Date;
+    shareable: boolean;
+    awaiting_confirmation: boolean;
+    pending_version: string | null;
+}, versions: {
+    version: string;
+    source: string;
+    imported_at?: Date;
+    /** The version's plugin.json (counted for `componentCounts`; absent: nothing counted). */
+    manifest?: unknown;
+    source_format?: SourceFormat;
+}[], installs?: number, marketplace?: MarketplaceStatus, facts?: ItemScopeFacts): CatalogItemView;
+/** The components a version's plugin.json brings, by kind (none without a manifest). */
+export declare function componentCountsOf(m: PluginManifest | undefined): ComponentCounts;
+export {};