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

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

@@ -0,0 +1,293 @@
+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 { ExtensionLifecycle } from "../extensions/lifecycle.js";
+import { PluginInstallLock } from "../extensions/locks.js";
+import { SuperAdminLock } from "../identity/super-admin.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 ThemePreview } from "../themes/theme-usage.js";
+import { type ActorOpts, type CatalogItemView, CatalogService } from "./catalog.service.js";
+import { type ComponentKind } from "./component-state.js";
+import { type PluginConfirmResult, PluginImport } from "./plugin-import.js";
+import { PluginInstaller } from "./plugin-install.js";
+import { PlatformPluginUpdater } from "./plugin-upgrade.js";
+import { type PluginScope } from "./scope.js";
+import { PluginScopeSync } from "./scope-sync.js";
+/**
+ * What a scope change or a deployment-level disable would take away (spec §5 rule 8): the orgs
+ * that have the plugin on now (a live install) and would no longer want it, each with its agents
+ * that use the plugin's skills, connectors or agent templates and the number of connectors it
+ * created there, which stay as the org's own; and the orgs that would newly want
+ * it but need inputs first (connector templates, a required org config), which the sync leaves as
+ * `needs_config`. `scopeHash` is confirmed with the change.
+ */
+export interface ScopePreview {
+    affected: {
+        orgId: string;
+        orgName: string;
+        agents: {
+            id: string;
+            name: string;
+        }[];
+        /** The connectors the plugin's install created there: they stay as the org's own. */
+        connectorsKept: number;
+    }[];
+    needsConfig: string[];
+    /**
+     * A scope change only: the plugin's components with their own scope, which the change replaces
+     * (they follow the plugin again, spec §5 rule 2).
+     */
+    replaced: {
+        kind: ComponentKind;
+        id: string;
+        name: string;
+    }[];
+    /**
+     * The orgs the change would newly offer a skill of the plugin whose own skills already use its
+     * name, or turn a theme of the plugin on in where another theme with its id is on (rule 10,
+     * themes spec §6; `kind: "theme"` with the clashing themes in `themes`, `skills` empty): the
+     * change is refused while there are any.
+     */
+    conflicts: {
+        orgId: string;
+        orgName: string;
+        name: string;
+        skills: string[];
+        plugins: string[];
+        /** Set for a theme id clash; absent for a skill. */
+        kind?: "theme";
+        /** A theme id clash: the clashing themes on in the org. */
+        themes?: string[];
+    }[];
+    /**
+     * The plugin's themes the change takes away from some orgs (themes spec §6): the orgs among
+     * them whose default each is and how many people picked it. Absent when no theme is taken away.
+     */
+    themes?: ThemePreview[];
+    scopeHash: string;
+}
+/** A scope change (`orgs` only with `named`) or a disable. */
+export type ScopeTarget = {
+    scope: PluginScope;
+    orgs?: string[];
+} | {
+    disabled: true;
+};
+/**
+ * The refusal of a preview's conflicts: skill ones as `plugin.skill_conflict`, theme ones as
+ * `theme.id_taken`; both at once as `plugin.skill_conflict` listing every clash (the skill details
+ * first, then the theme ones `{ theme, orgId, themes, plugins }`), so none waits for a retry.
+ */
+export declare function conflictsError(conflicts: ScopePreview["conflicts"]): ApiError;
+/**
+ * The super admin's plugin scope and deployment-level disable (plugin and component management
+ * spec §4.1, §5 rules 2-4 and 8), and the import confirm that enqueues the scope sync of the item it
+ * wrote. A change is previewed, then confirmed with the preview's `scopeHash`, recomputed under the
+ * item row lock (a difference -> 409 `plugin.scope_stale`); it bumps `scope_version`, audits
+ * `catalog.scope_changed` and, after the commit, enqueues the item's scope sync, which installs or
+ * uninstalls in every org. Disabling keeps the scope, its org list and the org switches, so
+ * re-enabling (no hash needed) reinstalls where it was on. Builtin items -> 409 `plugin.builtin`.
+ * Stateless, shared by every replica.
+ */
+export declare class CatalogScopeService {
+    private readonly kdb;
+    private readonly adminLock;
+    private readonly catalog;
+    private readonly pluginImport;
+    private readonly installer;
+    private readonly extensions;
+    private readonly ops;
+    private readonly sync;
+    private readonly updater;
+    /** The owner org's lock: an org admin withdrawing its pending upload (ruling P3-10). */
+    private readonly orgLock;
+    /** The per-name install lock a reject / withdraw releases the name claim under (M1). */
+    private readonly installLock;
+    /** This replica's reconcile once a confirmed extension is enabled (before the scope sync). */
+    private readonly lifecycle;
+    /** The removed org plugin's cleanup job, backing the take-out of P3-21 (pre-flight F9). */
+    private readonly maintenance;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, adminLock: SuperAdminLock, catalog: CatalogService, pluginImport: PluginImport, installer: PluginInstaller, extensions: ExtensionAdmin, ops: ExtensionAdminOps, sync: PluginScopeSync, updater: PlatformPluginUpdater, 
+    /** The owner org's lock: an org admin withdrawing its pending upload (ruling P3-10). */
+    orgLock: OrgLock, 
+    /** The per-name install lock a reject / withdraw releases the name claim under (M1). */
+    installLock: PluginInstallLock, 
+    /** This replica's reconcile once a confirmed extension is enabled (before the scope sync). */
+    lifecycle: ExtensionLifecycle, 
+    /** The removed org plugin's cleanup job, backing the take-out of P3-21 (pre-flight F9). */
+    maintenance: Pick<Queue, "add">, log: KernelLogger, txHost: TransactionHost);
+    private get db();
+    /**
+     * Confirms a staged import ({@link PluginImport.confirm}: installs and enables the extension,
+     * writes the new item's scope), then enqueues the item's scope sync when its scope turns it on
+     * by itself (`all` or `named`; an `optional` item is on only where an org admin switches it on).
+     */
+    confirmImport(actor: string, stagingId: string, input: Parameters<PluginImport["confirm"]>[2], opts?: ActorOpts): Promise<PluginConfirmResult>;
+    /**
+     * Confirms the permissions of an item's extension (the admin's 待确认): approves the current
+     * permission set with snapshot source `web` (`permissionsHash` is the item view's, the extension
+     * review digest; a changed set -> 409 `extension.approval_stale`); an extension that was never
+     * deployed (no install record) is installed and enabled first (the package is in the package
+     * store from the import). Nothing waiting (a covered snapshot a person approved already, an item
+     * without an extension) -> 409 `extension.not_pending`. Enqueues the item's scope sync after.
+     *
+     * An org-owned item is confirmed only while an upload of it waits (ruling P3-10, see
+     * {@link confirmOrgUpload}); otherwise -> 409 `extension.not_pending`.
+     */
+    confirmPermissions(actor: string, itemId: string, permissionsHash: string, opts?: ActorOpts): Promise<CatalogItemView>;
+    /**
+     * The super admin's confirmation of an org upload's pending version (rulings P3-10, P3-11,
+     * P3-21): `permissionsHash` must be the digest of that version's package ({@link pendingDigest};
+     * another -> 409 `extension.approval_stale`, also for a version a later upload replaced); no
+     * pending version (withdrawn, rejected, replaced by one without an extension) -> 409
+     * `extension.not_pending`.
+     *
+     * A first version: its extension installed, its permissions approved, enabled, then (one
+     * transaction) the item stops waiting and the owner is told (`upload_confirmed`); after the
+     * commit its platform components are written and the scope sync enqueued. Each step re-reads
+     * the item under its row lock: removed meanwhile -> 409 `catalog.item_removed`, the pending
+     * version replaced -> `extension.approval_stale`; the extension this confirmation installed is
+     * then taken out again. A new version: the platform update to it
+     * ({@link PlatformPluginUpdater.updateToPending}, which installs or upgrades the extension,
+     * clears the pending state, tells the owner and the orgs using a shared plugin), then its
+     * permissions approved.
+     */
+    private confirmOrgUpload;
+    /**
+     * {@link confirmOrgUpload} under the item lock; returns the confirmed first version (its
+     * platform components and scope sync follow after), null for a new version.
+     */
+    private confirmLocked;
+    /** The item is live and its first version confirmed (no longer awaiting). */
+    private confirmed;
+    /**
+     * The error a failed confirmation step answers with: 409 `catalog.item_removed` when the item is
+     * gone or soft-deleted by now, whichever step failed (the removal's cleanup job may take the
+     * extension out under the confirmation, so a step answers `extension.not_found`), the original
+     * error logged; else (or when the item cannot be read) the original error.
+     */
+    private removalOr;
+    /** Clears the pending state of a version an earlier confirmation applied already. */
+    private clearPending;
+    /**
+     * Puts a confirmed new version's pending state back after its approval failed (ruling P3-37):
+     * the version applied, its permissions still waiting, 待确认 shows it again. Not when another
+     * upload is pending meanwhile.
+     */
+    private restorePending;
+    /** Approves the permissions of the installed package `sha` (already covered: nothing to do). */
+    private approvePackage;
+    /**
+     * An extension a confirmation installed whose item was removed or replaced meanwhile is taken
+     * out again (disabled, uninstalled; P3-21), and the name claim released when the item is gone
+     * (ruling P3-37). Inline and best effort (a failure is logged); a removed item's cleanup job
+     * (`owned-plugin-cleanup-<itemId>`, idempotent) is enqueued as well, so a failed take-out is
+     * retried (pre-flight F9).
+     */
+    private takeOut;
+    /** Releases the name claim of a removed item (nothing installed under it any more). */
+    private releaseIfGone;
+    /** The item is still live and pending with `version` (row lock), else 409 (P3-21). */
+    private stillPending;
+    /** {@link stillPending} in the caller's transaction; returns the owner org. */
+    private pendingRow;
+    /** A confirmed first version: the item stops waiting, the owner is told (`upload_confirmed`). */
+    private finishFirstVersion;
+    /**
+     * The super admin rejects an org upload's pending version (ruling P3-10, `reason` shown to the
+     * owner in `upload_rejected`): a first version is removed (soft delete, its requests
+     * cancelled), a new version's pending state cleared (the version stays imported, never applied);
+     * the extension name claim is released when nothing is installed under it (pre-flight F10).
+     * Nothing pending, or a platform-owned item (pre-flight F11) -> 409 `extension.not_pending`.
+     */
+    reject(actor: string, itemId: string, reason: string | null, opts?: ActorOpts): Promise<void>;
+    /**
+     * The owner org withdraws its pending upload (ruling P3-10): as {@link reject}, without a
+     * notice. Another org's or a platform item -> 404; nothing pending -> 409
+     * `extension.not_pending`.
+     */
+    withdraw(orgId: string, actor: string, itemId: string, opts?: ActorOpts): Promise<void>;
+    private dropPending;
+    /** The preview of a scope change or a disable (nothing written). */
+    preview(itemId: string, target: ScopeTarget): Promise<ScopePreview>;
+    /** Changes the scope after its preview (`scopeHash`); returns the item. */
+    setScope(actor: string, itemId: string, body: {
+        scope: PluginScope;
+        orgs?: string[];
+        scopeHash: string;
+    }, opts?: ActorOpts): Promise<CatalogItemView>;
+    /**
+     * Disables the plugin on the whole deployment (after its preview, `scopeHash` required) or
+     * enables it again (no hash); returns the item.
+     */
+    setDisabled(actor: string, itemId: string, body: {
+        disabled: boolean;
+        scopeHash?: string;
+    }, opts?: ActorOpts): Promise<CatalogItemView>;
+    /** Shows or hides the item to orgs outside its `named` list; returns the item. */
+    setShown(actor: string, itemId: string, shown: boolean, opts?: ActorOpts): Promise<CatalogItemView>;
+    private writeShown;
+    private writeScope;
+    private writeDisabled;
+    /**
+     * Writes an org-owned plugin's 可共享 flag and copies it to its component rows (ruling P3-2).
+     * Turning it off narrows an `optional` / `all` plugin, and each component with its own such
+     * scope, to the owner plus the orgs where it is on now (ruling P3-25), and enqueues the item's
+     * scope sync after the commit. The caller authorizes (the owner org's admin, Task 7). A platform
+     * item (no owner) or a missing one -> 404.
+     */
+    setShareable(itemId: string, shareable: boolean, actor?: string | null): Promise<void>;
+    /**
+     * Adds one org to a `named` item's list in the caller's transaction (an approved `access`
+     * request, spec §5.1 rule 2): nobody loses access, so no preview. The item row is locked; it
+     * must be live and not builtin (404 / `plugin.builtin`). Bumps `scope_version`, audits
+     * `catalog.scope_changed` and enqueues the item's scope sync after the commit. Returns whether
+     * the list changed (false: not `named`, or listed already).
+     */
+    addOrg(actor: string, itemId: string, orgId: string, opts?: ActorOpts & {
+        requestId?: string;
+    }): Promise<boolean>;
+    /**
+     * Enqueues the item's scope sync after a commit made elsewhere (an org upload's confirm,
+     * `OrgPluginUploads`); a failure only warns.
+     */
+    enqueueSync(itemId: string): Promise<void>;
+    /** Enqueues the item's scope sync; a failure only warns (the next change or org sync converges). */
+    private enqueue;
+    /**
+     * 409 `theme.platform_default` when a live theme of the item is the platform default and `after`
+     * says the change leaves it narrower than `all` or gone (themes spec §7). In the caller's
+     * transaction, before anything is written.
+     */
+    private assertKeepsPlatformDefault;
+    /** The live item (row locked with `forUpdate`); missing -> 404, builtin -> `plugin.builtin`. */
+    private item;
+    /** The `named` list of the item, sorted. */
+    private listed;
+    /** The state after the change: `orgs` only with `named`, each a live org. */
+    private targetOf;
+    /** The preview of moving `item` to `target` (read through the current context). */
+    private compute;
+    /**
+     * The component side of a plugin scope change or disable (spec §5 rules 2, 8, 10): the
+     * components with their own scope a scope change replaces; the orgs where a skill or agent
+     * template is on now and would be off after (agents merged into `affected`: a component with its
+     * own scope that goes back to following the plugin, or one cut by the disable); and the orgs a
+     * skill would newly be offered to whose own skills use its name, or a theme would come on in
+     * where another theme with its id is on; and per theme the orgs it would go off in
+     * (`themesLost`). `onAfter`: the orgs the plugin is on in after the change.
+     */
+    private componentChanges;
+    /**
+     * Sends the components of the item with their own scope back to following it (a plugin scope
+     * change, spec §5 rule 2): `scope_mode = follow`, their own lists dropped, `scope_version`
+     * bumped, one `component.scope_changed` audit each. In the caller's transaction.
+     */
+    private followAgain;
+}