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

package/dist/check/plugin-permissions.js

@@ -115,6 +115,7 @@ function readManifest(obj, decls) {
         caps: new Set(),
         storage: false,
         models: false,
+        name: stringValue(prop(obj, "name")?.value ? resolve(prop(obj, "name")?.value, decls) : undefined),
         setup: undefined,
     };
     for (const key of ["requires", "optional", "provides"]) {
@@ -128,7 +129,11 @@ function readManifest(obj, decls) {
         m.secrets = !!secrets && resolve(secrets.value, decls).value === true;
         const storage = prop(pe, "storage");
         m.storage = !!storage && resolve(storage.value, decls).value === true;
-        m.models = !!prop(pe, "models");
+        // an empty list declares nothing (ctx.models is gated on at least one purpose)
+        const models = prop(pe, "models");
+        const me = models ? resolve(models.value, decls) : undefined;
+        m.models =
+            me !== undefined && !(me.type === "ArrayExpression" && me.elements.length === 0);
         for (const t of strings(prop(pe, "tools")?.value, decls))
             m.tools.add(t);
         for (const h of strings(prop(pe, "hooks")?.value, decls))
@@ -165,7 +170,7 @@ function readManifest(obj, decls) {
     }
     return m;
 }
-function scanSetup(f, m, decls) {
+function scanSetup(f, m, decls, onTool, onCall) {
     const out = [];
     /** 明确的违规：豁免注释不起作用。 */
     const add = (at, rule, message) => {
@@ -239,6 +244,8 @@ function scanSetup(f, m, decls) {
                 if (obj.type !== "MemberExpression" || !isCtx(obj.object))
                     return;
                 const area = memberName(obj);
+                if (area !== undefined)
+                    onCall?.(area, method);
                 if (area === "http" && method === "route") {
                     const verb = args[0] ? stringValue(resolve(args[0], decls)) : undefined;
                     const path = args[1] ? stringValue(resolve(args[1], decls)) : undefined;
@@ -253,6 +260,13 @@ function scanSetup(f, m, decls) {
                     const spec = args[0] ? resolve(args[0], decls) : undefined;
                     const nameProp = spec?.type === "ObjectExpression" ? prop(spec, "name") : undefined;
                     const name = nameProp ? stringValue(resolve(nameProp.value, decls)) : undefined;
+                    onTool?.({
+                        file: f.file,
+                        line: f.lineOf(n.start),
+                        extension: m.name,
+                        tool: name,
+                        allowed: !!findMarker(f, n)?.reason,
+                    });
                     if (name === undefined)
                         return dynamic(n, "perm-tools", "the tool name");
                     if (!m.tools.has(name)) {
@@ -302,7 +316,9 @@ function scanSetup(f, m, decls) {
                     }
                 }
                 else if (name === "models") {
-                    add(n, "perm-reserved", "ctx.models is reserved and not provided in this release; remove the access");
+                    if (!m.models) {
+                        add(n, "perm-models", "ctx.models is used but not declared; declare its purposes in permissions.models in the extension manifest");
+                    }
                 }
                 else if (name === "http" ||
                     name === "tools" ||
@@ -338,7 +354,7 @@ function scanSetup(f, m, decls) {
     }
     return out;
 }
-function scanFile(f) {
+function scanFile(f, onTool, onCall) {
     const decls = buildDecls(f);
     const out = [];
     walk(f.program, (n) => {
@@ -351,7 +367,7 @@ function scanFile(f) {
         const obj = arg ? resolve(arg, decls) : undefined;
         if (obj?.type !== "ObjectExpression")
             return;
-        out.push(...scanSetup(f, readManifest(obj, decls), decls));
+        out.push(...scanSetup(f, readManifest(obj, decls), decls, onTool, onCall));
     });
     return out;
 }
@@ -366,7 +382,9 @@ function scanFile(f) {
  * - perm-hooks: the mount point of ctx.hooks.on(mount, …) is not in permissions.hooks (the mount
  *   point must be a string literal or a same-file const, like the names below), or the options are
  *   `{ mode: "policy" }` and the mount point is not in permissions.policyHooks;
- * - perm-reserved：用了尚未提供的 ctx.models。
+ * - perm-models: ctx.models is used but permissions.models is not declared (the purposes it may use
+ *   are checked at run time);
+ * - perm-reserved: platform access that cannot be confirmed (a destructured ctx, a computed member).
  * 路由路径、工具名、能力 ref、界面 id 须是字符串字面量或本文件的 const；动态的写法报「无法静态确认」，
  * 豁免：`// capybara:allow-dynamic-permission <原因>`（行尾或紧邻上一行，原因必填）。
  * ctx 会跟踪本地别名，以及按位置传给同文件函数的参数。
@@ -390,3 +408,45 @@ export function checkPluginPermissions(pluginDirs) {
     }
     return findings;
 }
+/**
+ * Every `ctx.tools.register({ name })` of the non-test sources under `pluginDirs`, found by the
+ * same scanner as {@link checkPluginPermissions} (so it follows ctx aliases and same-file helpers).
+ * Unparseable files are skipped here; the permissions check reports them.
+ */
+export function findToolRegistrations(pluginDirs) {
+    const out = [];
+    for (const dir of pluginDirs) {
+        for (const { file, isTest } of listSourceFiles(dir)) {
+            if (isTest)
+                continue;
+            const parsed = parseFile(file);
+            if (isParseError(parsed))
+                continue;
+            scanFile(parsed, (r) => out.push(r));
+        }
+    }
+    return out.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+/**
+ * Which of `ctx.tools.register`, `ctx.ui.view|action` and `ctx.hooks.on` the non-test sources
+ * under `pluginDir` call, found by the same scanner as {@link checkPluginPermissions}.
+ */
+export function findCtxCalls(pluginDir) {
+    const out = { tools: false, ui: false, hooks: false };
+    for (const { file, isTest } of listSourceFiles(pluginDir)) {
+        if (isTest)
+            continue;
+        const parsed = parseFile(file);
+        if (isParseError(parsed))
+            continue;
+        scanFile(parsed, undefined, (area, method) => {
+            if (area === "tools" && method === "register")
+                out.tools = true;
+            else if (area === "ui" && (method === "view" || method === "action"))
+                out.ui = true;
+            else if (area === "hooks" && method === "on")
+                out.hooks = true;
+        });
+    }
+    return out;
+}

package/dist/check/plugin-tool-keys.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from "./source.js";
+export type { Finding };
+/** The model-visible key of an extension tool is `plugin__<extension>__<tool>`; 64 characters at most. */
+export declare const TOOL_KEY_PREFIX = "plugin__";
+export declare const TOOL_KEY_MAX = 64;
+/**
+ * plugin-tool-key-length: the key `plugin__<extension>__<tool>` of every `ctx.tools.register`
+ * must fit in {@link TOOL_KEY_MAX} characters (model APIs cap tool names at 64). The names must be
+ * string literals or same-file consts, as for `perm-tools`; a name that is not is reported as
+ * "cannot be confirmed statically" unless the call carries `// capybara:allow-dynamic-permission
+ * <reason>`. Scans the non-test sources under `pluginDirs`.
+ */
+export declare function checkPluginToolKeys(pluginDirs: string[]): Finding[];

package/dist/check/plugin-tool-keys.js

@@ -0,0 +1,38 @@
+import { findToolRegistrations } from "./plugin-permissions.js";
+/** The model-visible key of an extension tool is `plugin__<extension>__<tool>`; 64 characters at most. */
+export const TOOL_KEY_PREFIX = "plugin__";
+export const TOOL_KEY_MAX = 64;
+/**
+ * plugin-tool-key-length: the key `plugin__<extension>__<tool>` of every `ctx.tools.register`
+ * must fit in {@link TOOL_KEY_MAX} characters (model APIs cap tool names at 64). The names must be
+ * string literals or same-file consts, as for `perm-tools`; a name that is not is reported as
+ * "cannot be confirmed statically" unless the call carries `// capybara:allow-dynamic-permission
+ * <reason>`. Scans the non-test sources under `pluginDirs`.
+ */
+export function checkPluginToolKeys(pluginDirs) {
+    const rule = "plugin-tool-key-length";
+    const out = [];
+    for (const r of findToolRegistrations(pluginDirs)) {
+        if (r.extension === undefined || r.tool === undefined) {
+            if (r.allowed)
+                continue;
+            out.push({
+                file: r.file,
+                line: r.line,
+                rule,
+                message: `Cannot statically confirm the length of the tool key (${r.extension === undefined ? "extension name" : "tool name"} is not a literal). Use a string literal (or a same-file const), or add // capybara:allow-dynamic-permission <reason>`,
+            });
+            continue;
+        }
+        const key = `${TOOL_KEY_PREFIX}${r.extension}__${r.tool}`;
+        if (key.length > TOOL_KEY_MAX) {
+            out.push({
+                file: r.file,
+                line: r.line,
+                rule,
+                message: `Tool key "${key}" is ${key.length} characters; the limit is ${TOOL_KEY_MAX} (plugin__<extension>__<tool>). Shorten the tool name to at most ${Math.max(0, TOOL_KEY_MAX - TOOL_KEY_PREFIX.length - r.extension.length - 2)} characters or the extension name`,
+            });
+        }
+    }
+    return out;
+}

package/dist/check/release-metadata.d.ts

@@ -9,5 +9,10 @@ import type { Finding } from "./source.js";
  * has no `directory`. The `example-*` plugins must be private. The plugin tgz carries these fields
  * (`METADATA_FIELDS` of the packer); the libraries' half of the rule is core's
  * `check:release-metadata`.
+ * `release-display-name`: a published plugin's `.capybara-plugin/plugin.json` needs a
+ * `displayName` (`{ zh, en }`), the name every page shows instead of the package name.
+ * `release-description-zh` (a warning, never an error, so third-party marketplaces are not
+ * blocked): a published plugin's `description` has no `zh` (`marketplace --write` copies it into
+ * the marketplace `summary`, which the Chinese UI shows).
  */
 export declare function checkPluginReleaseMetadata(plugins: string[], root: string): Finding[];

package/dist/check/release-metadata.js

@@ -1,6 +1,29 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join, relative } from "node:path";
+import { PLUGIN_MANIFEST_FILE } from "@capybara-hq/plugin-sdk";
 const RULE = "plugin-release-metadata";
+const DISPLAY_NAME_RULE = "release-display-name";
+const DESCRIPTION_ZH_RULE = "release-description-zh";
+/**
+ * The plugin's `.capybara-plugin/plugin.json` as an object; undefined when the file is missing or
+ * not a JSON object ("Plugin pack" reports those).
+ */
+function readManifest(file) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const m = JSON.parse(readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+        return typeof m === "object" && m !== null && !Array.isArray(m)
+            ? m
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A description without a `zh` text: a string, or an object without `zh`. */
+const lacksZh = (d) => typeof d === "string" ||
+    (typeof d === "object" && d !== null && d.zh === undefined);
 const readJson = (file) => JSON.parse(readFileSync(file, "utf8"));
 /** `repository.url` of a package.json (`"repository": "<url>"` or `{ url }`). */
 function repositoryUrl(pkg) {
@@ -22,6 +45,11 @@ function repositoryUrl(pkg) {
  * has no `directory`. The `example-*` plugins must be private. The plugin tgz carries these fields
  * (`METADATA_FIELDS` of the packer); the libraries' half of the rule is core's
  * `check:release-metadata`.
+ * `release-display-name`: a published plugin's `.capybara-plugin/plugin.json` needs a
+ * `displayName` (`{ zh, en }`), the name every page shows instead of the package name.
+ * `release-description-zh` (a warning, never an error, so third-party marketplaces are not
+ * blocked): a published plugin's `description` has no `zh` (`marketplace --write` copies it into
+ * the marketplace `summary`, which the Chinese UI shows).
  */
 export function checkPluginReleaseMetadata(plugins, root) {
     const out = [];
@@ -47,6 +75,25 @@ export function checkPluginReleaseMetadata(plugins, root) {
         }
         if (typeof pkg.license !== "string")
             finding(`${label} is published and needs a "license"`);
+        const manifestFile = join(dir, PLUGIN_MANIFEST_FILE);
+        const manifest = readManifest(manifestFile);
+        if (manifest !== undefined && manifest.displayName === undefined) {
+            out.push({
+                file: manifestFile,
+                line: 1,
+                rule: DISPLAY_NAME_RULE,
+                message: `${label} is published and needs a "displayName" in ${PLUGIN_MANIFEST_FILE}: { "zh": …, "en": … }, the name pages show`,
+            });
+        }
+        if (manifest !== undefined && lacksZh(manifest.description)) {
+            out.push({
+                file: manifestFile,
+                line: 1,
+                rule: DESCRIPTION_ZH_RULE,
+                severity: "warning",
+                message: `${label} is published and its description has no zh: write "description": { "en": …, "zh": … } in ${PLUGIN_MANIFEST_FILE} (the marketplace summary the Chinese UI shows)`,
+            });
+        }
         if (typeof pkg.homepage !== "string" || !pkg.homepage.startsWith("https://")) {
             finding(`${label} is published and needs an https "homepage"`);
         }

package/dist/check/report.d.ts

@@ -1,8 +1,9 @@
-import type { Finding } from "./source.js";
+import { type Finding } from "./source.js";
 /** One finding as a line: `<file relative to root>:<line> <rule> <message>`. */
 export declare const formatFinding: (f: Finding, root: string) => string;
 /**
- * Prints the result of one check: `[name] passed`, or the finding count and one line per finding
- * (stderr). Returns whether it passed.
+ * Prints the result of one check: `[name] passed` (`passed with N warning(s)` and one line per
+ * warning when it has only warnings), or the finding count and one line per finding (stderr).
+ * Returns whether it passed (warnings do not fail it).
  */
 export declare function printCheck(name: string, findings: Finding[], root: string): boolean;

package/dist/check/report.js

@@ -1,16 +1,26 @@
 import { relative } from "node:path";
+import { errorsOf } from "./source.js";
 /** One finding as a line: `<file relative to root>:<line> <rule> <message>`. */
 export const formatFinding = (f, root) => `${relative(root, f.file) || f.file}:${f.line} ${f.rule} ${f.message}`;
 /**
- * Prints the result of one check: `[name] passed`, or the finding count and one line per finding
- * (stderr). Returns whether it passed.
+ * Prints the result of one check: `[name] passed` (`passed with N warning(s)` and one line per
+ * warning when it has only warnings), or the finding count and one line per finding (stderr).
+ * Returns whether it passed (warnings do not fail it).
  */
 export function printCheck(name, findings, root) {
+    const errors = errorsOf(findings);
     if (findings.length === 0) {
         console.log(`[${name}] passed`);
         return true;
     }
-    console.error(`[${name}] ${findings.length} finding(s)`);
+    if (errors.length === 0) {
+        console.error(`[${name}] passed with ${findings.length} warning(s)`);
+        for (const f of findings)
+            console.error(`  ${formatFinding(f, root)}`);
+        return true;
+    }
+    const warnings = findings.length - errors.length;
+    console.error(`[${name}] ${errors.length} finding(s)${warnings > 0 ? ` and ${warnings} warning(s)` : ""}`);
     for (const f of findings)
         console.error(`  ${formatFinding(f, root)}`);
     return false;

package/dist/check/run.d.ts

@@ -8,12 +8,14 @@ export interface PluginCheckScope {
     root: string;
     /**
      * Plugin directories: every check runs on each (dependency boundary, extension state,
-     * permissions, pack, tool design, test imports, release metadata, and the migrations in
+     * permissions, pack, config forms, tool design, test imports, release metadata, and the migrations in
      * `<plugin>/migrations`).
      */
     plugins: string[];
     /** Package directories held to the SDK's boundary (core: `packages/plugin-sdk`). */
     sdkDirs?: string[];
+    /** Package directories that may depend on `@capybara-hq/plugin-sdk` only (core: `packages/device`). */
+    deviceDirs?: string[];
     /** More directories the tool design rules scan (core: the kernel's builtin tools). */
     toolDesignDirs?: string[];
     /** More migration directories (core: the kernel's migrations). */

package/dist/check/run.js

@@ -1,12 +1,16 @@
 import { join } from "node:path";
+import { checkConfigForms } from "./config-forms.js";
 import { checkDeps } from "./deps.js";
 import { checkMigrations } from "./migrations.js";
+import { checkOrgOverride } from "./org-override.js";
 import { checkPluginPack } from "./plugin-pack.js";
 import { checkPluginPermissions } from "./plugin-permissions.js";
 import { checkPluginState } from "./plugin-state.js";
+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
@@ -22,14 +26,21 @@ export function pluginChecks(scope) {
                 ...plugins.map((p) => join(p, "migrations")),
             ]),
         },
-        { name: "Dependency boundary", run: () => checkDeps(plugins, scope.sdkDirs ?? []) },
+        {
+            name: "Dependency boundary",
+            run: () => checkDeps(plugins, scope.sdkDirs ?? [], scope.deviceDirs ?? []),
+        },
         { name: "Extension state", run: () => checkPluginState(plugins) },
         { name: "Extension permissions", run: () => checkPluginPermissions(plugins) },
         { 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]),
         },
+        { name: "Tool key length", run: () => checkPluginToolKeys(plugins) },
         { name: "Plugin test imports", run: () => checkPluginTestImports(plugins) },
         {
             name: "Plugin release metadata",

package/dist/check/source.d.ts

@@ -1,10 +1,17 @@
 import { type Comment } from "oxc-parser";
+/**
+ * One finding of a check. `severity: "warning"` is printed but does not fail the check (only a
+ * few rules warn, e.g. `release-description-zh`); without it the finding is an error.
+ */
 export type Finding = {
     file: string;
     line: number;
     rule: string;
     message: string;
+    severity?: "warning";
 };
+/** The findings that fail a check (every finding that is not a warning). */
+export declare const errorsOf: (findings: Finding[]) => Finding[];
 /** ESTree 节点（oxc-parser 的输出）。只声明本检查用到的公共字段。 */
 export interface Node {
     type: string;

package/dist/check/source.js

@@ -1,6 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseSync } from "oxc-parser";
+/** The findings that fail a check (every finding that is not a warning). */
+export const errorsOf = (findings) => findings.filter((f) => f.severity !== "warning");
 const SOURCE_EXT = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
 const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
 /** 只在插件根目录下才有特殊含义的目录名（更深处同名目录是普通源码目录，必须扫描）。 */

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/check/tool-design.d.ts

@@ -5,7 +5,7 @@ export type { Finding };
  * - tool-description：`ctx.tools.register(spec, …)` 与 `BuiltinTool` 字面量（有 spec 与 run）里的 spec
  *   必须有字符串字面量 description（可 `+` 拼接）、不少于 20 字符、不含中文（模型可见文案一律英文）；
  * - tool-error-actionable：`new ToolError(msg)` 的 msg 是字符串字面量 / 模板（或本文件内的常量、函数返回值），
- *   且含建议动词 use / call / retry / check / ask / pass / provide 之一，让模型知道下一步做什么。
+ *   且含建议动词 use / call / retry / check / ask / pass / provide / read 之一，让模型知道下一步做什么。
  * spec 可以直接写对象字面量，也可以引用本文件内的 const；其他写法（跨文件、动态构造）报 tool-description。
  * 已知缺口：从别的文件导入的消息常量 / 函数不追踪；非 ToolError 类的错误不查；运行时拼出的 spec 不查。
  * 扫描：传入目录下的非测试源码。

package/dist/check/tool-design.js

@@ -2,7 +2,7 @@ import { isParseError, listSourceFiles, parseFile, stringValue, walk, } from "./
 const MIN_DESCRIPTION = 20;
 const CJK = /[㐀-鿿豈-﫿　-〿＀-￯]/;
 /** 可执行的建议动词：错误信息里至少出现其一（整词、不分大小写）。 */
-const ACTION_VERB = /\b(?:use|call|retry|check|ask|pass|provide)\b/i;
+const ACTION_VERB = /\b(?:use|call|retry|check|ask|pass|provide|read)\b/i;
 const WRAPPERS = new Set([
     "ParenthesizedExpression",
     "TSAsExpression",
@@ -129,7 +129,7 @@ const MSG_DESC_MISSING = "工具缺少 description，或它不是字符串字面
 const MSG_DESC_SHORT = `工具 description 至少 ${MIN_DESCRIPTION} 个字符：说清工具做什么、何时该用、何时不该用`;
 const MSG_DESC_CJK = "工具 description 是模型可见文案，必须是英文，不得含中文字符";
 const MSG_ERR_DYNAMIC = "ToolError 的消息必须是字符串字面量或模板（或指向本文件内的此类常量 / 函数），否则无法检查是否可执行";
-const MSG_ERR_ACTION = "ToolError 的消息要让模型知道下一步怎么做：必须含建议动词之一（use / call / retry / check / ask / pass / provide）";
+const MSG_ERR_ACTION = "ToolError 的消息要让模型知道下一步怎么做：必须含建议动词之一（use / call / retry / check / ask / pass / provide / read）";
 /** 取一个 spec 表达式对应的对象字面量（直接写，或经本文件内的常量引用）。 */
 function specObject(n, env) {
     let e = unwrap(n);
@@ -204,7 +204,7 @@ function scanFile(f) {
  * - tool-description：`ctx.tools.register(spec, …)` 与 `BuiltinTool` 字面量（有 spec 与 run）里的 spec
  *   必须有字符串字面量 description（可 `+` 拼接）、不少于 20 字符、不含中文（模型可见文案一律英文）；
  * - tool-error-actionable：`new ToolError(msg)` 的 msg 是字符串字面量 / 模板（或本文件内的常量、函数返回值），
- *   且含建议动词 use / call / retry / check / ask / pass / provide 之一，让模型知道下一步做什么。
+ *   且含建议动词 use / call / retry / check / ask / pass / provide / read 之一，让模型知道下一步做什么。
  * spec 可以直接写对象字面量，也可以引用本文件内的 const；其他写法（跨文件、动态构造）报 tool-description。
  * 已知缺口：从别的文件导入的消息常量 / 函数不追踪；非 ToolError 类的错误不查；运行时拼出的 spec 不查。
  * 扫描：传入目录下的非测试源码。

package/dist/check/ui-slots.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from "./source.js";
+/**
+ * Slot problems of a manifest's `ui` (UI slots spec §3.2): a slot or version this SDK does not know
+ * (`ui-slot-unknown`, error: the host drops the contribution), an `after` that is no anchor of the
+ * slot (`ui-slot-anchor`, error) and a deprecated `place` (`ui-place-deprecated`, warning).
+ */
+export declare function uiSlotFindings(file: string, ui: unknown): Finding[];

package/dist/check/ui-slots.js

@@ -0,0 +1,30 @@
+import { resolveUiSlots } from "@capybara-hq/plugin-sdk";
+/**
+ * Slot problems of a manifest's `ui` (UI slots spec §3.2): a slot or version this SDK does not know
+ * (`ui-slot-unknown`, error: the host drops the contribution), an `after` that is no anchor of the
+ * slot (`ui-slot-anchor`, error) and a deprecated `place` (`ui-place-deprecated`, warning).
+ */
+export function uiSlotFindings(file, ui) {
+    if (!Array.isArray(ui))
+        return [];
+    const r = resolveUiSlots(ui);
+    const out = [];
+    const at = (rule, message, severity) => {
+        out.push({ file, line: 1, rule, message, ...(severity && { severity }) });
+    };
+    for (const d of r.dropped) {
+        at("ui-slot-unknown", `ui "${d.id}" names slot ${d.ref}, which this SDK does not know (${d.reason}); the host would drop it`);
+    }
+    for (const a of r.unknownAnchors) {
+        const c = ui.find((x) => x.id === a.id);
+        const ref = r.resolved.find((x) => x.contribution.id === a.id);
+        const anchors = ref?.slot.anchors ?? [];
+        at("ui-slot-anchor", `ui "${a.id}" has after "${a.after}", which is not an anchor of slot ${ref?.slot.id ?? c?.slot}; the anchors are ${anchors.join(", ")}`);
+    }
+    for (const id of r.deprecatedPlace) {
+        const c = ui.find((x) => x.id === id);
+        const slot = r.resolved.find((x) => x.contribution.id === id)?.slot.id;
+        at("ui-place-deprecated", `ui "${id}" uses place "${c?.place}"; write slot: "${slot}"`, "warning");
+    }
+    return out;
+}

package/dist/cli.js

@@ -2,8 +2,6 @@
  * `capybara-plugin`: pack, check, sync the versions of and release Capybara plugins.
  *
  *   capybara-plugin pack [<dir>...] [--all <root>] [--out <dir>]
- *   capybara-plugin pack --bootstrap <manifest> [--root <dir>] [--out <dir>] [--registry <url>]
- *                        [--npm-token <token>]
  *   capybara-plugin check [--root <dir>] [--plugins <glob>] [--base <ref>]
  *   capybara-plugin sync-versions [--root <dir>] [--plugins <glob>]
  *   capybara-plugin marketplace --write|--check [--base <rev>] [--root <dir>] [--file <path>]