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

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 {};