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

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.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";
@@ -1291,9 +1291,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,

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/permission-set.d.ts

@@ -49,6 +49,12 @@ export interface PermissionSet {
             views: string[];
             embeds: 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）；没有警告或不是安装记录时省略。
@@ -106,8 +112,16 @@ export declare const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
 /** 渲染 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

@@ -108,6 +108,10 @@ export function buildPermissionSet(input) {
                 .sort((a, b) => cmp(a.purpose, b.purpose)),
             network: sortedUnique(p.network),
             ui: { views: sortedUnique(p.ui?.views), embeds: sortedUnique(p.ui?.embeds) },
+            // 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 } : {}),
     };
@@ -155,6 +159,8 @@ export function permissionKeys(set) {
         keys.push(`${UI_VIEW_KEY_PREFIX}${v}`);
     for (const e of p.ui?.embeds ?? [])
         keys.push(`ui.embed:${e}`);
+    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);
@@ -167,11 +173,19 @@ export const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
 /** 渲染 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) {