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

package/README.md

@@ -14,8 +14,6 @@ npm install --save-dev @capybara-hq/plugin-tools
 
 ```bash
 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>]
@@ -30,38 +28,41 @@ capybara-plugin release [--dry-run] [--provenance] [--out <dir>] [--auto] [--roo
   manifest written into `plugin.json`, LICENSE / NOTICE and the bundled dependencies' notices
   included. A plugin with an extension gets `"main"` and `"exports": { ".": "./dist/index.mjs" }`,
   so once installed it resolves by package name (a test loads `@capybara-hq/plugin-model-fake`
-  from npm). `--all <root>` packs every plugin of a repository; `--bootstrap` packs the entries of
-  a bootstrap manifest (workspace entries from the repository, npm entries downloaded from
-  `--registry`, default `CAPYBARA_PACKAGES__NPM_REGISTRY` or the public registry, with
-  `--npm-token` / `CAPYBARA_PACKAGES__NPM_TOKEN` sent to the registry origin only, tarballs capped
-  at 50 MiB) and checks them against their pinned sha512 and their `package.json` name and version.
-  Output: `artifacts/plugins`.
+  from npm). `--all <root>` packs every plugin of a repository. Output: `artifacts/plugins`. (The
+  bootstrap plugins a kernel pins are no longer packed here: a starting kernel downloads them.)
 - **check**: every plugin check, on the plugins under `<root>/plugins/*` (or `--plugins <glob>`, or
   the root itself when it is a plugin): the dependency boundary (a plugin depends only on
   `@capybara-hq/plugin-sdk` and third-party packages), extension state under multiple replicas (no
   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
@@ -101,7 +102,7 @@ and hides packaging bugs.
 
 ## Library
 
-The same code as functions: `packPlugin`, `packBootstrap`, `pluginChecks` / `runChecks` and each
+The same code as functions: `packPlugin`, `downloadPinnedNpmPackage`, `pluginChecks` / `runChecks` and each
 check (`checkDeps`, `checkPluginState`, `checkPluginPermissions`, `checkPluginPack`,
 `checkToolDesign`, `checkMigrations`, `checkAppliedMigrations`, `checkPluginTestImports`,
 `checkPluginReleaseMetadata`), `syncPluginVersions` (after `changeset version`),

package/bin/capybara-plugin.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // The `capybara-plugin` bin: runs the compiled CLI (dist/cli.js, built by `tsc -b`). In this
-// repository, the root scripts (pnpm pack-plugin, pack-plugins, pack-bootstrap, release) run the
+// repository, the root scripts (pnpm pack-plugin, pack-plugins, release) run the
 // TypeScript sources through tsx instead.
 import { existsSync } from "node:fs";
 

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/deps.d.ts

@@ -5,7 +5,9 @@ export type { Finding };
  * - pluginDirs: each plugin directory (source imports and package.json); a violation is
  *   plugin-imports-kernel (a path leaving the plugin directory: plugin-imports-outside);
  * - sdkDirs: the packages/plugin-sdk directory; any @capybara-hq/* package or path leaving the
- *   package directory is sdk-imports-internal.
+ *   package directory is sdk-imports-internal;
+ * - deviceDirs: the packages/device directory (source, tests and package.json); any @capybara-hq/*
+ *   package other than plugin-sdk or path leaving the package directory is device-imports-internal.
  *
  * Covers: import / export from / export * / import type / dynamic import("literal or concatenated
  * literals") / require("…") / import x = require() / import("x") types; package.json dependencies /
@@ -20,4 +22,4 @@ export type { Finding };
  * `module.require` or `createRequire(...)`; `import.meta.resolve`; paths built at run time to read
  * files; nested package.json files and TS `paths` mappings.
  */
-export declare function checkDeps(pluginDirs: string[], sdkDirs?: string[]): Finding[];
+export declare function checkDeps(pluginDirs: string[], sdkDirs?: string[], deviceDirs?: string[]): Finding[];

package/dist/check/deps.js

@@ -33,6 +33,13 @@ const SDK_RULES = {
     outsideMessage: (what) => `packages/plugin-sdk must not reference files outside its package directory (${what})`,
     allowed: () => false,
 };
+const DEVICE_RULES = {
+    pkgRule: "device-imports-internal",
+    outsideRule: "device-imports-internal",
+    pkgMessage: (what) => `packages/device runs on a person's machine and may depend only on ${SDK} and third-party npm packages, not on ${what}; the kernel is reached over HTTP and WebSocket only`,
+    outsideMessage: (what) => `packages/device must not reference files outside its package directory (${what})`,
+    allowed: (pkg) => pkg === SDK,
+};
 /** The violation a reference string (package name / relative path / file: URL / protocol dependency value) makes, if any. */
 function judge(value, baseDir, rootDir, rules, where) {
     const pkgs = [...value.matchAll(SCOPED_RE)].map((m) => `${SCOPE}${m[1]}`);
@@ -180,7 +187,9 @@ function sourceFindings(dir, rules, srcDir) {
  * - pluginDirs: each plugin directory (source imports and package.json); a violation is
  *   plugin-imports-kernel (a path leaving the plugin directory: plugin-imports-outside);
  * - sdkDirs: the packages/plugin-sdk directory; any @capybara-hq/* package or path leaving the
- *   package directory is sdk-imports-internal.
+ *   package directory is sdk-imports-internal;
+ * - deviceDirs: the packages/device directory (source, tests and package.json); any @capybara-hq/*
+ *   package other than plugin-sdk or path leaving the package directory is device-imports-internal.
  *
  * Covers: import / export from / export * / import type / dynamic import("literal or concatenated
  * literals") / require("…") / import x = require() / import("x") types; package.json dependencies /
@@ -195,7 +204,7 @@ function sourceFindings(dir, rules, srcDir) {
  * `module.require` or `createRequire(...)`; `import.meta.resolve`; paths built at run time to read
  * files; nested package.json files and TS `paths` mappings.
  */
-export function checkDeps(pluginDirs, sdkDirs = []) {
+export function checkDeps(pluginDirs, sdkDirs = [], deviceDirs = []) {
     const findings = [];
     for (const dir of pluginDirs) {
         findings.push(...packageFindings(dir, PLUGIN_RULES), ...sourceFindings(dir, PLUGIN_RULES, dir));
@@ -203,5 +212,8 @@ export function checkDeps(pluginDirs, sdkDirs = []) {
     for (const dir of sdkDirs) {
         findings.push(...packageFindings(dir, SDK_RULES), ...sourceFindings(dir, SDK_RULES, join(dir, "src")));
     }
+    for (const dir of deviceDirs) {
+        findings.push(...packageFindings(dir, DEVICE_RULES), ...sourceFindings(dir, DEVICE_RULES, dir));
+    }
     return findings;
 }

package/dist/check/index.d.ts

@@ -1,10 +1,13 @@
-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";
+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

@@ -1,10 +1,13 @@
-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";
+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/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-pack.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { ExtensionPackageError, PACKAGES_MAX_BYTES_DEFAULT, PluginPackageError, readExtensionPackage, readPluginPackage, } from "@capybara-hq/kernel";
 import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
 import { packPlugin } from "../pack/pack.js";
+import { uiSlotFindings } from "./ui-slots.js";
 /**
  * The default of `packages.maxBytes` (from the kernel config schema): an official plugin's package
  * must install under the default limit.
@@ -38,6 +39,7 @@ export async function checkPluginPack(pluginDirs) {
                 }
                 const bytes = new Uint8Array(await readFile(r.file));
                 const plugin = await readPluginPackage(bytes, opts);
+                findings.push(...uiSlotFindings(file, plugin.manifest.extension?.manifest.ui));
                 if (plugin.manifest.extension !== undefined)
                     await readExtensionPackage(bytes, opts);
             }

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；
@@ -11,7 +22,9 @@ export type { Finding };
  * - 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 会跟踪本地别名，以及按位置传给同文件函数的参数。
@@ -20,3 +33,23 @@ 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[];
+/** 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;