@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

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

@@ -1,3 +1,5 @@
+import type { LocalizedName } 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";
 /**
@@ -35,10 +37,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 +55,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 +122,57 @@ 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;
+    /**
+     * 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 +202,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

@@ -18,16 +18,16 @@ 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",
 ];
 /** 总是敏感的类别。 */
@@ -159,7 +159,7 @@ export function permissionGroups(set) {
     });
 }
 /**
- * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * 需要超级管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
  * （`converging` 收敛中、`pending_migration` 待迁移）。
  */
 export function extensionNeedsAction(status) {
@@ -167,7 +167,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 +179,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)

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

@@ -0,0 +1,129 @@
+import { type PluginSetupGuide, type SetupGuideLanguage, type SetupGuidePlace, type SetupGuideText } 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 OrgRole } from "../orgs/roles.js";
+/** The setup guide a channel connection was set up with (`channel_connections.guide_ack`). */
+export type GuideAck = GuideAckJson;
+/** Where a channel 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. */
+export interface ConnectionGuideState {
+    /** The plugin's channel-connection 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).
+     */
+    guideDrift: {
+        from: string;
+        to: string;
+    } | null;
+}
+/** A guide rendered for an org (spec 2026-11-08-plugin-setup-guides-design.md §4). */
+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. */
+    modes: string[];
+    /** The mode rendered (null for a guide without modes and no connection). */
+    mode: string | null;
+    steps: SetupGuideText[];
+    files: {
+        title: SetupGuideText;
+        language: SetupGuideLanguage;
+        fileName: string;
+        content: string;
+    }[];
+    /** 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). */
+    hash: string;
+}
+type VersionFile = {
+    path: string;
+    size: number;
+    sha256: string;
+};
+/**
+ * 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.
+ */
+export declare function setupGuideHash(guide: PluginSetupGuide, files: VersionFile[], mode: string | null): string;
+/**
+ * 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`).
+ */
+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 latest;
+    /**
+     * 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).
+     */
+    currentAck(plugin: string, mode: string): 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.
+     */
+    ackDrifted(plugin: string, ack: GuideAck | null): Promise<boolean>;
+    /**
+     * 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.
+     */
+    channelGuides(names: string[], org: {
+        orgId: string;
+        role: OrgRole;
+    }): Promise<Map<string, SetupGuideRef & {
+        guide: PluginSetupGuide;
+        files: VersionFile[];
+    }>>;
+    /** The guide fields of channel connections (one query for all; spec §6 for the drift rule). */
+    connectionStates(connections: {
+        id: string;
+        plugin: string;
+        guideAck: GuideAck | null;
+    }[], org: {
+        orgId: string;
+        role: OrgRole;
+    }): Promise<Map<string, ConnectionGuideState>>;
+    /**
+     * 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 新建渠道.
+     */
+    render(org: {
+        orgId: string;
+        role: OrgRole;
+    }, itemId: string, guideId: string, q: {
+        mode?: string | undefined;
+        connectionId?: string | undefined;
+        name?: string | undefined;
+    }): Promise<RenderedSetupGuide>;
+    /** A live connection of the org on the plugin; otherwise `channel.not_found`. */
+    private connection;
+}
+export {};

package/dist/extensions/plugin-guides.js

@@ -0,0 +1,283 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { renderSetupGuideText, SETUP_GUIDE_MODES, SETUP_GUIDE_VARIABLES, setupGuideFileProblem, setupGuideModes, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { readCatalogDisplayFiles } from "../catalog/catalog-content.js";
+import { webhookBase, webhookUrlOf } from "../channels/webhook-url.js";
+import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { can, roleAtLeast } from "../orgs/roles.js";
+import { packagePath } from "../packages/tgz.js";
+import { orgVisibleItems } from "./plugin-icons.js";
+/** The org action each place's page needs besides `catalog.read`. */
+const PLACE_ACTION = {
+    "channel-connection": "channels.manage",
+};
+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 itemNotFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
+const guideNotFound = () => new ApiError("catalog.guide_not_found", "The plugin has no such setup guide");
+/** The items of a guide (steps or files) that apply to a mode: those without one, and its own. */
+const forMode = (items, mode) => (items ?? []).filter((x) => x.mode === undefined || x.mode === mode);
+/**
+ * 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.
+ */
+export function setupGuideHash(guide, files, mode) {
+    const h = createHash("sha256");
+    for (const f of forMode(guide.files, mode)) {
+        const path = packagePath(f.path);
+        h.update(`${path}\0${files.find((x) => x.path === path)?.sha256 ?? "missing"}\n`);
+    }
+    return h.digest("hex");
+}
+/** A plugin's guide for a place: its first one there (a plugin normally has one per place). */
+const guideOf = (manifest, place) => (manifest.setupGuides ?? []).find((g) => g.place === place);
+/**
+ * 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`).
+ */
+let PluginGuides = class PluginGuides {
+    db;
+    config;
+    constructor(db, config) {
+        this.db = db;
+        this.config = config;
+    }
+    /** The live items (with their latest version) by name or id. */
+    latest(by, keys) {
+        return this.db
+            .selectFrom("catalog_items as i")
+            .innerJoin("catalog_item_versions as v", (j) => j.onRef("v.item_id", "=", "i.id").onRef("v.version", "=", "i.latest_version"))
+            .select([
+            "i.id",
+            "i.name",
+            "i.scope",
+            "i.builtin",
+            "i.disabled",
+            "i.shown_to_others",
+            "i.owner_org_id",
+            "i.shareable",
+            "i.awaiting_confirmation",
+            "i.latest_version",
+            "v.manifest",
+            "v.files",
+        ])
+            .where(by === "name" ? "i.name" : "i.id", "in", [...new Set(keys)])
+            .where("i.deleted_at", "is", null)
+            .execute();
+    }
+    /**
+     * 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).
+     */
+    async currentAck(plugin, mode) {
+        const [row] = await this.latest("name", [plugin]);
+        const guide = row && guideOf(row.manifest, "channel-connection");
+        if (!row || !guide)
+            return null;
+        return {
+            guideId: guide.id,
+            version: row.latest_version,
+            hash: setupGuideHash(guide, row.files, mode),
+            mode,
+        };
+    }
+    /**
+     * 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.
+     */
+    async ackDrifted(plugin, ack) {
+        if (ack === null)
+            return false;
+        const current = await this.currentAck(plugin, ack.mode);
+        return current !== null && current.guideId === ack.guideId && current.hash !== ack.hash;
+    }
+    /**
+     * 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.
+     */
+    async channelGuides(names, org) {
+        const out = new Map();
+        if (names.length === 0)
+            return out;
+        const rows = (await this.latest("name", names)).filter((r) => guideOf(r.manifest, "channel-connection") !== undefined);
+        const visible = await orgVisibleItems(this.db, rows, org.orgId, roleAtLeast(org.role, "admin"));
+        for (const r of visible) {
+            const guide = guideOf(r.manifest, "channel-connection");
+            out.set(r.name, {
+                itemId: r.id,
+                guideId: guide.id,
+                version: r.latest_version,
+                guide,
+                files: r.files,
+            });
+        }
+        return out;
+    }
+    /** The guide fields of channel connections (one query for all; spec §6 for the drift rule). */
+    async connectionStates(connections, org) {
+        const guides = await this.channelGuides(connections.map((c) => c.plugin), org);
+        const out = new Map();
+        for (const c of connections) {
+            const g = guides.get(c.plugin);
+            const ack = c.guideAck;
+            const drifted = g !== undefined &&
+                ack !== null &&
+                ack.guideId === g.guideId &&
+                setupGuideHash(g.guide, g.files, ack.mode) !== ack.hash;
+            out.set(c.id, {
+                setupGuide: g ? { itemId: g.itemId, guideId: g.guideId, version: g.version } : null,
+                guideDrift: drifted ? { from: ack.version, to: g.version } : null,
+            });
+        }
+        return out;
+    }
+    /**
+     * 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 新建渠道.
+     */
+    async render(org, itemId, guideId, q) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        const rows = await this.latest("id", [itemId]);
+        const [row] = await orgVisibleItems(this.db, rows, org.orgId, roleAtLeast(org.role, "admin"));
+        if (!row)
+            throw itemNotFound();
+        const guide = (row.manifest.setupGuides ?? []).find((g) => g.id === guideId);
+        if (!guide)
+            throw guideNotFound();
+        if (!can(org.role, PLACE_ACTION[guide.place])) {
+            throw new ApiError("forbidden", "Insufficient organization role");
+        }
+        if (q.mode !== undefined && !SETUP_GUIDE_MODES[guide.place].includes(q.mode)) {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                {
+                    path: "mode",
+                    message: `mode must be one of ${SETUP_GUIDE_MODES[guide.place].join(", ")}`,
+                },
+            ]);
+        }
+        const connection = q.connectionId === undefined
+            ? undefined
+            : await this.connection(org.orgId, row.name, q.connectionId);
+        const modes = setupGuideModes(guide);
+        const mode = q.mode ?? connection?.inbound_mode ?? modes[0] ?? null;
+        const cfg = this.config.get();
+        const publicUrl = cfg.http.publicUrl?.replace(/\/+$/, "") ?? null;
+        const base = webhookBase(cfg);
+        const orgRow = await this.db
+            .selectFrom("orgs")
+            .select("name")
+            .where("id", "=", org.orgId)
+            .executeTakeFirst();
+        const values = {
+            publicUrl,
+            webhookUrl: connection && base !== undefined ? webhookUrlOf(base, connection.id) : null,
+            signInCallbackUrl: publicUrl === null
+                ? null
+                : `${publicUrl}/api/v1/auth/sso/${encodeURIComponent(row.name)}/callback`,
+            connectionName: connection?.name ?? q.name?.trim() ?? null,
+            orgName: orgRow?.name ?? null,
+            pluginName: row.name,
+            pluginVersion: row.latest_version,
+            mode,
+        };
+        if (values.connectionName === "")
+            values.connectionName = null;
+        const known = SETUP_GUIDE_VARIABLES[guide.place];
+        const unresolved = new Set();
+        const render = (text, language) => {
+            const r = renderSetupGuideText(text, values, language, known);
+            for (const u of r.unresolved)
+                unresolved.add(u);
+            return r.text;
+        };
+        const localized = (t, language) => ({
+            en: render(t.en, language),
+            ...(t.zh !== undefined && { zh: render(t.zh, language) }),
+        });
+        const versionFiles = row.files;
+        const selected = forMode(guide.files, mode);
+        const metas = selected.map((f) => {
+            const path = packagePath(f.path);
+            const meta = versionFiles.find((x) => x.path === path);
+            // stored at import with the version; a missing one means tampered or lost storage
+            if (!meta)
+                throw new ApiError("internal", `Setup guide file ${path} is not stored`);
+            return meta;
+        });
+        const stored = await readCatalogDisplayFiles(this.db, metas);
+        const files = selected.map((f) => {
+            const path = packagePath(f.path);
+            const data = stored.find((x) => x.path === path)?.data;
+            const problem = setupGuideFileProblem(path, data);
+            if (problem !== undefined) {
+                throw new ApiError("internal", `Stored setup guide file is invalid: ${problem}`);
+            }
+            return {
+                title: f.title,
+                language: f.language,
+                fileName: path.split("/").pop().replace(/\.tmpl$/i, ""),
+                content: render(new TextDecoder().decode(data), f.language),
+            };
+        });
+        return {
+            itemId: row.id,
+            plugin: row.name,
+            version: row.latest_version,
+            id: guide.id,
+            place: guide.place,
+            title: guide.title,
+            modes,
+            mode,
+            steps: forMode(guide.steps, mode).map((s) => localized({ en: s.en, ...(s.zh !== undefined && { zh: s.zh }) }, "text")),
+            files,
+            unresolved: known.filter((k) => unresolved.has(k)),
+            hash: setupGuideHash(guide, versionFiles, mode),
+        };
+    }
+    /** A live connection of the org on the plugin; otherwise `channel.not_found`. */
+    async connection(orgId, plugin, id) {
+        const notFound = () => new ApiError("channel.not_found", "Channel connection not found");
+        if (!UUID_RE.test(id))
+            throw notFound();
+        const c = await this.db
+            .selectFrom("channel_connections")
+            .select(["id", "name", "inbound_mode"])
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("plugin", "=", plugin)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!c)
+            throw notFound();
+        return c;
+    }
+};
+PluginGuides = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KernelConfigService))
+], PluginGuides);
+export { PluginGuides };

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

@@ -0,0 +1,54 @@
+import { type PluginScope } from "../catalog/scope.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type OrgRole } from "../orgs/roles.js";
+/** Who reads the icons: the super admin (admin routes) or one org (its routes, its visibility). */
+export type PluginIconScope = {
+    kind: "admin";
+} | {
+    kind: "org";
+    orgId: string;
+    isAdmin: boolean;
+};
+/** The icon scope of an org route's caller (its org and role). */
+export declare const orgIconScope: (org: {
+    orgId: string;
+    role: OrgRole;
+}) => PluginIconScope;
+/** The catalog item columns {@link orgVisibleItems} reads. */
+export interface OrgVisibilityRow {
+    id: string;
+    scope: PluginScope;
+    builtin: boolean;
+    disabled: boolean;
+    shown_to_others: boolean;
+    owner_org_id: string | null;
+    shareable: boolean;
+    awaiting_confirmation: boolean;
+}
+/**
+ * The rows of live catalog items the org's catalog shows (one query for the org's list rows):
+ * members never see disabled items, an upload waiting for confirmation only its owner, another
+ * org's item only when shareable or listed here (the share gate), a `named` item only its listed
+ * orgs or as requestable. Shared by the plugin icons and the setup guides.
+ */
+export declare function orgVisibleItems<T extends OrgVisibilityRow>(db: KernelDb, rows: T[], orgId: string, isAdmin: boolean): Promise<T[]>;
+/**
+ * Plugin icons for the things a plugin brings (channels, extensions, model providers; maintainer
+ * decision 2026-11-08): extension name -> the URL of its plugin's icon, the catalog item of the
+ * same name (one live item per name). A name is present only when the item's latest version has
+ * an icon and the reader may load it: the admin scope gets `GET /api/v1/admin/catalog/items/:id/icon`
+ * for every live item; an org gets `GET /api/v1/orgs/:orgId/catalog/:itemId/icon` only for items
+ * its catalog shows (members never see disabled items, a `named` item only for its listed orgs or
+ * as requestable, an org-owned item only for its owner or through the share gate, an upload
+ * waiting for confirmation only for its owner). The URL carries the version, so a new icon is not
+ * hidden by the browser cache. Stateless; one query per call (two for an org: its list rows).
+ */
+export declare class PluginIcons {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** Extension (plugin) name -> its icon's URL; names without one are absent. */
+    many(names: string[], scope: PluginIconScope): Promise<Map<string, string>>;
+    /** Catalog item id -> its icon's URL (a list of items); items without one are absent. */
+    ofItems(ids: string[], scope: PluginIconScope): Promise<Map<string, string>>;
+    private resolve;
+}