universal-plugin 0.3.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.mjs

@@ -3,6 +3,7 @@ import { Command, Option } from "commander";
 import * as fsNode from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { encode } from "@toon-format/toon";
 import { fileURLToPath } from "node:url";
 import * as childProcess from "node:child_process";
 import * as semver from "semver";
@@ -158,21 +159,6 @@ function cleanCommand() {
 function printJson(data) {
 	console.log(JSON.stringify(data, null, 2));
 }
-function printFields(fields) {
-	const entries = Object.entries(fields).filter(([, v]) => v != null);
-	const width = Math.max(...entries.map(([k]) => k.length));
-	for (const [key, val] of entries) console.log(`${key.padEnd(width)}  ${val}`);
-}
-function printTable(items, cols) {
-	if (items.length === 0) {
-		console.log("(none)");
-		return;
-	}
-	const widths = cols.map((c) => Math.max(c.label.length, ...items.map((i) => c.get(i).length)));
-	console.log(cols.map((c, i) => c.label.toUpperCase().padEnd(widths[i])).join("  "));
-	console.log(widths.map((w) => "-".repeat(w)).join("  "));
-	for (const item of items) console.log(cols.map((c, i) => c.get(item).padEnd(widths[i])).join("  "));
-}
 function getFormat() {
 	const argv = process.argv;
 	const fmtIdx = argv.indexOf("--format");
@@ -182,9 +168,20 @@ function getFormat() {
 function isJsonOutput() {
 	return getFormat() === "json";
 }
-function output(data, readable) {
+/** Print the machine result on stdout: JSON when asked for, TOON otherwise (AXI #1).
+*
+* `view` is the default format's payload, carrying the minimal row schema and the
+* pre-computed aggregates a reader needs (AXI #2, #4). It defaults to `data`, which
+* suits a command whose full result is already minimal. */
+function output(data, view) {
+	if (isJsonOutput()) printJson(data);
+	else console.log(encode(view ?? data));
+}
+/** Print a result whose default rendering is a document body rather than a record.
+* `--format json` still emits the structured payload. */
+function outputText(data, text) {
 	if (isJsonOutput()) printJson(data);
-	else readable();
+	else text();
 }
 //#endregion
 //#region src/json.ts
@@ -419,30 +416,22 @@ function buildCommand() {
 			});
 			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
 			const { built, skipped, failed, canonical } = result.summary;
-			output({
+			const jsonResult = {
 				built: result.rows.filter((r) => r.status === "built"),
 				skipped: result.rows.filter((r) => r.status === "skipped"),
 				failed: result.rows.filter((r) => r.status === "failed"),
 				canonical: result.rows.filter((r) => r.status === "canonical"),
 				summary: result.summary,
 				warnings: result.warnings
-			}, () => {
-				if (result.rows.length > 0) printTable(result.rows, [
-					{
-						label: "vendor",
-						get: (r) => r.vendor
-					},
-					{
-						label: "path",
-						get: (r) => r.path
-					},
-					{
-						label: "status",
-						get: (r) => r.status
-					}
-				]);
-				const counts = `built ${built}, skipped ${skipped}, failed ${failed}`;
-				console.log(canonical > 0 ? `${counts}, served by plugin.json ${canonical}` : counts);
+			};
+			const counts = `built ${built}, skipped ${skipped}, failed ${failed}`;
+			output(jsonResult, {
+				vendors: result.rows.map((r) => ({
+					vendor: r.vendor,
+					path: r.path,
+					status: r.status
+				})),
+				summary: canonical > 0 ? `${counts}, served by plugin.json ${canonical}` : counts
 			});
 			process.stderr.write(NEXT_STEP$2);
 			if (failed > 0) process.exitCode = 1;
@@ -730,29 +719,17 @@ function bundleCommand() {
 			const pinned = result.pins.filter((p) => p.status === "pinned").length;
 			const unchanged = result.pins.filter((p) => p.status === "unchanged").length;
 			const skipped = result.pins.filter((p) => p.status === "skipped").length;
-			output({ pins: result.pins }, () => {
-				const truncated = !opts.full && result.pins.length > TRUNCATE_THRESHOLD;
-				const rows = truncated ? result.pins.slice(0, TRUNCATE_THRESHOLD) : result.pins;
-				if (rows.length > 0) printTable(rows, [
-					{
-						label: "package",
-						get: (r) => r.package
-					},
-					{
-						label: "current",
-						get: (r) => r.current
-					},
-					{
-						label: "resolved",
-						get: (r) => r.resolved
-					},
-					{
-						label: "status",
-						get: (r) => r.status
-					}
-				]);
-				if (truncated) console.log(`… +${result.pins.length - TRUNCATE_THRESHOLD} more — rerun with --full`);
-				console.log(`pinned ${pinned}, unchanged ${unchanged}, skipped ${skipped}`);
+			const truncated = !opts.full && result.pins.length > TRUNCATE_THRESHOLD;
+			const shown = truncated ? result.pins.slice(0, TRUNCATE_THRESHOLD) : result.pins;
+			output({ pins: result.pins }, {
+				pins: shown.map((r) => ({
+					package: r.package,
+					current: r.current,
+					resolved: r.resolved,
+					status: r.status
+				})),
+				...truncated ? { truncated: `… +${result.pins.length - TRUNCATE_THRESHOLD} more — rerun with --full` } : {},
+				summary: `pinned ${pinned}, unchanged ${unchanged}, skipped ${skipped}`
 			});
 			if (result.pins.length === 0) process.stderr.write("nothing to bundle\n");
 			process.stderr.write(NEXT_STEP$1);
@@ -853,22 +830,11 @@ function addCommand(fs) {
 				key: opts.key,
 				name: result.name,
 				action: result.action
-			}, () => {
-				printTable([result], [
-					{
-						label: "key",
-						get: () => opts.key
-					},
-					{
-						label: "name",
-						get: (r) => r.name
-					},
-					{
-						label: "action",
-						get: (r) => r.action
-					}
-				]);
-				console.log(`${opts.key}: ${count} entries`);
+			}, {
+				key: opts.key,
+				name: result.name,
+				action: result.action,
+				summary: `${opts.key}: ${count} entries`
 			});
 			process.stderr.write(`→ universal-plugin config get --key ${opts.key}\n`);
 		} catch (err) {
@@ -883,12 +849,9 @@ function getCommand(fs) {
 			assertNotReserved(opts.key);
 			const root = resolveRoot(opts.root);
 			const entries = getEntries(fs.read(root), opts.key);
-			output(entries, () => {
-				printTable(entries, [{
-					label: "name",
-					get: (e) => String(e.name ?? "")
-				}]);
-				console.log(`${opts.key}: ${entries.length} entries`);
+			output(entries, {
+				names: entries.map((e) => String(e.name ?? "")),
+				summary: `${opts.key}: ${entries.length} entries`
 			});
 			process.stderr.write(`→ universal-plugin config add --key ${opts.key} --entry <json>\n`);
 		} catch (err) {
@@ -1026,20 +989,18 @@ function governanceCommand() {
 			process.stderr.write(`Governance "${name}" not found\n`);
 			process.exit(1);
 		}
-		output(result, () => {
+		outputText(result, () => {
 			process.stdout.write(result.content);
 		});
 	});
 	cmd.command("list").description("List available governances").option("--format <format>", "Output format: json or text (default: text)").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((opts) => {
 		const entries = listGovernances(resolveRoot(opts.root), realGovernanceFs);
-		output(entries, () => {
-			printTable(entries, [{
-				label: "name",
-				get: (e) => e.name
-			}, {
-				label: "scope",
-				get: (e) => e.scope
-			}]);
+		output(entries, {
+			governances: entries.map((e) => ({
+				name: e.name,
+				scope: e.scope
+			})),
+			summary: `${entries.length} governances across ${new Set(entries.map((e) => e.scope)).size} scopes`
 		});
 	});
 	return cmd;
@@ -1172,15 +1133,12 @@ function initCommand$1(deps = { fs: realInitFs }) {
 				created: plan.rows.filter((r) => r.action === "created").map((r) => r.path),
 				updated: plan.rows.filter((r) => r.action === "updated").map((r) => r.path),
 				summary: plan.summary
-			}, () => {
-				printTable(plan.rows, [{
-					label: "path",
-					get: (r) => r.path
-				}, {
-					label: "action",
-					get: (r) => r.action
-				}]);
-				console.log(`created ${plan.summary.created}, updated ${plan.summary.updated}`);
+			}, {
+				files: plan.rows.map((r) => ({
+					path: r.path,
+					action: r.action
+				})),
+				summary: `created ${plan.summary.created}, updated ${plan.summary.updated}`
 			});
 			process.stderr.write(NEXT_STEP);
 		} catch (err) {
@@ -1496,24 +1454,15 @@ function initCommand() {
 				dryRun: opts.dryRun,
 				force: opts.force
 			});
-			output(results, () => printTable(results, [
-				{
-					label: "target",
-					get: (row) => row.target
-				},
-				{
-					label: "status",
-					get: (row) => row.status
-				},
-				{
-					label: "paths",
-					get: (row) => row.paths.join(", ") || "-"
-				},
-				{
-					label: "plugins",
-					get: (row) => row.plugins.join(", ") || "-"
-				}
-			]));
+			output(results, {
+				targets: results.map((row) => ({
+					target: row.target,
+					status: row.status,
+					paths: row.paths.join(" ") || "-",
+					plugins: row.plugins.join(" ") || "-"
+				})),
+				summary: `${results.length} targets`
+			});
 			process.stderr.write("Generated repository metadata only; no marketplace publication, registration, installation, authentication, or provisioning occurred.\n");
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
@@ -1849,11 +1798,9 @@ function publishCommand() {
 	cmd.command("sync-version").description("Sync version from packagePath/package.json into plugin.json").addOption(ROOT_OPTION).action((opts) => {
 		try {
 			const result = syncVersion(resolveRoot(opts.root), realSyncVersionFs);
-			output(result, () => {
-				printFields({
-					version: result.version,
-					manifest: result.manifestPath
-				});
+			output(result, {
+				version: result.version,
+				manifest: result.manifestPath
 			});
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
@@ -2129,19 +2076,14 @@ function versionCommand(deps = { fs: realVersionFs }) {
 					derived: rows.filter((r) => r.action === "derived").length
 				}
 			};
-			output(jsonResult, () => {
-				printFields({
-					from: plan.from ?? "(none)",
-					to: plan.to
-				});
-				printTable(rows, [{
-					label: "path",
-					get: (r) => r.path
-				}, {
-					label: "action",
-					get: (r) => r.action
-				}]);
-				console.log(dryRun ? `planned ${plan.summary.updated}, updated 0 (dry run)` : `updated ${plan.summary.updated}, derived ${jsonResult.summary.derived}`);
+			output(jsonResult, {
+				from: plan.from ?? "(none)",
+				to: plan.to,
+				files: rows.map((r) => ({
+					path: r.path,
+					action: r.action
+				})),
+				summary: dryRun ? `planned ${plan.summary.updated}, updated 0 (dry run)` : `updated ${plan.summary.updated}, derived ${jsonResult.summary.derived}`
 			});
 			process.stderr.write(nextStep(dryRun, opts.build !== false));
 		} catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -25,6 +25,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "LICENSE",
     "bin",
     "dist",
     "governances",
@@ -36,6 +37,7 @@
     "agents"
   ],
   "dependencies": {
+    "@toon-format/toon": "^4.1.1",
     "commander": "^14.0.3",
     "semver": "^7.8.1"
   },

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -1,87 +1,95 @@
 # universal-plugin
 
 [![npm version](https://img.shields.io/npm/v/universal-plugin.svg)](https://www.npmjs.com/package/universal-plugin)
-[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/universal-plugin.svg)](https://www.npmjs.com/package/universal-plugin)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cyberuni/universal-plugin/blob/main/LICENSE)
 
-Universal AI agent plugin build tool. Author one canonical plugin manifest (root `plugin.json`) and generate vendor-specific manifests for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
-
-## Specification
-
-This package follows the [Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec).
-Consult that repository's versioned specification and releases before changing manifest
-or component compatibility behavior; it is the canonical reference for the current standard.
+Write one canonical plugin manifest (root `plugin.json`). Generate the vendor manifests for Claude
+Code, Cursor, Codex, and GitHub Copilot CLI.
 
 ## Usage
 
-No install required — run with `npx`:
+No install required:
 
 ```sh
 npx universal-plugin <command>
 ```
 
-Or pin to an exact version for reproducible builds:
+Pin an exact version for reproducible builds:
 
 ```sh
-npx universal-plugin@0.2.0 <command>
+npx universal-plugin@0.3.1 <command>
 ```
 
-## upx — the fast package runner
-
-`npm i -g universal-plugin` also puts a second bin, `upx`, on PATH. `upx <pkg>@^<major>` finds an
-already-installed version satisfying the range (local `node_modules` first, then global) and runs
-it directly — about 10× faster than `npx`'s ~1s per-call resolve+spawn cost — falling back to
-`npx` when nothing installed matches:
-
-```sh
-npm i -g universal-plugin
-upx cyber-skills@^2 audit validate
-```
+## Specification
 
-Use a caret range on the major, not an exact pin, so one global install serves every caller. `upx`
-needs to be installed to be on PATH; `npx` always ships with npm, so `npx` remains the safe default
-where `universal-plugin` isn't installed globally.
+This package follows the [Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec).
+That repository is the canonical reference. Consult its versioned specification and releases before
+you change manifest or component compatibility behavior.
 
 ## Commands
 
-### plugin — author the canonical manifest
+### plugin
+
+Author the canonical manifest and derive everything from it.
 
 ```sh
-# Generate vendor manifests from root plugin.json
-npx universal-plugin plugin build
+npx universal-plugin plugin init                 # scaffold plugin.json
+npx universal-plugin plugin init --npm           # also wire an npm package to ship it
+npx universal-plugin plugin build                # generate vendor manifests
+npx universal-plugin plugin version <bump>       # move the version across every file carrying one
+npx universal-plugin plugin bundle               # pin skill npx references to workspace versions
 ```
 
-`validate` and `init` are specified but implementation is deferred.
+`build` writes `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, and
+`.codex-plugin/plugin.json`. Copilot CLI reads the canonical root `plugin.json` directly, so no
+fourth file is derived.
+
+Each command writes JSON with `JSON.stringify`. Your repository decides how JSON looks, so run your
+formatter after any command that writes a manifest.
 
-### sync — cross-vendor plugin sync
+### sync
+
+Move an installed plugin from the runtime that installed it to the others.
 
 ```sh
-# Detect cross-vendor sync actions from a vendor's manifest
 npx universal-plugin prepare <vendor-id>              # e.g. claude-code
 npx universal-plugin prepare <vendor-id> --scope project --root <path>
-npx universal-plugin prepare <vendor-id> --dry-run    # print action count without writing state
-
-# Apply a pending sync action
+npx universal-plugin prepare <vendor-id> --dry-run    # print the action count without writing state
 npx universal-plugin sync apply <action-id>
 ```
 
 ### publish
 
 ```sh
-# Sync version from packagePath/package.json into root plugin.json
-npx universal-plugin publish sync-version
+npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json
 ```
 
+This writes the canonical `plugin.json` only. Run `plugin build` afterwards, or the vendor manifests
+keep their previous version.
+
 ### marketplace
 
 ```sh
-# Generate a local Codex catalog from canonical plugin manifests.
 npx universal-plugin marketplace init --codex --root .
 ```
 
-Codex caches a local plugin install by its marketplace entry version. After changing packaged plugin
-files, update the canonical `plugin.json` version, regenerate the Codex catalog (use `--force` when
-replacing an existing catalog), reinstall the plugin, and start a new Codex session. This ensures the
-installed copy and its generated marketplace entry use the same version.
+Codex caches a local plugin install by its marketplace entry version. After you change packaged
+plugin files: update the canonical `plugin.json` version, regenerate the catalog (add `--force` to
+replace an existing one), reinstall the plugin, then start a new Codex session. The installed copy
+and its marketplace entry then carry the same version.
+
+### config
+
+Read and write plugin-registered config in `.agents/universal-plugin.json`.
+
+```sh
+npx universal-plugin config get --key sdd-plugins
+npx universal-plugin config add --key sdd-plugins --entry '{"name":"aces","handles":["agent evaluation"]}'
+```
+
+`add` appends the entry, or replaces the existing entry with the same `name`. Both commands print
+TOON by default; pass `--format json` for JSON.
 
 ### governance
 
@@ -99,6 +107,29 @@ npx universal-plugin clean                            # remove the asset store
 npx universal-plugin self-update <version>            # update the version pin in hook files
 ```
 
+## upx, the fast package runner
+
+`npm i -g universal-plugin` puts a second bin, `upx`, on PATH.
+
+`upx <pkg>@^<major>` looks for an already-installed version satisfying the range, checking local
+`node_modules` first and then global. It spawns that binary directly, skipping the resolve step that
+costs `npx` roughly 1s per call. When nothing installed matches, it falls back to `npx`.
+
+```sh
+npm i -g universal-plugin
+upx cyber-skills@^2 audit validate
+```
+
+Use a caret range on the major rather than an exact pin, so one global install serves every caller.
+
+`upx` only works once `universal-plugin` is installed globally. `npx` ships with npm, so keep `npx`
+as the default anywhere you cannot guarantee that install.
+
+## Related
+
+This package publishes a plugin. To set up the agent configuration of a repository you work in, use
+[`buddy-agent-harness`](https://github.com/repobuddy/buddy-agent-harness).
+
 ## License
 
-MIT
+[MIT](https://github.com/cyberuni/universal-plugin/blob/main/LICENSE)

package/skills/doctor/README.md

@@ -0,0 +1,42 @@
+# doctor skill
+
+Diagnose a universal agent plugin: what the canonical `plugin.json` declares, and whether what is on
+disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
+
+## What it does
+
+`scripts/doctor.mjs` composes the shipped CLI's `plugin build --dry-run --format json` with the
+filesystem facts that build cannot see — whether each derived manifest exists, whether it predates
+the canonical manifest, whether a stale or shadowing manifest is lying around, and whether the two
+authored version numbers still agree. It emits one JSON object: `vendors`, `findings`, `ok`.
+
+The skill supplies the judgment around it: which finding matters, and which skill owns its repair.
+
+## It never repairs
+
+Every finding names the skill that fixes it — `init` for anything that rewrites the manifest,
+`version` for the release number, `remove-plugin` for artifacts. A repair can overwrite a manifest
+the user maintains, and that judgment belongs to the skill that owns the write.
+
+The script is read-only and exits `0` whether or not it finds anything, so it is safe to run
+unattended, including from a session-start hook.
+
+## Why a script rather than a checklist
+
+The checks are deterministic: same tree, same findings. The one check that is not scriptable is the
+definitive staleness test — rebuild on a clean tree and read the diff — because it writes. The skill
+reports that one as a repair for the user to run.
+
+Manifest validation is chartered as a CLI capability (`plugin validate`, specified but not yet
+shipped). This script stays a thin composition on purpose, so it folds into that command rather than
+competing with it.
+
+## Boundaries
+
+Diagnoses the plugin a project ships. A repository's own agent wiring — `.agents/skills/`,
+`AGENTS.md`, per-harness bridges — is `buddy-agent-harness:doctor`.
+
+## References
+
+- [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)
+- [`plugin build`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/build/README.md)