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

package/dist/catalog/catalog-import.module.js

@@ -0,0 +1,63 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { ClientModule } from "../client/client.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { SuperAdminLockModule } from "../identity/super-admin.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { CatalogService } from "./catalog.service.js";
+import { ComponentPromotion } from "./component-promotion.js";
+import { CatalogItemLock, CatalogSourceLock } from "./locks.js";
+import { MarketplacesService } from "./marketplaces.service.js";
+import { PlatformComponents } from "./platform-components.js";
+import { PluginImport } from "./plugin-import.js";
+// Its own file so that `SkillsModule` can import it (an owner's new version of a promoted skill is
+// written to its platform row, ruling P3-4) without a module file cycle through `CatalogModule`.
+/**
+ * The platform side of the catalog: marketplaces, the one import review (prepare -> confirm), the
+ * items and their platform components. The CLI's `capybara plugins *` and `capybara bootstrap` run on this
+ * part alone.
+ */
+let CatalogImportModule = class CatalogImportModule {
+};
+CatalogImportModule = __decorate([
+    Module({
+        imports: [
+            ExtensionsModule,
+            SuperAdminLockModule,
+            // an org upload re-checks the owner org's admin (`PluginImport`, ruling P3-7)
+            OrgLockModule,
+            StorageModule,
+            // the client build prefix goes with an expired org upload's package (`PluginImport`)
+            ClientModule,
+            // a failed post-import platform sync enqueues the migration job (`PluginImport.syncPlatform`)
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
+        providers: [
+            CatalogSourceLock,
+            CatalogItemLock,
+            MarketplacesService,
+            PluginImport,
+            PlatformComponents,
+            // promote on share (ruling P3-3): the admin component routes and the owner's 可共享
+            ComponentPromotion,
+            CatalogService,
+        ],
+        exports: [
+            MarketplacesService,
+            PluginImport,
+            PlatformComponents,
+            ComponentPromotion,
+            CatalogService,
+            CatalogItemLock,
+        ],
+    })
+], CatalogImportModule);
+export { CatalogImportModule };

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

@@ -1,10 +1,13 @@
 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, PermissionsMismatch, SourceDetail } from "./catalog.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
@@ -34,8 +37,20 @@ export interface CatalogListing {
     description: string;
     displayName: LocalizedName | null;
 }
+/**
+ * A stored manifest with `suggestedAppearance.replacements` back in plugin.json order: `order` is
+ * the version's `appearance_order` (the jsonb column does not keep key order); keys it does not
+ * name follow in stored order. Anything else is returned as is.
+ */
+export declare function inAuthorOrder(manifest: unknown, order: readonly string[] | null): unknown;
 /** 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;
@@ -51,6 +66,11 @@ export interface CatalogVersionWrite {
     contentDigest: string;
     /** The normalized plugin.json. */
     manifest: PluginManifest;
+    /**
+     * The keys of `manifest.suggestedAppearance.replacements` in plugin.json order (the manifest may
+     * have passed through jsonb, which does not keep key order); null without replacements.
+     */
+    appearanceOrder: string[] | null;
     listing: CatalogListing;
     /** The id of the item to create when there is none yet (the one the storage prefix used). */
     newItemId: string;
@@ -86,6 +106,16 @@ export interface CatalogVersionWrite {
  * 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;
@@ -126,17 +156,34 @@ export declare function precheckCatalogImport(db: KernelSchemaDb, name: string,
 }>;
 /**
  * Writes a catalog version in the caller's transaction (`db` is its handle; the caller has
- * re-checked the enterprise admin and holds the name's {@link CatalogItemLock}): checks conflicts again (the same source; no version of
+ * 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<string>;
+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), instead of failing only at deploy time.
+ * `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. */
@@ -151,8 +198,10 @@ export interface MarketplaceStatus {
     contentChanged: boolean;
 }
 /**
- * For each marketplace-imported item, its marketplace (when enabled): the highest compatible
- * version listed, and whether a compatible entry's content changed at an imported version.
+ * 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;
@@ -168,6 +217,60 @@ export declare function countInstalls(db: KernelSchemaDb, items: {
     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;
@@ -175,12 +278,24 @@ export declare function itemView(i: {
     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;
-}[], installs?: number, marketplace?: MarketplaceStatus): CatalogItemView;
+    /** 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 {};