@capybara-hq/plugin-tools 0.1.0-rc.2 → 0.1.0-rc.3

package/dist/check/index.d.ts

@@ -5,6 +5,7 @@ export { checkMigrations, checkSql } from "./migrations.js";
 export { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";
 export { checkPluginPermissions } from "./plugin-permissions.js";
 export { checkPluginState } from "./plugin-state.js";
+export { checkPluginToolKeys, TOOL_KEY_MAX } from "./plugin-tool-keys.js";
 export { syncPluginVersions } from "./plugin-versions.js";
 export { checkPluginReleaseMetadata } from "./release-metadata.js";
 export { formatFinding, printCheck } from "./report.js";

package/dist/check/index.js

@@ -5,6 +5,7 @@ export { checkMigrations, checkSql } from "./migrations.js";
 export { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";
 export { checkPluginPermissions } from "./plugin-permissions.js";
 export { checkPluginState } from "./plugin-state.js";
+export { checkPluginToolKeys, TOOL_KEY_MAX } from "./plugin-tool-keys.js";
 export { syncPluginVersions } from "./plugin-versions.js";
 export { checkPluginReleaseMetadata } from "./release-metadata.js";
 export { formatFinding, printCheck } from "./report.js";

package/dist/check/plugin-permissions.d.ts

@@ -1,5 +1,16 @@
 import { type Finding } from "./source.js";
 export type { Finding };
+/** A `ctx.tools.register({ name })` call found in an extension's setup. */
+export interface ToolRegistration {
+    file: string;
+    line: number;
+    /** The extension name of the enclosing defineExtension (undefined: not a literal). */
+    extension: string | undefined;
+    /** The tool name (undefined: not a literal or same-file const). */
+    tool: string | undefined;
+    /** The call carries a `capybara:allow-dynamic-permission <reason>` marker. */
+    allowed: boolean;
+}
 /**
  * 插件权限静态检查（AST）：把 setup(ctx) 里对平台能力的访问与 defineExtension 清单比对。规则：
  * - perm-secrets：用了 ctx.secrets 而 permissions.secrets 不是 true；
@@ -20,3 +31,9 @@ export type { Finding };
  * 扫描范围：传入目录下的非测试源码。
  */
 export declare function checkPluginPermissions(pluginDirs: string[]): Finding[];
+/**
+ * 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 declare function findToolRegistrations(pluginDirs: string[]): ToolRegistration[];

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"]) {
@@ -165,7 +166,7 @@ function readManifest(obj, decls) {
     }
     return m;
 }
-function scanSetup(f, m, decls) {
+function scanSetup(f, m, decls, onTool) {
     const out = [];
     /** 明确的违规：豁免注释不起作用。 */
     const add = (at, rule, message) => {
@@ -253,6 +254,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)) {
@@ -338,7 +346,7 @@ function scanSetup(f, m, decls) {
     }
     return out;
 }
-function scanFile(f) {
+function scanFile(f, onTool) {
     const decls = buildDecls(f);
     const out = [];
     walk(f.program, (n) => {
@@ -351,7 +359,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));
     });
     return out;
 }
@@ -390,3 +398,22 @@ 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);
+}

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/run.js

@@ -4,6 +4,7 @@ import { checkMigrations } from "./migrations.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";
@@ -30,6 +31,7 @@ export function pluginChecks(scope) {
             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/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/package.json

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