universal-plugin 0.5.0 → 0.7.0

package/dist/cli.mjs

@@ -423,9 +423,26 @@ const COMMON_METADATA = [
 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`);
 }
+/** A manifest field carried into a catalog entry, in the shape the catalog schema states. A manifest
+*  written from a `package.json` carries `repository` as `{ type, url }`, and every catalog wants the
+*  URL alone — Claude Code rejects the object (`plugins[].repository: expected string`). A value that
+*  cannot be reduced to the right type is dropped rather than written: an entry missing an optional
+*  field still installs, an entry with the wrong type installs nowhere. */
+function catalogValue(field, value) {
+	if (field === "keywords") return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+	if (field === "repository" && typeof value === "object" && value !== null && !Array.isArray(value)) {
+		const url = value.url;
+		return typeof url === "string" ? url.replace(/^git\+/, "") : void 0;
+	}
+	return typeof value === "string" ? value : void 0;
+}
 function commonMetadata(plugin) {
 	const result = {};
-	for (const field of COMMON_METADATA) if (plugin.metadata[field] !== void 0) result[field] = plugin.metadata[field];
+	for (const field of COMMON_METADATA) {
+		if (plugin.metadata[field] === void 0) continue;
+		const value = catalogValue(field, plugin.metadata[field]);
+		if (value !== void 0) result[field] = value;
+	}
 	return result;
 }
 function json(value) {
@@ -665,6 +682,374 @@ function gatherCatalogRepo(root) {
 	};
 }
 //#endregion
+//#region src/marketplace/validation.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function checkString(issues, path, value, { required = false } = {}) {
+	if (value === void 0) {
+		if (required) issues.push({
+			path,
+			message: "is required"
+		});
+		return;
+	}
+	if (typeof value !== "string") {
+		issues.push({
+			path,
+			message: `must be a string, not ${typeName(value)}`
+		});
+		return;
+	}
+	if (required && value.trim() === "") issues.push({
+		path,
+		message: "must not be empty"
+	});
+}
+function checkStringArray(issues, path, value) {
+	if (value === void 0) return;
+	if (!Array.isArray(value)) {
+		issues.push({
+			path,
+			message: `must be an array of strings, not ${typeName(value)}`
+		});
+		return;
+	}
+	value.forEach((item, index) => {
+		checkString(issues, `${path}[${index}]`, item);
+	});
+}
+/** `owner` and a plugin's `author` share one shape: an object carrying a required `name`. A string
+*  there is the mistake `package.json`'s `"author": "Name <email>"` invites; Claude Code reports
+*  `expected object, received string` and refuses the catalog. */
+function checkPerson(issues, path, value, { required = false } = {}) {
+	if (value === void 0) {
+		if (required) issues.push({
+			path,
+			message: "is required"
+		});
+		return;
+	}
+	if (!isObject(value)) {
+		const remedy = typeof value === "string" ? ` — write { "name": ${JSON.stringify(value)} }` : "";
+		issues.push({
+			path,
+			message: `must be an object with a name, not ${typeName(value)}${remedy}`
+		});
+		return;
+	}
+	checkString(issues, `${path}.name`, value.name, { required: true });
+	checkString(issues, `${path}.email`, value.email);
+	checkString(issues, `${path}.url`, value.url);
+}
+/** The source forms the official schema accepts: a `./`-prefixed repository-relative path, or one of
+*  the tagged remote objects. */
+const REMOTE_SOURCE_KEYS = {
+	npm: ["package"],
+	url: ["url"],
+	github: ["repo"],
+	"git-subdir": ["url", "path"]
+};
+function checkClaudeSource(issues, path, value) {
+	if (value === void 0) {
+		issues.push({
+			path,
+			message: "is required"
+		});
+		return;
+	}
+	if (typeof value === "string") {
+		if (!value.startsWith("./")) issues.push({
+			path,
+			message: `must be a "./"-prefixed repository-relative path, not ${JSON.stringify(value)}`
+		});
+		return;
+	}
+	if (!isObject(value)) {
+		issues.push({
+			path,
+			message: `must be a "./" path or a source object, not ${typeName(value)}`
+		});
+		return;
+	}
+	const kind = value.source;
+	if (typeof kind !== "string" || !(kind in REMOTE_SOURCE_KEYS)) {
+		issues.push({
+			path: `${path}.source`,
+			message: `must be one of ${Object.keys(REMOTE_SOURCE_KEYS).join(", ")}`
+		});
+		return;
+	}
+	for (const key of REMOTE_SOURCE_KEYS[kind]) checkString(issues, `${path}.${key}`, value[key], { required: true });
+}
+function checkClaudeEntry(issues, path, entry) {
+	if (!isObject(entry)) {
+		issues.push({
+			path,
+			message: `must be an object, not ${typeName(entry)}`
+		});
+		return;
+	}
+	checkString(issues, `${path}.name`, entry.name, { required: true });
+	checkClaudeSource(issues, `${path}.source`, entry.source);
+	checkString(issues, `${path}.version`, entry.version);
+	checkString(issues, `${path}.description`, entry.description);
+	checkString(issues, `${path}.homepage`, entry.homepage);
+	if (isObject(entry.repository) && typeof entry.repository.url === "string") issues.push({
+		path: `${path}.repository`,
+		message: `must be a string, not object — write ${JSON.stringify(entry.repository.url)}`
+	});
+	else checkString(issues, `${path}.repository`, entry.repository);
+	checkString(issues, `${path}.license`, entry.license);
+	checkString(issues, `${path}.category`, entry.category);
+	checkPerson(issues, `${path}.author`, entry.author);
+	checkStringArray(issues, `${path}.keywords`, entry.keywords);
+	checkStringArray(issues, `${path}.tags`, entry.tags);
+}
+function validateClaudeShaped(catalog) {
+	const issues = [];
+	checkString(issues, "name", catalog.name, { required: true });
+	checkPerson(issues, "owner", catalog.owner, { required: true });
+	checkString(issues, "description", catalog.description);
+	checkString(issues, "version", catalog.version);
+	if (catalog.plugins === void 0) {
+		issues.push({
+			path: "plugins",
+			message: "is required"
+		});
+		return issues;
+	}
+	if (!Array.isArray(catalog.plugins)) {
+		issues.push({
+			path: "plugins",
+			message: `must be an array, not ${typeName(catalog.plugins)}`
+		});
+		return issues;
+	}
+	catalog.plugins.forEach((entry, index) => {
+		checkClaudeEntry(issues, `plugins[${index}]`, entry);
+	});
+	return issues;
+}
+/** Codex reads a document of its own: no `owner`, a display name under `interface`, and an object
+*  `source` naming a local path (`.research/local-marketplaces`, E-CODEX-M11). It tolerates extra
+*  keys and requires no entry `version`. */
+function validateCodex(catalog) {
+	const issues = [];
+	checkString(issues, "name", catalog.name, { required: true });
+	if (catalog.interface !== void 0 && !isObject(catalog.interface)) issues.push({
+		path: "interface",
+		message: `must be an object, not ${typeName(catalog.interface)}`
+	});
+	else if (isObject(catalog.interface)) checkString(issues, "interface.displayName", catalog.interface.displayName);
+	if (catalog.plugins === void 0) {
+		issues.push({
+			path: "plugins",
+			message: "is required"
+		});
+		return issues;
+	}
+	if (!Array.isArray(catalog.plugins)) {
+		issues.push({
+			path: "plugins",
+			message: `must be an array, not ${typeName(catalog.plugins)}`
+		});
+		return issues;
+	}
+	catalog.plugins.forEach((entry, index) => {
+		const path = `plugins[${index}]`;
+		if (!isObject(entry)) {
+			issues.push({
+				path,
+				message: `must be an object, not ${typeName(entry)}`
+			});
+			return;
+		}
+		checkString(issues, `${path}.name`, entry.name, { required: true });
+		checkString(issues, `${path}.version`, entry.version);
+		checkString(issues, `${path}.category`, entry.category);
+		if (typeof entry.source === "string") checkClaudeSource(issues, `${path}.source`, entry.source);
+		else if (isObject(entry.source)) {
+			checkString(issues, `${path}.source.source`, entry.source.source, { required: true });
+			if (entry.source.source === "local") checkClaudeSource(issues, `${path}.source.path`, entry.source.path);
+		} else issues.push({
+			path: `${path}.source`,
+			message: "is required"
+		});
+	});
+	return issues;
+}
+/** Every issue a target's runtime would raise against this catalog, empty when it loads. */
+function validateCatalog(target, catalog) {
+	if (!isObject(catalog)) return [{
+		path: "",
+		message: `catalog must be a JSON object, not ${typeName(catalog)}`
+	}];
+	return target === "codex" ? validateCodex(catalog) : validateClaudeShaped(catalog);
+}
+/** The same check against a catalog still in its serialized form. Text that does not parse is one
+*  issue rather than a thrown error, so a caller checking four files reports all four. */
+function validateCatalogContent(target, content) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch (err) {
+		return [{
+			path: "",
+			message: `is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+		}];
+	}
+	return validateCatalog(target, parsed);
+}
+/** One error message naming the file and every issue in it, for a caller that fails loud. */
+function formatCatalogIssues(file, issues) {
+	return `error: catalog "${file}" does not match the marketplace schema:\n${issues.map((issue) => `  ${issue.path === "" ? file : `${issue.path}`} ${issue.message}`).join("\n")}`;
+}
+//#endregion
+//#region src/pin/pin.ts
+/** The words that mean "fetch and run this package". Stated once: the skill-prose matcher below and
+*  the argv matcher used for `mcpServers` invocations must agree on what a runner is. */
+const RUNNERS = "npx|upx";
+/** The `-y` spelling is the one ad-hoc regexes miss, so it lives here with `--yes` rather than in
+*  each caller. */
+const RUNNER_FLAG = "--yes|-y";
+/** Characters a package specifier may carry, scope included. */
+const PACKAGE_CHARS = "@a-z0-9/._-";
+const PIN_PATTERN = new RegExp(`(${RUNNERS})\\s+(?:(?:${RUNNER_FLAG})\\s+)?([${PACKAGE_CHARS}]+)@(\\S+)`, "g");
+const RUNNER_WORD = new RegExp(`^(?:${RUNNERS})$`);
+const RUNNER_FLAG_ARG = new RegExp(`^(?:${RUNNER_FLAG})$`);
+const PACKAGE_TOKEN = new RegExp(`^[${PACKAGE_CHARS}]+$`);
+/** 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 runner = match[1];
+		const pkg = match[2];
+		const current = match[3];
+		if (!runner || !pkg || !current) continue;
+		pins.push({
+			pkg,
+			current: stripTrailing(current),
+			file: "",
+			runner
+		});
+	}
+	return pins;
+}
+/** True when `command` invokes a package runner, and so carries a package specifier in its argv. */
+function isPackageRunner(command) {
+	return typeof command === "string" && RUNNER_WORD.test(command);
+}
+/** Splits a package specifier token into its name and, when present, its version. A leading `@` is
+*  the scope separator, never the version one. */
+function splitSpecifier(token) {
+	const at = token.lastIndexOf("@");
+	if (at <= 0) return { pkg: token };
+	return {
+		pkg: token.slice(0, at),
+		version: token.slice(at + 1)
+	};
+}
+/** Rewrites the package specifier in a runner's argv to `<pkg>@<version>`. The specifier is the
+*  first argument that is not a runner flag. Returns null when the argv carries none. Every other
+*  argument is carried through exactly as authored — this rewrites one slot, not the argv. */
+function pinRunnerArgs(args, version) {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (typeof arg !== "string") continue;
+		if (RUNNER_FLAG_ARG.test(arg)) continue;
+		if (!PACKAGE_TOKEN.test(arg)) return null;
+		const { pkg, version: previous } = splitSpecifier(arg);
+		const next = [...args];
+		next[i] = `${pkg}@${version}`;
+		return previous === void 0 ? {
+			args: next,
+			pkg
+		} : {
+			args: next,
+			pkg,
+			previous
+		};
+	}
+	return null;
+}
+/** The canonical opt-in marker on an `mcpServers` entry: "this package is the plugin's own, stamp
+*  the plugin's version onto it". A build directive — never part of a vendor's schema, so it is
+*  stripped from everything derived. */
+const PIN_MARKER = "pinToPluginVersion";
+/** Stamps the plugin's version onto every `mcpServers` entry that opts in with {@link PIN_MARKER},
+*  and strips the marker from all of them. Pure: the caller decides where the result is delivered.
+*
+*  Opt-in is required and a name match is never used — a plugin may publish its server under a
+*  package name that is not the plugin's, and an unrelated `npx -y widget-cli` must never be
+*  stamped with this plugin's version. */
+function pinMcpServers(servers, version) {
+	const out = {};
+	const notes = [];
+	let changed = false;
+	for (const [server, rawEntry] of Object.entries(servers)) {
+		if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+			out[server] = rawEntry;
+			continue;
+		}
+		const { [PIN_MARKER]: marker, ...entry } = rawEntry;
+		if (marker !== void 0) changed = true;
+		if (marker !== true) {
+			out[server] = entry;
+			continue;
+		}
+		if (!version) {
+			notes.push({
+				server,
+				kind: "no-manifest-version"
+			});
+			out[server] = entry;
+			continue;
+		}
+		if (!isPackageRunner(entry["command"])) {
+			notes.push({
+				server,
+				kind: "not-a-runner"
+			});
+			out[server] = entry;
+			continue;
+		}
+		const args = entry["args"];
+		const pinned = Array.isArray(args) ? pinRunnerArgs(args, version) : null;
+		if (!pinned) {
+			notes.push({
+				server,
+				kind: "no-specifier"
+			});
+			out[server] = entry;
+			continue;
+		}
+		if (pinned.previous !== void 0 && pinned.previous !== version) notes.push({
+			server,
+			kind: "repinned",
+			previous: pinned.previous
+		});
+		out[server] = {
+			...entry,
+			args: pinned.args
+		};
+		changed = true;
+	}
+	return {
+		servers: out,
+		changed,
+		notes
+	};
+}
+//#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`. */
@@ -675,17 +1060,68 @@ 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. */
+/** Vendors the canonical root manifest serves as-is. The build derives no *manifest* for these —
+*  writing one would either be shadowed by root (a lower-precedence path) or clobber root itself.
+*  Their components are a separate question: see COPILOT_NAMESPACE. */
 const CANONICAL_SERVED = new Set(["copilot-cli"]);
+/** The reverse-domain directory Copilot CLI reads its native components from once a plugin declares
+*  the canonical `$schema` (ADR-0015). It REPLACES the plugin root for these kinds — a spec-mode
+*  runtime does not read `agents/` at all — so the build derives the tree rather than relying on the
+*  authored paths. `skills/` and `mcp.json` do not move.
+*  Evidence: `.research/copilot-spec-mode-namespace/`. */
+const COPILOT_NAMESPACE = "com.github.copilot";
+/** Component kinds whose directories the namespace took over, copied file-for-file, each with the
+*  schema's default location for the field. The default is what an *undeclared* field means, never a
+*  stand-in for a declared path that did not resolve — the same asymmetry `readSkills` follows. */
+const COPILOT_COPIED_KINDS = {
+	agents: "./agents/",
+	commands: "./commands/",
+	rules: "./rules/"
+};
+/** Where the namespace reads hooks and LSP config from. Fixed paths — Copilot CLI has no derived
+*  manifest that could repoint them. */
+const COPILOT_HOOKS_PATH = "hooks/hooks.json";
+const COPILOT_LSP_PATH = "lsp.json";
+/** Authored under the namespace, never derived: Copilot's canvas extensions have no canonical root
+*  location to derive from, so `--clean` must leave this subtree alone. */
+const COPILOT_AUTHORED_DIR = "extensions";
+/** What each vendor's build output occupies in the published package, for `plugin init --npm`'s
+*  `package.json` `files` wiring. */
+const VENDOR_SHIPPED_PATHS = {
+	"claude-code": [VENDOR_OUTPUT["claude-code"]],
+	cursor: [VENDOR_OUTPUT.cursor],
+	codex: [VENDOR_OUTPUT.codex],
+	"copilot-cli": [`${COPILOT_NAMESPACE}/`]
+};
 /** Where every vendor looks for a plugin's hooks when the manifest declares none
 *  (`.research/hook-event-survey/conclusion.md`). */
 const DEFAULT_HOOKS_PATH = "./hooks/hooks.json";
+/** Where skills live when the extension namespace declares no `skills` path. */
+const DEFAULT_SKILLS_PATH = "./skills/";
+/** The Agent Plugins Specification's fixed location for a plugin's MCP config (ADR-0007 §6.1). */
+const DEFAULT_MCP_PATH = "./mcp.json";
 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] ?? {};
 }
+/** Copilot CLI searches `.plugin/plugin.json` first, so a leftover one there outranks the canonical
+*  root manifest — the pre-0.6 layout's other half. */
+const SHADOWING_MANIFEST = ".plugin/plugin.json";
+/** The pre-0.6 layout signals, if any, that explain a build deriving nothing (issue #61). Pure: the
+*  one filesystem fact it needs is passed in.
+*
+*  Scoped to the two signals that are unambiguously the old layout. A manifest that merely omits the
+*  `extensions` block is not one of them — that is as likely a manifest nobody has configured yet as
+*  one left behind by an upgrade, and erroring on it would fail builds this change has no quarrel
+*  with. `doctor` still reports it as `legacy-manifest`, which is why the empty-state path points
+*  there. */
+function legacyLayoutSignals(manifest, hasShadowingManifest) {
+	const signals = [];
+	if ("vendorExtensions" in manifest) signals.push("plugin.json carries a top-level \"vendorExtensions\" block — harness fields moved under extensions[\"org.cyberuni.universal-plugin\"].harnesses");
+	if (hasShadowingManifest) signals.push(`${SHADOWING_MANIFEST} shadows the canonical root plugin.json`);
+	return signals;
+}
 function readManifest(root) {
 	const manifestPath = path.join(root, "plugin.json");
 	if (!fs.existsSync(manifestPath)) throw new Error(`No plugin.json found at ${root}`);
@@ -731,6 +1167,8 @@ function buildPlugin(root, opts = {}) {
 		vendors = [opts.vendor];
 	}
 	if (vendors.length === 0) {
+		const signals = legacyLayoutSignals(manifest, fs.existsSync(path.join(root, SHADOWING_MANIFEST)));
+		if (signals.length > 0) throw new Error(`Nothing was derived, and this project is still on the pre-0.6 manifest layout:\n${signals.map((s) => `  - ${s}`).join("\n")}\nRun /universal-plugin:doctor for the full diagnosis and the skill that owns each repair.`);
 		warnings.push("No vendors declared in harnesses — nothing to build");
 		return {
 			vendors: [],
@@ -747,8 +1185,11 @@ function buildPlugin(root, opts = {}) {
 	const { $schema: _schema, extensions: _extensions, ...metadata } = manifest;
 	const { vendors: _vendors, packagePath: _packagePath, harnesses: _harnesses, dependencies: declaredDependencies, ...componentConfig } = uext;
 	warnings.push(...validateDependencies(declaredDependencies).warnings);
-	const skills = readSkills(root, manifest);
+	const skills = readSkills(root, manifest, warnings);
 	const canonicalHooks = readCanonicalHooks(root, componentConfig["hooks"], warnings);
+	const declaredMcp = readCanonicalMcpServers(root, componentConfig["mcpServers"], warnings);
+	const mcp = declaredMcp ? pinMcpServers(declaredMcp.servers, manifest.version) : null;
+	warnings.push(...(mcp?.notes ?? []).map(formatMcpNote));
 	for (const vendor of vendors) {
 		const relPath = VENDOR_OUTPUT[vendor];
 		const outputPath = path.join(root, relPath);
@@ -764,11 +1205,17 @@ function buildPlugin(root, opts = {}) {
 		warnings.push(...dependencies.warnings);
 		if (dependencies.dependencies) vendorManifest["dependencies"] = dependencies.dependencies;
 		if (CANONICAL_SERVED.has(vendor)) {
-			for (const drop of dedupeDrops(hooks?.drops ?? [])) warnings.push(`${vendor} cannot run the "${drop.type}" hook handler on ${drop.event} — it is ignored at runtime`);
+			for (const drop of dedupeDrops(hooks?.drops ?? [])) warnings.push(`${vendor} cannot run the "${drop.type}" hook handler on ${drop.event} — dropped from the derived hooks file`);
+			if (mcp?.changed) warnings.push(`${vendor} reads the canonical plugin.json directly — the pinned mcpServers is not delivered to it`);
 			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(vendor, skills, opts, written, warnings);
-			rows.push({
+			const derived = deriveCopilotNamespace(root, componentConfig, hooks, indent, opts, written, warnings);
+			rows.push(derived ? {
+				vendor,
+				path: `${COPILOT_NAMESPACE}/`,
+				status: "built"
+			} : {
 				vendor,
 				path: relPath,
 				status: "canonical"
@@ -779,6 +1226,9 @@ function buildPlugin(root, opts = {}) {
 		const derivedHooksPath = path.join(outputDir, "hooks.json");
 		if (hooks?.changed) if (hooks.hooks) vendorManifest["hooks"] = `./${path.dirname(relPath).split(path.sep).join("/")}/hooks.json`;
 		else delete vendorManifest["hooks"];
+		const derivedMcpPath = path.join(outputDir, "mcp.json");
+		if (mcp?.changed && declaredMcp) if (declaredMcp.inline) vendorManifest["mcpServers"] = mcp.servers;
+		else vendorManifest["mcpServers"] = `./${path.dirname(relPath).split(path.sep).join("/")}/mcp.json`;
 		if (opts.verbose) {
 			console.log(`[${vendor}] → ${outputPath}`);
 			for (const key of Object.keys(vendorFields)) console.log(`  + ${key} (from harnesses.${vendor})`);
@@ -794,6 +1244,7 @@ function buildPlugin(root, opts = {}) {
 				if (hooks.hooks) writeArtifact(derivedHooksPath, `${JSON.stringify(hooks.hooks, null, indent)}\n`, opts, written);
 				else if (!opts.dryRun && fs.existsSync(derivedHooksPath)) fs.unlinkSync(derivedHooksPath);
 			}
+			if (mcp?.changed && declaredMcp && !declaredMcp.inline) writeArtifact(derivedMcpPath, `${JSON.stringify({ mcpServers: mcp.servers }, null, indent)}\n`, opts, written);
 			writeSkillArtifacts(vendor, skills, opts, written, warnings);
 			rows.push({
 				vendor,
@@ -848,6 +1299,8 @@ function refreshCatalogs(root, manifest, vendors, opts, written, warnings) {
 		if (existing === void 0) continue;
 		try {
 			const artifact = refreshCatalogEntry(target, plugin, existing);
+			const issues = validateCatalogContent(target, artifact.content);
+			if (issues.length > 0) warnings.push(formatCatalogIssues(relative, issues));
 			if (sameCatalogContent(artifact.content, existing)) {
 				rows.push({
 					path: relative,
@@ -891,12 +1344,40 @@ function writeSkillArtifacts(vendor, skills, opts, written, warnings) {
 		}
 	}
 }
-function readSkills(root, manifest) {
+/** Resolves a `pathValue` declaration — a single "./" path, an array of them, or a { paths: [...] }
+*  object — into the list of declared paths. Returns null when the field is absent or malformed, so
+*  the caller can tell "declared nothing" from "declared these", and never silently substitute a
+*  default for a form it failed to read. */
+function resolvePathValue(declaration) {
+	if (typeof declaration === "string") return [declaration];
+	if (Array.isArray(declaration)) {
+		const paths = declaration.filter((entry) => typeof entry === "string");
+		return paths.length === declaration.length ? paths : null;
+	}
+	if (declaration && typeof declaration === "object") {
+		const paths = declaration.paths;
+		if (Array.isArray(paths) && paths.every((entry) => typeof entry === "string")) return paths;
+	}
+	return null;
+}
+function readSkills(root, manifest, warnings) {
 	const skillsCfg = universalPluginExtension(manifest).skills;
-	const skillsPath = typeof skillsCfg === "string" ? skillsCfg : "./skills/";
-	const skillsDir = path.resolve(root, skillsPath);
-	if (!fs.existsSync(skillsDir)) return [];
-	return listSkillFiles(skillsDir).map((skillPath) => parseSkill(skillPath));
+	const declared = skillsCfg === void 0 ? null : resolvePathValue(skillsCfg);
+	if (skillsCfg !== void 0 && declared === null) {
+		warnings.push("skills declaration is not a path, a path list, or a { paths } object — no skills were read");
+		return [];
+	}
+	const paths = declared ?? [DEFAULT_SKILLS_PATH];
+	const skills = [];
+	for (const relPath of paths) {
+		const skillsDir = path.resolve(root, relPath);
+		if (!fs.existsSync(skillsDir)) {
+			if (declared) warnings.push(`skills path "${relPath}" not found — no skills read from it`);
+			continue;
+		}
+		skills.push(...listSkillFiles(skillsDir).map((skillPath) => parseSkill(skillPath)));
+	}
+	return skills;
 }
 function listSkillFiles(dir) {
 	return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
@@ -936,6 +1417,87 @@ function withClaudeInvocationFlags(skill) {
 	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)}`;
 }
+/** Derives the `com.github.copilot/` tree Copilot CLI reads its native components from in spec mode
+*  (ADR-0015). Returns whether anything was derived — a plugin that declares none of the moved kinds
+*  has nothing here and keeps its `canonical` row.
+*
+*  The moved directory kinds are copied file-for-file: their content is vendor-neutral, and the
+*  namespace is a location change, not a format change. Hooks are the exception — they are translated
+*  first, exactly as for every other vendor. `skills/` and `mcp.json` stay at the plugin root and are
+*  deliberately not copied: a second copy under the namespace is one nothing reads. */
+function deriveCopilotNamespace(root, componentConfig, hooks, indent, opts, written, warnings) {
+	const nsDir = path.join(root, COPILOT_NAMESPACE);
+	if (opts.clean && !opts.dryRun) cleanCopilotNamespace(nsDir);
+	let derived = false;
+	for (const [kind, defaultPath] of Object.entries(COPILOT_COPIED_KINDS)) {
+		const declaration = componentConfig[kind];
+		const declared = declaration === void 0 ? null : resolvePathValue(declaration);
+		if (declaration !== void 0 && declared === null) {
+			warnings.push(`${kind} declaration is not a path, a path list, or a { paths } object — nothing copied to ${COPILOT_NAMESPACE}/${kind}/`);
+			continue;
+		}
+		for (const relPath of declared ?? [defaultPath]) {
+			const sourceDir = path.resolve(root, relPath);
+			if (!fs.existsSync(sourceDir)) {
+				if (declared) warnings.push(`${kind} path "${relPath}" not found — nothing copied to ${COPILOT_NAMESPACE}/${kind}/`);
+				continue;
+			}
+			for (const file of listFilesRecursive(sourceDir)) {
+				const relative = path.relative(sourceDir, file);
+				const target = kind === "agents" ? copilotAgentName(relative) : relative;
+				writeArtifact(path.join(nsDir, kind, target), fs.readFileSync(file), opts, written);
+				derived = true;
+			}
+		}
+	}
+	const hooksPath = path.join(nsDir, COPILOT_HOOKS_PATH);
+	if (hooks?.hooks) {
+		writeArtifact(hooksPath, `${JSON.stringify(hooks.hooks, null, indent)}\n`, opts, written);
+		derived = true;
+	} else if (hooks && !opts.dryRun && fs.existsSync(hooksPath)) fs.unlinkSync(hooksPath);
+	const lspDeclaration = componentConfig["lspServers"];
+	if (lspDeclaration !== void 0) {
+		const lspPaths = resolvePathValue(lspDeclaration);
+		if (lspPaths === null) warnings.push("copilot-cli reads lspServers from com.github.copilot/lsp.json, and an inline map has no documented file shape to write — not delivered");
+		else for (const relPath of lspPaths) {
+			const sourceFile = path.resolve(root, relPath);
+			if (!fs.existsSync(sourceFile)) {
+				warnings.push(`lspServers path "${relPath}" not found — nothing copied to ${COPILOT_NAMESPACE}/${COPILOT_LSP_PATH}`);
+				continue;
+			}
+			writeArtifact(path.join(nsDir, COPILOT_LSP_PATH), fs.readFileSync(sourceFile), opts, written);
+			derived = true;
+		}
+	}
+	return derived;
+}
+/** Copilot CLI reads `agents/` as `.agent.md` files, while the canonical `agents/` is the Claude
+*  Code-shaped `*.md`. Copying the authored name would land a file the runtime ignores — the same
+*  silent loss ADR-0015 exists to end, one directory over. Commands and rules are copied verbatim:
+*  the runtime documents no extension for either, and inventing one would be a guess. */
+function copilotAgentName(relative) {
+	if (!relative.endsWith(".md") || relative.endsWith(".agent.md")) return relative;
+	return `${relative.slice(0, -3)}.agent.md`;
+}
+/** Removes what the build derives under the namespace, and only that. `extensions/` is authored
+*  there — deleting it would destroy the one thing in the tree nothing can regenerate. */
+function cleanCopilotNamespace(nsDir) {
+	if (!fs.existsSync(nsDir)) return;
+	for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+		if (entry.name === COPILOT_AUTHORED_DIR) continue;
+		fs.rmSync(path.join(nsDir, entry.name), {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function listFilesRecursive(dir) {
+	return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const entryPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) return listFilesRecursive(entryPath);
+		return entry.isFile() ? [entryPath] : [];
+	});
+}
 function writeArtifact(outputPath, content, opts, written) {
 	if (!opts.dryRun) {
 		if (opts.clean && fs.existsSync(outputPath)) fs.unlinkSync(outputPath);
@@ -990,9 +1552,60 @@ function dedupeDrops(drops) {
 		return true;
 	});
 }
+/** Resolves the canonical MCP declaration — an inline block, a path, or a list of paths — the same
+*  way hooks are resolved. Returns null when there is nothing to read; an unreadable declaration
+*  warns and leaves the declaration to pass through untouched. */
+function readCanonicalMcpServers(root, declaration, warnings) {
+	if (declaration && typeof declaration === "object" && !Array.isArray(declaration)) {
+		const block = declaration;
+		if (Array.isArray(block["paths"])) return fromPaths(root, block["paths"], warnings);
+		const inner = block["mcpServers"];
+		return {
+			servers: inner && typeof inner === "object" && !Array.isArray(inner) ? inner : block,
+			inline: true
+		};
+	}
+	const paths = (typeof declaration === "string" ? [declaration] : Array.isArray(declaration) ? declaration : null) ?? (fs.existsSync(path.resolve(root, DEFAULT_MCP_PATH)) ? [DEFAULT_MCP_PATH] : []);
+	if (paths.length === 0) return null;
+	return fromPaths(root, paths, warnings);
+}
+function fromPaths(root, paths, warnings) {
+	const merged = {};
+	let read = 0;
+	for (const relPath of paths) {
+		const mcpPath = path.resolve(root, relPath);
+		if (!fs.existsSync(mcpPath)) {
+			warnings.push(`mcp file "${relPath}" not found — left untranslated`);
+			continue;
+		}
+		try {
+			const parsed = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+			const inner = parsed["mcpServers"];
+			Object.assign(merged, inner && typeof inner === "object" && !Array.isArray(inner) ? inner : parsed);
+			read++;
+		} catch (err) {
+			warnings.push(`mcp file "${relPath}" could not be read — left untranslated: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return read === 0 ? null : {
+		servers: merged,
+		inline: false
+	};
+}
+/** A marked entry that could not be pinned is a silent loss of the guarantee the marker asked for,
+*  so each one is named. None of them fails the build — the manifest still derives. */
+function formatMcpNote(note) {
+	switch (note.kind) {
+		case "no-manifest-version": return `mcpServers "${note.server}" asks to be pinned to the plugin version, but the manifest declares no version — left unpinned`;
+		case "not-a-runner": return `mcpServers "${note.server}" asks to be pinned to the plugin version, but its command is not "npx" or "upx" — left unpinned`;
+		case "no-specifier": return `mcpServers "${note.server}" asks to be pinned to the plugin version, but its args carry no package specifier — left unpinned`;
+		case "repinned": return `mcpServers "${note.server}" was authored at "${note.previous}" — overwritten with the plugin version`;
+	}
+}
 //#endregion
 //#region src/build/cli.ts
 const NEXT_STEP$2 = "→ universal-plugin plugin validate\n";
+const NEXT_STEP_NOTHING_BUILT = "→ /universal-plugin:doctor — diagnose why nothing is declared\n";
 function buildCommand() {
 	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) => {
@@ -1028,7 +1641,7 @@ function buildCommand() {
 				})),
 				summary: (canonical > 0 ? `${counts}, served by plugin.json ${canonical}` : counts) + catalogSummary
 			});
-			process.stderr.write(NEXT_STEP$2);
+			process.stderr.write(result.vendors.length === 0 ? NEXT_STEP_NOTHING_BUILT : NEXT_STEP$2);
 			if (failed > 0) process.exitCode = 1;
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
@@ -1071,29 +1684,6 @@ function realPinFs(skillsDir) {
 	};
 }
 //#endregion
-//#region src/pin/pin.ts
-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(/[`'")]+$/, "");
-}
-function extractPins(text) {
-	const pins = [];
-	for (const match of text.matchAll(PIN_PATTERN)) {
-		const runner = match[1];
-		const pkg = match[2];
-		const current = match[3];
-		if (!runner || !pkg || !current) continue;
-		pins.push({
-			pkg,
-			current: stripTrailing(current),
-			file: "",
-			runner
-		});
-	}
-	return pins;
-}
-//#endregion
 //#region src/bundle/bundle.ts
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1709,9 +2299,9 @@ const STANDARD_FILES = ["plugin.json", "skills/"];
 *  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) {
+function wireFiles(pkg, vendorPaths) {
 	const files = Array.isArray(pkg.files) ? [...pkg.files] : [];
-	for (const entry of [...STANDARD_FILES, ...manifestPaths]) if (!files.includes(entry)) files.push(entry);
+	for (const entry of [...STANDARD_FILES, ...vendorPaths]) if (!files.includes(entry)) files.push(entry);
 	return {
 		...pkg,
 		files
@@ -1775,6 +2365,8 @@ function planCatalogs(state, opts, manifest, notes) {
 		const target = VENDOR_TARGETS[vendor];
 		if (!target) continue;
 		const artifact = mergeCatalogEntry(target, metadata, plugin, (path) => repo.catalogs[path]);
+		const issues = validateCatalogContent(target, artifact.content);
+		if (issues.length > 0) notes.push(formatCatalogIssues(artifact.path, issues));
 		catalogs.push({
 			path: `${toPluginRoot}${artifact.path}`,
 			content: artifact.content
@@ -1784,7 +2376,7 @@ function planCatalogs(state, opts, manifest, notes) {
 }
 /** 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) {
+function planInit(state, opts, rootDirName, resolveShippedPaths) {
 	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);
@@ -1805,8 +2397,8 @@ function planInit(state, opts, rootDirName, resolveManifestPath) {
 	}
 	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);
+		const wireVendors = opts.vendors.length > 0 ? opts.vendors : ["claude-code"];
+		packageJson = wireFiles(state.packageJson, wireVendors.flatMap(resolveShippedPaths));
 		rows.push({
 			path: "package.json",
 			action: "updated"
@@ -1847,7 +2439,7 @@ function initCommand$1(deps = { fs: realInitFs }) {
 				force: Boolean(opts.force),
 				npm: Boolean(opts.npm),
 				marketplace: opts.marketplace !== false
-			}, path.basename(root), (vendor) => VENDOR_OUTPUT[vendor]);
+			}, path.basename(root), (vendor) => VENDOR_SHIPPED_PATHS[vendor] ?? []);
 			deps.fs.apply(root, plan);
 			output({
 				created: plan.rows.filter((r) => r.action === "created").map((r) => r.path),
@@ -2378,7 +2970,11 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 		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");
+	for (const { target, artifacts } of planned) for (const artifact of artifacts) {
+		assertContained(root, path.join(root, artifact.path), fs, "selected artifact");
+		const issues = validateCatalogContent(target, artifact.content);
+		if (issues.length > 0) throw new Error(formatCatalogIssues(artifact.path, issues));
+	}
 	const conflicts = [];
 	for (const entry of planned) for (const artifact of entry.artifacts) {
 		const output = path.join(root, artifact.path);
@@ -2405,6 +3001,66 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 	return results;
 }
 //#endregion
+//#region src/marketplace/validate.ts
+/** A `./`-prefixed source names a directory inside the repository, and Claude Code resolves it
+*  against the directory holding `.claude-plugin/`. A source pointing nowhere passes every schema
+*  check and still installs nothing, so the on-disk check belongs here rather than in the rules. */
+function checkSources(root, fs, catalog) {
+	if (typeof catalog !== "object" || catalog === null) return [];
+	const plugins = catalog.plugins;
+	if (!Array.isArray(plugins)) return [];
+	const issues = [];
+	plugins.forEach((entry, index) => {
+		if (typeof entry !== "object" || entry === null) return;
+		const source = entry.source;
+		const location = typeof source === "string" ? source : typeof source === "object" && source !== null ? source.path : void 0;
+		if (typeof location !== "string" || !location.startsWith("./")) return;
+		if (!fs.exists(path.join(root, location))) issues.push({
+			path: `plugins[${index}].source`,
+			message: `points at "${location}", which does not exist`
+		});
+	});
+	return issues;
+}
+/** Checks the catalogs a repository carries against the shape each runtime loads. Reads only; it
+*  repairs nothing, because a catalog someone hand-edited is theirs to correct. */
+function validateMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
+	const root = path.resolve(rootInput);
+	return (opts.targets && opts.targets.length > 0 ? [...new Set(opts.targets)] : [
+		"claude",
+		"codex",
+		"copilot",
+		"cursor"
+	]).map((target) => {
+		const relative = TARGET_CATALOG_PATHS[target];
+		const file = path.join(root, relative);
+		if (!fs.exists(file)) return {
+			target,
+			path: relative,
+			status: opts.required ? "invalid" : "missing",
+			issues: opts.required ? [{
+				path: "",
+				message: "no catalog at this path"
+			}] : []
+		};
+		const content = fs.read(file);
+		const issues = [...validateCatalogContent(target, content), ...parseAndCheckSources(root, fs, content)];
+		return {
+			target,
+			path: relative,
+			status: issues.length === 0 ? "valid" : "invalid",
+			issues
+		};
+	});
+}
+function parseAndCheckSources(root, fs, content) {
+	try {
+		return checkSources(root, fs, JSON.parse(content));
+	} catch {
+		return [];
+	}
+}
+//#endregion
 //#region src/marketplace/cli.ts
 function targetsFromOptions(opts) {
 	const targets = [
@@ -2443,8 +3099,36 @@ function initCommand() {
 		}
 	});
 }
+function validateCommand() {
+	return new Command("validate").description("Check the repository-local marketplace catalogs against the schema each runtime loads").option("--claude", "Validate the Claude marketplace catalog").option("--codex", "Validate the Codex marketplace catalog").option("--copilot", "Validate the Copilot marketplace catalog").option("--cursor", "Validate the Cursor marketplace catalog").option("--required", "Treat a selected target with no catalog as a failure").option("--format <format>", "Output format: toon or json (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin marketplace validate --claude\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 = validateMarketplace(resolveRoot(opts.root), {
+				targets: targetsFromOptions(opts),
+				required: opts.required
+			});
+			output(results, {
+				targets: results.map((row) => ({
+					target: row.target,
+					status: row.status,
+					path: row.path,
+					issues: row.issues.length
+				})),
+				summary: `${results.filter((row) => row.status === "invalid").length} invalid of ${results.length}`
+			});
+			for (const row of results.filter((row) => row.status === "invalid")) {
+				process.stderr.write(formatCatalogIssues(row.path, row.issues));
+				process.stderr.write("\n");
+			}
+			if (results.some((row) => row.status === "invalid")) process.exitCode = 1;
+		} 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());
+	return new Command("marketplace").description("Generate repository-local marketplace metadata").addCommand(initCommand()).addCommand(validateCommand());
 }
 //#endregion
 //#region src/prepare/fs.ts