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

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

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const CatalogHash: z.ZodString;
+export declare const CatalogItemsQuery: z.ZodObject<{
+    includeDeleted: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    pending: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
+}, z.core.$strip>;
+export declare const CatalogUpdatePreviewBody: z.ZodObject<{
+    version: z.ZodString;
+}, z.core.$strict>;
+export declare const CatalogUpdateBody: z.ZodObject<{
+    version: z.ZodString;
+    diffHash: z.ZodString;
+}, z.core.$strict>;
+/** `:id` as the routes take it (`@Param`). */
+export declare const CatalogIdPathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `:stagingId` of a staged import as the route takes it (`@Param`). */
+export declare const CatalogStagingPathParams: z.ZodObject<{
+    stagingId: z.ZodString;
+}, z.core.$strip>;
+export declare const CatalogNpmImportBody: z.ZodObject<{
+    package: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const CatalogGitImportBody: z.ZodObject<{
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CatalogScope: z.ZodEnum<{
+    all: "all";
+    named: "named";
+    optional: "optional";
+}>;
+export declare const CatalogScopeOrgs: z.ZodArray<z.ZodString>;
+/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
+export declare const CatalogScopePreviewBody: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export declare const CatalogScopeBody: z.ZodObject<{
+    scope: z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scopeHash: z.ZodString;
+}, z.core.$strict>;
+export declare const CatalogDisabledBody: z.ZodObject<{
+    disabled: z.ZodBoolean;
+    scopeHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CatalogShownBody: z.ZodObject<{
+    shownToOthers: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const ADMIN_CATALOG_ROUTES: readonly RouteSchemas[];

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

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { CATALOG_LIST_MAX_LIMIT } from "./catalog.service.js";
+export const CatalogHash = z.string().min(1).max(128);
+export const CatalogItemsQuery = z.object({
+    includeDeleted: z.enum(["true", "false"]).optional(),
+    limit: z.coerce.number().int().min(1).max(CATALOG_LIST_MAX_LIMIT).optional(),
+    offset: z.coerce.number().int().min(0).max(1_000_000).optional(),
+    /** `true`: only the items waiting for a permission confirmation (not paged). */
+    pending: z.enum(["true", "false"]).optional(),
+});
+const CatalogVersion = z.string().min(1).max(256);
+export const CatalogUpdatePreviewBody = z.object({ version: CatalogVersion }).strict();
+export const CatalogUpdateBody = z
+    .object({ version: CatalogVersion, diffHash: CatalogHash })
+    .strict();
+/** `:id` as the routes take it (`@Param`). */
+export const CatalogIdPathParams = z.object({ id: z.string().min(1) });
+/** `:stagingId` of a staged import as the route takes it (`@Param`). */
+export const CatalogStagingPathParams = z.object({ stagingId: z.string().min(1) });
+export const CatalogNpmImportBody = z.object({
+    package: z.string().min(1).max(214),
+    version: z.string().min(1).max(256).optional(),
+});
+export const CatalogGitImportBody = z
+    .object({
+    url: z.string().min(1).max(2000),
+    ref: z.string().min(1).max(256).optional(),
+    path: z.string().min(1).max(512).optional(),
+})
+    .strict();
+export const CatalogScope = z.enum(["all", "optional", "named"]);
+export const CatalogScopeOrgs = z.array(z.string().min(1).max(128)).max(1000);
+/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
+export const CatalogScopePreviewBody = z
+    .object({
+    scope: CatalogScope.optional(),
+    orgs: CatalogScopeOrgs.optional(),
+    disabled: z.literal(true).optional(),
+})
+    .strict()
+    .refine((b) => (b.disabled === true) !== (b.scope !== undefined), {
+    message: "send either scope (with orgs for named) or disabled: true",
+})
+    .refine((b) => b.disabled === undefined || b.orgs === undefined, {
+    message: "orgs: only allowed with scope named",
+    path: ["orgs"],
+});
+export const CatalogScopeBody = z
+    .object({ scope: CatalogScope, orgs: CatalogScopeOrgs.optional(), scopeHash: CatalogHash })
+    .strict();
+export const CatalogDisabledBody = z
+    .object({ disabled: z.boolean(), scopeHash: CatalogHash.optional() })
+    .strict();
+export const CatalogShownBody = z.object({ shownToOthers: z.boolean() }).strict();
+export const ADMIN_CATALOG_ROUTES = [
+    { route: "GET /api/v1/admin/catalog/items", query: CatalogItemsQuery },
+    { route: "GET /api/v1/admin/catalog/items/:id", params: CatalogIdPathParams },
+    {
+        route: "POST /api/v1/admin/catalog/items/:id/update/preview",
+        params: CatalogIdPathParams,
+        body: CatalogUpdatePreviewBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/update",
+        params: CatalogIdPathParams,
+        body: CatalogUpdateBody,
+    },
+    { route: "POST /api/v1/admin/catalog/import/npm", body: CatalogNpmImportBody },
+    { route: "POST /api/v1/admin/catalog/import/git", body: CatalogGitImportBody },
+    { route: "GET /api/v1/admin/catalog/imports/:stagingId", params: CatalogStagingPathParams },
+    {
+        route: "POST /api/v1/admin/catalog/items/:id/scope/preview",
+        params: CatalogIdPathParams,
+        body: CatalogScopePreviewBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/scope",
+        params: CatalogIdPathParams,
+        body: CatalogScopeBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/disabled",
+        params: CatalogIdPathParams,
+        body: CatalogDisabledBody,
+    },
+    {
+        route: "PUT /api/v1/admin/catalog/items/:id/shown",
+        params: CatalogIdPathParams,
+        body: CatalogShownBody,
+    },
+    { route: "DELETE /api/v1/admin/catalog/items/:id", params: CatalogIdPathParams },
+];

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

@@ -0,0 +1,264 @@
+import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type ParsedTheme, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { ExtensionRegistry } from "../extensions/registry.js";
+import type { ExtensionUnavailableReason } from "../extensions/unavailable.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 { readDisplayFiles } from "./catalog-files.js";
+import type { ConnectorInstallInput, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
+import type { OrgPluginState, PluginScope } from "./scope.js";
+/** A catalog item from an organization's view (`GET /orgs/:orgId/catalog`). */
+/** Why an org's plugin is `unavailable` ({@link OrgCatalogItem.reason}). */
+export type PluginUnavailableReason = "plugin_disabled" | ExtensionUnavailableReason;
+export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "marketplaceId" | "latestMarketplaceVersion" | "newerInMarketplace" | "scopeOrgs" | "enabledOrgs" | "offCount" | "pending" | "shownToOthers" | "awaitingConfirmation" | "pendingVersion"> {
+    /** The owner org only (absent for other orgs): its upload waits for the super admin (P3-9). */
+    awaitingConfirmation?: boolean;
+    /** The owner org only (absent for other orgs): the version waiting for that confirmation. */
+    pendingVersion?: string | null;
+    scope: PluginScope;
+    /** Shipped with the deployment (a required bootstrap plugin): on in every org, never switchable. */
+    builtin: boolean;
+    /**
+     * The effective state in this org: `on`, `off`, `needs_config` (installed with an on connector
+     * template that has no connector here, ruling P2-10; or wanted but not installed, and the
+     * install needs inputs), `unavailable` (disabled by the super admin, members don't see it; or
+     * not installed here and its extension cannot run on the deployment, see `reason`) or
+     * `not_offered` (a `named` item shown to orgs outside its list: requestable, not usable).
+     */
+    state: OrgPluginState;
+    /**
+     * Only when `unavailable`: why (Platform tool spec §14.2 problem 1). `plugin_disabled`: the super
+     * admin disabled the item; otherwise its extension's {@link ExtensionUnavailableReason}, the same
+     * one the org's 扩展 page shows.
+     */
+    reason?: PluginUnavailableReason;
+    /** The org admin may switch it (never for `all` and builtin items). */
+    switchable: boolean;
+    /** The plugin's extension (or a template's connector extension) is not on the deployment. */
+    notDeployed: boolean;
+    /**
+     * This org's live plugin install of the item (installing, installed or upgrading);
+     * `upgradeAvailable` is always null since plugin scope phase 2 (no per-org upgrade, ruling F2;
+     * kept for the web until its upgrade dialog goes).
+     */
+    installed: {
+        pluginInstallId: string;
+        version: string;
+        upgradeAvailable: string | null;
+    } | null;
+    /** This org's pending request for the item (spec §5.1), null when none. */
+    request: {
+        id: string;
+        kind: "access" | "enable";
+        createdAt: 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); `implied` ones are the connector extensions its
+     * templates use that the org has off: the install switches them on first.
+     */
+    dependencies: {
+        name: string;
+        range: string;
+        implied?: true;
+    }[];
+    /** The skill directories. */
+    skills: string[];
+    /** The agent template files (`agents/<name>.md`, sub-agents spec §16). */
+    agents: string[];
+    /**
+     * An installed plugin whose connector templates on in the org miss a connector there
+     * (`needs_config`, ruling P2-10): those templates, for `POST …/catalog/:itemId/connectors`;
+     * empty otherwise (Task 10).
+     */
+    missingTemplates: OrgCatalogTemplate[];
+}
+/**
+ * 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";
+}
+/** 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;
+    }[];
+}
+/**
+ * The digest of a skill's files (paths relative to the skill directory): equal digests = the same
+ * content. Shared by the org upgrade diff and the platform components.
+ */
+export declare function skillFilesDigest(files: {
+    path: string;
+    sha256: string;
+}[]): string;
+/** The digest of the files under `dir/` of a catalog version (paths relative to it). */
+export declare function dirDigest(row: CatalogVersionFiles, dir: string): 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, itemId: string, includeDisabled: boolean): Promise<CatalogIcon>;
+export type { ConnectorInstallInput };
+/**
+ * The input of `POST /orgs/:orgId/catalog/:itemId/install`: the platform version is installed
+ * (ruling P2-17), so there is no version.
+ */
+export type OrgInstallInput = PluginInstallInput;
+/** Install result: 201 installed. */
+export interface OrgInstallResult {
+    status: 201;
+    installed: {
+        itemId: string;
+        version: string;
+        pluginInstallId: string;
+    };
+    /** The install view (its components, dependency installs included). */
+    install: PluginInstallView;
+}
+/**
+ * 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`). `actor` null is the kernel itself (the plugin scope sync): the
+ * lock only.
+ */
+export declare function lockOrgForActions(orgLock: Pick<OrgLock, "lock" | "lockAndAuthorize">, orgId: string, actor: string | null, 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[]>;
+/**
+ * Reads a version's display files (icons, setup guide files; `catalog-files.ts`) from PG, sha256
+ * checked, in the order given; no object storage is involved. A listed file missing from PG is lost
+ * or tampered data (`internal`).
+ */
+export declare function readCatalogDisplayFiles(db: Parameters<typeof readDisplayFiles>[0], files: {
+    path: string;
+    size: number;
+    sha256: 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;
+}[]>;
+/** A theme of a catalog version ({@link readCatalogThemes}). */
+export interface CatalogTheme {
+    /** The theme id (the file's base name). */
+    id: string;
+    /** Relative to the plugin root. */
+    path: string;
+    theme: ParsedTheme;
+    /** The theme's fonts and logo files (paths relative to the plugin root), sanitized. */
+    assets: SkillPackageFile[];
+    /** {@link themeAssetsDigest} of the version's records of those files. */
+    assetsDigest: string;
+}
+/** The asset paths a parsed theme references (fonts, logo mark and favicon), without `./`. */
+export declare function themeAssetPaths(theme: ParsedTheme): string[];
+/**
+ * The digest of a theme's assets as recorded on a catalog version (`files`): equal digests = the
+ * same fonts and logo. With the canonical definition it decides whether a theme changed.
+ */
+export declare function themeAssetsDigest(files: {
+    path: string;
+    sha256: string;
+}[], theme: ParsedTheme): string;
+/**
+ * The themes of a catalog version (`manifest.themes`, listed explicitly since import), parsed from
+ * storage and their assets checked again (checked at import; again in case storage was changed).
+ * Grammar and token names are checked again (a token renamed in core stays loud, themes spec
+ * §4.1), but not readability: the version passed it at import, and a later change of the built-in
+ * tokens must not block an update or a rollback to it. A theme that fails -> 400 `theme.invalid`
+ * as at import (themes spec §6: a failing new version blocks the plugin update with the same
+ * refusal).
+ */
+export declare function readCatalogThemes(storage: StorageService, v: CatalogVersionFiles): Promise<CatalogTheme[]>;