@capybara-hq/plugin-sdk 0.1.0-rc.6 → 0.1.0-rc.8

package/dist/setup-guide.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Plugin setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): setup material a plugin
+ * ships (steps and template files such as Slack's app manifest) that the kernel renders with a
+ * fixed set of safe, deterministic variables and the web shows where the person needs it. The
+ * format lives in `plugin.json` `setupGuides` ({@link PluginSetupGuide}); this module holds the
+ * places, their modes and variables, the limits and the pure renderer.
+ *
+ * Placeholders are `{{name}}` (spaces inside the braces allowed) with `name` matching
+ * `[A-Za-z][A-Za-z0-9]*`. There is no other syntax: no conditionals, loops, filters or escapes. A
+ * placeholder the place does not define, or one without a value, stays as written.
+ */
+/** Where a guide is shown. `channel-connection`: 新建渠道 and the channel detail page. */
+export declare const SETUP_GUIDE_PLACES: readonly ["channel-connection"];
+export type SetupGuidePlace = (typeof SETUP_GUIDE_PLACES)[number];
+/**
+ * The modes of each place: a step or file with `mode` applies to that mode only.
+ * `channel-connection`: the connection's `inboundMode`.
+ */
+export declare const SETUP_GUIDE_MODES: Readonly<Record<SetupGuidePlace, readonly string[]>>;
+/**
+ * The variables of each place. None is a secret: the kernel fills them from public URLs, names and
+ * versions only (`publicUrl`, `webhookUrl`, `signInCallbackUrl`, `connectionName`, `orgName`,
+ * `pluginName`, `pluginVersion`, `mode`).
+ */
+export declare const SETUP_GUIDE_VARIABLES: Readonly<Record<SetupGuidePlace, readonly string[]>>;
+/** Languages of a template file: the code block's label and how values are escaped. */
+export declare const SETUP_GUIDE_LANGUAGES: readonly ["yaml", "json", "text"];
+export type SetupGuideLanguage = (typeof SETUP_GUIDE_LANGUAGES)[number];
+/** Limits of setup guides. */
+export declare const SETUP_GUIDE_LIMITS: {
+    /** Guides per plugin. */
+    readonly guides: 8;
+    /** Steps per guide. */
+    readonly steps: 20;
+    /** Files per guide. */
+    readonly files: 8;
+    /** Characters of a step (each language). */
+    readonly stepChars: 2000;
+    /** Characters of a title (each language). */
+    readonly titleChars: 100;
+    /** Bytes of a template file. */
+    readonly fileBytes: number;
+};
+/** File names a template file may have (checked on the path). */
+export declare const SETUP_GUIDE_FILE_RE: RegExp;
+/** Localized text: English, optional Chinese (falls back to English). */
+export interface SetupGuideText {
+    en: string;
+    zh?: string;
+}
+/** A step: plain text (a backtick pair is shown as inline code), optionally for one mode. */
+export interface SetupGuideStep extends SetupGuideText {
+    mode?: string;
+}
+/** A template file of a guide. */
+export interface SetupGuideFile {
+    /** `./…` inside the plugin, `.tmpl` / `.yaml` / `.yml` / `.json` / `.txt`. */
+    path: string;
+    title: SetupGuideText;
+    language: SetupGuideLanguage;
+    mode?: string;
+}
+/** A setup guide in `plugin.json` `setupGuides`. */
+export interface PluginSetupGuide {
+    /** `^[a-z0-9][a-z0-9-]{0,63}$`, unique in the plugin. */
+    id: string;
+    place: SetupGuidePlace;
+    title: SetupGuideText;
+    steps?: SetupGuideStep[];
+    files?: SetupGuideFile[];
+}
+/** The placeholder names a text uses, each once, in order of first use. */
+export declare function setupGuidePlaceholders(text: string): string[];
+/** The placeholders of a text that the place does not define (the toolchain refuses them). */
+export declare function unknownSetupGuidePlaceholders(text: string, place: SetupGuidePlace): string[];
+/** The modes a guide's steps and files use, in the place's order (empty: no mode switch). */
+export declare function setupGuideModes(guide: PluginSetupGuide): string[];
+/**
+ * Renders a guide text: each `{{name}}` with a value in `values` is replaced by it, escaped for
+ * `language` (`yaml` / `json`: JSON-string-escaped without quotes, so a placeholder inside double
+ * quotes stays one string; `text`: control characters become spaces). A placeholder whose value is
+ * null or undefined stays as written and is listed in `unresolved` when `known` holds it; one not
+ * in `known` stays as written and is not listed. Never runs code; deterministic.
+ */
+export declare function renderSetupGuideText(text: string, values: Readonly<Record<string, string | null | undefined>>, language: SetupGuideLanguage, known?: readonly string[]): {
+    text: string;
+    unresolved: string[];
+};
+/**
+ * Whether a guide's template file is usable: present, at most {@link SETUP_GUIDE_LIMITS}`.fileBytes`,
+ * valid UTF-8 text without NUL. The problem (English, naming the path), or undefined when it is.
+ * Shared by the packer and the kernel's package reader.
+ */
+export declare function setupGuideFileProblem(path: string, data: Uint8Array | undefined): string | undefined;

package/dist/setup-guide.js

@@ -0,0 +1,135 @@
+/**
+ * Plugin setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): setup material a plugin
+ * ships (steps and template files such as Slack's app manifest) that the kernel renders with a
+ * fixed set of safe, deterministic variables and the web shows where the person needs it. The
+ * format lives in `plugin.json` `setupGuides` ({@link PluginSetupGuide}); this module holds the
+ * places, their modes and variables, the limits and the pure renderer.
+ *
+ * Placeholders are `{{name}}` (spaces inside the braces allowed) with `name` matching
+ * `[A-Za-z][A-Za-z0-9]*`. There is no other syntax: no conditionals, loops, filters or escapes. A
+ * placeholder the place does not define, or one without a value, stays as written.
+ */
+/** Where a guide is shown. `channel-connection`: 新建渠道 and the channel detail page. */
+export const SETUP_GUIDE_PLACES = ["channel-connection"];
+/**
+ * The modes of each place: a step or file with `mode` applies to that mode only.
+ * `channel-connection`: the connection's `inboundMode`.
+ */
+export const SETUP_GUIDE_MODES = {
+    "channel-connection": ["long_connection", "webhook"],
+};
+/**
+ * The variables of each place. None is a secret: the kernel fills them from public URLs, names and
+ * versions only (`publicUrl`, `webhookUrl`, `signInCallbackUrl`, `connectionName`, `orgName`,
+ * `pluginName`, `pluginVersion`, `mode`).
+ */
+export const SETUP_GUIDE_VARIABLES = {
+    "channel-connection": [
+        "publicUrl",
+        "webhookUrl",
+        "signInCallbackUrl",
+        "connectionName",
+        "orgName",
+        "pluginName",
+        "pluginVersion",
+        "mode",
+    ],
+};
+/** Languages of a template file: the code block's label and how values are escaped. */
+export const SETUP_GUIDE_LANGUAGES = ["yaml", "json", "text"];
+/** Limits of setup guides. */
+export const SETUP_GUIDE_LIMITS = {
+    /** Guides per plugin. */
+    guides: 8,
+    /** Steps per guide. */
+    steps: 20,
+    /** Files per guide. */
+    files: 8,
+    /** Characters of a step (each language). */
+    stepChars: 2000,
+    /** Characters of a title (each language). */
+    titleChars: 100,
+    /** Bytes of a template file. */
+    fileBytes: 64 * 1024,
+};
+/** File names a template file may have (checked on the path). */
+export const SETUP_GUIDE_FILE_RE = /\.(?:tmpl|ya?ml|json|txt)$/i;
+const PLACEHOLDER_RE = /\{\{\s*([A-Za-z][A-Za-z0-9]*)\s*\}\}/g;
+/** The placeholder names a text uses, each once, in order of first use. */
+export function setupGuidePlaceholders(text) {
+    const out = [];
+    for (const m of text.matchAll(PLACEHOLDER_RE)) {
+        const name = m[1];
+        if (!out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
+/** The placeholders of a text that the place does not define (the toolchain refuses them). */
+export function unknownSetupGuidePlaceholders(text, place) {
+    const known = SETUP_GUIDE_VARIABLES[place];
+    return setupGuidePlaceholders(text).filter((n) => !known.includes(n));
+}
+/** The modes a guide's steps and files use, in the place's order (empty: no mode switch). */
+export function setupGuideModes(guide) {
+    const used = new Set();
+    for (const s of guide.steps ?? [])
+        if (s.mode !== undefined)
+            used.add(s.mode);
+    for (const f of guide.files ?? [])
+        if (f.mode !== undefined)
+            used.add(f.mode);
+    return SETUP_GUIDE_MODES[guide.place].filter((m) => used.has(m));
+}
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what is replaced
+const CONTROL_RE = /[\u0000-\u001f\u007f]/g;
+/** A value as inserted into a text of the language (see {@link renderSetupGuideText}). */
+function escapeValue(value, language) {
+    if (language === "text")
+        return value.replace(CONTROL_RE, " ");
+    // JSON string escaping without the quotes: valid inside a JSON string and a YAML double-quoted
+    // scalar, whatever the value holds
+    return JSON.stringify(value).slice(1, -1);
+}
+/**
+ * Renders a guide text: each `{{name}}` with a value in `values` is replaced by it, escaped for
+ * `language` (`yaml` / `json`: JSON-string-escaped without quotes, so a placeholder inside double
+ * quotes stays one string; `text`: control characters become spaces). A placeholder whose value is
+ * null or undefined stays as written and is listed in `unresolved` when `known` holds it; one not
+ * in `known` stays as written and is not listed. Never runs code; deterministic.
+ */
+export function renderSetupGuideText(text, values, language, known = Object.keys(values)) {
+    const unresolved = [];
+    const out = text.replace(PLACEHOLDER_RE, (whole, name) => {
+        if (!known.includes(name))
+            return whole;
+        const v = Object.hasOwn(values, name) ? values[name] : undefined;
+        if (v === null || v === undefined) {
+            if (!unresolved.includes(name))
+                unresolved.push(name);
+            return whole;
+        }
+        return escapeValue(v, language);
+    });
+    return { text: out, unresolved };
+}
+/**
+ * Whether a guide's template file is usable: present, at most {@link SETUP_GUIDE_LIMITS}`.fileBytes`,
+ * valid UTF-8 text without NUL. The problem (English, naming the path), or undefined when it is.
+ * Shared by the packer and the kernel's package reader.
+ */
+export function setupGuideFileProblem(path, data) {
+    if (data === undefined)
+        return `${path} not found in the package`;
+    if (data.byteLength > SETUP_GUIDE_LIMITS.fileBytes) {
+        return `${path} is larger than ${SETUP_GUIDE_LIMITS.fileBytes} bytes`;
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return `${path} is not valid UTF-8 text`;
+    }
+    return text.includes("\u0000") ? `${path} is not a text file (it contains NUL)` : undefined;
+}

package/dist/theme-assets.d.ts

@@ -0,0 +1,39 @@
+import { type ParsedTheme } from "./theme.js";
+/**
+ * Parses a logo SVG (UTF-8, ≤ {@link THEME_LIMITS}`.svgBytes`) with a strict, namespace-aware
+ * XML parser and re-serializes it. The root must be an `svg` element in the SVG namespace with a
+ * numeric `viewBox`; its `width`, `height` and `class` are dropped. Rejected: a DOCTYPE (and so
+ * any entity declaration), processing instructions, a non-UTF-8 encoding, elements outside the
+ * SVG allowlist (`script`, `foreignObject`, `style`, …) or in the XHTML namespace, `style` and
+ * `on*` attributes, `href` / `xlink:href` not starting with `#`, `javascript:` / `vbscript:` in
+ * any value, quotes or a backslash in attribute values, any function other than `url(#id)`, colors
+ * (`rgb`, `rgba`, `hsl`, `hsla`) and transforms (`translate`, `rotate`, `scale`, `matrix`,
+ * `skewX`, `skewY`), a viewBox longer than 128 characters, and animation of `href`, `style` or event
+ * handlers. Comments, the XML declaration and elements / attributes in other namespaces (editor
+ * metadata) are dropped; CDATA becomes escaped text. Never throws.
+ */
+export declare function sanitizeThemeSvg(bytes: Uint8Array): {
+    svg: string;
+} | {
+    error: string;
+};
+/** A woff2 font: the `wOF2` signature and at most {@link THEME_LIMITS}`.fontBytes`. */
+export declare function checkWoff2(bytes: Uint8Array): string | undefined;
+/**
+ * A PNG logo: the PNG signature, an `IHDR` first chunk with a height of at least
+ * {@link THEME_LIMITS}`.pngMinHeight` pixels, and at most {@link THEME_LIMITS}`.pngBytes`.
+ */
+export declare function checkPng(bytes: Uint8Array): string | undefined;
+/**
+ * Resolves and checks the asset files of a parsed theme: each `fonts[].file` ({@link checkWoff2})
+ * and `logo.mark` / `logo.favicon` (`.svg` through {@link sanitizeThemeSvg}, `.png` through
+ * {@link checkPng}); the favicon must be square (SVG viewBox or PNG width = height). `files` holds the plugin's files keyed by their path without a leading
+ * `./`; the returned `assets` (the sanitized SVG bytes, the other files unchanged) use the same
+ * keys. Errors are `<field>: <reason>`, English; the total input size of the theme's distinct
+ * assets must stay within {@link THEME_LIMITS}`.assetsBytes`. That limit is per plugin, so a
+ * caller reading several themes also checks the sum over all of them (distinct paths).
+ */
+export declare function validateThemeAssets(theme: ParsedTheme, files: Map<string, Uint8Array>): {
+    assets: Map<string, Uint8Array>;
+    errors: string[];
+};