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

package/dist/extensions/plugin-guides.js

@@ -7,108 +7,325 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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";
+var PluginGuides_1;
+import { renderSetupGuide, SETUP_GUIDE_PLACE_INFO, SETUP_GUIDE_PLACES, setupGuideDocPath, setupGuideDocProblem, setupGuideHash, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
 import { readCatalogDisplayFiles } from "../catalog/catalog-content.js";
-import { webhookBase, webhookUrlOf } from "../channels/webhook-url.js";
+import { readDisplayFiles } from "../catalog/catalog-files.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { can, roleAtLeast } from "../orgs/roles.js";
-import { packagePath } from "../packages/tgz.js";
+import { PLACE_ACTIONS, resolvePlace, } from "./guide-places.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",
-};
+export { PLACE_ACTIONS } from "./guide-places.js";
 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 GUIDE_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const GUIDE_KEYS = new Set(["id", "place", "template"]);
 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);
+const invalidQuery = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
+/** The live items (with their latest version) by name or id. */
+function latestItems(db, by, keys) {
+    return 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();
+}
+/** Whether a stored `setupGuides` entry is a v2 one (the SDK's strict shape). */
+function isV2Guide(g) {
+    if (typeof g !== "object" || g === null || Array.isArray(g))
+        return false;
+    const o = g;
+    return (Object.keys(o).every((k) => GUIDE_KEYS.has(k)) &&
+        typeof o.id === "string" &&
+        GUIDE_ID_RE.test(o.id) &&
+        SETUP_GUIDE_PLACES.includes(o.place) &&
+        (o.template === undefined || (typeof o.template === "string" && GUIDE_ID_RE.test(o.template))));
+}
 /**
- * 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 version's v2 guides and the entries skipped: a version imported before setup guides v2 keeps
+ * v1-shaped entries, which render no guide (spec §15; not a compatibility layer).
  */
-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");
+function guidesOf(manifest) {
+    const raw = manifest.setupGuides;
+    if (!Array.isArray(raw))
+        return { guides: [], skipped: 0 };
+    const guides = raw.filter(isV2Guide);
+    return { guides, skipped: raw.length - guides.length };
 }
-/** 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);
+/** A plugin's guide for a place (and template): the manifest allows at most one. */
+const guideFor = (manifest, place, templateId) => guidesOf(manifest).guides.find((g) => g.place === place && (templateId === undefined || g.template === templateId));
+/**
+ * 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 const templateGuideOf = (manifest, templateId) => guideFor(manifest, "connector-template", templateId);
+/** The stored file of a guide document, or undefined when the version has none. */
+const docMeta = (row, id, locale) => {
+    const path = setupGuideDocPath(id, locale);
+    return row.files.find((f) => f.path === path);
+};
 /**
- * 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`).
  */
-let PluginGuides = class PluginGuides {
+let PluginGuides = PluginGuides_1 = class PluginGuides {
     db;
     config;
-    constructor(db, config) {
+    log;
+    constructor(db, config, log) {
         this.db = db;
         this.config = config;
+        this.log = log;
     }
-    /** 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();
+        return latestItems(this.db, by, keys);
+    }
+    /** The rows the org's catalog shows ({@link orgVisibleItems}); all of them without an org. */
+    visibleTo(rows, org) {
+        return org === undefined
+            ? rows
+            : orgVisibleItems(this.db, rows, org.orgId, roleAtLeast(org.role, "admin"));
+    }
+    /** The English documents of guides, by `<itemId>/<guideId>` (one PG read); absent when not stored. */
+    async englishSources(pairs) {
+        const metas = pairs.flatMap(({ row, guide }) => {
+            const meta = docMeta(row, guide.id, "en");
+            return meta === undefined ? [] : [{ key: `${row.id}/${guide.id}`, meta }];
+        });
+        const out = new Map();
+        if (metas.length === 0)
+            return out;
+        const files = await readCatalogDisplayFiles(this.db, metas.map((m) => m.meta));
+        metas.forEach((m, i) => {
+            const data = files[i]?.data;
+            if (data !== undefined && setupGuideDocProblem(m.meta.path, data) === undefined) {
+                out.set(m.key, new TextDecoder().decode(data));
+            }
+        });
+        return out;
+    }
+    /** The admin drift hash of a guide for a mode. */
+    static hashOf(enSource, guide, mode) {
+        return setupGuideHash(enSource, {
+            place: guide.place,
+            guideId: guide.id,
+            mode,
+            audience: "admin",
+        });
     }
     /**
-     * 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.
      */
-    async currentAck(plugin, mode) {
-        const [row] = await this.latest("name", [plugin]);
-        const guide = row && guideOf(row.manifest, "channel-connection");
+    async currentAck(plugin, place, o) {
+        const [row] = await this.visibleTo(await this.latest("name", [plugin]), o.org);
+        const guide = row && guideFor(row.manifest, place, o.templateId);
         if (!row || !guide)
             return null;
+        const en = (await this.englishSources([{ row, guide }])).get(`${row.id}/${guide.id}`);
+        if (en === undefined)
+            return null;
         return {
             guideId: guide.id,
             version: row.latest_version,
-            hash: setupGuideHash(guide, row.files, mode),
-            mode,
+            hash: PluginGuides_1.hashOf(en, guide, o.mode),
+            mode: o.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.
+     * 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.
      */
-    async ackDrifted(plugin, ack) {
+    async ackDrifted(plugin, place, ack, o = {}) {
         if (ack === null)
             return false;
-        const current = await this.currentAck(plugin, ack.mode);
+        const current = await this.currentAck(plugin, place, {
+            mode: ack.mode,
+            ...(o.templateId !== undefined && { templateId: o.templateId }),
+        });
         return current !== null && current.guideId === ack.guideId && current.hash !== ack.hash;
     }
+    /**
+     * 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.
+     */
+    async templateAck(itemId, templateId, org) {
+        if (!UUID_RE.test(itemId))
+            return null;
+        const [row] = await this.visibleTo(await this.latest("id", [itemId]), org);
+        const guide = row && guideFor(row.manifest, "connector-template", templateId);
+        if (!row || !guide)
+            return null;
+        const en = (await this.englishSources([{ row, guide }])).get(`${row.id}/${guide.id}`);
+        if (en === undefined)
+            return null;
+        return {
+            guideId: guide.id,
+            version: row.latest_version,
+            hash: PluginGuides_1.hashOf(en, guide, null),
+            mode: 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.
+     */
+    async templateGuides(pairs) {
+        const out = new Map();
+        const ids = [...new Set(pairs.map((p) => p.itemId))].filter((id) => UUID_RE.test(id));
+        if (ids.length === 0)
+            return out;
+        const rows = new Map((await this.latest("id", ids)).map((r) => [r.id, r]));
+        for (const p of pairs) {
+            const row = rows.get(p.itemId);
+            const guide = row && guideFor(row.manifest, "connector-template", p.templateId);
+            if (guide)
+                out.set(`${p.itemId}/${p.templateId}`, { itemId: p.itemId, guideId: guide.id });
+        }
+        return out;
+    }
+    /**
+     * 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.
+     */
+    async connectorStates(connectors, org) {
+        const out = new Map();
+        const none = { setupGuide: null, guideDrift: null };
+        const ids = [
+            ...new Set(connectors.flatMap((c) => (c.itemId !== null && c.templateId !== null ? [c.itemId] : []))),
+        ].filter((id) => UUID_RE.test(id));
+        const rows = ids.length === 0
+            ? []
+            : await orgVisibleItems(this.db, await this.latest("id", ids), org.orgId, roleAtLeast(org.role, "admin"));
+        const byId = new Map(rows.map((r) => [r.id, r]));
+        const guideOf = (c) => {
+            const row = c.itemId === null ? undefined : byId.get(c.itemId);
+            const guide = row && c.templateId !== null
+                ? guideFor(row.manifest, "connector-template", c.templateId)
+                : undefined;
+            return row && guide ? { row, guide } : undefined;
+        };
+        // documents only for the guides an ack is compared with
+        const compared = new Map();
+        for (const c of connectors) {
+            const g = guideOf(c);
+            if (g && c.guideAck !== null && c.guideAck.guideId === g.guide.id) {
+                compared.set(`${g.row.id}/${g.guide.id}`, g);
+            }
+        }
+        const sources = await this.englishSources([...compared.values()]);
+        for (const c of connectors) {
+            const g = guideOf(c);
+            if (!g) {
+                out.set(c.id, none);
+                continue;
+            }
+            const ack = c.guideAck;
+            const en = sources.get(`${g.row.id}/${g.guide.id}`);
+            const drifted = en !== undefined &&
+                ack !== null &&
+                ack.guideId === g.guide.id &&
+                PluginGuides_1.hashOf(en, g.guide, null) !== ack.hash;
+            out.set(c.id, {
+                setupGuide: { itemId: g.row.id, guideId: g.guide.id, version: g.row.latest_version },
+                guideDrift: drifted && ack !== null ? { from: ack.version, to: g.row.latest_version } : null,
+            });
+        }
+        return out;
+    }
+    /**
+     * 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).
+     */
+    async templateGuideChanges(itemId, from, to) {
+        const targets = guidesOf(to.manifest).guides.filter((g) => g.place === "connector-template" && g.template !== undefined);
+        if (targets.length === 0)
+            return [];
+        const fromRow = from === null
+            ? undefined
+            : await this.db
+                .selectFrom("catalog_item_versions")
+                .select(["manifest", "files"])
+                .where("item_id", "=", itemId)
+                .where("version", "=", from)
+                .executeTakeFirst();
+        const out = [];
+        for (const guide of targets) {
+            const templateId = guide.template;
+            const toHash = await this.storedHash(to, guide);
+            if (toHash === undefined)
+                continue;
+            const before = fromRow && guideFor(fromRow.manifest, "connector-template", templateId);
+            const fromHash = fromRow && before?.id === guide.id ? await this.storedHash(fromRow, before) : undefined;
+            if (fromHash === toHash)
+                continue;
+            const counted = await this.db
+                .selectFrom("connectors as c")
+                .innerJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+                .innerJoin("orgs as o", "o.id", "c.org_id")
+                .select((eb) => eb.fn.count("c.org_id").distinct().as("orgs"))
+                .where("t.catalog_item_id", "=", itemId)
+                .where("t.template_id", "=", templateId)
+                .where("c.deleted_at", "is", null)
+                .where("o.deleted_at", "is", null)
+                .where(sql `c.guide_ack->>'guideId' = ${guide.id}`)
+                .where(sql `c.guide_ack->>'hash' <> ${toHash}`)
+                .executeTakeFirst();
+            const orgs = Number(counted?.orgs ?? 0);
+            if (fromHash === undefined && orgs === 0)
+                continue;
+            out.push({ templateId, guideId: guide.id, from, to: to.version, orgs });
+        }
+        return out;
+    }
+    /** The admin drift hash of a guide in a version (no mode), or undefined when not stored. */
+    async storedHash(row, guide) {
+        const meta = docMeta(row, guide.id, "en");
+        if (meta === undefined)
+            return undefined;
+        const data = (await readDisplayFiles(this.db, [meta])).get(meta.path)?.data;
+        if (data === undefined || setupGuideDocProblem(meta.path, data) !== undefined)
+            return undefined;
+        return PluginGuides_1.hashOf(new TextDecoder().decode(data), guide, null);
+    }
     /**
      * 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.
@@ -117,31 +334,40 @@ let PluginGuides = class PluginGuides {
         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 rows = (await this.latest("name", names)).filter((r) => guideFor(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");
+            const guide = guideFor(r.manifest, "channel-connection");
             out.set(r.name, {
                 itemId: r.id,
                 guideId: guide.id,
                 version: r.latest_version,
                 guide,
-                files: r.files,
+                row: r,
             });
         }
         return out;
     }
-    /** 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). */
     async connectionStates(connections, org) {
         const guides = await this.channelGuides(connections.map((c) => c.plugin), org);
+        // documents only for the guides an ack is compared with
+        const compared = [
+            ...new Set(connections
+                .filter((c) => c.guideAck !== null && guides.get(c.plugin)?.guideId === c.guideAck.guideId)
+                .map((c) => c.plugin)),
+        ].map((p) => guides.get(p));
+        const sources = await this.englishSources(compared);
         const out = new Map();
         for (const c of connections) {
             const g = guides.get(c.plugin);
             const ack = c.guideAck;
+            const en = g && sources.get(`${g.itemId}/${g.guideId}`);
             const drifted = g !== undefined &&
+                en !== undefined &&
                 ack !== null &&
                 ack.guideId === g.guideId &&
-                setupGuideHash(g.guide, g.files, ack.mode) !== ack.hash;
+                PluginGuides_1.hashOf(en, g.guide, 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,
@@ -149,13 +375,61 @@ let PluginGuides = class PluginGuides {
         }
         return out;
     }
+    /**
+     * 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`.
+     */
+    async loadDocument(itemId, guideId, locale) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        const [row] = await this.latest("id", [itemId]);
+        if (!row)
+            throw itemNotFound();
+        const guide = guidesOf(row.manifest).guides.find((g) => g.id === guideId);
+        if (!guide)
+            throw guideNotFound();
+        return { row, guide, ...(await this.documents(row, guide, locale)) };
+    }
+    /** Reads and checks a guide's stored documents (one PG read). */
+    async documents(row, guide, locale) {
+        const en = docMeta(row, guide.id, "en");
+        // stored at import with the version; a missing one means tampered or lost storage
+        if (en === undefined) {
+            throw new ApiError("internal", `Setup guide document ${setupGuideDocPath(guide.id, "en")} is not stored`);
+        }
+        const zh = locale === "zh" ? docMeta(row, guide.id, "zh") : undefined;
+        const files = await readCatalogDisplayFiles(this.db, zh === undefined ? [en] : [en, zh]);
+        const text = (f, path) => {
+            const problem = setupGuideDocProblem(path, f?.data);
+            if (problem !== undefined) {
+                throw new ApiError("internal", `Stored setup guide document is invalid: ${problem}`);
+            }
+            return new TextDecoder().decode(f?.data);
+        };
+        const enSource = text(files[0], en.path);
+        if (zh === undefined)
+            return { source: enSource, enSource, locale: "en" };
+        return { source: text(files[1], zh.path), enSource, locale: "zh" };
+    }
+    /** Logs the stored guide entries a version skips (once per render). */
+    warnSkipped(row) {
+        const { skipped } = guidesOf(row.manifest);
+        if (skipped > 0) {
+            this.log.warn("setup guide entries skipped: not in the v2 format (update the plugin)", {
+                plugin: row.name,
+                version: row.latest_version,
+                skipped,
+            });
+        }
+    }
     /**
      * 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.
      */
     async render(org, itemId, guideId, q) {
         if (!UUID_RE.test(itemId))
@@ -164,83 +438,82 @@ let PluginGuides = class PluginGuides {
         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);
+        this.warnSkipped(row);
+        const guide = guidesOf(row.manifest).guides.find((g) => g.id === guideId);
         if (!guide)
             throw guideNotFound();
-        if (!can(org.role, PLACE_ACTION[guide.place])) {
+        const audience = this.checkQuery(guide, q);
+        const action = PLACE_ACTIONS[guide.place][audience];
+        if (action === undefined || !can(org.role, action)) {
             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 docs = await this.documents(row, guide, q.locale ?? "en");
         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 resolution = await resolvePlace({
+            db: this.db,
+            config: this.config.get(),
+            item: { id: row.id, name: row.name, version: row.latest_version },
+            guide,
+            locale: docs.locale,
+            org: { orgId: org.orgId, name: orgRow?.name ?? "" },
+            query: { connectionId: q.connectionId, name: q.name, connectorId: q.connectorId },
         });
-        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;
+        return this.renderDoc(row, guide, docs, resolution, { mode: q.mode, audience });
+    }
+    /**
+     * 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.
+     */
+    async renderForPlatform(itemId, guideId, q) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        const [row] = await this.latest("id", [itemId]);
+        if (!row)
+            throw itemNotFound();
+        this.warnSkipped(row);
+        const guide = guidesOf(row.manifest).guides.find((g) => g.id === guideId);
+        if (!guide)
+            throw guideNotFound();
+        const docs = await this.documents(row, guide, q.locale ?? "en");
+        const resolution = await resolvePlace({
+            db: this.db,
+            config: this.config.get(),
+            item: { id: row.id, name: row.name, version: row.latest_version },
+            guide,
+            locale: docs.locale,
+            org: null,
+            query: {},
         });
-        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 this.renderDoc(row, guide, docs, resolution, { mode: undefined, audience: "admin" });
+    }
+    /** The audience asked for, after checking `mode` and `audience` against the place. */
+    checkQuery(guide, q) {
+        const info = SETUP_GUIDE_PLACE_INFO[guide.place];
+        const audience = q.audience ?? "admin";
+        if (!info.audiences.includes(audience)) {
+            throw invalidQuery("audience", `audience must be one of ${info.audiences.join(", ")} for a ${guide.place} guide`);
+        }
+        if (q.mode !== undefined && !info.modes.includes(q.mode)) {
+            throw invalidQuery("mode", info.modes.length === 0
+                ? `a ${guide.place} guide has no modes`
+                : `mode must be one of ${info.modes.join(", ")}`);
+        }
+        return audience;
+    }
+    /** The rendered guide: the mode picked, the document rendered, the hash and the reasons. */
+    renderDoc(row, guide, docs, resolution, o) {
+        const info = SETUP_GUIDE_PLACE_INFO[guide.place];
+        // the asked mode, else the target's stored one, else the place's first (spec §8)
+        const mode = info.modes.length === 0 ? null : (o.mode ?? resolution.storedMode ?? info.modes[0] ?? null);
+        const doc = renderSetupGuide(docs.source, {
+            place: guide.place,
+            mode,
+            audience: o.audience,
+            values: { ...resolution.values, mode },
         });
         return {
             itemId: row.id,
@@ -248,36 +521,34 @@ let PluginGuides = class PluginGuides {
             version: row.latest_version,
             id: guide.id,
             place: guide.place,
-            title: guide.title,
-            modes,
+            template: guide.template ?? null,
+            locale: docs.locale,
+            title: doc.title,
+            modes: doc.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),
+            audiences: doc.audiences,
+            audience: o.audience,
+            blocks: doc.blocks,
+            checks: doc.checks,
+            // `mode` without a value (a place without modes) has no reason anyone can act on
+            unresolved: doc.unresolved.flatMap((name) => {
+                const reason = resolution.reasons[name];
+                return reason === undefined ? [] : [{ name, reason }];
+            }),
+            hash: setupGuideHash(docs.enSource, {
+                place: guide.place,
+                guideId: guide.id,
+                mode,
+                audience: o.audience,
+            }),
+            target: resolution.target,
         };
     }
-    /** 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([
+PluginGuides = PluginGuides_1 = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(KernelConfigService))
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(KERNEL_LOGGER))
 ], PluginGuides);
 export { PluginGuides };