@coda-console/protocol 1.0.0 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Coda 与插件之间的约定，Coda 和插件都引用它，独立演进：
 
-- **插件清单的类型**（`schemas/plugin/`）：插件目录 `package.json` 里 `contributes` 的每个键是一种类型，各有一份 JSON Schema（draft 2020-12，`$id` 为 `https://coda.pub/schemas/plugin/v1/<文件>`）。`plugin.json` 是整份清单，`setting.json` 是一项设置的声明。插件写的合乎它用到的类型就对；写给别的插件扩展点的键由那个插件声明。
+- **插件清单的类型**（`schemas/plugin/`）：插件目录 `package.json` 里 `contributes` 的每个键是一种类型，各有一份 JSON Schema（draft 2020-12，`$id` 为 `https://coda.pub/schemas/plugin/v1/<文件>`）。`plugin.json` 是整份清单，`setting.json` 是一项设置的声明。插件写的合乎它用到的类型就对；写给别的插件扩展点的键由那个插件声明，扩展点可以带自己的 schema（`extensionPoints.<名>.schema`，声明它的插件目录里的一个文件），写给它的东西合乎那份 schema 才对。
 - **通用校验器**（`validate.mjs`）：用 Ajv 对清单做 schema 校验。JSON Schema 说不了的只用五个通用关键字（`x-unique-by`、`x-max-contains`、`x-ref`、`x-placeholders`、`x-file`，照 Kubernetes 的 `x-kubernetes-*`），每个在哪里写都是同一个意思，写法见文件开头。校验器不随功能变长：类型加字段就是改 schema。
 - **Agent 接入协议**（`docs/agent-protocol.md`）：Coda 怎样用 ACP 接 Agent，以及 Coda 加的扩展（会话指令、插话、`_coda/wait`、执行失败、工具调用的审核）。
 
@@ -13,16 +13,24 @@ npm install @coda-console/protocol
 ```
 
 ```js
-import { manifestProblem, valueProblem, TYPES, SCHEMAS } from '@coda-console/protocol/validate';
+import { manifestProblem, pointProblem, valueProblem, TYPES, SCHEMAS } from '@coda-console/protocol/validate';
 
 // 整份清单；给出插件目录时，连同它点名的文件一起查（x-file）。合乎类型返回 null，否则是一句说明：哪里、schema 怎么说。
 const problem = manifestProblem(JSON.parse(readFileSync('plugin/package.json', 'utf8')), 'plugin');
 // 某个类型里的一部分，如输入框模式的参数（插件运行时给出的）。
 valueProblem('composer-modes.json#/$defs/parameters', parameters, '插件给出的参数');
+// 写给别的插件扩展点的东西，按那个扩展点的 schema（已读出的对象）；给出写它的插件目录时连同它点名的文件一起查。
+pointProblem(panelsSchema, manifest.contributes.panels, 'contributes.panels', 'plugin');
 ```
 
+扩展点的 schema 和这里的并列：可以 `$ref` 协议的 schema（`common.json#/$defs/line40`），可以用五个关键字；它自己写的 `$id` 不算数，指针只指它校验的那份值里的位置。
+
 `TYPES` 是 Coda 自己的类型（`contributes` 的键），`SCHEMAS` 是全部 schema（按文件名）。
 
+## 项目中的多选选项
+
+设置的 `items.anyOf` 选项可附带 `workflowKind`（`check`、`premerge`、`deploy`、`preview`、`release`）。全局设置显示全部选项；项目设置只显示该项目有的流程类别，未写此字段的选项始终显示。宿主负责按项目提供可选项，流程执行时仍需按运行的提交判断可用操作。
+
 ## 谁在用
 
 - **Coda**：读插件时用它校验清单，再整理成自己的结构；只另看插件身份（ID、设置名在 ID 之下），以及装到一台机器上才知道的（来源、已装插件的冲突）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Coda 的协议：插件清单的类型（JSON Schema）、通用校验器与 Agent 接入协议",
   "type": "module",
   "license": "MIT",

package/schemas/plugin/extension-points.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://coda.pub/schemas/plugin/v1/extension-points.json",
   "title": "contributes.extensionPoints：插件声明的扩展点",
-  "description": "扩展点名 → 声明。只写 description 的，别的插件用 contributes.extensions 接一条命令；写了 contributes 的，任何插件在它的 contributes 里用这个键写的东西归它，原样交给声明它的插件读。",
+  "description": "扩展点名 → 声明。只写 description 的，别的插件用 contributes.extensions 接一条命令；写了 contributes 的，任何插件在它的 contributes 里用这个键写的东西归它，原样交给声明它的插件读，合乎它的 schema 才装得上。",
   "type": "object",
   "propertyNames": {"$ref": "common.json#/$defs/id"},
   "additionalProperties": {
@@ -46,12 +46,18 @@
         "type": "object",
         "propertyNames": {"pattern": "^(\\*|[A-Za-z][A-Za-z0-9]{0,39})(\\.(\\*|[A-Za-z][A-Za-z0-9]{0,39})){0,7}$"},
         "additionalProperties": {"$ref": "common.json#/$defs/line40"}
+      },
+      "schema": {
+        "description": "别的插件在这个键下写的东西的 JSON Schema（draft 2020-12）：本插件目录里的 .json 文件，至多 256 KiB。它和协议的类型并列，可以引用它们（common.json#/$defs/line40）、用协议的五个关键字；指针只指它自己校验的那份值里的位置",
+        "type": "string",
+        "pattern": "\\.json$",
+        "x-file": {"type": "file", "maxBytes": 262144, "schema": true}
       }
     },
     "required": ["description"],
     "additionalProperties": false,
     "if": {"required": ["contributes"]},
     "then": {"description": "写了 contributes 的扩展点也写 title", "required": ["title"]},
-    "else": {"description": "只有写了 contributes 的扩展点才写 title 与 commands", "not": {"anyOf": [{"required": ["title"]}, {"required": ["commands"]}]}}
+    "else": {"description": "只有写了 contributes 的扩展点才写 title、commands 与 schema", "not": {"anyOf": [{"required": ["title"]}, {"required": ["commands"]}, {"required": ["schema"]}]}}
   }
 }

package/schemas/plugin/mcp-servers.json

@@ -7,6 +7,7 @@
   "maxProperties": 20,
   "propertyNames": {"description": "服务器名只用小写字母、数字和「-」，以字母开头，至多 40 个字符，不能是 Coda 自己的 coda", "$ref": "common.json#/$defs/id", "not": {"const": "coda"}},
   "additionalProperties": {
+    "description": "一个服务器：由 Agent 在本机启动、经标准输入输出说话的程序（stdio），写 command 与 args；远程的（http、sse）现在不支持",
     "type": "object",
     "properties": {
       "type": {"description": "现在只支持由 Agent 在本机启动的服务器（stdio）", "const": "stdio"},

package/schemas/plugin/setting.json

@@ -167,7 +167,8 @@
             "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}
+              "description": {"type": "string", "maxLength": 400},
+              "workflowKind": {"description": "在项目设置里只在该项目有这一类流程时显示；全局设置列出全部选项", "enum": ["check", "premerge", "deploy", "preview", "release"]}
             },
             "required": ["const"],
             "additionalProperties": false

package/validate.mjs

@@ -1,6 +1,7 @@
 // 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,
+// one a plugin's extension point declares, for that plugin to read: of the schema that point names, a file of the declaring
+// plugin's (`extensionPoints.<point>.schema`), when it names one. 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,
@@ -13,10 +14,12 @@
 //   (`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.
+// - `x-file`: { type, under?, suffix?, contains?, maxBytes?, magic?, schema?, 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 `schema` a JSON Schema these keywords compile; with `absent`, a path there
+//   is none at. Checked when the directory is known.
 // It imports nothing but Node and Ajv.
+import { createHash } from 'node:crypto';
 import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
 import { isAbsolute, join, normalize, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -30,73 +33,111 @@ export const SCHEMAS = Object.fromEntries(readdirSync(SCHEMA_DIR).filter(file =>
 // 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.
+// What a pointer names, from where a keyword is: the manifest's root, or levels up from the value itself; and where that is.
 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;
+  if (up > here.length) return { at: undefined, path: '' };
   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);
+  return { at: steps.reduce((at, step) => at !== null && typeof at === 'object' && Object.hasOwn(at, step) ? at[step] : undefined, rootData),
+    path: steps.map(step => `/${escape(step)}`).join('') };
 }
 const unescape = step => step.replace(/~1/g, '/').replace(/~0/g, '~');
+const escape = step => String(step).replace(/~/g, '~0').replace(/\//g, '~1');
 const fail = (validate, keyword, message, parentSchema) => { validate.errors = [{ keyword, message, params: {}, parentSchema }]; return false; };
 
+// What each keyword is written with, checked where a schema using it is compiled: one written wrong is refused there, as an
+// extension point's schema is (x-file `schema`), not where a value is checked against it.
+const SCHEMA_VALUE = { type: ['object', 'boolean'] };
+const META = {
+  'x-max-contains': { type: 'object', properties: { match: SCHEMA_VALUE, max: { type: 'integer', minimum: 0 } }, required: ['match', 'max'], additionalProperties: false },
+  'x-unique-by': { type: 'array', minItems: 1, items: { anyOf: [{ type: 'string' },
+    { type: 'object', properties: { part: { type: 'string' } }, required: ['part'], additionalProperties: false }] } },
+  'x-ref': { type: 'object', properties: { pointer: { type: 'string', pattern: '^(?:\\d+(?:/.*)?|/.*)$' }, part: { type: 'string' }, match: SCHEMA_VALUE },
+    required: ['pointer'], additionalProperties: false },
+  'x-placeholders': { type: 'object', properties: { names: { type: 'array', items: { type: 'string' } }, config: SCHEMA_VALUE }, additionalProperties: false },
+  'x-file': { type: 'object', properties: { type: { enum: ['file', 'directory'] }, under: { type: 'string' }, suffix: { type: 'string' }, contains: { type: 'string' },
+    maxBytes: { type: 'integer', minimum: 0 }, magic: { type: 'string' }, schema: { type: 'boolean' }, absent: { type: 'boolean' } },
+    required: ['type'], additionalProperties: false },
+};
+
+// A validator that answers now: one of a schema written `$async` answers later, with a promise that would pass for a yes.
+function now(validate) {
+  if (validate.$async) throw new Error('不能是异步的（$async）');
+  return validate;
+}
+
+// A schema a keyword is written with (`match`, `config`), for a value elsewhere in what is checked: compiled on its own as a
+// validator that answers now, and run as one part of the whole — with what the whole is checked with (`self`, Ajv's context:
+// the plugin's directory), on the whole value, at the value's place in it — so that its pointers and files are as the
+// schema around it has them.
+function inner(ajv, schema) {
+  const validate = now(ajv.compile(schema));
+  return (self, value, path, { rootData }) => validate.call(self, value, { instancePath: path, rootData, dynamicAnchors: {} });
+}
+
 function keywords(ajv) {
   ajv.addKeyword({
-    keyword: 'x-max-contains', type: 'object', schemaType: 'object',
+    keyword: 'x-max-contains', type: 'object', schemaType: 'object', metaSchema: META['x-max-contains'],
     compile({ match, max }) {
-      const matcher = ajv.compile(match);
-      return value => Object.values(value).filter(each => matcher(each)).length <= max;
+      const matches = inner(ajv, match);
+      return function (value, cxt) {
+        return Object.entries(value).filter(([key, each]) => matches(this, each, `${cxt.instancePath}/${escape(key)}`, cxt)).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);
+    keyword: 'x-unique-by', type: 'array', schemaType: 'array', metaSchema: META['x-unique-by'], errors: true,
+    compile(keys, parentSchema) {
+      const by = keys.map(key => typeof key === 'object' ? { part: new RegExp(key.part, 'u') } : { key });
+      return function unique(items) {
+        for (const { key, part } of by) {
+          const 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;
+        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]);
-  };
+  function resolves(self, ref, matches, name, cxt) {
+    const { at, path } = locate(ref.pointer, cxt);
+    const key = Array.isArray(at) ? at.indexOf(name) : at !== null && typeof at === 'object' && Object.hasOwn(at, name) ? name : -1;
+    return key !== -1 && (!matches || matches(self, at[key], `${path}/${escape(key)}`, cxt));
+  }
   ajv.addKeyword({
-    keyword: 'x-ref', type: 'string', schemaType: 'object',
+    keyword: 'x-ref', type: 'string', schemaType: 'object', metaSchema: META['x-ref'],
     compile(ref) {
-      const matcher = ref.match ? ajv.compile(ref.match) : null, part = ref.part ? new RegExp(ref.part, 'u') : null;
-      return (value, cxt) => {
+      const matches = ref.match !== undefined ? inner(ajv, ref.match) : null, part = ref.part !== undefined ? new RegExp(ref.part, 'u') : null;
+      return function (value, cxt) {
         const name = part ? part.exec(value)?.[1] : value;
-        return name !== undefined && resolves(ref, matcher, name, cxt);
+        return name !== undefined && resolves(this, ref, matches, name, cxt);
       };
     },
   });
   ajv.addKeyword({
-    keyword: 'x-placeholders', type: 'string', schemaType: 'object',
+    keyword: 'x-placeholders', type: 'string', schemaType: 'object', metaSchema: META['x-placeholders'],
     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));
-      });
+      const config = allowed.config !== undefined ? { pointer: '/contributes/configuration/properties' } : null, matches = config && inner(ajv, allowed.config);
+      return function (value, cxt) {
+        return [...value.matchAll(/\$\{([^}]*)\}/g)].every(([, place]) => {
+          if ((allowed.names ?? []).includes(place)) return true;
+          const setting = /^config:(.+)$/.exec(place)?.[1];
+          return !!(config && setting && resolves(this, config, matches, setting, cxt));
+        });
+      };
     },
   });
   ajv.addKeyword({
-    keyword: 'x-file', type: 'string', schemaType: 'object', errors: true,
+    keyword: 'x-file', type: 'string', schemaType: 'object', metaSchema: META['x-file'], 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 ?? ''}`);
@@ -114,6 +155,8 @@ function keywords(ajv) {
         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);
       }
+      if (spec.schema) try { declared(JSON.parse(readFileSync(join(dir, path), 'utf8'))); }
+      catch (e) { return fail(file, 'x-file', `${path} 不是可用的 JSON Schema：${e.message}`, parentSchema); }
       return true;
     },
   });
@@ -128,6 +171,20 @@ const validator = file => {
   if (!compiled.has(file)) compiled.set(file, ajv.getSchema(`${BASE}${file}`));
   return compiled.get(file);
 };
+// The schema an extension point declares, compiled once by what it says, under an ID of its own beside these (whatever `$id`
+// it wrote), so that it builds on them as they build on one another (`common.json#/$defs/line40`): its validator, and the
+// schema as compiled, for what it says of a failing value. One that answers later (`$async`) is refused.
+const points = new Map();
+function declared(schema) {
+  const text = JSON.stringify(schema);
+  if (!points.has(text)) {
+    // `true` and `false` say all they say as they are; what is no schema at all Ajv refuses.
+    const object = schema !== null && typeof schema === 'object' && !Array.isArray(schema);
+    const own = object ? { ...schema, $id: `${BASE}point-${createHash('sha256').update(text).digest('hex').slice(0, 16)}.json` } : schema;
+    points.set(text, { validate: now((object && ajv.getSchema(own.$id)) || ajv.compile(own)), schema: own });
+  }
+  return points.get(text);
+}
 
 // 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)
@@ -140,11 +197,11 @@ const nodes = function* (node) {
   yield node;
   for (const child of Object.values(node)) yield* nodes(child);
 };
-function described(error, { roots = true } = {}) {
+function described(error, { roots = true, schemas = [] } = {}) {
   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)) {
+  for (const root of [...schemas, ...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;
@@ -155,16 +212,17 @@ function described(error, { roots = true } = {}) {
 }
 // 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 = '') {
+// `schemas`: those besides these the value was checked against (an extension point's).
+export function explain(errors, base = '', schemas = []) {
   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 === 'required') { const said = described(error, { roots: false, schemas }); 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);
+  const said = described(error, { schemas });
   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}）` : ''}`; }
+  if (error.keyword === 'x-file') { const own = described(error, { roots: false, schemas }); return `${at}${name}：${error.message}${own ? `（${own}）` : ''}`; }
   return `${at}${name}：${said ?? error.message}`;
 }
 
@@ -180,3 +238,10 @@ export function valueProblem(ref, value, where) {
   if (!validate) throw new Error(`没有这个 schema：${ref}`);
   return validate.call({ dir: null }, value) ? null : explain(validate.errors, where);
 }
+// What a plugin writes for another's extension point (`value`, under `where`, as `contributes.panels`), checked against the
+// schema that point declares (the declaring plugin's file, read): null, or what is wrong. `dir`: the writing plugin's
+// directory, for the files it names. The schema sees the value alone: its pointers name places in it.
+export function pointProblem(schema, value, where, dir = null) {
+  const point = declared(schema);
+  return point.validate.call({ dir }, value) ? null : explain(point.validate.errors, where, [point.schema]);
+}