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

package/README.md

@@ -36,26 +36,33 @@ capybara-plugin release [--dry-run] [--provenance] [--out <dir>] [--auto] [--roo
   timers, no module-level mutable state), the permission manifest (hooks, UI, storage, HTTP,
   secrets, tools), packing into a valid plugin package, the tool design rules (English
   descriptions, actionable errors), the migrations (naming, idempotent, no unmarked destructive
-  statements), the plugin tests' imports (`plugin-test-imports`: a file under `<plugin>/test` uses
+  statements, one file per number in a directory), the plugin tests' imports (`plugin-test-imports`: a file under `<plugin>/test` uses
   only `@capybara-hq/plugin-sdk`, `@capybara-hq/testing`, `@capybara-hq/plugin-model-fake`, the
   plugin itself and files inside the plugin, by import, package-name string or path) and the
   release metadata (`plugin-release-metadata`: a public plugin has a `description`, a `license`, an
   https `homepage` and `repository` `{ type: "git", url: <the root package.json's
-  repository.url>, directory: <its dir> }`; `example-*` plugins are private). `--base <ref>` also fails when the diff edits, deletes or renames an applied
-  migration. No plugin found is an error. A plugin may list `@capybara-hq/plugin-tools` (like
+  repository.url>, directory: <its dir> }`; `example-*` plugins are private; its `plugin.json`
+  has a `displayName`, and `release-description-zh` warns, without failing, when its `description`
+  has no `zh`). Warnings are printed under `passed with N warning(s)`. `--base <ref>` also fails when the diff edits, deletes or renames an applied
+  migration, or adds one numbered at or below the highest number of its directory at `<ref>`. No plugin found is an error. A plugin may list `@capybara-hq/plugin-tools` (like
   `@capybara-hq/testing`) in its devDependencies.
 - **sync-versions**: after `changeset version` (which bumps only `package.json`), copies each
   plugin's version into its `.capybara-plugin/plugin.json` and its extension manifest
   (`src/index.ts`, `  version: "x"`), which the packer requires equal.
-- **marketplace**: `--write` appends to `.capybara-plugin/marketplace.json` (`--file`) one npm entry
-  per public plugin version it does not list yet (`name`, `version`, `summary`, `homepage`,
+- **marketplace**: `--write` keeps one npm entry per public plugin in
+  `.capybara-plugin/marketplace.json` (`--file`), its current version (`name`, `version`,
+  `summary` from the `plugin.json` `description`, `displayName` from `plugin.json`, `homepage`,
   `permissions`, `source.npm` with the sha512 of a reproducible pack), formatted as Biome formats
-  it; `--check` fails when an entry is missing (`marketplace-missing`) or the file does not parse
-  (`marketplace-invalid`). A version already listed is not compared with the tree: once
+  it: a plugin whose version moved gets its entry replaced in place, its other versions are
+  dropped, a listed entry's `summary` / `displayName` are refreshed from `plugin.json`
+  (`marketplace-display-stale` in `--check`; source and integrity untouched), and entries of
+  plugins not in the tree are kept. `--check` fails when a plugin's
+  current version is missing or not its only entry (`marketplace-missing`) or the file does not
+  parse (`marketplace-invalid`). A version already listed is not compared with the tree: once
   published, its bytes are the release gate's business. `--check --base <rev>` (pull requests)
-  also requires the entries at `<rev>` to stay unchanged and first, in order
-  (`marketplace-append-only`), and the entries added since to match their packs
-  (`marketplace-integrity`). Entries of versions no longer in the tree are kept.
+  also requires a plugin's version to only increase over the versions `<rev>` lists
+  (`marketplace-version-decrease`), a version `<rev>` lists to keep its integrity, and the entries
+  added since to match their packs (`marketplace-integrity`).
 - **release**: publishes every non-private workspace package whose version is not on npm yet:
   plugins (the packages under `plugins/`) as their plugin tgz, libraries through `pnpm pack`, with
   the dist-tag rule (prerelease `next`, backport `release-<major>.<minor>`, else `latest`), then

package/dist/check/applied-migrations.d.ts

@@ -26,3 +26,26 @@ export declare function checkAppliedMigrations(nameStatus: string, isMigration:
  * repository; finding files are relative to `cwd` too.
  */
 export declare function diffAppliedMigrations(cwd: string, base: string, isMigration: MigrationFilePredicate): Finding[];
+/** The files of a migration directory at the base (repo-relative `dir`, POSIX); `[]` when absent. */
+export type BaseMigrationNames = (dir: string) => readonly string[];
+/**
+ * PR check (rule `migration-number-behind-base`): every migration the diff adds is numbered above
+ * the highest number of its directory at the base. A branch that numbered its migrations before
+ * the base released the same or higher numbers (a branch's `0063..0068` against main's new
+ * `0063`) would otherwise merge with a collision or out of order: databases that already ran the
+ * base's files never run a lower-numbered newcomer in sequence, and a shared one ends up numbered
+ * differently from a fresh one.
+ *
+ * `nameStatus` is the output of `git diff --name-status -M <base>...HEAD`; the added files are the
+ * `A` entries and the destinations of `C` and `R` entries (`R` sources are
+ * {@link checkAppliedMigrations}'). `baseNames` lists a directory at the base itself (not the merge
+ * base: the base may have moved on since the branch started). A file that already exists at the
+ * base under the same name is not new to it and is skipped.
+ */
+export declare function checkMigrationNumbers(nameStatus: string, isMigration: MigrationFilePredicate, baseNames: BaseMigrationNames): Finding[];
+/**
+ * Runs {@link checkMigrationNumbers} on `<base>...HEAD` in `cwd`, listing each directory at
+ * `<base>` itself with `git ls-tree`. Paths are relative to `cwd`, as in
+ * {@link diffAppliedMigrations}.
+ */
+export declare function diffMigrationNumbers(cwd: string, base: string, isMigration: MigrationFilePredicate): Finding[];

package/dist/check/applied-migrations.js

@@ -63,3 +63,89 @@ export function diffAppliedMigrations(cwd, base, isMigration) {
     const out = execFileSync("git", ["diff", "--name-status", "--no-ext-diff", "--relative", "-M", `${base}...HEAD`], { cwd, encoding: "utf8" });
     return checkAppliedMigrations(out, isMigration);
 }
+const NUMBERED = /^(\d{4})_[^/]*\.sql$/;
+/**
+ * PR check (rule `migration-number-behind-base`): every migration the diff adds is numbered above
+ * the highest number of its directory at the base. A branch that numbered its migrations before
+ * the base released the same or higher numbers (a branch's `0063..0068` against main's new
+ * `0063`) would otherwise merge with a collision or out of order: databases that already ran the
+ * base's files never run a lower-numbered newcomer in sequence, and a shared one ends up numbered
+ * differently from a fresh one.
+ *
+ * `nameStatus` is the output of `git diff --name-status -M <base>...HEAD`; the added files are the
+ * `A` entries and the destinations of `C` and `R` entries (`R` sources are
+ * {@link checkAppliedMigrations}'). `baseNames` lists a directory at the base itself (not the merge
+ * base: the base may have moved on since the branch started). A file that already exists at the
+ * base under the same name is not new to it and is skipped.
+ */
+export function checkMigrationNumbers(nameStatus, isMigration, baseNames) {
+    const findings = [];
+    const highest = new Map();
+    const highestIn = (dir) => {
+        if (!highest.has(dir)) {
+            let top = null;
+            for (const name of baseNames(dir)) {
+                const m = NUMBERED.exec(name);
+                if (m?.[1] === undefined)
+                    continue;
+                const n = Number(m[1]);
+                if (top === null || n > top.n)
+                    top = { n, name };
+            }
+            highest.set(dir, top);
+        }
+        return highest.get(dir) ?? null;
+    };
+    for (const line of nameStatus.split("\n")) {
+        if (line === "")
+            continue;
+        const parts = line.split("\t");
+        const kind = parts[0]?.[0];
+        const added = kind === "A" ? parts[1] : kind === "C" || kind === "R" ? parts[2] : undefined;
+        if (added === undefined || !isMigration(added))
+            continue;
+        const slash = added.lastIndexOf("/");
+        const dir = slash < 0 ? "" : added.slice(0, slash);
+        const name = added.slice(slash + 1);
+        const m = NUMBERED.exec(name);
+        if (m?.[1] === undefined)
+            continue; // the naming rule reports it
+        if (baseNames(dir).includes(name))
+            continue;
+        const top = highestIn(dir);
+        if (top === null || Number(m[1]) > top.n)
+            continue;
+        findings.push({
+            file: added,
+            line: 1,
+            rule: "migration-number-behind-base",
+            message: `migration number ${m[1]} is not above the base's highest in ${dir || "."} (${top.name}): renumber the files this change adds to follow it`,
+        });
+    }
+    return findings;
+}
+/**
+ * Runs {@link checkMigrationNumbers} on `<base>...HEAD` in `cwd`, listing each directory at
+ * `<base>` itself with `git ls-tree`. Paths are relative to `cwd`, as in
+ * {@link diffAppliedMigrations}.
+ */
+export function diffMigrationNumbers(cwd, base, isMigration) {
+    const out = execFileSync("git", ["diff", "--name-status", "--no-ext-diff", "--relative", "-M", `${base}...HEAD`], { cwd, encoding: "utf8" });
+    const listed = new Map();
+    const baseNames = (dir) => {
+        let names = listed.get(dir);
+        if (names === undefined) {
+            const tree = execFileSync("git", ["ls-tree", "--name-only", base, "--", `${dir || "."}/`], {
+                cwd,
+                encoding: "utf8",
+            });
+            names = tree
+                .split("\n")
+                .filter((p) => p !== "")
+                .map((p) => p.slice(p.lastIndexOf("/") + 1));
+            listed.set(dir, names);
+        }
+        return names;
+    };
+    return checkMigrationNumbers(out, isMigration, baseNames);
+}

package/dist/check/cli.d.ts

@@ -7,7 +7,8 @@ export declare const CHECK_USAGE = "capybara-plugin check [--root <dir>] [--plug
  *   default `plugins/*` when `<root>/plugins` exists, else the root itself when it holds
  *   `.capybara-plugin/plugin.json`;
  * - `--base <ref>`: also fail when `<ref>...HEAD` edits, deletes or renames a migration of a plugin
- *   (applied migrations are immutable); for pull requests.
+ *   (applied migrations are immutable), or adds one numbered at or below the highest number of its
+ *   directory at `<ref>`; for pull requests.
  *
  * Finding no plugin is an error: an empty scan would pass without checking anything.
  *

package/dist/check/cli.js

@@ -1,7 +1,7 @@
 import { join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { discoverPlugins, pluginsGlobOf } from "../discover.js";
-import { diffAppliedMigrations, migrationFileMatcher } from "./applied-migrations.js";
+import { diffAppliedMigrations, diffMigrationNumbers, migrationFileMatcher, } from "./applied-migrations.js";
 import { pluginChecks, runChecks } from "./run.js";
 export const CHECK_USAGE = "capybara-plugin check [--root <dir>] [--plugins <glob>] [--base <ref>]";
 /**
@@ -12,7 +12,8 @@ export const CHECK_USAGE = "capybara-plugin check [--root <dir>] [--plugins <glo
  *   default `plugins/*` when `<root>/plugins` exists, else the root itself when it holds
  *   `.capybara-plugin/plugin.json`;
  * - `--base <ref>`: also fail when `<ref>...HEAD` edits, deletes or renames a migration of a plugin
- *   (applied migrations are immutable); for pull requests.
+ *   (applied migrations are immutable), or adds one numbered at or below the highest number of its
+ *   directory at `<ref>`; for pull requests.
  *
  * Finding no plugin is an error: an empty scan would pass without checking anything.
  *
@@ -53,7 +54,10 @@ export async function checkCommand(args, cwd) {
         const isMigration = migrationFileMatcher([glob === "." ? "migrations" : `${glob}/migrations`]);
         checks.push({
             name: "Applied migrations",
-            run: () => diffAppliedMigrations(root, base, isMigration).map((f) => ({
+            run: () => [
+                ...diffAppliedMigrations(root, base, isMigration),
+                ...diffMigrationNumbers(root, base, isMigration),
+            ].map((f) => ({
                 ...f,
                 file: join(root, f.file),
             })),

package/dist/check/config-forms.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from "./source.js";
+/**
+ * Config forms (extension config forms spec §10): every plugin with an extension (`src/index.ts`)
+ * is bundled and imported the way the packer does, and its deployment and org config schemas are
+ * turned into the form JSON Schemas the package carries.
+ * - `plugin-config-ui`: a problem of their hints (`validateConfigUi` at the level, and value hints
+ *   on secrets, which the JSON Schema drops silently); the packer refuses these too.
+ * - `plugin-config-labels`: a published plugin (not `"private": true`) whose rendered field has no
+ *   label in both zh and en (secret records drawn per item by `x-ui.secrets` are skipped).
+ * A plugin that does not bundle or import is left to "Plugin pack", which reports it.
+ * Findings point at the plugin's `src/index.ts`.
+ */
+export declare function checkConfigForms(pluginDirs: string[]): Promise<Finding[]>;

package/dist/check/config-forms.js

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extensionConfigSchemas, formatConfigSchemaProblem, missingConfigLabels, } from "../pack/config-schemas.js";
+import { importPluginExtension } from "../pack/pack.js";
+/** A plugin's package.json, or undefined when it is missing or not a JSON object. */
+function readPackageJson(file) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(file, "utf8"));
+        return typeof pkg === "object" && pkg !== null && !Array.isArray(pkg)
+            ? pkg
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Config forms (extension config forms spec §10): every plugin with an extension (`src/index.ts`)
+ * is bundled and imported the way the packer does, and its deployment and org config schemas are
+ * turned into the form JSON Schemas the package carries.
+ * - `plugin-config-ui`: a problem of their hints (`validateConfigUi` at the level, and value hints
+ *   on secrets, which the JSON Schema drops silently); the packer refuses these too.
+ * - `plugin-config-labels`: a published plugin (not `"private": true`) whose rendered field has no
+ *   label in both zh and en (secret records drawn per item by `x-ui.secrets` are skipped).
+ * A plugin that does not bundle or import is left to "Plugin pack", which reports it.
+ * Findings point at the plugin's `src/index.ts`.
+ */
+export async function checkConfigForms(pluginDirs) {
+    const findings = [];
+    for (const dir of pluginDirs) {
+        const file = join(dir, "src/index.ts");
+        if (!existsSync(file))
+            continue;
+        let config;
+        try {
+            config = (await importPluginExtension(dir)).config;
+        }
+        catch {
+            continue;
+        }
+        const { schemas, problems } = extensionConfigSchemas(config);
+        for (const p of problems) {
+            findings.push({
+                file,
+                line: 1,
+                rule: "plugin-config-ui",
+                message: formatConfigSchemaProblem(p),
+            });
+        }
+        const pkg = readPackageJson(join(dir, "package.json"));
+        // a missing or malformed package.json is "Plugin pack"'s finding
+        if (pkg === undefined || pkg.private === true)
+            continue;
+        for (const level of ["deployment", "org"]) {
+            const schema = schemas[level];
+            if (schema === undefined)
+                continue;
+            for (const p of missingConfigLabels(schema)) {
+                findings.push({
+                    file,
+                    line: 1,
+                    rule: "plugin-config-labels",
+                    message: `${level} config: ${p.path} ${p.message}: a published plugin labels every field it shows (ui(schema, { label: { zh, en } }))`,
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/check/index.d.ts

@@ -1,7 +1,9 @@
-export { checkAppliedMigrations, diffAppliedMigrations, type MigrationFilePredicate, migrationFileMatcher, } from "./applied-migrations.js";
+export { type BaseMigrationNames, checkAppliedMigrations, checkMigrationNumbers, diffAppliedMigrations, diffMigrationNumbers, type MigrationFilePredicate, migrationFileMatcher, } from "./applied-migrations.js";
 export { CHECK_USAGE, checkCommand } from "./cli.js";
+export { checkConfigForms } from "./config-forms.js";
 export { checkDeps } from "./deps.js";
 export { checkMigrations, checkSql } from "./migrations.js";
+export { checkOrgOverride } from "./org-override.js";
 export { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";
 export { checkPluginPermissions } from "./plugin-permissions.js";
 export { checkPluginState } from "./plugin-state.js";

package/dist/check/index.js

@@ -1,7 +1,9 @@
-export { checkAppliedMigrations, diffAppliedMigrations, migrationFileMatcher, } from "./applied-migrations.js";
+export { checkAppliedMigrations, checkMigrationNumbers, diffAppliedMigrations, diffMigrationNumbers, migrationFileMatcher, } from "./applied-migrations.js";
 export { CHECK_USAGE, checkCommand } from "./cli.js";
+export { checkConfigForms } from "./config-forms.js";
 export { checkDeps } from "./deps.js";
 export { checkMigrations, checkSql } from "./migrations.js";
+export { checkOrgOverride } from "./org-override.js";
 export { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";
 export { checkPluginPermissions } from "./plugin-permissions.js";
 export { checkPluginState } from "./plugin-state.js";

package/dist/check/migrations.d.ts

@@ -6,6 +6,6 @@ export type { Finding };
 export declare function checkSql(file: string, source: string): Finding[];
 /**
  * Checks migration directories (missing ones are ignored). Rules: naming / idempotent / destructive /
- * transaction-control / do-block.
+ * transaction-control / do-block / migration-duplicate-number.
  */
 export declare function checkMigrations(dirs: string[]): Finding[];

package/dist/check/migrations.js

@@ -64,7 +64,7 @@ export function checkSql(file, source) {
 }
 /**
  * Checks migration directories (missing ones are ignored). Rules: naming / idempotent / destructive /
- * transaction-control / do-block.
+ * transaction-control / do-block / migration-duplicate-number.
  */
 export function checkMigrations(dirs) {
     const findings = [];
@@ -75,6 +75,7 @@ export function checkMigrations(dirs) {
             .filter((e) => e.isFile())
             .map((e) => e.name)
             .sort();
+        findings.push(...duplicateNumbers(dir, entries));
         for (const name of entries) {
             const file = join(dir, name);
             if (!NAME_RE.test(name)) {
@@ -91,3 +92,31 @@ export function checkMigrations(dirs) {
     }
     return findings;
 }
+/**
+ * Two files of one directory with the same `NNNN` (rule `migration-duplicate-number`): the
+ * migrator runs files in name order and records them by name, so the pair runs in an order
+ * nobody chose, and a database that already ran one of them under that number ends up with a
+ * different numbering than a fresh one (as when a branch's `0063` met main's released `0063`).
+ * Every file after the first of a number is reported, naming the first.
+ */
+function duplicateNumbers(dir, sortedNames) {
+    const first = new Map();
+    const findings = [];
+    for (const name of sortedNames) {
+        if (!NAME_RE.test(name))
+            continue;
+        const n = name.slice(0, 4);
+        const earlier = first.get(n);
+        if (earlier === undefined) {
+            first.set(n, name);
+            continue;
+        }
+        findings.push({
+            file: join(dir, name),
+            line: 1,
+            rule: "migration-duplicate-number",
+            message: `migration number ${n} is also used by ${earlier}: each number is used once per directory; renumber the file that is not applied anywhere yet to the next free number`,
+        });
+    }
+    return findings;
+}

package/dist/check/org-override.d.ts

@@ -0,0 +1,10 @@
+import type { Finding } from "./source.js";
+/**
+ * `plugin-org-override-unbound` (a warning): an extension whose deployment config has an
+ * `orgAccess(…, "override")` field, but that registers no tool, no `ctx.ui` view or action, no
+ * hook and provides none of `web-search`, `web-fetch`, `directory`, `model-provider` or
+ * `file-preview`. An override reaches the extension only in the per-call `config` of those entry
+ * points, so the field can never take effect. Findings point at the plugin's `src/index.ts`.
+ * A plugin that does not bundle or import is left to "Plugin pack".
+ */
+export declare function checkOrgOverride(pluginDirs: string[]): Promise<Finding[]>;

package/dist/check/org-override.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { extensionConfigSchemas } from "../pack/config-schemas.js";
+import { importPluginExtension } from "../pack/pack.js";
+import { findCtxCalls } from "./plugin-permissions.js";
+/** Extension points whose calls carry the org's per-call config on their own. */
+const ORG_AWARE_POINTS = new Set([
+    "web-search",
+    "web-fetch",
+    "directory",
+    "model-provider",
+    "file-preview",
+]);
+/** The top-level properties of a deployment schema marked `x-org: "override"`. */
+function overrideFields(schema) {
+    const props = schema?.properties;
+    if (typeof props !== "object" || props === null)
+        return [];
+    return Object.entries(props)
+        .filter(([, v]) => v?.["x-org"] === "override")
+        .map(([k]) => k);
+}
+/**
+ * `plugin-org-override-unbound` (a warning): an extension whose deployment config has an
+ * `orgAccess(…, "override")` field, but that registers no tool, no `ctx.ui` view or action, no
+ * hook and provides none of `web-search`, `web-fetch`, `directory`, `model-provider` or
+ * `file-preview`. An override reaches the extension only in the per-call `config` of those entry
+ * points, so the field can never take effect. Findings point at the plugin's `src/index.ts`.
+ * A plugin that does not bundle or import is left to "Plugin pack".
+ */
+export async function checkOrgOverride(pluginDirs) {
+    const findings = [];
+    for (const dir of pluginDirs) {
+        const file = join(dir, "src/index.ts");
+        if (!existsSync(file))
+            continue;
+        let ext;
+        try {
+            ext = await importPluginExtension(dir);
+        }
+        catch {
+            continue;
+        }
+        const fields = overrideFields(extensionConfigSchemas(ext.config).schemas.deployment);
+        if (fields.length === 0)
+            continue;
+        const calls = findCtxCalls(dir);
+        if (calls.tools || calls.ui || calls.hooks)
+            continue;
+        const provided = (ext.provides ?? []).map((p) => String(p).split("@")[0] ?? "");
+        if (provided.some((p) => ORG_AWARE_POINTS.has(p)))
+            continue;
+        findings.push({
+            file,
+            line: 1,
+            rule: "plugin-org-override-unbound",
+            severity: "warning",
+            message: `deployment config field ${fields.join(", ")} allows an org override, but the extension registers no tool, ui view, action or hook and provides no org-aware extension point (${[...ORG_AWARE_POINTS].join(", ")}), so no per-call config ever reaches it`,
+        });
+    }
+    return findings;
+}

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

@@ -37,3 +37,17 @@ export declare function checkPluginPermissions(pluginDirs: string[]): Finding[];
  * Unparseable files are skipped here; the permissions check reports them.
  */
 export declare function findToolRegistrations(pluginDirs: string[]): ToolRegistration[];
+/** The `ctx.<area>.<method>` calls an extension's setup makes (see {@link findCtxCalls}). */
+export interface CtxCalls {
+    /** `ctx.tools.register` is called. */
+    tools: boolean;
+    /** `ctx.ui.view` or `ctx.ui.action` is called. */
+    ui: boolean;
+    /** `ctx.hooks.on` is called. */
+    hooks: boolean;
+}
+/**
+ * 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 declare function findCtxCalls(pluginDir: string): CtxCalls;

package/dist/check/plugin-permissions.js

@@ -166,7 +166,7 @@ function readManifest(obj, decls) {
     }
     return m;
 }
-function scanSetup(f, m, decls, onTool) {
+function scanSetup(f, m, decls, onTool, onCall) {
     const out = [];
     /** 明确的违规：豁免注释不起作用。 */
     const add = (at, rule, message) => {
@@ -240,6 +240,8 @@ function scanSetup(f, m, decls, onTool) {
                 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;
@@ -346,7 +348,7 @@ function scanSetup(f, m, decls, onTool) {
     }
     return out;
 }
-function scanFile(f, onTool) {
+function scanFile(f, onTool, onCall) {
     const decls = buildDecls(f);
     const out = [];
     walk(f.program, (n) => {
@@ -359,7 +361,7 @@ function scanFile(f, onTool) {
         const obj = arg ? resolve(arg, decls) : undefined;
         if (obj?.type !== "ObjectExpression")
             return;
-        out.push(...scanSetup(f, readManifest(obj, decls), decls, onTool));
+        out.push(...scanSetup(f, readManifest(obj, decls), decls, onTool, onCall));
     });
     return out;
 }
@@ -417,3 +419,26 @@ export function findToolRegistrations(pluginDirs) {
     }
     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/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;