@capybara-hq/plugin-tools 0.1.0-rc.7 → 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/marketplace/cli.d.ts

@@ -16,7 +16,8 @@ export declare const MARKETPLACE_USAGE: string;
  * `--check` exits 1 on any finding that is not a warning (`marketplace-missing`,
  * `marketplace-display-stale`, `marketplace-integrity`, `marketplace-version-decrease`,
  * `marketplace-invalid`); `--write` writes each plugin's entry (replacing its other versions,
- * refreshing a listed entry's summary and displayName) and exits 1 only on `marketplace-invalid`.
+ * refreshing a listed entry's summary, displayName and icon) and exits 1 only on
+ * `marketplace-invalid`.
  * Relative paths resolve against `cwd`. Returns the exit code.
  */
 export declare function marketplaceCommand(args: string[], cwd: string): Promise<number>;

package/dist/marketplace/cli.js

@@ -22,7 +22,8 @@ export const MARKETPLACE_USAGE = "capybara-plugin marketplace --write|--check [-
  * `--check` exits 1 on any finding that is not a warning (`marketplace-missing`,
  * `marketplace-display-stale`, `marketplace-integrity`, `marketplace-version-decrease`,
  * `marketplace-invalid`); `--write` writes each plugin's entry (replacing its other versions,
- * refreshing a listed entry's summary and displayName) and exits 1 only on `marketplace-invalid`.
+ * refreshing a listed entry's summary, displayName and icon) and exits 1 only on
+ * `marketplace-invalid`.
  * Relative paths resolve against `cwd`. Returns the exit code.
  */
 export async function marketplaceCommand(args, cwd) {

package/dist/marketplace/marketplace.d.ts

@@ -28,7 +28,7 @@ export interface SyncMarketplaceResult {
     /** `name@version` of the other entries of the tree's plugins (dropped with `write`). */
     removed: string[];
     /**
-     * `name@version` of listed entries whose `summary` / `displayName` differ from plugin.json
+     * `name@version` of listed entries whose `summary` / `displayName` / `icon` differ from plugin.json
      * (rewritten with `write`; source and integrity never change).
      */
     refreshed: string[];
@@ -37,25 +37,33 @@ export interface SyncMarketplaceResult {
      * `marketplace-integrity` and `marketplace-version-decrease` (with a base, see
      * {@link SyncMarketplaceOptions.base}) and, without `write`, `marketplace-missing` (one per
      * plugin whose current version is not listed, or not as its only entry) and
-     * `marketplace-display-stale` (a listed entry's summary / displayName differ from plugin.json).
+     * `marketplace-display-stale` (a listed entry's summary / displayName / icon differ from plugin.json).
      */
     findings: Finding[];
 }
+/**
+ * The repository path of a plugin's icon: the plugin.json `icon` (relative to the plugin's
+ * directory `dir`) as `./<path from the root>` (an entry's `icon`, read at the marketplace's
+ * commit, so it follows every release without naming a tag).
+ */
+export declare function repoIconPath(root: string, dir: string, icon: string): string;
 /**
  * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing one entry
  * per public plugin, its current version (plugin component management spec §13.2, replacing the
  * one-entry-per-version rule of the package ecosystem spec §5.2). Each public plugin (not
  * `"private": true`) not listed at its version is packed reproducibly with {@link packPlugin} and
- * gets an entry `{ name, version, summary, displayName?, homepage?, permissions, source: { npm: {
- * package, version, integrity } } }` (`summary` from the plugin.json `description`, a string being
- * `en`; `displayName` copied from plugin.json; `integrity` the pack's sha512, which the release
+ * gets an entry `{ name, version, summary, displayName?, icon?, homepage?, permissions, source: {
+ * npm: { package, version, integrity } } }` (`summary` from the plugin.json `description`, a string
+ * being `en`; `displayName` copied from plugin.json; `icon` the plugin.json `icon` as a path in the
+ * repository, `./<plugin dir>/<icon>`, which a git marketplace reads at its refreshed commit;
+ * `integrity` the pack's sha512, which the release
  * then publishes byte for byte; `permissions` display only). The new entry takes the place of the
  * plugin's first entry (a version that moved), the plugin's other entries are dropped (also those
  * of a file written in the older one-entry-per-version form), and a plugin not listed yet is
  * appended. Entries of plugins not in the tree are kept. A version already listed is not packed or
  * compared: once published, its bytes are the release gate's business (`release --marketplace`),
  * so a later source or toolchain change at the same version is not a finding; only its display
- * fields (`summary`, `displayName`) are refreshed from the source plugin.json. Every other field
+ * fields (`summary`, `displayName`, `icon`) are refreshed from the source plugin.json. Every other field
  * of a kept entry stays as written, among them `deprecated`, which the maintainer sets by hand on
  * a published version's entry (not in plugin.json: that would change the packed bytes); a new
  * version's entry has none, and no rule compares it with the base. With `base`, see

package/dist/marketplace/marketplace.js

@@ -36,39 +36,60 @@ async function permissionsOf(bytes, hasExtension) {
 }
 /** An entry's version: `version`, else its npm source's. */
 const versionOf = (e) => e.version ?? ("npm" in e.source ? e.source.npm.version : undefined);
-/** The display fields of a plugin's source plugin.json; undefined when it does not parse. */
-function displayOf(json) {
+/**
+ * The repository path of a plugin's icon: the plugin.json `icon` (relative to the plugin's
+ * directory `dir`) as `./<path from the root>` (an entry's `icon`, read at the marketplace's
+ * commit, so it follows every release without naming a tag).
+ */
+export function repoIconPath(root, dir, icon) {
+    const rel = relative(root, dir).split("\\").join("/");
+    const file = icon.replace(/^\.\//, "");
+    return `./${rel === "" ? file : `${rel}/${file}`}`;
+}
+/**
+ * The display fields of a plugin's source plugin.json (`dir` its directory under `root`); undefined
+ * when it does not parse.
+ */
+function displayOf(json, root, dir) {
     const m = parsePluginManifest(json);
     if ("errors" in m)
         return undefined;
     return {
         summary: summaryOf(m.description),
         ...(m.displayName !== undefined && { displayName: m.displayName }),
+        ...(m.icon !== undefined && { icon: repoIconPath(root, dir, m.icon) }),
     };
 }
+/** The display fields after `summary`, in this order. */
+const AFTER_SUMMARY = ["displayName", "icon"];
 /**
- * `raw` with its `summary` and `displayName` set to `d` (in place, `displayName` right after
- * `summary` when it is new, removed when plugin.json has none); undefined when they already equal.
+ * `raw` with its `summary`, `displayName` and `icon` set to `d` (in place; a new `displayName` /
+ * `icon` right after `summary`, removed when plugin.json has none); undefined when they already
+ * equal.
  */
 function refreshDisplay(raw, d) {
     if (!isObj(raw))
         return undefined;
     if (canonical(raw.summary) === canonical(d.summary) &&
-        canonical(raw.displayName) === canonical(d.displayName)) {
+        AFTER_SUMMARY.every((k) => canonical(raw[k]) === canonical(d[k]))) {
         return undefined;
     }
+    const after = (out) => {
+        for (const k of AFTER_SUMMARY)
+            if (d[k] !== undefined)
+                out[k] = d[k];
+    };
     const out = {};
     for (const [k, v] of Object.entries(raw)) {
-        if (k === "displayName")
+        if (AFTER_SUMMARY.includes(k))
             continue;
         out[k] = k === "summary" ? d.summary : v;
-        if (k === "summary" && d.displayName !== undefined)
-            out.displayName = d.displayName;
+        if (k === "summary")
+            after(out);
     }
     if (!("summary" in raw)) {
         out.summary = d.summary;
-        if (d.displayName !== undefined)
-            out.displayName = d.displayName;
+        after(out);
     }
     return out;
 }
@@ -77,16 +98,18 @@ function refreshDisplay(raw, d) {
  * per public plugin, its current version (plugin component management spec §13.2, replacing the
  * one-entry-per-version rule of the package ecosystem spec §5.2). Each public plugin (not
  * `"private": true`) not listed at its version is packed reproducibly with {@link packPlugin} and
- * gets an entry `{ name, version, summary, displayName?, homepage?, permissions, source: { npm: {
- * package, version, integrity } } }` (`summary` from the plugin.json `description`, a string being
- * `en`; `displayName` copied from plugin.json; `integrity` the pack's sha512, which the release
+ * gets an entry `{ name, version, summary, displayName?, icon?, homepage?, permissions, source: {
+ * npm: { package, version, integrity } } }` (`summary` from the plugin.json `description`, a string
+ * being `en`; `displayName` copied from plugin.json; `icon` the plugin.json `icon` as a path in the
+ * repository, `./<plugin dir>/<icon>`, which a git marketplace reads at its refreshed commit;
+ * `integrity` the pack's sha512, which the release
  * then publishes byte for byte; `permissions` display only). The new entry takes the place of the
  * plugin's first entry (a version that moved), the plugin's other entries are dropped (also those
  * of a file written in the older one-entry-per-version form), and a plugin not listed yet is
  * appended. Entries of plugins not in the tree are kept. A version already listed is not packed or
  * compared: once published, its bytes are the release gate's business (`release --marketplace`),
  * so a later source or toolchain change at the same version is not a finding; only its display
- * fields (`summary`, `displayName`) are refreshed from the source plugin.json. Every other field
+ * fields (`summary`, `displayName`, `icon`) are refreshed from the source plugin.json. Every other field
  * of a kept entry stays as written, among them `deprecated`, which the maintainer sets by hand on
  * a published version's entry (not in plugin.json: that would change the packed bytes); a new
  * version's entry has none, and no rule compares it with the base. With `base`, see
@@ -150,7 +173,7 @@ export async function syncMarketplace(opts) {
             const kept = listed[0];
             /** Keeps the listed entry: drops the other versions, refreshes its display fields. */
             const keep = (raw) => {
-                const display = displayOf(source);
+                const display = displayOf(source, opts.root, dir);
                 const fresh = display === undefined ? undefined : refreshDisplay(raw, display);
                 if (dropped.length > 0 || fresh !== undefined) {
                     const entry = fresh ?? raw;
@@ -188,6 +211,9 @@ export async function syncMarketplace(opts) {
                 version: npm.version,
                 summary: summaryOf(r.manifest.description),
                 ...(r.manifest.displayName !== undefined && { displayName: r.manifest.displayName }),
+                ...(r.manifest.icon !== undefined && {
+                    icon: repoIconPath(opts.root, dir, r.manifest.icon),
+                }),
                 ...(r.manifest.homepage !== undefined && { homepage: r.manifest.homepage }),
                 permissions: await permissionsOf(bytes, r.manifest.extension !== undefined),
                 source: { npm },

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, staticManifestOf, 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";
@@ -167,6 +168,8 @@ const SHIPPED_ELSEWHERE = [
     "skills",
     "connectors",
     "agents",
+    // setup guide templates: the listed files are shipped by contentFiles
+    "guides",
     ".capybara-plugin",
     "README.md",
     "LICENSE",
@@ -357,11 +360,75 @@ 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)
+    for (const g of m.setupGuides ?? []) {
+        const at = `${label}: setupGuides ${g.id}`;
+        const unknown = (text, where) => {
+            const names = unknownSetupGuidePlaceholders(text, g.place);
+            if (names.length > 0) {
+                throw new Error(`${at}: ${where} uses ${names.map((n) => `{{${n}}}`).join(", ")}, which place ${g.place} does not define`);
+            }
+        };
+        g.steps?.forEach((step, i) => {
+            unknown(step.en, `step ${i + 1}`);
+            if (step.zh !== undefined)
+                unknown(step.zh, `step ${i + 1} (zh)`);
+        });
+        for (const f of g.files ?? []) {
+            const rel = stripDot(f.path);
+            await addFile(rel, `setup guide ${g.id} file`);
+            const data = files.get(rel);
+            const problem = setupGuideFileProblem(f.path, new Uint8Array(data));
+            if (problem !== undefined)
+                throw new Error(`${at}: ${problem}`);
+            unknown(data.toString("utf8"), f.path);
+        }
+    }
     return {
         files,
         skills: m.skills?.length ?? scannedSkills,
         templates: m.connectorTemplates?.length ?? templates.length,
         agents: agents.length,
+        themes: themePaths.length,
     };
 }
 /**
@@ -485,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`
@@ -501,10 +568,17 @@ 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")) {
+        throw new Error(`${label}: a channel-connection setup guide needs the plugin's extension to provide channel@1 (src/index.ts)`);
+    }
     const files = new Map([...(ext?.files ?? []), ...content.files]);
     const extra = await extraFiles(dir, srcPkg.files);
     for (const [path, data] of extra.files)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-tools",
-  "version": "0.1.0-rc.7",
+  "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/plugin-sdk": "^0.1.0-rc.6",
-    "@capybara-hq/kernel": "^0.1.0-rc.9"
+    "@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.9"
+    "@capybara-hq/testing": "0.1.0-rc.11"
   },
   "scripts": {
     "build": "tsc -b"