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

package/dist/extensions/package.d.ts

@@ -1,4 +1,4 @@
-import { type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
+import { type LocalizedName, type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
 import { ApiError } from "../errors.js";
 import { HOST_ZOD_VERSION, type PackageTgzLimits } from "../packages/tgz.js";
 import { type PermissionSet } from "./permission-set.js";
@@ -29,10 +29,11 @@ export { HOST_ZOD_VERSION };
 /** Unpack limits: `maxBytes` is `packages.maxBytes`; the rest default to {@link EXTENSION_PACKAGE_LIMITS}. */
 export type ExtensionPackageLimits = PackageTgzLimits;
 /**
- * Codes of {@link ExtensionPackageError}: an invalid package, a tgz in the pre-0.1.0 format, or a
- * plugin without an extension (nothing to install on the deployment).
+ * Codes of {@link ExtensionPackageError}: an invalid package, a tgz in the pre-0.1.0 format, a
+ * plugin without an extension (nothing to install on the deployment), or client code the
+ * extension manifest does not declare.
  */
-export type ExtensionPackageErrorCode = "extension.package_invalid" | "extension.legacy_format" | "extension.no_extension";
+export type ExtensionPackageErrorCode = "extension.package_invalid" | "extension.legacy_format" | "extension.no_extension" | "client.undeclared";
 /** The extension package is invalid; `issues` lists the problems (English, shown to the admin). */
 export declare class ExtensionPackageError extends Error {
     readonly code: ExtensionPackageErrorCode;
@@ -57,6 +58,8 @@ export interface ExtensionPackage {
     size: number;
     packageJson: Record<string, unknown>;
     section: ExtensionPackageSection;
+    /** The plugin.json `displayName`, when the plugin has one. */
+    displayName?: LocalizedName;
     files: {
         path: string;
         size: number;
@@ -105,6 +108,17 @@ export declare function readMigrationSql(root: string, section: Pick<PluginExten
     file: string;
     sql: string;
 }[]>;
+/**
+ * The plugin.json `displayName` of the plugin a config-declared extension module belongs to: the
+ * `.capybara-plugin/plugin.json` beside the nearest `package.json` above the module's directory
+ * `dir`. Nothing when there is no such file or it names another plugin than the extension `name`
+ * (a module inside some other plugin's directory); `problem` when it cannot be read or is not a
+ * valid plugin.json (the extension then has no display name of its own).
+ */
+export declare function declaredDisplayName(dir: string, name: string): Promise<{
+    displayName?: LocalizedName;
+    problem?: string;
+}>;
 /**
  * Unpacks the package into `dir` (dropping the `package/` prefix). `dir` must not exist or be empty;
  * the unpack rules and limits are the same as {@link readExtensionPackage} (paths, file types, entry

package/dist/extensions/package.js

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, posix, relative, resolve as resolvePath } from "node:path";
-import { checkEntryImports, isSafePackagePath, PLUGIN_MANIFEST_FILE, } from "@capybara-hq/plugin-sdk";
+import { dirname, join, posix, relative, resolve as resolvePath } from "node:path";
+import { checkEntryImports, isSafePackagePath, PLUGIN_MANIFEST_FILE, parsePluginManifest, } from "@capybara-hq/plugin-sdk";
 import { init as lexerInit, parse as lexerParse } from "es-module-lexer";
 import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package.js";
 import { pluginSchemaName } from "../ctx/create-ctx.js";
@@ -111,7 +111,11 @@ function checkModuleGraph(entry, byPath) {
     return issues;
 }
 /** Maps an error of `readPluginPackage` to the extension package error. */
-const fromPluginPackageError = (e) => new ExtensionPackageError(e.issues, e.code === "catalog.legacy_format" ? "extension.legacy_format" : "extension.package_invalid");
+const fromPluginPackageError = (e) => new ExtensionPackageError(e.issues, e.code === "catalog.legacy_format"
+    ? "extension.legacy_format"
+    : e.code === "client.undeclared"
+        ? "client.undeclared"
+        : "extension.package_invalid");
 /**
  * Reads and validates an extension package without running any code from it: a plugin tgz
  * (`readPluginPackage`) with an `extension` section, whose entry's module graph passes the import
@@ -159,6 +163,7 @@ export async function readExtensionPackage(bytes, opts) {
         size: plugin.size,
         packageJson: plugin.packageJson,
         section: { ...ext, name: manifest.name, version: manifest.version },
+        ...(manifest.displayName !== undefined && { displayName: manifest.displayName }),
         files: [...files].map(([path, data]) => ({ path, size: data.byteLength })),
         migrationSql,
     };
@@ -206,6 +211,54 @@ export async function readMigrationSql(root, section) {
         out.push({ file, sql: await readFile(resolvePath(dir, file), "utf8") });
     return out;
 }
+/**
+ * The plugin.json `displayName` of the plugin a config-declared extension module belongs to: the
+ * `.capybara-plugin/plugin.json` beside the nearest `package.json` above the module's directory
+ * `dir`. Nothing when there is no such file or it names another plugin than the extension `name`
+ * (a module inside some other plugin's directory); `problem` when it cannot be read or is not a
+ * valid plugin.json (the extension then has no display name of its own).
+ */
+export async function declaredDisplayName(dir, name) {
+    let root;
+    for (let d = resolvePath(dir);;) {
+        try {
+            await readFile(join(d, "package.json"));
+            root = d;
+            break;
+        }
+        catch {
+            // none here: go up
+        }
+        const up = dirname(d);
+        if (up === d)
+            return {};
+        d = up;
+    }
+    let text;
+    try {
+        text = await readFile(join(root, PLUGIN_MANIFEST_FILE), "utf8");
+    }
+    catch {
+        return {};
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (e) {
+        return { problem: `${PLUGIN_MANIFEST_FILE} is not valid JSON: ${errMsg(e)}` };
+    }
+    // another plugin's plugin.json (valid or not) says nothing about this extension
+    const named = json?.name;
+    if (typeof named === "string" && named !== name)
+        return {};
+    const m = parsePluginManifest(json);
+    if ("errors" in m)
+        return { problem: m.errors.slice(0, 3).join("; ") };
+    if (m.name !== name)
+        return {};
+    return m.displayName === undefined ? {} : { displayName: m.displayName };
+}
 /**
  * Unpacks the package into `dir` (dropping the `package/` prefix). `dir` must not exist or be empty;
  * the unpack rules and limits are the same as {@link readExtensionPackage} (paths, file types, entry

package/dist/extensions/permission-set.d.ts

@@ -42,13 +42,27 @@ export interface PermissionSet {
         }[];
         network: string[];
         /**
-         * 界面贡献（`permissions.ui`）：`views` 记入快照但不卡加载（升级时自动补进快照）；
-         * `embeds` 与其他权限一样卡加载。旧快照没有这一项（按空处理）。
+         * Client code (`permissions.client`, client extensions spec §5.4): the plugin ships a browser
+         * bundle that runs with full trust in members' browsers. Sensitive and blocking. Older snapshots
+         * lack it (read as false).
+         */
+        client: boolean;
+        /**
+         * UI contributions (`permissions.ui`): `views` are recorded in the snapshot without blocking the
+         * load (added to the snapshot automatically on upgrade); `embeds` and `components` block the
+         * load like any other permission. Older snapshots lack `ui` or `components` (read as empty).
          */
         ui: {
             views: string[];
             embeds: string[];
+            components: string[];
         };
+        /**
+         * Setup check ids (`permissions.setupChecks`, setup guides v2 §10.2): recorded and shown at
+         * review but never blocking loading, like `ui.views` (a check gets only data the extension
+         * already gets for the same target). Absent when none are declared (and in older snapshots).
+         */
+        setupChecks?: string[];
     };
     /**
      * 安装记录包迁移警告的摘要（`warningsDigest`，Ruling P4）；没有警告或不是安装记录时省略。
@@ -94,7 +108,8 @@ export declare function buildPermissionSet(input: {
 }): PermissionSet;
 /**
  * 权限集合的稳定字符串键（排序），如 `provides:channel@1`、`config.org.secret:apiKey`、`table:todos`、
- * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`。
+ * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`,
+ * `permissions.client`, `ui.component:hud`.
  * 容忍旧快照缺字段（按空处理），快照格式演进时不会抛错。
  */
 export declare function permissionKeys(set: PermissionSet): string[];
@@ -103,11 +118,26 @@ export declare function permissionKeys(set: PermissionSet): string[];
  * Lower-case letters and dots only, as catalog permission keys require (`PERMISSION_KEY_RE`).
  */
 export declare const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
+/**
+ * Permission key of client code (`permissions.client`): sensitive and blocking. The key, not the
+ * bundle's bytes, is reviewed: an upgrade that only changes the bundle adds no key.
+ */
+export declare const CLIENT_KEY = "permissions.client";
+/** Key prefix of a client component (`ui.component:<id>`): sensitive and blocking. */
+export declare const UI_COMPONENT_KEY_PREFIX = "ui.component:";
 /** 渲染 schema 视图的权限键前缀：记入快照但不卡加载（见 {@link blockingKeys}）。 */
 export declare const UI_VIEW_KEY_PREFIX = "ui.view:";
 /**
- * 新增项里需要批准（卡加载）的部分：除 `ui.view:*` 之外的全部。视图只是把插件已有的数据交给内核组件来画，
- * 不给插件新能力（spec §4.1），升级多出视图时插件照常加载、快照自动补上。
+ * Key prefix of a setup check id (`permissions.setupChecks`): recorded but never blocking
+ * ({@link blockingKeys}). Lower-case letters and dots before the colon, as catalog permission keys
+ * require (`PERMISSION_KEY_RE` of the marketplace format).
+ */
+export declare const SETUP_CHECK_KEY_PREFIX = "setup.check:";
+/**
+ * 新增项里需要批准（卡加载）的部分：除 `ui.view:*` 与 `setup.check:*` 之外的全部。视图只是把插件已有的数据交给
+ * 内核组件来画，不给插件新能力（spec §4.1）；setup checks get only data the extension already gets
+ * for the same target (setup guides v2 §10.2). An upgrade adding either loads as usual and the
+ * snapshot takes them.
  */
 export declare function blockingKeys(added: readonly string[]): string[];
 /** 两份权限集合的差异（按 {@link permissionKeys}）；`prev` 为空（无快照）时全部算新增。 */

package/dist/extensions/permission-set.js

@@ -107,14 +107,24 @@ export function buildPermissionSet(input) {
                 .map((m) => ({ purpose: m.purpose, kind: m.kind }))
                 .sort((a, b) => cmp(a.purpose, b.purpose)),
             network: sortedUnique(p.network),
-            ui: { views: sortedUnique(p.ui?.views), embeds: sortedUnique(p.ui?.embeds) },
+            client: p.client === true,
+            ui: {
+                views: sortedUnique(p.ui?.views),
+                embeds: sortedUnique(p.ui?.embeds),
+                components: sortedUnique(p.ui?.components),
+            },
+            // only when declared: sets (and snapshots) of plugins without setup checks stay as they were
+            ...(p.setupChecks && p.setupChecks.length > 0
+                ? { setupChecks: sortedUnique(p.setupChecks) }
+                : {}),
         },
         ...(input.warningsDigest ? { warningsDigest: input.warningsDigest } : {}),
     };
 }
 /**
  * 权限集合的稳定字符串键（排序），如 `provides:channel@1`、`config.org.secret:apiKey`、`table:todos`、
- * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`。
+ * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`,
+ * `permissions.client`, `ui.component:hud`.
  * 容忍旧快照缺字段（按空处理），快照格式演进时不会抛错。
  */
 export function permissionKeys(set) {
@@ -151,10 +161,16 @@ export function permissionKeys(set) {
         keys.push(`permissions.models:${m.purpose} (${m.kind})`);
     for (const d of p.network ?? [])
         keys.push(`permissions.network:${d}`);
+    if (p.client)
+        keys.push(CLIENT_KEY);
     for (const v of p.ui?.views ?? [])
         keys.push(`${UI_VIEW_KEY_PREFIX}${v}`);
     for (const e of p.ui?.embeds ?? [])
         keys.push(`ui.embed:${e}`);
+    for (const c of p.ui?.components ?? [])
+        keys.push(`${UI_COMPONENT_KEY_PREFIX}${c}`);
+    for (const c of p.setupChecks ?? [])
+        keys.push(`${SETUP_CHECK_KEY_PREFIX}${c}`);
     if (s.warningsDigest)
         keys.push(`${WARNINGS_KEY_PREFIX}${s.warningsDigest}`);
     return sortedUnique(keys);
@@ -164,14 +180,29 @@ export function permissionKeys(set) {
  * Lower-case letters and dots only, as catalog permission keys require (`PERMISSION_KEY_RE`).
  */
 export const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
+/**
+ * Permission key of client code (`permissions.client`): sensitive and blocking. The key, not the
+ * bundle's bytes, is reviewed: an upgrade that only changes the bundle adds no key.
+ */
+export const CLIENT_KEY = "permissions.client";
+/** Key prefix of a client component (`ui.component:<id>`): sensitive and blocking. */
+export const UI_COMPONENT_KEY_PREFIX = "ui.component:";
 /** 渲染 schema 视图的权限键前缀：记入快照但不卡加载（见 {@link blockingKeys}）。 */
 export const UI_VIEW_KEY_PREFIX = "ui.view:";
 /**
- * 新增项里需要批准（卡加载）的部分：除 `ui.view:*` 之外的全部。视图只是把插件已有的数据交给内核组件来画，
- * 不给插件新能力（spec §4.1），升级多出视图时插件照常加载、快照自动补上。
+ * Key prefix of a setup check id (`permissions.setupChecks`): recorded but never blocking
+ * ({@link blockingKeys}). Lower-case letters and dots before the colon, as catalog permission keys
+ * require (`PERMISSION_KEY_RE` of the marketplace format).
+ */
+export const SETUP_CHECK_KEY_PREFIX = "setup.check:";
+/**
+ * 新增项里需要批准（卡加载）的部分：除 `ui.view:*` 与 `setup.check:*` 之外的全部。视图只是把插件已有的数据交给
+ * 内核组件来画，不给插件新能力（spec §4.1）；setup checks get only data the extension already gets
+ * for the same target (setup guides v2 §10.2). An upgrade adding either loads as usual and the
+ * snapshot takes them.
  */
 export function blockingKeys(added) {
-    return added.filter((k) => !k.startsWith(UI_VIEW_KEY_PREFIX));
+    return added.filter((k) => !k.startsWith(UI_VIEW_KEY_PREFIX) && !k.startsWith(SETUP_CHECK_KEY_PREFIX));
 }
 /** 两份权限集合的差异（按 {@link permissionKeys}）；`prev` 为空（无快照）时全部算新增。 */
 export function diffPermissions(prev, next) {

package/dist/extensions/permission-view.d.ts

@@ -1,3 +1,5 @@
+import type { LocalizedName, UiDropReason } from "@capybara-hq/plugin-sdk";
+import type { PluginScope } from "../catalog/scope.js";
 import { type PermissionSet } from "./permission-set.js";
 import type { ExtensionSource } from "./sources.js";
 /**
@@ -10,11 +12,11 @@ import type { ExtensionSource } from "./sources.js";
 export declare function reviewHash(set: PermissionSet, warnings?: readonly PackageWarning[]): string;
 /** 权限清单展示用的一组：按类别分组，`sensitive` 标出需要管理员特别留意的类别。 */
 export interface PermissionGroup {
-    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui";
+    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui" | "components" | "client";
     /**
-     * Sensitive category: secrets, public routes, tools, hooks; also the "provides" group when it holds
-     * one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group when it holds an embedded app
-     * (embed: the extension's own page in an iframe).
+     * Sensitive category: secrets, public routes, tools, hooks, client components, client code; also
+     * the "provides" group when it holds one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group
+     * (views and embeds) when it holds an embedded app (embed: the extension's own page in an iframe).
      */
     sensitive: boolean;
     items: string[];
@@ -23,10 +25,12 @@ export interface PermissionGroup {
 }
 /**
  * Sensitive reason codes (the UI translates them by code): secrets, public routes, tools, hooks,
- * embedded apps, and sensitive extension points ({@link SENSITIVE_EXTENSION_POINTS}; the code is the
- * extension point name without `@<major>`, with `-` replaced by `_`).
+ * embedded apps, client code and client components (client extensions spec §5.4: code that runs with
+ * full trust in members' browsers), and sensitive extension points
+ * ({@link SENSITIVE_EXTENSION_POINTS}; the code is the extension point name without `@<major>`, with
+ * `-` replaced by `_`).
  */
-export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "migration_warnings";
+export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "client_code" | "ui_component" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "migration_warnings";
 /** 权限清单里的一项（分组里的一项，或 `added` 里的一个权限键）。 */
 export interface PermissionItem {
     value: string;
@@ -35,10 +39,10 @@ export interface PermissionItem {
     reason?: SensitiveReason;
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@1` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
+ * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
  * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
  * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须企业管理员批准。只影响展示，不改权限快照的键。
+ * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
  */
 export declare const SENSITIVE_EXTENSION_POINTS: readonly string[];
 /**
@@ -53,18 +57,27 @@ export declare function permissionGroups(set: PermissionSet): PermissionGroup[];
 /**
  * 部署级插件状态（后台展示；F-I：副本行存原因，这里推导展示用的状态）。
  * `dependency`：必需能力没有（加载着的）提供方（F-M：排在 `failed` 之后、`pending_approval` 之前）。
+ * `conflict`: it provides a single-provider extension point another loaded extension provides (same
+ * rank as `dependency`); it loads once that one is disabled.
  */
-export type DeploymentExtensionStatus = "enabled" | "disabled" | "pending_approval" | "pending_config" | "pending_migration" | "converging" | "failed" | "dependency"
+export type DeploymentExtensionStatus = "enabled" | "disabled" | "pending_approval" | "pending_config" | "pending_migration" | "converging" | "failed" | "dependency" | "conflict"
 /** The stored package is in the pre-0.1.0 format: reinstall it from a repacked tgz. */
  | "legacy_format";
 /**
- * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * 需要超级管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
  * （`converging` 收敛中、`pending_migration` 待迁移）。
  */
 export declare function extensionNeedsAction(status: DeploymentExtensionStatus): boolean;
 /** One item of the admin extension list (`GET /api/v1/admin/extensions`). */
 export interface AdminExtensionView {
     name: string;
+    /** The plugin's display name (`ExtensionDisplayNames`); null when it has none. */
+    displayName: LocalizedName | null;
+    /**
+     * The URL of its plugin's icon on the admin catalog route (`PluginIcons`); null when the plugin's
+     * latest version has none or there is no catalog item; absent on a degraded view (the read failed).
+     */
+    icon?: string | null;
     version: string;
     source: ExtensionSource;
     /** 安装记录的包；配置声明为 null。 */
@@ -111,15 +124,95 @@ export interface AdminExtensionView {
     /** 有部署级配置字段。 */
     configurable: boolean;
     configValid: boolean;
+    /**
+     * Only when the platform config leaves required overridable fields empty (spec A §5.4a; the
+     * extension still runs): the number of orgs where it is on and that still need their own config.
+     */
+    orgsNeedingConfig?: number;
     /** 能从部署卸载（只有安装记录，必需的引导插件除外；卸载前须先停用）。 */
     removable: boolean;
     /**
      * A required bootstrap plugin (package ecosystem spec §7): enabled in every org, cannot be
-     * disabled or uninstalled; an enterprise admin may upgrade it.
+     * disabled or uninstalled; a super admin may upgrade it.
      */
     required: boolean;
+    /** The scope of the catalog plugin the extension ships in (builtin: `all`); null without one. */
+    scope: PluginScope | null;
+    /** Orgs where the extension is enabled (a required plugin: every org). */
+    enabledOrgs: number;
+    /** Shipped with the deployment (a builtin plugin or a required bootstrap plugin). */
+    builtin: boolean;
     /** Where the install record came from (`bootstrap` for the bootstrap step); null for config-declared. */
     installSource: "npm" | "file" | "catalog" | "bootstrap" | null;
+    /**
+     * UI contributions this replica's loaded instance left out at load (UI slots spec §3.2): a slot the
+     * catalog does not know, or not at that version. `[]` when the extension is not loaded here.
+     */
+    uiDropped: {
+        id: string;
+        ref: string;
+        reason: UiDropReason;
+    }[];
+    /**
+     * The client build that runs (client extensions spec §9.1, §9.3, §10.4): the one a live replica
+     * serves (the install's own package when it runs, else the older one still served beside an
+     * upgrade awaiting approval or failed), or the install record package's build when no replica
+     * serves one; its id (the package sha256), every file with its size, and the client API
+     * version; null when that package has no client code (or the view is degraded).
+     */
+    client: {
+        build: string;
+        files: {
+            path: string;
+            bytes: number;
+        }[];
+        apiVersion: number;
+    } | null;
+    /**
+     * Crash and load reports of that build, newest first, at most 50: `orgId` is null for admin
+     * pages and may name an org deleted since (rows stay until the 30-day prune). Empty without a
+     * client build.
+     */
+    clientReports: {
+        orgId: string | null;
+        contribution: string | null;
+        kind: string;
+        count: number;
+        firstAt: string;
+        lastAt: string;
+        lastMessage: string;
+    }[];
+    /**
+     * Only with status `conflict`: the single-provider extension point and the other extensions that
+     * provide it (they keep this one from loading; disabling them loads it, no restart).
+     */
+    conflict?: {
+        extensionPoint: string;
+        providers: {
+            name: string;
+            displayName: LocalizedName | null;
+        }[];
+        /**
+         * The provider the single-provider election picked (the first of `providers`) is not loaded
+         * (failed, pending), so the point has no running provider: an admin warning.
+         */
+        unprovided?: true;
+    };
+    /**
+     * Only on a disabled install record: another enabled extension provides a single-provider
+     * extension point this one provides, so enabling it is refused (409
+     * `extension.single_provider_enabled`) until that one is disabled; `required`: that one is a
+     * required bootstrap plugin, which cannot be disabled, so this one cannot replace it (409
+     * `extension.single_provider_required`).
+     */
+    enableBlocked?: {
+        extensionPoint: string;
+        enabled: {
+            name: string;
+            displayName: LocalizedName | null;
+        };
+        required?: true;
+    };
     /**
      * Why the install record's package cannot be read (bytes missing or corrupt, over the current
      * size limit; status failed), or the legacy-format message (status `legacy_format`); permissions
@@ -149,7 +242,7 @@ export interface StatusInput {
 }
 /**
  * 由期望状态、快照、配置校验、`migrated_sha` 与各副本状态推出部署级状态，优先级：
- * `failed` > `dependency` > `pending_approval` > `pending_config` > `pending_migration` > `converging` > `enabled` / `disabled`。
+ * `failed` > `dependency` > `conflict` > `pending_approval` > `pending_config` > `pending_migration` > `converging` > `enabled` / `disabled`。
  * - 安装记录只看目标包（`desired.sha256`）的副本行：旧包的失败不算；
  * - 停用的安装记录不看迁移；仍有副本加载着时为 `converging`；
  * - 配置声明始终期望启用。

package/dist/extensions/permission-view.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { pluginSchemaName } from "../ctx/create-ctx.js";
 import { isDestructiveSql, splitSqlStatements } from "../db/sql-statements.js";
-import { permissionKeys, WARNINGS_KEY_PREFIX } from "./permission-set.js";
+import { CLIENT_KEY, permissionKeys, UI_COMPONENT_KEY_PREFIX, WARNINGS_KEY_PREFIX, } from "./permission-set.js";
 /**
  * Review digest: the first 16 hex digits of `sha256(permissionKeys(set).join("\n"))`; with migration
  * warnings their digest (kind, file, line and statement) is folded in, without warnings it equals the
@@ -18,35 +18,42 @@ export function reviewHash(set, warnings = []) {
     return h.digest("hex").slice(0, 16);
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@1` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
+ * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
  * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
  * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须企业管理员批准。只影响展示，不改权限快照的键。
+ * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
  */
 export const SENSITIVE_EXTENSION_POINTS = [
     "channel@1",
     "directory@1",
     "identity-source@1",
-    "sandbox@1",
+    "sandbox@2",
     "object-store@1",
 ];
+/** The one item of the "client" group (client extensions spec §5.4). */
+const CLIENT_ITEM = "client code";
 /** 总是敏感的类别。 */
 const ALWAYS_SENSITIVE = new Set([
     "secrets",
     "publicRoutes",
     "tools",
     "hooks",
+    "components",
+    "client",
 ]);
 const CATEGORY_REASON = {
     secrets: "secrets",
     publicRoutes: "public_routes",
     tools: "tools",
     hooks: "hooks",
+    components: "ui_component",
+    client: "client_code",
 };
 /**
  * Why an item in a category is sensitive (undefined when it is not; shared by the grouped list, the
- * per-item `added` and the CLI markers): secrets, public routes, tools and hooks are always
- * sensitive; {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`) in "UI".
+ * per-item `added` and the CLI markers): secrets, public routes, tools, hooks and client code are
+ * always sensitive, and so are client components (their own group, items are the component ids);
+ * {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`) in "UI".
  */
 function itemReason(category, item) {
     // storage 不算敏感：ctx.storage 的键由内核加前缀 `plugins/<插件>/<orgId>/`，插件只能读写自己的前缀
@@ -55,8 +62,11 @@ function itemReason(category, item) {
             ? item.split("@")[0].replaceAll("-", "_")
             : undefined;
     }
-    if (category === "ui")
-        return item.startsWith("embed:") ? "ui_embed" : undefined;
+    if (category === "ui") {
+        if (item.startsWith("embed:"))
+            return "ui_embed";
+        return undefined;
+    }
     return ALWAYS_SENSITIVE.has(category) ? CATEGORY_REASON[category] : undefined;
 }
 const itemOf = (category, value) => {
@@ -68,6 +78,8 @@ function keyItem(key) {
     const after = (prefix) => (key.startsWith(prefix) ? key.slice(prefix.length) : null);
     if (key === "permissions.secrets")
         return { category: "secrets", item: "secret store" };
+    if (key === CLIENT_KEY)
+        return { category: "client", item: CLIENT_ITEM };
     if (/^config\.(deployment|org)\.secret:/.test(key))
         return { category: "secrets", item: key.slice(key.indexOf(":") + 1) };
     const table = [
@@ -77,6 +89,7 @@ function keyItem(key) {
         ["permissions.hooks:", "hooks", ""],
         ["permissions.hooks.policy:", "hooks", "policy:"],
         ["ui.embed:", "ui", "embed:"],
+        [UI_COMPONENT_KEY_PREFIX, "components", ""],
         ["ui.view:", "ui", "view:"],
     ];
     for (const [prefix, category, itemPrefix] of table) {
@@ -113,11 +126,12 @@ export function permissionKeyItems(keys) {
 /** 把权限集合整理成分组清单（固定顺序，空组省略）。纯函数。 */
 export function permissionGroups(set) {
     const p = set.permissions;
-    // 旧快照没有 ui（按空处理）
-    const ui = p.ui ?? { views: [], embeds: [] };
-    const secretFields = [...set.config.deployment, ...set.config.org]
-        .filter((f) => f.secret)
-        .map((f) => f.path || "<root>");
+    // older snapshots lack `ui`, `ui.components` and `client` (read as empty / false)
+    const ui = p.ui ?? { views: [], embeds: [], components: [] };
+    const components = ui.components ?? [];
+    // Level-prefixed like the config group: a field at both levels (an overridable secret such as
+    // `appSecret`) is two items, not one name listed twice.
+    const secretFields = ["deployment", "org"].flatMap((level) => set.config[level].filter((f) => f.secret).map((f) => `${level}:${f.path || "<root>"}`));
     const configFields = ["deployment", "org"].flatMap((level) => set.config[level].map((f) => `${level}:${f.path || "<root>"}`));
     const secretItems = [...(p.secrets ? ["secret store"] : []), ...secretFields];
     const groups = [
@@ -150,6 +164,8 @@ export function permissionGroups(set) {
             category: "ui",
             items: [...ui.views.map((v) => `view:${v}`), ...ui.embeds.map((e) => `embed:${e}`)],
         },
+        { category: "components", items: components },
+        { category: "client", items: p.client === true ? [CLIENT_ITEM] : [] },
     ];
     return groups
         .filter((g) => g.items.length > 0)
@@ -159,7 +175,7 @@ export function permissionGroups(set) {
     });
 }
 /**
- * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * 需要超级管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
  * （`converging` 收敛中、`pending_migration` 待迁移）。
  */
 export function extensionNeedsAction(status) {
@@ -167,7 +183,7 @@ export function extensionNeedsAction(status) {
 }
 /**
  * 由期望状态、快照、配置校验、`migrated_sha` 与各副本状态推出部署级状态，优先级：
- * `failed` > `dependency` > `pending_approval` > `pending_config` > `pending_migration` > `converging` > `enabled` / `disabled`。
+ * `failed` > `dependency` > `conflict` > `pending_approval` > `pending_config` > `pending_migration` > `converging` > `enabled` / `disabled`。
  * - 安装记录只看目标包（`desired.sha256`）的副本行：旧包的失败不算；
  * - 停用的安装记录不看迁移；仍有副本加载着时为 `converging`；
  * - 配置声明始终期望启用。
@@ -179,6 +195,8 @@ export function deriveExtensionStatus(i) {
         return "failed";
     if (rows.some((r) => r.reason === "dependency" && (r.state === "pending" || r.state === "unloaded")))
         return "dependency";
+    if (rows.some((r) => r.reason === "conflict" && r.state === "pending"))
+        return "conflict";
     if (i.pendingApproval)
         return "pending_approval";
     if (!i.configValid)