diff --git a/plugins/plugin-ops/.codex-plugin/plugin.json b/plugins/plugin-ops/.codex-plugin/plugin.json index 40cb1b9..e34cb42 100644 --- a/plugins/plugin-ops/.codex-plugin/plugin.json +++ b/plugins/plugin-ops/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-ops", - "version": "0.2.3", + "version": "0.2.4", "description": "Install, update, migrate, and validate Codex plugins and marketplace catalogs.", "author": { "name": "Melodic Software", diff --git a/plugins/plugin-ops/skills/verify-plugin/SKILL.md b/plugins/plugin-ops/skills/verify-plugin/SKILL.md index 9161583..1abc4f5 100644 --- a/plugins/plugin-ops/skills/verify-plugin/SKILL.md +++ b/plugins/plugin-ops/skills/verify-plugin/SKILL.md @@ -43,7 +43,8 @@ contract or repository-adaptation design is correct. node /scripts/validate-marketplace.mjs ``` - Add `--json` when machine-readable output is useful. + Add `--json` when machine-readable output is useful; its shape is the + contract in [JSON output](#json-output). 4. Fix structural errors before judgment-based review. Do not weaken the validator to accept a malformed package. 5. Review the user-goal and architecture contract: @@ -80,3 +81,19 @@ contract or repository-adaptation design is correct. Report errors first, then warnings and untested behavior. Include exact file paths, commands, live upstream URLs and date checked, context cases, adapter and fallback decisions, and behavioral evidence. + +## JSON output + +`--json` prints one object with these keys, in this order. Paths are absolute. + +| Key | Type | Meaning | +| --- | --- | --- | +| `target` | string | Validated root. | +| `kind` | `"marketplace"`, `"plugin"`, or `null` | What the target was; `null` when the target is neither or could not be inspected. | +| `catalog` | string or `null` | Catalog Codex loads; `null` for a plugin target. | +| `manifests` | array | One `{plugin, manifest, format}` per resolved plugin: its root, the manifest Codex loads, and `format` (`agent-plugin`, `codex`, `claude`, or `cursor`). An entry may add `overlay`, the `.codex-plugin` file read as the Codex overlay. | +| `errors` | array | `{code, file, message}` entries that fail validation. | +| `warnings` | array | `{code, file, message}` entries that do not. | + +Adding a key is compatible. Renaming or removing one, or changing its type, is +breaking. The exit code is 0 only when `errors` is empty. diff --git a/plugins/plugin-ops/skills/verify-plugin/scripts/validate-marketplace.test.mjs b/plugins/plugin-ops/skills/verify-plugin/scripts/validate-marketplace.test.mjs index 40ab6d3..dd3caa2 100644 --- a/plugins/plugin-ops/skills/verify-plugin/scripts/validate-marketplace.test.mjs +++ b/plugins/plugin-ops/skills/verify-plugin/scripts/validate-marketplace.test.mjs @@ -177,6 +177,8 @@ test("rejects an unparsable marketplace file", async (t) => { }); test("skips a catalog slot that is not a file, as Codex does", async (t) => { + // Codex checks `is_file()` on each `MARKETPLACE_MANIFEST_RELATIVE_PATHS` entry in + // codex-rs/core-plugins/src/marketplace.rs (rust-v0.162.0). const root = await tempRoot(t); await mkdir(path.join(root, ".agents", "plugins", "marketplace.json"), { recursive: true }); const result = await validateTarget(root); @@ -834,6 +836,7 @@ test("command line emits the documented result shape with --json", async (t) => const root = await completeMarketplace(t); const { stdout } = await run(process.execPath, [VALIDATOR, root, "--json"]); const parsed = JSON.parse(stdout); + // The key list is the contract in SKILL.md, section "JSON output". assert.deepEqual(Object.keys(parsed), ["target", "kind", "catalog", "manifests", "errors", "warnings"]); assert.equal(parsed.target, root); assert.equal(parsed.kind, "marketplace"); diff --git a/tests/plugin-ops-plugin.test.mjs b/tests/plugin-ops-plugin.test.mjs index 1212e03..599c1ea 100644 --- a/tests/plugin-ops-plugin.test.mjs +++ b/tests/plugin-ops-plugin.test.mjs @@ -12,7 +12,7 @@ const paths = skillPaths("plugin-ops"); test("the marketplace exposes the Plugin Ops plugin", async () => { await assertMarketplacePlugin({ name: "plugin-ops", - version: "0.2.3", + version: "0.2.4", category: "Developer Tools", }); });