universal-plugin 0.2.2 → 0.3.0

package/dist/cli.mjs

@@ -5,15 +5,12 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as childProcess from "node:child_process";
+import * as semver from "semver";
 //#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 === void 0 ? process.cwd() : path.resolve(root);
+	return root ?? process.cwd();
 }
 //#endregion
 //#region src/state/state.ts
@@ -200,6 +197,8 @@ function detectIndent(json) {
 }
 //#endregion
 //#region src/build/build.ts
+/** Where each vendor reads its manifest, relative to the project root. Shared with
+*  `plugin init --npm`, which wires exactly these paths into `package.json` `files`. */
 const VENDOR_OUTPUT = {
 	"claude-code": ".claude-plugin/plugin.json",
 	cursor: ".cursor-plugin/plugin.json",
@@ -207,31 +206,44 @@ const VENDOR_OUTPUT = {
 	"copilot-cli": "plugin.json"
 };
 const KNOWN_VENDORS = new Set(Object.keys(VENDOR_OUTPUT));
+/** Vendors the canonical root manifest serves as-is. The build derives no file for these — writing
+*  one would either be shadowed by root (a lower-precedence path) or clobber root itself. */
+const CANONICAL_SERVED = new Set(["copilot-cli"]);
+const UP_NAMESPACE$1 = "org.cyberuni.universal-plugin";
+/** Reads universal-plugin's config block from the canonical manifest's extensions map. */
+function universalPluginExtension(manifest) {
+	return manifest.extensions?.[UP_NAMESPACE$1] ?? {};
+}
 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}`);
+	const manifestPath = path.join(root, "plugin.json");
+	if (!fsNode.existsSync(manifestPath)) throw new Error(`No plugin.json found at ${root}`);
 	return JSON.parse(fsNode.readFileSync(manifestPath, "utf8"));
 }
-function validateManifest(manifest) {
+/** Validates the manifest. Vendor rules apply only to the vendors actually being built: pass
+*  `targets` to scope the check (build passes its selected targets), else it defaults to the
+*  manifest's own selection (`vendors ?? harnesses` keys). */
+function validateManifest(manifest, targets) {
 	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");
+	const uext = universalPluginExtension(manifest);
+	const harnesses = uext.harnesses ?? {};
+	const codexTargeted = (targets ?? uext.vendors ?? Object.keys(harnesses)).includes("codex") && Boolean(harnesses["codex"]);
+	if (codexTargeted && !manifest.description) errors.push("description is required when targeting codex");
+	if (codexTargeted && !manifest.version) errors.push("version is required when targeting codex");
 	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 manifestPath = path.join(root, "plugin.json");
+	if (!fsNode.existsSync(manifestPath)) throw new Error(`No 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) => {
+	const uext = universalPluginExtension(manifest);
+	const harnesses = uext.harnesses ?? {};
+	let vendors = (uext.vendors ?? Object.keys(harnesses)).filter((v) => {
 		if (!KNOWN_VENDORS.has(v)) {
-			warnings.push(`Unknown vendor "${v}" in vendorExtensions — skipped`);
+			warnings.push(`Unknown vendor "${v}" in harnesses — skipped`);
 			rows.push({
 				vendor: v,
 				path: "-",
@@ -242,11 +254,11 @@ function buildPlugin(root, opts = {}) {
 		return true;
 	});
 	if (opts.vendor) {
-		if (!vendors.includes(opts.vendor)) throw new Error(`Vendor "${opts.vendor}" not declared in vendorExtensions`);
+		if (!vendors.includes(opts.vendor)) throw new Error(`Vendor "${opts.vendor}" not declared in harnesses`);
 		vendors = [opts.vendor];
 	}
 	if (vendors.length === 0) {
-		warnings.push("No vendors declared in vendorExtensions — nothing to build");
+		warnings.push("No vendors declared in harnesses — nothing to build");
 		return {
 			vendors: [],
 			written: [],
@@ -255,20 +267,36 @@ function buildPlugin(root, opts = {}) {
 			summary: summarize(rows)
 		};
 	}
+	const errors = validateManifest(manifest, vendors);
+	if (errors.length > 0) throw new Error(`plugin.json validation failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
 	const written = [];
-	const { vendorExtensions: _ext, $schema: _schema, ...canonical } = manifest;
+	const { $schema: _schema, extensions: _extensions, ...metadata } = manifest;
+	const { vendors: _vendors, packagePath: _packagePath, harnesses: _harnesses, ...componentConfig } = uext;
+	const skills = readSkills(root, manifest);
 	for (const vendor of vendors) {
 		const relPath = VENDOR_OUTPUT[vendor];
 		const outputPath = path.join(root, relPath);
 		const outputDir = path.dirname(outputPath);
-		const vendorFields = vendorExtensions[vendor] ?? {};
+		const vendorFields = harnesses[vendor] ?? {};
 		const vendorManifest = {
-			...canonical,
+			...metadata,
+			...componentConfig,
 			...vendorFields
 		};
+		if (CANONICAL_SERVED.has(vendor)) {
+			const overrides = Object.keys(vendorFields);
+			if (overrides.length > 0) warnings.push(`harnesses.${vendor} sets ${overrides.join(", ")}, but ${vendor} reads the canonical plugin.json directly — these fields are not delivered`);
+			writeSkillArtifacts(root, vendor, skills, opts, written, warnings);
+			rows.push({
+				vendor,
+				path: relPath,
+				status: "canonical"
+			});
+			continue;
+		}
 		if (opts.verbose) {
 			console.log(`[${vendor}] → ${outputPath}`);
-			for (const key of Object.keys(vendorFields)) console.log(`  + ${key} (from vendorExtensions)`);
+			for (const key of Object.keys(vendorFields)) console.log(`  + ${key} (from harnesses.${vendor})`);
 		}
 		try {
 			if (!opts.dryRun) {
@@ -277,6 +305,7 @@ function buildPlugin(root, opts = {}) {
 				fsNode.writeFileSync(outputPath, `${JSON.stringify(vendorManifest, null, indent)}\n`);
 			}
 			written.push(outputPath);
+			writeSkillArtifacts(root, vendor, skills, opts, written, warnings);
 			rows.push({
 				vendor,
 				path: relPath,
@@ -299,18 +328,90 @@ function buildPlugin(root, opts = {}) {
 		summary: summarize(rows)
 	};
 }
+function writeSkillArtifacts(root, vendor, skills, opts, written, warnings) {
+	for (const skill of skills) {
+		if (vendor === "claude-code") {
+			writeClaudeSkill(skill, opts, written);
+			continue;
+		}
+		if (skill.invocationPolicy === "model") continue;
+		if (vendor === "cursor") {
+			writeArtifact(path.join(root, ".cursor", "commands", `${skill.name}.md`), skill.body, opts, written);
+			continue;
+		}
+		if (vendor === "codex") try {
+			writeArtifact(path.join(os.homedir(), ".codex", "prompts", `${skill.name}.md`), skill.body, opts, written);
+		} catch (err) {
+			warnings.push(`Failed to write Codex prompt for skill "${skill.name}" (best-effort): ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+}
+function readSkills(root, manifest) {
+	const skillsCfg = universalPluginExtension(manifest).skills;
+	const skillsPath = typeof skillsCfg === "string" ? skillsCfg : "./skills/";
+	const skillsDir = path.resolve(root, skillsPath);
+	if (!fsNode.existsSync(skillsDir)) return [];
+	return listSkillFiles(skillsDir).map((skillPath) => parseSkill(skillPath));
+}
+function listSkillFiles(dir) {
+	return fsNode.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const entryPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) return listSkillFiles(entryPath);
+		return entry.isFile() && entry.name === "SKILL.md" ? [entryPath] : [];
+	});
+}
+function parseSkill(skillPath) {
+	const content = fsNode.readFileSync(skillPath, "utf8");
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+	const frontmatter = match?.[1] ?? "";
+	const rawPolicy = frontmatter.match(/^invocation-policy:\s*['"]?(user|model|both)['"]?\s*(?:#.*)?$/m)?.[1];
+	const declaredPolicy = frontmatter.match(/^invocation-policy:\s*(\S+)/m)?.[1];
+	if (declaredPolicy && !rawPolicy) throw new Error(`Invalid invocation-policy "${declaredPolicy}" in ${skillPath}; expected user, model, or both`);
+	return {
+		path: skillPath,
+		name: path.basename(path.dirname(skillPath)),
+		invocationPolicy: rawPolicy ?? "both",
+		hasInvocationPolicy: rawPolicy !== void 0,
+		body: match ? content.slice(match[0].length) : content,
+		content
+	};
+}
+function writeClaudeSkill(skill, opts, written) {
+	if (!skill.hasInvocationPolicy) return;
+	const content = withClaudeInvocationFlags(skill);
+	if (content === skill.content) return;
+	if (!opts.dryRun) fsNode.writeFileSync(skill.path, content);
+	written.push(skill.path);
+}
+function withClaudeInvocationFlags(skill) {
+	const match = skill.content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return skill.content;
+	const lines = match[1].split(/\r?\n/).filter((line) => !/^(disable-model-invocation|user-invocable):\s*/.test(line));
+	if (skill.invocationPolicy === "user") lines.push("disable-model-invocation: true");
+	if (skill.invocationPolicy === "model") lines.push("user-invocable: false");
+	return `${skill.content.slice(0, match.index)}---\n${lines.join("\n")}\n---${skill.content.slice(match.index + match[0].length)}`;
+}
+function writeArtifact(outputPath, content, opts, written) {
+	if (!opts.dryRun) {
+		if (opts.clean && fsNode.existsSync(outputPath)) fsNode.unlinkSync(outputPath);
+		fsNode.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fsNode.writeFileSync(outputPath, content);
+	}
+	written.push(outputPath);
+}
 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
+		failed: rows.filter((r) => r.status === "failed").length,
+		canonical: rows.filter((r) => r.status === "canonical").length
 	};
 }
 //#endregion
 //#region src/build/cli.ts
-const NEXT_STEP$1 = "→ universal-plugin plugin validate\n";
+const NEXT_STEP$2 = "→ universal-plugin plugin validate\n";
 function buildCommand() {
-	const cmd = new Command("build").description("Generate vendor manifests from .plugin/plugin.json");
+	const cmd = new Command("build").description("Generate vendor manifests from 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 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), {
@@ -320,11 +421,12 @@ function buildCommand() {
 				clean: opts.clean
 			});
 			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
-			const { built, skipped, failed } = result.summary;
+			const { built, skipped, failed, canonical } = 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"),
+				canonical: result.rows.filter((r) => r.status === "canonical"),
 				summary: result.summary,
 				warnings: result.warnings
 			}, () => {
@@ -342,9 +444,10 @@ function buildCommand() {
 						get: (r) => r.status
 					}
 				]);
-				console.log(`built ${built}, skipped ${skipped}, failed ${failed}`);
+				const counts = `built ${built}, skipped ${skipped}, failed ${failed}`;
+				console.log(canonical > 0 ? `${counts}, served by plugin.json ${canonical}` : counts);
 			});
-			process.stderr.write(NEXT_STEP$1);
+			process.stderr.write(NEXT_STEP$2);
 			if (failed > 0) process.exitCode = 1;
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
@@ -388,7 +491,7 @@ function realPinFs(skillsDir) {
 }
 //#endregion
 //#region src/pin/pin.ts
-const PIN_PATTERN = /npx\s+(?:--yes\s+|-y\s+)?([@a-z0-9/._-]+)@(\S+)/g;
+const PIN_PATTERN = /(npx|upx)\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(/[`'")]+$/, "");
@@ -396,13 +499,15 @@ function stripTrailing(raw) {
 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;
+		const runner = match[1];
+		const pkg = match[2];
+		const current = match[3];
+		if (!runner || !pkg || !current) continue;
 		pins.push({
 			pkg,
 			current: stripTrailing(current),
-			file: ""
+			file: "",
+			runner
 		});
 	}
 	return pins;
@@ -412,12 +517,14 @@ function extractPins(text) {
 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}`);
+/** Rewrites every `npx <pkg>@<anything>` or `upx <pkg>@<anything>` occurrence in `content` to
+*  `<runner> <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. `forceRunner` omitted preserves each occurrence's existing runner word (an `npx`
+*  reference stays `npx`, an `upx` reference stays `upx`). */
+function rewritePin(content, pkg, next, forceRunner) {
+	const pattern = new RegExp(`(npx|upx)(\\s+(?:--yes\\s+|-y\\s+)?${escapeRegExp(pkg)}@)[^\\s\`'")]+`, "g");
+	return content.replace(pattern, (_match, runner, mid) => `${forceRunner ?? runner}${mid}${next}`);
 }
 const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
 const PIN_EXEMPT_PATTERN = /(^|\n)\s*pin-exempt:\s*true\s*(\n|$)/;
@@ -486,7 +593,7 @@ function bundlePins(pinFs, versionSource, opts = {}) {
 		let changed = false;
 		for (const file of inScope) {
 			const content = contents.get(file);
-			const rewritten = rewritePin(content, pkg, target);
+			const rewritten = rewritePin(content, pkg, target, opts.runner);
 			if (rewritten !== content) {
 				changed = true;
 				contents.set(file, rewritten);
@@ -500,7 +607,6 @@ function bundlePins(pinFs, versionSource, opts = {}) {
 			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
@@ -510,16 +616,13 @@ function bundlePins(pinFs, versionSource, opts = {}) {
 //#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. */
+*  ancestor declares one (the workspace glob then resolves relative to `start`). */
 function findMonorepoRoot(start) {
-	const from = path.resolve(start);
-	let dir = from;
+	let dir = start;
 	for (;;) {
 		if (fsNode.existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
 		const parent = path.dirname(dir);
-		if (parent === dir) return from;
+		if (parent === dir) return start;
 		dir = parent;
 	}
 }
@@ -613,16 +716,18 @@ function realVersionSource(workspace) {
 //#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";
+const NEXT_STEP$1 = "→ review and commit the pinned skills\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) => {
+	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)").option("--runner <runner>", "Runner word to emit on rewritten refs: npx or upx (default: preserve each ref's runner)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin bundle --dry-run --full\n").action((opts) => {
 		try {
+			const runner = opts.runner;
+			if (runner !== void 0 && runner !== "npx" && runner !== "upx") throw new Error(`error: unknown --runner value "${runner}" (expected npx or upx)`);
 			const root = resolveRoot(opts.root);
-			const result = bundlePins(realPinFs(resolveSkillsDir(root, readManifest(root).skills)), realVersionSource(discoverWorkspace(root)), { dryRun: opts.dryRun });
+			const result = bundlePins(realPinFs(resolveSkillsDir(root, universalPluginExtension(readManifest(root)).skills)), realVersionSource(discoverWorkspace(root)), {
+				dryRun: opts.dryRun,
+				runner
+			});
 			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;
@@ -653,8 +758,7 @@ function bundleCommand() {
 				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);
+			process.stderr.write(NEXT_STEP$1);
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
 			process.exit(1);
@@ -663,6 +767,143 @@ function bundleCommand() {
 	return cmd;
 }
 //#endregion
+//#region src/config/config.ts
+/** Pure domain for the plugin-registered config store.
+*
+*  `.agents/universal-plugin.json` holds the CLI's own config plus, under
+*  plugin-registered keys, arrays of `{ name, … }` entry objects. This module owns
+*  the rules: which keys are reserved, how an entry merges into a key's array
+*  (append or replace-by-name, position preserved), and how a key's array is read.
+*  No I/O — the caller supplies the parsed config object. */
+/** Keys `universal-plugin` owns for its own config — never plugin-registered arrays.
+*  `packagePath` is a string read by `publish sync-version`. */
+const RESERVED_KEYS = ["packagePath"];
+function isReservedKey(key) {
+	return RESERVED_KEYS.includes(key);
+}
+/** The array registered at `key`, or an empty array when the key is absent or non-array. */
+function getEntries(config, key) {
+	const value = config[key];
+	return Array.isArray(value) ? value : [];
+}
+/** Merge `entry` into the array at `key`: append when no element shares its `name`,
+*  else replace that element in place (array position preserved). Returns a new config
+*  object; the input is not mutated. Throws when `entry` is not a JSON object or lacks a
+*  non-empty `name` (the merge dedup key). Reserved-key rejection is the caller's guard. */
+function addEntry(config, key, entry) {
+	if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw new Error("error: --entry must be a JSON object");
+	const name = entry.name;
+	if (typeof name !== "string" || name.length === 0) throw new Error("error: --entry must include a non-empty \"name\" field");
+	const existing = getEntries(config, key);
+	const index = existing.findIndex((e) => typeof e === "object" && e !== null && e.name === name);
+	let next;
+	let action;
+	if (index === -1) {
+		next = [...existing, entry];
+		action = "appended";
+	} else {
+		next = existing.slice();
+		next[index] = entry;
+		action = "replaced";
+	}
+	return {
+		config: {
+			...config,
+			[key]: next
+		},
+		action,
+		name
+	};
+}
+//#endregion
+//#region src/config/fs.ts
+function configPath(root) {
+	return path.join(root, ".agents", "universal-plugin.json");
+}
+const realConfigFs = {
+	read(root) {
+		const file = configPath(root);
+		if (!fsNode.existsSync(file)) return {};
+		return JSON.parse(fsNode.readFileSync(file, "utf8"));
+	},
+	write(root, config) {
+		const file = configPath(root);
+		const indent = fsNode.existsSync(file) ? detectIndent(fsNode.readFileSync(file, "utf8")) : "	";
+		fsNode.mkdirSync(path.dirname(file), { recursive: true });
+		fsNode.writeFileSync(file, `${JSON.stringify(config, null, indent)}\n`);
+	}
+};
+//#endregion
+//#region src/config/cli.ts
+function assertNotReserved(key) {
+	if (isReservedKey(key)) throw new Error(`error: "${key}" is a reserved key (universal-plugin's own config) — not a plugin-registered array`);
+}
+function addCommand(fs) {
+	return new Command("add").description("Register (append or replace-by-name) an entry in the array at a config key").requiredOption("--key <key>", "The config key whose array to write").requiredOption("--entry <json>", "The entry object as JSON (must include a \"name\" field)").option("--format <format>", "Output format: json or toon (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin config add --key sdd-plugins --entry '{\"name\":\"aces\",\"handles\":[\"agent evaluation\"]}'\n").action((opts) => {
+		try {
+			assertNotReserved(opts.key);
+			let parsed;
+			try {
+				parsed = JSON.parse(opts.entry);
+			} catch {
+				throw new Error("error: --entry is not valid JSON");
+			}
+			const root = resolveRoot(opts.root);
+			const result = addEntry(fs.read(root), opts.key, parsed);
+			fs.write(root, result.config);
+			const count = getEntries(result.config, opts.key).length;
+			output({
+				key: opts.key,
+				name: result.name,
+				action: result.action
+			}, () => {
+				printTable([result], [
+					{
+						label: "key",
+						get: () => opts.key
+					},
+					{
+						label: "name",
+						get: (r) => r.name
+					},
+					{
+						label: "action",
+						get: (r) => r.action
+					}
+				]);
+				console.log(`${opts.key}: ${count} entries`);
+			});
+			process.stderr.write(`→ universal-plugin config get --key ${opts.key}\n`);
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+}
+function getCommand(fs) {
+	return new Command("get").description("Read the array of entries registered at a config key").requiredOption("--key <key>", "The config key whose array to read").option("--format <format>", "Output format: json or toon (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin config get --key sdd-plugins\n").action((opts) => {
+		try {
+			assertNotReserved(opts.key);
+			const root = resolveRoot(opts.root);
+			const entries = getEntries(fs.read(root), opts.key);
+			output(entries, () => {
+				printTable(entries, [{
+					label: "name",
+					get: (e) => String(e.name ?? "")
+				}]);
+				console.log(`${opts.key}: ${entries.length} entries`);
+			});
+			process.stderr.write(`→ universal-plugin config add --key ${opts.key} --entry <json>\n`);
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+}
+function configCommand(fs = realConfigFs) {
+	return new Command("config").description("Read and write plugin-registered config in .agents/universal-plugin.json").addCommand(addCommand(fs)).addCommand(getCommand(fs));
+}
+//#endregion
 //#region src/governance/fs.ts
 const realGovernanceFs = {
 	exists: (p) => fsNode.existsSync(p),
@@ -807,6 +1048,486 @@ function governanceCommand() {
 	return cmd;
 }
 //#endregion
+//#region src/init/fs.ts
+function manifestPath(root) {
+	return path.join(root, "plugin.json");
+}
+function packageJsonPath(root) {
+	return path.join(root, "package.json");
+}
+const realInitFs = {
+	gather(root) {
+		const pj = packageJsonPath(root);
+		const packageJson = fsNode.existsSync(pj) ? JSON.parse(fsNode.readFileSync(pj, "utf8")) : null;
+		return {
+			manifestExists: fsNode.existsSync(manifestPath(root)),
+			packageJson
+		};
+	},
+	apply(root, plan) {
+		fsNode.writeFileSync(manifestPath(root), `${JSON.stringify(plan.manifest, null, "	")}\n`);
+		for (const dir of plan.dirs) fsNode.mkdirSync(path.join(root, dir), { recursive: true });
+		if (plan.packageJson) {
+			const pj = packageJsonPath(root);
+			const indent = detectIndent(fsNode.readFileSync(pj, "utf8"));
+			fsNode.writeFileSync(pj, `${JSON.stringify(plan.packageJson, null, indent)}\n`);
+		}
+	}
+};
+//#endregion
+//#region src/init/init.ts
+/** Pure domain for `plugin init` — scaffolding the canonical manifest and (with `--npm`)
+*  wiring an npm package to ship it.
+*
+*  No I/O: the caller gathers the current filesystem state, calls `planInit`, and applies the
+*  returned plan. `planInit` owns the rules — the guard order, the closed manifest shape, the
+*  no-`--vendor` default (omit the `vendors` key, never write `vendors: []` — `plugin build`'s
+*  `vendors ?? harnesses`-keys fallback engages only on an absent key), and the `--npm`
+*  files-wiring default (`claude-code`). The vendor→derived-manifest-path map is injected so the
+*  domain stays free of the build/registry layer. */
+const SCHEMA_URL = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+const UP_NAMESPACE = "org.cyberuni.universal-plugin";
+const SCAFFOLD_DIRS = [
+	"skills",
+	"agents",
+	"governances",
+	"commands"
+];
+/** The closed canonical manifest init writes: `$schema` + `name`, plus the extensions namespace
+*  carrying the `vendors` list only when `--vendor` was passed. */
+function buildManifest(name, vendors) {
+	const manifest = {
+		$schema: SCHEMA_URL,
+		name
+	};
+	if (vendors.length > 0) manifest.extensions = { [UP_NAMESPACE]: { vendors } };
+	return manifest;
+}
+/** The open-standard base every published plugin ships, whatever it targets: the canonical
+*  Agent Plugins Spec manifest and the skills directory every runtime reads. Vendor-derived
+*  manifests layer on top of this — they never replace it. */
+const STANDARD_FILES = ["plugin.json", "skills/"];
+/** Adds the open-standard base plus each derived manifest path to `package.json` `files`, creating
+*  the array when absent and never duplicating an entry. Other fields and existing entries are
+*  preserved. The base goes in regardless of `--vendor`: a package that ships only
+*  `.claude-plugin/plugin.json` has published a Claude Code plugin, not a standard one. */
+function wireFiles(pkg, manifestPaths) {
+	const files = Array.isArray(pkg.files) ? [...pkg.files] : [];
+	for (const entry of [...STANDARD_FILES, ...manifestPaths]) if (!files.includes(entry)) files.push(entry);
+	return {
+		...pkg,
+		files
+	};
+}
+/** Plans the init run. Throws on a guard failure (an existing manifest without `--force`; `--npm`
+*  with no `package.json`) before returning any plan, so the caller writes nothing on a guard trip. */
+function planInit(state, opts, rootDirName, resolveManifestPath) {
+	if (opts.npm && state.packageJson === null) throw new Error("error: --npm requires a package.json at the project root");
+	if (state.manifestExists && !opts.force) throw new Error("plugin.json already exists — pass --force to overwrite");
+	const manifest = buildManifest(opts.name ?? rootDirName, opts.vendors);
+	const dirs = opts.scaffold ? [...SCAFFOLD_DIRS] : [];
+	const rows = [{
+		path: "plugin.json",
+		action: "created"
+	}];
+	let packageJson = null;
+	if (opts.npm) {
+		const manifestPaths = (opts.vendors.length > 0 ? opts.vendors : ["claude-code"]).map(resolveManifestPath).filter((p) => Boolean(p));
+		packageJson = wireFiles(state.packageJson, manifestPaths);
+		rows.push({
+			path: "package.json",
+			action: "updated"
+		});
+	}
+	const created = rows.filter((r) => r.action === "created").length;
+	const updated = rows.filter((r) => r.action === "updated").length;
+	return {
+		manifest,
+		dirs,
+		packageJson,
+		rows,
+		summary: {
+			created,
+			updated
+		}
+	};
+}
+//#endregion
+//#region src/init/cli.ts
+const NEXT_STEP = "→ add skills to skills/, then run universal-plugin plugin build\n";
+function collect(value, previous) {
+	return [...previous, value];
+}
+function initCommand$1(deps = { fs: realInitFs }) {
+	const cmd = new Command("init").description("Scaffold the canonical plugin.json (with --npm, wire an npm package to ship it)");
+	cmd.option("--name <name>", "Plugin name (default: the root directory name)").option("--vendor <id>", "Target vendor; repeatable", collect, []).option("--scaffold", "Create the standard skills/ agents/ governances/ commands/ directories").option("--force", "Overwrite an existing plugin.json").option("--yes", "Non-interactive (compatibility no-op; init never prompts)").option("--npm", "Wire package.json 'files' to ship the derived vendor manifests").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 init --name my-plugin --scaffold\n").action((opts) => {
+		try {
+			const root = resolveRoot(opts.root);
+			const plan = planInit(deps.fs.gather(root), {
+				name: opts.name,
+				vendors: opts.vendor ?? [],
+				scaffold: Boolean(opts.scaffold),
+				force: Boolean(opts.force),
+				npm: Boolean(opts.npm)
+			}, path.basename(root), (vendor) => VENDOR_OUTPUT[vendor]);
+			deps.fs.apply(root, plan);
+			output({
+				created: plan.rows.filter((r) => r.action === "created").map((r) => r.path),
+				updated: plan.rows.filter((r) => r.action === "updated").map((r) => r.path),
+				summary: plan.summary
+			}, () => {
+				printTable(plan.rows, [{
+					label: "path",
+					get: (r) => r.path
+				}, {
+					label: "action",
+					get: (r) => r.action
+				}]);
+				console.log(`created ${plan.summary.created}, updated ${plan.summary.updated}`);
+			});
+			process.stderr.write(NEXT_STEP);
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+//#endregion
+//#region src/marketplace/fs.ts
+const realMarketplaceFs = {
+	exists: fsNode.existsSync,
+	isDirectory(file) {
+		return fsNode.statSync(file).isDirectory();
+	},
+	realpath(file) {
+		return fsNode.realpathSync(file);
+	},
+	read(file) {
+		return fsNode.readFileSync(file, "utf8");
+	},
+	listEntries(dir) {
+		return fsNode.readdirSync(dir);
+	},
+	writeAtomically(file, content) {
+		fsNode.mkdirSync(path.dirname(file), { recursive: true });
+		const temporary = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+		fsNode.writeFileSync(temporary, content);
+		fsNode.renameSync(temporary, file);
+	}
+};
+//#endregion
+//#region src/marketplace/marketplace.ts
+const COMMON_METADATA = [
+	"description",
+	"version",
+	"homepage",
+	"repository",
+	"license",
+	"keywords"
+];
+function assertMarketplaceName(value, label) {
+	if (!/^[a-z0-9][a-z0-9._-]*$/i.test(value)) throw new Error(`error: ${label} "${value}" must contain only letters, digits, dots, underscores, or hyphens`);
+}
+function commonMetadata(plugin) {
+	const result = {};
+	for (const field of COMMON_METADATA) if (plugin.metadata[field] !== void 0) result[field] = plugin.metadata[field];
+	return result;
+}
+function json(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+function claudeArtifact(metadata, plugins) {
+	return {
+		path: ".claude-plugin/marketplace.json",
+		content: json({
+			...metadata,
+			plugins: plugins.map((plugin) => ({
+				name: plugin.name,
+				source: plugin.source,
+				...commonMetadata(plugin)
+			}))
+		})
+	};
+}
+function codexArtifact(metadata, plugins) {
+	return {
+		path: ".agents/plugins/marketplace.json",
+		content: json({
+			name: metadata.name,
+			interface: { displayName: metadata.name },
+			plugins: plugins.map((plugin) => ({
+				name: plugin.name,
+				version: plugin.metadata.version,
+				source: {
+					source: "local",
+					path: plugin.source
+				},
+				policy: {
+					installation: "AVAILABLE",
+					authentication: "ON_INSTALL"
+				},
+				category: "Productivity"
+			}))
+		})
+	};
+}
+function copilotArtifact(metadata, plugins) {
+	return {
+		path: ".github/plugin/marketplace.json",
+		content: json({
+			...metadata,
+			metadata: { displayName: metadata.name },
+			plugins: plugins.map((plugin) => ({
+				name: plugin.name,
+				source: plugin.source,
+				...commonMetadata(plugin)
+			}))
+		})
+	};
+}
+function cursorArtifacts(metadata, plugins) {
+	const sources = plugins.map((plugin) => ({
+		name: plugin.name,
+		source: plugin.source,
+		...commonMetadata(plugin)
+	}));
+	return [{
+		path: ".cursor-plugin/marketplace-submission.json",
+		content: json({
+			...metadata,
+			plugins: sources,
+			dashboard: "https://cursor.com/dashboard"
+		})
+	}, {
+		path: "CURSOR_MARKETPLACE_SUBMISSION.md",
+		content: `# Cursor Marketplace Submission\n\nMarketplace: ${metadata.name}\nOwner: ${metadata.owner}\n\nPlugins:\n${sources.map((plugin) => `- ${plugin.name}: ${plugin.source}`).join("\n")}\n\nSubmit this metadata through the [Cursor dashboard](https://cursor.com/dashboard). This command generated local submission metadata only; no publication or provisioning occurred.\n`
+	}];
+}
+function serializeTarget(target, metadata, plugins) {
+	switch (target) {
+		case "claude": return [claudeArtifact(metadata, plugins)];
+		case "codex": return [codexArtifact(metadata, plugins)];
+		case "copilot": return [copilotArtifact(metadata, plugins)];
+		case "cursor": return cursorArtifacts(metadata, plugins);
+	}
+}
+//#endregion
+//#region src/marketplace/init.ts
+function isInside(root, candidate) {
+	const relative = path.relative(root, candidate);
+	return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+function containingExistingPath(file, fs) {
+	let current = file;
+	while (!fs.exists(current)) {
+		const parent = path.dirname(current);
+		if (parent === current) throw new Error(`error: path "${file}" must resolve within --root`);
+		current = parent;
+	}
+	return current;
+}
+function assertContained(root, candidate, fs, label) {
+	if (!isInside(fs.realpath(root), fs.realpath(containingExistingPath(candidate, fs)))) throw new Error(`error: ${label} "${candidate}" must resolve within --root`);
+}
+function parseManifest(fs, file) {
+	try {
+		const parsed = JSON.parse(fs.read(file));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not an object");
+		return parsed;
+	} catch {
+		throw new Error(`error: manifest "${file}" is not valid JSON`);
+	}
+}
+function manifestOwner(manifest) {
+	if (typeof manifest.author === "string") return manifest.author;
+	if (typeof manifest.author === "object" && manifest.author !== null) {
+		const author = manifest.author;
+		if (typeof author.name === "string") return author.name;
+	}
+}
+function deriveMetadata(root, fs, opts) {
+	const rootManifest = path.join(root, "plugin.json");
+	if (fs.exists(rootManifest)) assertContained(root, rootManifest, fs, "root plugin.json");
+	const manifest = fs.exists(rootManifest) ? parseManifest(fs, rootManifest) : {};
+	const name = opts.name ?? path.basename(root);
+	const owner = opts.owner ?? manifestOwner(manifest);
+	assertMarketplaceName(name, "marketplace name");
+	if (!owner || owner.trim() === "") throw new Error("error: marketplace owner is required; set --owner or root plugin.json author");
+	return {
+		name,
+		owner
+	};
+}
+function scanRoots(root, fs, scanDirs) {
+	const roots = [...new Set((scanDirs ?? ["plugins"]).map((dir) => path.resolve(root, dir)))].sort();
+	for (const scanRoot of roots) {
+		if (!isInside(root, scanRoot)) throw new Error(`error: --plugin-scan-dir "${scanRoot}" must resolve within --root`);
+		if (!fs.exists(scanRoot)) {
+			if (scanDirs === void 0) continue;
+			throw new Error(`error: plugin scan directory "${scanRoot}" does not exist`);
+		}
+		if (!fs.isDirectory(scanRoot)) throw new Error(`error: plugin scan directory "${scanRoot}" is not a directory`);
+		assertContained(root, scanRoot, fs, "--plugin-scan-dir");
+	}
+	return roots.filter((scanRoot) => fs.exists(scanRoot));
+}
+function discoverPlugins(root, fs, scanDirs) {
+	const plugins = [];
+	const names = /* @__PURE__ */ new Set();
+	for (const scanRoot of scanRoots(root, fs, scanDirs)) for (const entry of fs.listEntries(scanRoot).sort()) {
+		if ([
+			".plugin",
+			".claude-plugin",
+			".codex-plugin",
+			".cursor-plugin"
+		].includes(entry)) continue;
+		const pluginRoot = path.join(scanRoot, entry);
+		if (!fs.isDirectory(pluginRoot)) continue;
+		assertContained(root, pluginRoot, fs, "plugin directory");
+		const manifestPath = path.join(pluginRoot, "plugin.json");
+		if (!fs.exists(manifestPath)) continue;
+		assertContained(root, manifestPath, fs, "plugin manifest");
+		const manifest = parseManifest(fs, manifestPath);
+		if (typeof manifest.name !== "string" || manifest.name.trim() === "") throw new Error(`error: manifest "${manifestPath}" must contain a non-empty name`);
+		assertMarketplaceName(manifest.name, "plugin name");
+		if (names.has(manifest.name)) throw new Error(`error: duplicate plugin name "${manifest.name}"`);
+		names.add(manifest.name);
+		const source = `./${path.relative(root, pluginRoot).split(path.sep).join("/")}`;
+		plugins.push({
+			name: manifest.name,
+			source,
+			metadata: manifest
+		});
+	}
+	return plugins.sort((a, b) => a.name.localeCompare(b.name));
+}
+function assertCodexPluginVersions(plugins) {
+	for (const plugin of plugins) if (typeof plugin.metadata.version !== "string" || plugin.metadata.version.trim() === "") throw new Error(`error: canonical plugin manifest for Codex entry "${plugin.name}" requires a version`);
+}
+function writeArtifacts(fs, artifacts, root) {
+	const changed = artifacts.filter((artifact) => !sameArtifact(fs, path.join(root, artifact.path), artifact.content));
+	for (const artifact of changed) fs.writeAtomically(path.join(root, artifact.path), artifact.content);
+}
+function selectedTargets(targets) {
+	return targets && targets.length > 0 ? [...new Set(targets)] : [
+		"claude",
+		"codex",
+		"copilot"
+	];
+}
+function sameArtifact(fs, file, content) {
+	if (!fs.exists(file)) return false;
+	const existing = fs.read(file);
+	if (!file.endsWith(".json")) return existing === content;
+	try {
+		return JSON.stringify(normalizeJson(JSON.parse(existing))) === JSON.stringify(normalizeJson(JSON.parse(content)));
+	} catch {
+		return false;
+	}
+}
+/** JSON object key order and whitespace do not change a catalog's meaning; array order does. */
+function normalizeJson(value) {
+	if (Array.isArray(value)) return value.map(normalizeJson);
+	if (typeof value !== "object" || value === null) return value;
+	const record = value;
+	return Object.fromEntries(Object.keys(record).sort().map((key) => [key, normalizeJson(record[key])]));
+}
+function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
+	const root = path.resolve(rootInput);
+	const metadata = deriveMetadata(root, fs, opts);
+	const plugins = discoverPlugins(root, fs, opts.scanDirs);
+	const targets = selectedTargets(opts.targets);
+	if (targets.includes("codex")) assertCodexPluginVersions(plugins);
+	const planned = targets.map((target) => ({
+		target,
+		artifacts: serializeTarget(target, metadata, plugins)
+	}));
+	for (const { artifacts } of planned) for (const artifact of artifacts) assertContained(root, path.join(root, artifact.path), fs, "selected artifact");
+	const conflicts = [];
+	for (const entry of planned) for (const artifact of entry.artifacts) {
+		const output = path.join(root, artifact.path);
+		if (fs.exists(output) && !sameArtifact(fs, output, artifact.content) && !opts.force) conflicts.push(artifact.path);
+	}
+	if (conflicts.length > 0) throw new Error(`error: generated artifact differs: ${conflicts.join(", ")}; rerun with --force to replace selected artifacts`);
+	const results = planned.map(({ target, artifacts }) => {
+		if (plugins.length === 0) return {
+			target,
+			status: "empty",
+			paths: [],
+			plugins: [],
+			reason: "no plugins discovered"
+		};
+		const unchanged = artifacts.every((artifact) => sameArtifact(fs, path.join(root, artifact.path), artifact.content));
+		return {
+			target,
+			status: opts.dryRun ? "planned" : unchanged ? "unchanged" : "generated",
+			paths: artifacts.map((artifact) => artifact.path),
+			plugins: plugins.map((plugin) => plugin.name)
+		};
+	});
+	if (!opts.dryRun && plugins.length > 0) writeArtifacts(fs, planned.flatMap((entry) => entry.artifacts), root);
+	if (!opts.targets || opts.targets.length === 0) results.push({
+		target: "cursor",
+		status: "skipped-default",
+		paths: [],
+		plugins: [],
+		reason: "Cursor requires an explicit submission scaffold"
+	});
+	return results;
+}
+//#endregion
+//#region src/marketplace/cli.ts
+function targetsFromOptions(opts) {
+	const targets = [
+		"claude",
+		"codex",
+		"copilot",
+		"cursor"
+	].filter((target) => opts[target]);
+	return targets.length > 0 ? targets : void 0;
+}
+function initCommand() {
+	return new Command("init").description("Generate local marketplace metadata without publishing or provisioning").option("--claude", "Generate the Claude marketplace catalog").option("--codex", "Generate the Codex marketplace catalog").option("--copilot", "Generate the Copilot marketplace catalog").option("--cursor", "Generate the Cursor submission scaffold").option("--plugin-scan-dir <dir>", "Directory beneath --root to scan for root-level plugin.json files (repeatable)", (value, previous = []) => [...previous, value]).option("--name <name>", "Override the marketplace name").option("--owner <name>", "Override the marketplace owner").option("--dry-run", "Preview artifacts without writing them").option("--force", "Replace differing artifacts for selected targets").option("--format <format>", "Output format: toon or json (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin marketplace init --root .\n").action((opts) => {
+		try {
+			if (opts.format !== void 0 && opts.format !== "toon" && opts.format !== "json") throw new Error("error: --format must be \"toon\" or \"json\"");
+			const results = initializeMarketplace(resolveRoot(opts.root), {
+				targets: targetsFromOptions(opts),
+				scanDirs: opts.pluginScanDir,
+				name: opts.name,
+				owner: opts.owner,
+				dryRun: opts.dryRun,
+				force: opts.force
+			});
+			output(results, () => printTable(results, [
+				{
+					label: "target",
+					get: (row) => row.target
+				},
+				{
+					label: "status",
+					get: (row) => row.status
+				},
+				{
+					label: "paths",
+					get: (row) => row.paths.join(", ") || "-"
+				},
+				{
+					label: "plugins",
+					get: (row) => row.plugins.join(", ") || "-"
+				}
+			]));
+			process.stderr.write("Generated repository metadata only; no marketplace publication, registration, installation, authentication, or provisioning occurred.\n");
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exitCode = 1;
+		}
+	});
+}
+function marketplaceCommand() {
+	return new Command("marketplace").description("Generate repository-local marketplace metadata").addCommand(initCommand());
+}
+//#endregion
 //#region src/vendor-registry/vendor-registry.ts
 function lookupVendor(registry, vendorId) {
 	return registry[vendorId] ?? null;
@@ -1038,32 +1759,87 @@ function prepareCommand() {
 	});
 }
 //#endregion
-//#region src/publish/fs.ts
-const realSyncVersionFs = {
+//#region src/version/fs.ts
+const realJsonIo = {
 	exists: (p) => fsNode.existsSync(p),
 	read: (p) => fsNode.readFileSync(p, "utf8"),
 	write: (p, content) => fsNode.writeFileSync(p, content)
 };
+/** Reads `packagePath` from `.agents/universal-plugin.json`. Absent file, absent key, or a
+*  non-string value all mean "this plugin declares no npm package" — the manifest is then the only
+*  authored file. (A *declared* path whose `package.json` is missing is a different case, and the
+*  domain rejects it.) */
+function readPackagePath(root, io) {
+	const configPath = path.join(root, ".agents", "universal-plugin.json");
+	if (!io.exists(configPath)) return null;
+	const packagePath = JSON.parse(io.read(configPath))["packagePath"];
+	return typeof packagePath === "string" && packagePath.length > 0 ? packagePath : null;
+}
+/** Writes `value` over `filePath`, keeping whatever indentation that file already used. */
+function writeJson(io, filePath, value) {
+	const indent = io.exists(filePath) ? detectIndent(io.read(filePath)) : "	";
+	io.write(filePath, `${JSON.stringify(value, null, indent)}\n`);
+}
+/** The one applier. Writes every authored file the plan names — and nothing else: the derived
+*  vendor manifests are re-derived by calling `plugin build`, which owns them. */
+function applyVersionPlan(root, plan, io) {
+	writeJson(io, path.join(root, "plugin.json"), plan.manifest);
+	if (plan.packageJson) writeJson(io, path.join(root, plan.packageJson.path), plan.packageJson.content);
+}
+const realVersionFs = {
+	gather(root) {
+		const manifestPath = path.join(root, "plugin.json");
+		const manifestExists = realJsonIo.exists(manifestPath);
+		const manifest = manifestExists ? JSON.parse(realJsonIo.read(manifestPath)) : null;
+		const packagePath = readPackagePath(root, realJsonIo);
+		const pkgJsonPath = packagePath === null ? null : path.join(root, packagePath, "package.json");
+		return {
+			manifestExists,
+			manifest,
+			packagePath,
+			packageJson: pkgJsonPath !== null && realJsonIo.exists(pkgJsonPath) ? JSON.parse(realJsonIo.read(pkgJsonPath)) : null
+		};
+	},
+	apply(root, plan) {
+		applyVersionPlan(root, plan, realJsonIo);
+	}
+};
+//#endregion
+//#region src/publish/fs.ts
+const realSyncVersionFs = realJsonIo;
 //#endregion
 //#region src/publish/sync-version.ts
+/** The changesets-driven direction of the version flow: the number is decided by
+*  `changeset version` in `<packagePath>/package.json`, and this copies it into the canonical
+*  manifest. `plugin version` is the other direction — the number decided here, flowing out to
+*  `package.json`. The two differ **only** in where the version comes from, so they share
+*  `applyVersionPlan` and cannot drift; `package.json` is the source here, never rewritten. */
 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 manifestPath = path.join(root, "plugin.json");
+	if (!syncFs.exists(manifestPath)) throw new Error(`No 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 manifest = JSON.parse(syncFs.read(manifestPath));
 	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`);
+	const current = manifest["version"];
+	applyVersionPlan(root, {
+		from: typeof current === "string" ? current : null,
+		to: version,
+		manifest: {
+			...manifest,
+			version
+		},
+		packageJson: null,
+		rows: [{
+			path: "plugin.json",
+			action: "updated"
+		}],
+		summary: { updated: 1 }
+	}, syncFs);
 	return {
 		version,
 		manifestPath
@@ -1073,7 +1849,7 @@ function syncVersion(root, syncFs) {
 //#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) => {
+	cmd.command("sync-version").description("Sync version from packagePath/package.json into plugin.json").addOption(ROOT_OPTION).action((opts) => {
 		try {
 			const result = syncVersion(resolveRoot(opts.root), realSyncVersionFs);
 			output(result, () => {
@@ -1232,18 +2008,173 @@ function syncCommand() {
 	return cmd;
 }
 //#endregion
+//#region src/version/version.ts
+/** Pure domain for `plugin version` — moving a plugin's version.
+*
+*  No I/O: the caller gathers the current filesystem state, calls `planVersion`, and applies the
+*  returned plan. `planVersion` owns the rules — the guard order (every guard resolves before the
+*  first write, so a failing run leaves the tree untouched), the bump arithmetic, and the fact that
+*  only the **authored** files are planned.
+*
+*  A version lives in five places, but only two are authored: the canonical `plugin.json` and, when
+*  the project declares a `packagePath`, that `package.json`. The per-vendor manifests
+*  (`plugin build`), the local marketplace catalogs (`marketplace init`), and the `npx`/`upx`
+*  pins in `skills/**` (`plugin bundle`) are all **derived** — re-derived by calling the command
+*  that owns them, never written a second time here. */
+const RELEASE_TYPES = [
+	"major",
+	"minor",
+	"patch",
+	"premajor",
+	"preminor",
+	"prepatch",
+	"prerelease"
+];
+function isReleaseType(value) {
+	return RELEASE_TYPES.includes(value);
+}
+/** Reads the canonical manifest's current version, or `null` when it carries none. */
+function currentVersion(manifest) {
+	const version = manifest?.["version"];
+	return typeof version === "string" && version.length > 0 ? version : null;
+}
+/** Resolves the bump argument against the current version. An explicit version is used as given;
+*  a release type is applied to the current one, which must therefore exist. */
+function resolveTarget(current, opts) {
+	if (semver.valid(opts.bump)) return semver.valid(opts.bump);
+	if (!isReleaseType(opts.bump)) throw new Error(`Unknown version or release type "${opts.bump}" — expected an explicit version (1.4.0) or one of: ${RELEASE_TYPES.join(", ")}`);
+	if (current === null) throw new Error("plugin.json has no version to bump from — pass an explicit version (e.g. 0.1.0) to set the first one");
+	const next = opts.preid === void 0 ? semver.inc(current, opts.bump) : semver.inc(current, opts.bump, opts.preid);
+	if (next === null) throw new Error(`Current version "${current}" in plugin.json is not valid semver`);
+	return next;
+}
+/** Plans the version move. Throws on any guard failure before returning a plan, so the caller
+*  writes nothing on a guard trip. */
+function planVersion(state, opts) {
+	if (!state.manifestExists || state.manifest === null) throw new Error("No plugin.json found at the project root");
+	const from = currentVersion(state.manifest);
+	const to = resolveTarget(from, opts);
+	if (from !== null && !semver.gt(to, from) && !opts.force) throw new Error(`Target version "${to}" does not advance on the current version "${from}" — pass --force to set it anyway`);
+	if (state.packagePath !== null && state.packageJson === null) throw new Error(`No package.json found at packagePath "${state.packagePath}"`);
+	const rows = [{
+		path: "plugin.json",
+		action: "updated"
+	}];
+	let packageJson = null;
+	if (state.packagePath !== null && state.packageJson !== null) {
+		const relPath = joinRelative(state.packagePath, "package.json");
+		packageJson = {
+			path: relPath,
+			content: {
+				...state.packageJson,
+				version: to
+			}
+		};
+		rows.push({
+			path: relPath,
+			action: "updated"
+		});
+	}
+	return {
+		from,
+		to,
+		manifest: {
+			...state.manifest,
+			version: to
+		},
+		packageJson,
+		rows,
+		summary: { updated: rows.length }
+	};
+}
+/** Root-relative POSIX join — the domain reports paths as the user typed `packagePath`, so the
+*  result stays stable across platforms and readable in the TOON output. */
+function joinRelative(dir, file) {
+	const normalized = dir.replace(/\\/g, "/").replace(/\/+$/, "");
+	return normalized === "" || normalized === "." ? file : `${normalized}/${file}`;
+}
+//#endregion
+//#region src/version/cli.ts
+function versionCommand(deps = { fs: realVersionFs }) {
+	const cmd = new Command("version").description("Move the plugin version across every file that carries one").argument("<bump>", `Release type (${RELEASE_TYPES.join(", ")}) or an explicit version (1.4.0)`);
+	cmd.option("--preid <id>", "Prerelease identifier for the pre* release types").option("--force", "Allow a version that does not advance on the current one").option("--no-build", "Skip re-deriving the vendor manifests").option("--dry-run", "Print what would be written without writing").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 version minor\n").action((bump, opts) => {
+		try {
+			const root = resolveRoot(opts.root);
+			const plan = planVersion(deps.fs.gather(root), {
+				bump,
+				preid: opts.preid,
+				force: Boolean(opts.force)
+			});
+			const dryRun = Boolean(opts.dryRun);
+			const rows = plan.rows.map((r) => ({
+				path: r.path,
+				action: dryRun ? "planned" : r.action
+			}));
+			if (!dryRun) {
+				deps.fs.apply(root, plan);
+				if (opts.build !== false) {
+					const result = buildPlugin(root, {});
+					for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
+					for (const written of result.written) rows.push({
+						path: path.relative(root, written).split(path.sep).join("/"),
+						action: "derived"
+					});
+				}
+			}
+			const jsonResult = {
+				from: plan.from,
+				to: plan.to,
+				dryRun,
+				written: dryRun ? [] : rows.map((r) => r.path),
+				planned: rows.filter((r) => r.action === "planned").map((r) => r.path),
+				summary: {
+					updated: plan.summary.updated,
+					derived: rows.filter((r) => r.action === "derived").length
+				}
+			};
+			output(jsonResult, () => {
+				printFields({
+					from: plan.from ?? "(none)",
+					to: plan.to
+				});
+				printTable(rows, [{
+					label: "path",
+					get: (r) => r.path
+				}, {
+					label: "action",
+					get: (r) => r.action
+				}]);
+				console.log(dryRun ? `planned ${plan.summary.updated}, updated 0 (dry run)` : `updated ${plan.summary.updated}, derived ${jsonResult.summary.derived}`);
+			});
+			process.stderr.write(nextStep(dryRun, opts.build !== false));
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exit(1);
+		}
+	});
+	return cmd;
+}
+function nextStep(dryRun, built) {
+	if (dryRun) return "→ re-run without --dry-run to apply\n";
+	return built ? "→ universal-plugin plugin bundle\n" : "→ universal-plugin plugin build\n";
+}
+//#endregion
 //#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);
 function pluginCommand() {
-	const cmd = new Command("plugin").description("Author the canonical plugin manifest (build, bundle; validate, init planned)");
+	const cmd = new Command("plugin").description("Author the canonical plugin manifest (build, bundle, init, version; validate planned)");
 	cmd.addCommand(buildCommand());
 	cmd.addCommand(bundleCommand());
+	cmd.addCommand(initCommand$1());
+	cmd.addCommand(versionCommand());
 	return cmd;
 }
 program.addCommand(pluginCommand());
 program.addCommand(cleanCommand());
+program.addCommand(configCommand());
 program.addCommand(governanceCommand());
+program.addCommand(marketplaceCommand());
 program.addCommand(prepareCommand());
 program.addCommand(publishCommand());
 program.addCommand(syncCommand());