universal-plugin 0.1.0

package/bin/universal-plugin.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const dir = dirname(fileURLToPath(import.meta.url))
+await import(join(dir, '..', 'dist', 'cli.mjs'))

package/dist/cli.mjs

@@ -0,0 +1,814 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import * as fsNode from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as childProcess from "node:child_process";
+//#region src/cli-options.ts
+/** Repo root; resolves to cwd when omitted. */
+const ROOT_OPTION = new Option("--root <path>", "Plugin root directory");
+function resolveRoot(root) {
+	return root ?? process.cwd();
+}
+//#endregion
+//#region src/state/state.ts
+const KNOWN_ACTION_TYPES = new Set([
+	"install",
+	"upgrade",
+	"remove"
+]);
+function emptyState() {
+	return {
+		schemaVersion: 1,
+		snapshots: {},
+		dismissed: {},
+		pendingActions: [],
+		uniPluginUpdates: {},
+		plugins: {},
+		assets: {}
+	};
+}
+function mergeSafeState(raw) {
+	return {
+		...raw,
+		plugins: raw.plugins ?? {},
+		assets: raw.assets ?? {},
+		pendingActions: (raw.pendingActions ?? []).filter((a) => KNOWN_ACTION_TYPES.has(a.type))
+	};
+}
+function writePluginIndex(state, vendorId, pluginName, entry) {
+	return {
+		...state,
+		plugins: {
+			...state.plugins,
+			[vendorId]: {
+				...state.plugins[vendorId] ?? {},
+				[pluginName]: entry
+			}
+		}
+	};
+}
+function writeAssetIndex(state, pluginName, entry) {
+	return {
+		...state,
+		assets: {
+			...state.assets,
+			[pluginName]: entry
+		}
+	};
+}
+function takeSnapshot(state, vendorId, scope, plugins, takenAt) {
+	return {
+		...state,
+		snapshots: {
+			...state.snapshots,
+			[vendorId]: {
+				...state.snapshots[vendorId] ?? {},
+				[scope]: {
+					takenAt,
+					plugins
+				}
+			}
+		}
+	};
+}
+function isDismissed(state, vendorId, scope, plugin, version) {
+	const entry = state.dismissed[`${vendorId}/${scope}/${plugin}`];
+	if (!entry) return false;
+	if (entry.reason === "keep") return true;
+	return entry.version === version;
+}
+function addPendingAction(state, action) {
+	const key = `${action.type}|${action.plugin}|${action.toVendor}|${action.scope}`;
+	if (state.pendingActions.some((a) => `${a.type}|${a.plugin}|${a.toVendor}|${a.scope}` === key)) return state;
+	return {
+		...state,
+		pendingActions: [...state.pendingActions, action]
+	};
+}
+//#endregion
+//#region src/asset-store/asset-store.ts
+const ASSET_DIRS = [
+	"governances",
+	"disciplines",
+	"guidelines",
+	"templates"
+];
+function globalStorePath() {
+	return path.join(os.homedir(), ".agents", ".universal-plugin", "plugins");
+}
+function projectStorePath(root) {
+	return path.join(root, ".agents", ".universal-plugin", "plugins");
+}
+function storeEntryPath(storePath, segment) {
+	return path.join(storePath, segment);
+}
+//#endregion
+//#region src/asset-store/fs.ts
+function entryExists(entryPath) {
+	return fsNode.existsSync(entryPath);
+}
+function populateEntry(entryPath, pluginRoot) {
+	for (const dir of ASSET_DIRS) {
+		const src = path.join(pluginRoot, dir);
+		const dest = path.join(entryPath, dir);
+		if (!fsNode.existsSync(src)) continue;
+		fsNode.mkdirSync(dest, { recursive: true });
+		for (const file of fsNode.readdirSync(src)) fsNode.copyFileSync(path.join(src, file), path.join(dest, file));
+	}
+}
+function removeStore(storePath) {
+	fsNode.rmSync(storePath, {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
+//#region src/asset-store/cli.ts
+function globalStatePath$3() {
+	return path.join(os.homedir(), ".agents", "universal-plugin.json");
+}
+function clearStateIndex(statePath) {
+	try {
+		const cleared = {
+			...mergeSafeState(JSON.parse(fsNode.readFileSync(statePath, "utf8"))),
+			plugins: {},
+			assets: {}
+		};
+		fsNode.writeFileSync(statePath, JSON.stringify(cleared, null, 2) + "\n", "utf8");
+	} catch (err) {
+		if (err.code !== "ENOENT") throw err;
+	}
+}
+function cleanCommand() {
+	return new Command("clean").description("Remove the asset store").addOption(new Option("--state", "Also clear plugins and assets from state JSON")).addOption(new Option("--scope <scope>", "global or project").choices(["global", "project"]).default("global")).option("--root <path>", "Project root (for --scope project)").action((opts) => {
+		const storePath = opts.scope === "project" ? projectStorePath(resolveRoot(opts.root)) : globalStorePath();
+		removeStore(storePath);
+		process.stdout.write(`Removed ${storePath}\n`);
+		if (opts.state) {
+			clearStateIndex(globalStatePath$3());
+			process.stdout.write("Cleared plugins and assets from state JSON\n");
+		}
+	});
+}
+//#endregion
+//#region src/output.ts
+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");
+	if (fmtIdx !== -1) return argv[fmtIdx + 1];
+	if (argv.includes("--json")) return "json";
+}
+function isJsonOutput() {
+	return getFormat() === "json";
+}
+function output(data, readable) {
+	if (isJsonOutput()) printJson(data);
+	else readable();
+}
+//#endregion
+//#region src/build/build.ts
+const VENDOR_OUTPUT = {
+	"claude-code": ".claude-plugin/plugin.json",
+	cursor: ".cursor-plugin/plugin.json",
+	codex: ".codex-plugin/plugin.json",
+	"copilot-cli": "plugin.json"
+};
+const KNOWN_VENDORS = new Set(Object.keys(VENDOR_OUTPUT));
+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}`);
+	return JSON.parse(fsNode.readFileSync(manifestPath, "utf8"));
+}
+function validateManifest(manifest) {
+	const errors = [];
+	if (!manifest.name) errors.push("name is required");
+	if (manifest.vendorExtensions?.codex && !manifest.description) errors.push("description is required when targeting codex");
+	if (manifest.vendorExtensions?.codex && !manifest.version) errors.push("version is required when targeting codex");
+	return errors;
+}
+function buildPlugin(root, opts = {}) {
+	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")}`);
+	const warnings = [];
+	const vendorExtensions = manifest.vendorExtensions ?? {};
+	let vendors = Object.keys(vendorExtensions).filter((v) => {
+		if (!KNOWN_VENDORS.has(v)) {
+			warnings.push(`Unknown vendor "${v}" in vendorExtensions — skipped`);
+			return false;
+		}
+		return true;
+	});
+	if (opts.vendor) {
+		if (!vendors.includes(opts.vendor)) throw new Error(`Vendor "${opts.vendor}" not declared in vendorExtensions`);
+		vendors = [opts.vendor];
+	}
+	if (vendors.length === 0) {
+		warnings.push("No vendors declared in vendorExtensions — nothing to build");
+		return {
+			vendors: [],
+			written: [],
+			warnings
+		};
+	}
+	const written = [];
+	const { vendorExtensions: _ext, $schema: _schema, ...canonical } = manifest;
+	for (const vendor of vendors) {
+		const outputPath = path.join(root, VENDOR_OUTPUT[vendor]);
+		const outputDir = path.dirname(outputPath);
+		const vendorFields = vendorExtensions[vendor] ?? {};
+		const vendorManifest = {
+			...canonical,
+			...vendorFields
+		};
+		if (opts.verbose) {
+			console.log(`[${vendor}] → ${outputPath}`);
+			for (const key of Object.keys(vendorFields)) console.log(`  + ${key} (from vendorExtensions)`);
+		}
+		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`);
+		}
+		written.push(outputPath);
+	}
+	return {
+		vendors,
+		written,
+		warnings
+	};
+}
+//#endregion
+//#region src/build/cli.ts
+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) => {
+		try {
+			const result = buildPlugin(resolveRoot(opts.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
+				}]);
+			});
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+//#endregion
+//#region src/governance/fs.ts
+const realGovernanceFs = {
+	exists: (p) => fsNode.existsSync(p),
+	read: (p) => fsNode.readFileSync(p, "utf8"),
+	list: (dir) => {
+		if (!fsNode.existsSync(dir)) return [];
+		return fsNode.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
+	}
+};
+//#endregion
+//#region src/governance/governance.ts
+function getManagedDir() {
+	if (process.platform === "darwin") return "/Library/Application Support/UniPlugin/governances";
+	if (process.platform === "win32") return path.join(process.env["ProgramData"] ?? "C:\\ProgramData", "UniPlugin", "governances");
+	return "/etc/universal-plugin/governances";
+}
+function getUserDir() {
+	return path.join(os.homedir(), ".agents", "governances");
+}
+function getProjectDir(root) {
+	return path.join(root, "governances");
+}
+function getPackageDir() {
+	const thisFile = fileURLToPath(import.meta.url);
+	return path.join(path.dirname(thisFile), "..", "governances");
+}
+function getScopedPaths(root) {
+	return [
+		{
+			scope: "managed",
+			dir: getManagedDir()
+		},
+		{
+			scope: "project",
+			dir: getProjectDir(root)
+		},
+		{
+			scope: "user",
+			dir: getUserDir()
+		},
+		{
+			scope: "package",
+			dir: getPackageDir()
+		}
+	];
+}
+function showGovernance(name, root, govFs, storeOpts) {
+	const slashIdx = name.indexOf("/");
+	if (slashIdx !== -1 && storeOpts) {
+		const pluginName = name.slice(0, slashIdx);
+		const assetName = name.slice(slashIdx + 1);
+		for (const scope of [
+			"managed",
+			"project",
+			"user"
+		]) {
+			let dir;
+			if (scope === "managed") dir = getManagedDir();
+			else if (scope === "project") dir = getProjectDir(root);
+			else dir = getUserDir();
+			const filePath = path.join(dir, pluginName, `${assetName}.md`);
+			if (govFs.exists(filePath)) return {
+				content: govFs.read(filePath),
+				scope
+			};
+		}
+		const entry = storeOpts.state.assets[pluginName];
+		if (!entry) return null;
+		const segment = path.join(entry.source, `${pluginName}@${entry.version}`);
+		const storePath = path.join(storeOpts.globalStorePath, segment, "governances", `${assetName}.md`);
+		if (govFs.exists(storePath)) return {
+			content: govFs.read(storePath),
+			scope: "store"
+		};
+		return null;
+	}
+	for (const { scope, dir } of getScopedPaths(root)) {
+		const filePath = path.join(dir, `${name}.md`);
+		if (govFs.exists(filePath)) return {
+			content: govFs.read(filePath),
+			scope
+		};
+	}
+	return null;
+}
+function listGovernances(root, govFs) {
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const { scope, dir } of getScopedPaths(root)) for (const name of govFs.list(dir)) if (!seen.has(name)) {
+		seen.add(name);
+		entries.push({
+			name,
+			scope
+		});
+	}
+	return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+//#endregion
+//#region src/governance/cli.ts
+function readGlobalState() {
+	const p = path.join(os.homedir(), ".agents", "universal-plugin.json");
+	try {
+		return mergeSafeState(JSON.parse(fsNode.readFileSync(p, "utf8")));
+	} catch {
+		return emptyState();
+	}
+}
+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 result = showGovernance(name, resolveRoot(opts.root), realGovernanceFs, {
+			state: readGlobalState(),
+			globalStorePath: globalStorePath()
+		});
+		if (!result) {
+			process.stderr.write(`Governance "${name}" not found\n`);
+			process.exit(1);
+		}
+		output(result, () => {
+			process.stdout.write(result.content);
+		});
+	});
+	cmd.command("list").description("List available governances").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
+			}]);
+		});
+	});
+	return cmd;
+}
+//#endregion
+//#region src/vendor-registry/vendor-registry.ts
+function lookupVendor(registry, vendorId) {
+	return registry[vendorId] ?? null;
+}
+function mergeRegistries(base, override) {
+	const result = { ...base };
+	for (const [id, config] of Object.entries(override)) result[id] = {
+		...base[id] ?? {},
+		...config
+	};
+	return result;
+}
+//#endregion
+//#region src/vendor-registry/fs.ts
+function bundledRegistryPath() {
+	const thisFile = fileURLToPath(import.meta.url);
+	return path.join(path.dirname(thisFile), "data", "vendors.json");
+}
+function userOverridePath() {
+	return path.join(os.homedir(), ".agents", "universal-plugin-vendors.json");
+}
+function loadRegistry() {
+	const bundled = JSON.parse(fsNode.readFileSync(bundledRegistryPath(), "utf8"));
+	try {
+		return mergeRegistries(bundled, JSON.parse(fsNode.readFileSync(userOverridePath(), "utf8")));
+	} catch (err) {
+		if (err.code === "ENOENT") return bundled;
+		throw err;
+	}
+}
+//#endregion
+//#region src/prepare/fs.ts
+function expandHome(p) {
+	return p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p;
+}
+function globalStatePath$2() {
+	return path.join(os.homedir(), ".agents", "universal-plugin.json");
+}
+function projectStatePath(root) {
+	return path.join(root, ".agents", "universal-plugin.json");
+}
+function readStateFile(filePath) {
+	try {
+		return mergeSafeState(JSON.parse(fsNode.readFileSync(filePath, "utf8")));
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+function writeStateFile(filePath, state) {
+	fsNode.mkdirSync(path.dirname(filePath), { recursive: true });
+	fsNode.writeFileSync(filePath, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+function realPrepareFs(vendor, projectRoot) {
+	return {
+		readManifest() {
+			if (!vendor.globalManifest) return {};
+			const manifestPath = expandHome(vendor.globalManifest);
+			try {
+				const raw = JSON.parse(fsNode.readFileSync(manifestPath, "utf8"));
+				return Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, typeof v === "object" && v !== null && "version" in v ? String(v.version) : String(v)]));
+			} catch (err) {
+				if (err.code === "ENOENT") return {};
+				throw err;
+			}
+		},
+		readPluginRoots() {
+			if (!vendor.globalPluginDir) return {};
+			const pluginDir = expandHome(vendor.globalPluginDir);
+			const manifest = this.readManifest();
+			const home = os.homedir();
+			return Object.fromEntries(Object.keys(manifest).map((name) => {
+				const absPath = path.join(pluginDir, name);
+				return [name, absPath.startsWith(home) ? "~" + absPath.slice(home.length) : absPath];
+			}));
+		},
+		readGlobalState: () => readStateFile(globalStatePath$2()) ?? emptyState(),
+		readProjectState: () => projectRoot ? readStateFile(projectStatePath(projectRoot)) : null,
+		writeGlobalState: (s) => writeStateFile(globalStatePath$2(), s),
+		writeProjectState: (s) => {
+			if (projectRoot) writeStateFile(projectStatePath(projectRoot), s);
+		}
+	};
+}
+function populateStoreFromVendorCache(pluginRoots, versions) {
+	const storePath = globalStorePath();
+	for (const [pluginName, pluginRoot] of Object.entries(pluginRoots)) {
+		const entryPath = storeEntryPath(storePath, `npm/${pluginName}@${versions[pluginName] ?? "unknown"}`);
+		if (entryExists(entryPath)) continue;
+		populateEntry(entryPath, pluginRoot);
+	}
+}
+//#endregion
+//#region src/prepare/delta.ts
+function computeDelta(input) {
+	const { vendorId, scope, currentPlugins, state, now } = input;
+	const previous = state.snapshots[vendorId]?.[scope];
+	if (!previous) return [];
+	const previousPlugins = previous.plugins;
+	const added = Object.keys(currentPlugins).filter((p) => !(p in previousPlugins));
+	const removed = Object.keys(previousPlugins).filter((p) => !(p in currentPlugins));
+	const otherVendors = Object.entries(state.snapshots).filter(([id]) => id !== vendorId);
+	const actions = [];
+	let counter = 0;
+	const makeId = () => `delta-${now}-${++counter}`;
+	for (const plugin of added) {
+		const version = currentPlugins[plugin];
+		for (const [otherId, otherScopes] of otherVendors) {
+			const otherScope = otherScopes[scope];
+			if (!otherScope) continue;
+			if (plugin in otherScope.plugins) continue;
+			if (isDismissed(state, otherId, scope, plugin, version)) continue;
+			actions.push({
+				id: makeId(),
+				type: "install",
+				plugin,
+				version,
+				fromVendor: vendorId,
+				toVendor: otherId,
+				scope,
+				detectedAt: now
+			});
+		}
+	}
+	for (const plugin of removed) for (const [otherId, otherScopes] of otherVendors) {
+		const otherScope = otherScopes[scope];
+		if (!otherScope) continue;
+		if (!(plugin in otherScope.plugins)) continue;
+		const otherVersion = otherScope.plugins[plugin];
+		if (isDismissed(state, otherId, scope, plugin, otherVersion)) continue;
+		actions.push({
+			id: makeId(),
+			type: "remove",
+			plugin,
+			version: otherVersion,
+			fromVendor: vendorId,
+			toVendor: otherId,
+			scope,
+			detectedAt: now
+		});
+	}
+	for (const [otherId, otherScopes] of otherVendors) {
+		const otherScope = otherScopes[scope];
+		if (!otherScope) continue;
+		for (const [plugin, version] of Object.entries(currentPlugins)) {
+			const otherVersion = otherScope.plugins[plugin];
+			if (!otherVersion || otherVersion === version) continue;
+			if (!isNewerSemver(version, otherVersion)) continue;
+			if (isDismissed(state, otherId, scope, plugin, version)) continue;
+			actions.push({
+				id: makeId(),
+				type: "upgrade",
+				plugin,
+				version,
+				fromVendor: vendorId,
+				toVendor: otherId,
+				scope,
+				detectedAt: now
+			});
+		}
+	}
+	return actions;
+}
+function isNewerSemver(a, b) {
+	const [aMajor = 0, aMinor = 0, aPatch = 0] = a.split(".").map(Number);
+	const [bMajor = 0, bMinor = 0, bPatch = 0] = b.split(".").map(Number);
+	if (aMajor !== bMajor) return aMajor > bMajor;
+	if (aMinor !== bMinor) return aMinor > bMinor;
+	return aPatch > bPatch;
+}
+//#endregion
+//#region src/prepare/prepare.ts
+function runPrepare(opts) {
+	const { vendorId, scope, fs: prepareFs, now, dryRun } = opts;
+	const currentPlugins = prepareFs.readManifest();
+	const state = scope === "global" ? prepareFs.readGlobalState() : prepareFs.readProjectState() ?? emptyState();
+	const actions = computeDelta({
+		vendorId,
+		scope,
+		currentPlugins,
+		state,
+		now
+	});
+	let updatedState = takeSnapshot(state, vendorId, scope, currentPlugins, now);
+	for (const action of actions) updatedState = addPendingAction(updatedState, action);
+	const pluginRoots = prepareFs.readPluginRoots();
+	for (const [pluginName, pluginPath] of Object.entries(pluginRoots)) {
+		const version = currentPlugins[pluginName] ?? "unknown";
+		updatedState = writePluginIndex(updatedState, vendorId, pluginName, {
+			source: "npm",
+			path: pluginPath,
+			version
+		});
+		updatedState = writeAssetIndex(updatedState, pluginName, {
+			source: "npm",
+			version
+		});
+	}
+	if (!dryRun) if (scope === "global") prepareFs.writeGlobalState(updatedState);
+	else prepareFs.writeProjectState(updatedState);
+	return { newActionCount: actions.length };
+}
+//#endregion
+//#region src/prepare/cli.ts
+function prepareCommand() {
+	return new Command("prepare").description("Detect cross-vendor plugin sync actions").argument("<vendor-id>", "Vendor to read manifest from (e.g. claude-code)").addOption(new Option("--scope <scope>", "global or project").default("global").choices(["global", "project"])).option("--root <path>", "Project root for project-scope state file").option("--dry-run", "Print action count without writing state").action((vendorId, opts) => {
+		const vendor = lookupVendor(loadRegistry(), vendorId);
+		if (!vendor) {
+			process.stderr.write(`Unknown vendor: ${vendorId}\n`);
+			process.exit(1);
+		}
+		if (opts.scope === "project" && !opts.root) {
+			process.stderr.write("--root is required when --scope is project\n");
+			process.exit(1);
+		}
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const prepareFs = realPrepareFs(vendor, opts.root);
+		const pluginRoots = prepareFs.readPluginRoots();
+		const manifest = prepareFs.readManifest();
+		const { newActionCount } = runPrepare({
+			vendorId,
+			scope: opts.scope,
+			fs: prepareFs,
+			now,
+			dryRun: opts.dryRun
+		});
+		populateStoreFromVendorCache(pluginRoots, manifest);
+		if (newActionCount > 0) process.stdout.write(`${newActionCount} plugin sync action(s) pending. Run /sync to review.\n`);
+	});
+}
+//#endregion
+//#region src/self-update/fs.ts
+function globalStatePath$1() {
+	return path.join(os.homedir(), ".agents", "universal-plugin.json");
+}
+function realSelfUpdateFs(hookFilePaths) {
+	return {
+		globHookFiles: () => hookFilePaths,
+		readFile: (p) => fsNode.readFileSync(p, "utf8"),
+		writeFile: (p, c) => fsNode.writeFileSync(p, c, "utf8"),
+		readGlobalState: () => {
+			try {
+				return mergeSafeState(JSON.parse(fsNode.readFileSync(globalStatePath$1(), "utf8")));
+			} catch (err) {
+				if (err.code === "ENOENT") return emptyState();
+				throw err;
+			}
+		},
+		writeGlobalState: (s) => {
+			fsNode.mkdirSync(path.dirname(globalStatePath$1()), { recursive: true });
+			fsNode.writeFileSync(globalStatePath$1(), JSON.stringify(s, null, 2) + "\n");
+		}
+	};
+}
+//#endregion
+//#region src/self-update/self-update.ts
+function runSelfUpdate(opts) {
+	const { toVersion, fs } = opts;
+	const [major] = toVersion.split(".");
+	if (!major || !/^\d+$/.test(major)) throw new Error(`Invalid version format: ${toVersion}`);
+	const pattern = new RegExp(`(npx universal-plugin@)${major}\\.[0-9]+\\.[0-9]+`, "g");
+	let updatedCount = 0;
+	for (const filePath of fs.globHookFiles()) {
+		const content = fs.readFile(filePath);
+		pattern.lastIndex = 0;
+		if (!pattern.test(content)) continue;
+		pattern.lastIndex = 0;
+		const updated = content.replace(pattern, `$1${toVersion}`);
+		if (updated !== content) {
+			fs.writeFile(filePath, updated);
+			updatedCount++;
+		}
+	}
+	const state = fs.readGlobalState();
+	const updates = { ...state.uniPluginUpdates };
+	delete updates[major];
+	fs.writeGlobalState({
+		...state,
+		uniPluginUpdates: updates
+	});
+	return { updatedCount };
+}
+//#endregion
+//#region src/self-update/cli.ts
+function selfUpdateCommand() {
+	return new Command("self-update").description("Update universal-plugin version pin in universal-plugin hook files").argument("<version>", "Target version (e.g. 1.5.0)").action((toVersion) => {
+		const registry = loadRegistry();
+		const { updatedCount } = runSelfUpdate({
+			toVersion,
+			fs: realSelfUpdateFs(Object.values(registry).map((v) => v.hookGlob).filter((g) => g !== null).map((g) => g.replace("~", os.homedir())).filter((p) => {
+				try {
+					fsNode.accessSync(p);
+					return true;
+				} catch {
+					return false;
+				}
+			}))
+		});
+		process.stdout.write(`Updated ${updatedCount} hook file(s).\n`);
+	});
+}
+//#endregion
+//#region src/sync/sync.ts
+function applySyncAction(opts) {
+	const { actionId, registry, fs } = opts;
+	const state = fs.readGlobalState();
+	const action = state.pendingActions.find((a) => a.id === actionId);
+	if (!action) return { outcome: "not-found" };
+	const vendor = registry[action.toVendor];
+	const templateCommand = action.type === "install" ? vendor?.installCommand : action.type === "remove" ? vendor?.removeCommand : vendor?.updateCommand;
+	const withoutAction = {
+		...state,
+		pendingActions: state.pendingActions.filter((a) => a.id !== actionId)
+	};
+	if (!templateCommand) {
+		fs.writeGlobalState(withoutAction);
+		return {
+			outcome: "manual",
+			instruction: `Install ${action.plugin}@${action.version} in ${action.toVendor} via its marketplace, then run: sync apply ${action.id}`
+		};
+	}
+	const command = templateCommand.replace("{name}", action.plugin).replace("{version}", action.version);
+	if (fs.shell(command) !== 0) return { outcome: "failed" };
+	fs.writeGlobalState(withoutAction);
+	return { outcome: "applied" };
+}
+//#endregion
+//#region src/sync/cli.ts
+function globalStatePath() {
+	return path.join(os.homedir(), ".agents", "universal-plugin.json");
+}
+function realSyncFs() {
+	return {
+		readGlobalState: () => {
+			try {
+				return mergeSafeState(JSON.parse(fsNode.readFileSync(globalStatePath(), "utf8")));
+			} catch (err) {
+				if (err.code === "ENOENT") return emptyState();
+				throw err;
+			}
+		},
+		writeGlobalState: (s) => {
+			fsNode.mkdirSync(path.dirname(globalStatePath()), { recursive: true });
+			fsNode.writeFileSync(globalStatePath(), JSON.stringify(s, null, 2) + "\n");
+		},
+		shell: (cmd) => childProcess.spawnSync(cmd, {
+			shell: true,
+			stdio: "inherit"
+		}).status ?? 1
+	};
+}
+function syncCommand() {
+	const cmd = new Command("sync").description("Manage cross-vendor plugin sync").addHelpCommand(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,
+			registry: loadRegistry(),
+			fs: realSyncFs(),
+			now: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (result.outcome === "applied") process.stdout.write("Applied.\n");
+		else if (result.outcome === "manual") process.stdout.write(`${result.instruction}\n`);
+		else if (result.outcome === "not-found") {
+			process.stderr.write(`Action "${actionId}" not found in state file.\n`);
+			process.exit(1);
+		} else {
+			process.stderr.write("Apply failed. Try again or install manually.\n");
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+//#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.addCommand(cleanCommand());
+program.addCommand(governanceCommand());
+program.addCommand(prepareCommand());
+program.addCommand(syncCommand());
+program.addCommand(selfUpdateCommand());
+program.parseAsync(process.argv).catch((err) => {
+	process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/data/vendors.json

@@ -0,0 +1,46 @@
+{
+	"claude-code": {
+		"sessionStartEvent": "SessionStart",
+		"globalManifest": "~/.claude/plugins/installed_plugins.json",
+		"projectManifest": null,
+		"hookGlob": "~/.claude/plugins/universal-plugin/hooks/hooks.json",
+		"globalPluginDir": "~/.claude/plugins/",
+		"pluginRootSuffix": ".claude-plugin/plugin.json",
+		"installCommand": "claude plugin install {name}",
+		"removeCommand": "claude plugin remove {name}",
+		"updateCommand": "claude plugin update {name}@{version}"
+	},
+	"cursor": {
+		"sessionStartEvent": "sessionStart",
+		"globalManifest": null,
+		"projectManifest": null,
+		"hookGlob": null,
+		"globalPluginDir": null,
+		"pluginRootSuffix": ".cursor-plugin/plugin.json",
+		"installCommand": null,
+		"removeCommand": null,
+		"updateCommand": null
+	},
+	"codex": {
+		"sessionStartEvent": "SessionStart",
+		"globalManifest": null,
+		"projectManifest": null,
+		"hookGlob": null,
+		"globalPluginDir": null,
+		"pluginRootSuffix": ".codex-plugin/plugin.json",
+		"installCommand": null,
+		"removeCommand": null,
+		"updateCommand": null
+	},
+	"copilot-cli": {
+		"sessionStartEvent": "sessionStart",
+		"globalManifest": null,
+		"projectManifest": null,
+		"hookGlob": null,
+		"globalPluginDir": null,
+		"pluginRootSuffix": "plugin.json",
+		"installCommand": null,
+		"removeCommand": null,
+		"updateCommand": null
+	}
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"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
+	}
+}