universal-plugin 0.17.1 → 0.18.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.17.1",
+	"version": "0.18.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/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.17.1",
+	"version": "0.18.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/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.17.1",
+	"version": "0.18.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/CHANGELOG.md

@@ -1,5 +1,21 @@
 # universal-plugin
 
+## 0.18.0
+
+### Minor Changes
+
+- 760b3d7: `doctor` checks semantic-release wiring. It reports `semantic-release-no-stamp` when the semantic-release config has no `@semantic-release/exec` `prepareCmd` running `plugin version`, and `semantic-release-npm-unshipped` when a plugin that ships to no npm package still runs `@semantic-release/npm`, listed or through the default plugins list.
+- c7739a2: The `init-universal-plugin` skill now wires release-it and release-please when the survey finds them or the user picks them, once the user approves. For release-it it adds an `after:bump` hook running `plugin version ${version}`, sets `"npm": false` for a plugin that ships to no npm package, and offers to tag the current commit with the plugin's version when the repository has no tag, since release-it then reads the current version from the tag. For release-please it writes `release-please-config.json` (`release-type: simple` with an `extra-files` entry for `plugin.json`, or `release-type: node` for an npm package) and seeds `.release-please-manifest.json` with the current version, and it hands the user the workflow step that restamps the release PR. `plugin init` gets no new flag.
+- 9f5f59a: The `init-universal-plugin` skill now wires semantic-release when the survey finds it or the user picks it. Once the user approves, it adds `@semantic-release/exec` running `plugin version ${nextRelease.version}` in `prepare`, and `@semantic-release/git` to commit the stamped files back. For a plugin that ships to no npm package it drops `@semantic-release/npm`. For release-it and release-please, the skill names the stamp each tool must call. The wiring stays in the skill, and `plugin init` gets no new flag.
+- 11c42a6: A plugin that ships to no npm package can now be released with changesets. In a changesets repository with no `package.json` at the plugin root, `plugin init` writes a minimal private one (`name`, `"private": true`, `version`), wires the root `version` script, and adds `"release": "changeset publish"`; `--no-changesets` opts out. `plugin version --from-package` with no package in a changesets repository names that `package.json` and the `privatePackages` setting. `doctor` reports `changesets-no-package`, `changesets-private-untagged`, and `changesets-no-publish-script`.
+- fa31d36: release-it is now a documented release model. With `"npm": false` release-it reads the version from the latest git tag and needs no `package.json`; an `after:bump` hook running `universal-plugin plugin version ${version}` stamps it before the release commit and tag. `doctor` reports `release-it-no-stamp` for a release-it config with no hook running `plugin version`.
+- bea7278: `doctor` reports `release-please-restamp-no-ci` when a workflow pushes the `--from-manifest` restamp with the default `GITHUB_TOKEN`. That push starts no workflow run, so the release PR's checks never run on its head commit and a required check blocks the merge. The `version` skill's release-please workflow now mints a GitHub App token with `actions/create-github-app-token` and passes it to release-please and to `actions/checkout`.
+- 8e20a28: A plugin that ships to no npm package can now be released with release-please. `plugin version --from-manifest` restamps every place at the version `plugin.json` already holds, for a CI step on the release PR after `extra-files` bumps `plugin.json`; it is refused where `packagePath` is declared. `doctor` reports `release-please-no-restamp` when a release-please config bumps `plugin.json` and no workflow runs `plugin version`. The `version` skill gives the config and the workflow.
+
+### Patch Changes
+
+- 7e8b2e1: `doctor` no longer reports `unreleased-content` for a non-npm plugin that a release tool versions. A plugin released with changesets (through a private `package.json`), release-please (its config bumps `plugin.json`), semantic-release, or release-it is skipped like a plugin that declares `packagePath`, because the tool picks the next number at release time.
+
 ## 0.17.1
 
 ### Patch Changes

package/dist/cli.mjs

@@ -8608,10 +8608,31 @@ function ownPackage(state) {
 		json: state.rootPackageJson ?? null
 	};
 }
+/** Changesets releases only what has a `package.json`, so a plugin that ships to no npm package
+*  needs a private one to carry its version (#234). Names the file and the config that makes
+*  `changeset publish` tag it. */
+function changesetsPackageHint(state) {
+	const name = typeof state.manifest?.name === "string" ? state.manifest.name : "<plugin-name>";
+	const version = typeof state.manifest?.version === "string" ? state.manifest.version : "0.0.0";
+	return [
+		"changesets releases only a package, so a plugin that is not published to npm needs a private package.json at the plugin root:",
+		`  ${JSON.stringify({
+			name,
+			private: true,
+			version
+		})}`,
+		"and .changeset/config.json needs \"privatePackages\": { \"version\": true, \"tag\": true } so changeset publish tags the release.",
+		"plugin init writes the package.json when it finds .changeset/."
+	].join("\n");
+}
 /** Reads the version a release tool already wrote into the package. */
 function versionFromPackage(state) {
 	const pkg = ownPackage(state);
-	if (pkg.json === null) throw new Error(state.packagePath === null ? "No package.json to read the version from: packagePath is not set in .agents/universal-plugin.json and the plugin root has no package.json" : `No package.json found at packagePath "${state.packagePath}"`);
+	if (pkg.json === null) {
+		if (state.packagePath !== null) throw new Error(`No package.json found at packagePath "${state.packagePath}"`);
+		const message = "No package.json to read the version from: packagePath is not set in .agents/universal-plugin.json and the plugin root has no package.json";
+		throw new Error(state.changesets ? `${message}\n${changesetsPackageHint(state)}` : message);
+	}
 	const version = pkg.json["version"];
 	if (typeof version !== "string" || version.length === 0) throw new Error(`No version found in ${pkg.path}`);
 	if (version === "0.0.0-development") throw new Error(`${pkg.path} holds the placeholder ${UNSTAMPED_VERSION} — pass the release's version explicitly (plugin version \${nextRelease.version})`);
@@ -8619,15 +8640,33 @@ function versionFromPackage(state) {
 	if (valid === null) throw new Error(`Version "${version}" in ${pkg.path} is not valid semver`);
 	return valid;
 }
-/** Picks the number. Exactly one source: a bump argument or `--from-package`. Under ADR-0010 §2 a
+/** Reads the version a release tool already wrote into the canonical manifest (#238). Under a
+*  declared `packagePath` the package owns the number, so the manifest is not a source there. */
+function versionFromManifest(state, from) {
+	if (state.packagePath !== null) {
+		const pkg = joinRelative(state.packagePath, "package.json");
+		throw new Error(`packagePath is declared, so ${pkg} owns the number, not plugin.json — run plugin version --from-package`);
+	}
+	if (from === null) throw new Error("plugin.json has no version to restamp — pass an explicit version (e.g. 0.1.0) to set the first one");
+	if (from === "0.0.0-development") throw new Error(`plugin.json holds the placeholder ${UNSTAMPED_VERSION} — pass the release's version explicitly`);
+	const valid = import_semver.valid(from);
+	if (valid === null) throw new Error(`Version "${from}" in plugin.json is not valid semver`);
+	return valid;
+}
+/** Picks the number. Exactly one source: a bump argument, `--from-package`, or `--from-manifest`. Under ADR-0010 §2 a
 *  plugin with `packagePath` gets its number from the package, so a release type there is refused —
 *  the explicit and `--from-package` forms stay, because release tools call them. */
 function resolveVersion(state, from, opts) {
+	if (opts.fromPackage && opts.fromManifest) throw new Error("Pass --from-package or --from-manifest, not both");
+	if (opts.fromManifest) {
+		if (opts.bump !== void 0) throw new Error(`Pass a version or --from-manifest, not both (got "${opts.bump}")`);
+		return versionFromManifest(state, from);
+	}
 	if (opts.fromPackage) {
 		if (opts.bump !== void 0) throw new Error(`Pass a version or --from-package, not both (got "${opts.bump}")`);
 		return versionFromPackage(state);
 	}
-	if (opts.bump === void 0) throw new Error(`Pass a release type (${RELEASE_TYPES.join(", ")}), an explicit version, or --from-package`);
+	if (opts.bump === void 0) throw new Error(`Pass a release type (${RELEASE_TYPES.join(", ")}), an explicit version, --from-package, or --from-manifest`);
 	if (state.packagePath !== null && isReleaseType(opts.bump)) {
 		const pkg = joinRelative(state.packagePath, "package.json");
 		throw new Error(`packagePath is declared, so the release picks the number — bump ${pkg} with your release tool (e.g. changeset version), then run plugin version --from-package`);
@@ -8896,6 +8935,10 @@ function gatherMcpFiles(root, declaration) {
 	}
 	return files;
 }
+/** Whether `.changeset/` sits at the plugin root or at the repository root above it. */
+function hasChangesets(root) {
+	return [root, gitToplevel(root)].some((dir) => dir !== void 0 && fs$1.existsSync(path$1.join(dir, ".changeset")));
+}
 function toRelative(root, abs) {
 	return path$1.relative(root, abs).split(path$1.sep).join("/");
 }
@@ -8921,7 +8964,8 @@ const realVersionFs = {
 			})),
 			workspace: Object.fromEntries(discoverWorkspace(root)),
 			mcpFiles: gatherMcpFiles(root, uext["mcpServers"]),
-			pinsMapExists: fs$1.existsSync(path$1.join(root, PINS_MAP_PATH))
+			pinsMapExists: fs$1.existsSync(path$1.join(root, PINS_MAP_PATH)),
+			changesets: hasChangesets(root)
 		};
 	},
 	apply(root, plan) {
@@ -9164,9 +9208,22 @@ function gatherChangesets(root, repo) {
 	if (!fs$1.existsSync(path$1.join(workspace, ".changeset"))) return void 0;
 	return {
 		pluginPath,
-		packageJson: readJson$1(packageJsonPath(workspace))
+		packageJson: readJson$1(packageJsonPath(workspace)),
+		config: readJsonSafe(path$1.join(workspace, ".changeset", "config.json"))
 	};
 }
+function readJsonSafe(file) {
+	try {
+		return readJson$1(file);
+	} catch {
+		return null;
+	}
+}
+/** The version an existing `plugin.json` carries, which a new private package.json is seeded from. */
+function readManifestVersion(root) {
+	const version = readJsonSafe(manifestPath(root))?.version;
+	return typeof version === "string" && version !== "" ? version : void 0;
+}
 function writeJson(file, value) {
 	const existing = fs$1.existsSync(file) ? fs$1.readFileSync(file, "utf8") : void 0;
 	fs$1.writeFileSync(file, formatJson(value, {
@@ -9179,6 +9236,7 @@ const realInitFs = {
 		const repo = gatherRepo(root);
 		return {
 			manifestExists: fs$1.existsSync(manifestPath(root)),
+			manifestVersion: readManifestVersion(root),
 			packageJson: readJson$1(packageJsonPath(root)),
 			repo,
 			changesets: gatherChangesets(root, repo)
@@ -9284,6 +9342,89 @@ function wireChangesets(pkg, pluginPath, cliVersion) {
 	};
 	return { content: next };
 }
+const CHANGESET_PUBLISH = "changeset publish";
+/** The version a private package starts at when the manifest carries none to seed it from. */
+const FIRST_VERSION = "0.0.0";
+/** The package.json a plugin that ships to no npm package needs before changesets can release it
+*  (#234). Changesets finds only packages, and `@changesets/apply-release-plan` always writes
+*  `<dir>/package.json`, so this file is what carries the version. `private` keeps
+*  `changeset publish` to a git tag; no `files`, `main`, or `exports`, because nothing is packed. */
+function privatePackage(name, version) {
+	return {
+		name,
+		private: true,
+		version
+	};
+}
+/** Adds `"release": "changeset publish"`, the script changesets/action runs as its publish step.
+*  For a private package it creates the git tag the GitHub release hangs on. A custom `release`
+*  script is left alone with a note. Returns `null` content when nothing changes. */
+function wireReleaseScript(pkg) {
+	const scripts = typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {};
+	const script = typeof scripts.release === "string" ? scripts.release : void 0;
+	if (script?.includes(CHANGESET_PUBLISH)) return { content: null };
+	if (script !== void 0) return {
+		content: null,
+		note: `changesets: the root "release" script is custom; make sure it runs "${CHANGESET_PUBLISH}" so a release is tagged`
+	};
+	return { content: {
+		...pkg,
+		scripts: {
+			...scripts,
+			release: CHANGESET_PUBLISH
+		}
+	} };
+}
+/** Whether `.changeset/config.json` has changesets bump and tag private packages. Changesets bumps
+*  them by default but tags them only when `privatePackages.tag` is `true`. */
+function tagsPrivatePackages(config) {
+	const setting = config?.privatePackages;
+	if (typeof setting !== "object" || setting === null) return false;
+	const { version, tag } = setting;
+	return version !== false && tag === true;
+}
+/** Wires a plugin that ships to no npm package for a changesets release: a private package.json at
+*  the plugin root, and the `version` and `release` scripts at the workspace root. Appends to `rows`
+*  and `notes` in place. */
+function planPrivateRelease(opts, name, version, changesets, rows, notes) {
+	const sameFile = changesets.pluginPath === "";
+	let packageJson = privatePackage(name, version);
+	rows.push({
+		path: "package.json",
+		action: "created"
+	});
+	if (sameFile) packageJson = {
+		...packageJson,
+		scripts: { version: CHANGESET_VERSION }
+	};
+	else notes.push(`changesets: ${changesets.pluginPath}/package.json must be a workspace package (pnpm-workspace.yaml or "workspaces") for changesets to release it`);
+	let workspacePackageJson = null;
+	const rootPkg = sameFile ? packageJson : changesets.packageJson;
+	if (rootPkg === null) notes.push(`changesets: no package.json at the workspace root to wire; add a "version" script running "${CHANGESET_VERSION} && ${syncVersionCommand(changesets.pluginPath)}" and a "release" script running "${CHANGESET_PUBLISH}"`);
+	else {
+		const versioned = wireChangesets(rootPkg, changesets.pluginPath, opts.cliVersion);
+		if (versioned.note) notes.push(versioned.note);
+		const released = wireReleaseScript(versioned.content ?? rootPkg);
+		if (released.note) notes.push(released.note);
+		const wired = released.content ?? versioned.content;
+		if (wired && sameFile) packageJson = wired;
+		else if (wired) {
+			workspacePackageJson = {
+				path: `${changesets.pluginPath.split("/").map(() => "..").join("/")}/package.json`,
+				content: wired
+			};
+			rows.push({
+				path: workspacePackageJson.path,
+				action: "updated"
+			});
+		}
+	}
+	if (!tagsPrivatePackages(changesets.config)) notes.push("changesets: set \"privatePackages\": { \"version\": true, \"tag\": true } in .changeset/config.json so changeset publish tags each release");
+	return {
+		packageJson,
+		workspacePackageJson
+	};
+}
 /** The local marketplace a repository carries is named after the repository, not after the plugin:
 *  the catalog sits at the repository root and lists every plugin the repository develops. `-local`
 *  separates it from a published marketplace of the same plugins. */
@@ -9356,9 +9497,12 @@ function planCatalogs(state, opts, manifest, notes) {
 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);
+	const name = opts.name ?? rootDirName;
+	const manifest = buildManifest(name, opts.vendors);
 	const packageVersion = state.packageJson?.version;
 	if (opts.npm && typeof packageVersion === "string" && packageVersion !== "") manifest.version = packageVersion;
+	const privateVersion = !opts.npm && opts.changesets !== false && state.changesets && state.packageJson === null ? state.manifestVersion ?? FIRST_VERSION : void 0;
+	if (privateVersion !== void 0) manifest.version = privateVersion;
 	const dirs = opts.scaffold ? [...SCAFFOLD_DIRS] : [];
 	const rows = [{
 		path: "plugin.json",
@@ -9384,7 +9528,7 @@ function planInit(state, opts, rootDirName, resolveShippedPaths) {
 		});
 	}
 	let workspacePackageJson = null;
-	const changesets = state.changesets;
+	const changesets = opts.changesets === false ? void 0 : state.changesets;
 	if (opts.npm && changesets) {
 		const sameFile = changesets.pluginPath === "";
 		const rootPkg = sameFile ? packageJson : changesets.packageJson;
@@ -9405,6 +9549,11 @@ function planInit(state, opts, rootDirName, resolveShippedPaths) {
 			}
 		}
 	}
+	if (privateVersion !== void 0 && changesets) {
+		const wired = planPrivateRelease(opts, name, privateVersion, changesets, rows, notes);
+		packageJson = wired.packageJson;
+		workspacePackageJson = wired.workspacePackageJson;
+	}
 	const created = rows.filter((r) => r.action === "created").length;
 	const updated = rows.filter((r) => r.action === "updated").length;
 	const unchanged = rows.filter((r) => r.action === "unchanged").length;
@@ -9431,7 +9580,7 @@ function collect$1(value, previous) {
 }
 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$1, []).option("--scaffold", "Create the standard skills/ agents/ references/ commands/ directories").option("--force", "Overwrite an existing plugin.json").option("--yes", "Non-interactive (compatibility no-op; init never prompts)").option("--npm", "Wire package.json to ship the plugin (files, version; changesets version sync)").option("--no-marketplace", "Skip the repository's local marketplace catalogs").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) => {
+	cmd.option("--name <name>", "Plugin name (default: the root directory name)").option("--vendor <id>", "Target vendor; repeatable", collect$1, []).option("--scaffold", "Create the standard skills/ agents/ references/ commands/ directories").option("--force", "Overwrite an existing plugin.json").option("--yes", "Non-interactive (compatibility no-op; init never prompts)").option("--npm", "Wire package.json to ship the plugin (files, version; changesets version sync)").option("--no-marketplace", "Skip the repository's local marketplace catalogs").option("--no-changesets", "Skip the changesets release wiring (private package.json, version and release scripts)").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), {
@@ -9441,6 +9590,7 @@ function initCommand$1(deps = { fs: realInitFs }) {
 				force: Boolean(opts.force),
 				npm: Boolean(opts.npm),
 				marketplace: opts.marketplace !== false,
+				changesets: opts.changesets !== false,
 				cliVersion: deps.version
 			}, path$1.basename(root), (vendor) => VENDOR_SHIPPED_PATHS[vendor] ?? []);
 			deps.fs.apply(root, plan);
@@ -18114,12 +18264,13 @@ function prepareCommand() {
 //#region src/version/cli.ts
 function versionCommand(deps = { fs: realVersionFs }) {
 	const cmd = new Command("version").description("Stamp the plugin version into every file that carries one").argument("[bump]", `Release type (${RELEASE_TYPES.join(", ")}) or an explicit version (1.4.0)`);
-	cmd.option("--from-package", "Take the version the package's package.json already holds (changesets, release-please)").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", [
+	cmd.option("--from-package", "Take the version the package's package.json already holds (changesets, release-please)").option("--from-manifest", "Restamp every place with the version plugin.json already holds (release-please extra-files)").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", [
 		"",
 		"Examples:",
 		"  $ universal-plugin plugin version minor            # plain repository: the author picks",
 		"  $ universal-plugin plugin version 1.4.0            # semantic-release: prepareCmd",
-		"  $ universal-plugin plugin version --from-package   # changesets / release-please",
+		"  $ universal-plugin plugin version --from-package   # changesets / release-please, npm package",
+		"  $ universal-plugin plugin version --from-manifest  # release-please, plugin.json bumped by extra-files",
 		""
 	].join("\n")).action((bump, opts) => runVersion(bump, opts, deps.fs));
 	return cmd;
@@ -18132,6 +18283,7 @@ function runVersion(bump, opts, versionFs = realVersionFs) {
 		const plan = planVersion(versionFs.gather(root), {
 			...bump === void 0 ? {} : { bump },
 			fromPackage: Boolean(opts.fromPackage),
+			fromManifest: Boolean(opts.fromManifest),
 			...opts.preid === void 0 ? {} : { preid: opts.preid },
 			force: Boolean(opts.force)
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.17.1",
+	"version": "0.18.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/skills/adopt-upx/scripts/rewrite-upx.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/rewrite-upx.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/adopt-upx/scripts/rewrite-upx.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.18.0","entry":"skills/adopt-upx/scripts/rewrite-upx.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 //#region src/skill-scripts/rewrite-upx.ts

package/skills/build-plugin/SKILL.md

@@ -47,7 +47,7 @@ node scripts/build.mjs --root <plugin-root>
 
 Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI the project installed
 (`pnpm exec universal-plugin`), else the CLI pinned to the version this skill shipped with
-(`npx universal-plugin@0.17.1`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
+(`npx universal-plugin@0.18.0`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
 must name the directory that holds the canonical `plugin.json`.
 
 The command never prompts, so it is safe to run unattended.

package/skills/build-plugin/scripts/build.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/build-plugin/scripts/build.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.18.0","entry":"skills/build-plugin/scripts/build.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/doctor-universal-plugin/SKILL.md

@@ -95,6 +95,14 @@ Each `code` below is what the script emits.
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
 | `package-path-unknown` | the CLI could not report `packagePath` (a version too old to read it), so `version-drift` and `unreleased-content` were skipped rather than guessed | upgrade universal-plugin |
 | `misplaced-package-path` | `plugin.json` declares `packagePath` under `extensions["org.cyberuni.universal-plugin"]`, where the CLI never reads it — the plugin is silently treated as not shipping to npm | move it to `.agents/universal-plugin.json`, relative to the plugin root |
+| `changesets-no-package` | the repository is released with changesets, the plugin ships to no npm package, and its root has no `package.json` — changesets releases only a package, so `changeset version` and `changeset publish` fail | `/universal-plugin:init-universal-plugin` (pnpm install: `pnpm-universal-plugin-init-universal-plugin`) — `plugin init` writes a private `package.json` |
+| `changesets-private-untagged` | a non-npm plugin in a changesets repository, and `.changeset/config.json` does not set `"privatePackages": { "version": true, "tag": true }` — `changeset publish` tags no private package, so no release is made | set `privatePackages` in `.changeset/config.json` |
+| `changesets-no-publish-script` | a non-npm plugin in a changesets repository, and a workflow runs `changesets/action` with no `publish-script` (`publish` in v1) — after the Version Packages PR merges the action does nothing, so no tag or GitHub release is made | add `publish-script: pnpm release` to the step, with a `release` script running `changeset publish` |
+| `release-please-no-restamp` | the plugin ships to no npm package, `release-please-config.json` bumps its `plugin.json` through `extra-files`, and no workflow runs `plugin version` — release-please runs no command before its release commit, so the release PR leaves the vendor manifests, catalogs, skill pins and compiled scripts on the old version | add a workflow step on the release PR branch running `universal-plugin plugin version --from-manifest` and pushing the stamped files — `/universal-plugin:version` (pnpm install: `pnpm-universal-plugin-version`) has the workflow |
+| `release-please-restamp-no-ci` | a workflow restamps the release PR with `plugin version --from-manifest` and pushes with the default `GITHUB_TOKEN` — that push starts no workflow run, so the PR's checks never run on its head commit and a required check blocks the merge. A `workflow_dispatch` re-run does not fix it: its checks do not count toward a required check | mint a GitHub App token with `actions/create-github-app-token` and pass it as `token:` to `release-please-action` and `actions/checkout` — `/universal-plugin:version` (pnpm install: `pnpm-universal-plugin-version`) has the workflow |
+| `release-it-no-stamp` | a release-it config (`.release-it.*`, or the `release-it` key of `package.json`) has no hook running `plugin version` — release-it commits and tags the release with `plugin.json` and the vendor manifests still on the previous version | add `"hooks": { "after:bump": "universal-plugin plugin version ${version}" }` to the config |
+| `semantic-release-no-stamp` | a semantic-release config (`.releaserc*`, `.config/releaserc*`, `release.config.*`, or the `release` key of `package.json`) has no `@semantic-release/exec` `prepareCmd` running `plugin version` — the release is tagged with `plugin.json`, the vendor manifests and the catalogs still on the previous version | add `["@semantic-release/exec", { "prepareCmd": "universal-plugin plugin version ${nextRelease.version}" }]` before `@semantic-release/git` — `/universal-plugin:init-universal-plugin` (pnpm install: `pnpm-universal-plugin-init-universal-plugin`) wires it |
+| `semantic-release-npm-unshipped` | the plugin ships to no npm package, and its semantic-release config lists `@semantic-release/npm` or relies on the default `plugins` list, which includes it — with no `package.json` the release fails (`ENOPKG`), and with one the plugin still rewrites its version | remove `@semantic-release/npm`, writing the `plugins` list out if the config relies on the defaults — `/universal-plugin:init-universal-plugin` (pnpm install: `pnpm-universal-plugin-init-universal-plugin`) wires it |
 | `unparsable-manifest` | root `plugin.json` is not valid JSON | fix the syntax error |
 | `invalid-catalog` | a marketplace catalog — at the repository root, or at a `--marketplace-root` clone — is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` (pnpm install: `pnpm-universal-plugin-marketplace`) |
 | `marketplace-root-missing` | a `--marketplace-root` path does not exist, so it could not be checked at all | clone the marketplace repository, or fix the path |
@@ -172,7 +180,7 @@ it does not, offer to add it — ask first, because both are the user's files:
   semantic-release bot opens.
 
 Use the locked `universal-plugin` from the repository's devDependencies when it has one; otherwise
-`npx universal-plugin@0.17.1`, pinned. This check matters most where the release tool picks the
+`npx universal-plugin@0.18.0`, pinned. This check matters most where the release tool picks the
 number, because nothing else runs between that bump and publish.
 
 ## Unreleased content
@@ -187,9 +195,13 @@ The script compares the shipped paths — the canonical manifest, the skills dir
 emits `unreleased-content` for anything committed since. Uncommitted work is not reported; it has not
 shipped.
 
-Two cases are deliberately silent. A plugin that declares `packagePath` is skipped, because there the
-release picks the number ([ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md) §2) and content waiting ahead of the last released version is the
-normal state of a branch. A tree with no git history is skipped rather than guessed at.
+Two cases are deliberately silent. A plugin whose release picks the number is skipped, because
+content waiting ahead of the last released version is the normal state of a branch there
+([ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md) §6). That is a plugin that declares `packagePath`, or a plugin a release tool versions:
+changesets (`.changeset/` and a private or absent plugin-root `package.json`), release-please (its
+config bumps this `plugin.json` through `extra-files`), semantic-release (`.releaserc*`,
+`release.config.*`, or a `release` key in `package.json`), or release-it (a `.release-it.*` file, or a
+`release-it` key in `package.json`). A tree with no git history is skipped rather than guessed at.
 
 The repair is the bump, and it belongs to `/universal-plugin:version` (pnpm install: `pnpm-universal-plugin-version`). Judge first whether the change
 is meant to ship — content that is still being worked on is not a finding to act on.