@capybara-hq/plugin-tools 0.1.0-rc.8 → 0.1.0-rc.9

package/dist/check/run.js

@@ -10,6 +10,7 @@ import { checkPluginToolKeys } from "./plugin-tool-keys.js";
 import { checkPluginReleaseMetadata } from "./release-metadata.js";
 import { printCheck } from "./report.js";
 import { checkPluginTestImports } from "./test-imports.js";
+import { checkThemes } from "./themes.js";
 import { checkToolDesign } from "./tool-design.js";
 /**
  * Every plugin-scoped check over `scope`, in the order `capybara-plugin check` and core's `pnpm
@@ -34,6 +35,7 @@ export function pluginChecks(scope) {
         { name: "Plugin pack", run: () => checkPluginPack(plugins) },
         { name: "Config forms", run: () => checkConfigForms(plugins) },
         { name: "Org override", run: () => checkOrgOverride(plugins) },
+        { name: "Themes", run: () => checkThemes(plugins) },
         {
             name: "Tool design",
             run: () => checkToolDesign([...(scope.toolDesignDirs ?? []), ...plugins]),

package/dist/check/themes.d.ts

@@ -0,0 +1,19 @@
+import { type ParsedTheme } from "@capybara-hq/plugin-sdk";
+import type { Finding } from "./source.js";
+/** The theme paths of a plugin (relative, no leading `./`): `manifest.themes`, else `themes/*.json`. */
+export declare function themePathsOf(dir: string): {
+    paths: string[];
+    listed: boolean;
+};
+/**
+ * The theme checks of a plugin (spec §4-§5), reading `manifest.themes` or `themes/*.json`:
+ * - `theme-invalid`: a theme file that is missing, over the size limit, not JSON or rejected by
+ *   `parseThemeFile`, or more themes than {@link THEME_LIMITS}`.perPlugin`;
+ * - `theme-readability`: a theme whose merged scheme fails the readability pairs (`unreadable:`);
+ * - `theme-asset`: a font or logo that is missing or invalid (`validateThemeAssets`), and the sum
+ *   of the distinct asset sizes over all of the plugin's themes above
+ *   {@link THEME_LIMITS}`.assetsBytes` (the limit is per plugin; the SDK checks one theme).
+ */
+export declare function checkThemes(pluginDirs: string[]): Finding[];
+/** The asset paths a parsed theme references (fonts, logo mark and favicon). */
+export declare function assetRefs(theme: ParsedTheme): string[];

package/dist/check/themes.js

@@ -0,0 +1,112 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, posix } from "node:path";
+import { PLUGIN_MANIFEST_FILE, parseThemeFile, THEME_LIMITS, themeIdOf, validateThemeAssets, } from "@capybara-hq/plugin-sdk";
+const stripDot = (p) => p.replace(/^\.\//, "");
+/** The theme paths of a plugin (relative, no leading `./`): `manifest.themes`, else `themes/*.json`. */
+export function themePathsOf(dir) {
+    let listed;
+    try {
+        const m = JSON.parse(readFileSync(join(dir, PLUGIN_MANIFEST_FILE), "utf8"));
+        if (Array.isArray(m.themes)) {
+            listed = m.themes.flatMap((t) => (typeof t?.path === "string" ? [stripDot(t.path)] : []));
+        }
+    }
+    catch {
+        // a missing or broken manifest is the pack check's business
+    }
+    if (listed !== undefined)
+        return { paths: [...new Set(listed)], listed: true };
+    const root = join(dir, "themes");
+    const scanned = existsSync(root)
+        ? readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".json"))
+            .map((e) => `themes/${e.name}`)
+            .sort()
+        : [];
+    return { paths: scanned, listed: false };
+}
+/**
+ * The theme checks of a plugin (spec §4-§5), reading `manifest.themes` or `themes/*.json`:
+ * - `theme-invalid`: a theme file that is missing, over the size limit, not JSON or rejected by
+ *   `parseThemeFile`, or more themes than {@link THEME_LIMITS}`.perPlugin`;
+ * - `theme-readability`: a theme whose merged scheme fails the readability pairs (`unreadable:`);
+ * - `theme-asset`: a font or logo that is missing or invalid (`validateThemeAssets`), and the sum
+ *   of the distinct asset sizes over all of the plugin's themes above
+ *   {@link THEME_LIMITS}`.assetsBytes` (the limit is per plugin; the SDK checks one theme).
+ */
+export function checkThemes(pluginDirs) {
+    const findings = [];
+    for (const dir of pluginDirs) {
+        const { paths } = themePathsOf(dir);
+        if (paths.length === 0)
+            continue;
+        const manifest = join(dir, PLUGIN_MANIFEST_FILE);
+        if (paths.length > THEME_LIMITS.perPlugin) {
+            findings.push({
+                file: manifest,
+                line: 1,
+                rule: "theme-invalid",
+                message: `the plugin has ${paths.length} themes; at most ${THEME_LIMITS.perPlugin} are allowed`,
+            });
+        }
+        const files = new Map();
+        const sizes = new Map();
+        for (const rel of paths) {
+            const file = join(dir, rel);
+            const bad = (rule, message) => findings.push({ file, line: 1, rule, message });
+            if (!existsSync(file) || !statSync(file).isFile()) {
+                bad("theme-invalid", `theme ./${rel} does not exist`);
+                continue;
+            }
+            if (statSync(file).size > THEME_LIMITS.fileBytes) {
+                bad("theme-invalid", `theme file is larger than ${THEME_LIMITS.fileBytes} bytes`);
+                continue;
+            }
+            const r = parseThemeFile(themeIdOf(rel), readFileSync(file, "utf8"));
+            if ("errors" in r) {
+                for (const e of r.errors) {
+                    bad(e.startsWith("unreadable:") ? "theme-readability" : "theme-invalid", e);
+                }
+                continue;
+            }
+            const used = assetRefs(r);
+            for (const ref of used) {
+                const key = stripDot(ref);
+                const p = posix.normalize(key);
+                if (files.has(p) || p.startsWith("..") || p.startsWith("/"))
+                    continue;
+                const abs = join(dir, p);
+                if (existsSync(abs) && statSync(abs).isFile())
+                    files.set(p, readFileSync(abs));
+            }
+            const { errors } = validateThemeAssets(r, files);
+            for (const e of errors)
+                bad("theme-asset", e);
+            for (const ref of used) {
+                const bytes = files.get(stripDot(ref));
+                if (bytes !== undefined)
+                    sizes.set(stripDot(ref), bytes.length);
+            }
+        }
+        let total = 0;
+        for (const n of sizes.values())
+            total += n;
+        if (total > THEME_LIMITS.assetsBytes) {
+            findings.push({
+                file: manifest,
+                line: 1,
+                rule: "theme-asset",
+                message: `the plugin's theme assets are larger than ${THEME_LIMITS.assetsBytes} bytes in total (${total}); the limit covers all of the plugin's themes`,
+            });
+        }
+    }
+    return findings;
+}
+/** The asset paths a parsed theme references (fonts, logo mark and favicon). */
+export function assetRefs(theme) {
+    const refs = (theme.fonts ?? []).map((f) => f.file);
+    for (const ref of [theme.logo?.mark, theme.logo?.favicon])
+        if (ref !== undefined)
+            refs.push(ref);
+    return refs;
+}

package/dist/pack/pack.d.ts

@@ -38,7 +38,7 @@ export declare function importPluginExtension(pluginDir: string): Promise<Extens
  * 2. when `src/index.ts` exists, bundles the extension ({@link bundleExtension}) and sets
  *    `extension = { entry: "./dist/index.mjs", manifest, migrations?: "./migrations", ui?: "./ui" }`;
  *    a declarative plugin (no `src/index.ts`) runs no esbuild and creates no staging dir;
- * 3. ships `skills/**`, `connectors/*.json`, `agents/*.md` and the listed paths ({@link contentFiles}), README,
+ * 3. ships `skills/**`, `connectors/*.json`, `agents/*.md`, `themes/*.json` with their assets and the listed paths ({@link contentFiles}), README,
  *    LICENSE, NOTICE and the plain files of package.json `files` ({@link extraFiles});
  * 4. writes a package.json with only name / version / type / license / {@link METADATA_FIELDS}
  *    and, with an extension, `main` / `exports` (the entry) and peerDependencies (no `capybara`

package/dist/pack/pack.js

@@ -7,10 +7,11 @@ import { dirname, join, posix, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
-import { AGENT_TEMPLATE_LIMITS, checkEntryImports, defineExtension, HOST_PROVIDED_PACKAGES, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, SDK_VERSION, setupGuideFileProblem, staticManifestOf, unknownSetupGuidePlaceholders, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
+import { AGENT_TEMPLATE_LIMITS, checkEntryImports, defineExtension, HOST_PROVIDED_PACKAGES, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, parseThemeFile, SDK_VERSION, setupGuideFileProblem, staticManifestOf, THEME_LIMITS, themeIdOf, unknownSetupGuidePlaceholders, validatePluginPackageJsonFor, validateThemeAssets, } from "@capybara-hq/plugin-sdk";
 import { init as lexerInit, parse as lexerParse } from "es-module-lexer";
 import { build } from "esbuild";
 import { pack as tarPack } from "tar-stream";
+import { assetRefs, themePathsOf } from "../check/themes.js";
 import { extensionConfigSchemas, formatConfigSchemaProblem } from "./config-schemas.js";
 /** The extension entry the packer writes (relative to the package root). */
 const EXTENSION_ENTRY = "dist/index.mjs";
@@ -359,6 +360,43 @@ async function contentFiles(dir, label, m) {
         }
         agentNames.set(t.template.name, rel);
     }
+    // Themes: listed, else scanned from themes/*.json; each is parsed, its assets are checked and
+    // shipped (spec §4-§5), so a bad theme fails the pack before import
+    const { paths: themePaths } = themePathsOf(dir);
+    if (themePaths.length > THEME_LIMITS.perPlugin) {
+        throw new Error(`${label}: ${themePaths.length} themes; a plugin may have at most ${THEME_LIMITS.perPlugin}`);
+    }
+    const themeFiles = new Map();
+    const assetSizes = new Map();
+    for (const rel of themePaths) {
+        await addFile(rel, "theme");
+        const t = parseThemeFile(themeIdOf(rel), files.get(rel).toString("utf8"));
+        if ("errors" in t)
+            throw new Error(`${label}: ${rel}: ${t.errors.join("; ")}`);
+        for (const ref of assetRefs(t)) {
+            const key = stripDot(ref);
+            if (themeFiles.has(key))
+                continue;
+            const abs = join(dir, key);
+            if (!existsSync(abs) || !(await stat(abs)).isFile())
+                continue;
+            themeFiles.set(key, await readFile(abs));
+        }
+        const checked = validateThemeAssets(t, themeFiles);
+        if (checked.errors.length > 0) {
+            throw new Error(`${label}: ${rel}: ${checked.errors.join("; ")}`);
+        }
+        for (const key of checked.assets.keys()) {
+            files.set(key, Buffer.from(themeFiles.get(key)));
+            assetSizes.set(key, themeFiles.get(key).length);
+        }
+    }
+    let assetTotal = 0;
+    for (const n of assetSizes.values())
+        assetTotal += n;
+    if (assetTotal > THEME_LIMITS.assetsBytes) {
+        throw new Error(`${label}: theme assets are larger than ${THEME_LIMITS.assetsBytes} bytes in total (${assetTotal})`);
+    }
     // Setup guides (spec 2026-11-08-plugin-setup-guides-design.md §2): the listed template files,
     // text within the size limit, and only placeholders the place defines (the kernel leaves an
     // unknown one visible; the toolchain refuses it so a typo never ships)
@@ -390,6 +428,7 @@ async function contentFiles(dir, label, m) {
         skills: m.skills?.length ?? scannedSkills,
         templates: m.connectorTemplates?.length ?? templates.length,
         agents: agents.length,
+        themes: themePaths.length,
     };
 }
 /**
@@ -513,7 +552,7 @@ async function bundleExtension(dir, label, pkgVersion) {
  * 2. when `src/index.ts` exists, bundles the extension ({@link bundleExtension}) and sets
  *    `extension = { entry: "./dist/index.mjs", manifest, migrations?: "./migrations", ui?: "./ui" }`;
  *    a declarative plugin (no `src/index.ts`) runs no esbuild and creates no staging dir;
- * 3. ships `skills/**`, `connectors/*.json`, `agents/*.md` and the listed paths ({@link contentFiles}), README,
+ * 3. ships `skills/**`, `connectors/*.json`, `agents/*.md`, `themes/*.json` with their assets and the listed paths ({@link contentFiles}), README,
  *    LICENSE, NOTICE and the plain files of package.json `files` ({@link extraFiles});
  * 4. writes a package.json with only name / version / type / license / {@link METADATA_FIELDS}
  *    and, with an extension, `main` / `exports` (the entry) and peerDependencies (no `capybara`
@@ -529,8 +568,12 @@ export async function packPlugin(pluginDir, outDir) {
     const source = await readSourceManifest(dir, label);
     const content = await contentFiles(dir, label, source);
     const hasExtension = existsSync(join(dir, "src/index.ts"));
-    if (!hasExtension && content.skills === 0 && content.templates === 0 && content.agents === 0) {
-        throw new Error(`${label}: a plugin must contain an extension, a skill, a connector template or an agent template (src/index.ts, skills/<name>/SKILL.md, connectors/<id>.json or agents/<name>.md)`);
+    if (!hasExtension &&
+        content.skills === 0 &&
+        content.templates === 0 &&
+        content.agents === 0 &&
+        content.themes === 0) {
+        throw new Error(`${label}: a plugin must contain an extension, a skill, a connector template, an agent template or a theme (src/index.ts, skills/<name>/SKILL.md, connectors/<id>.json, agents/<name>.md or themes/<id>.json)`);
     }
     const ext = hasExtension ? await bundleExtension(dir, label, srcPkg.version) : undefined;
     if (ext === undefined && source.setupGuides?.some((g) => g.place === "channel-connection")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-tools",
-  "version": "0.1.0-rc.8",
+  "version": "0.1.0-rc.9",
   "description": "Capybara plugin toolchain: the capybara-plugin CLI to pack, check and release Capybara plugins",
   "license": "Apache-2.0",
   "repository": {
@@ -51,12 +51,12 @@
     "esbuild": "0.28.2",
     "oxc-parser": "^0.154.0",
     "tar-stream": "3.2.2",
-    "@capybara-hq/kernel": "^0.1.0-rc.10",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.7"
+    "@capybara-hq/kernel": "^0.1.0-rc.11",
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.8"
   },
   "devDependencies": {
     "zod": "^4.6.7",
-    "@capybara-hq/testing": "0.1.0-rc.10"
+    "@capybara-hq/testing": "0.1.0-rc.11"
   },
   "scripts": {
     "build": "tsc -b"