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

package/dist/catalog/catalog.module.d.ts

@@ -1,13 +1,11 @@
+import { CatalogImportModule } from "./catalog-import.module.js";
+export { CatalogImportModule };
 /**
- * The enterprise side of the catalog: marketplaces, the one import review (prepare -> confirm) and
- * the items with their policy. The CLI's `capybara plugins *` and `capybara bootstrap` run on this
- * part alone.
- */
-export declare class CatalogImportModule {
-}
-/**
- * The plugin catalog (spec §4, §10): {@link CatalogImportModule}, catalog requests, and org installs,
- * upgrades and rollbacks with their dependencies. The catalog's periodic jobs (`CatalogJobs`) are
+ * The plugin catalog (spec §4, §10): {@link CatalogImportModule}, catalog requests, org installs
+ * with their dependencies, the platform plugin update (`PlatformPluginUpdater`), the admin's scope
+ * and disable
+ * (`CatalogScopeService`), org admins' plugin uploads (`OrgPluginUploads`) and their own plugins (`OwnedItems`), and the producer of the plugin scope sync
+ * (`PluginScopeSync`; its consumer is the worker role's `PluginScopeWorkersModule`). The catalog's periodic jobs (`CatalogJobs`) are
  * the worker role's (`WorkerModule`).
  */
 export declare class CatalogModule {

package/dist/catalog/catalog.module.js

@@ -6,43 +6,35 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Module } from "@nestjs/common";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
-import { EnterpriseAdminLockModule } from "../identity/enterprise-admin.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 { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
-import { CatalogService } from "./catalog.service.js";
-import { CatalogItemLock, CatalogSourceLock } from "./locks.js";
-import { MarketplacesService } from "./marketplaces.service.js";
+import { CatalogImportModule } from "./catalog-import.module.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { ComponentScopeService } from "./component-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
-import { PluginImport } from "./plugin-import.js";
+import { OrgExtensionSwitch } from "./org-extension-switch.js";
+import { OrgPluginUploads } from "./org-plugin-uploads.js";
+import { OwnedItems } from "./owned-items.js";
 import { PluginInstaller } from "./plugin-install.js";
-import { PluginUpgrader } from "./plugin-upgrade.js";
+import { PlatformPluginUpdater } from "./plugin-upgrade.js";
 import { CatalogRequestsService } from "./requests.service.js";
-/**
- * The enterprise side of the catalog: marketplaces, the one import review (prepare -> confirm) and
- * the items with their policy. The CLI's `capybara plugins *` and `capybara bootstrap` run on this
- * part alone.
- */
-let CatalogImportModule = class CatalogImportModule {
-};
-CatalogImportModule = __decorate([
-    Module({
-        imports: [ExtensionsModule, EnterpriseAdminLockModule, StorageModule],
-        providers: [
-            CatalogSourceLock,
-            CatalogItemLock,
-            MarketplacesService,
-            PluginImport,
-            CatalogService,
-        ],
-        exports: [MarketplacesService, PluginImport, CatalogService],
-    })
-], CatalogImportModule);
+import { PLUGIN_SCOPE_QUEUE, PluginScopeSync } from "./scope-sync.js";
 export { CatalogImportModule };
+/** The plugin scope sync's queue registration (re-exported: the admin health reads its counts). */
+const PLUGIN_SCOPE_QUEUE_MODULE = QueueModule.registerQueue(PLUGIN_SCOPE_QUEUE);
+/** This module's maintenance queue registration (re-exported for the admin health). */
+const MAINTENANCE_QUEUE_MODULE = QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME);
 /**
- * The plugin catalog (spec §4, §10): {@link CatalogImportModule}, catalog requests, and org installs,
- * upgrades and rollbacks with their dependencies. The catalog's periodic jobs (`CatalogJobs`) are
+ * The plugin catalog (spec §4, §10): {@link CatalogImportModule}, catalog requests, org installs
+ * with their dependencies, the platform plugin update (`PlatformPluginUpdater`), the admin's scope
+ * and disable
+ * (`CatalogScopeService`), org admins' plugin uploads (`OrgPluginUploads`) and their own plugins (`OwnedItems`), and the producer of the plugin scope sync
+ * (`PluginScopeSync`; its consumer is the worker role's `PluginScopeWorkersModule`). The catalog's periodic jobs (`CatalogJobs`) are
  * the worker role's (`WorkerModule`).
  */
 let CatalogModule = class CatalogModule {
@@ -52,19 +44,43 @@ CatalogModule = __decorate([
         imports: [
             CatalogImportModule,
             ExtensionsModule,
-            EnterpriseAdminLockModule,
+            SuperAdminLockModule,
             OrgLockModule,
             StorageModule,
             SkillsModule,
             ToolsModule,
+            // the producer side of the plugin scope sync (`PluginScopeWorkersModule` consumes it)
+            PLUGIN_SCOPE_QUEUE_MODULE,
+            // a removed org plugin's cleanup job (`OwnedItems`, `CatalogScopeService`; consumed by the
+            // worker role's `MaintenanceProcessor`)
+            MAINTENANCE_QUEUE_MODULE,
+        ],
+        providers: [
+            CatalogRequestsService,
+            PluginInstaller,
+            PlatformPluginUpdater,
+            OrgCatalogService,
+            OrgExtensionSwitch,
+            PluginScopeSync,
+            CatalogScopeService,
+            ComponentScopeService,
+            OrgPluginUploads,
+            OwnedItems,
         ],
-        providers: [CatalogRequestsService, PluginInstaller, PluginUpgrader, OrgCatalogService],
         exports: [
+            PLUGIN_SCOPE_QUEUE_MODULE,
+            MAINTENANCE_QUEUE_MODULE,
             CatalogImportModule,
             CatalogRequestsService,
             PluginInstaller,
-            PluginUpgrader,
+            PlatformPluginUpdater,
             OrgCatalogService,
+            OrgExtensionSwitch,
+            PluginScopeSync,
+            CatalogScopeService,
+            ComponentScopeService,
+            OrgPluginUploads,
+            OwnedItems,
         ],
     })
 ], CatalogModule);

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

@@ -1,15 +1,17 @@
 import { type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
 import type { SourceFormat } from "../db/kernel-schema.js";
-import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
-import type { AdminExtensionView } from "../extensions/permission-view.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { PluginInstallLock } from "../extensions/locks.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";
 import type { TranslationReport } from "./claude/report.js";
 import { MarketplacesService } from "./marketplaces.service.js";
+import { type Owner } from "./ownership.js";
 import { PluginImport, type PluginReview } from "./plugin-import.js";
+import type { PluginScope } from "./scope.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. */
@@ -18,8 +20,54 @@ export interface CatalogItemView {
     name: string;
     publisher: string;
     displayName: LocalizedName | null;
+    /** The English description (the plugin.json description's `en`, or the plain string). */
     description: string;
+    /**
+     * The Chinese description of the latest version (its plugin.json `description.zh`, read from the
+     * stored manifest); null without one. The UI shows it in Chinese, else `description`.
+     */
+    descriptionZh: string | null;
+    /** The old item policy, kept for reading only (scope and `disabled` replaced it). */
     policy: CatalogPolicy;
+    /** Who the plugin is offered to (`all` for a builtin plugin). */
+    scope: PluginScope;
+    /** The orgs of a `named` scope (empty otherwise). */
+    scopeOrgs: string[];
+    /** Shipped with the deployment (a required bootstrap plugin): scope `all`, never changed. */
+    builtin: boolean;
+    /** Stopped on the whole deployment by the super admin (its scope is kept). */
+    disabled: boolean;
+    /**
+     * Orgs outside a `named` item's list see it as requestable (`not_offered`); false hides it from
+     * them (spec §5.1 rule 1). Irrelevant for other scopes.
+     */
+    shownToOthers: boolean;
+    /** The platform, or the org that owns it (ruling P3-1; deleted orgs by their name). */
+    owner: Owner;
+    /**
+     * An org-owned item's owner shares it with other orgs (the share gate `owner = platform OR
+     * shareable`, P3-1); false for platform items, which pass the gate anyway.
+     */
+    shareable: boolean;
+    /** An org's upload carrying an extension waits for the super admin's confirmation (P3-9). */
+    awaitingConfirmation: boolean;
+    /** The org-uploaded version that waits for that confirmation (null: none). */
+    pendingVersion: string | null;
+    /** Orgs it is on in: orgs with a live plugin install of it (every org for a builtin plugin). */
+    enabledOrgs: number;
+    /**
+     * Orgs whose admin switched it off while its scope is `all` (layering spec §4: on in every org
+     * unless an org turned it off); 0 for other scopes and for builtin items.
+     */
+    offCount: number;
+    /**
+     * Its extension waits for a person's confirmation: not installed on the deployment, its
+     * permission set not covered by the approved snapshot, or (builtin) only approved by the
+     * bootstrap step. Confirm with `POST items/:id/confirm`.
+     */
+    pending: boolean;
+    /** The digest to send with the confirmation; null unless `pending` and the package is readable. */
+    permissionsHash: string | null;
     latestVersion: string;
     /** Every version, newest first (semver; equal but for build metadata: the later import first). */
     versions: string[];
@@ -31,7 +79,7 @@ export interface CatalogItemView {
     /** The latest version's source (file / npm / marketplace). */
     source: string;
     /**
-     * The marketplace an item was imported from (`official` or an enterprise marketplace id); null
+     * The marketplace an item was imported from (`official` or a custom marketplace id); null
      * when imported by hand or when that marketplace was deleted.
      */
     marketplaceId: string | null;
@@ -51,8 +99,20 @@ export interface CatalogItemView {
      * §5.3). Importing it again records `<version>+git.<sha12>` / `+sha256.<12>`.
      */
     contentChanged: boolean;
+    /** What the latest version's plugin.json brings (read-only; dependencies are not components). */
+    componentCounts: ComponentCounts;
+    /** The format the latest version was read from (`claude-code`: translated from Claude Code). */
+    sourceFormat: SourceFormat;
     updatedAt: string;
 }
+/** The components of a plugin version, by kind (spec §3). */
+export interface ComponentCounts {
+    extension: 0 | 1;
+    skills: number;
+    connectorTemplates: number;
+    agentTemplates: number;
+    themes: number;
+}
 /**
  * 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.
@@ -116,12 +176,19 @@ export interface CatalogItemDetail {
     item: CatalogItemView & {
         packageName: string | null;
         deletedAt: string | null;
+        /**
+         * The version the platform's components come from (spec §7.1): set by the import that created
+         * the item and by each platform update; importing a newer version does not move it.
+         */
+        platformVersion: string;
     };
     versions: CatalogItemVersionView[];
 }
 /** Audits carry the PAT when a personal token made the call. */
 export interface ActorOpts {
     actorTokenId?: string;
+    /** Merged into the audit detail (a write made through the Platform tool: `via`, …). */
+    auditDetail?: Record<string, unknown>;
 }
 /**
  * The marketplace's permission summary differs from the keys computed from the package (a warning,
@@ -155,30 +222,38 @@ export declare const gitFallbackVersion: (commit: string) => string;
 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
+ * Platform catalog items (D9 / C21 / C22, `/api/v1/admin/catalog/*`, super 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.
+ * one review, whose confirm installs the plugin's extension); this service lists and shows items,
+ * deletes, and prepares marketplace imports (scope and disable: `CatalogScopeService`). Stateless,
+ * shared by every replica.
  */
 export declare class CatalogService {
     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 config;
     private readonly installs;
-    private readonly ops;
+    /** The deployment's extensions with their approvals (what is pending confirmation). */
+    private readonly admin;
     /** Plugin import (a marketplace entry goes through its prepare). */
     private readonly pluginImport;
-    /** The token of an enterprise marketplace (sent only to its URL's origin). */
+    /** The token of a custom marketplace (sent only to its URL's origin). */
     private readonly marketplaces;
+    /** Serializes a claim release with an install of that name still committing (F10). */
+    private readonly installLock;
     readonly txHost: TransactionHost;
     constructor(kdb: KernelDb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
-    adminLock: EnterpriseAdminLock, config: KernelConfigService, installs: ExtensionInstalls, ops: ExtensionAdminOps, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock: SuperAdminLock, config: KernelConfigService, installs: ExtensionInstalls, 
+    /** The deployment's extensions with their approvals (what is pending confirmation). */
+    admin: ExtensionAdmin, 
     /** Plugin import (a marketplace entry goes through its prepare). */
     pluginImport: PluginImport, 
-    /** The token of an enterprise marketplace (sent only to its URL's origin). */
-    marketplaces: MarketplacesService, txHost: TransactionHost);
+    /** The token of a custom marketplace (sent only to its URL's origin). */
+    marketplaces: MarketplacesService, 
+    /** Serializes a claim release with an install of that name still committing (F10). */
+    installLock: PluginInstallLock, txHost: TransactionHost);
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
     private get db();
     /** Downloads a marketplace archive source, verified against its integrity. */
@@ -186,7 +261,8 @@ export declare class CatalogService {
     /**
      * 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
+     * the host (`marketplace.incompatible`) and not deprecated (`marketplace.entry_deprecated`, 409; the
+     * confirm does not read the marketplace again); 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:
@@ -237,40 +313,55 @@ export declare class CatalogService {
         includeDeleted?: boolean;
         limit?: number;
         offset?: number;
+        pending?: boolean;
     }): 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;
+        pending?: boolean;
     }): 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>;
-    private writePolicy;
     /**
      * 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`.
+     * them), its themes are soft-deleted (nothing refers to their rows), organizations no longer see
+     * it; the same name can later be imported again as a new item. Deleted / missing -> `catalog.item_not_found`. A platform plugin whose extension is
+     * still enabled on the deployment -> 409 `catalog.extension_enabled` (details
+     * `[{ extension, displayName }]`): disable it on the Extensions page first, as an uninstall
+     * requires. A disabled extension keeps its install record (the super admin uninstalls it on the
+     * Extensions page); an org-owned item's extension is taken out by `OwnedPluginCleanup`.
      */
     remove(actor: string, itemId: string, opts?: ActorOpts): Promise<void>;
+    /**
+     * The precheck of {@link remove} (the Platform tool's `plugins.delete`): throws what the delete
+     * would throw for an enabled extension; read-only, no locks.
+     */
+    assertRemovable(itemId: string): Promise<void>;
     private writeRemove;
     /**
-     * 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`.
+     * A live platform item whose extension (the install of the item's name from its package) is
+     * enabled -> 409 `catalog.extension_enabled`. With `lock`, under the per-name install lock an
+     * enable takes too (the caller's transaction), so no enable slips in between.
+     */
+    private assertExtensionDisabled;
+    /**
+     * The soft delete of {@link remove} in the caller's transaction, without its super admin check
+     * (pre-flight F14: the super admin's remove and an owner's delete or an org deletion,
+     * `OwnedItems.transferOrRemove`, share it): `deleted_at` set, a pending version cleared, the
+     * extension name claim of a first upload still waiting released (ruling P3-37, F10), its themes
+     * soft-deleted (refused with 409 `theme.platform_default` while one is the platform default),
+     * pending requests cancelled, audit `catalog.removed` (`actor` null: the kernel). Returns the
+     * removed item's name, or null when it is gone already.
      */
-    installToDeployment(actor: string, itemId: string, version: string, opts?: ActorOpts): Promise<AdminExtensionView>;
-    private view;
+    removeIn(actor: string | null, itemId: string, opts?: ActorOpts & {
+        reason?: string;
+    }): Promise<{
+        name: string;
+    } | null>;
 }