@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/catalog/plugin-import.d.ts

@@ -1,26 +1,33 @@
-import { type AgentTemplate, type AgentTemplateTier, type LocalizedName } from "@capybara-hq/plugin-sdk";
+import { type AgentTemplate, type AgentTemplateTier, type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { Queue } from "bullmq";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
 import { ExtensionBlobs } from "../extensions/blobs.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
 import { PluginApproveLock, PluginInstallLock } from "../extensions/locks.js";
 import { ExtensionPackageError } from "../extensions/package.js";
 import { type PackageWarning, type PermissionGroup, type PermissionItem } from "../extensions/permission-view.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.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 { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import type { ProvenanceResult } from "../packages/provenance.js";
 import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
 import type { ActorOpts, CatalogItemView, PermissionsMismatch, SourceDetail } from "./catalog.service.js";
 import { type ClaudeEntryOverlay } from "./claude/manifest.js";
 import { type TranslationReport } from "./claude/report.js";
 import { CatalogItemLock } from "./locks.js";
+import { PlatformComponents } from "./platform-components.js";
 import { PluginPackageError } from "./plugin-package.js";
+import type { PluginScope } from "./scope.js";
+/** How long after a failed post-import platform sync the migration job runs for the item. */
+export declare const PLATFORM_SYNC_RETRY_MS = 60000;
 /**
- * Enterprise import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
+ * Platform import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
  * it contains (an extension, skills, connector templates, dependencies), confirmed once.
  *
  * prepare: the tgz is always hostile input, and **nothing is written until every check passes**
@@ -30,7 +37,7 @@ import { PluginPackageError } from "./plugin-package.js";
  * refused; name ownership; a downgrade to a version with unrun migrations is refused), each skill by
  * the skill package rules, each connector template against the connector loaded on this replica (or
  * statically when the connector is provided by the plugin's own extension or by a dependency), the
- * catalog name / version conflicts and the actor still an enterprise admin. Dependencies are only
+ * catalog name / version conflicts and the actor still a super admin. Dependencies are only
  * resolved against the imported catalog versions for the review (an unresolved one does not block
  * the import, spec §4.1); they are never fetched. Only then is the extension handed to
  * `ExtensionInstalls.ingest` (source `catalog`), the skill / template / icon files written to object
@@ -39,13 +46,13 @@ import { PluginPackageError } from "./plugin-package.js";
  * confirm: `reviewHash` must match the staging; in one transaction it deletes the staging row
  * (confirm works once), locks the extension name and recomputes its deployment state (installed /
  * upgraded / swapped after the review -> `plugin.review_stale`), writes the extension's permission
- * snapshot when it is installed by this import (or upgraded with `deployExtension`; source web, audit
- * `extension.permissions_approved` carrying the plugin), and creates the item or adds the version
- * (`manifest` = the normalized plugin.json, `extension_sha256`, the files under the staging prefix).
- * After the commit, with `deployExtension`, the plugin's own extension is installed on the
- * deployment and enabled (`ExtensionAdminOps.install` + `enable`; each replica reconciles, no
- * restart); a failure is returned, not thrown, and an upgrade that was not installed gets its old
- * snapshot back.
+ * snapshot when it is installed or upgraded by this import (source web, audit
+ * `extension.permissions_approved` carrying the plugin), and creates the item (with the scope the
+ * admin chose, default `optional`) or adds the version (`manifest` = the normalized plugin.json,
+ * `extension_sha256`, the files under the staging prefix). After the commit the plugin's own
+ * extension is installed on the deployment and enabled (`ExtensionAdminOps.install` + `enable`;
+ * each replica reconciles, no restart); a failure is returned, not thrown, and an upgrade that was
+ * not installed gets its old snapshot back.
  *
  * Expired staging is cleaned by the maintenance job `app-staging-cleanup`
  * ({@link PluginImport.cleanupExpired}): it deletes the staging row and its object prefix; a stored
@@ -54,7 +61,7 @@ import { PluginPackageError } from "./plugin-package.js";
  */
 /** How long a staged import is kept. */
 export declare const PLUGIN_STAGING_TTL_MS: number;
-/** The deployment state of the plugin's extension and what confirming with `deployExtension` does. */
+/** The deployment state of the plugin's extension and what confirming does with it. */
 export type ExtensionReviewAction = "install" | "upgrade" | "keep";
 /** The plugin's extension in a review. */
 export interface PluginReviewExtension {
@@ -63,10 +70,17 @@ export interface PluginReviewExtension {
     /** sha256 of the plugin tgz (the package store key). */
     sha256: string;
     /**
-     * install: not on the deployment; upgrade: installed from another package (another version), the
-     * import's package replaces it when deployed; keep: this exact package is installed.
+     * install: not on the deployment; upgrade: installed from another package whose version is not
+     * above the import's, the import's package replaces it when confirmed; keep: this exact package is
+     * installed, or the installed version is newer (`olderThanDeployed`): the confirm records the
+     * version in the catalog only and never downgrades the deployment.
      */
     action: ExtensionReviewAction;
+    /**
+     * The import's version is below the one deployed: the review warns that confirming keeps the
+     * deployed extension (action `keep`); absent otherwise.
+     */
+    olderThanDeployed?: true;
     /** Installed on the deployment (any version). */
     deployed: boolean;
     /** The installed version (null when not installed). */
@@ -131,11 +145,19 @@ export interface PluginImportSource {
     /** Where it came from (stored on the catalog version as `source_detail`). */
     detail?: SourceDetail;
 }
+/**
+ * An org upload (spec §14, rulings P3-7, P3-8): the org that will own the plugin. Its admin is
+ * authorized (`catalog.upload`) instead of the super admin, its staging is its own, and the new
+ * item is owned by it with scope `named: [orgId]`.
+ */
+export interface ImportOwner {
+    orgId: string;
+}
 /** The format a plugin was read from: a Capybara plugin, or a translated Claude Code plugin. */
 export type PluginSourceFormat = "capybara" | "claude-code";
 /** The largest license text stored (bytes); a longer one is omitted (`licenseTruncated`). */
 export declare const LICENSE_TEXT_MAX_BYTES = 65536;
-/** The one review of a plugin (the enterprise admin sees every component before confirming). */
+/** The one review of a plugin (the super admin sees every component before confirming). */
 export interface PluginReview {
     name: string;
     /** `claude-code`: translated from a Claude Code plugin (no extension; see `translation`). */
@@ -166,7 +188,10 @@ export interface PluginReview {
     /** package.json `name`; null for a git plugin without package.json. */
     packageName: string | null;
     publisher: string;
+    /** The plugin.json description's English text (a plain string description is English). */
     description: string;
+    /** Its Chinese text (`description.zh`); null without one. */
+    descriptionZh: string | null;
     displayName?: LocalizedName;
     license?: string;
     homepage?: string;
@@ -209,7 +234,7 @@ export interface PluginReview {
     /** Digest of everything above that confirm depends on; sent back on confirm. */
     reviewHash: string;
 }
-/** The deploy result of the plugin's extension with `deployExtension`. */
+/** The deploy result of the plugin's extension at confirm. */
 export interface ExtensionDeployResult {
     name: string;
     action: "install" | "upgrade";
@@ -229,8 +254,21 @@ export interface ExtensionDeployResult {
 /** The result of {@link PluginImport.confirm}. */
 export interface PluginConfirmResult {
     item: CatalogItemView;
-    /** null without `deployExtension` or when there is nothing to deploy (no extension, keep). */
+    /** This confirm created the item (a first import of the name), else it added a version. */
+    created: boolean;
+    /** null when there is nothing to deploy (no extension, or keep). */
     deploy: ExtensionDeployResult | null;
+    /**
+     * An org upload with an extension: the version waits for the super admin's confirmation
+     * (ruling P3-10); nothing was approved, installed or synced.
+     */
+    pending: boolean;
+    /**
+     * The confirm made the item's first usable version: it created the item, or it replaced an org
+     * upload's first version that was still waiting for the super admin with a version without an
+     * extension (applied at once, plan Task 6).
+     */
+    firstVersion: boolean;
 }
 /** What prepare checks besides the package itself (npm and marketplace imports). */
 export interface PluginPrepareExpect {
@@ -252,6 +290,33 @@ export interface ReviewProvenance {
     provenance: ProvenanceResult;
     warning?: "repository_mismatch";
 }
+/** What an org's staged upload targets (see {@link PluginImport.stagedTarget}). */
+export interface StagedTarget {
+    itemId: string;
+    version: string;
+    /** The review's own hash (an org's review of an update shows a combined one, P3-12). */
+    reviewHash: string;
+    /** The review has an extension. */
+    extension: boolean;
+    /** The live item exists already (a new version), owned by the staging's org. */
+    existing: boolean;
+    /** That item's first version still waits for the super admin (P3-9). */
+    awaiting: boolean;
+    /** The version is imported already (pre-flight F4). */
+    retry: boolean;
+    /** The target as the platform updater reads it (the staged manifest and files). */
+    target: {
+        version: string;
+        manifest: PluginManifest;
+        object_prefix: string | null;
+        files: {
+            path: string;
+            size: number;
+            sha256: string;
+        }[];
+        extension_sha256: string | null;
+    };
+}
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
  * `catalog.legacy_format`, anything else -> `catalog.invalid_manifest` (issues as details).
@@ -259,20 +324,27 @@ export interface ReviewProvenance {
 export declare function catalogPackageError(e: PluginPackageError | ExtensionPackageError): ApiError;
 export declare class PluginImport {
     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;
+    /** The owner org's lock: an org upload re-checks its admin under it (ruling P3-7). */
+    private readonly orgLock;
     private readonly installLock;
     private readonly approveLock;
     private readonly itemLock;
     private readonly config;
     private readonly installs;
     private readonly ops;
+    private readonly admin;
     /** Reads a package from the package store (confirm recomputes the permission set). */
     private readonly blobs;
     /** Config-declared names, loaded connectors and extension versions (the extension registry). */
     private readonly registry;
     private readonly log;
     readonly txHost: TransactionHost;
+    /** The platform rows of a new item's components, written after the confirm's commit. */
+    private readonly platform;
+    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
+    private readonly maintenance;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     private files;
     /**
@@ -282,12 +354,18 @@ export declare class PluginImport {
      */
     private connectorsLoaded;
     constructor(kdb: KernelDb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
-    adminLock: EnterpriseAdminLock, installLock: PluginInstallLock, approveLock: PluginApproveLock, itemLock: CatalogItemLock, config: KernelConfigService, storage: StorageService, installs: ExtensionInstalls, ops: ExtensionAdminOps, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock: SuperAdminLock, 
+    /** The owner org's lock: an org upload re-checks its admin under it (ruling P3-7). */
+    orgLock: OrgLock, installLock: PluginInstallLock, approveLock: PluginApproveLock, itemLock: CatalogItemLock, config: KernelConfigService, storage: StorageService, installs: ExtensionInstalls, ops: ExtensionAdminOps, admin: ExtensionAdmin, 
     /** Reads a package from the package store (confirm recomputes the permission set). */
     blobs: ExtensionBlobs, 
     /** Config-declared names, loaded connectors and extension versions (the extension registry). */
-    registry: ExtensionRegistry, log: KernelLogger, txHost: TransactionHost);
+    registry: ExtensionRegistry, log: KernelLogger, txHost: TransactionHost, 
+    /** The platform rows of a new item's components, written after the confirm's commit. */
+    platform: PlatformComponents, 
+    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
+    maintenance: Pick<Queue, "add">);
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
     private get db();
     /**
@@ -297,9 +375,11 @@ export declare class PluginImport {
      */
     useCliStorage(storage: PrefixedStorage): void;
     /**
-     * The enterprise-admin re-check under the lock, in the caller's transaction. `actor` null is the
+     * The super-admin re-check under the lock, in the caller's transaction. `actor` null is the
      * CLI (the operator of the deployment: no account to re-check, audits carry no actor), like
-     * `ExtensionInstalls.ingest`.
+     * `ExtensionInstalls.ingest`. An org upload (`owner`) re-checks the actor as an admin of the
+     * owner org under the org row lock instead (`catalog.upload`; an org deleted meanwhile -> 404
+     * `org.not_found`).
      */
     private authorizeActor;
     /** The re-check alone, in a transaction of its own (before anything is written). */
@@ -318,6 +398,8 @@ export declare class PluginImport {
         };
         provenance?: ReviewProvenance;
         claudeManifestIgnored?: true;
+        /** An org upload (a `file` source only, ruling P3-7). */
+        owner?: ImportOwner;
     }): Promise<{
         stagingId: string;
         review: PluginReview;
@@ -371,39 +453,90 @@ export declare class PluginImport {
     /**
      * A staged import's review, as prepare returned it, with a marketplace import's permission
      * mismatch when there is one (the import page loads `?staging=<id>` with it). Unknown, expired or
-     * already confirmed -> 404 `plugin.staging_not_found`.
+     * already confirmed -> 404 `plugin.staging_not_found`. Each sees only its own staging (P3-8):
+     * the super admin's routes the platform's (no `owner`), an org's routes that org's.
      */
-    staged(stagingId: string): Promise<{
+    staged(stagingId: string, owner?: ImportOwner): Promise<{
         stagingId: string;
         review: PluginReview;
         permissionsMismatch?: PermissionsMismatch;
     }>;
     /**
-     * Confirms a staged import (see the file header). Returns the committed catalog item and, with
-     * `deployExtension`, the extension's deploy result (a failed deploy is returned, not thrown).
+     * What an org's staged upload targets (P3-12, pre-flight F3): its item, version and review hash,
+     * whether the item exists (a new version of the org's own plugin) or the version is imported
+     * already (F4), and the target as the platform updater reads it: the staged manifest and files,
+     * or the imported version's for a retry. Another org's staging -> 404 `plugin.staging_not_found`.
+     */
+    stagedTarget(stagingId: string, owner: ImportOwner): Promise<StagedTarget>;
+    /** The catalog item's view (as a confirm returns it). */
+    view(itemId: string): Promise<CatalogItemView>;
+    /**
+     * Confirms a staged import (see the file header). Returns the committed catalog item and the
+     * extension's deploy result (a failed deploy is returned, not thrown). `scope` (default
+     * `optional`) and `orgs` (only with `named`; each an existing org, else `validation_failed`) are
+     * written when this confirm creates the item; a new version of an existing item keeps its scope.
+     * The caller enqueues the scope sync of the item after this returns.
+     *
+     * An org upload (`opts.owner`, spec §14): only that org's staging; the actor re-checked as its
+     * admin; `scope` / `orgs` are not taken: a new item is owned by the org, scope `named: [owner]`,
+     * not shown to other orgs, `shareable` as given (default false). Custom deny, the name owner and
+     * the dependencies are checked again under the item name's lock. A package with an extension
+     * is stored and its extension name claimed, nothing approved or installed: the version waits
+     * for the super admin (`pending`, ruling P3-10; see {@link commit}).
      */
     confirm(actor: string | null, stagingId: string, input: {
         reviewHash: string;
-        deployExtension: boolean;
         /**
-         * With `deployExtension`: enable the extension after installing it (default true). false
-         * keeps the install record's desired state (a new install stays disabled), for the bootstrap
-         * step's upgrades of a plugin an enterprise admin may have disabled.
+         * Enable the extension after installing it (default true). false keeps the install record's
+         * desired state (a new install stays disabled), for the bootstrap step's upgrades of a
+         * plugin a super admin may have disabled.
          */
         enable?: boolean;
+        /** The new item's scope (default `optional`). */
+        scope?: PluginScope;
+        /** The orgs of a `named` scope. */
+        orgs?: string[];
         /**
          * The skills (by name, each in the review) suggested as pinned when an agent selects them
          * (spec §9.1); replaces the plugin's `pinned` flags in the stored manifest. Omitted keeps
-         * them. An admin decision like `deployExtension`, so not part of `reviewHash`.
+         * them. An admin decision like the scope, so not part of `reviewHash`.
          */
         pinnedSuggestions?: string[];
-    }, opts?: ActorOpts): Promise<PluginConfirmResult>;
+        /** An org upload's new item: shared with other orgs by its owner (default false, P3-16). */
+        shareable?: boolean;
+    }, opts?: ActorOpts & {
+        owner?: ImportOwner;
+    }): Promise<PluginConfirmResult>;
+    /**
+     * Writes the platform components of an item's first usable version after a commit made
+     * elsewhere (the super admin's confirmation of an org upload, `CatalogScopeService`); a failure
+     * is logged and retried by the migration job (see {@link syncPlatform}).
+     */
+    writePlatformComponents(itemId: string, version: string): Promise<void>;
     /**
      * The confirm's transaction: the staging row consumed, the extension's action recomputed under
      * its install lock (stale -> `plugin.review_stale`), its snapshot approved, and the catalog
      * version written under the item name's lock.
+     *
+     * An org upload with an extension (ruling P3-10) approves nothing: under the install lock it
+     * claims the extension name for its package (another package's -> 409
+     * `extension.name_conflict` naming its owner, before anything is written), and the version
+     * written becomes the item's pending one (`pending_version` / `_by` / `_at`; a first version
+     * also `awaiting_confirmation`). A later upload replaces the pending version (P3-11). An org
+     * upload without an extension for an item whose first version still waits (plan Task 6) replaces
+     * that upload and applies at once: the item stops waiting and the claim is released (nothing
+     * was installed under it).
      */
     private commit;
+    /**
+     * The platform components of a new item. The item is committed already, so a failure is logged
+     * and not thrown (like a failed deploy, the import itself succeeded); a run of the platform
+     * components migration job (which writes what is missing) is enqueued on `cap-kernel-maintenance`
+     * after {@link PLATFORM_SYNC_RETRY_MS}, one per item (deterministic job id). If that run fails
+     * too, its `itemsFailed` shows in the super admin's inbox; the daily run and every worker start
+     * try again.
+     */
+    private syncPlatform;
     /**
      * Writes the extension's permission snapshot for the version being imported (source web; cli
      * without an actor; bootstrap for the bootstrap step), after
@@ -437,6 +570,14 @@ export declare class PluginImport {
      * replica has it or it is gone.
      */
     private cleanupOne;
+    /**
+     * An expired org staging's extension package (an org upload stores it at prepare, P3-10): removed
+     * with the staging unless something else uses it — an install (running or migrated), a catalog
+     * version, another staging — or it was stored by anyone else (the package row's source must be
+     * this staging's own `catalog` ref). A platform staging keeps its package, as before. Its object
+     * is deleted after the commit.
+     */
+    private dropOrgPackage;
     /** npm / marketplace imports: the package must be the one that was asked for. */
     private checkExpected;
     /** A config-declared extension's name cannot be taken by an imported plugin. */
@@ -448,7 +589,10 @@ export declare class PluginImport {
     private checkContent;
     /**
      * The highest imported, non-deleted catalog version satisfying each dependency's range (null when
-     * none does).
+     * none does). An org upload (`owner`, P3-13) resolves only against items the org can use
+     * ({@link usableBy}: confirmed, not disabled, offered to it), and any dependency left unresolved
+     * -> 409 `plugin.dependency_unavailable` (details `[{ dependencies }]`, their names): an org
+     * upload never brings in anything the org could not install itself.
      */
     private resolveDependencies;
     /**