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

package/dist/catalog/component-scope.controller.js

@@ -0,0 +1,257 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, HttpCode, Inject, Post, Put, Req } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { orgIconScope, PluginIcons } from "../extensions/plugin-icons.js";
+import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ComponentParams, ComponentDisabledSchema as DisabledBody, ComponentIdSchema as IdParams, ComponentListQuery as ListQuery, OrgComponentListQuery, ComponentScopePreviewSchema as PreviewBody, ComponentScopeSchema as ScopeBody, ComponentShownSchema as ShownBody, ComponentSwitchBody as SwitchBody, ComponentTemplateVersionSchema as TemplateVersionBody, } from "./component-scope.schemas.js";
+import { ComponentScopeService, } from "./component-scope.service.js";
+import { PlatformComponents } from "./platform-components.js";
+class ComponentIdParams extends createZodDto(IdParams, "ComponentIdParams") {
+}
+class TemplateVersionDto extends createZodDto(TemplateVersionBody, "TemplateVersionBody") {
+}
+class ComponentParamsDto extends createZodDto(ComponentParams, "ComponentParams") {
+}
+class ComponentListQuery extends createZodDto(ListQuery, "ComponentListQuery") {
+}
+class OrgComponentListQueryDto extends createZodDto(OrgComponentListQuery, "OrgComponentListQuery") {
+}
+class ComponentScopePreviewBody extends createZodDto(PreviewBody, "ComponentScopePreviewBody") {
+}
+class ComponentScopeBody extends createZodDto(ScopeBody, "ComponentScopeBody") {
+}
+class ComponentDisabledBody extends createZodDto(DisabledBody, "ComponentDisabledBody") {
+}
+class ComponentShownBody extends createZodDto(ShownBody, "ComponentShownBody") {
+}
+class ComponentSwitchBody extends createZodDto(SwitchBody, "ComponentSwitchBody") {
+}
+/**
+ * Each component with `icon`: its plugin's icon URL on the reader's route (null without one, for
+ * a component without a plugin, or when the reader may not see the plugin; maintainer decision
+ * 2026-11-09: a connector template without an icon of its own shows its plugin's).
+ */
+async function withIcons(icons, rows, scope) {
+    const ids = rows.flatMap((r) => (r.itemId === null ? [] : [r.itemId]));
+    const urls = await icons.ofItems(ids, scope);
+    return rows.map((r) => ({ ...r, icon: r.itemId === null ? null : (urls.get(r.itemId) ?? null) }));
+}
+const actorOpts = (actor) => {
+    const tokenId = patTokenId(actor);
+    return tokenId !== undefined ? { actorTokenId: tokenId } : {};
+};
+/**
+ * Platform components (`/api/v1/admin/components/*`, super admins; plugin scope phase 2, Task 6):
+ * the global list of skills, agent templates and connector templates, and each one's own scope,
+ * disable and visibility (spec §5 rules 2, 4, 8, 10). Changes that take something away are
+ * previewed (`POST …/scope/preview`) and confirmed with `scopeHash`.
+ */
+let AdminComponentsController = class AdminComponentsController {
+    scope;
+    components;
+    icons;
+    constructor(scope, components, icons) {
+        this.scope = scope;
+        this.components = components;
+        this.icons = icons;
+    }
+    /**
+     * Updates a platform skill on its own (spec §7.2): the skill package (zip) as the raw body
+     * (`application/octet-stream`, at most `packages.maxBytes`). The package keeps the skill's name
+     * (400 `validation_failed`), is checked like an org upload (400 `skill.invalid_package`), and
+     * becomes the next version, flagged as updated on its own; it keeps its plugin and serves in
+     * orgs at once. Unknown component -> 404 `component.not_found`. Audits `component.version_uploaded`.
+     */
+    uploadSkillVersion(principal, p, req) {
+        const actor = requireUser(principal);
+        const body = req.body;
+        if (!Buffer.isBuffer(body) || body.byteLength === 0) {
+            throw new ApiError("unsupported_media_type", "Send the skill package (.zip) as the request body with content-type application/octet-stream");
+        }
+        return this.components.uploadSkillVersion({ accountId: actor.account.id, ...actorOpts(actor) }, p.id, new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+    }
+    /** Updates a platform agent template on its own: `{ content }` is the template markdown file. */
+    uploadAgentTemplateVersion(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.components.uploadAgentTemplateVersion({ accountId: actor.account.id, ...actorOpts(actor) }, p.id, body.content);
+    }
+    /**
+     * `GET ?kind=`: every platform component of the kind (plugin, owner, scope, version, orgs on),
+     * each with its display name and its plugin's icon (`icon`, the admin route; null without one).
+     */
+    async list(q) {
+        return {
+            components: await withIcons(this.icons, await this.scope.list(q.kind), { kind: "admin" }),
+        };
+    }
+    /**
+     * A component's versions, newest first: `{ versions: [{ version, catalogVersion, updatedOnOwn,
+     * createdAt }] }` (a connector template keeps no history: its current version only). Unknown or
+     * removed -> 404 `component.not_found`.
+     */
+    async versions(p) {
+        return { versions: await this.scope.versions(p.kind, p.id) };
+    }
+    /**
+     * What a component scope change (`{ scope, orgs? }`), a disable (`{ disabled: true }`) or a
+     * return to its plugin's scope (`{ follow: true }`) would do: `{ affected: [{ orgId, orgName,
+     * agents }], conflicts: [{ orgId, orgName, name, skills }], scopeHash }`. Unknown component ->
+     * 404 `component.not_found`; of a builtin plugin -> 409 `plugin.builtin`.
+     */
+    preview(p, body) {
+        return this.scope.preview(p.kind, p.id, body.scope !== undefined
+            ? { scope: body.scope, ...(body.orgs !== undefined && { orgs: body.orgs }) }
+            : body.disabled === true
+                ? { disabled: true }
+                : { follow: true });
+    }
+    /**
+     * Gives the component its own scope, or makes it follow its plugin again, confirmed with the
+     * preview's `scopeHash` (a difference -> 409 `plugin.scope_stale`); an org whose own skill has
+     * its name would newly be offered it -> 409 `plugin.skill_conflict`. Audits
+     * `component.scope_changed`.
+     */
+    setScope(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.scope.setScope(actor.account.id, p.kind, p.id, body.scope !== undefined
+            ? {
+                scope: body.scope,
+                scopeHash: body.scopeHash,
+                ...(body.orgs !== undefined && { orgs: body.orgs }),
+            }
+            : { follow: true, scopeHash: body.scopeHash }, actorOpts(actor));
+    }
+    /** Disables the component on the deployment (`scopeHash` required) or enables it again. */
+    setDisabled(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.scope.setDisabled(actor.account.id, p.kind, p.id, {
+            disabled: body.disabled,
+            ...(body.scopeHash !== undefined && { scopeHash: body.scopeHash }),
+        }, actorOpts(actor));
+    }
+    /** Shows or hides the component to orgs outside its `named` list. */
+    setShown(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.scope.setShown(actor.account.id, p.kind, p.id, body.shownToOthers, actorOpts(actor));
+    }
+};
+__decorate([
+    Post("skill/:id/versions"),
+    HttpCode(201),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentIdParams)),
+    __param(2, Req())
+], AdminComponentsController.prototype, "uploadSkillVersion", null);
+__decorate([
+    Post("agent_template/:id/versions"),
+    HttpCode(201),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentIdParams)),
+    __param(2, ZBody(TemplateVersionDto))
+], AdminComponentsController.prototype, "uploadAgentTemplateVersion", null);
+__decorate([
+    Get(),
+    __param(0, ZQuery(ComponentListQuery))
+], AdminComponentsController.prototype, "list", null);
+__decorate([
+    Get(":kind/:id/versions"),
+    __param(0, ZParam(ComponentParamsDto))
+], AdminComponentsController.prototype, "versions", null);
+__decorate([
+    Post(":kind/:id/scope/preview"),
+    HttpCode(200),
+    __param(0, ZParam(ComponentParamsDto)),
+    __param(1, ZBody(ComponentScopePreviewBody))
+], AdminComponentsController.prototype, "preview", null);
+__decorate([
+    Put(":kind/:id/scope"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentParamsDto)),
+    __param(2, ZBody(ComponentScopeBody))
+], AdminComponentsController.prototype, "setScope", null);
+__decorate([
+    Put(":kind/:id/disabled"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentParamsDto)),
+    __param(2, ZBody(ComponentDisabledBody))
+], AdminComponentsController.prototype, "setDisabled", null);
+__decorate([
+    Put(":kind/:id/shown"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentParamsDto)),
+    __param(2, ZBody(ComponentShownBody))
+], AdminComponentsController.prototype, "setShown", null);
+AdminComponentsController = __decorate([
+    Controller("api/v1/admin/components"),
+    SuperAdmin(),
+    __param(0, Inject(ComponentScopeService)),
+    __param(1, Inject(PlatformComponents)),
+    __param(2, Inject(PluginIcons))
+], AdminComponentsController);
+export { AdminComponentsController };
+/**
+ * An org admin's switch of one platform component (`PUT orgs/:orgId/components/:kind/:id/switch`,
+ * spec §5 rule 5, §13.5): `{ enabled: true }` -> 200 `{ component }`; `{ enabled: false }` on a
+ * component in use -> 200 `{ preview: { agents }, confirm }`, then with `confirm` -> `{ component }`.
+ * The route needs `catalog.read`; the service re-checks the kind's manage action (org admins).
+ */
+let OrgComponentsController = class OrgComponentsController {
+    scope;
+    icons;
+    constructor(scope, icons) {
+        this.scope = scope;
+        this.icons = icons;
+    }
+    /**
+     * The platform components offered to the org (`?kind=`, `?itemId=`: only those; Task 10): each
+     * with its state in the org (`on`, `locked` for `all`, the org's `switch`) and whether an org
+     * admin may switch it. Members read it (the workspace pages are read-only for them). Each has
+     * its display name and `icon`, its plugin's icon on the org's catalog route (null without one,
+     * or when the org's catalog does not show the plugin to the reader: the share gate holds).
+     */
+    async list(org, q) {
+        const rows = await this.scope.orgList(org.orgId, {
+            ...(q.kind !== undefined && { kind: q.kind }),
+            ...(q.itemId !== undefined && { itemId: q.itemId }),
+        });
+        return { components: await withIcons(this.icons, rows, orgIconScope(org)) };
+    }
+    async setSwitch(principal, org, p, body) {
+        const actor = requireUser(principal);
+        const r = await this.scope.setSwitch(org.orgId, actor.account.id, p.kind, p.id, { enabled: body.enabled, ...(body.confirm !== undefined && { confirm: body.confirm }) }, patTokenId(actor));
+        return r.kind === "done"
+            ? { component: r.component }
+            : { preview: r.preview, confirm: r.confirm };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("catalog.read"),
+    __param(0, CurrentOrg()),
+    __param(1, ZQuery(OrgComponentListQueryDto))
+], OrgComponentsController.prototype, "list", null);
+__decorate([
+    Put(":kind/:id/switch"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ComponentParamsDto)),
+    __param(3, ZBody(ComponentSwitchBody))
+], OrgComponentsController.prototype, "setSwitch", null);
+OrgComponentsController = __decorate([
+    Controller("api/v1/orgs/:orgId/components"),
+    __param(0, Inject(ComponentScopeService)),
+    __param(1, Inject(PluginIcons))
+], OrgComponentsController);
+export { OrgComponentsController };

package/dist/catalog/component-scope.schemas.d.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const ComponentKindSchema: z.ZodEnum<{
+    agent_template: "agent_template";
+    connector_template: "connector_template";
+    skill: "skill";
+    theme: "theme";
+}>;
+export declare const OrgComponentListQuery: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodEnum<{
+        agent_template: "agent_template";
+        connector_template: "connector_template";
+        skill: "skill";
+        theme: "theme";
+    }>>;
+    itemId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** `?kind=` of the admin component list. */
+export declare const ComponentListQuery: z.ZodObject<{
+    kind: z.ZodEnum<{
+        agent_template: "agent_template";
+        connector_template: "connector_template";
+        skill: "skill";
+        theme: "theme";
+    }>;
+}, z.core.$strict>;
+export declare const ComponentParams: z.ZodObject<{
+    kind: z.ZodEnum<{
+        agent_template: "agent_template";
+        connector_template: "connector_template";
+        skill: "skill";
+        theme: "theme";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `{ enabled, confirm? }` of the org's switch of a platform component. */
+export declare const ComponentSwitchBody: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const exactlyOnePreviewTarget: (b: {
+    scope?: unknown;
+    disabled?: true | undefined;
+    follow?: true | undefined;
+}) => boolean;
+declare const orgsNeedScope: (b: {
+    scope?: unknown;
+    orgs?: unknown;
+}) => boolean;
+declare const scopeXorFollow: (b: {
+    scope?: unknown;
+    follow?: true | undefined;
+}) => boolean;
+/** The fields of the scope preview body, before its refinements (zod 4 cannot `extend` a refined object). */
+export declare const ComponentScopePreviewFields: 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>>;
+    follow: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/** `{ scope, orgs? }`, `{ disabled: true }` or `{ follow: true }`: exactly one. */
+export declare const ComponentScopePreviewSchema: 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>>;
+    follow: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/** The fields of the scope body, before its refinements. */
+export declare const ComponentScopeFields: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    follow: z.ZodOptional<z.ZodLiteral<true>>;
+    scopeHash: z.ZodString;
+}, z.core.$strict>;
+/** `{ scope, orgs?, scopeHash }` or `{ follow: true, scopeHash }`. */
+export declare const ComponentScopeSchema: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    follow: z.ZodOptional<z.ZodLiteral<true>>;
+    scopeHash: z.ZodString;
+}, z.core.$strict>;
+export declare const ComponentDisabledSchema: z.ZodObject<{
+    disabled: z.ZodBoolean;
+    scopeHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ComponentShownSchema: z.ZodObject<{
+    shownToOthers: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const ComponentIdSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const ComponentTemplateVersionSchema: z.ZodObject<{
+    content: z.ZodString;
+}, z.core.$strict>;
+/** The refinements of the two scope bodies, for operations that rebuild them from the fields. */
+export declare const componentScopeRules: {
+    exactlyOnePreviewTarget: typeof exactlyOnePreviewTarget;
+    orgsNeedScope: typeof orgsNeedScope;
+    scopeXorFollow: typeof scopeXorFollow;
+};
+export declare const COMPONENT_SCOPE_ROUTES: readonly RouteSchemas[];
+export {};

package/dist/catalog/component-scope.schemas.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { COMPONENT_KINDS } from "./component-state.js";
+export const ComponentKindSchema = z.enum(COMPONENT_KINDS);
+export const OrgComponentListQuery = z
+    .object({ kind: ComponentKindSchema.optional(), itemId: z.string().uuid().optional() })
+    .strict();
+/** `?kind=` of the admin component list. */
+export const ComponentListQuery = z.object({ kind: ComponentKindSchema }).strict();
+export const ComponentParams = z.object({
+    kind: ComponentKindSchema,
+    id: z.string().min(1).max(128),
+});
+/** `{ enabled, confirm? }` of the org's switch of a platform component. */
+export const ComponentSwitchBody = z
+    .object({
+    enabled: z.boolean(),
+    confirm: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+})
+    .strict();
+const Scope = z.enum(["all", "optional", "named"]);
+const Orgs = z.array(z.string().min(1).max(128)).max(1000);
+const Hash = z.string().min(1).max(128);
+const exactlyOnePreviewTarget = (b) => [b.scope !== undefined, b.disabled === true, b.follow === true].filter(Boolean).length === 1;
+const orgsNeedScope = (b) => b.scope !== undefined || b.orgs === undefined;
+const scopeXorFollow = (b) => (b.scope !== undefined) !== (b.follow === true);
+/** The fields of the scope preview body, before its refinements (zod 4 cannot `extend` a refined object). */
+export const ComponentScopePreviewFields = z
+    .object({
+    scope: Scope.optional(),
+    orgs: Orgs.optional(),
+    disabled: z.literal(true).optional(),
+    follow: z.literal(true).optional(),
+})
+    .strict();
+/** `{ scope, orgs? }`, `{ disabled: true }` or `{ follow: true }`: exactly one. */
+export const ComponentScopePreviewSchema = ComponentScopePreviewFields.refine(exactlyOnePreviewTarget, { message: "send exactly one of scope (with orgs for named), disabled: true or follow: true" }).refine(orgsNeedScope, { message: "orgs: only allowed with scope named", path: ["orgs"] });
+/** The fields of the scope body, before its refinements. */
+export const ComponentScopeFields = z
+    .object({
+    scope: Scope.optional(),
+    orgs: Orgs.optional(),
+    follow: z.literal(true).optional(),
+    scopeHash: Hash,
+})
+    .strict();
+/** `{ scope, orgs?, scopeHash }` or `{ follow: true, scopeHash }`. */
+export const ComponentScopeSchema = ComponentScopeFields.refine(scopeXorFollow, {
+    message: "send either scope (with orgs for named) or follow: true",
+}).refine(orgsNeedScope, { message: "orgs: only allowed with scope named", path: ["orgs"] });
+export const ComponentDisabledSchema = z
+    .object({ disabled: z.boolean(), scopeHash: Hash.optional() })
+    .strict();
+export const ComponentShownSchema = z.object({ shownToOthers: z.boolean() }).strict();
+export const ComponentIdSchema = z.object({ id: z.string().min(1).max(128) });
+export const ComponentTemplateVersionSchema = z
+    .object({ content: z.string().min(1).max(400_000) })
+    .strict();
+/** The refinements of the two scope bodies, for operations that rebuild them from the fields. */
+export const componentScopeRules = { exactlyOnePreviewTarget, orgsNeedScope, scopeXorFollow };
+export const COMPONENT_SCOPE_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/components", query: OrgComponentListQuery },
+    { route: "GET /api/v1/admin/components", query: ComponentListQuery },
+    { route: "GET /api/v1/admin/components/:kind/:id/versions", params: ComponentParams },
+    {
+        route: "POST /api/v1/admin/components/:kind/:id/scope/preview",
+        params: ComponentParams,
+        body: ComponentScopePreviewSchema,
+    },
+    {
+        route: "PUT /api/v1/admin/components/:kind/:id/scope",
+        params: ComponentParams,
+        body: ComponentScopeSchema,
+    },
+    {
+        route: "PUT /api/v1/admin/components/:kind/:id/disabled",
+        params: ComponentParams,
+        body: ComponentDisabledSchema,
+    },
+    {
+        route: "PUT /api/v1/admin/components/:kind/:id/shown",
+        params: ComponentParams,
+        body: ComponentShownSchema,
+    },
+    {
+        route: "POST /api/v1/admin/components/agent_template/:id/versions",
+        params: ComponentIdSchema,
+        body: ComponentTemplateVersionSchema,
+    },
+    {
+        route: "PUT /api/v1/orgs/:orgId/components/:kind/:id/switch",
+        params: ComponentParams,
+        body: ComponentSwitchBody,
+    },
+];