@mostra/protocol 0.13.0 → 0.15.0

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 (125) hide show
  1. package/dist/artifact-path.d.ts +22 -0
  2. package/dist/artifact-path.d.ts.map +1 -0
  3. package/dist/artifact-path.js +39 -0
  4. package/dist/artifact-path.js.map +1 -0
  5. package/dist/diagnostics/codes/index.d.ts +5 -2
  6. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  7. package/dist/diagnostics/codes/index.js +7 -1
  8. package/dist/diagnostics/codes/index.js.map +1 -1
  9. package/dist/diagnostics/codes/license.d.ts +8 -0
  10. package/dist/diagnostics/codes/license.d.ts.map +1 -0
  11. package/dist/diagnostics/codes/license.js +55 -0
  12. package/dist/diagnostics/codes/license.js.map +1 -0
  13. package/dist/diagnostics/codes/pack.d.ts +8 -0
  14. package/dist/diagnostics/codes/pack.d.ts.map +1 -0
  15. package/dist/diagnostics/codes/pack.js +110 -0
  16. package/dist/diagnostics/codes/pack.js.map +1 -0
  17. package/dist/diagnostics/codes/plugin.d.ts +8 -0
  18. package/dist/diagnostics/codes/plugin.d.ts.map +1 -0
  19. package/dist/diagnostics/codes/plugin.js +154 -0
  20. package/dist/diagnostics/codes/plugin.js.map +1 -0
  21. package/dist/diagnostics/diagnostic.d.ts +1 -1
  22. package/dist/diagnostics/diagnostic.d.ts.map +1 -1
  23. package/dist/diagnostics/diagnostic.js +4 -1
  24. package/dist/diagnostics/diagnostic.js.map +1 -1
  25. package/dist/index.d.ts +13 -1
  26. package/dist/index.js +13 -1
  27. package/dist/methods/deps/add.d.ts +6 -0
  28. package/dist/methods/deps/add.d.ts.map +1 -1
  29. package/dist/methods/deps/add.js +1 -0
  30. package/dist/methods/deps/add.js.map +1 -1
  31. package/dist/methods/index.d.ts.map +1 -1
  32. package/dist/methods/index.js +15 -1
  33. package/dist/methods/index.js.map +1 -1
  34. package/dist/methods/mostra/initialize.d.ts +7 -0
  35. package/dist/methods/mostra/initialize.d.ts.map +1 -1
  36. package/dist/methods/mostra/initialize.js +4 -2
  37. package/dist/methods/mostra/initialize.js.map +1 -1
  38. package/dist/methods/pack/add.d.ts +80 -0
  39. package/dist/methods/pack/add.d.ts.map +1 -0
  40. package/dist/methods/pack/add.js +59 -0
  41. package/dist/methods/pack/add.js.map +1 -0
  42. package/dist/methods/plugin/add.d.ts +43 -0
  43. package/dist/methods/plugin/add.d.ts.map +1 -0
  44. package/dist/methods/plugin/add.js +39 -0
  45. package/dist/methods/plugin/add.js.map +1 -0
  46. package/dist/methods/plugin/commands.d.ts +38 -0
  47. package/dist/methods/plugin/commands.d.ts.map +1 -0
  48. package/dist/methods/plugin/commands.js +33 -0
  49. package/dist/methods/plugin/commands.js.map +1 -0
  50. package/dist/methods/plugin/export.d.ts +58 -0
  51. package/dist/methods/plugin/export.d.ts.map +1 -0
  52. package/dist/methods/plugin/export.js +57 -0
  53. package/dist/methods/plugin/export.js.map +1 -0
  54. package/dist/methods/plugin/list.d.ts +26 -0
  55. package/dist/methods/plugin/list.d.ts.map +1 -0
  56. package/dist/methods/plugin/list.js +30 -0
  57. package/dist/methods/plugin/list.js.map +1 -0
  58. package/dist/methods/plugin/remove.d.ts +32 -0
  59. package/dist/methods/plugin/remove.d.ts.map +1 -0
  60. package/dist/methods/plugin/remove.js +33 -0
  61. package/dist/methods/plugin/remove.js.map +1 -0
  62. package/dist/methods/plugin/validate.d.ts +35 -0
  63. package/dist/methods/plugin/validate.d.ts.map +1 -0
  64. package/dist/methods/plugin/validate.js +33 -0
  65. package/dist/methods/plugin/validate.js.map +1 -0
  66. package/dist/plugin/contract-versions.generated.js +14 -0
  67. package/dist/plugin/contract-versions.generated.js.map +1 -0
  68. package/dist/plugin/contracts.d.ts +51 -0
  69. package/dist/plugin/contracts.d.ts.map +1 -0
  70. package/dist/plugin/contracts.js +129 -0
  71. package/dist/plugin/contracts.js.map +1 -0
  72. package/dist/plugin/license.d.ts +87 -0
  73. package/dist/plugin/license.d.ts.map +1 -0
  74. package/dist/plugin/license.js +243 -0
  75. package/dist/plugin/license.js.map +1 -0
  76. package/dist/plugin/manifest.d.ts +141 -0
  77. package/dist/plugin/manifest.d.ts.map +1 -0
  78. package/dist/plugin/manifest.js +281 -0
  79. package/dist/plugin/manifest.js.map +1 -0
  80. package/dist/plugin/registry-item.d.ts +171 -0
  81. package/dist/plugin/registry-item.d.ts.map +1 -0
  82. package/dist/plugin/registry-item.js +162 -0
  83. package/dist/plugin/registry-item.js.map +1 -0
  84. package/dist/plugin/spdx.generated.d.ts +9 -0
  85. package/dist/plugin/spdx.generated.d.ts.map +1 -0
  86. package/dist/plugin/spdx.generated.js +846 -0
  87. package/dist/plugin/spdx.generated.js.map +1 -0
  88. package/dist/plugin.d.ts +7 -0
  89. package/dist/plugin.js +6 -0
  90. package/dist/plugins.d.ts +118 -0
  91. package/dist/plugins.d.ts.map +1 -0
  92. package/dist/plugins.js +109 -0
  93. package/dist/plugins.js.map +1 -0
  94. package/package.json +19 -4
  95. package/schemas/plugin-manifest.draft-07.json +611 -0
  96. package/schemas/plugin-manifest.schema.json +607 -0
  97. package/schemas/protocol.draft-07.json +899 -1
  98. package/schemas/protocol.schema.json +875 -1
  99. package/src/artifact-path.ts +46 -0
  100. package/src/diagnostics/codes/index.ts +14 -2
  101. package/src/diagnostics/codes/license.ts +65 -0
  102. package/src/diagnostics/codes/pack.ts +125 -0
  103. package/src/diagnostics/codes/plugin.ts +173 -0
  104. package/src/diagnostics/diagnostic.ts +7 -1
  105. package/src/index.ts +57 -0
  106. package/src/methods/deps/add.ts +7 -0
  107. package/src/methods/index.ts +14 -0
  108. package/src/methods/mostra/initialize.ts +9 -1
  109. package/src/methods/pack/add.ts +133 -0
  110. package/src/methods/plugin/add.ts +70 -0
  111. package/src/methods/plugin/commands.ts +67 -0
  112. package/src/methods/plugin/export.ts +100 -0
  113. package/src/methods/plugin/list.ts +45 -0
  114. package/src/methods/plugin/remove.ts +58 -0
  115. package/src/methods/plugin/validate.ts +60 -0
  116. package/src/plugin/contract-versions.generated.ts +15 -0
  117. package/src/plugin/contracts.ts +171 -0
  118. package/src/plugin/license.ts +320 -0
  119. package/src/plugin/manifest.ts +546 -0
  120. package/src/plugin/registry-item.ts +330 -0
  121. package/src/plugin/spdx-tables.ts +74 -0
  122. package/src/plugin/spdx.generated.ts +844 -0
  123. package/src/plugin.ts +77 -0
  124. package/src/plugins.ts +239 -0
  125. package/LICENSE +0 -202
@@ -0,0 +1,546 @@
1
+ /**
2
+ * The plugin manifest (D30, ROUND-3 §6.2, EX-02): the `"mostra"` key of a plugin's
3
+ * `package.json`. Its Zod schema is the source of the published JSON Schema
4
+ * (`schemas/plugin-manifest.schema.json`); {@link checkPluginManifest} adds what a schema can't
5
+ * say (a contract each contribution kind needs, unique IDs, license expressions) and reports every
6
+ * problem it finds, each with the path of the field, so `mostra plugin validate` names them all.
7
+ */
8
+ import * as z from "zod";
9
+ import {
10
+ ContractName,
11
+ type ContractName as ContractNameType,
12
+ LicenseClass,
13
+ type LicenseClass as LicenseClassType,
14
+ } from "../plugins.ts";
15
+ import {
16
+ CONTRACT_NAMES,
17
+ type ContributesKey,
18
+ coreCommandTaken,
19
+ PLUGIN_CONTRACTS,
20
+ } from "./contracts.ts";
21
+ import {
22
+ ACKNOWLEDGED_CLASSES,
23
+ isLicenseRef,
24
+ LicenseExpressionError,
25
+ parseLicenseExpression,
26
+ } from "./license.ts";
27
+
28
+ /**
29
+ * The dated revision of the manifest's schema (and of pack items'), published with it; within it
30
+ * the schema only grows, as the host protocol's does (D32).
31
+ */
32
+ export const PLUGIN_MANIFEST_REVISION = "2026-11-14";
33
+
34
+ /** The registry of the manifest's schemas: its own JSON Schema bundle, apart from the protocol's. */
35
+ export const pluginManifestRegistry: z.core.$ZodRegistry<{ id?: string; description?: string }> =
36
+ z.registry<{ id?: string; description?: string }>();
37
+
38
+ /** The pattern of a manifest's `name`: `<namespace>/<name>`, the namespace in reverse-DNS form. */
39
+ export const PLUGIN_NAME: RegExp =
40
+ /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+\/[a-z0-9][a-z0-9._-]{0,63}$/;
41
+
42
+ /** The pattern of a contribution's ID (each contract package's `CONTRIBUTION_ID`). */
43
+ export const CONTRIBUTION_ID: RegExp = /^[a-z0-9][a-z0-9._-]{0,63}$/;
44
+
45
+ /** A path inside the plugin's package: `./`-relative, `/`-separated, never leaving it. */
46
+ export const PACKAGE_PATH: RegExp = /^\.\/(?!.*(?:^|\/)\.\.?(?:\/|$))[^\\:*?"<>|\0]+$/;
47
+
48
+ /** The effects a plugin may declare (D30): disclosure, never enforced. */
49
+ export const PLUGIN_EFFECTS: readonly string[] = [
50
+ "network",
51
+ "filesystem",
52
+ "process",
53
+ "credentials",
54
+ "sends-data",
55
+ ];
56
+
57
+ /** The systems a plugin may name, as Node.js names them. */
58
+ export const PLUGIN_PLATFORMS: readonly string[] = ["darwin", "linux", "win32"];
59
+
60
+ /** One contribution that loads from a module of the package. */
61
+ export interface PluginEntry {
62
+ /** Its ID: what `--as`, a component or a review anchor names. */
63
+ readonly id: string;
64
+ /** The module that exports it: `./dist/pdf.js`. */
65
+ readonly entry: string;
66
+ /** The export that holds it; `default` when absent. */
67
+ readonly export?: string;
68
+ }
69
+
70
+ /** A CLI command contribution. */
71
+ export interface PluginCommandEntry {
72
+ /** Its words after `mostra`, joined by spaces: `term record`. */
73
+ readonly command: string;
74
+ /** The module that exports it: `./dist/index.js`. */
75
+ readonly entry: string;
76
+ /** The export that holds the definition; `default` when absent. */
77
+ readonly export?: string;
78
+ }
79
+
80
+ /** A source pack the plugin carries: a registry item file in its package. */
81
+ export interface PluginPackEntry {
82
+ /** The item: `./registry/terminal-demo.json`. */
83
+ readonly item: string;
84
+ }
85
+
86
+ /** What a plugin contributes, by kind. */
87
+ export interface PluginContributes {
88
+ /** Embed engines (`@mostra/contract-embed-engine`). */
89
+ readonly embedEngines?: readonly PluginEntry[];
90
+ /** Exporters (`@mostra/contract-exporter`). */
91
+ readonly exporters?: readonly PluginEntry[];
92
+ /** Verify checks (`@mostra/contract-verify-check`). */
93
+ readonly verifyChecks?: readonly PluginEntry[];
94
+ /** Anchor providers (`@mostra/contract-anchor-provider`). */
95
+ readonly anchorProviders?: readonly PluginEntry[];
96
+ /** Connectors (`@mostra/contract-connector`). */
97
+ readonly connectors?: readonly PluginEntry[];
98
+ /** CLI commands (`@mostra/contract-cli-command`). */
99
+ readonly cliCommands?: readonly PluginCommandEntry[];
100
+ /** Source packs it carries: registry items in the package. */
101
+ readonly packs?: readonly PluginPackEntry[];
102
+ }
103
+
104
+ /** A license the plugin brings with it, declared so Mostra can disclose it before install. */
105
+ export interface BundledLicense {
106
+ /** The npm package (or bundled engine) under it. */
107
+ readonly package: string;
108
+ /** Its SPDX expression: `MIT`, `LicenseRef-Remotion`. */
109
+ readonly license: string;
110
+ /** For a `LicenseRef-`: `source-available` or `proprietary`. */
111
+ readonly class?: LicenseClassType;
112
+ /** One line on its terms, shown at install. */
113
+ readonly summary?: string;
114
+ /** Where its full text is. */
115
+ readonly url?: string;
116
+ }
117
+
118
+ /** A plugin's example and the baselines it verifies against. */
119
+ export interface PluginExample {
120
+ /** Its ID: lower-case letters, digits, `.`, `_` and `-`. */
121
+ readonly id: string;
122
+ /** The example artifact: `./examples/htop`. */
123
+ readonly path: string;
124
+ /** Its committed baselines: `./baselines/htop`. */
125
+ readonly baselines?: string;
126
+ }
127
+
128
+ /** The `"mostra"` key of a plugin's `package.json`. */
129
+ export interface PluginManifest {
130
+ /** `<namespace>/<name>`, the namespace in reverse-DNS form: `dev.acme/pdf`. */
131
+ readonly name: string;
132
+ /** A short name for people. */
133
+ readonly title?: string;
134
+ /** One sentence on what it does, for people and agents. */
135
+ readonly description?: string;
136
+ /** A semver range per contract it implements: `{ "exporter": "^0.1.0" }`. */
137
+ readonly contracts: Partial<Record<ContractNameType, string>>;
138
+ /** What it contributes, by kind. */
139
+ readonly contributes: PluginContributes;
140
+ /** What it does beyond computing (`network`, `filesystem` …): declared, never enforced. */
141
+ readonly effects?: readonly string[];
142
+ /** The plugin's own license, as an SPDX expression. */
143
+ readonly license: string;
144
+ /** Licenses of what it brings along: engines, assets, dependencies. */
145
+ readonly bundledLicenses?: readonly BundledLicense[];
146
+ /** Agent Skills that teach agents to use it: `./skills/pdf`. */
147
+ readonly skills?: readonly string[];
148
+ /** Example artifacts, each verified against its baselines. */
149
+ readonly examples?: readonly PluginExample[];
150
+ /** The systems it runs on; absent means all of Mostra's. */
151
+ readonly platforms?: readonly string[];
152
+ }
153
+
154
+ const packagePath = z.string().regex(PACKAGE_PATH, "a ./-relative path inside the package");
155
+ const exportName = z.string().regex(/^[A-Za-z_$][\w$]*$/, "a JavaScript export name");
156
+
157
+ const PluginEntrySchema: z.ZodType<PluginEntry> = z
158
+ .looseObject({
159
+ id: z.string().regex(CONTRIBUTION_ID, "lower-case letters, digits, '.', '_' and '-' (1 to 64)"),
160
+ entry: packagePath,
161
+ export: exportName.exactOptional(),
162
+ })
163
+ .register(pluginManifestRegistry, { id: "PluginEntry" });
164
+
165
+ const PluginCommandEntrySchema: z.ZodType<PluginCommandEntry> = z
166
+ .looseObject({
167
+ command: z
168
+ .string()
169
+ .regex(
170
+ /^[a-z][a-z0-9-]{0,31}(?: [a-z][a-z0-9-]{0,31}){0,3}$/,
171
+ "one to four lower-case words separated by single spaces",
172
+ ),
173
+ entry: packagePath,
174
+ export: exportName.exactOptional(),
175
+ })
176
+ .register(pluginManifestRegistry, { id: "PluginCommandEntry" });
177
+
178
+ const PluginPackEntrySchema: z.ZodType<PluginPackEntry> = z
179
+ .looseObject({ item: packagePath })
180
+ .register(pluginManifestRegistry, { id: "PluginPackEntry" });
181
+
182
+ const entries = PluginEntrySchema.array().readonly().exactOptional();
183
+
184
+ const PluginContributesSchema: z.ZodType<PluginContributes> = z
185
+ .looseObject({
186
+ embedEngines: entries,
187
+ exporters: entries,
188
+ verifyChecks: entries,
189
+ anchorProviders: entries,
190
+ connectors: entries,
191
+ cliCommands: PluginCommandEntrySchema.array().readonly().exactOptional(),
192
+ packs: PluginPackEntrySchema.array().readonly().exactOptional(),
193
+ })
194
+ .register(pluginManifestRegistry, { id: "PluginContributes" });
195
+
196
+ const BundledLicenseSchema: z.ZodType<BundledLicense> = z
197
+ .looseObject({
198
+ package: z.string().min(1).max(214),
199
+ license: z.string().min(1).max(512),
200
+ class: LicenseClass.exactOptional(),
201
+ summary: z.string().max(400).exactOptional(),
202
+ url: z.url().exactOptional(),
203
+ })
204
+ .register(pluginManifestRegistry, { id: "BundledLicense" });
205
+
206
+ const PluginExampleSchema: z.ZodType<PluginExample> = z
207
+ .looseObject({
208
+ id: z.string().regex(CONTRIBUTION_ID),
209
+ path: packagePath,
210
+ baselines: packagePath.exactOptional(),
211
+ })
212
+ .register(pluginManifestRegistry, { id: "PluginExample" });
213
+
214
+ /** The Zod schema of the `PluginManifest` type, open to keys a later release adds. */
215
+ export const PluginManifestSchema: z.ZodType<PluginManifest> = z
216
+ .looseObject({
217
+ name: z.string().regex(PLUGIN_NAME, "<namespace>/<name>, the namespace in reverse-DNS form"),
218
+ title: z.string().min(1).max(80).exactOptional(),
219
+ description: z.string().max(400).exactOptional(),
220
+ contracts: z.partialRecord(ContractName, z.string().min(1).max(128)),
221
+ contributes: PluginContributesSchema,
222
+ effects: z.array(z.string()).readonly().exactOptional(),
223
+ license: z.string().min(1).max(512),
224
+ bundledLicenses: BundledLicenseSchema.array().readonly().exactOptional(),
225
+ skills: packagePath.array().readonly().exactOptional(),
226
+ examples: PluginExampleSchema.array().readonly().exactOptional(),
227
+ platforms: z.array(z.string()).readonly().exactOptional(),
228
+ })
229
+ .register(pluginManifestRegistry, {
230
+ id: "PluginManifest",
231
+ description:
232
+ 'The "mostra" key of a Mostra plugin\'s package.json (D30): its name, contract ranges, contributions, declared effects and licenses.',
233
+ });
234
+
235
+ /** One problem with a manifest, at a path under `package.json` (`["mostra", "contracts"]`). */
236
+ export interface ManifestIssue {
237
+ /** Its path, relative to the package or registry. */
238
+ readonly path: readonly (string | number)[];
239
+ /** How serious it is: `error` fails the check, `warning` and `hint` inform. */
240
+ readonly severity: "error" | "warning";
241
+ /** What it found, in plain words. */
242
+ readonly message: string;
243
+ }
244
+
245
+ /** What {@link checkPluginManifest} found. */
246
+ export interface ManifestCheck {
247
+ /** The manifest, when it has no error. */
248
+ readonly manifest?: PluginManifest;
249
+ /** Every problem, errors and warnings, in the order of the manifest. */
250
+ readonly issues: readonly ManifestIssue[];
251
+ }
252
+
253
+ const KNOWN_KEYS: Readonly<Record<string, readonly string[]>> = {
254
+ manifest: [
255
+ "$schema",
256
+ "name",
257
+ "title",
258
+ "description",
259
+ "contracts",
260
+ "contributes",
261
+ "effects",
262
+ "license",
263
+ "bundledLicenses",
264
+ "skills",
265
+ "examples",
266
+ "platforms",
267
+ ],
268
+ contributes: [...CONTRACT_NAMES.map((name) => PLUGIN_CONTRACTS[name].key), "packs"],
269
+ entry: ["id", "entry", "export", "title"],
270
+ command: ["command", "entry", "export"],
271
+ pack: ["item"],
272
+ license: ["package", "license", "class", "summary", "url"],
273
+ example: ["id", "path", "baselines"],
274
+ };
275
+
276
+ /** The contract each `contributes` key's contributions implement. */
277
+ export const CONTRACT_OF_KEY: Readonly<Record<ContributesKey, ContractNameType>> =
278
+ Object.fromEntries(CONTRACT_NAMES.map((name) => [PLUGIN_CONTRACTS[name].key, name])) as Record<
279
+ ContributesKey,
280
+ ContractNameType
281
+ >;
282
+
283
+ /**
284
+ * Checks the `"mostra"` key of a `package.json` (`value`), reporting every problem with its path.
285
+ * Unknown keys are warnings, so manifests grow additively; everything Mostra can't load is an
286
+ * error.
287
+ */
288
+ export function checkPluginManifest(value: unknown): ManifestCheck {
289
+ const issues: ManifestIssue[] = [];
290
+ const at = (...path: (string | number)[]): (string | number)[] => ["mostra", ...path];
291
+ const error = (message: string, ...path: (string | number)[]): void => {
292
+ issues.push({ path: at(...path), severity: "error", message });
293
+ };
294
+ const warn = (message: string, ...path: (string | number)[]): void => {
295
+ issues.push({ path: at(...path), severity: "warning", message });
296
+ };
297
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
298
+ error("The mostra key must be an object: the plugin's manifest.");
299
+ return { issues };
300
+ }
301
+ const parsed = PluginManifestSchema.safeParse(value);
302
+ if (!parsed.success) {
303
+ for (const issue of parsed.error.issues) {
304
+ const path = issue.path.filter(
305
+ (part): part is string | number => typeof part === "string" || typeof part === "number",
306
+ );
307
+ if (issue.code === "unrecognized_keys") {
308
+ // Only `contracts` is closed: a contract this release doesn't implement can't load.
309
+ for (const key of issue.keys) {
310
+ error(
311
+ `Mostra implements no contract "${key}"; it implements ${CONTRACT_NAMES.join(", ")}.`,
312
+ ...path,
313
+ key,
314
+ );
315
+ }
316
+ } else error(issueMessage(issue), ...path);
317
+ }
318
+ }
319
+ const raw = value as Record<string, unknown>;
320
+ const unknownKeys = (object: unknown, known: readonly string[], ...path: (string | number)[]) => {
321
+ if (typeof object !== "object" || object === null || Array.isArray(object)) return;
322
+ for (const key of Object.keys(object)) {
323
+ if (!known.includes(key)) {
324
+ warn(`This Mostra release doesn't know the key "${key}"; it is ignored.`, ...path, key);
325
+ }
326
+ }
327
+ };
328
+ unknownKeys(raw, KNOWN_KEYS["manifest"] ?? []);
329
+ unknownKeys(raw["contributes"], KNOWN_KEYS["contributes"] ?? [], "contributes");
330
+ const contributes = (raw["contributes"] ?? {}) as Record<string, unknown>;
331
+ for (const [key, list] of Object.entries(contributes)) {
332
+ if (!Array.isArray(list)) continue;
333
+ list.forEach((item, index) => {
334
+ const known =
335
+ key === "cliCommands"
336
+ ? KNOWN_KEYS["command"]
337
+ : key === "packs"
338
+ ? KNOWN_KEYS["pack"]
339
+ : KNOWN_KEYS["entry"];
340
+ unknownKeys(item, known ?? [], "contributes", key, index);
341
+ });
342
+ }
343
+ if (Array.isArray(raw["bundledLicenses"])) {
344
+ raw["bundledLicenses"].forEach((item, index) => {
345
+ unknownKeys(item, KNOWN_KEYS["license"] ?? [], "bundledLicenses", index);
346
+ });
347
+ }
348
+ if (Array.isArray(raw["examples"])) {
349
+ raw["examples"].forEach((item, index) => {
350
+ unknownKeys(item, KNOWN_KEYS["example"] ?? [], "examples", index);
351
+ });
352
+ }
353
+ // The rules beyond the schema run on what the manifest holds even when part of it is wrong, so
354
+ // one run reports every invalid field (EX-02); each looks only at values of the right type.
355
+ const view = lenientView(raw);
356
+ // Each kind of contribution needs its contract, and IDs are unique per contract.
357
+ let contributions = 0;
358
+ for (const name of CONTRACT_NAMES) {
359
+ const key = PLUGIN_CONTRACTS[name].key;
360
+ const list = view.contributes[key];
361
+ if (list === undefined) continue;
362
+ contributions += list.length;
363
+ if (list.length > 0 && !view.contracts.has(name)) {
364
+ error(
365
+ `contributes.${key} needs the contract it implements: add "${name}" with a range to contracts.`,
366
+ "contributes",
367
+ key,
368
+ );
369
+ }
370
+ const seen = new Map<string, number>();
371
+ list.forEach((item, index) => {
372
+ const id = key === "cliCommands" ? item["command"] : item["id"];
373
+ if (typeof id !== "string") return;
374
+ const first = seen.get(id);
375
+ if (first !== undefined) {
376
+ error(
377
+ `"${id}" is contributed twice (also at contributes.${key}[${first}]).`,
378
+ "contributes",
379
+ key,
380
+ index,
381
+ );
382
+ } else seen.set(id, index);
383
+ if (key === "cliCommands") {
384
+ const taken = coreCommandTaken(id.split(" "));
385
+ if (taken !== undefined) {
386
+ error(
387
+ `"mostra ${id}" would collide with Mostra's own "mostra ${taken.join(" ")}".`,
388
+ "contributes",
389
+ key,
390
+ index,
391
+ "command",
392
+ );
393
+ }
394
+ }
395
+ });
396
+ }
397
+ for (const name of view.contracts) {
398
+ const key = PLUGIN_CONTRACTS[name].key;
399
+ if ((view.contributes[key]?.length ?? 0) === 0) {
400
+ warn(
401
+ `The manifest declares the ${name} contract but contributes nothing to it.`,
402
+ "contracts",
403
+ name,
404
+ );
405
+ }
406
+ }
407
+ if (
408
+ view.contributesObject &&
409
+ contributions === 0 &&
410
+ (view.contributes["packs"]?.length ?? 0) === 0
411
+ ) {
412
+ error("The plugin contributes nothing: add an entry to contributes.", "contributes");
413
+ }
414
+ // Licenses: the plugin's own, and each bundled one, must be expressions Mostra can read.
415
+ if (typeof raw["license"] === "string") {
416
+ try {
417
+ parseLicenseExpression(raw["license"]);
418
+ } catch (problem) {
419
+ if (!(problem instanceof LicenseExpressionError)) throw problem;
420
+ error(
421
+ `${problem.message} Use an SPDX expression, or LicenseRef-<name> for another license.`,
422
+ "license",
423
+ );
424
+ }
425
+ }
426
+ view.bundledLicenses.forEach((bundled, index) => {
427
+ const license = bundled["license"];
428
+ if (typeof license === "string") {
429
+ try {
430
+ parseLicenseExpression(license);
431
+ } catch (problem) {
432
+ if (!(problem instanceof LicenseExpressionError)) throw problem;
433
+ error(problem.message, "bundledLicenses", index, "license");
434
+ }
435
+ }
436
+ const licenseClass = bundled["class"];
437
+ if (typeof licenseClass === "string" && typeof license === "string") {
438
+ if (!isLicenseRef(license)) {
439
+ error(
440
+ "class applies only to a LicenseRef-: Mostra classes SPDX licenses from the SPDX License List itself.",
441
+ "bundledLicenses",
442
+ index,
443
+ "class",
444
+ );
445
+ } else if (
446
+ !ACKNOWLEDGED_CLASSES.has(licenseClass as LicenseClass) ||
447
+ licenseClass === "unknown"
448
+ ) {
449
+ error(
450
+ 'A LicenseRef- is never OSI-approved: its class is "source-available" or "proprietary".',
451
+ "bundledLicenses",
452
+ index,
453
+ "class",
454
+ );
455
+ }
456
+ }
457
+ });
458
+ view.effects.forEach((effect, index) => {
459
+ if (typeof effect === "string" && !PLUGIN_EFFECTS.includes(effect)) {
460
+ warn(
461
+ `This Mostra release doesn't know the effect "${effect}" (it knows ${PLUGIN_EFFECTS.join(", ")}); it is shown as declared.`,
462
+ "effects",
463
+ index,
464
+ );
465
+ }
466
+ });
467
+ view.platforms.forEach((platform, index) => {
468
+ if (typeof platform === "string" && !PLUGIN_PLATFORMS.includes(platform)) {
469
+ warn(
470
+ `"${platform}" isn't a system Mostra runs on (${PLUGIN_PLATFORMS.join(", ")}).`,
471
+ "platforms",
472
+ index,
473
+ );
474
+ }
475
+ });
476
+ if (!parsed.success) return { issues };
477
+ const manifest = parsed.data;
478
+ return issues.some((issue) => issue.severity === "error") ? { issues } : { manifest, issues };
479
+ }
480
+
481
+ /** What the rules beyond the schema read of a manifest, whatever its shape. */
482
+ interface LenientView {
483
+ /** The contracts it declares, by a name Mostra implements (any range). */
484
+ readonly contracts: ReadonlySet<ContractNameType>;
485
+ readonly contributesObject: boolean;
486
+ /** Each kind's list of objects. */
487
+ readonly contributes: Readonly<Record<string, readonly Record<string, unknown>[]>>;
488
+ readonly bundledLicenses: readonly Record<string, unknown>[];
489
+ readonly effects: readonly unknown[];
490
+ readonly platforms: readonly unknown[];
491
+ }
492
+
493
+ const isObject = (value: unknown): value is Record<string, unknown> =>
494
+ typeof value === "object" && value !== null && !Array.isArray(value);
495
+
496
+ function lenientView(raw: Record<string, unknown>): LenientView {
497
+ const contracts = new Set<ContractNameType>();
498
+ if (isObject(raw["contracts"])) {
499
+ for (const key of Object.keys(raw["contracts"])) {
500
+ if ((CONTRACT_NAMES as readonly string[]).includes(key))
501
+ contracts.add(key as ContractNameType);
502
+ }
503
+ }
504
+ const contributes: Record<string, Record<string, unknown>[]> = {};
505
+ if (isObject(raw["contributes"])) {
506
+ for (const [key, list] of Object.entries(raw["contributes"])) {
507
+ if (Array.isArray(list)) contributes[key] = list.filter(isObject);
508
+ }
509
+ }
510
+ return {
511
+ contracts,
512
+ contributesObject: isObject(raw["contributes"]),
513
+ contributes,
514
+ bundledLicenses: Array.isArray(raw["bundledLicenses"])
515
+ ? raw["bundledLicenses"].filter(isObject)
516
+ : [],
517
+ effects: Array.isArray(raw["effects"]) ? raw["effects"] : [],
518
+ platforms: Array.isArray(raw["platforms"]) ? raw["platforms"] : [],
519
+ };
520
+ }
521
+
522
+ /** A Zod issue in the manifest's words. */
523
+ function issueMessage(issue: z.core.$ZodIssue): string {
524
+ if (issue.code === "invalid_type") {
525
+ return issue.input === undefined
526
+ ? `This field is required (${issue.expected}).`
527
+ : `Expected ${issue.expected}.`;
528
+ }
529
+ if (issue.code === "invalid_value") {
530
+ return `Expected one of ${issue.values.map((value) => JSON.stringify(value)).join(", ")}.`;
531
+ }
532
+ if (issue.code === "invalid_format" && issue.format === "regex") {
533
+ return `Expected ${issue.message.replace(/^Invalid string: must match pattern .*$/, "the documented form")}.`;
534
+ }
535
+ return issue.message;
536
+ }
537
+
538
+ /** Where a plugin with this manifest may be installed: every scope its contracts allow. */
539
+ export function manifestScopes(manifest: PluginManifest): readonly ("artifact" | "home")[] {
540
+ const kinds = CONTRACT_NAMES.filter(
541
+ (name) => (manifest.contributes[PLUGIN_CONTRACTS[name].key]?.length ?? 0) > 0,
542
+ );
543
+ const packs = (manifest.contributes.packs?.length ?? 0) > 0;
544
+ const home = !packs && kinds.every((name) => PLUGIN_CONTRACTS[name].scopes.includes("home"));
545
+ return home ? ["artifact", "home"] : ["artifact"];
546
+ }