universal-plugin 0.6.0 → 0.7.0

package/dist/cli.mjs

@@ -911,6 +911,145 @@ 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`. */
@@ -921,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}`);
@@ -977,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: [],
@@ -993,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);
@@ -1010,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"
@@ -1025,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})`);
@@ -1040,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,
@@ -1139,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) => {
@@ -1184,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);
@@ -1238,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) => {
@@ -1276,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`);
@@ -1319,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, "\\$&");
@@ -1957,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
@@ -2034,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);
@@ -2055,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"
@@ -2097,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),

package/governances/plugin-design.md

@@ -245,6 +245,20 @@ ln -sf .mcp.json mcp.json
 
 If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattributes`. MCP server startup failures are non-fatal.
 
+### Pinning a self-published server to the plugin version
+
+A plugin whose MCP server is its own npm package writes an unpinned invocation — `{"command": "npx", "args": ["-y", "my-server", "mcp"]}` — and a consumer on plugin 1.4.0 then gets 1.4.0's skills alongside whatever `npx` resolves as latest for the server. Mark the entry and `build` stamps the version on:
+
+```json
+{ "command": "npx", "args": ["-y", "my-server", "mcp"], "pinToPluginVersion": true }
+```
+
+- **The marker is required.** `build` never name-matches — 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.
+- **The marker never reaches a runtime.** It is a build directive, not part of any vendor's schema, so `build` strips it from every derived manifest and derived `mcp.json`. The authored files are left as written.
+- An already-pinned specifier is **overwritten** with the manifest version, and the build warns naming the version it replaced. Do not hand-pin a marked entry.
+- A marked entry the build cannot pin — the `command` is not `npx`/`upx`, the manifest declares no `version`, or `args` carry no package specifier — is warned about and left alone; the build stays green.
+- `copilot-cli` reads the canonical manifest directly, so it has no derived manifest to receive the pin; the build warns rather than pretending otherwise.
+
 ## Environment Variable Mapping
 
 | Canonical | Claude Code | Cursor | Codex | Copilot CLI |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -30,9 +30,11 @@
     "dist",
     "governances",
     "plugin.json",
+    "schema",
     ".claude-plugin",
     ".cursor-plugin",
     ".codex-plugin",
+    "com.github.copilot",
     "skills",
     "agents"
   ],

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/schema/README.md

@@ -0,0 +1,10 @@
+# Vendored schemas
+
+`claude-code-marketplace.json` is the official Claude Code marketplace schema, fetched verbatim from
+<https://json.schemastore.org/claude-code-marketplace.json> (the copy generated 2026-04-23) on
+2026-08-19.
+
+It ships nowhere: `package.json` `files` does not list this directory. It exists so
+`src/marketplace/validation.schema.test.ts` can hold this project's catalog rules against the
+runtime's own schema without reaching the network in a test, and so a re-fetch is a reviewable diff.
+Re-fetch it when Claude Code's catalog shape moves, then run the tests.