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

package/dist/marketplace/marketplace.js

@@ -4,16 +4,22 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { isSensitivePermissionKey, PACKAGES_MAX_BYTES_DEFAULT, permissionKeys, permissionSetOfPackage, readExtensionPackage, WARNINGS_KEY_PREFIX, } from "@capybara-hq/kernel";
-import { MARKETPLACE_LIMITS, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { MARKETPLACE_LIMITS, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, parsePluginManifest, pluginDescription, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
 import { discoverPlugins } from "../discover.js";
 import { integrityOf } from "../integrity.js";
 import { packPlugin } from "../pack/pack.js";
+import { compareSemver, parseSemver } from "../release/semver.js";
 export { MARKETPLACE_FILE } from "./file.js";
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-/** The marketplace summary of a plugin: its plugin.json description, cut to the summary limit. */
-function summaryOf(description) {
+/** The marketplace summary text: a description cut to the summary limit. */
+function cut(text) {
     const max = MARKETPLACE_LIMITS.summaryChars;
-    return description.length <= max ? description : `${description.slice(0, max - 1)}…`;
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/** The marketplace summary of a plugin: its plugin.json description (`{ en, zh? }`), each cut. */
+function summaryOf(description) {
+    const d = pluginDescription(description);
+    return { en: cut(d.en), ...(d.zh !== undefined && { zh: cut(d.zh) }) };
 }
 /** The permission summary of a packed plugin, as the kernel computes it at import (display only). */
 async function permissionsOf(bytes, hasExtension) {
@@ -30,29 +36,70 @@ async function permissionsOf(bytes, hasExtension) {
 }
 /** An entry's version: `version`, else its npm source's. */
 const versionOf = (e) => e.version ?? ("npm" in e.source ? e.source.npm.version : undefined);
+/** The display fields of a plugin's source plugin.json; undefined when it does not parse. */
+function displayOf(json) {
+    const m = parsePluginManifest(json);
+    if ("errors" in m)
+        return undefined;
+    return {
+        summary: summaryOf(m.description),
+        ...(m.displayName !== undefined && { displayName: m.displayName }),
+    };
+}
 /**
- * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing every
- * published version of its public plugins (package ecosystem spec §5.2; one entry per
- * `(name, version)`, Decision 7 of phase A3b). Each public plugin (not `"private": true`) is packed
- * reproducibly with {@link packPlugin}; when the file has no entry for its name and version, an
- * entry `{ name, version, summary, homepage?, permissions, source: { npm: { package, version,
- * integrity } } }` is added (`integrity` the pack's sha512, which the release then publishes
- * byte for byte; `permissions` display only). A version already listed is not packed or compared:
- * once published, its bytes are the release gate's business (`release --marketplace`), so a later
- * source or toolchain change at the same version is not a finding. With `base`, published entries
- * must be unchanged and first in order, and entries added since must match the tree's packs.
- * Entries of versions no longer in the tree are kept, so a pinned commit lists what it pins and
- * older versions stay importable. The file is written formatted as Biome formats it
- * ({@link formatMarketplaceJson}).
- * With `write`, the new entries are appended in plugin order (nothing is written when there is any
- * other finding).
+ * `raw` with its `summary` and `displayName` set to `d` (in place, `displayName` right after
+ * `summary` when it is new, removed when plugin.json has none); undefined when they already equal.
+ */
+function refreshDisplay(raw, d) {
+    if (!isObj(raw))
+        return undefined;
+    if (canonical(raw.summary) === canonical(d.summary) &&
+        canonical(raw.displayName) === canonical(d.displayName)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (k === "displayName")
+            continue;
+        out[k] = k === "summary" ? d.summary : v;
+        if (k === "summary" && d.displayName !== undefined)
+            out.displayName = d.displayName;
+    }
+    if (!("summary" in raw)) {
+        out.summary = d.summary;
+        if (d.displayName !== undefined)
+            out.displayName = d.displayName;
+    }
+    return out;
+}
+/**
+ * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing one entry
+ * per public plugin, its current version (plugin component management spec §13.2, replacing the
+ * one-entry-per-version rule of the package ecosystem spec §5.2). Each public plugin (not
+ * `"private": true`) not listed at its version is packed reproducibly with {@link packPlugin} and
+ * gets an entry `{ name, version, summary, displayName?, homepage?, permissions, source: { npm: {
+ * package, version, integrity } } }` (`summary` from the plugin.json `description`, a string being
+ * `en`; `displayName` copied from plugin.json; `integrity` the pack's sha512, which the release
+ * then publishes byte for byte; `permissions` display only). The new entry takes the place of the
+ * plugin's first entry (a version that moved), the plugin's other entries are dropped (also those
+ * of a file written in the older one-entry-per-version form), and a plugin not listed yet is
+ * appended. Entries of plugins not in the tree are kept. A version already listed is not packed or
+ * compared: once published, its bytes are the release gate's business (`release --marketplace`),
+ * so a later source or toolchain change at the same version is not a finding; only its display
+ * fields (`summary`, `displayName`) are refreshed from the source plugin.json. Every other field
+ * of a kept entry stays as written, among them `deprecated`, which the maintainer sets by hand on
+ * a published version's entry (not in plugin.json: that would change the packed bytes); a new
+ * version's entry has none, and no rule compares it with the base. With `base`, see
+ * {@link SyncMarketplaceOptions.base}. The file is written formatted as Biome formats it
+ * ({@link formatMarketplaceJson}); nothing is written when there is any other finding.
  */
 export async function syncMarketplace(opts) {
     const findings = [];
     const at = (rule, message) => findings.push({ file: opts.file, line: 1, rule, message });
+    const none = () => ({ added: [], removed: [], refreshed: [], findings });
     if (!existsSync(opts.file)) {
         at("marketplace-invalid", `${opts.file} does not exist: create it with schemaVersion, name, owner and "plugins": []`);
-        return { added: [], findings };
+        return none();
     }
     let raw;
     try {
@@ -60,22 +107,23 @@ export async function syncMarketplace(opts) {
     }
     catch (e) {
         at("marketplace-invalid", `not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
-        return { added: [], findings };
+        return none();
     }
     const parsed = parseMarketplaceManifest(raw);
     if ("errors" in parsed) {
         at("marketplace-invalid", parsed.errors.join("; "));
-        return { added: [], findings };
+        return none();
     }
+    // The parser keeps the order, so parsed.plugins[i] is rawEntries[i].
     const rawEntries = isObj(raw) && Array.isArray(raw.plugins) ? raw.plugins : [];
-    /** `name@version` of the entries added since `opts.base` (all of them without a base). */
-    let addedSinceBase;
+    /** `name@version` of the entries the base lists (undefined without a base). */
+    let baseKeys;
     if (opts.base !== undefined) {
         const baseEntries = entriesAt(opts.root, opts.file, opts.base);
-        findings.push(...appendOnly(baseEntries, rawEntries, opts.file));
-        addedSinceBase = new Set(rawEntries.slice(baseEntries.length).map((e) => keyOfRaw(e)));
+        findings.push(...publishedRules(baseEntries, rawEntries, opts.file));
+        baseKeys = new Set(baseEntries.map(keyOfRaw));
     }
-    const added = [];
+    const updates = [];
     const out = await mkdtemp(join(tmpdir(), "capybara-marketplace-"));
     try {
         for (const dir of discoverPlugins(opts.root, opts.plugins)) {
@@ -87,15 +135,33 @@ export async function syncMarketplace(opts) {
             if (pkg.private === true)
                 continue;
             const source = JSON.parse(await readFile(manifestFile, "utf8"));
+            // (the display fields of a listed entry are refreshed from this source plugin.json)
             const name = String(source.name);
             const version = String(pkg.version);
-            const listed = parsed.plugins.filter((e) => e.name === name && versionOf(e) === version);
+            const mine = parsed.plugins.flatMap((e, i) => (e.name === name ? [{ e, i }] : []));
+            const listed = mine.filter(({ e }) => versionOf(e) === version);
+            const dropped = mine
+                .filter(({ e }) => versionOf(e) !== version)
+                .map(({ e }) => `${name}@${versionOf(e) ?? "(no version)"}`);
             // A version already listed is published (or about to be): its bytes are the release gate's
             // business, so a later source or toolchain change at the same version is not a finding here.
             // Only an entry added since the base is compared with the tree's pack.
-            const toCompare = listed.filter((e) => addedSinceBase?.has(`${e.name}@${versionOf(e)}`));
-            if (listed.length > 0 && toCompare.length === 0)
+            const toCompare = listed.filter(({ e }) => baseKeys !== undefined && !baseKeys.has(keyOf(e)));
+            const kept = listed[0];
+            /** Keeps the listed entry: drops the other versions, refreshes its display fields. */
+            const keep = (raw) => {
+                const display = displayOf(source);
+                const fresh = display === undefined ? undefined : refreshDisplay(raw, display);
+                if (dropped.length > 0 || fresh !== undefined) {
+                    const entry = fresh ?? raw;
+                    updates.push({ name, version, entry, isNew: false, dropped, refreshed: !!fresh });
+                }
+            };
+            if (kept !== undefined && toCompare.length === 0) {
+                keep(rawEntries[kept.i]);
                 continue;
+            }
+            // Packed: the plugin is not listed at its version, or its entry is new since the base.
             const r = await packPlugin(dir, out);
             const bytes = new Uint8Array(await readFile(r.file));
             const npm = {
@@ -103,7 +169,7 @@ export async function syncMarketplace(opts) {
                 version: r.manifest.version,
                 integrity: integrityOf(bytes),
             };
-            for (const e of toCompare) {
+            for (const { e } of toCompare) {
                 const src = "npm" in e.source ? e.source.npm : undefined;
                 if (src?.package !== npm.package || src.integrity !== npm.integrity) {
                     const was = src === undefined
@@ -113,39 +179,76 @@ export async function syncMarketplace(opts) {
                         `with integrity ${npm.integrity}: run capybara-plugin marketplace --write`);
                 }
             }
-            if (listed.length > 0)
+            if (kept !== undefined) {
+                keep(rawEntries[kept.i]);
                 continue;
-            added.push({
+            }
+            const entry = {
                 name: r.manifest.name,
                 version: npm.version,
-                summary: { en: summaryOf(r.manifest.description) },
+                summary: summaryOf(r.manifest.description),
+                ...(r.manifest.displayName !== undefined && { displayName: r.manifest.displayName }),
                 ...(r.manifest.homepage !== undefined && { homepage: r.manifest.homepage }),
                 permissions: await permissionsOf(bytes, r.manifest.extension !== undefined),
                 source: { npm },
-            });
+            };
+            updates.push({ name, version, entry, isNew: true, dropped, refreshed: false });
         }
     }
     finally {
         await rm(out, { recursive: true, force: true });
     }
+    const added = updates.filter((u) => u.isNew).map((u) => u.entry);
+    const removed = updates.flatMap((u) => u.dropped);
+    const refreshed = updates.filter((u) => u.refreshed).map((u) => `${u.name}@${u.version}`);
     if (!opts.write) {
-        for (const e of added) {
-            at("marketplace-missing", `${e.name}@${e.version} is not listed: run capybara-plugin marketplace --write`);
+        for (const u of updates) {
+            if (u.refreshed) {
+                at("marketplace-display-stale", `${u.name}@${u.version} has a summary or displayName other than its plugin.json's: ` +
+                    "run capybara-plugin marketplace --write");
+            }
+            if (!u.isNew && u.dropped.length === 0)
+                continue;
+            const also = u.dropped.map((d) => d.slice(u.name.length + 1)).join(", ");
+            at("marketplace-missing", u.isNew
+                ? `${u.name}@${u.version} is not listed${also === "" ? "" : ` (the marketplace lists ${also})`}: ` +
+                    "one entry per plugin, its current version; run capybara-plugin marketplace --write"
+                : `${u.name}@${u.version} is not the plugin's only entry (also ${also}): ` +
+                    "one entry per plugin, its current version; run capybara-plugin marketplace --write");
+        }
+        return { added, removed, refreshed, findings };
+    }
+    if (findings.length > 0 || updates.length === 0)
+        return { added, removed, refreshed, findings };
+    const byName = new Map(updates.map((u) => [u.name, u]));
+    const placed = new Set();
+    const plugins = [];
+    for (const e of rawEntries) {
+        const name = isObj(e) ? String(e.name) : "";
+        const u = byName.get(name);
+        if (u === undefined) {
+            plugins.push(e);
+        }
+        else if (!placed.has(name)) {
+            placed.add(name);
+            plugins.push(u.entry);
         }
-        return { added, findings };
     }
-    if (findings.length > 0 || added.length === 0)
-        return { added, findings };
+    for (const u of updates)
+        if (!placed.has(u.name))
+            plugins.push(u.entry);
     const next = isObj(raw) ? { ...raw } : {};
-    next.plugins = [...(Array.isArray(next.plugins) ? next.plugins : []), ...added];
+    next.plugins = plugins;
     const check = parseMarketplaceManifest(next);
     if ("errors" in check) {
         at("marketplace-invalid", `the new entries do not parse: ${check.errors.join("; ")}`);
-        return { added, findings };
+        return { added, removed, refreshed, findings };
     }
     await writeFile(opts.file, formatMarketplaceJson(next));
-    return { added, findings };
+    return { added, removed, refreshed, findings };
 }
+/** `name@version` of a parsed entry (`?` without a version). */
+const keyOf = (e) => `${e.name}@${versionOf(e) ?? "?"}`;
 /** `name@version` of a raw entry (`?` for what is missing). */
 function keyOfRaw(e) {
     if (!isObj(e))
@@ -153,7 +256,7 @@ function keyOfRaw(e) {
     const npm = isObj(e.source) && isObj(e.source.npm) ? e.source.npm : {};
     return `${String(e.name ?? "?")}@${String(e.version ?? npm.version ?? "?")}`;
 }
-/** JSON with object keys sorted (deep equality of entries regardless of key order). */
+/** JSON with object keys sorted (deep equality regardless of key order). */
 function canonical(v) {
     if (Array.isArray(v))
         return `[${v.map(canonical).join(",")}]`;
@@ -184,25 +287,68 @@ function entriesAt(root, file, base) {
     const raw = JSON.parse(text);
     return isObj(raw) && Array.isArray(raw.plugins) ? raw.plugins : [];
 }
+/** A raw entry's version when it is a plain semver (else undefined: not ordered). */
+function semverOfRaw(e) {
+    const v = keyOfRaw(e).split("@").pop();
+    return v !== undefined && parseSemver(v) !== undefined ? v : undefined;
+}
 /**
- * `marketplace-append-only`: the base's entries are published, so the current list must start with
- * exactly them, in the same order (an entry is never edited, removed or moved; new ones go last).
+ * The rules on the entries published at the base: `marketplace-integrity`, a version the base
+ * lists keeps its source (package and integrity); `marketplace-version-decrease`, a version the
+ * base does not list must be newer than every version the base lists for that plugin, and a
+ * plugin's newest listed version may not be older than the newest the base lists. Display
+ * fields (summary, displayName, permissions, homepage) may change, entries may move, and a
+ * plugin's older versions may go (one entry per plugin).
  */
-function appendOnly(base, current, file) {
+function publishedRules(base, current, file) {
     const out = [];
-    base.forEach((b, i) => {
-        const c = current[i];
-        if (c !== undefined && canonical(c) === canonical(b))
-            return;
-        const key = keyOfRaw(b);
-        const moved = current.some((x) => canonical(x) === canonical(b));
-        out.push({
-            file,
-            line: 1,
-            rule: "marketplace-append-only",
-            message: `${key} is published at the base and ${moved ? "moved" : c !== undefined && keyOfRaw(c) === key ? "was edited" : "went away"}: published entries never change and new ones are appended at the end`,
-        });
-    });
+    const finding = (rule, message) => out.push({ file, line: 1, rule, message });
+    const baseByKey = new Map(base.map((b) => [keyOfRaw(b), b]));
+    const newest = new Map();
+    for (const b of base) {
+        const v = semverOfRaw(b);
+        const name = isObj(b) ? String(b.name) : "?";
+        const top = newest.get(name);
+        if (v !== undefined && (top === undefined || compareSemver(v, top) > 0))
+            newest.set(name, v);
+    }
+    /** `name@version` of the entries reported as `marketplace-version-decrease`. */
+    const decreased = new Set();
+    for (const c of current) {
+        const key = keyOfRaw(c);
+        const b = baseByKey.get(key);
+        const src = (e) => (isObj(e) ? e.source : undefined);
+        if (b !== undefined) {
+            if (canonical(src(c)) !== canonical(src(b))) {
+                finding("marketplace-integrity", `${key} is published at the base with the source ${canonical(src(b))}, now ` +
+                    `${canonical(src(c))}: a published version keeps its integrity (bump the version instead)`);
+            }
+            continue;
+        }
+        const v = semverOfRaw(c);
+        const top = newest.get(isObj(c) ? String(c.name) : "?");
+        if (v !== undefined && top !== undefined && compareSemver(v, top) < 0)
+            decreased.add(key);
+    }
+    // A plugin's newest listed version may not fall below the newest the base lists, also when it
+    // moves back to an older version the base lists too (a base in the older form).
+    const newestNow = new Map();
+    for (const c of current) {
+        const v = semverOfRaw(c);
+        const name = isObj(c) ? String(c.name) : "?";
+        const top = newestNow.get(name);
+        if (v !== undefined && (top === undefined || compareSemver(v, top) > 0))
+            newestNow.set(name, v);
+    }
+    for (const [name, v] of newestNow) {
+        const top = newest.get(name);
+        if (top !== undefined && compareSemver(v, top) < 0)
+            decreased.add(`${name}@${v}`);
+    }
+    for (const key of decreased) {
+        const name = key.slice(0, key.lastIndexOf("@"));
+        finding("marketplace-version-decrease", `${key} is older than ${newest.get(name)}, which the base lists: an entry's version may only increase`);
+    }
     return out;
 }
 const INDENT = "  ";

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