universal-plugin 0.2.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")}`);
@@ -232,7 +374,7 @@ function buildPlugin(root, opts = {}) {
 		};
 	}
 	const written = [];
-	const { vendorExtensions: _ext, $schema: _schema, packagePath: _pkg, ...canonical } = manifest;
+	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);
@@ -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`);
@@ -403,7 +631,7 @@ function readGlobalState() {
 }
 function governanceCommand() {
 	const cmd = new Command("governance").description("Manage plugin governances").helpCommand(false);
-	cmd.command("show <name>").description("Show a governance by name").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((name, opts) => {
+	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()
@@ -416,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, [{
@@ -670,21 +898,29 @@ const realSyncVersionFs = {
 };
 //#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 manifest = JSON.parse(syncFs.read(manifestPath));
-	const packagePath = manifest["packagePath"];
-	if (!packagePath || typeof packagePath !== "string") throw new Error("packagePath is required in .plugin/plugin.json");
+	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, "	")}\n`);
+	syncFs.write(manifestPath, `${JSON.stringify(updated, null, indent)}\n`);
 	return {
 		version,
 		manifestPath
@@ -856,7 +1092,12 @@ function syncCommand() {
 //#region src/cli.ts
 const program = new Command();
 program.name("universal-plugin").description("Universal AI agent plugin build tool").version("0.0.0").helpCommand(false);
-program.addCommand(buildCommand());
+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());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -11,7 +11,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cyberuni/universal-plugin.git",
+    "url": "git+https://github.com/cyberuni/cyberplace.git",
     "directory": "packages/universal-plugin"
   },
   "license": "MIT",

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