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

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

@@ -12,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" | "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 code; 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) or a client component.
      */
     sensitive: boolean;
     items: string[];
@@ -25,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;
@@ -151,6 +153,35 @@ export interface AdminExtensionView {
         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).

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
@@ -30,23 +30,28 @@ export const SENSITIVE_EXTENSION_POINTS = [
     "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",
+    "client",
 ]);
 const CATEGORY_REASON = {
     secrets: "secrets",
     publicRoutes: "public_routes",
     tools: "tools",
     hooks: "hooks",
+    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; {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`)
+ * and client components (`component:<id>`) in "UI".
  */
 function itemReason(category, item) {
     // storage 不算敏感：ctx.storage 的键由内核加前缀 `plugins/<插件>/<orgId>/`，插件只能读写自己的前缀
@@ -55,8 +60,13 @@ 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";
+        if (item.startsWith("component:"))
+            return "ui_component";
+        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, "ui", "component:"],
         ["ui.view:", "ui", "view:"],
     ];
     for (const [prefix, category, itemPrefix] of table) {
@@ -113,8 +126,9 @@ export function permissionKeyItems(keys) {
 /** 把权限集合整理成分组清单（固定顺序，空组省略）。纯函数。 */
 export function permissionGroups(set) {
     const p = set.permissions;
-    // 旧快照没有 ui（按空处理）
-    const ui = p.ui ?? { views: [], embeds: [] };
+    // older snapshots lack `ui`, `ui.components` and `client` (read as empty / false)
+    const ui = p.ui ?? { views: [], embeds: [], components: [] };
+    const components = ui.components ?? [];
     const secretFields = [...set.config.deployment, ...set.config.org]
         .filter((f) => f.secret)
         .map((f) => f.path || "<root>");
@@ -148,8 +162,13 @@ export function permissionGroups(set) {
         { category: "network", items: p.network },
         {
             category: "ui",
-            items: [...ui.views.map((v) => `view:${v}`), ...ui.embeds.map((e) => `embed:${e}`)],
+            items: [
+                ...ui.views.map((v) => `view:${v}`),
+                ...ui.embeds.map((e) => `embed:${e}`),
+                ...components.map((c) => `component:${c}`),
+            ],
         },
+        { category: "client", items: p.client === true ? [CLIENT_ITEM] : [] },
     ];
     return groups
         .filter((g) => g.items.length > 0)

package/dist/extensions/plugin-guides.d.ts

@@ -1,92 +1,225 @@
-import { type PluginSetupGuide, type SetupGuideLanguage, type SetupGuidePlace, type SetupGuideText } from "@capybara-hq/plugin-sdk";
+import { type PluginSetupGuide, type SetupGuideAudience, type SetupGuideBlock, type SetupGuidePlace } from "@capybara-hq/plugin-sdk";
 import type { GuideAckJson } from "../db/kernel-schema.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
 import { type OrgRole } from "../orgs/roles.js";
-/** The setup guide a channel connection was set up with (`channel_connections.guide_ack`). */
+import { type GuideTarget, type GuideTargetQuery, type UnresolvedReason } from "./guide-places.js";
+export { PLACE_ACTIONS, type UnresolvedReason } from "./guide-places.js";
+/**
+ * The setup guide a target was set up with (`channel_connections.guide_ack`,
+ * `connectors.guide_ack`): the guide, the plugin version, the drift hash of the admin audience and
+ * the mode (null for a place without modes).
+ */
 export type GuideAck = GuideAckJson;
-/** Where a channel page finds its plugin's guide (`GET /orgs/:orgId/catalog/:itemId/guides/:guideId`). */
+/** Where a page finds its plugin's guide (`GET /orgs/:orgId/catalog/:itemId/guides/:guideId`). */
 export interface SetupGuideRef {
     itemId: string;
     guideId: string;
     /** The item's latest version (the guide's). */
     version: string;
 }
-/** The guide fields of a channel connection page. */
+/** The guide fields of a channel connection or connector page. */
 export interface ConnectionGuideState {
-    /** The plugin's channel-connection guide the org may see, null without one. */
+    /**
+     * The plugin's channel-connection guide (or the connector's template guide) the org may see,
+     * null without one.
+     */
     setupGuide: SetupGuideRef | null;
     /**
-     * The plugin changed the guide's templates since the connection was set up (its ack): the
-     * version acked and the current one; null otherwise (or without an ack).
+     * The plugin changed the guide's code blocks or checks for the ack's mode since the connection
+     * was set up (its ack): the version acked and the current one; null otherwise (or without an
+     * ack).
      */
     guideDrift: {
         from: string;
         to: string;
     } | null;
 }
-/** A guide rendered for an org (spec 2026-11-08-plugin-setup-guides-design.md §4). */
+/** Where a connector template's page finds its guide (`guide` of the template entries). */
+export interface TemplateGuideRef {
+    itemId: string;
+    guideId: string;
+}
+/**
+ * A template whose guide an update changes (the platform update preview, spec §11): the admin
+ * hash differs between the platform's current version and the target. `orgs` counts the orgs with
+ * a connector set up with that guide (an ack of it) whose ack the target leaves behind: org admins
+ * asked to update their app. Counts only, never org names.
+ */
+export interface TemplateGuideChange {
+    templateId: string;
+    guideId: string;
+    /** The platform's current version (null: never synced). */
+    from: string | null;
+    to: string;
+    orgs: number;
+}
+/** A guide rendered for an org or the platform (spec 2026-11-09-setup-guides-v2-design.md §7.2). */
 export interface RenderedSetupGuide {
     itemId: string;
     plugin: string;
     version: string;
     id: string;
     place: SetupGuidePlace;
-    title: SetupGuideText;
-    /** The modes the guide's steps and files use; empty = no mode switch. */
+    /** The connector template a `connector-template` guide is for; null for other places. */
+    template: string | null;
+    /** The document rendered (zh falls back to en). */
+    locale: "en" | "zh";
+    title: string;
+    /** The modes the document's sections use; empty = no mode switch. */
     modes: string[];
-    /** The mode rendered (null for a guide without modes and no connection). */
+    /** The mode rendered; null for a place without modes. */
     mode: string | null;
-    steps: SetupGuideText[];
-    files: {
-        title: SetupGuideText;
-        language: SetupGuideLanguage;
-        fileName: string;
-        content: string;
+    /** The audiences the document has sections for. */
+    audiences: SetupGuideAudience[];
+    audience: SetupGuideAudience;
+    blocks: SetupGuideBlock[];
+    /** The check rows, in document order. */
+    checks: {
+        id: string;
+        label: string;
+        source: "plugin" | "kernel";
+    }[];
+    /** Known variables the rendered text uses without a value (left as written), with why. */
+    unresolved: {
+        name: string;
+        reason: UnresolvedReason;
     }[];
-    /** Known variables without a value here (left as written, e.g. webhookUrl before saving). */
-    unresolved: string[];
-    /** The template hash of this mode (what an ack records). */
+    /** The drift hash of this mode and audience (what an ack records). */
     hash: string;
+    target: GuideTarget | null;
+}
+/** The query of the guide route. */
+export interface GuideQuery extends GuideTargetQuery {
+    mode?: string | undefined;
+    audience?: SetupGuideAudience | undefined;
+    locale?: "en" | "zh" | undefined;
 }
 type VersionFile = {
     path: string;
     size: number;
     sha256: string;
 };
+/** The live items (with their latest version) by name or id. */
+declare function latestItems(db: KernelDb, by: "name" | "id", keys: string[]): Promise<{
+    awaiting_confirmation: boolean;
+    builtin: boolean;
+    disabled: boolean;
+    files: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+    id: string;
+    latest_version: string;
+    manifest: unknown;
+    name: string;
+    owner_org_id: string | null;
+    scope: "all" | "named" | "optional";
+    shareable: boolean;
+    shown_to_others: boolean;
+}[]>;
+/** A live item with its latest version, as {@link PluginGuides} reads it. */
+export type ItemRow = Awaited<ReturnType<typeof latestItems>>[number];
 /**
- * The template hash of a guide for a mode (spec §6): sha256 over `path NUL sha256 LF` of the files
- * that apply to it, from the version's file list (no storage read). Equal hashes = the same
- * rendered files for the same variables.
+ * A connector template's guide in a version's manifest (v2 entries only), for callers that already
+ * hold the manifest (the org catalog detail).
  */
-export declare function setupGuideHash(guide: PluginSetupGuide, files: VersionFile[], mode: string | null): string;
+export declare const templateGuideOf: (manifest: unknown, templateId: string) => PluginSetupGuide | undefined;
 /**
- * Plugin setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): resolves an extension's
- * catalog item (the item of the same name, its latest version), renders a guide's steps and
- * template files with the place's fixed variables (public URLs, names, versions, the mode; never a
- * secret), and computes the template hashes channel connections record to tell when an upgrade
- * changed their setup. Org reads follow the catalog icon's visibility ({@link orgVisibleItems}).
- * Stateless: everything comes from PG (version rows, connection rows, the guide files in
- * `catalog_files`).
+ * Plugin setup guides v2 (spec `2026-11-09-setup-guides-v2-design.md`): resolves an extension's
+ * catalog item (the item of the same name, its latest version), renders a guide document for a
+ * place, audience, mode and target with the place's safe variables (`guide-places.ts`; never a
+ * secret), and computes the drift hashes targets record to tell when an upgrade changed their
+ * setup. Org reads follow the catalog icon's visibility ({@link orgVisibleItems}), the platform
+ * preview any live item. Stateless: everything comes from PG (version rows, target rows, the
+ * documents in `catalog_files`).
  */
 export declare class PluginGuides {
     private readonly db;
     private readonly config;
-    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">);
-    /** The live items (with their latest version) by name or id. */
+    private readonly log;
+    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "warn">);
     private latest;
+    /** The rows the org's catalog shows ({@link orgVisibleItems}); all of them without an org. */
+    private visibleTo;
+    /** The English documents of guides, by `<itemId>/<guideId>` (one PG read); absent when not stored. */
+    private englishSources;
+    /** The admin drift hash of a guide for a mode. */
+    private static hashOf;
     /**
-     * The ack of a plugin's current channel-connection guide for a mode (recorded on a connection
-     * when it is created or switches mode); null when the plugin has no catalog item or no guide.
-     * Kernel-internal: no org visibility (the connection belongs to the plugin either way).
+     * The ack of a plugin's current guide for a place (and template) and mode, admin audience:
+     * recorded on a target when it is created or switches mode. Null when the plugin has no catalog
+     * item, no such guide or no stored document. Without `org` kernel-internal (no org visibility:
+     * the target belongs to the plugin either way); with `org` (a person acking the guide) null
+     * also when the org's catalog does not show the item, the guide read's rule.
      */
-    currentAck(plugin: string, mode: string): Promise<GuideAck | null>;
+    currentAck(plugin: string, place: SetupGuidePlace, o: {
+        mode: string | null;
+        templateId?: string;
+        org?: {
+            orgId: string;
+            role: OrgRole;
+        };
+    }): Promise<GuideAck | null>;
     /**
-     * Whether an ack is behind the plugin's current guide (the drift rule of spec §6, as the
-     * connection pages compute it): the same guide whose templates for the ack's mode changed. False
-     * without an ack, a catalog item or the guide. Kernel-internal: no org visibility.
+     * Whether an ack is behind the plugin's current guide (spec §11): the same guide whose hash for
+     * the ack's mode changed. False without an ack, a catalog item or the guide. Kernel-internal: no
+     * org visibility.
      */
-    ackDrifted(plugin: string, ack: GuideAck | null): Promise<boolean>;
+    ackDrifted(plugin: string, place: SetupGuidePlace, ack: GuideAck | null, o?: {
+        templateId?: string;
+    }): Promise<boolean>;
+    /**
+     * The ack of a connector template's current guide (admin audience, no mode): recorded on a
+     * connector when it is created from the template. Null when the item has no guide for the
+     * template or no stored document. Without `org` kernel-internal (no org visibility: the caller is
+     * creating or reading the org's own connector of that template); with `org` (a person acking the
+     * guide) null also when the org's catalog does not show the item.
+     */
+    templateAck(itemId: string, templateId: string, org?: {
+        orgId: string;
+        role: OrgRole;
+    }): Promise<GuideAck | null>;
+    /**
+     * `<itemId>/<templateId>` -> the template's guide in the item's latest version, for the template
+     * entries of the catalog detail and the components list; templates without one are absent.
+     * Kernel-internal: callers list only items and templates the org already sees.
+     */
+    templateGuides(pairs: {
+        itemId: string;
+        templateId: string;
+    }[]): Promise<Map<string, TemplateGuideRef>>;
+    /**
+     * The guide fields of connectors (spec §9.3, §11): a connector made from a template
+     * (`itemId` / `templateId` of its platform template) whose item the org's catalog shows gets the
+     * template's guide; drift = an ack of the same guide whose admin hash changed. Custom connectors
+     * (no template) get nulls. One query each for items and documents.
+     */
+    connectorStates(connectors: {
+        id: string;
+        itemId: string | null;
+        templateId: string | null;
+        guideAck: GuideAck | null;
+    }[], org: {
+        orgId: string;
+        role: OrgRole;
+    }): Promise<Map<string, ConnectionGuideState>>;
+    /**
+     * The connector template guides an update of an item changes (the platform update preview,
+     * {@link TemplateGuideChange}): per template guide of the target whose admin hash differs from
+     * the platform's current version's (a guide new in the target counts only when connectors hold
+     * an ack of it). Documents a version does not store are skipped. Kernel-internal (the super
+     * admin's or the owner's preview).
+     */
+    templateGuideChanges(itemId: string, from: string | null, to: {
+        version: string;
+        manifest: unknown;
+        files: VersionFile[];
+    }): Promise<TemplateGuideChange[]>;
+    /** The admin drift hash of a guide in a version (no mode), or undefined when not stored. */
+    private storedHash;
     /**
      * Plugin name -> its channel-connection guide, for plugins whose item the org's catalog shows
      * (`GET channels/schema/:plugin` and the connection pages); others are absent.
@@ -96,9 +229,9 @@ export declare class PluginGuides {
         role: OrgRole;
     }): Promise<Map<string, SetupGuideRef & {
         guide: PluginSetupGuide;
-        files: VersionFile[];
+        row: ItemRow;
     }>>;
-    /** The guide fields of channel connections (one query for all; spec §6 for the drift rule). */
+    /** The guide fields of channel connections (one query each for guides and documents; spec §11). */
     connectionStates(connections: {
         id: string;
         plugin: string;
@@ -107,23 +240,43 @@ export declare class PluginGuides {
         orgId: string;
         role: OrgRole;
     }): Promise<Map<string, ConnectionGuideState>>;
+    /**
+     * The documents of a guide of an item's latest version (no visibility check: callers check it):
+     * the source in `locale` (falling back to English), the English source (hashes, check lookup) and
+     * the locale actually read. 404 `catalog.item_not_found` / `catalog.guide_not_found`.
+     */
+    loadDocument(itemId: string, guideId: string, locale: "en" | "zh"): Promise<{
+        row: ItemRow;
+        guide: PluginSetupGuide;
+        source: string;
+        enSource: string;
+        locale: "en" | "zh";
+    }>;
+    /** Reads and checks a guide's stored documents (one PG read). */
+    private documents;
+    /** Logs the stored guide entries a version skips (once per render). */
+    private warnSkipped;
     /**
      * Renders a guide for an org (`GET /orgs/:orgId/catalog/:itemId/guides/:guideId`): the item must
      * be one the org's catalog shows (else `catalog.item_not_found`), the guide one its latest
-     * version has (else `catalog.guide_not_found`), and the caller must hold the place's action
-     * (`channels.manage` for `channel-connection`, else `forbidden`). `connectionId` (a live
-     * connection of the org on this plugin, else `channel.not_found`) supplies the connection's name,
-     * webhook URL and default mode; `name` stands in for the name on 新建渠道.
+     * version has (else `catalog.guide_not_found`), `mode` and `audience` the place's (else
+     * `validation_failed`), and the caller must hold the place and audience's action
+     * ({@link PLACE_ACTIONS}, else `forbidden`). The target parameters are the place's
+     * (`guide-places.ts`): a target must be a live object of the org on the plugin, else 404.
      */
     render(org: {
         orgId: string;
         role: OrgRole;
-    }, itemId: string, guideId: string, q: {
-        mode?: string | undefined;
-        connectionId?: string | undefined;
-        name?: string | undefined;
+    }, itemId: string, guideId: string, q: GuideQuery): Promise<RenderedSetupGuide>;
+    /**
+     * Renders a guide for the platform (the super admin's preview, `GET /admin/catalog/:itemId/guides/
+     * :guideId`): any live item, the admin audience, no org (`orgName` unresolved) and no target.
+     */
+    renderForPlatform(itemId: string, guideId: string, q: {
+        locale?: "en" | "zh" | undefined;
     }): Promise<RenderedSetupGuide>;
-    /** A live connection of the org on the plugin; otherwise `channel.not_found`. */
-    private connection;
+    /** The audience asked for, after checking `mode` and `audience` against the place. */
+    private checkQuery;
+    /** The rendered guide: the mode picked, the document rendered, the hash and the reasons. */
+    private renderDoc;
 }
-export {};