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

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

@@ -2,10 +2,11 @@ import type { FastifyReply } from "fastify";
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import type { CatalogIcon, OrgCatalogDetail, OrgCatalogItem, OrgCatalogService, OrgInstallResult, OrgUpgradeResult } from "./org-catalog.service.js";
-import type { PluginInstaller, PluginInstallView, UninstallReport } from "./plugin-install.js";
+import type { CatalogIcon, OrgCatalogDetail, OrgCatalogItem, OrgInstallResult, OrgUpgradeResult } from "./catalog-content.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+import { PluginInstaller, type PluginInstallView, type UninstallReport } from "./plugin-install.js";
 import type { UpgradePreview } from "./plugin-upgrade.js";
-import type { CatalogRequestsService, CatalogRequestView } from "./requests.service.js";
+import { CatalogRequestsService, type CatalogRequestView } from "./requests.service.js";
 declare const RequestBody: z.ZodObject<{
     note: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;

package/dist/catalog/org-catalog.controller.js

@@ -7,14 +7,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Query, Res, } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Res } from "@nestjs/common";
 import { z } from "zod";
-import { CATALOG_REQUESTS, ORG_CATALOG, PLUGIN_INSTALLER } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { roleAtLeast } from "../orgs/roles.js";
 import { CredentialValue } from "../tools/connectors.controller.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+import { PluginInstaller } from "./plugin-install.js";
+import { CatalogRequestsService } from "./requests.service.js";
 const RequestBody = z
     .object({
     note: z.string().max(1000).optional(),
@@ -71,6 +74,18 @@ const DecideBody = z.object({ decision: z.enum(["approve", "reject"]) }).strict(
 const AdminListQuery = z.object({
     status: z.enum(["pending", "approved", "rejected", "cancelled"]).optional(),
 });
+class CatalogRequestsQuery extends createZodDto(AdminListQuery, "CatalogRequestsQuery") {
+}
+class CatalogDecideBody extends createZodDto(DecideBody, "CatalogDecideBody") {
+}
+class OrgPluginInstallBody extends createZodDto(InstallBody, "OrgPluginInstallBody") {
+}
+class CatalogRequestBody extends createZodDto(RequestBody, "CatalogRequestBody") {
+}
+class OrgPluginUpgradeBody extends createZodDto(UpgradeBody, "OrgPluginUpgradeBody") {
+}
+class OrgPluginUpgradePreviewBody extends createZodDto(UpgradePreviewBody, "OrgPluginUpgradePreviewBody") {
+}
 /**
  * The enterprise catalog from an organization's view (`/api/v1/orgs/:orgId/...`, human users only):
  * - `GET catalog` (`catalog.read`, member and up; members do not see disabled items);
@@ -182,7 +197,7 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("itemId")),
-    __param(3, Body(new ZodPipe(RequestBody)))
+    __param(3, ZBody(CatalogRequestBody))
 ], OrgCatalogController.prototype, "request", null);
 __decorate([
     Post("catalog/:itemId/install"),
@@ -190,7 +205,7 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("itemId")),
-    __param(3, Body(new ZodPipe(InstallBody))),
+    __param(3, ZBody(OrgPluginInstallBody)),
     __param(4, Res({ passthrough: true }))
 ], OrgCatalogController.prototype, "install", null);
 __decorate([
@@ -212,7 +227,7 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("installId")),
-    __param(3, Body(new ZodPipe(UpgradePreviewBody)))
+    __param(3, ZBody(OrgPluginUpgradePreviewBody))
 ], OrgCatalogController.prototype, "upgradePreview", null);
 __decorate([
     Post("plugin-installs/:installId/upgrade"),
@@ -220,7 +235,7 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("installId")),
-    __param(3, Body(new ZodPipe(UpgradeBody))),
+    __param(3, ZBody(OrgPluginUpgradeBody)),
     __param(4, Res({ passthrough: true }))
 ], OrgCatalogController.prototype, "upgrade", null);
 __decorate([
@@ -230,13 +245,13 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, Body(new ZodPipe(DecideBody)))
+    __param(3, ZBody(CatalogDecideBody))
 ], OrgCatalogController.prototype, "decide", null);
 OrgCatalogController = __decorate([
     Controller("api/v1/orgs/:orgId"),
-    __param(0, Inject(ORG_CATALOG)),
-    __param(1, Inject(CATALOG_REQUESTS)),
-    __param(2, Inject(PLUGIN_INSTALLER))
+    __param(0, Inject(OrgCatalogService)),
+    __param(1, Inject(CatalogRequestsService)),
+    __param(2, Inject(PluginInstaller))
 ], OrgCatalogController);
 export { OrgCatalogController };
 /** Enterprise admins decide deployment-level catalog requests (`/api/v1/admin/catalog/requests`). */
@@ -260,18 +275,18 @@ let AdminCatalogRequestsController = class AdminCatalogRequestsController {
 };
 __decorate([
     Get(),
-    __param(0, Query(new ZodPipe(AdminListQuery)))
+    __param(0, ZQuery(CatalogRequestsQuery))
 ], AdminCatalogRequestsController.prototype, "list", null);
 __decorate([
     Post(":id/decide"),
     HttpCode(200),
     __param(0, CurrentPrincipal()),
     __param(1, Param("id")),
-    __param(2, Body(new ZodPipe(DecideBody)))
+    __param(2, ZBody(CatalogDecideBody))
 ], AdminCatalogRequestsController.prototype, "decide", null);
 AdminCatalogRequestsController = __decorate([
     Controller("api/v1/admin/catalog/requests"),
     EnterpriseAdmin(),
-    __param(0, Inject(CATALOG_REQUESTS))
+    __param(0, Inject(CatalogRequestsService))
 ], AdminCatalogRequestsController);
 export { AdminCatalogRequestsController };

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

@@ -1,199 +1,13 @@
-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 {
-    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;
-};
-/**
- * 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;
-}[]>;
+import { ExtensionRegistry } from "../extensions/registry.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, type OrgUpgradeResult } from "./catalog-content.js";
+import { PluginInstaller } from "./plugin-install.js";
+import { type PluginUpgradeInput, PluginUpgrader, type UpgradePreview } from "./plugin-upgrade.js";
+import { CatalogRequestsService } from "./requests.service.js";
 /**
  * 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
@@ -205,8 +19,21 @@ export declare function readCatalogAgentTemplates(storage: StorageService, v: Ca
  * dependencies are not approved separately, spec §10). No in-process state.
  */
 export declare class OrgCatalogService {
-    private readonly d;
-    constructor(d: OrgCatalogDeps);
+    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 requests;
+    private readonly pluginInstaller;
+    private readonly pluginUpgrader;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: OrgLock, storage: StorageService, registry: ExtensionRegistry, requests: CatalogRequestsService, pluginInstaller: PluginInstaller, pluginUpgrader: PluginUpgrader, log: KernelLogger, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
     /** The org's view of the items; members (not admins) don't see disabled items. */
     list(orgId: string, accountId: string, itemId?: string): Promise<OrgCatalogItem[]>;
     /**
@@ -232,6 +59,11 @@ export declare class OrgCatalogService {
     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>;
+    /**
+     * Role and policy under the org row lock; needs_approval without a grant -> a stage deployment
+     * request (its id). Approval follows this plugin's policy only, not its dependencies' (spec §10).
+     */
+    private requestIfNeeded;
     /** The upgrade preview of an org install (spec §10, see `PluginUpgrader`). */
     upgradePreview(orgId: string, actor: string, installId: string, version: string): Promise<UpgradePreview>;
     /**
@@ -241,6 +73,8 @@ export declare class OrgCatalogService {
      * org admin runs the upgrade again); otherwise the upgrade runs (200, the install view).
      */
     upgrade(orgId: string, actor: string, installId: string, body: PluginUpgradeInput, actorTokenId?: string): Promise<OrgUpgradeResult>;
+    /** Like {@link requestIfNeeded}, for an upgrade's target version. */
+    private upgradeRequestIfNeeded;
     /** The actor can install something in the org (forbidden otherwise), checked before item errors. */
     private assertCanInstall;
 }