@capybara-hq/kernel 0.1.0-rc.13 → 0.1.0-rc.15

package/dist/extensions/blobs.js

@@ -9,10 +9,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { createHash } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
+import { ClientBuilds } from "../client/client-builds.service.js";
+import { CLIENT_DIR } from "../client/client-files.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
+import { unpackPackageTgz } from "../packages/tgz.js";
 import { StorageService } from "../storage/storage.service.js";
 /**
  * Content-addressed extension package store (C13): one copy per sha256 of the whole tgz.
@@ -21,6 +24,13 @@ import { StorageService } from "../storage/storage.service.js";
  *   extension, F-Q): PG `extension_blobs` (`blob_store = pg`, also limited by `packages.maxBytes`).
  * Each package's location is recorded in `extension_packages.blob_store`; reads follow the record and
  * check the sha256.
+ *
+ * A package with an `extension.client` section also stores its client build (`ClientBuilds`,
+ * client extensions spec §9.1): the client files are read again from the bytes being stored,
+ * checked against the section and written to object storage before the package row's transaction,
+ * and the build row is inserted in that transaction, all under the build's lock. Without object
+ * storage (`ClientBuilds`' own, which the CLI points at its store) such a package is refused
+ * (`storage.unavailable`), so a stored build always has its files.
  */
 /** 取到的包与 sha256 不符（存储里的字节被篡改或损坏）。 */
 export class ExtensionBlobIntegrityError extends Error {
@@ -39,6 +49,7 @@ let ExtensionBlobs = class ExtensionBlobs {
     txHost;
     storage;
     config;
+    clientBuilds;
     /**
      * CLI only: packages the CLI process imported itself and reads back before the store, since such
      * a package may be recorded in an object store the CLI cannot read. Each entry's sha256 was
@@ -48,11 +59,12 @@ let ExtensionBlobs = class ExtensionBlobs {
     local = new Map();
     constructor(db, txHost, 
     /** Without an object-store extension (the CLI) packages go to PG. */
-    storage, config) {
+    storage, config, clientBuilds) {
         this.db = db;
         this.txHost = txHost;
         this.storage = storage;
         this.config = config;
+        this.clientBuilds = clientBuilds;
     }
     /** `packages.maxBytes` (read at every call). */
     maxBytes() {
@@ -85,16 +97,38 @@ let ExtensionBlobs = class ExtensionBlobs {
         if (createHash("sha256").update(bytes).digest("hex") !== p.sha256) {
             throw new ExtensionBlobIntegrityError(p.sha256);
         }
+        const client = p.section.client;
+        if (client === undefined) {
+            await this.store(p, bytes, src, undefined);
+            return;
+        }
+        // client code is delivered from object storage: refused before anything is written without it
+        this.clientBuilds.assertAvailable();
+        const files = await this.clientFiles(bytes);
+        // one store or delete of this package's client build at a time (ClientBuilds header)
+        await this.clientBuilds.locked(p.sha256, () => this.store(p, bytes, src, { section: client, files }));
+    }
+    /** {@link put} after its checks; `client` for a package with client code (under its lock). */
+    async store(p, bytes, src, client) {
+        const plugin = p.section.manifest.name;
         const existing = await this.db
             .selectFrom("extension_packages")
             .select("blob_store")
             .where("sha256", "=", p.sha256)
             .executeTakeFirst();
         if (existing) {
-            // 记录已在：字节若丢了（对象被删、库被清）就按原存放位置补上
+            // The row is there: bytes that went missing (an object deleted, a database cleared) are
+            // restored where the row says, and so are the client build's files and row
             await this.repair(p.sha256, existing.blob_store, bytes);
+            if (client !== undefined) {
+                await this.clientBuilds.extract(p.sha256, plugin, client.files, client.section);
+            }
             return;
         }
+        // checked and written before the transaction (no object storage call inside one)
+        const build = client !== undefined
+            ? await this.clientBuilds.writeFiles(p.sha256, plugin, client.files, client.section)
+            : undefined;
         const store = src.store ?? (this.storage.available ? "object" : "pg");
         if (store === "object") {
             if (!this.storage.available)
@@ -106,9 +140,14 @@ let ExtensionBlobs = class ExtensionBlobs {
         }
         // the row stores the plugin's extension section as reviewed (without the name / version copy)
         const { name: _name, version: _version, ...section } = p.section;
-        await this.record(p, section, bytes, src, store);
+        await this.record(p, section, bytes, src, store, build);
+    }
+    /** The files under `dist/client/` of a package's bytes (sha256 already checked by the caller). */
+    async clientFiles(bytes) {
+        const files = await unpackPackageTgz(bytes, { maxBytes: this.maxBytes() });
+        return new Map(files.filter((f) => f.path.startsWith(CLIENT_DIR)).map((f) => [f.path, f.data]));
     }
-    async record(p, section, bytes, src, store) {
+    async record(p, section, bytes, src, store, build) {
         const m = p.section.manifest;
         const inserted = await this.db
             .insertInto("extension_packages")
@@ -135,6 +174,9 @@ let ExtensionBlobs = class ExtensionBlobs {
                 .onConflict((oc) => oc.column("sha256").doNothing())
                 .execute();
         }
+        // the build row commits with the package row it references (or after another replica's)
+        if (build !== undefined)
+            await this.clientBuilds.insert(build);
     }
     /** 已有记录的包：按记录的存放位置检查字节在不在，不在就写回（调用方已校验 sha256）。 */
     async repair(sha256, store, bytes) {
@@ -205,7 +247,8 @@ ExtensionBlobs = __decorate([
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
     __param(2, Inject(StorageService)),
-    __param(3, Inject(KernelConfigService))
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(ClientBuilds))
 ], ExtensionBlobs);
 export { ExtensionBlobs };
 async function readCapped(body, max) {

package/dist/extensions/guide-places.d.ts

@@ -0,0 +1,66 @@
+import { type PluginSetupGuide, type SetupGuideAudience, type SetupGuidePlace } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../infra/database/kernel-db.js";
+import type { OrgAction } from "../orgs/roles.js";
+/** Why a known variable has no value: what the web and the `Platform` tool tell the reader. */
+export type UnresolvedReason = 
+/** The target is not saved yet (the webhook URL, a connection name nobody typed). */
+"not_saved"
+/** `http.publicUrl` is not set (the URLs built from it). */
+ | "public_url"
+/** `channels.webhookBaseUrl` is not set or unusable. */
+ | "webhook_base"
+/** No connector is made from the template yet. */
+ | "no_connector"
+/** Rendered for the platform (the super admin's preview), not for an org. */
+ | "no_org";
+/** The org action each audience of a place needs besides `catalog.read` (spec §9.1). */
+export declare const PLACE_ACTIONS: Readonly<Record<SetupGuidePlace, Readonly<Partial<Record<SetupGuideAudience, OrgAction>>>>>;
+/** The object a guide is rendered for. */
+export interface GuideTarget {
+    kind: "channel-connection" | "connector";
+    id: string;
+}
+/** The target parameters of the guide route, per place. */
+export interface GuideTargetQuery {
+    connectionId?: string | undefined;
+    name?: string | undefined;
+    connectorId?: string | undefined;
+}
+/** What a place resolves for one rendering (the mode is the caller's: it picks it from these). */
+export interface PlaceResolution {
+    /** Every variable of the place except `mode`; null = known without a value. */
+    values: Record<string, string | null>;
+    /** The reason of each variable that is null in `values`. */
+    reasons: Record<string, UnresolvedReason>;
+    target: GuideTarget | null;
+    /** The target's stored mode (a channel connection's `inbound_mode`), null without one. */
+    storedMode: string | null;
+}
+/** Where the values come from. */
+export interface PlaceContext {
+    db: KernelDb;
+    config: Pick<KernelConfig, "http" | "channels"> & {
+        tools: Pick<KernelConfig["tools"], "oauthAllowInsecureLoopback">;
+    };
+    item: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    guide: PluginSetupGuide;
+    locale: "en" | "zh";
+    /** The org rendered for; null for the platform preview (no org, no target). */
+    org: {
+        orgId: string;
+        name: string;
+    } | null;
+    query: GuideTargetQuery;
+}
+/**
+ * The variable values of a place for one rendering (spec §6.3): the common ones, then the place's
+ * own from its target. Throws 400 `validation_failed` for another place's target parameter and 404
+ * (`channel.not_found`, `connector.not_found`) for a target that is not a live object of the org on
+ * the guide's plugin.
+ */
+export declare function resolvePlace(ctx: PlaceContext): Promise<PlaceResolution>;

package/dist/extensions/guide-places.js

@@ -0,0 +1,152 @@
+// The kernel side of the setup guide places (spec 2026-11-09-setup-guides-v2-design.md §6.3, §9):
+// the SDK registry (`SETUP_GUIDE_PLACE_INFO`) says which modes, audiences and variables a place
+// has; this module adds, per place, the org action each audience needs, the target lookup (a live
+// object of the org on the guide's plugin, else 404) and the variable values with the reason a
+// known variable has no value. No value ever comes from a target's config, a secret, a token or a
+// client id: only names, ids, versions and the two URL settings.
+import { SETUP_GUIDE_PLACE_INFO, } from "@capybara-hq/plugin-sdk";
+import { webhookBase, webhookUrlOf } from "../channels/webhook-url.js";
+import { ApiError } from "../errors.js";
+import { OAUTH_CALLBACK_PATH } from "../tools/oauth/flow-paths.js";
+/** The org action each audience of a place needs besides `catalog.read` (spec §9.1). */
+export const PLACE_ACTIONS = {
+    "channel-connection": { admin: "channels.manage" },
+    "connector-template": { admin: "connectors.manage", member: "connectors.use" },
+};
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const invalidQuery = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
+/** The target parameters each place takes; another place's parameter is 400. */
+const TARGET_PARAMS = {
+    "channel-connection": ["connectionId", "name"],
+    "connector-template": ["connectorId"],
+};
+/**
+ * The variable values of a place for one rendering (spec §6.3): the common ones, then the place's
+ * own from its target. Throws 400 `validation_failed` for another place's target parameter and 404
+ * (`channel.not_found`, `connector.not_found`) for a target that is not a live object of the org on
+ * the guide's plugin.
+ */
+export async function resolvePlace(ctx) {
+    const place = ctx.guide.place;
+    for (const key of Object.keys(ctx.query)) {
+        if (ctx.query[key] !== undefined && !TARGET_PARAMS[place].includes(key)) {
+            throw invalidQuery(key, `${key} is not a target of a ${place} guide`);
+        }
+    }
+    const publicUrl = ctx.config.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    const values = {
+        publicUrl,
+        orgName: ctx.org?.name ?? null,
+        pluginName: ctx.item.name,
+        pluginVersion: ctx.item.version,
+    };
+    const reasons = {};
+    const signIn = publicUrl === null
+        ? null
+        : `${publicUrl}/api/v1/auth/sso/${encodeURIComponent(ctx.item.name)}/callback`;
+    let target = null;
+    let storedMode = null;
+    if (place === "channel-connection") {
+        const connection = ctx.query.connectionId === undefined
+            ? undefined
+            : await liveConnection(ctx, ctx.query.connectionId);
+        const base = webhookBase(ctx.config);
+        values.webhookUrl =
+            connection !== undefined && base !== undefined ? webhookUrlOf(base, connection.id) : null;
+        reasons.webhookUrl = connection === undefined ? "not_saved" : "webhook_base";
+        values.signInCallbackUrl = signIn;
+        const typed = ctx.query.name?.trim();
+        values.connectionName =
+            connection?.name ?? (typed === undefined || typed === "" ? null : typed);
+        reasons.connectionName = "not_saved";
+        if (connection !== undefined) {
+            target = { kind: "channel-connection", id: connection.id };
+            storedMode = connection.inbound_mode;
+        }
+    }
+    else {
+        const connector = ctx.query.connectorId === undefined
+            ? undefined
+            : await liveConnector(ctx, ctx.query.connectorId);
+        values.oauthCallbackUrl = publicUrl === null ? null : `${publicUrl}${OAUTH_CALLBACK_PATH}`;
+        values.signInCallbackUrl = signIn;
+        values.templateId = ctx.guide.template ?? null;
+        values.templateName = await templateName(ctx);
+        values.connectorName = connector?.name ?? null;
+        reasons.connectorName = "no_connector";
+        if (connector !== undefined)
+            target = { kind: "connector", id: connector.id };
+    }
+    reasons.publicUrl = "public_url";
+    reasons.signInCallbackUrl = "public_url";
+    reasons.oauthCallbackUrl = "public_url";
+    reasons.orgName = "no_org";
+    // keep only the reasons of variables that are the place's and have no value
+    const known = SETUP_GUIDE_PLACE_INFO[place].variables;
+    for (const name of Object.keys(reasons)) {
+        if (!Object.hasOwn(known, name) || values[name] !== null)
+            delete reasons[name];
+    }
+    return { values, reasons, target, storedMode };
+}
+/** A live connection of the org on the guide's plugin; otherwise `channel.not_found`. */
+async function liveConnection(ctx, id) {
+    const notFound = () => new ApiError("channel.not_found", "Channel connection not found");
+    if (ctx.org === null || !UUID_RE.test(id))
+        throw notFound();
+    const c = await ctx.db
+        .selectFrom("channel_connections")
+        .select(["id", "name", "inbound_mode"])
+        .where("id", "=", id)
+        .where("org_id", "=", ctx.org.orgId)
+        .where("plugin", "=", ctx.item.name)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    if (!c)
+        throw notFound();
+    return c;
+}
+/**
+ * A live connector of the org made from the guide's template (`connectors.platform_template_id` ->
+ * the platform component of the item's template, org-owned plugins included); otherwise
+ * `connector.not_found`, also for a custom connector or one made from another template.
+ */
+async function liveConnector(ctx, id) {
+    const notFound = () => new ApiError("connector.not_found", "Connector not found");
+    const template = ctx.guide.template;
+    if (ctx.org === null || template === undefined || !UUID_RE.test(id))
+        throw notFound();
+    const c = await ctx.db
+        .selectFrom("connectors as c")
+        .innerJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+        .select(["c.id", "c.name"])
+        .where("c.id", "=", id)
+        .where("c.org_id", "=", ctx.org.orgId)
+        .where("c.deleted_at", "is", null)
+        .where("t.catalog_item_id", "=", ctx.item.id)
+        .where("t.template_id", "=", template)
+        .executeTakeFirst();
+    if (!c)
+        throw notFound();
+    return c;
+}
+/**
+ * The template's display name in the document's language, from the platform component made from
+ * it at import (`platform_connector_templates.file`); the template id when there is none.
+ */
+async function templateName(ctx) {
+    const id = ctx.guide.template;
+    if (id === undefined)
+        return null;
+    const row = await ctx.db
+        .selectFrom("platform_connector_templates")
+        .select("file")
+        .where("catalog_item_id", "=", ctx.item.id)
+        .where("template_id", "=", id)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    const name = row?.file
+        ?.displayName;
+    const localized = ctx.locale === "zh" ? name?.zh : name?.en;
+    return typeof localized === "string" && localized !== "" ? localized : id;
+}

package/dist/extensions/host.d.ts

@@ -26,7 +26,8 @@ import { type ExtensionSource, ReplicaStatusStore } from "./sources.js";
 export { deploymentConfigHash };
 /**
  * One item of {@link ExtensionHost.uiContributions}: a UI contribution from the manifest whose slot
- * resolved at load (dropped ones never appear), with its registered view / action (embeds have none).
+ * resolved at load (dropped ones never appear), with its registered view / action (a view's or a
+ * component's; embeds have none).
  */
 export interface LoadedUiContribution {
     plugin: string;
@@ -412,6 +413,10 @@ export declare class ExtensionHost {
     /**
      * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
      * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     * `servingSha256` is the package this replica actually serves for the plugin (client code follows
+     * it, client extensions spec §9.3): the row's own package when loaded; for a failed / pending row
+     * the package of the instance still running here (an older one, or the row's own package when it
+     * stays loaded, e.g. beside a provider conflict), else null.
      */
     private writeStatus;
     /**

package/dist/extensions/host.js

@@ -38,7 +38,7 @@ import { ExtensionInstalls } from "./installs.js";
 import { ImportTracker, importExtensionModule, ManifestMismatchError, matchesSection, setupInstance, warnUpgrades, } from "./instance.js";
 import { parseLoadGate } from "./org-levels.js";
 import { declaredDisplayName, permissionSetOfSection, readMigrationSql } from "./package.js";
-import { blockingKeys, computePermissionSet, UI_VIEW_KEY_PREFIX, } from "./permission-set.js";
+import { blockingKeys, computePermissionSet, SETUP_CHECK_KEY_PREFIX, UI_VIEW_KEY_PREFIX, } from "./permission-set.js";
 import { ExtensionRegistry } from "./registry.js";
 import { ExtensionResolveError, electSingleProviders, PROVIDER_CONFLICT, providerConflictMessage, resolveExtensions, } from "./resolve.js";
 import { ReplicaStatusStore, } from "./sources.js";
@@ -1176,15 +1176,24 @@ let ExtensionHost = class ExtensionHost {
     /**
      * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
      * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     * `servingSha256` is the package this replica actually serves for the plugin (client code follows
+     * it, client extensions spec §9.3): the row's own package when loaded; for a failed / pending row
+     * the package of the instance still running here (an older one, or the row's own package when it
+     * stays loaded, e.g. beside a provider conflict), else null.
      */
     async writeStatus(s) {
-        if (s.servingVersion === undefined && (s.state === "failed" || s.state === "pending")) {
-            const cur = this.registry.current(s.plugin);
-            s = {
-                ...s,
-                servingVersion: cur && (cur.sha256 !== s.sha256 || cur.version !== s.version) ? cur.version : null,
-            };
-        }
+        const waiting = s.state === "failed" || s.state === "pending";
+        const cur = waiting ? this.registry.current(s.plugin) : undefined;
+        const other = cur && (cur.sha256 !== s.sha256 || cur.version !== s.version) ? cur : null;
+        s = {
+            ...s,
+            ...(waiting && s.servingVersion === undefined && { servingVersion: other?.version ?? null }),
+            servingSha256: s.servingSha256 !== undefined
+                ? s.servingSha256
+                : s.state === "loaded"
+                    ? s.sha256
+                    : (cur?.sha256 ?? null),
+        };
         if (s.source === "install") {
             if (s.state === "unloaded")
                 this.installRows.delete(s.plugin);
@@ -1291,9 +1300,9 @@ let ExtensionHost = class ExtensionHost {
                 // 权限变少、不变（版本变了）或只多出视图（ui.view:*，不卡加载）：直接加载，快照跟上当前清单。
                 // 补进视图不写审计（与 autoApprove 一样，Ruling A4），只记日志
                 const updated = await approvals.refresh(name, manifest.version, a.set);
-                const merged = decision.added.filter((k) => k.startsWith(UI_VIEW_KEY_PREFIX));
+                const merged = decision.added.filter((k) => k.startsWith(UI_VIEW_KEY_PREFIX) || k.startsWith(SETUP_CHECK_KEY_PREFIX));
                 if (updated && merged.length > 0 && blockingKeys(decision.added).length === 0) {
-                    this.log.info("plugin ui views merged into the permission snapshot", {
+                    this.log.info("plugin ui views and setup checks merged into the permission snapshot", {
                         plugin: name,
                         version: manifest.version,
                         merged,
@@ -2103,8 +2112,10 @@ let ExtensionHost = class ExtensionHost {
      */
     uiContributions() {
         return this.registry.all().flatMap((i) => i.ui.map(({ contribution: c, slot, after }) => {
-            const render = c.kind === "view" ? i.uiViews.get(c.id) : undefined;
-            const action = c.kind === "view" ? i.uiActions.get(c.id) : undefined;
+            // a view's, or a component's server view (client extensions spec §5.2); embeds have none
+            const served = c.kind === "view" || c.kind === "component";
+            const render = served ? i.uiViews.get(c.id) : undefined;
+            const action = served ? i.uiActions.get(c.id) : undefined;
             return {
                 plugin: i.name,
                 contribution: c,

package/dist/extensions/instance.d.ts

@@ -1,5 +1,5 @@
 import { type DroppedUiContribution, type ExtensionManifest, type ExtensionPointRef, type ResolvedUiContribution, type StaticExtensionManifest } from "@capybara-hq/plugin-sdk";
-import { type ExtensionPointAccess, type KernelDeps, type KernelExtensionContext, LiveConfig, type RegisteredTool, type Route } from "../ctx/create-ctx.js";
+import { type ExtensionPointAccess, type KernelDeps, type KernelExtensionContext, LiveConfig, type RegisteredSetupCheck, type RegisteredTool, type Route } from "../ctx/create-ctx.js";
 import type { UiActionHandler, UiRender } from "../ui/registry.js";
 import type { RegisteredHook } from "./hooks.js";
 import { InflightTracker } from "./inflight.js";
@@ -79,6 +79,10 @@ export declare class ExtensionInstance {
     get hooks(): readonly RegisteredHook[];
     get uiViews(): ReadonlyMap<string, UiRender>;
     get uiActions(): ReadonlyMap<string, UiActionHandler>;
+    /** Setup checks registered through `ctx.setup.check` (empty after revocation). */
+    get setupChecks(): ReadonlyMap<string, RegisteredSetupCheck>;
+    /** The instance's `ctx.signal`: aborted when it is revoked or disposed. */
+    get signal(): AbortSignal;
     /** 账上仍在的登记（撤销后为空）。 */
     registrations(): Registration[];
     get disposed(): boolean;

package/dist/extensions/instance.js

@@ -130,6 +130,14 @@ export class ExtensionInstance {
     get uiActions() {
         return this.ctx.uiActions;
     }
+    /** Setup checks registered through `ctx.setup.check` (empty after revocation). */
+    get setupChecks() {
+        return this.ctx.setupChecks;
+    }
+    /** The instance's `ctx.signal`: aborted when it is revoked or disposed. */
+    get signal() {
+        return this.ctx.signal;
+    }
     /** 账上仍在的登记（撤销后为空）。 */
     registrations() {
         return this.ctx.ledger.list();

package/dist/extensions/ledger.d.ts

@@ -1,5 +1,5 @@
 /** 插件经 ctx 做的一项登记的种类（C17）。 */
-export type RegistrationKind = "tool" | "route" | "queue" | "bus" | "lease" | "ui.view" | "ui.action" | "provide" | "hook";
+export type RegistrationKind = "tool" | "route" | "queue" | "bus" | "lease" | "ui.view" | "ui.action" | "provide" | "hook" | "setup.check";
 /** 账上的一项：撤销时调用 `dispose()`。 */
 export interface Registration {
     kind: RegistrationKind;

package/dist/extensions/package.d.ts

@@ -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;

package/dist/extensions/package.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

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) {