universal-plugin 0.2.0 → 0.2.2

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

@@ -8,8 +8,12 @@ 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");
+/** Resolves `--root` to an absolute path (cwd when omitted). Absolute is the contract: a relative
+*  root such as `.` breaks any ancestor walk downstream (`path.dirname('.') === '.'` terminates the
+*  walk on its first step), which would make the same operation behave differently depending on the
+*  cwd it was invoked from. */
 function resolveRoot(root) {
-	return root ?? process.cwd();
+	return root === void 0 ? process.cwd() : path.resolve(root);
 }
 //#endregion
 //#region src/state/state.ts
@@ -186,6 +190,15 @@ function output(data, readable) {
 	else readable();
 }
 //#endregion
+//#region src/json.ts
+/** Detects indentation style from JSON text. Returns `'\t'` for tabs or a number for space count.
+*  Falls back to `'\t'` when no indentation is detected. */
+function detectIndent(json) {
+	const match = json.match(/\n([ \t]+)/);
+	if (!match) return "	";
+	return match[1].startsWith("	") ? "	" : match[1].length;
+}
+//#endregion
 //#region src/build/build.ts
 const VENDOR_OUTPUT = {
 	"claude-code": ".claude-plugin/plugin.json",
@@ -207,14 +220,23 @@ 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(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")}`);
 	const warnings = [];
+	const rows = [];
 	const vendorExtensions = manifest.vendorExtensions ?? {};
 	let vendors = Object.keys(vendorExtensions).filter((v) => {
 		if (!KNOWN_VENDORS.has(v)) {
 			warnings.push(`Unknown vendor "${v}" in vendorExtensions — skipped`);
+			rows.push({
+				vendor: v,
+				path: "-",
+				status: "skipped"
+			});
 			return false;
 		}
 		return true;
@@ -228,13 +250,16 @@ function buildPlugin(root, opts = {}) {
 		return {
 			vendors: [],
 			written: [],
-			warnings
+			warnings,
+			rows,
+			summary: summarize(rows)
 		};
 	}
 	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 relPath = VENDOR_OUTPUT[vendor];
+		const outputPath = path.join(root, relPath);
 		const outputDir = path.dirname(outputPath);
 		const vendorFields = vendorExtensions[vendor] ?? {};
 		const vendorManifest = {
@@ -245,24 +270,48 @@ function buildPlugin(root, opts = {}) {
 			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`);
+		try {
+			if (!opts.dryRun) {
+				if (opts.clean && fsNode.existsSync(outputPath)) fsNode.unlinkSync(outputPath);
+				fsNode.mkdirSync(outputDir, { recursive: true });
+				fsNode.writeFileSync(outputPath, `${JSON.stringify(vendorManifest, null, indent)}\n`);
+			}
+			written.push(outputPath);
+			rows.push({
+				vendor,
+				path: relPath,
+				status: "built"
+			});
+		} catch (err) {
+			warnings.push(`Failed to write "${vendor}" → ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+			rows.push({
+				vendor,
+				path: relPath,
+				status: "failed"
+			});
 		}
-		written.push(outputPath);
 	}
 	return {
 		vendors,
 		written,
-		warnings
+		warnings,
+		rows,
+		summary: summarize(rows)
+	};
+}
+function summarize(rows) {
+	return {
+		built: rows.filter((r) => r.status === "built").length,
+		skipped: rows.filter((r) => r.status === "skipped").length,
+		failed: rows.filter((r) => r.status === "failed").length
 	};
 }
 //#endregion
 //#region src/build/cli.ts
+const NEXT_STEP$1 = "→ universal-plugin plugin validate\n";
 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 toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code\n").action((opts) => {
 		try {
 			const result = buildPlugin(resolveRoot(opts.root), {
 				vendor: opts.vendor,
@@ -271,14 +320,341 @@ function buildCommand() {
 				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
-				}]);
+			const { built, skipped, failed } = result.summary;
+			output({
+				built: result.rows.filter((r) => r.status === "built"),
+				skipped: result.rows.filter((r) => r.status === "skipped"),
+				failed: result.rows.filter((r) => r.status === "failed"),
+				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
+					}
+				]);
+				console.log(`built ${built}, skipped ${skipped}, failed ${failed}`);
 			});
+			process.stderr.write(NEXT_STEP$1);
+			if (failed > 0) process.exitCode = 1;
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+//#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;
+}
+//#endregion
+//#region src/bundle/bundle.ts
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Rewrites every `npx <pkg>@<anything>` occurrence in `content` to `npx <pkg>@<next>`, regardless
+*  of whether the occurrence is a concrete version or a placeholder like `<version>` — so every
+*  reference to one CLI converges 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}`);
+}
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+const PIN_EXEMPT_PATTERN = /(^|\n)\s*pin-exempt:\s*true\s*(\n|$)/;
+/** True when a SKILL.md's frontmatter declares `metadata.pin-exempt: true` — its version strings
+*  are documentation/illustration, never rewritten by `bundle`. Nesting under `metadata` is not
+*  enforced structurally (no YAML dependency); the key's presence anywhere in the frontmatter block
+*  is the marker. */
+function isPinExempt(skillMdContent) {
+	const match = skillMdContent.match(FRONTMATTER_PATTERN);
+	if (!match) return false;
+	return PIN_EXEMPT_PATTERN.test(match[1]);
+}
+function dirOf(filePath) {
+	const idx = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+	return idx === -1 ? "" : filePath.slice(0, idx);
+}
+function isUnderExemptDir(filePath, exemptDirs) {
+	for (const dir of exemptDirs) if (filePath.startsWith(`${dir}/`) || filePath.startsWith(`${dir}\\`)) return true;
+	return false;
+}
+/** Scans the plugin's skills for `npx <pkg>@<pin>` references and, for each in-scope package that
+*  resolves against the workspace, rewrites every occurrence to that package's local version. A
+*  pin-exempt skill (and every file under its directory) is excluded entirely — never scanned,
+*  never rewritten, never reported. */
+function bundlePins(pinFs, versionSource, opts = {}) {
+	const files = pinFs.listSkillFiles();
+	const contents = /* @__PURE__ */ new Map();
+	for (const file of files) contents.set(file, pinFs.readFile(file));
+	const exemptDirs = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		if (!file.endsWith("/SKILL.md") && !file.endsWith("\\SKILL.md")) continue;
+		if (isPinExempt(contents.get(file))) exemptDirs.add(dirOf(file));
+	}
+	const inScope = files.filter((file) => !isUnderExemptDir(file, exemptDirs));
+	const currentsByPkg = /* @__PURE__ */ new Map();
+	for (const file of inScope) for (const pin of extractPins(contents.get(file))) {
+		const list = currentsByPkg.get(pin.pkg) ?? [];
+		list.push(pin.current);
+		currentsByPkg.set(pin.pkg, list);
+	}
+	const warnings = [];
+	const pins = [];
+	for (const [pkg, currents] of currentsByPkg) {
+		const current = currents[0];
+		const lookup = versionSource.resolve(pkg);
+		if (!lookup.inWorkspace) {
+			pins.push({
+				package: pkg,
+				current,
+				resolved: current,
+				status: "skipped"
+			});
+			continue;
+		}
+		if (lookup.version === void 0) {
+			warnings.push(`workspace package "${pkg}" has no readable package.json version — skipped`);
+			pins.push({
+				package: pkg,
+				current,
+				resolved: current,
+				status: "skipped"
+			});
+			continue;
+		}
+		const target = lookup.version;
+		let changed = false;
+		for (const file of inScope) {
+			const content = contents.get(file);
+			const rewritten = rewritePin(content, pkg, target);
+			if (rewritten !== content) {
+				changed = true;
+				contents.set(file, rewritten);
+				if (!opts.dryRun) pinFs.writeFile(file, rewritten);
+			}
+		}
+		pins.push({
+			package: pkg,
+			current,
+			resolved: target,
+			status: changed ? "pinned" : "unchanged"
+		});
+	}
+	if (pins.length > 0 && pins.every((pin) => pin.status === "skipped")) warnings.push(`resolved 0 of ${pins.length} referenced package(s) against the workspace — no pins were rewritten`);
+	return {
+		pins,
+		warnings
+	};
+}
+//#endregion
+//#region src/bundle/fs.ts
+const DEFAULT_GLOBS = ["packages/*"];
+/** Walks up from `start` looking for `pnpm-workspace.yaml`; falls back to `start` itself when no
+*  ancestor declares one (the workspace glob then resolves relative to `start`). `start` is resolved
+*  to an absolute path first — a relative one (`.`) would end the walk on its first step, silently
+*  making workspace discovery depend on the cwd the command was invoked from. */
+function findMonorepoRoot(start) {
+	const from = path.resolve(start);
+	let dir = from;
+	for (;;) {
+		if (fsNode.existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return from;
+		dir = parent;
+	}
+}
+/** Minimal `packages:` list extraction from a `pnpm-workspace.yaml` — no YAML dependency, just the
+*  flat glob-list shape pnpm-workspace files use. */
+function parseWorkspaceGlobs(yamlText) {
+	const lines = yamlText.split(/\r?\n/);
+	const globs = [];
+	let inPackages = false;
+	for (const line of lines) {
+		if (/^packages:\s*$/.test(line)) {
+			inPackages = true;
+			continue;
+		}
+		if (!inPackages) continue;
+		const item = line.match(/^\s*-\s*["']?([^"'\s#]+)["']?\s*$/);
+		if (item) {
+			globs.push(item[1]);
+			continue;
+		}
+		if (/^\S/.test(line)) inPackages = false;
+	}
+	return globs;
+}
+function readWorkspaceGlobs(monorepoRoot) {
+	const yamlPath = path.join(monorepoRoot, "pnpm-workspace.yaml");
+	if (!fsNode.existsSync(yamlPath)) return DEFAULT_GLOBS;
+	try {
+		const globs = parseWorkspaceGlobs(fsNode.readFileSync(yamlPath, "utf8"));
+		return globs.length > 0 ? globs : DEFAULT_GLOBS;
+	} catch {
+		return DEFAULT_GLOBS;
+	}
+}
+/** Expands a workspace glob to its member directories. Only the `<dir>/*` shape pnpm-workspace
+*  files use is supported; a glob without a trailing `/*` is treated as a single literal path. */
+function expandGlob(monorepoRoot, glob) {
+	if (glob.endsWith("/*")) {
+		const base = path.join(monorepoRoot, glob.slice(0, -2));
+		if (!fsNode.existsSync(base)) return [];
+		return fsNode.readdirSync(base, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path.join(base, entry.name));
+	}
+	const dir = path.join(monorepoRoot, glob);
+	return fsNode.existsSync(dir) ? [dir] : [];
+}
+/** Discovers every workspace member's version, keyed by its `package.json` `name` field (falling
+*  back to the directory name when `package.json` is missing or unreadable — registering the
+*  package as an in-workspace member with an unresolved version, distinct from a package with no
+*  workspace entry at all). */
+function discoverWorkspace(root) {
+	const monorepoRoot = findMonorepoRoot(root);
+	const globs = readWorkspaceGlobs(monorepoRoot);
+	const map = /* @__PURE__ */ new Map();
+	for (const glob of globs) for (const dir of expandGlob(monorepoRoot, glob)) {
+		let name = path.basename(dir);
+		let version;
+		try {
+			const pkg = JSON.parse(fsNode.readFileSync(path.join(dir, "package.json"), "utf8"));
+			if (typeof pkg.name === "string") name = pkg.name;
+			if (typeof pkg.version === "string") version = pkg.version;
+		} catch {}
+		map.set(name, version);
+	}
+	return map;
+}
+/** Writes `<root>/.plugin/pins.json` — a flat, key-sorted `{ "<package>": "<resolvedVersion>" }`
+*  map of the workspace-resolved pins (`pinned` + `unchanged`), so a bundled plugin's skills can read
+*  the shipped version programmatically (e.g. `${CLAUDE_PLUGIN_ROOT}/.plugin/pins.json`). External /
+*  `skipped` packages are excluded — they have no authoritative workspace version. */
+function writePinsMap(root, pins) {
+	const map = {};
+	for (const pin of pins) if (pin.status === "pinned" || pin.status === "unchanged") map[pin.package] = pin.resolved;
+	const sorted = {};
+	for (const key of Object.keys(map).sort((a, b) => a.localeCompare(b))) sorted[key] = map[key];
+	const dir = path.join(root, ".plugin");
+	fsNode.mkdirSync(dir, { recursive: true });
+	const pinsPath = path.join(dir, "pins.json");
+	const existing = fsNode.existsSync(pinsPath) ? fsNode.readFileSync(pinsPath, "utf8") : null;
+	const indent = existing ? detectIndent(existing) : "	";
+	fsNode.writeFileSync(pinsPath, `${JSON.stringify(sorted, null, indent)}\n`);
+}
+function realVersionSource(workspace) {
+	return { resolve(pkg) {
+		if (!workspace.has(pkg)) return { inWorkspace: false };
+		return {
+			inWorkspace: true,
+			version: workspace.get(pkg)
+		};
+	} };
+}
+//#endregion
+//#region src/bundle/cli.ts
+const TRUNCATE_THRESHOLD = 20;
+const NEXT_STEP = "→ review and commit the pinned skills\n";
+/** Every referenced package skipped: nothing was rewritten, so the next step is to check the
+*  workspace resolution rather than to commit a bundle that does not exist. */
+const NOTHING_RESOLVED_STEP = "→ nothing was pinned — confirm --root is inside the workspace that owns these packages before releasing\n";
+function bundleCommand() {
+	const cmd = new Command("bundle").description("Pin the plugin's skill npx references to their workspace package.json versions (release form)");
+	cmd.option("--dry-run", "Resolve and report pins without writing them").option("--full", "Show every pins row without truncation").option("--format <format>", "Output format: json or toon (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin bundle --dry-run --full\n").action((opts) => {
+		try {
+			const root = resolveRoot(opts.root);
+			const result = bundlePins(realPinFs(resolveSkillsDir(root, readManifest(root).skills)), realVersionSource(discoverWorkspace(root)), { dryRun: opts.dryRun });
+			if (!opts.dryRun) writePinsMap(root, result.pins);
+			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
+			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}`);
+			});
+			if (result.pins.length === 0) process.stderr.write("nothing to bundle\n");
+			const noneResolved = result.pins.length > 0 && skipped === result.pins.length;
+			process.stderr.write(noneResolved ? NOTHING_RESOLVED_STEP : NEXT_STEP);
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
 			process.exit(1);
@@ -403,7 +779,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 +792,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, [{
@@ -673,18 +1049,21 @@ const realSyncVersionFs = {
 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 +1235,13 @@ 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, bundle; validate, init planned)");
+	cmd.addCommand(buildCommand());
+	cmd.addCommand(bundleCommand());
+	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.2",
   "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",
@@ -48,10 +48,11 @@
   },
   "scripts": {
     "build": "tsdown",
+    "check:spec": "sdd-check-specs",
     "dev": "tsx src/cli.ts",
     "knip": "knip",
     "lint": "biome check .",
-    "test": "pnpm build && vitest run src",
+    "test": "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