universal-plugin 0.12.2 → 0.13.0

package/skills/version/README.md

@@ -1,36 +1,42 @@
 # version skill
 
-Move the version a plugin releases under, keeping every file that carries one in sync.
+Stamp the version a plugin releases under into every file that carries one.
 
-## The two authored numbers
+## Derive versus stamp
 
-A plugin's version appears in up to five places; only two are authored — the canonical `plugin.json`
-and, when `packagePath` is declared, that `package.json`. The vendor manifests, the local marketplace
-catalogs, and the `npx`/`upx` pins inside `skills/**/SKILL.md` are all derived.
+`plugin build` derives the vendor manifests from `plugin.json` and never decides a version.
+`plugin version` stamps: one call writes the number into the canonical `plugin.json`, the
+`packagePath` `package.json`, every `npx`/`upx <pkg>@<version>` pin in the skills, `.plugin/pins.json`,
+and each `mcpServers` entry marked `pinToPluginVersion`, then re-derives through `plugin build`.
 
-That is why nothing here is hand-edited: editing one authored file leaves the other stale, and every
-derived artifact with it. A consumer's plugin cache is keyed by version, so a content change without
-a matching bump is invisible to them.
+That is why nothing here is hand-edited. A consumer's plugin cache is keyed by version, so a content
+change without a matching bump is invisible to them.
 
-## Two release models
+## Three sources for the number
 
-The first question the skill asks is whether the repository uses changesets.
+| Source | Call | Used by |
+|---|---|---|
+| Author bump | `plugin version minor` | Plain repositories |
+| Explicit number | `plugin version 1.4.0` | semantic-release (`@semantic-release/exec` `prepareCmd`) |
+| The package's `package.json` | `plugin version --from-package` | changesets, release-please |
 
-- **With changesets** — the number is decided by the release, not by this skill. Add a changeset, let
-  the release run, and `publish sync-version` carries the released number into the canonical
-  manifest and re-derives the vendor manifests. With `--no-build`, `plugin build` is the next step.
-- **Without** — `plugin version <bump>` is the whole step. `scripts/version.mjs` runs it from the CLI
-  shipped beside the skill, so nothing is downloaded.
+With `packagePath` declared, a release type is refused: bump the package with the release tool, then
+run `--from-package`. The skill checks for `.changeset/` and `packagePath` before it picks a call.
 
-Running `plugin version` in a changesets repository would decide a number changesets is about to
-decide again. The skill checks for `.changeset/` before anything else.
+semantic-release stamps files that exist only in the npm package unless `@semantic-release/git`
+commits them back. Git-sourced installs read `plugin.json` from the repository, so they need that
+commit-back.
+
+`plugin bundle` and `publish sync-version` are deprecated aliases and are removed in the next minor
+release.
 
 ## The part that is not automatable
 
 Which release type to use is a promise to consumers about what broke. The skill offers the semver
-reading — breaking → major, new behavior → minor, fix only → patch, adjusted for `0.x` — and asks
+reading (breaking → major, new behavior → minor, fix only → patch, adjusted for `0.x`) and asks
 rather than guessing.
 
 ## References
 
+- [ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md)
 - [`plugin version` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/version/README.md)

package/skills/version/SKILL.md

@@ -1,54 +1,82 @@
 ---
 name: version
-description: Use this skill to move a universal agent plugin's version — bump it, set an explicit one, cut a release number, or reconcile a version that drifted between the canonical plugin.json and its npm package.json. Handles both release models: a changesets repository, where the number is decided by the release and carried in with publish sync-version, and a plain repository, where plugin version does the whole move. Trigger on "bump the plugin version", "release a new version of this plugin", "set the plugin version to 1.0.0", "cut a patch release", or "the manifest and package.json versions disagree".
+description: Use this skill to move a universal agent plugin's version — bump it, set an explicit one, cut a release number, or reconcile a version that drifted between the canonical plugin.json and its npm package.json. Handles every release model: a plain repository, where the author picks the number, and a release tool (changesets, release-please, semantic-release) that decides it and hands it to plugin version to stamp everywhere. Trigger on "bump the plugin version", "release a new version of this plugin", "set the plugin version to 1.0.0", "cut a patch release", or "the manifest and package.json versions disagree".
 ---
 
 # Move a plugin's version
 
-Bump or set the version a plugin releases under, keeping every file that carries one in sync.
+Stamp the version a plugin releases under into every file that carries one.
 
-A plugin's version lives in up to five places, but only **two are authored** — the canonical root
-`plugin.json` and, when the project declares a `packagePath`, that `package.json`. The per-vendor
-manifests, the local marketplace catalogs, and the `npx`/`upx` pins inside `skills/**/SKILL.md` are
-all **derived**. So never hand-edit a version: editing one file leaves the other authored file and
-every derived artifact stale, and a consumer's plugin cache is keyed by version, so a content change
-without a matching bump is invisible to them.
+The seam is **derive versus stamp**. `plugin build` derives the vendor manifests from `plugin.json`
+and never decides a version. `plugin version` is the one command that decides where a number goes: a
+single call writes it into every place, then re-derives through `plugin build`. So never hand-edit a
+version. Editing one file leaves the rest stale, and a consumer's plugin cache is keyed by version, so
+a content change without a matching bump is invisible to them.
 
-## Step 0 — Does this repo use changesets?
+One call writes:
+
+- the canonical `plugin.json`, and the `packagePath` `package.json` when you pass a release type or an
+  explicit number;
+- every `npx`/`upx <pkg>@<version>` pin in the text files under the skills directory (SKILL.md, other
+  Markdown, json/yaml, and `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts`/`.sh`/`.py` scripts). The plugin's
+  own package moves to the new version, other pnpm-workspace CLIs to their workspace versions, and
+  external packages are left alone. A skill with `metadata.pin-exempt: true` is skipped;
+- `.plugin/pins.json`;
+- the version each compiled skill script (`scripts` in the extension) embeds in its header — only the
+  header moves;
+- each authored `mcpServers` entry marked `pinToPluginVersion: true`, inline or in the mcp file. The
+  marker stays.
+
+## Step 1 — Pick the source of the number
+
+Ask who decides the number. There are three sources, and the release model picks one:
+
+| Source | Call | Used by |
+|---|---|---|
+| Author bump | `plugin version minor` | Plain repositories, with no `packagePath` |
+| Explicit number | `plugin version 1.4.0` | semantic-release |
+| The package's `package.json` | `plugin version --from-package` | changesets, release-please |
 
 ```bash
 test -d .changeset && echo "changesets"
+cat .agents/universal-plugin.json   # is packagePath declared?
 ```
 
-**If it does**, the version number is decided by changesets, not by you. Add a changeset and let the
-release run — the repo's `version` script should already call `publish sync-version`, which carries
-the released number from `package.json` into the canonical manifest and re-derives the vendor
-manifests, the same way `plugin version` does:
+With `packagePath` declared, a release type (`patch`, `minor`, `major`, `pre*`) is **refused**: the
+package owns the number. Bump the package with the release tool, then run `--from-package`. An
+explicit number and `--from-package` stay allowed. `--from-package` reads `<packagePath>/package.json`,
+or the plugin root's `package.json` when no `packagePath` is declared, and refuses `0.0.0-development`.
 
-```bash
-npx universal-plugin publish sync-version
-```
+Wire a release tool once; after that the release runs the stamp for you:
+
+- **changesets.** Root `version` script: `changeset version && universal-plugin plugin version --from-package --root <plugin>`.
+  `init-universal-plugin --npm` writes it.
+- **release-please.** Run `universal-plugin plugin version --from-package` after the release PR
+  bumps the package.
+- **semantic-release.** Add `@semantic-release/exec` with
+  `prepareCmd: "universal-plugin plugin version ${nextRelease.version}"`.
 
-If the script passes `--no-build`, it must run `plugin build` next (`/universal-plugin:build-plugin`);
-otherwise the vendor manifests and `com.github.copilot/` keep the old version, and a consumer's
-plugin cache never re-extracts.
+In a changesets repository, add a changeset and let the release run. Do not run `plugin version minor`
+there: it would decide a number changesets is about to decide again.
 
-Do **not** run `plugin version` in a changesets repo — it would decide a number changesets is about
-to decide again.
+### semantic-release must commit the stamp back
 
-**If it does not**, `plugin version` is the whole release-number step. Continue below.
+The stamped files exist only in the npm package unless `@semantic-release/git` commits them back.
+Git-sourced installs (Copilot CLI, GitHub-hosted marketplaces) read `plugin.json` from the repository,
+so for those channels the commit-back is required. Without it they are unsupported. Set `assets` to
+`plugin.json`, the vendor manifests, `skills/**`, `.plugin/pins.json`, and the mcp file.
 
-## Step 1 — Move the version
+## Step 2 — Run it
 
 ```bash
-node scripts/version.mjs <bump>
+node scripts/version.mjs <bump-or-number>
+node scripts/version.mjs --from-package
 ```
 
-Resolve that path against this skill's own directory; it runs the CLI that shipped beside it, so
-nothing is downloaded. `npx universal-plugin plugin version <bump>` is the fallback. The command
-never prompts, so it is safe to run unattended once the release type is decided.
-
-`<bump>` is either a semver release type or an explicit version:
+Resolve that path against this skill's own directory; it runs the project's installed CLI
+(`pnpm exec universal-plugin`), else `npx universal-plugin@0.13.0` pinned to this skill's version.
+`universal-plugin plugin version` on the `PATH` is the fallback. The command never prompts, so it is safe to run unattended once the
+source is decided.
 
 | `<bump>` | From `1.2.3` you get |
 |---|---|
@@ -58,29 +86,29 @@ never prompts, so it is safe to run unattended once the release type is decided.
 | `prerelease --preid beta` | `1.2.4-beta.0` |
 | `2.0.0-rc.1` (explicit) | `2.0.0-rc.1` |
 
-Useful flags:
-
 | Flag | Effect |
 |---|---|
+| `--from-package` | Take the version the package's `package.json` already holds |
 | `--preid <id>` | Prerelease identifier for the `pre*` release types |
-| `--dry-run` | Print the plan, write nothing — run this first when unsure |
+| `--dry-run` | Print the plan, write nothing. Run this first when unsure |
 | `--force` | Allow a target that does not advance on the current version |
-| `--no-build` | Skip re-deriving the vendor manifests (you will run `plugin build` yourself) |
-| `--format json` | Machine-readable result: `from`, `to`, `written` |
+| `--no-build` | Skip re-deriving the vendor manifests (run `plugin build` yourself) |
+| `--format json` | Machine-readable result |
+| `--root <path>` | Plugin root directory |
 
-**Which release type?** That is the user's call, not the command's and not yours to guess — a
-version is a promise to consumers about what broke. If the user has not said, ask, and offer the
-semver reading of the change: breaking → `major`, new behavior → `minor`, fix only → `patch` (on a
-`0.x` plugin, breaking → `minor` and everything else → `patch`).
+**Which release type?** In a plain repository that is the user's call, not the command's and not yours
+to guess. A version is a promise to consumers about what broke. If the user has not said, ask, and
+offer the semver reading of the change: breaking → `major`, new behavior → `minor`, fix only →
+`patch` (on a `0.x` plugin, breaking → `minor` and everything else → `patch`).
 
-## Step 2 — Confirm what moved
+## Step 3 — Confirm what moved
 
 The command reports every file it wrote and every manifest it re-derived. Expect the canonical
-manifest, the `packagePath` `package.json` if one is declared, and one derived manifest per declared
-harness:
+manifest, the `packagePath` `package.json` for a release type or explicit number, the pinned skill
+files, `.plugin/pins.json`, and one derived manifest per declared harness:
 
 ```bash
-node scripts/version.mjs patch --format json
+node scripts/version.mjs --from-package --format json
 ```
 
 Default stdout is TOON, which is the machine contract this CLI documents; `--format json` is there
@@ -99,15 +127,19 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 | no version to bump from | the manifest has never carried a `version` | pass an explicit version (`plugin version 0.1.0`) to set the first one |
 | an unknown version or release type | the argument is neither a release type nor valid semver | use one of the values in the table above |
 | a target that does not advance | the requested version is not greater than the current one | pick a higher version, or pass `--force` if the user genuinely wants to move backward |
+| a release type under `packagePath` | the package owns the number | bump the package with the release tool, then `plugin version --from-package` |
+| `0.0.0-development` from `--from-package` | semantic-release's placeholder, not a release | pass the explicit number instead |
 | a missing `package.json` at `packagePath` | `.agents/universal-plugin.json` names a package directory that does not exist | fix `packagePath`, or create the package |
 
 ## Do not
 
-- **Hand-edit a `version` field.** Two authored files and every derived artifact fall out of sync.
+- **Hand-edit a `version` field.** The other places fall out of sync.
 - **Write a derived manifest.** `.claude-plugin/plugin.json` and its siblings belong to
   `plugin build`; the bump already re-derived them.
-- **Run `npm version`.** It knows only `package.json` and leaves the canonical manifest — the actual
-  source of truth — stale.
+- **Run `npm version`.** It knows only `package.json` and leaves the canonical manifest and the
+  skill pins stale.
+- **Use the deprecated commands.** `plugin bundle` and `publish sync-version` print a warning and are
+  removed in the next minor release. `sync-version` now runs `plugin version --from-package`.
 
 ## Related skills
 
@@ -115,11 +147,12 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 |------|-------|
 | Create, adopt, or change what the plugin declares | `init-universal-plugin` |
 | Re-derive the vendor manifests by hand | `build-plugin` |
-| Check whether the two authored versions agree | `doctor-universal-plugin` |
+| Check whether every place agrees (`unstamped`, `version-drift`) | `doctor-universal-plugin` |
 | Add a changeset for the change being released | `add-changeset` |
 | Refresh the repository's own marketplace catalogs after a bump | `marketplace` |
 | List the released plugin in the shared marketplace | `publish-plugin` |
 
 ## References
 
+- [ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md), the derive/stamp seam
 - Spec: [`plugin/version/`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/version/README.md)

package/skills/version/scripts/version.mjs

@@ -1,11 +1,52 @@
 #!/usr/bin/env node
-// Runs `universal-plugin plugin version` from the CLI that ships beside this skill, so a release
-// number never depends on a network fetch or on which version `npx` happens to resolve.
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-// <package>/skills/<skill>/scripts/version.mjs: four levels up is the package root.
-const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
-
-process.argv.splice(2, 0, 'plugin', 'version')
-await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))
+// 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.13.0","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.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
+*  library it inlines, reads it; universal-plugin depends on neither. */
+const SCRIPT_GLOBAL = "__SKILL_SCRIPT__";
+//#endregion
+//#region src/skill-scripts/cli-runner.ts
+/** The data `plugin build` embedded in this compiled script. */
+function skillScript() {
+	const data = globalThis[SCRIPT_GLOBAL];
+	if (data === void 0) throw new Error("this script runs only as compiled by `plugin build`");
+	return data;
+}
+/** Runs the universal-plugin CLI. A skill may be copied away from its package, so it never reaches
+*  for a CLI beside it: the project's installed CLI first, then the one pinned to this script's
+*  version, which `plugin version` stamps. */
+function runCli(args, options = {}) {
+	const { bin, package: pkg, version } = skillScript();
+	const name = bin ?? "universal-plugin";
+	if (spawnSync("pnpm", [
+		"exec",
+		name,
+		"--version"
+	], { encoding: "utf8" }).status === 0) return spawnSync("pnpm", [
+		"exec",
+		name,
+		...args
+	], {
+		encoding: "utf8",
+		...options
+	});
+	const pinned = `${pkg ?? "universal-plugin"}@${version ?? "latest"}`;
+	return spawnSync("npx", [pinned, ...args], {
+		encoding: "utf8",
+		...options
+	});
+}
+//#endregion
+//#region src/skill-scripts/run-cli.ts
+const script = skillScript();
+const command = Object.entries(script.commands).find(([, entry]) => entry === script.entry)?.[0];
+if (command === void 0) {
+	process.stderr.write(`${script.entry} declares no command in the scripts map\n`);
+	process.exit(1);
+}
+const result = runCli([...command.split(" "), ...process.argv.slice(2)], { stdio: "inherit" });
+process.exit(result.status ?? 1);
+//#endregion
+export {};