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

package/dist/theme.js

@@ -0,0 +1,392 @@
+import { z } from "zod";
+import { CATALOG_ITEM_NAME_RE, isSafePackagePath } from "./plugin-package.js";
+import { checkThemeReadability } from "./theme-readability.js";
+import { THEME_OVERRIDABLE, THEME_TOKENS } from "./theme-tokens.generated.js";
+/**
+ * A theme file `themes/<id>.json` (themes spec §4): a partial override of the design tokens per
+ * scheme, optional fonts and an optional logo. The id is the file's base name
+ * ({@link themeIdOf}, `CATALOG_ITEM_NAME_RE`).
+ *
+ * {@link parseThemeFile} is the CSS-injection boundary: every token value is parsed against the
+ * grammar `tokens.json` uses (`#RRGGBB`, `rgba(r,g,b,a)`, shadows `<x> <y> <blur> [<spread>]
+ * <color>`) and re-rendered from its parts in canonical form. Asset paths (`fonts[].file`,
+ * `logo.*`) are relative to the plugin root (an optional leading `./`) and every segment is limited
+ * to `[A-Za-z0-9._-]`, so they need no escaping inside `url(...)`. Font families are limited to
+ * letters, digits, spaces and `-`. Free text (`name`, `description`, `logo.wordmark`) carries no
+ * control, format, line / paragraph separator or lone surrogate characters; it is text for the UI,
+ * never CSS. Whether the files exist and their size / signature / SVG rules are checked by
+ * the reader of the package, with {@link THEME_LIMITS}.
+ *
+ * The committed JSON Schema (`schemas/theme.v1.schema.json`) is generated from
+ * {@link ThemeFileSchema} (the shape only) by `pnpm gen:package-schemas`; token names, value
+ * grammar, path safety and readability are decided only by {@link parseThemeFile}.
+ */
+/** Limits of theme files and their assets. */
+export const THEME_LIMITS = {
+    /** UTF-8 bytes of one theme file. */
+    fileBytes: 64 * 1024,
+    /** Themes per plugin. */
+    perPlugin: 10,
+    /** Total bytes of a plugin's theme assets (fonts and logos). */
+    assetsBytes: 16 * 1024 * 1024,
+    /** Fonts per theme. */
+    fonts: 8,
+    /** Bytes of one woff2 font. */
+    fontBytes: 2 * 1024 * 1024,
+    /** Bytes of a logo SVG. */
+    svgBytes: 128 * 1024,
+    /** Bytes of a logo PNG. */
+    pngBytes: 256 * 1024,
+    /** Minimum pixel height of a logo PNG. */
+    pngMinHeight: 64,
+    /** Characters of the wordmark. */
+    wordmark: 24,
+};
+/** `themes/night-city.json` → `night-city`. */
+export function themeIdOf(path) {
+    return (path.split("/").pop() ?? "").replace(/\.json$/, "");
+}
+const MAX_ERRORS = 50;
+const FAMILY_RE = /^[A-Za-z0-9 -]{1,64}$/;
+/** Control, format, line / paragraph separator and lone surrogate characters. */
+const FORBIDDEN_CHARS_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/u;
+const PATH_SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+const FORBIDDEN_CHARS_MESSAGE = "must not contain control, format, line / paragraph separator or lone surrogate characters";
+const IMAGE_RE = /\.(?:svg|png)$/i;
+const MAX_VALUE_CHARS = 256;
+const text = (max, what) => z
+    .string()
+    .min(1)
+    .max(max)
+    .regex(/\S/, { message: `${what} must not be blank` })
+    .refine((t) => !FORBIDDEN_CHARS_RE.test(t), { message: `${what} ${FORBIDDEN_CHARS_MESSAGE}` });
+/** A plugin-root relative path (optional `./`), each segment `[A-Za-z0-9._-]`, no `.` / `..`. */
+const isPlainAssetPath = (p) => {
+    const rest = p.replace(/^\.\//, "");
+    return (isSafePackagePath(rest) &&
+        rest.split("/").every((seg) => PATH_SEGMENT_RE.test(seg) && seg !== "." && seg !== ".."));
+};
+const assetPath = (what, ext, kind) => z
+    .string()
+    .max(512)
+    .refine((p) => isPlainAssetPath(p) && ext.test(p), {
+    message: `${what} must be a relative ${kind} path inside the plugin, each segment of letters, digits, ".", "_" or "-"`,
+});
+const tokenValues = z.record(z.string().max(64), z.string().max(MAX_VALUE_CHARS));
+const radius = z.number().int().min(0).max(16);
+const schemeOverride = z.strictObject({
+    color: tokenValues.optional(),
+    shadow: tokenValues.optional(),
+    radius: z
+        .strictObject({ sm: radius.optional(), md: radius.optional(), bubble: radius.optional() })
+        .optional(),
+});
+const shape = z.strictObject({
+    $schema: z.string().max(512).optional(),
+    name: z.strictObject({ zh: text(100, "name.zh"), en: text(100, "name.en") }),
+    description: z
+        .strictObject({
+        en: text(1024, "description.en"),
+        zh: text(1024, "description.zh").optional(),
+    })
+        .optional(),
+    schemes: z
+        .strictObject({ dark: schemeOverride.optional(), light: schemeOverride.optional() })
+        .refine((s) => s.dark !== undefined || s.light !== undefined, {
+        message: "schemes must define dark, light or both",
+    }),
+    fonts: z
+        .array(z.strictObject({
+        family: z.string().regex(FAMILY_RE, {
+            message: "family must be 1-64 letters, digits, spaces or '-'",
+        }),
+        file: assetPath("file", /\.woff2$/i, ".woff2"),
+        weight: z.number().int().min(100).max(900),
+        style: z.enum(["normal", "italic"]).optional(),
+        role: z.enum(["prose", "mono"]),
+    }))
+        .max(THEME_LIMITS.fonts)
+        .optional(),
+    logo: z
+        .strictObject({
+        mark: assetPath("mark", IMAGE_RE, ".svg or .png").optional(),
+        wordmark: z
+            .string()
+            .regex(/\S/, { message: "wordmark must not be blank" })
+            .refine((w) => [...w].length <= THEME_LIMITS.wordmark, {
+            message: `wordmark must be at most ${THEME_LIMITS.wordmark} characters`,
+        })
+            .refine((w) => !FORBIDDEN_CHARS_RE.test(w), {
+            message: `wordmark ${FORBIDDEN_CHARS_MESSAGE}`,
+        })
+            .optional(),
+        favicon: assetPath("favicon", IMAGE_RE, ".svg or .png").optional(),
+    })
+        .optional(),
+});
+/**
+ * The zod schema of a theme file's shape (strict objects). Token names and values are only
+ * strings here; see {@link parseThemeFile}. The JSON Schema is generated with
+ * `z.toJSONSchema(ThemeFileSchema, { io: "input" })`.
+ */
+export const ThemeFileSchema = shape;
+const HEX_RE = /^#([0-9A-Fa-f]{6})$/;
+const RGBA_RE = /^rgba\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(0|1|0?\.\d{1,4})\s*\)$/;
+const LENGTH_RE = /^(-?)(\d{1,3})(px)?$/;
+/** `#RRGGBB` uppercase or `rgba(r,g,b,a)` rendered from its parts; undefined outside the grammar. */
+function parseColor(v) {
+    const hex = HEX_RE.exec(v);
+    if (hex)
+        return `#${hex[1].toUpperCase()}`;
+    const m = RGBA_RE.exec(v);
+    if (!m)
+        return undefined;
+    const ch = [m[1], m[2], m[3]].map(Number);
+    if (ch.some((c) => c > 255))
+        return undefined;
+    return `rgba(${ch.join(",")},${String(Number(m[4]))})`;
+}
+/** A shadow length: `0` or `<n>px` (unitless only for 0), rendered as `0` / `<n>px`. */
+function parseLength(v, allowNegative) {
+    const m = LENGTH_RE.exec(v);
+    if (!m)
+        return undefined;
+    const n = Number(m[2]);
+    if (n !== 0 && m[3] === undefined)
+        return undefined;
+    if (n === 0)
+        return "0";
+    if (m[1] === "-" && !allowNegative)
+        return undefined;
+    return `${m[1]}${n}px`;
+}
+/** `<x> <y> <blur> [<spread>] <color>`, rendered canonically; undefined outside the grammar. */
+function parseShadow(v) {
+    const s = v.trim();
+    const at = s.endsWith(")") ? s.lastIndexOf("rgba(") : s.lastIndexOf(" ") + 1;
+    if (at <= 0 || !/\s/.test(s.charAt(at - 1)))
+        return undefined;
+    const color = parseColor(s.slice(at));
+    const lengths = s.slice(0, at).trim().split(/\s+/);
+    if (color === undefined || lengths.length < 3 || lengths.length > 4)
+        return undefined;
+    // x, y and spread may be negative; blur may not.
+    const parts = lengths.map((l, i) => parseLength(l, i !== 2));
+    if (parts.some((p) => p === undefined))
+        return undefined;
+    return `${parts.join(" ")} ${color}`;
+}
+const SCHEMES = ["dark", "light"];
+const OVERRIDABLE = {
+    color: new Set(THEME_OVERRIDABLE.color),
+    shadow: new Set(THEME_OVERRIDABLE.shadow),
+};
+const GRAMMAR = {
+    color: { parse: parseColor, form: "#RRGGBB or rgba(r,g,b,a)" },
+    shadow: {
+        parse: parseShadow,
+        form: "<x> <y> <blur> [<spread>] <color> with px lengths and a #RRGGBB or rgba(r,g,b,a) color",
+    },
+};
+/**
+ * The canonical form of a token value under the grammar of `group` (the one {@link parseThemeFile}
+ * applies), or undefined when `value` is not a string within it. For readers of stored themes that
+ * emit values again (the kernel's stylesheet, themes spec §8): a stored value is re-validated
+ * before it reaches CSS, so a changed database row cannot inject CSS.
+ */
+export function canonicalThemeValue(group, value) {
+    if (typeof value !== "string" || value.length > MAX_VALUE_CHARS)
+        return undefined;
+    return GRAMMAR[group].parse(value);
+}
+/** Whether `v` is a font family a theme may name: 1-64 letters, digits, spaces or `-`. */
+export function isThemeFontFamily(v) {
+    return typeof v === "string" && FAMILY_RE.test(v);
+}
+/**
+ * Whether `v` is an asset path a theme may name: plugin-root relative (an optional leading `./`),
+ * every segment of `[A-Za-z0-9._-]`, no `.` / `..` segments (the extension is not checked).
+ */
+export function isThemeAssetPath(v) {
+    return typeof v === "string" && v.length <= 512 && isPlainAssetPath(v);
+}
+/**
+ * Each scheme the theme defines, merged onto the current built-in values (for swatches, the
+ * readability check and anything else that needs full values). A stored theme is read leniently:
+ * an override whose token name the built-in tokens no longer know (renamed in core), that is not
+ * overridable, or whose value falls outside the grammar is skipped, as the stylesheet skips it.
+ */
+export function mergeThemeSchemes(theme) {
+    const out = {};
+    const schemes = theme?.schemes;
+    if (schemes === null || typeof schemes !== "object")
+        return out;
+    for (const scheme of SCHEMES) {
+        const over = schemes[scheme];
+        if (over === null || typeof over !== "object")
+            continue;
+        const m = builtIn(scheme);
+        for (const group of ["color", "shadow"]) {
+            const values = over[group];
+            if (values === null || typeof values !== "object")
+                continue;
+            for (const [name, raw] of Object.entries(values)) {
+                if (!OVERRIDABLE[group].has(name))
+                    continue;
+                const v = canonicalThemeValue(group, raw);
+                if (v !== undefined)
+                    m[group][name] = v;
+            }
+        }
+        const radii = over.radius;
+        if (radii !== null && typeof radii === "object") {
+            for (const key of ["sm", "md", "bubble"]) {
+                const v = radii[key];
+                if (Number.isInteger(v) && v >= 0 && v <= 16) {
+                    m.radius[key] = v;
+                }
+            }
+        }
+        out[scheme] = m;
+    }
+    return out;
+}
+/** The built-in values of one scheme. */
+function builtIn(scheme) {
+    const pick = (group) => Object.fromEntries(Object.entries(group).map(([n, v]) => [n, v[scheme]]));
+    return {
+        color: pick(THEME_TOKENS.color),
+        shadow: pick(THEME_TOKENS.shadow),
+        radius: { ...THEME_TOKENS.radius },
+    };
+}
+function readJson(json) {
+    let text;
+    if (typeof json === "string") {
+        text = json;
+    }
+    else {
+        // An already parsed value is measured by its JSON serialization.
+        try {
+            text = JSON.stringify(json) ?? "";
+        }
+        catch {
+            return { errors: ["theme file must be a JSON object"] };
+        }
+    }
+    if (new TextEncoder().encode(text).length > THEME_LIMITS.fileBytes) {
+        return { errors: [`theme file is larger than ${THEME_LIMITS.fileBytes} bytes`] };
+    }
+    if (typeof json !== "string")
+        return { value: json };
+    try {
+        return { value: JSON.parse(json.startsWith("\uFEFF") ? json.slice(1) : json) };
+    }
+    catch (e) {
+        const first = (e instanceof Error ? e.message : String(e)).split("\n")[0];
+        return { errors: [`theme file is not valid JSON: ${first}`] };
+    }
+}
+/**
+ * Parses and validates a theme file: the parsed JSON value or the file text (larger than
+ * {@link THEME_LIMITS}`.fileBytes`, measured as text or as the value's JSON, is refused). Checks the id, the shape, token names against
+ * the generated allowlist (an unknown or non-overridable name is an error), the value grammar,
+ * fonts and logo; then (unless `options.readability` is false) merges every defined scheme onto
+ * the built-in tokens ({@link mergeThemeSchemes}) and reports each readability issue as an error
+ * starting `unreadable:`. Returned values are canonical (uppercase
+ * hex, rgba and shadows re-rendered from their parts). Invalid input returns `{ errors }`
+ * (`<path>: <reason>`, English, at most 50); never throws.
+ */
+export function parseThemeFile(id, json, options = {}) {
+    if (!CATALOG_ITEM_NAME_RE.test(id)) {
+        return { errors: [`theme id "${id}" must match ^[a-z0-9][a-z0-9-]{0,63}$`] };
+    }
+    const read = readJson(json);
+    if ("errors" in read)
+        return read;
+    const data = read.value;
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        return { errors: ["theme file must be a JSON object"] };
+    }
+    const r = shape.safeParse(data);
+    if (!r.success) {
+        return {
+            errors: r.error.issues.slice(0, MAX_ERRORS).map((i) => {
+                const path = i.path.map(String).join(".");
+                return path ? `${path}: ${i.message}` : i.message;
+            }),
+        };
+    }
+    const file = r.data;
+    const errors = [];
+    const seenFonts = new Set();
+    file.fonts?.forEach((f, i) => {
+        const key = `${f.family.toLowerCase()}|${f.weight}|${f.style ?? "normal"}|${f.role}`;
+        if (seenFonts.has(key)) {
+            errors.push(`fonts.${i}: duplicate font ${f.family} ${f.weight} ${f.style ?? "normal"} (${f.role})`);
+        }
+        seenFonts.add(key);
+    });
+    const schemes = {};
+    for (const scheme of SCHEMES) {
+        const over = file.schemes[scheme];
+        if (over === undefined)
+            continue;
+        const out = {};
+        // Token names come from the raw object's own keys: the zod record drops `__proto__`.
+        const rawScheme = data.schemes[scheme];
+        for (const group of ["color", "shadow"]) {
+            const values = over[group];
+            if (values === undefined)
+                continue;
+            const rawGroup = rawScheme?.[group];
+            const names = rawGroup !== null && typeof rawGroup === "object" ? Object.keys(rawGroup) : [];
+            const canonical = {};
+            for (const name of names) {
+                const path = `schemes.${scheme}.${group}.${name}`;
+                if (!OVERRIDABLE[group].has(name)) {
+                    errors.push(Object.hasOwn(THEME_TOKENS[group], name)
+                        ? `${path}: token ${group}.${name} is not overridable`
+                        : `${path}: unknown token ${group}.${name}`);
+                    continue;
+                }
+                const raw = values[name];
+                const v = raw === undefined ? undefined : GRAMMAR[group].parse(raw);
+                if (v === undefined) {
+                    errors.push(`${path}: must be ${GRAMMAR[group].form}`);
+                    continue;
+                }
+                canonical[name] = v;
+            }
+            out[group] = canonical;
+        }
+        if (over.radius !== undefined)
+            out.radius = { ...over.radius };
+        schemes[scheme] = out;
+    }
+    if (errors.length > 0)
+        return { errors: errors.slice(0, MAX_ERRORS) };
+    const merged = options.readability === false ? {} : mergeThemeSchemes({ schemes });
+    for (const scheme of SCHEMES) {
+        const m = merged[scheme];
+        if (m === undefined)
+            continue;
+        for (const issue of checkThemeReadability(scheme, m)) {
+            errors.push(issue.kind === "unevaluable"
+                ? `unreadable: schemes.${scheme}: ${issue.pair} has a value the check cannot evaluate`
+                : issue.kind === "separation-order"
+                    ? `unreadable: schemes.${scheme}: ${issue.pair} must stand further from the surface than hover (${issue.ratio.toFixed(1)} ≤ ${issue.floor.toFixed(1)})`
+                    : `unreadable: schemes.${scheme}: ${issue.pair} ${issue.kind} ${issue.ratio.toFixed(2)} is below ${issue.floor}${issue.detail === undefined ? "" : ` (${issue.detail})`}`);
+        }
+    }
+    if (errors.length > 0)
+        return { errors: errors.slice(0, MAX_ERRORS) };
+    const defined = SCHEMES.filter((s) => schemes[s] !== undefined);
+    const { $schema: _schema, ...rest } = file;
+    return {
+        ...rest,
+        schemes,
+        id,
+        singleScheme: defined.length === 1 ? defined[0] : null,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.8",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {
@@ -29,6 +29,7 @@
   ],
   "dependencies": {
     "kysely": "^0.29.6",
+    "saxes": "6.0.0",
     "semver": "^7.8.5",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"

package/schemas/connector-template.v1.schema.json

@@ -36,6 +36,9 @@
       "type": "string",
       "maxLength": 512
     },
+    "defaultEnabled": {
+      "type": "boolean"
+    },
     "template": {
       "type": "object",
       "properties": {

package/schemas/marketplace.v1.schema.json

@@ -129,6 +129,20 @@
             "maxLength": 2000,
             "pattern": "^https:\\/\\/\\S+$"
           },
+          "icon": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 2000,
+                "pattern": "^https:\\/\\/[^\\s?#]+\\.(?:[sS][vV][gG]|[pP][nN][gG])(?:\\?[^\\s#]*)?$"
+              },
+              {
+                "type": "string",
+                "maxLength": 512,
+                "pattern": "^\\.\\/[^\\s?#]+\\.(?:[sS][vV][gG]|[pP][nN][gG])$"
+              }
+            ]
+          },
           "deprecated": {
             "anyOf": [
               {

package/schemas/plugin.v1.schema.json

@@ -194,6 +194,161 @@
         "additionalProperties": false
       }
     },
+    "themes": {
+      "maxItems": 10,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 512,
+            "pattern": "^\\.\\/"
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "setupGuides": {
+      "maxItems": 8,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+          },
+          "place": {
+            "type": "string",
+            "enum": [
+              "channel-connection"
+            ]
+          },
+          "title": {
+            "type": "object",
+            "properties": {
+              "en": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100,
+                "pattern": "\\S"
+              },
+              "zh": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100,
+                "pattern": "\\S"
+              }
+            },
+            "required": [
+              "en"
+            ],
+            "additionalProperties": false
+          },
+          "steps": {
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "en": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 2000,
+                  "pattern": "\\S"
+                },
+                "zh": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 2000,
+                  "pattern": "\\S"
+                },
+                "mode": {
+                  "type": "string",
+                  "maxLength": 64
+                }
+              },
+              "required": [
+                "en"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "files": {
+            "maxItems": 8,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 3,
+                  "maxLength": 512,
+                  "allOf": [
+                    {
+                      "pattern": "^\\.\\/"
+                    },
+                    {
+                      "pattern": "\\.(?:tmpl|ya?ml|json|txt)$"
+                    }
+                  ]
+                },
+                "title": {
+                  "type": "object",
+                  "properties": {
+                    "en": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 100,
+                      "pattern": "\\S"
+                    },
+                    "zh": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 100,
+                      "pattern": "\\S"
+                    }
+                  },
+                  "required": [
+                    "en"
+                  ],
+                  "additionalProperties": false
+                },
+                "language": {
+                  "type": "string",
+                  "enum": [
+                    "yaml",
+                    "json",
+                    "text"
+                  ]
+                },
+                "mode": {
+                  "type": "string",
+                  "maxLength": 64
+                }
+              },
+              "required": [
+                "path",
+                "title",
+                "language"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "place",
+          "title"
+        ],
+        "additionalProperties": false
+      }
+    },
     "extension": {
       "type": "object",
       "properties": {