@coda-console/plugin-check 0.5.10 → 0.5.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/check/coda/components/plugins/agent-plugins.mjs +19 -70
  2. package/check/coda/components/plugins/plugin-extensions.mjs +1 -70
  3. package/check/coda/components/plugins/plugin-rules.mjs +120 -513
  4. package/check/coda/components/plugins/plugin-schema.mjs +177 -0
  5. package/check/coda/components/plugins/plugin-source-rules.mjs +3 -1
  6. package/check/coda/components/plugins/schemas/agents.json +50 -0
  7. package/check/coda/components/plugins/schemas/capabilities.json +16 -0
  8. package/check/coda/components/plugins/schemas/commands.json +21 -0
  9. package/check/coda/components/plugins/schemas/common.json +25 -0
  10. package/check/coda/components/plugins/schemas/composer-modes.json +79 -0
  11. package/check/coda/components/plugins/schemas/configuration.json +23 -0
  12. package/check/coda/components/plugins/schemas/endpoints.json +19 -0
  13. package/check/coda/components/plugins/schemas/environment.json +22 -0
  14. package/check/coda/components/plugins/schemas/events.json +23 -0
  15. package/check/coda/components/plugins/schemas/executors.json +26 -0
  16. package/check/coda/components/plugins/schemas/extension-points.json +57 -0
  17. package/check/coda/components/plugins/schemas/extensions.json +13 -0
  18. package/check/coda/components/plugins/schemas/git-credentials.json +17 -0
  19. package/check/coda/components/plugins/schemas/groups.json +21 -0
  20. package/check/coda/components/plugins/schemas/instructions.json +9 -0
  21. package/check/coda/components/plugins/schemas/mcp-servers.json +29 -0
  22. package/check/coda/components/plugins/schemas/model-providers.json +39 -0
  23. package/check/coda/components/plugins/schemas/path.json +16 -0
  24. package/check/coda/components/plugins/schemas/plugin.json +46 -0
  25. package/check/coda/components/plugins/schemas/repositories.json +7 -0
  26. package/check/coda/components/plugins/schemas/services.json +9 -0
  27. package/check/coda/components/plugins/schemas/setting.json +242 -0
  28. package/check/coda/components/plugins/schemas/setup.json +7 -0
  29. package/check/coda/components/plugins/schemas/skills.json +15 -0
  30. package/check/coda/components/plugins/schemas/views.json +30 -0
  31. package/check/coda/components/session-config/commands.mjs +17 -2
  32. package/check/coda/contract.json +35 -9
  33. package/check/coda/domain/errors.mjs +3 -0
  34. package/package.json +2 -1
  35. package/check/coda/components/plugins/model-protocols.mjs +0 -39
@@ -1,76 +1,25 @@
1
- // The agents a plugin brings (docs/plugins.md「Agent」): who each is, how the clients draw it, and how Coda starts its
2
- // process, which speaks ACP with Coda's waits (docs/agent-protocol.md). Nothing here knows any agent by name: Codex and
3
- // Claude are plugins like any other.
1
+ // The agents a plugin brings (docs/plugins.md「Agent」, schemas/agents.json): who each is, how the clients draw it, and how
2
+ // Coda starts its process, which speaks ACP with Coda's waits (docs/agent-protocol.md). Nothing here knows any agent by
3
+ // name: Codex and Claude are plugins like any other.
4
4
  import { readFileSync } from 'node:fs';
5
- import { isAbsolute, join, normalize, sep } from 'node:path';
6
- import { requireCondition as check } from '../../domain/errors.mjs';
7
- import { AGENT_ID } from '../../domain/values.mjs';
5
+ import { isAbsolute, join, normalize } from 'node:path';
8
6
 
9
- export const ICON_LIMIT = 32 * 1024;
10
- const NAME = 40, MODE_TITLE = 10, MODE_UNSET = 20, MODE_NOTE = 100, HINT = 200, COMMAND = 4000, CONFIG_FILES = 16, PATH = 1000;
11
- const code = 'invalid_plugin';
12
- const keys = (value, allowed, where) => {
13
- const extra = Object.keys(value).filter(k => !allowed.includes(k));
14
- check(!extra.length, code, `${where} 里有 Coda 不支持的键:${extra.join('、')}`);
15
- };
16
- const object = (value, where) => check(value && typeof value === 'object' && !Array.isArray(value), code, `${where} 须为对象`);
17
- const line = (value, max, where) => {
18
- check(typeof value === 'string' && value.trim() && [...value].length <= max && !/[\0\r\n]/.test(value), code, `${where} 须为不超过 ${max} 字的一行文本`);
19
- return value;
20
- };
21
- const optional = (value, max, where) => value === undefined ? undefined : line(value, max, where);
22
- // A path inside the plugin's directory or the working copy: relative, and never leaving it.
23
- const inside = (value, where, { segments = Infinity } = {}) => {
24
- line(value, PATH, where);
25
- const path = normalize(value);
26
- check(!isAbsolute(value) && path !== '..' && !path.startsWith(`..${sep}`) && path.split(sep).length <= segments, code,
27
- `${where} 须为不离开所在目录的相对路径${Number.isFinite(segments) ? `,至多 ${segments} 段` : ''}`);
28
- return path;
29
- };
30
- // An icon file, read once with the plugin: a PDF both clients draw as they drew the brand artwork they shipped with.
31
- function icon(dir, value, where) {
32
- const path = inside(value, where);
33
- let data;
34
- try { data = readFileSync(join(dir, path)); } catch (e) { check(false, code, `${where} 读不到:${e.message}`); }
35
- check(data.length <= ICON_LIMIT, code, `${where} 超过 ${ICON_LIMIT / 1024} KiB`);
36
- check(data.subarray(0, 5).toString('latin1') === '%PDF-', code, `${where} 须为 PDF`);
37
- return data.toString('base64');
7
+ // An icon file, read once with the plugin (its schema says it is a PDF in the plugin's directory): both clients draw it as
8
+ // they drew the brand artwork they shipped with.
9
+ const icon = (dir, path) => readFileSync(join(dir, normalize(path))).toString('base64');
10
+ const MODES = ['title', 'unset', 'note', 'auto', 'full'];
11
+ // `contributes.agents` of the plugin in `dir`, as its schema has them.
12
+ export function agentDeclarations(raw = [], dir) {
13
+ return raw.map(agent => ({
14
+ id: agent.id, displayName: agent.displayName,
15
+ icon: { light: icon(dir, agent.icon.light), ...(agent.icon.dark !== undefined ? { dark: icon(dir, agent.icon.dark) } : {}), template: agent.icon.template === true },
16
+ command: agent.command,
17
+ modes: Object.fromEntries(MODES.filter(key => agent.modes?.[key] !== undefined).map(key => [key, agent.modes[key]])),
18
+ ...(agent.skillsDir !== undefined ? { skillsDir: normalize(agent.skillsDir) } : {}),
19
+ configFiles: [...(agent.configFiles ?? [])],
20
+ ...(agent.setupHint !== undefined ? { setupHint: agent.setupHint } : {}),
21
+ }));
38
22
  }
39
-
40
- function declaration(raw, where, dir) {
41
- object(raw, where);
42
- keys(raw, ['id', 'displayName', 'icon', 'command', 'modes', 'skillsDir', 'configFiles', 'setupHint'], where);
43
- check(typeof raw.id === 'string' && AGENT_ID.test(raw.id), code, `${where} 的 id 只能用小写字母、数字和「-」,以字母开头,至多 40 个字符`);
44
- const at = `Agent ${raw.id}`;
45
- object(raw.icon, `${at} 的 icon`);
46
- keys(raw.icon, ['light', 'dark', 'template'], `${at} 的 icon`);
47
- check(raw.icon.template === undefined || typeof raw.icon.template === 'boolean', code, `${at} 的 icon.template 须为开或关`);
48
- const modes = raw.modes ?? {};
49
- object(modes, `${at} 的 modes`);
50
- keys(modes, ['title', 'unset', 'note', 'auto', 'full'], `${at} 的 modes`);
51
- check(raw.configFiles === undefined || (Array.isArray(raw.configFiles) && raw.configFiles.length <= CONFIG_FILES), code,
52
- `${at} 的 configFiles 须为至多 ${CONFIG_FILES} 项的数组`);
53
- return {
54
- id: raw.id, displayName: line(raw.displayName, NAME, `${at} 的 displayName`),
55
- icon: { light: icon(dir, raw.icon.light, `${at} 的 icon.light`),
56
- ...(raw.icon.dark !== undefined ? { dark: icon(dir, raw.icon.dark, `${at} 的 icon.dark`) } : {}), template: raw.icon.template === true },
57
- command: line(raw.command, COMMAND, `${at} 的 command`),
58
- modes: Object.fromEntries([['title', MODE_TITLE], ['unset', MODE_UNSET], ['note', MODE_NOTE], ['auto', 200], ['full', 200]]
59
- .filter(([key]) => modes[key] !== undefined).map(([key, max]) => [key, line(modes[key], max, `${at} 的 modes.${key}`)])),
60
- ...(raw.skillsDir !== undefined ? { skillsDir: inside(raw.skillsDir, `${at} 的 skillsDir`, { segments: 3 }) } : {}),
61
- configFiles: (raw.configFiles ?? []).map((file, i) => line(file, PATH, `${at} 的 configFiles[${i}]`)),
62
- ...(raw.setupHint !== undefined ? { setupHint: optional(raw.setupHint, HINT, `${at} 的 setupHint`) } : {}),
63
- };
64
- }
65
- // `contributes.agents` of the plugin in `dir`.
66
- export function agentDeclarations(raw, dir) {
67
- if (raw === undefined) return [];
68
- check(Array.isArray(raw), code, 'contributes.agents 须为数组');
69
- const agents = raw.map((a, i) => declaration(a, `contributes.agents[${i}]`, dir));
70
- check(new Set(agents.map(a => a.id)).size === agents.length, code, 'contributes.agents 里有重复的 id');
71
- return agents;
72
- }
73
-
74
23
  // A configuration file an agent reads its models from, as its plugin names it: `~/` is the home directory, `${VAR}` and
75
24
  // `${VAR:-default}` the backend's environment (a variable empty and without a default leaves the file out), and a relative
76
25
  // path is the project's.
@@ -6,64 +6,8 @@
6
6
  // the declaring plugin to read, only the commands in it listed where installing confirms them.
7
7
  import { requireCondition as check } from '../../domain/errors.mjs';
8
8
 
9
- const ID = /^[a-z][a-z0-9-]{0,39}$/;
10
- const POINT = /^[a-z][a-z0-9-]{0,39}$/;
11
- const DESCRIPTION = 200, COMMAND = 4000, TITLE = 20, LABEL = 40;
12
- // A key of `contributes` a point takes, and where in each thing written there a command is (`*`: every key, or element).
13
- const OFFER = /^[a-z][A-Za-z0-9]{0,39}$/, PATH = /^(\*|[A-Za-z][A-Za-z0-9]{0,39})(\.(\*|[A-Za-z][A-Za-z0-9]{0,39})){0,7}$/;
14
9
  const code = 'invalid_plugin';
15
- const object = (value, where) => check(value && typeof value === 'object' && !Array.isArray(value), code, `${where} 须为对象`);
16
- const keys = (value, allowed, where) => {
17
- const extra = Object.keys(value).filter(k => !allowed.includes(k));
18
- check(!extra.length, code, `${where} 里有 Coda 不支持的键:${extra.join('、')}`);
19
- };
20
- const line = (value, max, where) => {
21
- check(typeof value === 'string' && value.trim() && [...value].length <= max && !/[\0\r\n]/.test(value), code, `${where} 须为不超过 ${max} 字的一行文本`);
22
- return value;
23
- };
24
10
 
25
- // `extensionDependencies` (VS Code's name: `dependencies` is npm's): the IDs of the plugins this one needs installed, which installing it installs first.
26
- export function dependencyDeclarations(raw, self) {
27
- if (raw === undefined) return [];
28
- check(Array.isArray(raw) && raw.every(id => typeof id === 'string' && ID.test(id)) && new Set(raw).size === raw.length, code,
29
- 'extensionDependencies 须为插件 ID 的数组,不重复');
30
- check(!raw.includes(self), code, 'extensionDependencies 不能写自己');
31
- return [...raw];
32
- }
33
- // `contributes.extensionPoints`: name → `{ description }`, what others may plug in here; with `contributes`, the key of
34
- // `contributes` any plugin writes it under (none of Coda's own, `reserved`), what one thing written there is called
35
- // (`title`), and where in each a command is, with what it is for (`commands`: path → label).
36
- export function extensionPointDeclarations(raw, reserved = []) {
37
- if (raw === undefined) return {};
38
- object(raw, 'contributes.extensionPoints');
39
- // A key is one point's, of this plugin as of any other (plugin-source-rules.mjs claims).
40
- const taken = new Map();
41
- return Object.fromEntries(Object.entries(raw).map(([name, value]) => {
42
- const where = `contributes.extensionPoints.${name}`;
43
- check(POINT.test(name), code, `${where}:扩展点名只能用小写字母、数字和「-」,以字母开头`);
44
- object(value, where); keys(value, value.contributes === undefined ? ['description'] : ['description', 'contributes', 'title', 'commands'], where);
45
- const description = line(value.description, DESCRIPTION, `${where} 的 description`);
46
- if (value.contributes === undefined) return [name, { description }];
47
- check(typeof value.contributes === 'string' && OFFER.test(value.contributes), code, `${where} 的 contributes 须为字母和数字组成、以小写字母开头的键名`);
48
- check(!reserved.includes(value.contributes), code, `${where} 的 contributes:${value.contributes} 是 Coda 自己的贡献`);
49
- check(!taken.has(value.contributes), code, `${where} 的 contributes:${value.contributes} 已由扩展点 ${taken.get(value.contributes)} 声明`);
50
- taken.set(value.contributes, name);
51
- const commands = value.commands ?? {};
52
- object(commands, `${where} 的 commands`);
53
- for (const [path, label] of Object.entries(commands)) {
54
- check(PATH.test(path), code, `${where} 的 commands:${path} 须为以「.」连接的键名或「*」`);
55
- line(label, LABEL, `${where} 的 commands.${path}`);
56
- }
57
- return [name, { description, contributes: value.contributes, title: line(value.title, TITLE, `${where} 的 title`), commands: { ...commands } }];
58
- }));
59
- }
60
- // What a plugin writes under the keys of `contributes` that are not Coda's own (`reserved`), as written: each for the
61
- // point that takes it, which the catalog checks there is (checkCatalog).
62
- export function offerDeclarations(contributes = {}, reserved = []) {
63
- const offers = Object.entries(contributes ?? {}).filter(([key]) => !reserved.includes(key));
64
- for (const [key] of offers) check(OFFER.test(key), code, `contributes 里有 Coda 不支持的贡献:${key}`);
65
- return Object.fromEntries(offers);
66
- }
67
11
  // The point that takes what is written under this key of `contributes`, with the plugin declaring it, or null.
68
12
  export function offerPoint(plugins, key) {
69
13
  for (const plugin of plugins.values()) for (const [point, declared] of Object.entries(plugin.extensionPoints ?? {}))
@@ -89,19 +33,6 @@ export function offeredCommands(raw, declared) {
89
33
  for (const [name, item] of items) for (const [path, label] of Object.entries(declared.commands ?? {})) walk(item, path.split('.'), [], label, name);
90
34
  return { count: items.length, commands };
91
35
  }
92
- // `contributes.extensions`: `<plugin>/<point>` → `{ command }`, plugged into a point of a plugin it depends on.
93
- export function extensionDeclarations(raw, dependencies) {
94
- if (raw === undefined) return [];
95
- object(raw, 'contributes.extensions');
96
- return Object.entries(raw).map(([key, value]) => {
97
- const where = `contributes.extensions.${key}`, [plugin, point, ...rest] = key.split('/');
98
- check(ID.test(plugin ?? '') && POINT.test(point ?? '') && !rest.length, code, `${where}:须写成「插件 ID/扩展点名」`);
99
- check(dependencies.includes(plugin), code, `${where}:只能接所依赖的插件的扩展点,先把 ${plugin} 写进 extensionDependencies`);
100
- object(value, where); keys(value, ['command'], where);
101
- return { plugin, point, command: line(value.command, COMMAND, `${where} 的 command`) };
102
- });
103
- }
104
-
105
36
  // The catalog as a whole: every plugin needed is there, nothing needs itself round about, every point plugged into is
106
37
  // one its plugin declares, and what is written under a key of `contributes` not Coda's own a point takes.
107
38
  export function checkCatalog(plugins) {
@@ -128,7 +59,7 @@ export function checkCatalog(plugins) {
128
59
  export function offerProblem(plugin, plugins) {
129
60
  const others = new Map([...plugins, [plugin.id, plugin]]);
130
61
  const unknown = Object.keys(plugin.offers ?? {}).filter(key => !offerPoint(others, key));
131
- return unknown.length ? `contributes 里有 Coda 不支持的贡献:${unknown.join('、')}` : null;
62
+ return unknown.length ? `contributes 里的 ${unknown.join('、')} 不是 Coda 的类型,也没有插件的扩展点声明它` : null;
132
63
  }
133
64
  // What installing a plugin installs: what it needs, before it, then it.
134
65
  export function withDependencies(catalog, id) {