@coda-console/protocol 0.0.0-stage → 1.0.0

package/schemas/plugin/setting.json

@@ -0,0 +1,242 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/plugin/v1/setting.json",
+  "title": "一项设置的声明",
+  "description": "插件用 JSON Schema 声明设置，Coda 读的是其中一部分：单个值；多选（items.anyOf 的常量）；多个模型服务；一列行；表格（additionalProperties 是每一项）。表格的每一项是单个值、Agent 组合或几列；一列是单个值或 Agent 组合。格式只认 coda-agent（新会话用什么启动）、coda-agent-match（表格的行名：哪些会话）、duration（ISO 8601 时长）、coda-repo、coda-directory、coda-model-provider（别的插件提供的模型服务）、coda-model-url（模型服务的地址，Key 与接口写在同组的 modelKey、modelApi）。writeOnly 是密文：只写不读，放在数据库旁的文件里。",
+  "$ref": "#/$defs/setting",
+  "$defs": {
+    "base": {
+      "type": "object",
+      "properties": {
+        "type": {"description": "type 取 boolean、integer、number、string、object、array", "enum": ["boolean", "integer", "number", "string", "object", "array"]},
+        "title": {"type": "string"},
+        "description": {"type": "string"},
+        "markdownDescription": {"type": "string"},
+        "order": {"type": "number"},
+        "default": true,
+        "enum": {"description": "enum 是非空的数组", "type": "array", "minItems": 1},
+        "enumDescriptions": {"type": "array"},
+        "enumItemLabels": {"description": "enumItemLabels 是每个选项显示的文字，各不超过 100 字", "type": "array", "items": {"type": "string", "maxLength": 100}},
+        "minimum": {"type": "number"},
+        "maximum": {"type": "number"},
+        "format": {
+          "description": "format 只认 coda-agent、coda-agent-match、duration、coda-repo、coda-directory、coda-model-provider、coda-model-url",
+          "enum": ["coda-agent", "coda-agent-match", "duration", "coda-repo", "coda-directory", "coda-model-provider", "coda-model-url"]
+        }
+      },
+      "required": ["type"],
+      "allOf": [
+        {
+          "if": {"properties": {"format": {"const": "coda-agent"}}, "required": ["format"]},
+          "then": {"description": "coda-agent 是对象", "properties": {"type": {"const": "object"}}}
+        },
+        {
+          "if": {
+            "properties": {"format": {"enum": ["duration", "coda-repo", "coda-directory", "coda-model-provider", "coda-model-url"]}},
+            "required": ["format"]
+          },
+          "then": {"description": "duration、coda-repo、coda-directory、coda-model-provider、coda-model-url 是文本", "properties": {"type": {"const": "string"}}}
+        },
+        {"if": {"required": ["enum"]}, "then": {"description": "enum 只用于文本与数字", "properties": {"type": {"enum": ["string", "integer", "number"]}}}},
+        {"if": {"required": ["enumItemLabels"]}, "then": {"description": "enumItemLabels 跟着 enum 写", "required": ["enum"]}},
+        {
+          "if": {"anyOf": [{"required": ["modelKey"]}, {"required": ["modelApi"]}]},
+          "then": {
+            "description": "modelKey 与 modelApi 只写在 coda-model-url 的地址上",
+            "properties": {"format": {"const": "coda-model-url"}},
+            "required": ["format"]
+          }
+        }
+      ]
+    },
+    "secret": {"description": "writeOnly 是开或关", "type": "boolean"},
+    "modelKey": {
+      "description": "modelKey 是同组的一个密文的名字",
+      "type": "string",
+      "x-ref": {"pointer": "2", "match": {"properties": {"writeOnly": {"const": true}}, "required": ["writeOnly"]}}
+    },
+    "modelApi": {
+      "description": "modelApi 是同组的一个文本（不是密文）的名字",
+      "type": "string",
+      "x-ref": {"pointer": "2", "match": {"properties": {"type": {"const": "string"}, "writeOnly": {"const": false}}, "required": ["type"]}}
+    },
+    "setting": {
+      "description": "插件的一项设置",
+      "$ref": "#/$defs/base",
+      "properties": {
+        "writeOnly": {"$ref": "#/$defs/secret"},
+        "modelKey": {"$ref": "#/$defs/modelKey"},
+        "modelApi": {"$ref": "#/$defs/modelApi"},
+        "items": true,
+        "uniqueItems": {"description": "uniqueItems 只能是 true（每项至多一次）", "const": true},
+        "additionalProperties": true,
+        "propertyNames": true
+      },
+      "unevaluatedProperties": false,
+      "allOf": [
+        {
+          "if": {"properties": {"writeOnly": {"const": true}}, "required": ["writeOnly"]},
+          "then": {
+            "description": "密文设置（writeOnly）只能是没有 format、enum 与默认值的文本",
+            "properties": {"type": {"const": "string"}},
+            "not": {"anyOf": [{"required": ["format"]}, {"required": ["enum"]}, {"required": ["default"]}]}
+          }
+        },
+        {
+          "if": {"properties": {"type": {"const": "array"}}, "required": ["type"]},
+          "then": {"$ref": "#/$defs/array"},
+          "else": {
+            "description": "只有多选、多个模型服务与一列行（type: array）才写 items 与 uniqueItems",
+            "not": {"anyOf": [{"required": ["items"]}, {"required": ["uniqueItems"]}]}
+          }
+        },
+        {
+          "if": {
+            "properties": {"type": {"const": "object"}},
+            "required": ["type"],
+            "not": {"properties": {"format": {"const": "coda-agent"}}, "required": ["format"]}
+          },
+          "then": {
+            "description": "表格写 additionalProperties（每一项是什么）；propertyNames 只能是 { format: coda-agent-match }",
+            "required": ["additionalProperties"],
+            "properties": {
+              "additionalProperties": {"$ref": "#/$defs/entry"},
+              "propertyNames": {
+                "description": "propertyNames 只支持 format: coda-agent-match",
+                "type": "object",
+                "properties": {"format": {"const": "coda-agent-match"}},
+                "required": ["format"],
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      ]
+    },
+    "array": {
+      "description": "多选、多个模型服务与一列行写 items，不写 format、minimum 与 maximum",
+      "required": ["items"],
+      "not": {"anyOf": [{"required": ["format"]}, {"required": ["minimum"]}, {"required": ["maximum"]}]},
+      "if": {"properties": {"items": {"properties": {"format": {"const": "coda-model-provider"}}, "required": ["format"]}}},
+      "then": {"properties": {"items": {"$ref": "#/$defs/modelProviders"}}},
+      "else": {
+        "if": {"properties": {"items": {"properties": {"type": {"const": "object"}}, "required": ["type"]}}},
+        "then": {"description": "一列行不写 uniqueItems", "not": {"required": ["uniqueItems"]}, "properties": {"items": {"$ref": "#/$defs/rows"}}},
+        "else": {"properties": {"items": {"$ref": "#/$defs/options"}}}
+      }
+    },
+    "modelProviders": {
+      "description": "多个模型服务写 items: { type: string, format: coda-model-provider, modelApis }",
+      "type": "object",
+      "properties": {
+        "type": {"const": "string"},
+        "format": {"const": "coda-model-provider"},
+        "modelApis": {
+          "description": "modelApis 是 1–10 个接口名，取 openai-completions、openai-responses、anthropic-messages",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 10,
+          "items": {"enum": ["openai-completions", "openai-responses", "anthropic-messages"]}
+        }
+      },
+      "required": ["type", "format"],
+      "additionalProperties": false
+    },
+    "rows": {
+      "description": "一列行写 items: { type: object, properties, required }",
+      "$ref": "#/$defs/entry",
+      "required": ["properties"],
+      "not": {"required": ["format"]},
+      "properties": {
+        "properties": {
+          "additionalProperties": {"description": "一列行的列不能是密文，要密文用表格", "not": {"properties": {"writeOnly": {"const": true}}, "required": ["writeOnly"]}}
+        }
+      }
+    },
+    "options": {
+      "description": "多选写 items: { anyOf: [{ const, title, description }] }，1–50 项",
+      "type": "object",
+      "properties": {
+        "anyOf": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "description": "多选的一项是 { const, title, description }：const 只用字母、数字和「._-」，title 与 description 不超过 400 字",
+            "type": "object",
+            "properties": {
+              "const": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"},
+              "title": {"type": "string", "maxLength": 400},
+              "description": {"type": "string", "maxLength": 400}
+            },
+            "required": ["const"],
+            "additionalProperties": false
+          },
+          "x-unique-by": ["const"]
+        }
+      },
+      "required": ["anyOf"],
+      "additionalProperties": false
+    },
+    "entry": {
+      "description": "表格的一项：单个值、Agent 组合，或 properties 写明的 1–20 列",
+      "$ref": "#/$defs/base",
+      "properties": {"properties": true, "required": true},
+      "unevaluatedProperties": false,
+      "allOf": [
+        {"if": {"properties": {"type": {"const": "array"}}, "required": ["type"]}, "then": {"description": "多选与一列行只能是插件的一项设置，不能放进表格", "not": {}}},
+        {
+          "if": {"properties": {"type": {"const": "object"}}, "required": ["type"]},
+          "then": {
+            "description": "表格的每一项只能是单个值、Agent 组合，或 properties 写明的 1–20 列",
+            "anyOf": [{"properties": {"format": {"const": "coda-agent"}}, "required": ["format"]}, {"required": ["properties"]}]
+          }
+        },
+        {
+          "if": {"anyOf": [{"required": ["properties"]}, {"required": ["required"]}]},
+          "then": {"description": "只有一行几列时才写 properties 与 required", "properties": {"type": {"const": "object"}}, "not": {"required": ["format"]}}
+        },
+        {"if": {"required": ["properties"]}, "then": {"$ref": "#/$defs/row"}}
+      ]
+    },
+    "row": {
+      "properties": {
+        "properties": {
+          "description": "一行写 1–20 列；一行是一组，至多一个模型地址（coda-model-url）：检查可用模型按组找它",
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 20,
+          "propertyNames": {"description": "列名只用字母和数字，以小写字母开头", "pattern": "^[a-z][A-Za-z0-9]{0,39}$"},
+          "additionalProperties": {"$ref": "#/$defs/column"},
+          "x-max-contains": {"match": {"properties": {"format": {"const": "coda-model-url"}}, "required": ["format"]}, "max": 1}
+        },
+        "required": {
+          "description": "required 是本行的列名，不重复",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {"description": "required 是本行的列名，不重复", "type": "string", "x-ref": {"pointer": "2/properties"}}
+        }
+      }
+    },
+    "column": {
+      "description": "一列：单个值或 Agent 组合",
+      "$ref": "#/$defs/base",
+      "properties": {"writeOnly": {"$ref": "#/$defs/secret"}, "modelKey": {"$ref": "#/$defs/modelKey"}, "modelApi": {"$ref": "#/$defs/modelApi"}},
+      "unevaluatedProperties": false,
+      "allOf": [
+        {
+          "if": {"properties": {"writeOnly": {"const": true}}, "required": ["writeOnly"]},
+          "then": {
+            "description": "密文设置（writeOnly）只能是没有 format、enum 与默认值的文本",
+            "properties": {"type": {"const": "string"}},
+            "not": {"anyOf": [{"required": ["format"]}, {"required": ["enum"]}, {"required": ["default"]}]}
+          }
+        },
+        {
+          "if": {"properties": {"type": {"enum": ["object", "array"]}}, "required": ["type"]},
+          "then": {"description": "一列只能是单个值或 Agent 组合", "properties": {"format": {"const": "coda-agent"}}, "required": ["format"]}
+        }
+      ]
+    }
+  }
+}

package/schemas/plugin/setup.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/plugin/v1/setup.json",
+  "title": "contributes.setup：准备运行环境",
+  "description": "用户安装或更新插件后运行的一行命令。",
+  "$ref": "common.json#/$defs/commandHolder"
+}

package/schemas/plugin/skills.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/plugin/v1/skills.json",
+  "title": "contributes.skills：插件带来的 Agent Skill",
+  "description": "插件目录里的目录，每个有自己的 SKILL.md；Agent 按目录名找到它，所以目录名不重复。",
+  "type": "array",
+  "maxItems": 100,
+  "items": {
+    "description": "插件目录里的相对路径，目录名只用字母、数字、「.」「_」「-」，里面有 SKILL.md",
+    "type": "string",
+    "pattern": "^(?!/)(?!(.*/)?\\.\\.(/|$))(?!\\.?/*$)(.*/)?[A-Za-z0-9][A-Za-z0-9._-]{0,63}/*$",
+    "x-file": {"type": "directory", "contains": "SKILL.md"}
+  },
+  "x-unique-by": [{"part": "([^/]+)/*$"}]
+}

package/schemas/plugin/views.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/plugin/v1/views.json",
+  "title": "contributes.views：客户端为插件打开的页面",
+  "description": "插件目录里的 HTML，客户端在沙箱里开：在哪常驻（side 会话旁、page 一页），图标，接管打开的引用种类（handles，像 VS Code 的自定义编辑器），读数（readout）与只给哪种工作位置的会话（checkout）。",
+  "type": "array",
+  "maxItems": 10,
+  "items": {
+    "type": "object",
+    "properties": {
+      "id": {"$ref": "common.json#/$defs/id"},
+      "title": {"$ref": "common.json#/$defs/line40"},
+      "entry": {"description": "插件目录里的 .html 文件", "type": "string", "pattern": "^(?!/)(?!(.*/)?\\.\\.(/|$)).*\\.html$", "x-file": {"type": "file"}},
+      "in": {"description": "它常驻的位置：side、page，不重复", "type": "array", "uniqueItems": true, "items": {"enum": ["side", "page"]}},
+      "icon": {"$ref": "common.json#/$defs/symbol"},
+      "handles": {
+        "description": "它接管打开的引用种类（如 workflow-runs），至多 8 个，不重复",
+        "type": "array",
+        "maxItems": 8,
+        "uniqueItems": true,
+        "items": {"$ref": "common.json#/$defs/id"}
+      },
+      "readout": {"description": "读数：workflow-runs、machines、changes", "enum": ["workflow-runs", "machines", "changes"]},
+      "checkout": {"description": "只给哪种工作位置的会话：worktree", "enum": ["worktree"]}
+    },
+    "required": ["id", "title", "entry"],
+    "additionalProperties": false
+  },
+  "x-unique-by": ["id"]
+}

package/validate.mjs

@@ -0,0 +1,182 @@
+// A plugin is right when what it writes is of the types it names: each key of a manifest's `contributes` is a type with a
+// JSON Schema of its own (schemas/plugin/, `https://coda.pub/schemas/plugin/v1/…`), and a key that is no type of Coda's is
+// one a plugin's extension point declares, for that plugin to read. Checking one is checking it against those schemas,
+// nothing else: a field joins a type by joining its schema, never by a rule here. Coda checks a plugin with this module
+// when it reads one, and coda-plugins' contract check does where a plugin is written.
+// What JSON Schema cannot say of one value alone it says with five keywords, each meaning one thing wherever it is written,
+// as Kubernetes extends its OpenAPI with `x-kubernetes-*`:
+// - `x-unique-by`: [name or { part }] — in an array, each named property of its objects is unique among the items having it,
+//   and so is `part`'s first group of each of its texts (a directory's last name);
+// - `x-max-contains`: { match, max } — of an object's values, at most `max` satisfy `match` (`maxContains` of an object);
+// - `x-ref`: { pointer, part?, match? } — the value (or `part`'s first group of it) names a key of the object, or an element
+//   of the array, at `pointer` in the manifest: absolute (`/contributes/configuration/properties`), or relative to the value
+//   (`2/properties`: two levels up, then down); what it names satisfies `match` when that is given;
+// - `x-placeholders`: { names?, config? } — every `${…}` in the text is one of `names`, or `config:<setting>` naming one of
+//   the plugin's settings that satisfies `config`;
+// - `x-file`: { type, under?, suffix?, contains?, maxBytes?, magic?, absent? } — the value is a path in the plugin's directory
+//   (with `under` before it and `suffix` after it) that never leaves it, of that type, holding `contains`, at most
+//   `maxBytes` long, starting with `magic`; with `absent`, a path there is none at. Checked when the directory is known.
+// It imports nothing but Node and Ajv.
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
+import { isAbsolute, join, normalize, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+export const SCHEMA_DIR = fileURLToPath(new URL('./schemas/plugin/', import.meta.url));
+const BASE = 'https://coda.pub/schemas/plugin/v1/';
+// The schemas, by file name.
+export const SCHEMAS = Object.fromEntries(readdirSync(SCHEMA_DIR).filter(file => file.endsWith('.json')).sort()
+  .map(file => [file, JSON.parse(readFileSync(join(SCHEMA_DIR, file), 'utf8'))]));
+// The types a plugin may contribute to Coda itself, as the manifest's schema names them.
+export const TYPES = Object.keys(SCHEMAS['plugin.json'].properties.contributes.properties);
+
+// What a pointer names, from where a keyword is: the manifest's root, or levels up from the value itself.
+function locate(pointer, { rootData, instancePath }) {
+  const relative = /^(\d+)(.*)$/.exec(pointer);
+  const up = relative ? Number(relative[1]) : 0, rest = relative ? relative[2] : pointer;
+  const here = instancePath.split('/').slice(1).map(unescape);
+  if (up > here.length) return undefined;
+  const steps = [...(relative ? here.slice(0, here.length - up) : []), ...rest.split('/').slice(1).map(unescape)];
+  return steps.reduce((at, step) => at !== null && typeof at === 'object' && Object.hasOwn(at, step) ? at[step] : undefined, rootData);
+}
+const unescape = step => step.replace(/~1/g, '/').replace(/~0/g, '~');
+const fail = (validate, keyword, message, parentSchema) => { validate.errors = [{ keyword, message, params: {}, parentSchema }]; return false; };
+
+function keywords(ajv) {
+  ajv.addKeyword({
+    keyword: 'x-max-contains', type: 'object', schemaType: 'object',
+    compile({ match, max }) {
+      const matcher = ajv.compile(match);
+      return value => Object.values(value).filter(each => matcher(each)).length <= max;
+    },
+  });
+  ajv.addKeyword({
+    keyword: 'x-unique-by', type: 'array', schemaType: 'array', errors: true,
+    validate: function unique(keys, items, parentSchema) {
+      for (const key of keys) {
+        const part = typeof key === 'object' ? new RegExp(key.part, 'u') : null, seen = new Set();
+        for (const item of items) {
+          const value = part ? (typeof item === 'string' ? part.exec(item)?.[1] : undefined)
+            : item && typeof item === 'object' && Object.hasOwn(item, key) ? item[key] : undefined;
+          if (value === undefined) continue;
+          const said = JSON.stringify(value);
+          if (seen.has(said)) return fail(unique, 'x-unique-by', part ? `不能重复：${value}` : `${key} 不能重复：${value}`, parentSchema);
+          seen.add(said);
+        }
+      }
+      return true;
+    },
+  });
+  // A reference: whether `name` is a key (or element) of what `pointer` names, and that satisfies `match`.
+  const resolves = (ref, matcher, name, cxt) => {
+    const at = locate(ref.pointer, cxt);
+    if (Array.isArray(at)) return at.includes(name);
+    if (!at || typeof at !== 'object' || !Object.hasOwn(at, name)) return false;
+    return !matcher || matcher(at[name]);
+  };
+  ajv.addKeyword({
+    keyword: 'x-ref', type: 'string', schemaType: 'object',
+    compile(ref) {
+      const matcher = ref.match ? ajv.compile(ref.match) : null, part = ref.part ? new RegExp(ref.part, 'u') : null;
+      return (value, cxt) => {
+        const name = part ? part.exec(value)?.[1] : value;
+        return name !== undefined && resolves(ref, matcher, name, cxt);
+      };
+    },
+  });
+  ajv.addKeyword({
+    keyword: 'x-placeholders', type: 'string', schemaType: 'object',
+    compile(allowed) {
+      const config = allowed.config ? { pointer: '/contributes/configuration/properties' } : null, matcher = allowed.config ? ajv.compile(allowed.config) : null;
+      return (value, cxt) => [...value.matchAll(/\$\{([^}]*)\}/g)].every(([, place]) => {
+        if ((allowed.names ?? []).includes(place)) return true;
+        const setting = /^config:(.+)$/.exec(place)?.[1];
+        return !!(config && setting && resolves(config, matcher, setting, cxt));
+      });
+    },
+  });
+  ajv.addKeyword({
+    keyword: 'x-file', type: 'string', schemaType: 'object', errors: true,
+    validate: function file(spec, value, parentSchema) {
+      const dir = this?.dir;
+      const path = normalize(spec.under ? join(spec.under, `${value}${spec.suffix ?? ''}`) : `${value}${spec.suffix ?? ''}`);
+      if (isAbsolute(path) || path === '.' || path === '..' || path.startsWith(`..${sep}`)) return fail(file, 'x-file', `${value} 须为不离开插件目录的相对路径`, parentSchema);
+      if (!dir) return true;
+      let found;
+      try { found = statSync(join(dir, path)); } catch { return spec.absent ? true : fail(file, 'x-file', `插件目录里没有 ${path}`, parentSchema); }
+      if (spec.absent) return fail(file, 'x-file', `插件目录里已有 ${path}`, parentSchema);
+      if (spec.type === 'directory' ? !found.isDirectory() : !found.isFile()) return fail(file, 'x-file', `${path} 须为插件目录里的${spec.type === 'directory' ? '目录' : '文件'}`, parentSchema);
+      if (spec.contains) try { if (!statSync(join(dir, path, spec.contains)).isFile()) throw new Error(); }
+      catch { return fail(file, 'x-file', `${path} 里没有 ${spec.contains}`, parentSchema); }
+      if (spec.maxBytes !== undefined && found.size > spec.maxBytes) return fail(file, 'x-file', `${path} 超过 ${spec.maxBytes / 1024} KiB`, parentSchema);
+      if (spec.magic) {
+        const head = Buffer.alloc(spec.magic.length), fd = openSync(join(dir, path), 'r');
+        try { readSync(fd, head, 0, head.length, 0); } finally { closeSync(fd); }
+        if (head.toString('latin1') !== spec.magic) return fail(file, 'x-file', `${path} 不是 ${spec.magic.replace(/\W/g, '')}`, parentSchema);
+      }
+      return true;
+    },
+  });
+}
+
+const ajv = new Ajv2020({ allErrors: false, verbose: true, passContext: true, strict: true, strictTypes: false, strictRequired: false, allowUnionTypes: true });
+keywords(ajv);
+for (const schema of Object.values(SCHEMAS)) ajv.addSchema(schema);
+// The validators of the schemas here, by file.
+const compiled = new Map();
+const validator = file => {
+  if (!compiled.has(file)) compiled.set(file, ajv.getSchema(`${BASE}${file}`));
+  return compiled.get(file);
+};
+
+// Where in the manifest a value is, as a person writes it: `contributes.composerModes[0].in`.
+const place = (path, base) => path.split('/').slice(1).map(unescape)
+  .reduce((at, step) => /^\d+$/.test(step) ? `${at}[${step}]` : !/^[A-Za-z_$][\w$]*$/.test(step) ? `${at}「${step}」` : at ? `${at}.${step}` : step, base);
+const TYPE_NAMES = { array: '数组', object: '对象', string: '文本', number: '数字', integer: '整数', boolean: '开或关' };
+// What the schema says of a failing value: the description nearest above the keyword that failed (a branch's `then`, a
+// property's), found by where the error says it is, from the schema it failed in (the one a `$ref` names, any of these).
+const nodes = function* (node) {
+  if (!node || typeof node !== 'object') return;
+  yield node;
+  for (const child of Object.values(node)) yield* nodes(child);
+};
+function described(error, { roots = true } = {}) {
+  if (!error.parentSchema) return undefined;
+  if (error.parentSchema.description) return roots || !error.parentSchema.$id ? error.parentSchema.description : undefined;
+  const steps = error.schemaPath.replace(/^#\//, '').split('/').map(unescape).slice(0, -1);
+  for (const root of Object.values(SCHEMAS)) for (const from of nodes(root)) {
+    const path = [from];
+    for (const step of steps) path.push(path.at(-1)?.[step]);
+    if (path.at(-1) !== error.parentSchema) continue;
+    const said = path.slice(0, -1).reverse().find(node => typeof node?.description === 'string');
+    return roots || !said?.$id ? said?.description : undefined;
+  }
+  return undefined;
+}
+// What is wrong, said once: the first error, by its place and what the schema says of the value there.
+// What a whole type says of itself is too much for a key it lacks or one written twice: those say only what is wrong.
+export function explain(errors, base = '') {
+  const [error] = errors;
+  const at = place(error.instancePath, base) || 'package.json', name = error.propertyName ? `「${error.propertyName}」` : '';
+  if (error.keyword === 'x-unique-by') return `${at}${name}：${error.message}`;
+  if (error.keyword === 'required') { const said = described(error, { roots: false }); return `${at} 缺 ${error.params.missingProperty}${said ? `：${said}` : ''}`; }
+  if (error.keyword === 'additionalProperties' || error.keyword === 'unevaluatedProperties')
+    return `${at} 里有不认识的键：${error.params.additionalProperty ?? error.params.unevaluatedProperty}`;
+  const said = described(error);
+  if (error.keyword === 'type') return `${at}${name} 须为${TYPE_NAMES[error.params.type] ?? error.params.type}${said ? `：${said}` : ''}`;
+  if (error.keyword === 'x-file') { const own = described(error, { roots: false }); return `${at}${name}：${error.message}${own ? `（${own}）` : ''}`; }
+  return `${at}${name}：${said ?? error.message}`;
+}
+
+// A manifest checked against its schema, the files it names in `dir` when given. Returns null, or what is wrong.
+export function manifestProblem(manifest, dir = null) {
+  const validate = validator('plugin.json');
+  return validate.call({ dir }, manifest) ? null : explain(validate.errors);
+}
+// A value checked against one of the schemas (`ref`: a file, with a fragment, as `composer-modes.json#/$defs/parameters`),
+// as a plugin gives it while it runs: null, or what is wrong, at `where`.
+export function valueProblem(ref, value, where) {
+  const validate = ajv.getSchema(`${BASE}${ref}`) ?? null;
+  if (!validate) throw new Error(`没有这个 schema：${ref}`);
+  return validate.call({ dir: null }, value) ? null : explain(validate.errors, where);
+}