@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

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

@@ -1,213 +1,55 @@
-import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type Logger, type PluginManifest } from "@capybara-hq/plugin-sdk";
-import type { Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import type { ExtensionHost } from "../extensions/host.js";
-import { type OrgAction } from "../orgs/roles.js";
-import { checkSkillFiles, type SkillPackageFile } from "../skills/package.js";
-import type { StorageService } from "../storage/storage.service.js";
-import type { ConnectorTemplateRef, CreateConnectorInput } from "../tools/connectors.service.js";
-import { type CatalogItemView } from "./catalog.service.js";
-import type { ConnectorInstallInput, PluginInstaller, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
-import type { PluginUpgradeInput, PluginUpgrader, UpgradePreview } from "./plugin-upgrade.js";
-import type { CatalogRequestsService, CatalogRequestView } from "./requests.service.js";
-type Trx = Transaction<KernelDatabase>;
-/** A catalog item from an organization's view (`GET /orgs/:orgId/catalog`). */
-export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "marketplaceId" | "latestMarketplaceVersion" | "newerInMarketplace"> {
-    /**
-     * `yes` installable now; `needs_approval` needs enterprise admin approval (install returns 202 and
-     * creates a request); `granted` approved for this org; `disabled` disabled by the enterprise admin
-     * (members don't see it); `not_deployed` the plugin's extension is not on the deployment.
-     */
-    installable: "yes" | "needs_approval" | "granted" | "disabled" | "not_deployed";
-    /**
-     * This org's live plugin install of the item (installing, installed or upgrading);
-     * `upgradeAvailable` is the version it can be upgraded to now (spec §10), null when none.
-     */
-    installed: {
-        pluginInstallId: string;
-        version: string;
-        upgradeAvailable: string | null;
-    } | null;
-    /** This org's latest request for the item. */
-    request: {
-        id: string;
-        stage: "org" | "deployment";
-        status: string;
-    } | null;
-}
-/**
- * One connector template in an item's detail (for the install wizard): the endpoint preset, the
- * paths an org may edit and the auth preset (no credentials). `id` is the template file's base name,
- * sent as `connectors[id]` in the install body.
- */
-export interface OrgCatalogTemplate {
-    id: string;
-    displayName: LocalizedName | null;
-    description: string;
-    plugin: string;
-    connector: string;
-    endpoint: Record<string, unknown>;
-    editableEndpoint: string[];
-    auth: Record<string, unknown>;
-    ownership: "org" | "personal" | null;
-}
-/** `GET /orgs/:orgId/catalog/:itemId`: the item and what the install wizard needs (latest version). */
-export interface OrgCatalogDetail {
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ExtensionAvailability } from "../extensions/unavailable.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 { StorageService } from "../storage/storage.service.js";
+import { type CatalogIcon, type OrgCatalogDetail, type OrgCatalogItem, type OrgInstallInput, type OrgInstallResult } from "./catalog-content.js";
+import { PluginInstaller, type UninstallPreview, type UninstallReport } from "./plugin-install.js";
+/** The result of a switch: the item, or (switching off without `confirm`) the uninstall preview. */
+export type SwitchResult = {
+    kind: "done";
     item: OrgCatalogItem;
-    /** The latest version has an icon (`GET .../icon`). */
-    hasIcon: boolean;
-    /** The plugin's extension (its name), null without one. */
-    extension: string | null;
-    templates: OrgCatalogTemplate[];
-    /** The plugin's dependencies (name and range). */
-    dependencies: {
-        name: string;
-        range: string;
-    }[];
-    /** The skill directories. */
-    skills: string[];
-    /** The agent template files (`agents/<name>.md`, sub-agents spec §16). */
-    agents: string[];
-}
-/**
- * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
- * presets and editable paths, no credentials.
- */
-export declare function orgTemplateView(id: string, file: ConnectorTemplateFile): OrgCatalogTemplate;
-/** An item's icon (the latest version's plugin icon). */
-export interface CatalogIcon {
-    data: Uint8Array;
-    contentType: "image/svg+xml" | "image/png";
-    policy: "allow" | "needs_approval" | "disabled";
-}
-/** The parts of a catalog version row an org install reads. */
-export interface CatalogVersionFiles {
-    manifest: unknown;
-    object_prefix: string | null;
-    files: {
-        path: string;
-        size: number;
-        sha256: string;
-    }[];
-}
-/** Whether the item's latest version has an icon; unreadable counts as none. */
-export declare function catalogHasIcon(db: KernelDb, itemId: string): Promise<boolean>;
-/**
- * Reads the icon of the item's latest version (served only through kernel routes, with nosniff and
- * a CSP sandbox in the response headers; the web only shows it with `<img>`). Item missing, deleted
- * or (when `includeDisabled` is false) disabled -> `catalog.item_not_found` (decided before reading
- * storage); no icon -> `catalog.icon_not_found`; stored content that is not a valid svg / png
- * (checked at import, this guards against tampered storage) -> `internal`.
- */
-export declare function readCatalogIcon(db: KernelDb, storage: StorageService, itemId: string, includeDisabled: boolean): Promise<CatalogIcon>;
-export type { ConnectorInstallInput };
-/** The input of `POST /orgs/:orgId/catalog/:itemId/install` (default version: the latest). */
-export interface OrgInstallInput extends PluginInstallInput {
-    version?: string;
-}
-/** Install result: 201 installed; 202 needs enterprise admin approval, a request was created (or escalated). */
-export type OrgInstallResult = {
-    status: 201;
-    installed: {
-        itemId: string;
-        version: string;
-        pluginInstallId: string;
-    };
-    /** The install view (its components, dependency installs included). */
-    install: PluginInstallView;
-} | {
-    status: 202;
-    request: CatalogRequestView;
-};
-export interface OrgCatalogDeps {
-    db: KernelDb;
-    storage: StorageService;
-    host: Pick<ExtensionHost, "manifests">;
-    /** The connector `kind` provided by extension `plugin` loaded on this replica. */
-    findConnector: TemplateDeps["findConnector"];
-    requests: CatalogRequestsService;
-    pluginInstaller: Pick<PluginInstaller, "install" | "preflight">;
-    pluginUpgrader: Pick<PluginUpgrader, "preview" | "check" | "upgrade">;
-    log?: Pick<Logger, "warn">;
-}
-/** Upgrade result: 200 upgraded (the install view); 202 needs enterprise admin approval, a request was created. */
-export type OrgUpgradeResult = {
-    status: 200;
-    install: PluginInstallView;
 } | {
-    status: 202;
-    request: CatalogRequestView;
+    kind: "preview";
+    preview: UninstallPreview;
+    confirm: string;
 };
 /**
- * The org actions installing / uninstalling a plugin needs: the union over its components (an
- * extension -> `org.extensions.manage`, skills -> `skills.manage`, connector templates ->
- * `connectors.manage`, agent templates -> `agents.manage`), re-checked inside the org row lock.
- */
-export declare function requiredActions(m: PluginManifest): OrgAction[];
-/** Locks the org row in the caller's transaction and re-checks the actor can do every action (else `forbidden`). */
-export declare function lockOrgForActions(t: Trx, orgId: string, actor: string, actions: OrgAction[]): Promise<void>;
-/** The value at a dot path of `v` (own keys only), undefined when absent. */
-export declare function getPath(v: unknown, path: string): unknown;
-/** Sets the value at a dot path of `obj`, creating the objects on the way. */
-export declare function setPath(obj: Record<string, unknown>, path: string, value: unknown): void;
-/** What checking a template's connector extension needs. */
-export interface TemplateDeps {
-    /** The connector `kind` provided by extension `plugin` loaded on this replica. */
-    findConnector: (plugin: string, kind: string) => Connector | undefined;
-    /** The version of an extension loaded on this replica (undefined when not loaded). */
-    pluginVersion: (plugin: string) => string | undefined;
-}
-/**
- * 模板的连接器插件此刻是否可用：插件加载且提供该 kind，并满足 `pluginVersion`（若写了）；不可用返回原因
- * （模型不可见，给管理员看的英文）。
- */
-export declare function templatePluginProblem(d: TemplateDeps, template: ConnectorTemplateSpec): string | undefined;
-/**
- * Builds the connector install input from a connector template plus what the org filled in (C30):
- * the endpoint comes from the template, only paths listed in `editableEndpoint` (or fields under
- * them) may be changed by the org, changing another path -> `validation_failed`; the auth method
- * comes from the template, the org only gives credentials (static credentials via `credential`,
- * OAuth via `client`). Re-checks the template's plugin, kind and `pluginVersion` against the
- * connectors loaded on this replica right now (unmet -> `catalog.not_deployed`); the endpoint
- * (merged as a whole) schema check, credential pattern check and OAuth URL policy are re-checked by
- * `ConnectorsService.create`.
- */
-export declare function templateConnectorInput(deps: TemplateDeps, template: ConnectorTemplateSpec, ref: ConnectorTemplateRef, input: ConnectorInstallInput | undefined, defaultName: string, at?: string): CreateConnectorInput;
-/** 从部署存储读目录版本里的文件（按版本行的 sha256 校验）；`under` 给出时只读该目录下的文件，路径去掉该前缀。 */
-export declare function readCatalogFiles(storage: StorageService, objectPrefix: string | null, files: {
-    path: string;
-    size: number;
-    sha256: string;
-}[], under?: string): Promise<SkillPackageFile[]>;
-/** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
-export declare function skillOf(files: SkillPackageFile[]): ReturnType<typeof checkSkillFiles>;
-/** The connector templates of a catalog version, read from storage (id = the file's base name). */
-export declare function readCatalogTemplates(storage: StorageService, v: CatalogVersionFiles): Promise<{
-    id: string;
-    file: ConnectorTemplateFile;
-}[]>;
-/**
- * The agent templates of a catalog version (`manifest.agents`, listed explicitly since import),
- * parsed from storage (checked at import; parsed again in case storage was changed).
- */
-export declare function readCatalogAgentTemplates(storage: StorageService, v: CatalogVersionFiles): Promise<{
-    path: string;
-    template: AgentTemplate;
-}[]>;
-/**
- * Organizations browse and install from the enterprise catalog (C22): members browse (without
- * disabled items) and request, org admins install. Every item is a plugin, installed with its
- * dependencies by {@link PluginInstaller}; installing requires the union of the component actions
- * of the plugins it brings in ({@link requiredActions}), re-checked inside the org row lock; item
- * disabled -> `catalog.item_disabled`; a dependency unresolved / disabled / in a cycle ->
- * `catalog.dependency_*`; an extension or a template's connector not on the deployment ->
- * `catalog.not_deployed`; needs_approval without a grant -> a stage deployment request (HTTP 202;
- * dependencies are not approved separately, spec §10). No in-process state.
+ * Organizations see the platform catalog with the plugin scope rules applied (plugin and component
+ * management spec §5): a plugin is `all` (on in every org unless an org admin switched it off,
+ * layering spec §4), `optional` (an org admin switches it on), or `named` (offered to the listed
+ * orgs). Members get the list read-only; org admins switch a plugin on (an install by
+ * {@link PluginInstaller}, with its dependencies; the union of the component actions of the plugins
+ * it brings in is re-checked inside the org row lock) or off (an uninstall, after a preview they
+ * confirm with its hash). Disabled item -> `plugin.disabled`; a
+ * dependency unresolved / disabled / in a cycle -> `catalog.dependency_*`; an extension or a
+ * template's connector not on the deployment -> `catalog.not_deployed`. No in-process state.
  */
 export declare class OrgCatalogService {
-    private readonly d;
-    constructor(d: OrgCatalogDeps);
-    /** The org's view of the items; members (not admins) don't see disabled items. */
+    private readonly kdb;
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    private readonly orgLock;
+    private readonly storage;
+    private readonly registry;
+    private readonly pluginInstaller;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    /** Why a plugin's extension cannot run (the `unavailable` state's reason). */
+    private readonly availability;
+    constructor(kdb: KernelDb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: OrgLock, storage: StorageService, registry: ExtensionRegistry, pluginInstaller: PluginInstaller, log: KernelLogger, txHost: TransactionHost, 
+    /** Why a plugin's extension cannot run (the `unavailable` state's reason). */
+    availability: ExtensionAvailability);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
+    /**
+     * The org's view of the items: a `named` item without the org on its list is `not_offered` when
+     * shown to other orgs and absent otherwise; disabled ones are shown to admins as `unavailable`
+     * and absent for members. Each item carries the org's pending request for it.
+     */
     list(orgId: string, accountId: string, itemId?: string): Promise<OrgCatalogItem[]>;
     /**
      * Item detail (for the install wizard): the same view as the list (members don't see disabled
@@ -217,10 +59,11 @@ export declare class OrgCatalogService {
      */
     detail(orgId: string, accountId: string, itemId: string): Promise<OrgCatalogDetail>;
     /**
-     * The item's icon; members don't see disabled items (-> `catalog.item_not_found`, decided before
-     * reading storage).
+     * The item's icon; members don't see disabled items, nobody outside its list sees a hidden
+     * `named` item (-> `catalog.item_not_found`, decided before reading storage). Without `orgId`
+     * (the super admin) every item.
      */
-    icon(itemId: string, isAdmin: boolean): Promise<CatalogIcon>;
+    icon(itemId: string, isAdmin: boolean, orgId?: string): Promise<CatalogIcon>;
     /** For the admin item detail: whether the latest version has an icon. */
     hasIcon(itemId: string): Promise<boolean>;
     /**
@@ -230,17 +73,47 @@ export declare class OrgCatalogService {
      * deployed here (the install reads it again).
      */
     private undeployed;
-    /** Installs a plugin in the org (see the class comment). */
-    install(orgId: string, actor: string, itemId: string, body: OrgInstallInput, actorTokenId?: string): Promise<OrgInstallResult>;
-    /** The upgrade preview of an org install (spec §10, see `PluginUpgrader`). */
-    upgradePreview(orgId: string, actor: string, installId: string, version: string): Promise<UpgradePreview>;
     /**
-     * Upgrades an org install in place (spec §10, Decision 11): the preview's `diffHash` is checked
-     * first (`plugin.upgrade_stale`); the item disabled -> `catalog.item_disabled`; needs_approval
-     * without a grant -> a stage deployment request for the target version (202; after approval the
-     * org admin runs the upgrade again); otherwise the upgrade runs (200, the install view).
+     * Installs a plugin in the org (the old install route, an alias of switching it on): the role
+     * first, then item errors (a member cannot probe a disabled item through error codes), then the
+     * installer. Records the org's switch as on.
+     */
+    install(orgId: string, actor: string, itemId: string, body: OrgInstallInput, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<OrgInstallResult>;
+    /** The item when the org may see it (scope), else `catalog.item_not_found`. */
+    private visibleItem;
+    /** The org's live plugin install of the item, if any. */
+    private liveInstall;
+    /**
+     * The org admin's switch of a plugin (`PUT catalog/:itemId/switch`). On: installs it (or just
+     * records the switch when it is installed already). Off: refused for builtin items
+     * (`plugin.scope_locked`; an `all` one may go off, layering spec §4); without `confirm` returns
+     * the uninstall preview and its hash, with the hash of the current preview uninstalls (a changed
+     * preview -> `plugin.switch_stale`). The switch row is written after the install / uninstall.
+     */
+    setSwitch(orgId: string, actor: string, itemId: string, body: {
+        enabled: true;
+        inputs?: OrgInstallInput;
+    } | {
+        enabled: false;
+        confirm?: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<SwitchResult>;
+    /**
+     * `DELETE plugin-installs/:installId` of a catalog plugin follows the switch-off semantics: builtin
+     * items are refused (`plugin.scope_locked`) unless the install is not live (failed, or
+     * `installing`: the installer cleans up a stale one and refuses a fresh one). Removing a live
+     * install writes the switch row false in the uninstall's transaction (an `all` item then stays
+     * off in the org); removing a failed or stale one writes none.
+     */
+    uninstall(orgId: string, actor: string, installId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<UninstallReport>;
+    private itemOf;
+    /**
+     * Writes the org's switch row of the item under the org row lock. The item row is locked FOR
+     * SHARE first (exclusive with a scope change, an unshare, ruling P3-25, and an owner's delete or
+     * transfer); switching on re-checks that the org may still see it; the install path re-checks the same in `assertItemInstallable`.
      */
-    upgrade(orgId: string, actor: string, installId: string, body: PluginUpgradeInput, actorTokenId?: string): Promise<OrgUpgradeResult>;
+    private recordSwitch;
     /** The actor can install something in the org (forbidden otherwise), checked before item errors. */
     private assertCanInstall;
 }