@capybara-hq/plugin-tools 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/pack/cli.js

@@ -1,27 +1,16 @@
 import { relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { discoverPlugins } from "../discover.js";
-import { packBootstrap } from "./bootstrap.js";
-import { DEFAULT_NPM_REGISTRY } from "./npm.js";
 import { packPlugin } from "./pack.js";
-export const PACK_USAGE = "capybara-plugin pack [<dir>...] [--all <root>] [--out <dir>]\n" +
-    "       capybara-plugin pack --bootstrap <manifest> [--root <dir>] [--out <dir>] [--registry <url>]\n" +
-    "                                [--npm-token <token>]";
+export const PACK_USAGE = "capybara-plugin pack [<dir>...] [--all <root>] [--out <dir>]";
 /**
  * `capybara-plugin pack`: packs plugin directories into plugin tgz files.
  *
  * - `<dir>...`: the plugin directories to pack;
  * - `--all <root>`: also every plugin of the repository at `<root>` (`<root>/plugins/*`, or `<root>`
  *   itself when it is a plugin);
- * - `--bootstrap <manifest>`: the bootstrap directory an image bakes: every entry of the bootstrap
- *   manifest as `<name>-<version>.tgz`, checked against its pins (workspace entries' `path` is
- *   relative to `--root`, default the current directory; npm entries are downloaded from
- *   `--registry`, default `CAPYBARA_PACKAGES__NPM_REGISTRY` (the kernel's `packages.npmRegistry`)
- *   or else the public npm registry, and must match their pinned sha512; `--npm-token`, default
- *   `CAPYBARA_PACKAGES__NPM_TOKEN` (the kernel's `packages.npmToken`), is sent as a Bearer token to
- *   the registry origin only);
- * - `--out <dir>`: output directory, default `artifacts/plugins` (`artifacts/bootstrap` with
- *   `--bootstrap`) under the current directory. The last `--out` wins.
+ * - `--out <dir>`: output directory, default `artifacts/plugins` under the current directory. The
+ *   last `--out` wins.
  *
  * Relative paths resolve against `cwd` (the current directory). Returns the exit code.
  */
@@ -33,10 +22,6 @@ export async function packCommand(args, cwd) {
             help: { type: "boolean", short: "h", default: false },
             all: { type: "string" },
             out: { type: "string" },
-            bootstrap: { type: "string" },
-            root: { type: "string" },
-            registry: { type: "string" },
-            "npm-token": { type: "string" },
         },
     });
     if (values.help) {
@@ -48,28 +33,6 @@ export async function packCommand(args, cwd) {
         const rel = relative(cwd, p);
         return rel === "" ? "." : rel.startsWith("..") ? p : rel;
     };
-    if (values.bootstrap !== undefined) {
-        if (values.all !== undefined || positionals.length > 0) {
-            return usage("--bootstrap takes no plugin directory");
-        }
-        try {
-            const root = values.root === undefined ? cwd : resolve(cwd, values.root);
-            const manifest = resolve(cwd, values.bootstrap);
-            const registry = values.registry ?? (process.env.CAPYBARA_PACKAGES__NPM_REGISTRY || DEFAULT_NPM_REGISTRY);
-            const token = values["npm-token"] ?? process.env.CAPYBARA_PACKAGES__NPM_TOKEN;
-            for (const p of await packBootstrap(manifest, root, outOf("artifacts/bootstrap"), {
-                registry,
-                ...(token !== undefined && token !== "" && { token }),
-            })) {
-                console.log(`${shown(p.file)}  ${p.integrity}`);
-            }
-            return 0;
-        }
-        catch (e) {
-            console.error(e instanceof Error ? e.message : String(e));
-            return 1;
-        }
-    }
     const plugins = positionals.map((d) => resolve(cwd, d));
     if (values.all !== undefined) {
         const root = resolve(cwd, values.all);

package/dist/pack/config-schemas.d.ts

@@ -0,0 +1,34 @@
+import { type ConfigUiProblem, type ExtensionManifest, type JsonSchema } from "@capybara-hq/plugin-sdk";
+/**
+ * The config JSON Schemas an extension's package carries (extension config forms spec §4.5) and
+ * the checks the packer and `capybara-plugin check` ("Config forms") run on them.
+ */
+/** The config levels an extension declares a schema for. */
+export type ConfigSchemaLevel = "deployment" | "org";
+/** A problem of one level's schema (`path`: dot path of the node, `""` the root). */
+export interface ConfigSchemaProblem extends ConfigUiProblem {
+    level: ConfigSchemaLevel;
+}
+/** The JSON Schemas of an extension's config levels and the problems of their hints. */
+export interface ExtensionConfigSchemas {
+    schemas: {
+        deployment?: JsonSchema;
+        org?: JsonSchema;
+    };
+    problems: ConfigSchemaProblem[];
+}
+/**
+ * The JSON Schemas (`configJsonSchema`) of an extension's deployment and org config, with every
+ * problem of their hints: `validateConfigUi` at the level, plus value hints on secrets
+ * ({@link secretValueHints}). The packer refuses a plugin with problems.
+ */
+export declare function extensionConfigSchemas(config: ExtensionManifest["config"] | undefined): ExtensionConfigSchemas;
+/** `<level> config: <path>: <message>` (the root as `(root)`). */
+export declare const formatConfigSchemaProblem: (p: ConfigSchemaProblem) => string;
+/**
+ * The rendered fields of a form schema without a label in both languages (`plugin-config-labels`):
+ * every property node the form draws, in nested objects, array items and record values. A secret
+ * record named by some `x-ui.secrets[].path` is skipped (it is drawn inside each item with that
+ * hint's own label); a secret node is drawn as one input, so its own properties are not visited.
+ */
+export declare function missingConfigLabels(schema: JsonSchema): ConfigUiProblem[];

package/dist/pack/config-schemas.js

@@ -0,0 +1,151 @@
+import { configJsonSchema, validateConfigUi, } from "@capybara-hq/plugin-sdk";
+const LEVELS = ["deployment", "org"];
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Keywords whose value is data, not a schema: never recursed into. */
+const VALUE_KEYWORDS = new Set(["default", "const", "enum", "examples"]);
+/** Hints that would reveal values; `configJsonSchema` drops them under a secret. */
+const VALUE_HINTS = ["options", "presets"];
+const join = (path, seg) => (path === "" ? seg : `${path}.${seg}`);
+/**
+ * Value hints (`options`, `presets`) on a secret node or under one. `configJsonSchema` removes
+ * them before `validateConfigUi` could see them, so a plugin would ship a hint that silently does
+ * nothing; this reads the zod schema's own JSON Schema (meta `secret` / `ui` kept as written) with
+ * the schema's own zod, so plugin-tools needs no zod at run time.
+ */
+function secretValueHints(schema) {
+    const toJson = schema?.toJSONSchema;
+    if (typeof toJson !== "function")
+        return [];
+    const raw = toJson.call(schema, { io: "input", unrepresentable: "any" });
+    const out = new Map();
+    const walk = (node, path, inSecret) => {
+        if (Array.isArray(node)) {
+            for (const n of node)
+                walk(n, path, inSecret);
+            return;
+        }
+        if (!isObj(node))
+            return;
+        const secret = inSecret || node.secret === true;
+        if (secret && isObj(node.ui)) {
+            for (const k of VALUE_HINTS) {
+                if (node.ui[k] === undefined)
+                    continue;
+                const message = `x-ui.${k} on a secret field: secrets publish no values, so the form never shows them (remove ${k})`;
+                out.set(`${path}\n${message}`, { path, message });
+            }
+        }
+        for (const [k, v] of Object.entries(node)) {
+            if (k === "ui" || VALUE_KEYWORDS.has(k))
+                continue;
+            if (k === "properties" && isObj(v)) {
+                for (const [name, child] of Object.entries(v))
+                    walk(child, join(path, name), secret);
+            }
+            else if (k === "items" || k === "additionalProperties") {
+                walk(v, join(path, k), secret);
+            }
+            else {
+                walk(v, path, secret);
+            }
+        }
+    };
+    walk(raw, "", false);
+    return [...out.values()];
+}
+/**
+ * The JSON Schemas (`configJsonSchema`) of an extension's deployment and org config, with every
+ * problem of their hints: `validateConfigUi` at the level, plus value hints on secrets
+ * ({@link secretValueHints}). The packer refuses a plugin with problems.
+ */
+export function extensionConfigSchemas(config) {
+    const result = { schemas: {}, problems: [] };
+    for (const level of LEVELS) {
+        const zod = config?.[level];
+        if (zod === undefined)
+            continue;
+        const schema = configJsonSchema(zod);
+        result.schemas[level] = schema;
+        for (const p of [...validateConfigUi(schema, level), ...secretValueHints(zod)]) {
+            result.problems.push({ level, ...p });
+        }
+    }
+    return result;
+}
+/** `<level> config: <path>: <message>` (the root as `(root)`). */
+export const formatConfigSchemaProblem = (p) => `${p.level} config: ${p.path === "" ? "(root)" : p.path}: ${p.message}`;
+/** The non-null shape of a node: itself, or the one non-null branch of a nullable `anyOf`. */
+function shapeOf(node) {
+    const branches = (node.anyOf ?? node.oneOf);
+    if (node.type === undefined && Array.isArray(branches)) {
+        const rest = branches.filter((b) => isObj(b) && b.type !== "null");
+        if (rest.length === 1 && rest[0] !== undefined)
+            return rest[0];
+    }
+    return node;
+}
+const hasText = (v) => typeof v === "string" && v.trim() !== "";
+/** Does the node (or its non-null shape) carry `x-ui.label` with both zh and en? */
+function hasLabel(node) {
+    for (const n of [node, shapeOf(node)]) {
+        const label = isObj(n["x-ui"]) ? n["x-ui"].label : undefined;
+        if (isObj(label) && hasText(label.zh) && hasText(label.en))
+            return true;
+    }
+    return false;
+}
+/** Every `x-ui.secrets[].path` of a form schema (dot paths from the root). */
+function itemSecretPaths(node, out = new Set()) {
+    if (Array.isArray(node)) {
+        for (const n of node)
+            itemSecretPaths(n, out);
+        return out;
+    }
+    if (!isObj(node))
+        return out;
+    const hints = node["x-ui"];
+    if (isObj(hints) && Array.isArray(hints.secrets)) {
+        for (const s of hints.secrets)
+            if (isObj(s) && typeof s.path === "string")
+                out.add(s.path);
+    }
+    for (const [k, v] of Object.entries(node)) {
+        if (k !== "x-ui" && !VALUE_KEYWORDS.has(k))
+            itemSecretPaths(v, out);
+    }
+    return out;
+}
+/**
+ * The rendered fields of a form schema without a label in both languages (`plugin-config-labels`):
+ * every property node the form draws, in nested objects, array items and record values. A secret
+ * record named by some `x-ui.secrets[].path` is skipped (it is drawn inside each item with that
+ * hint's own label); a secret node is drawn as one input, so its own properties are not visited.
+ */
+export function missingConfigLabels(schema) {
+    const skip = itemSecretPaths(schema);
+    const out = [];
+    const visit = (node, path) => {
+        const shape = shapeOf(node);
+        if (isObj(shape.properties)) {
+            for (const [k, child] of Object.entries(shape.properties)) {
+                if (!isObj(child))
+                    continue;
+                const p = join(path, k);
+                if (skip.has(p))
+                    continue;
+                if (!hasLabel(child)) {
+                    out.push({ path: p, message: "has no label (x-ui.label with zh and en)" });
+                }
+                if (child["x-secret"] !== true)
+                    visit(child, p);
+            }
+        }
+        if (isObj(shape.items))
+            visit(shape.items, join(path, "items"));
+        if (isObj(shape.additionalProperties)) {
+            visit(shape.additionalProperties, join(path, "additionalProperties"));
+        }
+    };
+    visit(schema, "");
+    return out;
+}

package/dist/pack/index.d.ts

@@ -1,4 +1,4 @@
-export { type BootstrapPack, packBootstrap } from "./bootstrap.js";
 export { PACK_USAGE, packCommand } from "./cli.js";
+export { type ConfigSchemaLevel, type ConfigSchemaProblem, type ExtensionConfigSchemas, extensionConfigSchemas, formatConfigSchemaProblem, missingConfigLabels, } from "./config-schemas.js";
 export { assertNpmTarballLabel, DEFAULT_NPM_REGISTRY, downloadPinnedNpmPackage, fetchNpmTarball, NPM_TARBALL_MAX_BYTES, type NpmFetchOptions, NpmPackageError, type NpmPackageErrorKind, } from "./npm.js";
-export { METADATA_FIELDS, NOTICES_FILE, type PackResult, packPlugin, STAGING_PREFIX, } from "./pack.js";
+export { importPluginExtension, METADATA_FIELDS, NOTICES_FILE, type PackResult, packPlugin, STAGING_PREFIX, } from "./pack.js";

package/dist/pack/index.js

@@ -1,4 +1,4 @@
-export { packBootstrap } from "./bootstrap.js";
 export { PACK_USAGE, packCommand } from "./cli.js";
+export { extensionConfigSchemas, formatConfigSchemaProblem, missingConfigLabels, } from "./config-schemas.js";
 export { assertNpmTarballLabel, DEFAULT_NPM_REGISTRY, downloadPinnedNpmPackage, fetchNpmTarball, NPM_TARBALL_MAX_BYTES, NpmPackageError, } from "./npm.js";
-export { METADATA_FIELDS, NOTICES_FILE, packPlugin, STAGING_PREFIX, } from "./pack.js";
+export { importPluginExtension, METADATA_FIELDS, NOTICES_FILE, packPlugin, STAGING_PREFIX, } from "./pack.js";

package/dist/pack/pack.d.ts

@@ -1,4 +1,4 @@
-import { type PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type ExtensionManifest, type PluginManifest } from "@capybara-hq/plugin-sdk";
 /**
  * The result of packing: the tgz path, its hex sha256 and the `.capybara-plugin/plugin.json`
  * written into it (the extension's static manifest is `manifest.extension?.manifest`).
@@ -25,6 +25,12 @@ export declare const STAGING_PREFIX = ".capybara-pack-";
 export declare const METADATA_FIELDS: readonly ["description", "repository", "homepage", "keywords"];
 /** Third-party license notices of the bundled dependencies (written only when there are any). */
 export declare const NOTICES_FILE = "THIRD-PARTY-NOTICES.txt";
+/**
+ * The extension a plugin directory's `src/index.ts` defines, bundled and imported the way the
+ * packer does (in a `.capybara-pack-*` staging dir under the system temp dir, removed afterwards).
+ * For checks that need the module (config forms); throws what packing would throw.
+ */
+export declare function importPluginExtension(pluginDir: string): Promise<ExtensionManifest>;
 /**
  * Packs a plugin directory into a plugin package (spec §4.1):
  * 1. reads and validates the source `.capybara-plugin/plugin.json` (it must not carry
@@ -32,7 +38,7 @@ export declare const NOTICES_FILE = "THIRD-PARTY-NOTICES.txt";
  * 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,12 @@ 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, 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";
 /**
@@ -166,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",
@@ -356,13 +360,132 @@ 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,
     };
 }
+/**
+ * Bundles `src/index.ts` into `<stage>/package/dist/index.mjs` (esbuild, single-file ESM), checks
+ * the bundle's imports, imports it and runs its default export through defineExtension. Returns the
+ * bundle, the defined manifest and the bundled inputs (for the notices).
+ */
+async function buildAndImport(dir, label, stage) {
+    await linkHostPackages(dir, stage);
+    const entryOut = join(stage, "package", EXTENSION_ENTRY);
+    const result = await build({
+        absWorkingDir: dir,
+        entryPoints: [join(dir, "src/index.ts")],
+        outfile: entryOut,
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node24",
+        external: [...HOST_PROVIDED_PACKAGES],
+        plugins: [nodeBuiltins],
+        banner: { js: BANNER },
+        define: DEFINE,
+        charset: "utf8",
+        logLevel: "silent",
+        metafile: true,
+        // Notices of bundled dependencies go to THIRD-PARTY-NOTICES.txt (built from the metafile).
+        legalComments: "none",
+    });
+    if (result.errors.length > 0) {
+        throw new Error(`${label}: esbuild failed: ${result.errors.map((e) => e.text).join("; ")}`);
+    }
+    const code = await readFile(entryOut);
+    const issues = await importIssues(code.toString("utf8"));
+    if (issues.length > 0)
+        throw new Error(`${label}: ${issues.join("; ")}`);
+    const mod = await importBundle(entryOut);
+    if (typeof mod.default !== "object" || mod.default === null) {
+        throw new Error(`${label}: the bundle has no default export object`);
+    }
+    const m = defineExtension(mod.default);
+    return { code, m, inputs: Object.keys(result.metafile?.inputs ?? {}) };
+}
+/**
+ * The extension a plugin directory's `src/index.ts` defines, bundled and imported the way the
+ * packer does (in a `.capybara-pack-*` staging dir under the system temp dir, removed afterwards).
+ * For checks that need the module (config forms); throws what packing would throw.
+ */
+export async function importPluginExtension(pluginDir) {
+    const dir = resolve(pluginDir);
+    const stage = await realpath(await mkdtemp(join(tmpdir(), STAGING_PREFIX)));
+    try {
+        return (await buildAndImport(dir, dir, stage)).m;
+    }
+    finally {
+        await rm(stage, { recursive: true, force: true });
+    }
+}
 /**
  * Bundles the extension `src/index.ts`:
  * 1. esbuild bundles it into the single-file ESM `dist/index.mjs` (platform node, target node24),
@@ -371,6 +494,8 @@ async function contentFiles(dir, label, m) {
  * 2. the bundle's imports are checked (allowlist, no non-literal dynamic import), the bundle is
  *    imported and its default export goes through defineExtension; `staticManifestOf` gives the
  *    static manifest, whose version must equal the package.json version;
+ *    the config schemas become `extension.configSchemas` (`configJsonSchema`; refused when their
+ *    hints have problems, {@link extensionConfigSchemas});
  * 3. `migrations/` (when the manifest declares migrations, which must resolve to the plugin's
  *    `migrations/`), `ui/` (when present) and THIRD-PARTY-NOTICES.txt join the files.
  *
@@ -379,41 +504,14 @@ async function contentFiles(dir, label, m) {
 async function bundleExtension(dir, label, pkgVersion) {
     const stage = await realpath(await mkdtemp(join(tmpdir(), STAGING_PREFIX)));
     try {
-        await linkHostPackages(dir, stage);
-        const entryOut = join(stage, "package", EXTENSION_ENTRY);
-        const result = await build({
-            absWorkingDir: dir,
-            entryPoints: [join(dir, "src/index.ts")],
-            outfile: entryOut,
-            bundle: true,
-            platform: "node",
-            format: "esm",
-            target: "node24",
-            external: [...HOST_PROVIDED_PACKAGES],
-            plugins: [nodeBuiltins],
-            banner: { js: BANNER },
-            define: DEFINE,
-            charset: "utf8",
-            logLevel: "silent",
-            metafile: true,
-            // Notices of bundled dependencies go to THIRD-PARTY-NOTICES.txt (built from the metafile).
-            legalComments: "none",
-        });
-        if (result.errors.length > 0) {
-            throw new Error(`${label}: esbuild failed: ${result.errors.map((e) => e.text).join("; ")}`);
-        }
-        const code = await readFile(entryOut);
-        const issues = await importIssues(code.toString("utf8"));
-        if (issues.length > 0)
-            throw new Error(`${label}: ${issues.join("; ")}`);
-        const mod = await importBundle(entryOut);
-        if (typeof mod.default !== "object" || mod.default === null) {
-            throw new Error(`${label}: the bundle has no default export object`);
-        }
-        const m = defineExtension(mod.default);
+        const { code, m, inputs } = await buildAndImport(dir, label, stage);
         if (m.version !== pkgVersion) {
             throw new Error(`${label}: manifest version ${m.version} does not match package.json version ${String(pkgVersion)}`);
         }
+        const config = extensionConfigSchemas(m.config);
+        if (config.problems.length > 0) {
+            throw new Error(`${label}: invalid config UI hints: ${config.problems.map(formatConfigSchemaProblem).join("; ")}`);
+        }
         const files = new Map([[EXTENSION_ENTRY, code]]);
         const extension = {
             entry: `./${EXTENSION_ENTRY}`,
@@ -435,7 +533,10 @@ async function bundleExtension(dir, label, pkgVersion) {
             }
             extension.ui = "./ui";
         }
-        const notices = await thirdPartyNotices(dir, Object.keys(result.metafile?.inputs ?? {}));
+        if (config.schemas.deployment !== undefined || config.schemas.org !== undefined) {
+            extension.configSchemas = config.schemas;
+        }
+        const notices = await thirdPartyNotices(dir, inputs);
         if (notices !== undefined)
             files.set(NOTICES_FILE, Buffer.from(notices));
         return { files, extension };
@@ -451,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`
@@ -467,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)
@@ -504,7 +612,15 @@ export async function packPlugin(pluginDir, outDir) {
     if (pkgIssues.length > 0)
         throw new Error(`${label}: ${pkgIssues.join("; ")}`);
     files.set("package.json", Buffer.from(`${JSON.stringify(pkg, null, 2)}\n`));
-    files.set(PLUGIN_MANIFEST_FILE, Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+    // The packed text is pretty-printed while the config schema caps measure compact JSON: the text
+    // itself must stay under the reader's limit, or the kernel would refuse the package unread.
+    const manifestText = `${JSON.stringify(manifest, null, 2)}\n`;
+    if (manifestText.length > PLUGIN_MANIFEST_LIMITS.manifestChars) {
+        throw new Error(`${label}: packed ${PLUGIN_MANIFEST_FILE} is ${manifestText.length} characters, over the ` +
+            `${PLUGIN_MANIFEST_LIMITS.manifestChars} limit (PLUGIN_MANIFEST_LIMITS.manifestChars); ` +
+            "make the config schemas smaller");
+    }
+    files.set(PLUGIN_MANIFEST_FILE, Buffer.from(manifestText));
     const tgz = await makeTgz(files);
     await mkdir(outDir, { recursive: true });
     const file = resolve(outDir, tgzName(String(srcPkg.name), String(srcPkg.version)));

package/package.json

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

package/dist/pack/bootstrap.d.ts

@@ -1,25 +0,0 @@
-import { type NpmFetchOptions } from "./npm.js";
-/** One package {@link packBootstrap} wrote. */
-export interface BootstrapPack {
-    name: string;
-    version: string;
-    file: string;
-    integrity: string;
-}
-/**
- * Produces the bootstrap directory the image bakes (package ecosystem spec §7): every entry of the
- * bootstrap manifest (`packages/kernel/bootstrap.json`) as `<outDir>/<name>-<version>.tgz`. A
- * `source: "workspace"` entry is packed from `<repoRoot>/<path>` with {@link packPlugin}
- * (byte-reproducible) and must equal the entry: the plugin name, the version and the pinned sha512,
- * otherwise this throws naming the plugin and writes nothing for it (the image build fails rather
- * than baking a package `capybara bootstrap` would refuse). A `source: "npm"` entry is downloaded
- * from `opts.registry` (default the public npm registry, the kernel's `packages.npmRegistry`
- * default; `opts.token` goes to the registry origin only) and written only when its bytes match
- * the pinned sha512 and its package.json names the entry's package and version; a tampered,
- * mislabelled or oversized (`bootstrap.too_large`) tarball or an unpublished package or version
- * throws naming the plugin. So npm entries need the network at
- * build time only: init installs from the baked directory and never downloads.
- */
-export declare function packBootstrap(manifestFile: string, repoRoot: string, outDir: string, opts?: {
-    registry?: string;
-} & NpmFetchOptions): Promise<BootstrapPack[]>;