From 15da8bdac4384f01c4aba0ebd1f7602bc1b1bfcd Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 10 Oct 2026 23:52:33 -0400 Subject: [PATCH 1/2] docs(plugin-ops): document the verify-plugin --json output as a contract Add a JSON output section to verify-plugin listing the top-level keys in order, their types, and the compatibility rule. Point the shape test at that section and cite Codex's is_file() catalog-slot check in the skip test. Bump plugin-ops to 0.2.4. Co-Authored-By: Claude Opus 5.5 --- plugins/plugin-ops/.codex-plugin/plugin.json | 2 +- .../plugin-ops/skills/verify-plugin/SKILL.md | 19 ++++++++++++++++++- .../scripts/validate-marketplace.test.mjs | 3 +++ tests/plugin-ops-plugin.test.mjs | 2 +- 4 files changed, 23 insertions(+), 3 deletions(-) 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..32658ce 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 neither was found. | +| `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", }); }); From 694434c9bec420133ffe53427e734528ecc9de85 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 10 Oct 2026 23:53:16 -0400 Subject: [PATCH 2/2] docs(plugin-ops): note kind is null when the target cannot be inspected Co-Authored-By: Claude Opus 5.5 --- plugins/plugin-ops/skills/verify-plugin/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/plugin-ops/skills/verify-plugin/SKILL.md b/plugins/plugin-ops/skills/verify-plugin/SKILL.md index 32658ce..1abc4f5 100644 --- a/plugins/plugin-ops/skills/verify-plugin/SKILL.md +++ b/plugins/plugin-ops/skills/verify-plugin/SKILL.md @@ -89,7 +89,7 @@ fallback decisions, and behavioral evidence. | Key | Type | Meaning | | --- | --- | --- | | `target` | string | Validated root. | -| `kind` | `"marketplace"`, `"plugin"`, or `null` | What the target was; `null` when neither was found. | +| `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. |