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

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

@@ -0,0 +1,394 @@
+import type { LocalizedName, ThemeScheme } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { type ThemeSwatch } from "../themes/theme-state.js";
+import { type ThemePreview } from "../themes/theme-usage.js";
+import type { ActorOpts } from "./catalog.service.js";
+import { ComponentPromotion } from "./component-promotion.js";
+import { type ComponentKind } from "./component-state.js";
+import { type Owner } from "./ownership.js";
+import type { PluginScope } from "./scope.js";
+/**
+ * What a component scope change, a component disable or a switch back to its plugin's scope would
+ * do (spec §5 rules 8 and 10): the orgs where it is on now and would be off, with their agents that
+ * use it (by its id or an org copy linked to it), and the orgs it would newly be offered to whose
+ * own skills already use its name (the change is refused while there are any). `scopeHash` is
+ * confirmed with the change.
+ */
+export interface ComponentScopePreview {
+    affected: {
+        orgId: string;
+        orgName: string;
+        agents: {
+            id: string;
+            name: string;
+        }[];
+        /** A connector template: the org's connectors made from it, which stay as the org's own. */
+        connectorsKept: number;
+    }[];
+    /**
+     * `skills`: the clashing skill ids (org skills, other platform skills; for an agent template the
+     * clashing template ids, `name` its roster type, ruling P4-13); `plugins`: theirs.
+     */
+    conflicts: {
+        orgId: string;
+        orgName: string;
+        name: string;
+        skills: string[];
+        plugins: string[];
+        /** An agent template's: the owner of each clashing template, in `skills`' order. */
+        owners?: Owner[];
+        /** A theme's: the clashing themes on in the org (`skills` then empty). */
+        themes?: string[];
+    }[];
+    /**
+     * A theme the change takes away from some orgs (themes spec §6): the orgs among them whose
+     * default it is and how many people picked it. Absent when no theme is taken away.
+     */
+    themes?: ThemePreview[];
+    scopeHash: string;
+}
+/** A component's own scope (`orgs` only with `named`), a disable, or following its plugin again. */
+export type ComponentTarget = {
+    scope: PluginScope;
+    orgs?: string[];
+} | {
+    disabled: boolean;
+} | {
+    follow: true;
+};
+/**
+ * A component in the admin list (`GET admin/components`): a platform component, or (ruling P2-11)
+ * an org's own skill or agent template, listed read-only (`owner` = the org; its scope fields
+ * say it is on in that org only; scope, disable and uploads are platform-only, 404 for it).
+ */
+export interface ComponentView {
+    kind: ComponentKind;
+    id: string;
+    /** Skill or template name; a connector template's id (the file's base name). */
+    name: string;
+    /** A connector template's localized display name (null: show `name`). */
+    displayName: {
+        zh: string;
+        en: string;
+    } | null;
+    description: string | null;
+    /** The description's Chinese text (null: show `description` in every locale). */
+    descriptionZh: string | null;
+    /** The plugin it came from (null: none). */
+    plugin: string | null;
+    itemId: string | null;
+    /** The platform, or the org that owns it (ruling P3-1). */
+    owner: Owner;
+    /** Its owner shares it with other orgs (the share gate; always false for the platform's). */
+    shareable: boolean;
+    /**
+     * A platform row created from an org's own skill or agent template when it was first shared
+     * (promote on share, ruling P3-3); false for an org row and for a plugin's component.
+     */
+    promoted: boolean;
+    /** Of a builtin plugin: on everywhere, its scope cannot be changed nor disabled (409). */
+    builtin: boolean;
+    scopeMode: "follow" | "own";
+    /** The effective scope: the plugin's (builtin: `all`) when following it, else its own. */
+    scope: PluginScope;
+    /** The effective `named` list (the plugin's when following it), sorted. */
+    orgs: string[];
+    disabled: boolean;
+    /** The plugin is disabled or deleted: the component is off everywhere. */
+    pluginStopped: boolean;
+    shownToOthers: boolean;
+    version: string;
+    /** The orgs it is on in now, sorted. */
+    onIn: string[];
+    /**
+     * Orgs whose admin switched it off while its effective scope is `all` (layering spec §4); 0 for
+     * other scopes, builtin plugins and orgs' own rows.
+     */
+    offCount: number;
+    /** A theme: its name and swatches from its current version (absent for other kinds). */
+    theme?: {
+        name: LocalizedName;
+        swatches: Partial<Record<ThemeScheme, ThemeSwatch>>;
+    };
+}
+/** One version of a platform component (`GET admin/components/:kind/:id/versions`). */
+export interface ComponentVersionView {
+    /** The component's own version counter (a connector template: its catalog version). */
+    version: string;
+    /** The plugin version it came from (null: uploaded on its own). */
+    catalogVersion: string | null;
+    /** Written by an upload of the component on its own (spec §7.2). */
+    updatedOnOwn: boolean;
+    createdAt: string;
+}
+/** An org's view of one component after its switch. */
+export interface OrgComponentView {
+    kind: ComponentKind;
+    id: string;
+    name: string;
+    plugin: string | null;
+    /** The org's switch (null: never switched). */
+    switch: boolean | null;
+    on: boolean;
+    /**
+     * Of a builtin plugin, or the platform default theme (themes spec §7): it cannot be switched off
+     * (an `all` one can, layering spec §4).
+     */
+    locked: boolean;
+}
+/**
+ * A platform component offered to an org (`GET orgs/:orgId/components`, Task 10): on there, or one
+ * an org admin could switch on; what the workspace 技能 / 智能体模板 pages and the plugin detail
+ * show with their switches. Never a component the org cannot see.
+ */
+export interface OrgOfferedComponentView extends OrgComponentView {
+    /** A connector template's localized display name (null: show `name`). */
+    displayName: {
+        zh: string;
+        en: string;
+    } | null;
+    description: string | null;
+    /** The description's Chinese text (null: show `description` in every locale). */
+    descriptionZh: string | null;
+    itemId: string | null;
+    version: string;
+    scopeMode: "follow" | "own";
+    /** A `follow` component's plugin is on in the org (always true for `own`). */
+    pluginOn: boolean;
+    /**
+     * An org admin may switch it now: not locked, and (`follow`) its plugin is on in the org (a
+     * component of a plugin that is off is switched on with the plugin, spec §5 rule 5).
+     */
+    switchable: boolean;
+    /** On by platform default: the effective scope (its own, or its plugin's) is `all` and it is not builtin. */
+    platformDefault: boolean;
+    /**
+     * The org's copies linked to it without a pin (skills, agent templates): agents that select one
+     * of these ids use this component, and lose it while it is off (spec §5 rule 8).
+     */
+    linkedIds: string[];
+    /**
+     * The platform, or the org that owns it (an org's upload, ruling P3-1): what the workspace pages
+     * name as its owner (本组织 for the viewing org's own, the owner's name for another org's).
+     */
+    owner: Owner;
+    /**
+     * Connector templates only: the template's setup guide in its plugin's latest version (`GET
+     * …/catalog/:itemId/guides/:guideId`), null without one (spec 2026-11-09-setup-guides-v2 §9.3).
+     */
+    guide?: {
+        itemId: string;
+        guideId: string;
+    } | null;
+}
+/** The result of an org switch: the component, or (switching off without `confirm`) the preview. */
+export type ComponentSwitchResult = {
+    kind: "done";
+    component: OrgComponentView;
+} | {
+    kind: "preview";
+    preview: {
+        agents: {
+            id: string;
+            name: string;
+            refs: string[];
+        }[];
+        connectorsKept: number;
+        /**
+         * A theme: whether it is the org's default and how many of its members picked it (themes
+         * spec §6). Absent for other kinds and for a theme nobody there chose.
+         */
+        themes?: ThemePreview[];
+    };
+    confirm: string;
+};
+/** Actor facts of a write: the token, and detail the caller adds to the audit row. */
+type AuditOpts = ActorOpts & {
+    auditDetail?: Record<string, unknown>;
+};
+/**
+ * 409 `plugin.skill_conflict` listing the orgs whose own skills use a component's name (rule 10);
+ * for a theme 409 `theme.id_taken` listing the orgs where another theme with its id is on (details
+ * `[{ theme, orgId, themes, plugins }]`);
+ * for an agent template 409 `agent_template.name_taken` listing the orgs that already use its
+ * roster type (ruling P4-13; details `[{ orgId, type, templateId, owner }]`, one per clashing
+ * template, `owner` as save-as names it).
+ */
+export declare function nameConflictError(conflicts: ComponentScopePreview["conflicts"], kind?: ComponentKind): ApiError;
+/**
+ * Component scope and org switches (plugin scope phase 2, Task 6; spec §5 rules 2, 5, 8, 10, 11,
+ * §13.5). The super admin gives a platform component its own scope (`all` / `optional` / `named`),
+ * sends it back to following its plugin, disables it on the whole deployment or shows it to other
+ * orgs; each change that takes something away is previewed and confirmed with `scopeHash`
+ * (recomputed under the component row lock; a difference -> 409 `plugin.scope_stale`), and one that
+ * would offer a skill to an org whose own skill has its name is refused (409 `plugin.skill_conflict`).
+ * An org admin switches one component on or off in the org (only that component, rule 5); one of a
+ * builtin plugin -> 409 `plugin.scope_locked` (an `all` one may go off, layering spec §4); switching
+ * off something in use is previewed with its agents first.
+ * Name clashes are checked for skills, agent templates by their roster type, and themes by their
+ * id among the themes on in an org (themes spec §6). A change that would take the platform default
+ * theme away from an org is refused (409 `theme.platform_default`, themes spec §7). Components are
+ * resolved at read time (skills/usable.ts, agents/templates.ts), so nothing is enqueued.
+ * Stateless, shared by every replica.
+ */
+export declare class ComponentScopeService {
+    private readonly kdb;
+    private readonly adminLock;
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    private readonly orgLock;
+    /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
+    private readonly promotion;
+    readonly txHost: TransactionHost;
+    /** The connector templates' setup guides (the org list's `guide`). */
+    private readonly guides;
+    constructor(kdb: KernelDb, adminLock: SuperAdminLock, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: OrgLock, 
+    /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
+    promotion: ComponentPromotion, txHost: TransactionHost, 
+    /** The connector templates' setup guides (the org list's `guide`). */
+    guides: Pick<PluginGuides, "templateGuides">);
+    private get db();
+    /**
+     * What the admin routes act on (ruling P3-23): the platform component `id`, an org row the org
+     * promoted already (its platform row), or an org's own row not promoted yet. A connector
+     * template or a theme has no org rows; anything else -> 404 `component.not_found`.
+     */
+    private resolve;
+    /**
+     * Runs `write` with the org row prepared for promotion ({@link ComponentPromotion.prepare}, files
+     * copied before the transaction), preparing again when the row changed meanwhile.
+     */
+    private withPromotion;
+    /** The platform components of `kind`, with their effective scope and the orgs they are on in. */
+    list(kind: ComponentKind): Promise<ComponentView[]>;
+    /**
+     * The platform components offered to the org (`kind` / `itemId`: only those), by kind then name:
+     * on there, or visible to it and not stopped on the deployment (spec §5 rules 5, 11, §13.5).
+     */
+    orgList(orgId: string, filter: {
+        kind?: ComponentKind;
+        itemId?: string;
+    }): Promise<OrgOfferedComponentView[]>;
+    /**
+     * The org's copies of platform skills or agent templates linked without a pin (ruling B2), by
+     * platform id: they resolve to it, so agents that select them use it (none for connector
+     * templates and themes).
+     */
+    private linkedCopies;
+    /**
+     * The orgs' own skills (org scope) and agent templates, not linked to a platform component
+     * (ruling P2-11): listed read-only, on in their org only. Connector templates have none; an
+     * org's own theme is a platform_themes row with its org as owner, listed with the platform ones.
+     */
+    private orgOwned;
+    /** The preview of a scope change, a disable or a return to following the plugin (nothing written). */
+    preview(kind: ComponentKind, id: string, target: ComponentTarget): Promise<ComponentScopePreview>;
+    /** Gives the component its own scope, or makes it follow its plugin again, after its preview. */
+    setScope(actor: string, kind: ComponentKind, id: string, body: ({
+        scope: PluginScope;
+        orgs?: string[];
+    } | {
+        follow: true;
+    }) & {
+        scopeHash: string;
+    }, opts?: AuditOpts): Promise<ComponentView>;
+    /**
+     * Disables the component on the whole deployment (after its preview, `scopeHash` required) or
+     * enables it again (no hash; refused while an org it would be offered to has a skill of its name).
+     */
+    setDisabled(actor: string, kind: ComponentKind, id: string, body: {
+        disabled: boolean;
+        scopeHash?: string;
+    }, opts?: AuditOpts): Promise<ComponentView>;
+    /** Shows or hides the component to orgs outside its `named` list (never makes it usable). */
+    setShown(actor: string, kind: ComponentKind, id: string, shown: boolean, opts?: AuditOpts): Promise<ComponentView>;
+    /**
+     * The org admin's switch of one component (`PUT orgs/:orgId/components/:kind/:id/switch`): only
+     * this component (rule 5). A component not offered to the org -> 404. On: refused while the
+     * component or its plugin is disabled (`plugin.disabled`) or an own skill of the org has its name
+     * (`plugin.skill_conflict`, rule 10; a theme: `theme.id_taken`). Off: the platform default theme
+     * while it is on -> `theme.platform_default`; of a builtin plugin -> `plugin.scope_locked`; while it
+     * is on, without `confirm` the preview (agents that use it) and its hash are returned, with the
+     * current hash the switch is written (a changed preview -> `plugin.switch_stale`).
+     */
+    setSwitch(orgId: string, actor: string, kind: ComponentKind, id: string, body: {
+        enabled: boolean;
+        confirm?: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<ComponentSwitchResult>;
+    /**
+     * What {@link setSwitch} would do to the org's switch, read-only (the Platform tool's preview):
+     * the component as the org sees it, whether it is `stopped` on the deployment, and for one that
+     * is on and can be switched off the preview of the agents that lose it with the `confirm` hash
+     * the switch-off needs (both null otherwise). Unknown or not offered -> 404 `component.not_found`.
+     */
+    switchPreview(orgId: string, kind: ComponentKind, id: string): Promise<{
+        component: OrgComponentView;
+        stopped: boolean;
+        preview: {
+            agents: {
+                id: string;
+                name: string;
+                refs: string[];
+            }[];
+            connectorsKept: number;
+        } | null;
+        confirm: string | null;
+    }>;
+    /**
+     * `x.hashId`: the id the preview was asked for (an org row's id before its promotion);
+     * `x.promote`: the org row to promote first, in this transaction. Returns the id written.
+     */
+    private writeScope;
+    private writeDisabled;
+    /** `promote`: the org row to promote first, in this transaction. Returns the id written. */
+    private writeShown;
+    /**
+     * A live component's versions, newest first. A connector template keeps no history: its one entry
+     * is the current version. Missing (or removed) -> 404 `component.not_found`.
+     */
+    versions(kind: ComponentKind, id: string): Promise<ComponentVersionView[]>;
+    /** An org-owned skill's or agent template's versions (ruling P2-11); else 404. */
+    private orgOwnedVersions;
+    private view;
+    /** The live component (row locked with `forUpdate`); missing -> 404, of a builtin plugin -> 409. */
+    private component;
+    /**
+     * The scope that offers the component now: its own (`listed`: its own list), or for `follow` its
+     * plugin's (`all` for a builtin or deleted plugin: the widest, so nothing counts as widening).
+     */
+    private effectiveScope;
+    /** The component's own `named` list, sorted. */
+    private listed;
+    /**
+     * The state after the change: `orgs` only with `named`, each a live org. `listed`: the list now
+     * (an org row not promoted yet: `[owner]`), else read.
+     */
+    private targetOf;
+    /**
+     * 409 `theme.platform_default` when theme `c` is the platform default and `t` would leave it
+     * narrower than `all` or gone (themes spec §7), in the caller's transaction, before any write.
+     */
+    private assertKeepsPlatformDefault;
+    /**
+     * Theme `c`'s availability under `t`: gone when disabled (or its plugin is disabled or deleted
+     * while it follows it), else `all` when its effective scope (its own, or its plugin's; builtin:
+     * `all`) is `all`, else narrower.
+     */
+    private themeAfter;
+    /** Live orgs (`only`: that one), sorted by id. */
+    private liveOrgs;
+    private on;
+    /**
+     * The preview of moving `c` to `target` (read through the current context). `x.hashId`: the id
+     * the hash names (the one the preview was asked for); `x.listed`: the list now of an org row not
+     * promoted yet (`[owner]`).
+     */
+    private compute;
+}
+export {};