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

package/README.md

@@ -36,13 +36,13 @@ 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
+  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

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,5 +1,6 @@
-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 { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";

package/dist/check/index.js

@@ -1,5 +1,6 @@
-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 { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.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/release-metadata.d.ts

@@ -9,5 +9,7 @@ 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.
  */
 export declare function checkPluginReleaseMetadata(plugins: string[], root: string): Finding[];

package/dist/check/release-metadata.js

@@ -1,6 +1,25 @@
 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";
+/**
+ * Does the plugin's `.capybara-plugin/plugin.json` lack `displayName`? False when the file is
+ * missing or not JSON: "Plugin pack" reports those.
+ */
+function lacksDisplayName(file) {
+    if (!existsSync(file))
+        return false;
+    try {
+        const m = JSON.parse(readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+        return (typeof m === "object" &&
+            m !== null &&
+            m.displayName === undefined);
+    }
+    catch {
+        return false;
+    }
+}
 const readJson = (file) => JSON.parse(readFileSync(file, "utf8"));
 /** `repository.url` of a package.json (`"repository": "<url>"` or `{ url }`). */
 function repositoryUrl(pkg) {
@@ -22,6 +41,8 @@ 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.
  */
 export function checkPluginReleaseMetadata(plugins, root) {
     const out = [];
@@ -47,6 +68,15 @@ 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);
+        if (lacksDisplayName(manifestFile)) {
+            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 (typeof pkg.homepage !== "string" || !pkg.homepage.startsWith("https://")) {
             finding(`${label} is published and needs an https "homepage"`);
         }

package/dist/check/run.d.ts

@@ -8,7 +8,7 @@ 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/dist/check/run.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { checkConfigForms } from "./config-forms.js";
 import { checkDeps } from "./deps.js";
 import { checkMigrations } from "./migrations.js";
 import { checkPluginPack } from "./plugin-pack.js";
@@ -27,6 +28,7 @@ export function pluginChecks(scope) {
         { 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: "Tool design",
             run: () => checkToolDesign([...(scope.toolDesignDirs ?? []), ...plugins]),

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

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

package/dist/pack/config-schemas.js

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

package/dist/pack/index.d.ts

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

package/dist/pack/index.js

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

package/dist/pack/pack.d.ts

@@ -1,4 +1,4 @@
-import { type PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type ExtensionManifest, type PluginManifest } from "@capybara-hq/plugin-sdk";
 /**
  * The result of packing: the tgz path, its hex sha256 and the `.capybara-plugin/plugin.json`
  * written into it (the extension's static manifest is `manifest.extension?.manifest`).
@@ -25,6 +25,12 @@ export declare const STAGING_PREFIX = ".capybara-pack-";
 export declare const METADATA_FIELDS: readonly ["description", "repository", "homepage", "keywords"];
 /** Third-party license notices of the bundled dependencies (written only when there are any). */
 export declare const NOTICES_FILE = "THIRD-PARTY-NOTICES.txt";
+/**
+ * The extension a plugin directory's `src/index.ts` defines, bundled and imported the way the
+ * packer does (in a `.capybara-pack-*` staging dir under the system temp dir, removed afterwards).
+ * For checks that need the module (config forms); throws what packing would throw.
+ */
+export declare function importPluginExtension(pluginDir: string): Promise<ExtensionManifest>;
 /**
  * Packs a plugin directory into a plugin package (spec §4.1):
  * 1. reads and validates the source `.capybara-plugin/plugin.json` (it must not carry

package/dist/pack/pack.js

@@ -7,10 +7,11 @@ import { dirname, join, posix, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
-import { AGENT_TEMPLATE_LIMITS, checkEntryImports, defineExtension, HOST_PROVIDED_PACKAGES, PLUGIN_MANIFEST_FILE, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, SDK_VERSION, staticManifestOf, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
+import { AGENT_TEMPLATE_LIMITS, checkEntryImports, defineExtension, HOST_PROVIDED_PACKAGES, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, SDK_VERSION, staticManifestOf, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
 import { init as lexerInit, parse as lexerParse } from "es-module-lexer";
 import { build } from "esbuild";
 import { pack as tarPack } from "tar-stream";
+import { extensionConfigSchemas, formatConfigSchemaProblem } from "./config-schemas.js";
 /** The extension entry the packer writes (relative to the package root). */
 const EXTENSION_ENTRY = "dist/index.mjs";
 /**
@@ -363,6 +364,61 @@ async function contentFiles(dir, label, m) {
         agents: agents.length,
     };
 }
+/**
+ * Bundles `src/index.ts` into `<stage>/package/dist/index.mjs` (esbuild, single-file ESM), checks
+ * the bundle's imports, imports it and runs its default export through defineExtension. Returns the
+ * bundle, the defined manifest and the bundled inputs (for the notices).
+ */
+async function buildAndImport(dir, label, stage) {
+    await linkHostPackages(dir, stage);
+    const entryOut = join(stage, "package", EXTENSION_ENTRY);
+    const result = await build({
+        absWorkingDir: dir,
+        entryPoints: [join(dir, "src/index.ts")],
+        outfile: entryOut,
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node24",
+        external: [...HOST_PROVIDED_PACKAGES],
+        plugins: [nodeBuiltins],
+        banner: { js: BANNER },
+        define: DEFINE,
+        charset: "utf8",
+        logLevel: "silent",
+        metafile: true,
+        // Notices of bundled dependencies go to THIRD-PARTY-NOTICES.txt (built from the metafile).
+        legalComments: "none",
+    });
+    if (result.errors.length > 0) {
+        throw new Error(`${label}: esbuild failed: ${result.errors.map((e) => e.text).join("; ")}`);
+    }
+    const code = await readFile(entryOut);
+    const issues = await importIssues(code.toString("utf8"));
+    if (issues.length > 0)
+        throw new Error(`${label}: ${issues.join("; ")}`);
+    const mod = await importBundle(entryOut);
+    if (typeof mod.default !== "object" || mod.default === null) {
+        throw new Error(`${label}: the bundle has no default export object`);
+    }
+    const m = defineExtension(mod.default);
+    return { code, m, inputs: Object.keys(result.metafile?.inputs ?? {}) };
+}
+/**
+ * The extension a plugin directory's `src/index.ts` defines, bundled and imported the way the
+ * packer does (in a `.capybara-pack-*` staging dir under the system temp dir, removed afterwards).
+ * For checks that need the module (config forms); throws what packing would throw.
+ */
+export async function importPluginExtension(pluginDir) {
+    const dir = resolve(pluginDir);
+    const stage = await realpath(await mkdtemp(join(tmpdir(), STAGING_PREFIX)));
+    try {
+        return (await buildAndImport(dir, dir, stage)).m;
+    }
+    finally {
+        await rm(stage, { recursive: true, force: true });
+    }
+}
 /**
  * Bundles the extension `src/index.ts`:
  * 1. esbuild bundles it into the single-file ESM `dist/index.mjs` (platform node, target node24),
@@ -371,6 +427,8 @@ async function contentFiles(dir, label, m) {
  * 2. the bundle's imports are checked (allowlist, no non-literal dynamic import), the bundle is
  *    imported and its default export goes through defineExtension; `staticManifestOf` gives the
  *    static manifest, whose version must equal the package.json version;
+ *    the config schemas become `extension.configSchemas` (`configJsonSchema`; refused when their
+ *    hints have problems, {@link extensionConfigSchemas});
  * 3. `migrations/` (when the manifest declares migrations, which must resolve to the plugin's
  *    `migrations/`), `ui/` (when present) and THIRD-PARTY-NOTICES.txt join the files.
  *
@@ -379,41 +437,14 @@ async function contentFiles(dir, label, m) {
 async function bundleExtension(dir, label, pkgVersion) {
     const stage = await realpath(await mkdtemp(join(tmpdir(), STAGING_PREFIX)));
     try {
-        await linkHostPackages(dir, stage);
-        const entryOut = join(stage, "package", EXTENSION_ENTRY);
-        const result = await build({
-            absWorkingDir: dir,
-            entryPoints: [join(dir, "src/index.ts")],
-            outfile: entryOut,
-            bundle: true,
-            platform: "node",
-            format: "esm",
-            target: "node24",
-            external: [...HOST_PROVIDED_PACKAGES],
-            plugins: [nodeBuiltins],
-            banner: { js: BANNER },
-            define: DEFINE,
-            charset: "utf8",
-            logLevel: "silent",
-            metafile: true,
-            // Notices of bundled dependencies go to THIRD-PARTY-NOTICES.txt (built from the metafile).
-            legalComments: "none",
-        });
-        if (result.errors.length > 0) {
-            throw new Error(`${label}: esbuild failed: ${result.errors.map((e) => e.text).join("; ")}`);
-        }
-        const code = await readFile(entryOut);
-        const issues = await importIssues(code.toString("utf8"));
-        if (issues.length > 0)
-            throw new Error(`${label}: ${issues.join("; ")}`);
-        const mod = await importBundle(entryOut);
-        if (typeof mod.default !== "object" || mod.default === null) {
-            throw new Error(`${label}: the bundle has no default export object`);
-        }
-        const m = defineExtension(mod.default);
+        const { code, m, inputs } = await buildAndImport(dir, label, stage);
         if (m.version !== pkgVersion) {
             throw new Error(`${label}: manifest version ${m.version} does not match package.json version ${String(pkgVersion)}`);
         }
+        const config = extensionConfigSchemas(m.config);
+        if (config.problems.length > 0) {
+            throw new Error(`${label}: invalid config UI hints: ${config.problems.map(formatConfigSchemaProblem).join("; ")}`);
+        }
         const files = new Map([[EXTENSION_ENTRY, code]]);
         const extension = {
             entry: `./${EXTENSION_ENTRY}`,
@@ -435,7 +466,10 @@ async function bundleExtension(dir, label, pkgVersion) {
             }
             extension.ui = "./ui";
         }
-        const notices = await thirdPartyNotices(dir, Object.keys(result.metafile?.inputs ?? {}));
+        if (config.schemas.deployment !== undefined || config.schemas.org !== undefined) {
+            extension.configSchemas = config.schemas;
+        }
+        const notices = await thirdPartyNotices(dir, inputs);
         if (notices !== undefined)
             files.set(NOTICES_FILE, Buffer.from(notices));
         return { files, extension };
@@ -504,7 +538,15 @@ export async function packPlugin(pluginDir, outDir) {
     if (pkgIssues.length > 0)
         throw new Error(`${label}: ${pkgIssues.join("; ")}`);
     files.set("package.json", Buffer.from(`${JSON.stringify(pkg, null, 2)}\n`));
-    files.set(PLUGIN_MANIFEST_FILE, Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+    // The packed text is pretty-printed while the config schema caps measure compact JSON: the text
+    // itself must stay under the reader's limit, or the kernel would refuse the package unread.
+    const manifestText = `${JSON.stringify(manifest, null, 2)}\n`;
+    if (manifestText.length > PLUGIN_MANIFEST_LIMITS.manifestChars) {
+        throw new Error(`${label}: packed ${PLUGIN_MANIFEST_FILE} is ${manifestText.length} characters, over the ` +
+            `${PLUGIN_MANIFEST_LIMITS.manifestChars} limit (PLUGIN_MANIFEST_LIMITS.manifestChars); ` +
+            "make the config schemas smaller");
+    }
+    files.set(PLUGIN_MANIFEST_FILE, Buffer.from(manifestText));
     const tgz = await makeTgz(files);
     await mkdir(outDir, { recursive: true });
     const file = resolve(outDir, tgzName(String(srcPkg.name), String(srcPkg.version)));

package/package.json

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