universal-plugin 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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

@@ -186,6 +186,140 @@ function output(data, readable) {
 	else readable();
 }
 //#endregion
+//#region src/pin/fs.ts
+const TEXT_EXTENSIONS = new Set([
+	".md",
+	".mdx",
+	".markdown",
+	".json",
+	".yaml",
+	".yml",
+	".txt"
+]);
+/** Resolves the plugin's skills directory: the manifest's `skills` field under `root`,
+*  defaulting to `<root>/skills/`. */
+function resolveSkillsDir(root, manifestSkills) {
+	return path.join(root, manifestSkills ?? "skills/");
+}
+function walk(dir) {
+	if (!fsNode.existsSync(dir)) return [];
+	const files = [];
+	for (const entry of fsNode.readdirSync(dir, { withFileTypes: true })) {
+		const entryPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) files.push(...walk(entryPath));
+		else if (entry.isFile() && TEXT_EXTENSIONS.has(path.extname(entry.name))) files.push(entryPath);
+	}
+	return files;
+}
+function realPinFs(skillsDir) {
+	return {
+		listSkillFiles: () => walk(skillsDir),
+		readFile: (p) => fsNode.readFileSync(p, "utf8"),
+		writeFile: (p, c) => fsNode.writeFileSync(p, c, "utf8")
+	};
+}
+//#endregion
+//#region src/pin/pin.ts
+const PIN_PATTERN = /npx\s+(?:--yes\s+|-y\s+)?([@a-z0-9/._-]+)@(\S+)/g;
+/** Strips a trailing backtick, quote, or paren that isn't part of the version token. */
+function stripTrailing(raw) {
+	return raw.replace(/[`'")]+$/, "");
+}
+function extractPins(text) {
+	const pins = [];
+	for (const match of text.matchAll(PIN_PATTERN)) {
+		const pkg = match[1];
+		const current = match[2];
+		if (!pkg || !current) continue;
+		pins.push({
+			pkg,
+			current: stripTrailing(current),
+			file: ""
+		});
+	}
+	return pins;
+}
+const SEMVER_PATTERN = /^[~^]?\d+\.\d+\.\d+$/;
+function isValidSemver(version) {
+	return SEMVER_PATTERN.test(version);
+}
+/** True when a pin is a concrete version (optionally range-prefixed), not a placeholder like `<version>`. */
+function isConcreteVersion(version) {
+	return isValidSemver(version);
+}
+function majorOf(version) {
+	const [major] = version.replace(/^[~^]/, "").split(".");
+	return Number(major);
+}
+/** Pure semver compare: -1 if a < b, 0 if equal, 1 if a > b. Ignores build/prerelease metadata. */
+function compareSemver(a, b) {
+	const partsA = a.split(".").map(Number);
+	const partsB = b.split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
+		if (diff !== 0) return diff > 0 ? 1 : -1;
+	}
+	return 0;
+}
+function pickTarget(current, available, opts) {
+	if (!isValidSemver(current)) return available.latest;
+	const currentBare = current.replace(/^[~^]/, "");
+	const currentMajor = majorOf(current);
+	const candidates = available.versions.filter((v) => {
+		if (!isValidSemver(v)) return false;
+		if (opts.allowMajor) return true;
+		return majorOf(v) === currentMajor;
+	});
+	if (candidates.length === 0) return currentBare;
+	let best = candidates[0];
+	for (const candidate of candidates.slice(1)) if (compareSemver(candidate, best) > 0) best = candidate;
+	if (compareSemver(best, currentBare) < 0) return currentBare;
+	return best;
+}
+function styleRange(version, style) {
+	switch (style) {
+		case "exact": return version;
+		case "tilde": return `~${version}`;
+		case "caret": return `^${version}`;
+	}
+}
+function normalizeRange(raw) {
+	switch (raw) {
+		case "exact": return "exact";
+		case "tilde":
+		case "~": return "tilde";
+		case "caret":
+		case "^": return "caret";
+		default: throw new Error(`Invalid --range value "${raw}" — expected exact, tilde, caret, ~, or ^`);
+	}
+}
+//#endregion
+//#region src/pin/registry.ts
+function encodePkg(pkg) {
+	return pkg.replace("/", "%2f");
+}
+/** Registry client backed by the global `fetch` (Node ≥22). Resilient — network errors and
+*  non-2xx responses resolve to `null` rather than throwing. */
+function realRegistryClient(registryBase) {
+	const base = registryBase.replace(/\/+$/, "");
+	return { async fetchVersions(pkg) {
+		try {
+			const res = await fetch(`${base}/${encodePkg(pkg)}`);
+			if (!res.ok) return null;
+			const doc = await res.json();
+			const latest = doc["dist-tags"]?.latest;
+			const versions = doc.versions ? Object.keys(doc.versions) : [];
+			if (!latest) return null;
+			return {
+				latest,
+				versions
+			};
+		} catch {
+			return null;
+		}
+	} };
+}
+//#endregion
 //#region src/build/build.ts
 const VENDOR_OUTPUT = {
 	"claude-code": ".claude-plugin/plugin.json",
@@ -194,6 +328,11 @@ const VENDOR_OUTPUT = {
 	"copilot-cli": "plugin.json"
 };
 const KNOWN_VENDORS = new Set(Object.keys(VENDOR_OUTPUT));
+function detectIndent$1(json) {
+	const match = json.match(/\n([ \t]+)/);
+	if (!match) return "	";
+	return match[1].startsWith("	") ? "	" : match[1].length;
+}
 function readManifest(root) {
 	const manifestPath = path.join(root, ".plugin", "plugin.json");
 	if (!fsNode.existsSync(manifestPath)) throw new Error(`No .plugin/plugin.json found at ${root}`);
@@ -207,6 +346,9 @@ function validateManifest(manifest) {
 	return errors;
 }
 function buildPlugin(root, opts = {}) {
+	const manifestPath = path.join(root, ".plugin", "plugin.json");
+	if (!fsNode.existsSync(manifestPath)) throw new Error(`No .plugin/plugin.json found at ${root}`);
+	const indent = detectIndent$1(fsNode.readFileSync(manifestPath, "utf8"));
 	const manifest = readManifest(root);
 	const errors = validateManifest(manifest);
 	if (errors.length > 0) throw new Error(`plugin.json validation failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
@@ -248,7 +390,7 @@ function buildPlugin(root, opts = {}) {
 		if (!opts.dryRun) {
 			if (opts.clean && fsNode.existsSync(outputPath)) fsNode.unlinkSync(outputPath);
 			fsNode.mkdirSync(outputDir, { recursive: true });
-			fsNode.writeFileSync(outputPath, `${JSON.stringify(vendorManifest, null, 2)}\n`);
+			fsNode.writeFileSync(outputPath, `${JSON.stringify(vendorManifest, null, indent)}\n`);
 		}
 		written.push(outputPath);
 	}
@@ -258,26 +400,112 @@ function buildPlugin(root, opts = {}) {
 		warnings
 	};
 }
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Rewrites every `npx <pkg>@<anything>` occurrence to `npx <pkg>@<next>`, regardless of the
+*  version each occurrence currently carries — so a plugin's references to one CLI converge
+*  (a concrete pin, a placeholder, and a stale pin all land on the same resolved value). */
+function rewritePin(content, pkg, next) {
+	const pattern = new RegExp(`(npx\\s+(?:--yes\\s+|-y\\s+)?${escapeRegExp(pkg)}@)[^\\s\`'")]+`, "g");
+	return content.replace(pattern, `$1${next}`);
+}
+/** Scans the plugin's skills for `npx <pkg>@<pin>` references and resolves each distinct
+*  in-scope package's current version from the registry, rewriting the pins in place. */
+async function resolvePins(root, opts, client, pinFs) {
+	const range = opts.range ?? "exact";
+	const files = pinFs.listSkillFiles();
+	const contents = /* @__PURE__ */ new Map();
+	const currentsByPkg = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const content = pinFs.readFile(file);
+		contents.set(file, content);
+		for (const pin of extractPins(content)) {
+			const list = currentsByPkg.get(pin.pkg) ?? [];
+			list.push(pin.current);
+			currentsByPkg.set(pin.pkg, list);
+		}
+	}
+	const scope = opts.packages && opts.packages.length > 0 ? new Set(opts.packages) : null;
+	const inScope = [...currentsByPkg.entries()].filter(([pkg]) => !scope || scope.has(pkg));
+	const results = [];
+	results.warnings = [];
+	for (const [pkg, currents] of inScope) {
+		const anchor = currents.find(isConcreteVersion) ?? currents[0];
+		const available = await client.fetchVersions(pkg);
+		if (!available) {
+			results.warnings.push(`registry lookup for "${pkg}" failed — skipped`);
+			results.push({
+				package: pkg,
+				current: anchor,
+				resolved: anchor,
+				status: "skipped"
+			});
+			continue;
+		}
+		const written = styleRange(pickTarget(anchor, available, { allowMajor: opts.allowMajor ?? false }), range);
+		let changed = false;
+		for (const file of files) {
+			const content = contents.get(file);
+			const rewritten = rewritePin(content, pkg, written);
+			if (rewritten !== content) {
+				changed = true;
+				contents.set(file, rewritten);
+				if (!opts.dryRun) pinFs.writeFile(file, rewritten);
+			}
+		}
+		results.push({
+			package: pkg,
+			current: anchor,
+			resolved: written,
+			status: changed ? "updated" : "unchanged"
+		});
+	}
+	return results;
+}
 //#endregion
 //#region src/build/cli.ts
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+function collect(value, previous) {
+	return [...previous, value];
+}
 function buildCommand() {
 	const cmd = new Command("build").description("Generate vendor manifests from .plugin/plugin.json");
-	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--format <format>", "Output format: json or text (default: text)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).action((opts) => {
+	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--format <format>", "Output format: json or text (default: text)").option("--registry <url>", "Registry to resolve pinned CLI versions from", DEFAULT_REGISTRY).option("--range <style>", "Pin style to write: exact, tilde, or caret (~/^ accepted)", "exact").option("--package <name>", "Limit pin resolution to this package (repeatable)", collect, []).option("--allow-major", "Allow pin resolution to cross a major version boundary").option("--skip-pins", "Skip pin resolution entirely (manifests only)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code --range tilde\n").action(async (opts) => {
 		try {
-			const result = buildPlugin(resolveRoot(opts.root), {
+			const root = resolveRoot(opts.root);
+			const result = buildPlugin(root, {
 				vendor: opts.vendor,
 				dryRun: opts.dryRun,
 				verbose: opts.verbose,
 				clean: opts.clean
 			});
 			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
-			output(result, () => {
-				if (result.vendors.length === 0) return;
-				printFields({ vendors: result.vendors.join(", ") });
-				printTable(result.written.map((p) => ({ path: p })), [{
-					label: "output",
-					get: (r) => opts.dryRun ? `(dry-run) ${r.path}` : r.path
-				}]);
+			let pins = Object.assign([], { warnings: [] });
+			if (!opts.skipPins) {
+				const skillsDir = resolveSkillsDir(root, readManifest(root).skills);
+				const client = realRegistryClient(opts.registry);
+				const pinFs = realPinFs(skillsDir);
+				pins = await resolvePins(root, {
+					packages: opts.package,
+					allowMajor: opts.allowMajor,
+					dryRun: opts.dryRun,
+					range: normalizeRange(opts.range)
+				}, client, pinFs);
+				for (const warning of pins.warnings) process.stderr.write(`warn: ${warning}\n`);
+			}
+			output({
+				...result,
+				pins
+			}, () => {
+				if (result.vendors.length > 0) {
+					printFields({ vendors: result.vendors.join(", ") });
+					printTable(result.written.map((p) => ({ path: p })), [{
+						label: "output",
+						get: (r) => opts.dryRun ? `(dry-run) ${r.path}` : r.path
+					}]);
+				}
+				for (const p of pins) console.log(`${p.package}  ${p.current} → ${p.resolved}  ${p.status}`);
 			});
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
@@ -309,6 +537,9 @@ function getUserDir() {
 function getProjectDir(root) {
 	return path.join(root, "governances");
 }
+function getLocalDir(root) {
+	return path.join(root, ".agents", "governances");
+}
 function getPackageDir() {
 	const thisFile = fileURLToPath(import.meta.url);
 	return path.join(path.dirname(thisFile), "..", "governances");
@@ -323,6 +554,10 @@ function getScopedPaths(root) {
 			scope: "project",
 			dir: getProjectDir(root)
 		},
+		{
+			scope: "local",
+			dir: getLocalDir(root)
+		},
 		{
 			scope: "user",
 			dir: getUserDir()
@@ -395,8 +630,8 @@ function readGlobalState() {
 	}
 }
 function governanceCommand() {
-	const cmd = new Command("governance").description("Manage plugin governances").addHelpCommand(false);
-	cmd.command("show <name>").description("Show a governance by name").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((name, opts) => {
+	const cmd = new Command("governance").description("Manage plugin governances").helpCommand(false);
+	cmd.command("show <name>").description("Show a governance by name").option("--format <format>", "Output format: json or text (default: text)").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((name, opts) => {
 		const result = showGovernance(name, resolveRoot(opts.root), realGovernanceFs, {
 			state: readGlobalState(),
 			globalStorePath: globalStorePath()
@@ -409,7 +644,7 @@ function governanceCommand() {
 			process.stdout.write(result.content);
 		});
 	});
-	cmd.command("list").description("List available governances").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((opts) => {
+	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, [{
@@ -655,6 +890,63 @@ function prepareCommand() {
 	});
 }
 //#endregion
+//#region src/publish/fs.ts
+const realSyncVersionFs = {
+	exists: (p) => fsNode.existsSync(p),
+	read: (p) => fsNode.readFileSync(p, "utf8"),
+	write: (p, content) => fsNode.writeFileSync(p, content)
+};
+//#endregion
+//#region src/publish/sync-version.ts
+function detectIndent(json) {
+	const match = json.match(/\n([ \t]+)/);
+	if (!match) return "	";
+	return match[1].startsWith("	") ? "	" : match[1].length;
+}
+function syncVersion(root, syncFs) {
+	const manifestPath = path.join(root, ".plugin", "plugin.json");
+	if (!syncFs.exists(manifestPath)) throw new Error(`No .plugin/plugin.json found at ${root}`);
+	const agentsConfigPath = path.join(root, ".agents", "universal-plugin.json");
+	const packagePath = (syncFs.exists(agentsConfigPath) ? JSON.parse(syncFs.read(agentsConfigPath)) : {})["packagePath"];
+	if (!packagePath || typeof packagePath !== "string") throw new Error("packagePath is required in .agents/universal-plugin.json");
+	const raw = syncFs.read(manifestPath);
+	const manifest = JSON.parse(raw);
+	const pkgJsonPath = path.join(root, packagePath, "package.json");
+	if (!syncFs.exists(pkgJsonPath)) throw new Error(`No package.json found at ${packagePath}`);
+	const version = JSON.parse(syncFs.read(pkgJsonPath))["version"];
+	if (!version || typeof version !== "string") throw new Error(`No version found in ${packagePath}/package.json`);
+	const indent = detectIndent(raw);
+	const updated = {
+		...manifest,
+		version
+	};
+	syncFs.write(manifestPath, `${JSON.stringify(updated, null, indent)}\n`);
+	return {
+		version,
+		manifestPath
+	};
+}
+//#endregion
+//#region src/publish/cli.ts
+function publishCommand() {
+	const cmd = new Command("publish").description("Prepare plugin for publishing").helpCommand(false);
+	cmd.command("sync-version").description("Sync version from packagePath/package.json into .plugin/plugin.json").addOption(ROOT_OPTION).action((opts) => {
+		try {
+			const result = syncVersion(resolveRoot(opts.root), realSyncVersionFs);
+			output(result, () => {
+				printFields({
+					version: result.version,
+					manifest: result.manifestPath
+				});
+			});
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+//#endregion
 //#region src/self-update/fs.ts
 function globalStatePath$1() {
 	return path.join(os.homedir(), ".agents", "universal-plugin.json");
@@ -776,7 +1068,7 @@ function realSyncFs() {
 	};
 }
 function syncCommand() {
-	const cmd = new Command("sync").description("Manage cross-vendor plugin sync").addHelpCommand(false);
+	const cmd = new Command("sync").description("Manage cross-vendor plugin sync").helpCommand(false);
 	cmd.command("apply").description("Apply a pending sync action").argument("<action-id>", "Action ID from ~/.agents/universal-plugin.json").action((actionId) => {
 		const result = applySyncAction({
 			actionId,
@@ -799,11 +1091,17 @@ function syncCommand() {
 //#endregion
 //#region src/cli.ts
 const program = new Command();
-program.name("universal-plugin").description("Universal AI agent plugin build tool").version("0.0.0").addHelpCommand(false);
-program.addCommand(buildCommand());
+program.name("universal-plugin").description("Universal AI agent plugin build tool").version("0.0.0").helpCommand(false);
+function pluginCommand() {
+	const cmd = new Command("plugin").description("Author the canonical plugin manifest (build; validate, init planned)");
+	cmd.addCommand(buildCommand());
+	return cmd;
+}
+program.addCommand(pluginCommand());
 program.addCommand(cleanCommand());
 program.addCommand(governanceCommand());
 program.addCommand(prepareCommand());
+program.addCommand(publishCommand());
 program.addCommand(syncCommand());
 program.addCommand(selfUpdateCommand());
 program.parseAsync(process.argv).catch((err) => {

package/governances/plugin-design.md

@@ -0,0 +1,279 @@
+# Plugin Design
+
+Authoritative rules for creating, validating, and transforming cross-vendor agent plugins. Apply when creating, auditing, or distributing a plugin; see **skill-design** governance for standalone skill authoring rules.
+
+A **plugin** is the distribution unit — it bundles skills, MCP servers, hooks, commands, agents, and other extensions into a single installable package. A **skill** is the capability unit inside a plugin. Install plugins; invoke skills.
+
+## Source of Truth: `.plugin/plugin.json`
+
+Author `.plugin/plugin.json` as the canonical manifest. All vendor manifests are derived from it via `build`. This file is never read directly by vendors at runtime; it is the single source that the build layer transforms into each vendor's manifest.
+
+Schema declaration (first field):
+
+```json
+{ "$schema": "https://schema.cyberuni.dev/universal-agent-plugin/v1.json" }
+```
+
+### Required fields
+
+| Field | Type | Constraint |
+| --- | --- | --- |
+| `name` | string | 1–64 chars. Pattern: `^[a-z0-9]([a-z0-9\-.]*[a-z0-9])?$`. Lowercase letters, digits, hyphens, periods only. No leading/trailing `-` or `.`. No `--` or `..`. |
+
+### Optional metadata fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `version` | string | semver. **Required by Codex** — build fails if absent. |
+| `description` | string | ≤ 1024 chars. **Required by Codex** — build fails if absent. |
+| `author` | object | `{ name, email, url }` — all sub-fields optional. |
+| `homepage` | string | URL. |
+| `repository` | string \| object | URL string or `{ type, url }` object. |
+| `license` | string | SPDX identifier (e.g. `"MIT"`). |
+| `keywords` | string[] | Searchable tags for marketplace discovery. |
+
+### Component path fields
+
+Each accepts `string | string[] | { paths: string[] }`. Every path must start with `./`. No `../` segments — traversal rejected by conformant hosts.
+
+| Field | Component | Core? | Notes |
+| --- | --- | --- | --- |
+| `skills` | Skill directories containing `SKILL.md` | Yes | Default: `./skills/` |
+| `mcpServers` | `.mcp.json` path or inline MCP config | Yes | Default: `./.mcp.json` |
+| `commands` | Slash command `.md` files | Extended | Default: `./commands/` |
+| `agents` | Agent `.md` files | Extended | Default: `./agents/` |
+| `rules` | Context rule `.mdc` files | Extended | Cursor-only; ignored by other hosts |
+| `hooks` | `hooks.json` path or inline hook config | Extended | Canonical uses PascalCase events; build translates per vendor |
+| `lspServers` | `.lsp.json` path | Extended | Claude Code only |
+| `outputStyles` | Output style resources directory | Extended | Claude Code only |
+
+A conformant host must support at least one core component (`skills` or `mcpServers`). Extended types are silently ignored on non-supporting hosts — do not rely on them for core plugin functionality.
+
+### `vendorExtensions` field
+
+Declares which vendor manifests `build` generates, and provides vendor-specific fields for each. Each key is a recognized vendor ID; its presence drives build output. An empty `{}` opts into that vendor's output with no vendor-specific fields.
+
+| Vendor ID | Output path | Required beyond `name` |
+| --- | --- | --- |
+| `claude-code` | `.claude-plugin/plugin.json` | none |
+| `cursor` | `.cursor-plugin/plugin.json` | none |
+| `codex` | `.codex-plugin/plugin.json` | `version`, `description` |
+| `copilot-cli` | `plugin.json` (repo root) | none |
+
+Vendor-specific extension fields:
+
+| Field | `claude-code` | `cursor` | `codex` | `copilot-cli` |
+| --- | --- | --- | --- | --- |
+| `displayName` | ✓ | — | — | — |
+| `defaultEnabled` | ✓ (bool) | — | — | — |
+| `userConfig` | ✓ (prompted at enable) | — | — | — |
+| `channels` | ✓ | — | — | — |
+| `dependencies` | ✓ (inter-plugin) | — | — | — |
+| `themes` | ✓ | — | — | — |
+| `monitors` | ✓ | — | — | — |
+| `logo` | — | ✓ | — | — |
+| `publisher` | — | ✓ | — | — |
+| `category` | — | ✓ | — | ✓ |
+| `tags` | — | ✓ | — | ✓ |
+| `apps` | — | — | ✓ (→ `.app.json`) | — |
+| `interface` | — | — | ✓ (marketplace metadata) | — |
+
+## Canonical Directory Layout
+
+```
+<plugin-name>/
+├── .plugin/
+│   └── plugin.json               ← canonical source of truth
+│
+├── skills/<skill-name>/SKILL.md  ← shared: all vendors, identical format
+│
+├── commands/setup.md             ← required when rules/ is present
+├── commands/<cmd-name>.md        ← Claude Code + Cursor + Copilot CLI
+├── agents/<agent-name>.md        ← Claude Code + Cursor + Copilot CLI
+├── rules/<rule-name>.mdc         ← Cursor-only always-on
+│
+├── hooks/hooks.json              ← canonical hooks (PascalCase, ${PLUGIN_ROOT})
+│
+├── .mcp.json                     ← source of truth (all vendors)
+├── mcp.json -> .mcp.json         ← symlink (Cursor + open-plugin-spec)
+│
+└── README.md
+```
+
+Generated build artifacts (gitignore or commit — author's choice):
+
+```
+├── .claude-plugin/
+│   ├── plugin.json               ← generated
+│   └── hooks/hooks.json          ← generated (PascalCase, ${CLAUDE_PLUGIN_ROOT})
+├── .cursor-plugin/
+│   ├── plugin.json               ← generated
+│   └── hooks/hooks.json          ← generated (camelCase, ${PLUGIN_ROOT} pass-through)
+├── .codex-plugin/
+│   ├── plugin.json               ← generated
+│   └── hooks/hooks.json          ← generated (PascalCase, ${PLUGIN_ROOT} native)
+└── plugin.json                   ← generated (copilot-cli root manifest)
+```
+
+## Vendor Manifest Derivation
+
+Build reads `.plugin/plugin.json`, applies the rules below, writes each vendor's output.
+
+### Metadata field mapping
+
+| Canonical field | Claude Code | Cursor | Codex | Copilot CLI |
+| --- | --- | --- | --- | --- |
+| `name` | ✓ required | ✓ required | ✓ required | ✓ required |
+| `version` | ✓ optional | ✓ optional | ✓ **required** | ✓ optional |
+| `description` | ✓ optional | ✓ optional | ✓ **required** | ✓ optional |
+| `author`, `homepage`, `repository`, `license`, `keywords` | ✓ | ✓ | ✓ | ✓ |
+
+### Component path field mapping
+
+| Canonical field | Claude Code | Cursor | Codex | Copilot CLI |
+| --- | --- | --- | --- | --- |
+| `skills` | ✓ | ✓ | ✓ | ✓ |
+| `mcpServers` | ✓ → `./.mcp.json` | adapt → `./mcp.json` (symlink) | ✓ → `./.mcp.json` | ✓ |
+| `commands` | ✓ | ✓ | **omit** | ✓ |
+| `agents` | ✓ | ✓ | **omit** | ✓ |
+| `rules` | **omit** | ✓ | **omit** | **omit** |
+| `hooks` | adapt → PascalCase, `${CLAUDE_PLUGIN_ROOT}` | adapt → camelCase, pass-through env | ✓ → PascalCase, `${PLUGIN_ROOT}` native | adapt → camelCase, pass-through env |
+| `lspServers` | ✓ | **omit** | **omit** | **omit** |
+| `outputStyles` | ✓ | **omit** | **omit** | **omit** |
+
+## Hook Event Name Mapping
+
+Canonical hooks file uses **PascalCase** event names. Build translates per vendor.
+
+| Canonical (PascalCase) | Claude Code | Cursor | Codex | Copilot CLI |
+| --- | --- | --- | --- | --- |
+| `PreToolUse` | `PreToolUse` | `preToolUse` | `PreToolUse` | `preToolUse` |
+| `PostToolUse` | `PostToolUse` | `postToolUse` | `PostToolUse` | `postToolUse` |
+| `PostToolUseFailure` | `PostToolUseFailure` | — (drop+warn) | — (drop+warn) | — (drop+warn) |
+| `SessionStart` | `SessionStart` | `sessionStart` | `SessionStart` | `sessionStart` |
+| `SessionEnd` | `SessionEnd` | `sessionEnd` | `SessionEnd` | `sessionEnd` |
+| `Stop` | `Stop` | — (drop+warn) | — (drop+warn) | `agentStop` |
+| `UserPromptSubmit` | `UserPromptSubmit` | `beforeSubmitPrompt` | — (drop+warn) | — (drop+warn) |
+| `Notification` | `Notification` | — (drop+warn) | — (drop+warn) | `notification` |
+| `PermissionRequest` | `PermissionRequest` | — (drop+warn) | — (drop+warn) | `permissionRequest` |
+| `SubagentStart` | — | `subagentStart` | — | — |
+| `SubagentStop` | — | `subagentStop` | — | — |
+| `PreCompact` | `PreCompact` | `preCompact` | — | — |
+
+Events not in this table: pass through for `claude-code`; drop + warn for all others.
+
+**Canonical hooks file** (`hooks/hooks.json` — PascalCase, `${PLUGIN_ROOT}`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "${PLUGIN_ROOT}/hooks/impl.sh", "timeout": 10 }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [{ "type": "command", "command": "${PLUGIN_ROOT}/hooks/impl.sh", "timeout": 10 }]
+      }
+    ]
+  }
+}
+```
+
+Build generates vendor-specific versions. Do not hand-author the generated hook files.
+
+## MCP: Symlink Rule
+
+`.mcp.json` is the source of truth. `mcp.json` is always a symlink — never a regular file.
+
+```bash
+ln -sf .mcp.json mcp.json
+```
+
+| Runtime | Reads |
+| --- | --- |
+| Claude Code, Codex | `.mcp.json` |
+| Cursor, open-plugin-spec | `mcp.json` (via symlink) |
+
+If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattributes`. MCP server startup failures are non-fatal.
+
+## Environment Variable Mapping
+
+| Canonical | Claude Code | Cursor | Codex | Copilot CLI |
+| --- | --- | --- | --- | --- |
+| `${PLUGIN_ROOT}` | `${CLAUDE_PLUGIN_ROOT}` | pass-through (undocumented) | `${PLUGIN_ROOT}` (native) | pass-through (undocumented) |
+| `${PLUGIN_DATA}` | `${CLAUDE_PLUGIN_DATA}` | pass-through (undocumented) | `${PLUGIN_DATA}` (native) | pass-through (undocumented) |
+
+`${PLUGIN_ROOT}` is ephemeral (changes on update). `${PLUGIN_DATA}` survives updates; use it for caches and generated artifacts. `${CLAUDE_PROJECT_DIR}` (Claude Code only) is the project root the agent launched from.
+
+## Component Authoring Rules
+
+**Skills:** Author `skills/<name>/SKILL.md` following the **skill-design** governance. Within a plugin, reference MCP tools by fully qualified name: `{plugin-name}:{server-name}__{tool-name}`.
+
+**Commands:** One `.md` file per command in `commands/`. Filename (minus extension) is the command identifier. Optional frontmatter: `description`, `argument-hint`, `allowed-tools`, `disable-model-invocation`. `$ARGUMENTS` expands to user input.
+
+**Agents:** One `.md` file per agent in `agents/`. Required frontmatter: `name` (1–64 lowercase alphanumeric + hyphens), `description` (≤ 1024 chars). Body is the agent system prompt.
+
+**Rules (Cursor-only):** `.mdc` files in `rules/`. Required frontmatter: `description`. Optional: `alwaysApply` (bool), `globs` (file-pattern array). Bundle `commands/setup.md` to merge rule content into project's `AGENTS.md` — after that merge, `.mdc` files are redundant.
+
+**Decision tree for always-on guidance:**
+- Situation-triggered → **skill** (all agents)
+- Always-on, cross-agent → merge into **AGENTS.md**
+- Always-on, Cursor-only → `rules/` + `commands/setup.md`
+
+## Namespacing
+
+| Component | Format |
+| --- | --- |
+| Skills | `{plugin-name}:{skill-name}` |
+| MCP tools | `mcp__plugin_{plugin-name}_{server-name}__{tool-name}` |
+| Commands / agents | `{plugin-name}:{component-name}` |
+
+## Distribution
+
+| Scope | Claude Code | Cursor | Codex |
+| --- | --- | --- | --- |
+| **Personal** | `~/.claude/plugins/local/<name>` symlink | `~/.cursor/plugins/local/<name>` symlink + reload | `~/.agents/plugins/marketplace.json` |
+| **Team** | npm private package | Cursor Teams admin import | `.agents/plugins/marketplace.json` in repo |
+| **Public** | PR to `anthropics/claude-plugins-official` | `cursor.com/marketplace/publish` | `codex plugin marketplace add` |
+
+Default scope: **team**.
+
+**npm distribution:** All manifest directories (`.plugin/`, `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`) and component directories (`skills/`, `commands/`, `agents/`, `hooks/`) must be in `package.json#files`. `package.json` carries distribution metadata only — no plugin semantics.
+
+## Anti-Patterns
+
+- Using `../` in any manifest-declared path
+- Hardcoding absolute paths instead of `${PLUGIN_ROOT}` or `${PLUGIN_DATA}`
+- Committing `mcp.json` as a regular file — must always be a symlink to `.mcp.json`
+- Hand-authoring vendor hook files — use canonical `hooks/hooks.json` and let build generate vendor versions
+- Relying on extended component types (commands, rules, agents, hooks) for core functionality — silently ignored on non-supporting hosts
+- Duplicating SKILL.md content in `plugin.json` — the manifest is a path index, never a content mirror
+- Using `rules/` for cross-agent always-on guidance — use AGENTS.md instead
+- Putting install-time metadata in `plugin.json` instead of `skill.json`
+
+## Cross-Platform Portability
+
+| Runtime | SKILL.md native | Plugin manifest |
+| --- | --- | --- |
+| Claude Code | Yes | `.claude-plugin/plugin.json` |
+| Codex | Yes | `.codex-plugin/plugin.json` (`version` + `description` required) |
+| Cursor | Yes (conversion) | `.cursor-plugin/plugin.json` |
+| Copilot CLI | Yes | `plugin.json` at repo root |
+| Gemini CLI, GitHub Copilot, Amp | Yes | Different manifest paths — require separate authoring |
+| Windsurf | Needs conversion | 6,000 char/file hard limit; 12,000 chars total |
+| Zed, Aider, Continue.dev, Cline | No | Incompatible formats |
+
+Portability rules for skill bodies: keep each `SKILL.md` body under 6,000 chars; use forward slashes in path references; declare environment requirements in `compatibility` frontmatter; do not embed vendor-specific syntax in skill bodies.
+
+## References
+
+```bash
+npx universal-plugin@<version> governance show skill-design
+npx universal-plugin@<version> governance show skill-repo-structure
+npx universal-plugin@<version> governance show agent-tool-output
+```
+
+Spec: https://github.com/cyberuni/universal-plugin/blob/main/spec/universal-plugin-system.md

package/package.json

@@ -1,60 +1,59 @@
 {
-	"name": "universal-plugin",
-	"version": "0.1.0",
-	"description": "Universal AI agent plugin build tool",
-	"keywords": [
-		"agent-plugin",
-		"claude-code",
-		"cursor",
-		"codex",
-		"copilot-cli"
-	],
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/cyberuni/cyber-universal-agent-plugin.git",
-		"directory": "packages/universal-plugin"
-	},
-	"license": "MIT",
-	"author": "unional <homawong@gmail.com>",
-	"type": "module",
-	"bin": {
-		"universal-plugin": "bin/universal-plugin.mjs"
-	},
-	"exports": {
-		"./package.json": "./package.json"
-	},
-	"files": [
-		"bin",
-		"dist"
-	],
-	"scripts": {
-		"build": "tsdown",
-		"dev": "tsx src/cli.ts",
-		"knip": "knip",
-		"lint": "biome check .",
-		"prepack": "pnpm build",
-		"test": "pnpm build && vitest run src",
-		"test:watch": "vitest",
-		"typecheck": "tsc --noEmit",
-		"verify": "pnpm typecheck && pnpm lint && pnpm test"
-	},
-	"dependencies": {
-		"commander": "^14.0.3"
-	},
-	"devDependencies": {
-		"@types/node": "^24.10.1",
-		"knip": "^6.14.1",
-		"tsdown": "^0.22.0",
-		"tsx": "^4.22.3",
-		"typescript": "^6.0.0",
-		"vitest": "^4.1.7"
-	},
-	"packageManager": "pnpm@11.0.0",
-	"engines": {
-		"node": ">=22"
-	},
-	"publishConfig": {
-		"access": "public",
-		"provenance": true
-	}
-}
+  "name": "universal-plugin",
+  "version": "0.2.1",
+  "description": "Universal AI agent plugin build tool",
+  "keywords": [
+    "agent-plugin",
+    "claude-code",
+    "cursor",
+    "codex",
+    "copilot-cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyberuni/cyberplace.git",
+    "directory": "packages/universal-plugin"
+  },
+  "license": "MIT",
+  "author": "unional <homawong@gmail.com>",
+  "type": "module",
+  "bin": {
+    "universal-plugin": "bin/universal-plugin.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "governances"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "knip": "^6.14.1",
+    "tsdown": "^0.22.0",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsx src/cli.ts",
+    "knip": "knip",
+    "lint": "biome check .",
+    "test": "pnpm build && vitest run src",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm typecheck && pnpm lint && pnpm test"
+  }
+}

package/readme.md

@@ -0,0 +1,70 @@
+# 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)
+
+Universal AI agent plugin build tool. Author one canonical plugin manifest (`.plugin/plugin.json`) and generate vendor-specific manifests for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
+
+## Usage
+
+No install required — run with `npx`:
+
+```sh
+npx universal-plugin <command>
+```
+
+Or pin to an exact version for reproducible builds:
+
+```sh
+npx universal-plugin@0.2.0 <command>
+```
+
+## Commands
+
+### plugin — author the canonical manifest
+
+```sh
+# Generate vendor manifests from .plugin/plugin.json
+npx universal-plugin plugin build
+```
+
+`validate` and `init` are specified but implementation is deferred.
+
+### sync — cross-vendor plugin sync
+
+```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 sync apply <action-id>
+```
+
+### publish
+
+```sh
+# Sync version from packagePath/package.json into .plugin/plugin.json
+npx universal-plugin publish sync-version
+```
+
+### governance
+
+Version-pinned agent-tool contracts, read at runtime.
+
+```sh
+npx universal-plugin governance list
+npx universal-plugin governance show plugin-design
+```
+
+### Housekeeping
+
+```sh
+npx universal-plugin clean                            # remove the asset store
+npx universal-plugin self-update <version>            # update the version pin in hook files
+```
+
+## License
+
+MIT