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

package/dist/app.js

@@ -0,0 +1,150 @@
+import "reflect-metadata";
+import { NestFactory } from "@nestjs/core";
+import { createKernelAdapter } from "./http/adapter.js";
+import { createHttpApp } from "./http/app.js";
+import { NestLogAdapter } from "./http/nest-logger.js";
+import { GracefulShutdown } from "./infra/lifecycle/graceful-shutdown.service.js";
+import { handleShutdownSignals, } from "./infra/lifecycle/shutdown-signals.js";
+import { setupSwagger } from "./infra/swagger/swagger.js";
+import { KernelModule } from "./kernel.module.js";
+import { KernelLifecycle } from "./lifecycle/kernel-lifecycle.js";
+import { createConfiguredLogger } from "./log-config.js";
+/**
+ * Builds the kernel application (one Nest application, root module {@link KernelModule}) and sets
+ * up its HTTP side, without initializing it: nothing connects and nothing starts. A failure
+ * releases what was created (Redis connections, the pool) before it is thrown. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start; everything else uses {@link createKernelApp}.
+ */
+export async function buildKernelApp(config, options = {}) {
+    const logger = options.logger ?? createConfiguredLogger(config);
+    const app = await NestFactory.create(KernelModule.forRoot(config, { ...options, logger }), createKernelAdapter(config.http.trustProxy), { logger: new NestLogAdapter(logger), abortOnError: false });
+    const lifecycle = app.get(KernelLifecycle);
+    const gateway = lifecycle.gatewayRoutes();
+    try {
+        lifecycle.attachHttp(await createHttpApp({
+            log: logger,
+            servePlugins: config.roles.includes("api") || config.roles.includes("gateway"),
+            ...(gateway !== undefined && { gateway }),
+            replicaId: config.http.replicaId === undefined ? undefined : String(config.http.replicaId),
+            packageMaxBytes: config.packages.maxBytes,
+        }, app));
+        setupSwagger(app, config.http.swagger);
+    }
+    catch (e) {
+        // Nothing started: only release the connections (the stop phases are skipped)
+        lifecycle.releaseOnly();
+        await app.close();
+        throw e;
+    }
+    return app;
+}
+const closing = new WeakMap();
+/**
+ * Closes a kernel application once (later calls get the same promise): the stop phases begin at
+ * once (`KernelLifecycle.stop`: readiness 503, the start aborted at its next checkpoint), next to
+ * `app.close()`, which runs the shutdown hooks (the stop phases are the same promise, then Redis
+ * and the pool). Use it to stop an application from {@link createKernelApp} /
+ * {@link startKernelApp} (tests, `@capybara-hq/testing`), so the stop begins before Nest's
+ * `onModuleDestroy` hooks run.
+ */
+export function closeKernelApp(app) {
+    let p = closing.get(app);
+    if (p === undefined) {
+        p = Promise.all([app.get(KernelLifecycle).stop(), app.close()]).then(() => { });
+        closing.set(app, p);
+    }
+    return p;
+}
+/**
+ * Initializes a built kernel application: `init()` runs the start sequence
+ * (`KernelLifecycle.onApplicationBootstrap`). A failure (unless the shutdown began meanwhile) is
+ * logged; either way the application is closed (the stop phases, then Redis and the pool) before
+ * the error is thrown.
+ */
+async function initKernelApp(app) {
+    try {
+        await app.init();
+    }
+    catch (e) {
+        if (!app.get(GracefulShutdown).isShuttingDown()) {
+            app.get(KernelLifecycle).log.error("kernel start failed", { err: e });
+        }
+        await closeKernelApp(app);
+        throw e;
+    }
+}
+/**
+ * Creates the kernel application and runs its start sequence (nest kernel spec §4): Redis,
+ * migrations, the official marketplace, the bootstrap step, the extension load, the role parts,
+ * extension routes, the lifecycle reconcile and the config watch. Does not listen and installs no
+ * process-wide handler.
+ */
+export async function createKernelApp(config, options = {}) {
+    const app = await buildKernelApp(config, options);
+    await initKernelApp(app);
+    return app;
+}
+/**
+ * Builds the kernel application, installs the SIGTERM / SIGINT handlers
+ * ({@link handleShutdownSignals}), runs the start sequence and listens on `config.http.port`:
+ * nothing is served before the start sequence finished. The handlers are installed before the
+ * start, so a signal during it aborts the start at its next checkpoint and closes the application
+ * cleanly; this function then rejects once the signal path has exited (with 0). A second signal
+ * exits with 1 at once. A failed build or start is logged (`kernel start failed`) before it is
+ * thrown.
+ */
+export async function startKernelApp(config, options = {}, signalOptions = {}) {
+    const logger = options.logger ?? createConfiguredLogger(config);
+    let app;
+    try {
+        app = await buildKernelApp(config, { ...options, logger });
+    }
+    catch (e) {
+        // Nothing to stop (the build released what it created); the process entry only sees the error
+        logger.error("kernel start failed", { err: e });
+        throw e;
+    }
+    await startBuiltKernelApp(app, config, signalOptions);
+    return app;
+}
+/**
+ * The start half of {@link startKernelApp} for an application from {@link buildKernelApp}: installs
+ * the signal handlers, runs the start sequence and listens on `config.http.port`. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start.
+ */
+export async function startBuiltKernelApp(app, config, signalOptions = {}) {
+    const lifecycle = app.get(KernelLifecycle);
+    const signals = handleShutdownSignals(() => closeKernelApp(app), lifecycle.log, signalOptions);
+    try {
+        await initKernelApp(app);
+        try {
+            await lifecycle.listen(config.http.port);
+        }
+        catch (e) {
+            if (!app.get(GracefulShutdown).isShuttingDown()) {
+                lifecycle.log.error("kernel start failed", { err: e });
+            }
+            await closeKernelApp(app);
+            throw e;
+        }
+    }
+    catch (e) {
+        // Stopped by a signal: the signal path closes and exits; otherwise nothing is left to stop
+        const exiting = signals.exiting();
+        if (exiting)
+            await exiting;
+        else
+            signals.dispose();
+        throw e;
+    }
+}
+/** The in-process HTTP of a kernel application (`inject`, the route list). */
+export function kernelAppHttp(app) {
+    return app.get(KernelLifecycle).http;
+}
+/** The port a kernel application listens on; undefined before it listens and after the stop. */
+export function kernelAppPort(app) {
+    return app.get(KernelLifecycle).port;
+}

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

@@ -2,9 +2,9 @@ import type { FastifyReply } from "fastify";
 import { z } from "zod";
 import type { AdminExtensionView } from "../extensions/permission-view.js";
 import { type Principal } from "../identity/principal.js";
-import { type CatalogItemDetail, type CatalogItemView, type CatalogService, type PermissionsMismatch } from "./catalog.service.js";
-import type { OrgCatalogService } from "./org-catalog.service.js";
-import type { PluginConfirmResult, PluginImport, PluginReview } from "./plugin-import.js";
+import { type CatalogItemDetail, type CatalogItemView, CatalogService, type PermissionsMismatch } from "./catalog.service.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+import { type PluginConfirmResult, PluginImport, type PluginReview } from "./plugin-import.js";
 declare const NpmBody: z.ZodObject<{
     package: z.ZodString;
     version: z.ZodOptional<z.ZodString>;

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

@@ -7,14 +7,16 @@ 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, Put, Query, Req, Res, } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { CATALOG, ORG_CATALOG, PLUGIN_IMPORT } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
-import { CATALOG_LIST_MAX_LIMIT, } from "./catalog.service.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
+import { CATALOG_LIST_MAX_LIMIT, CatalogService, } from "./catalog.service.js";
 import { sendCatalogIcon } from "./org-catalog.controller.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+import { PluginImport } from "./plugin-import.js";
 const NpmBody = z.object({
     package: z.string().min(1).max(214),
     version: z.string().min(1).max(256).optional(),
@@ -43,6 +45,18 @@ const actorOpts = (actor) => {
     const tokenId = patTokenId(actor);
     return tokenId !== undefined ? { actorTokenId: tokenId } : {};
 };
+class CatalogImportConfirmBody extends createZodDto(ConfirmBody, "CatalogImportConfirmBody") {
+}
+class CatalogGitImportBody extends createZodDto(GitBody, "CatalogGitImportBody") {
+}
+class CatalogDeploymentInstallBody extends createZodDto(InstallBody, "CatalogDeploymentInstallBody") {
+}
+class CatalogItemsQuery extends createZodDto(ListQuery, "CatalogItemsQuery") {
+}
+class CatalogNpmImportBody extends createZodDto(NpmBody, "CatalogNpmImportBody") {
+}
+class CatalogPolicyBody extends createZodDto(PolicyBody, "CatalogPolicyBody") {
+}
 /**
  * The enterprise catalog (`/api/v1/admin/catalog/*`, enterprise admins): plugin import (upload / npm
  * prepare, then confirm), the item list and detail, policy, delete, and installing an item's
@@ -184,13 +198,13 @@ __decorate([
     Post("import/npm"),
     HttpCode(200),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(NpmBody)))
+    __param(1, ZBody(CatalogNpmImportBody))
 ], AdminCatalogController.prototype, "importNpm", null);
 __decorate([
     Post("import/git"),
     HttpCode(200),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(GitBody)))
+    __param(1, ZBody(CatalogGitImportBody))
 ], AdminCatalogController.prototype, "importGit", null);
 __decorate([
     Get("imports/:stagingId"),
@@ -201,11 +215,11 @@ __decorate([
     HttpCode(201),
     __param(0, CurrentPrincipal()),
     __param(1, Param("stagingId")),
-    __param(2, Body(new ZodPipe(ConfirmBody)))
+    __param(2, ZBody(CatalogImportConfirmBody))
 ], AdminCatalogController.prototype, "confirm", null);
 __decorate([
     Get("items"),
-    __param(0, Query(new ZodPipe(ListQuery)))
+    __param(0, ZQuery(CatalogItemsQuery))
 ], AdminCatalogController.prototype, "list", null);
 __decorate([
     Get("items/:id"),
@@ -220,7 +234,7 @@ __decorate([
     Put("items/:id/policy"),
     __param(0, CurrentPrincipal()),
     __param(1, Param("id")),
-    __param(2, Body(new ZodPipe(PolicyBody)))
+    __param(2, ZBody(CatalogPolicyBody))
 ], AdminCatalogController.prototype, "setPolicy", null);
 __decorate([
     Delete("items/:id"),
@@ -233,13 +247,13 @@ __decorate([
     HttpCode(200),
     __param(0, CurrentPrincipal()),
     __param(1, Param("id")),
-    __param(2, Body(new ZodPipe(InstallBody)))
+    __param(2, ZBody(CatalogDeploymentInstallBody))
 ], AdminCatalogController.prototype, "installToDeployment", null);
 AdminCatalogController = __decorate([
     Controller("api/v1/admin/catalog"),
     EnterpriseAdmin(),
-    __param(0, Inject(CATALOG)),
-    __param(1, Inject(PLUGIN_IMPORT)),
-    __param(2, Inject(ORG_CATALOG))
+    __param(0, Inject(CatalogService)),
+    __param(1, Inject(PluginImport)),
+    __param(2, Inject(OrgCatalogService))
 ], AdminCatalogController);
 export { AdminCatalogController };

package/dist/catalog/catalog-content.d.ts

@@ -0,0 +1,185 @@
+import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { ExtensionRegistry } from "../extensions/registry.js";
+import type { OrgLock } from "../orgs/org-lock.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, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
+import type { CatalogRequestView } from "./requests.service.js";
+/** 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: KernelSchemaDb, 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: KernelSchemaDb, 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;
+};
+/** 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 (`orgLock` joins it) and re-checks the actor can do every action (else `forbidden`). */
+export declare function lockOrgForActions(orgLock: Pick<OrgLock, "lockAndAuthorize">, 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;
+/** The connector `kind` provided by extension `plugin` loaded on this replica (from the registry). */
+export declare function findConnectorIn(registry: Pick<ExtensionRegistry, "list">, plugin: string, kind: string): Connector | undefined;
+/** 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;
+}[]>;