universal-plugin 0.17.0 → 0.18.0

package/skills/version/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 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".
+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, release-it) 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
@@ -34,11 +34,13 @@ Ask who decides the number. There are three sources, and the release model picks
 | 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 |
+| Explicit number | `plugin version 1.4.0` | semantic-release, release-it |
+| The package's `package.json` | `plugin version --from-package` | changesets, release-please with an npm package |
+| The canonical `plugin.json` | `plugin version --from-manifest` | release-please with no `package.json` (`extra-files`) |
 
 ```bash
 test -d .changeset && echo "changesets"
+ls .release-it.* 2>/dev/null; grep -q '"release-it"' package.json 2>/dev/null && echo "release-it"
 cat .agents/universal-plugin.json   # is packagePath declared?
 ```
 
@@ -51,10 +53,14 @@ 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.
+- **release-please, npm package.** Run `universal-plugin plugin version --from-package` after the
+  release PR bumps the package.
+- **release-please, no `package.json`.** `extra-files` bumps `plugin.json`, and a workflow step on the
+  release PR runs `universal-plugin plugin version --from-manifest`. See the section below.
 - **semantic-release.** Add `@semantic-release/exec` with
   `prepareCmd: "universal-plugin plugin version ${nextRelease.version}"`.
+- **release-it.** Run the stamp in the `after:bump` hook. For a plugin that ships to no npm package,
+  set `"npm": false` so release-it ignores `package.json`; see below.
 
 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.
@@ -64,17 +70,128 @@ there: it would decide a number changesets is about to decide again.
 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.
+`plugin.json`, the vendor manifests, the repository catalogs (`.claude-plugin/marketplace.json`,
+`.cursor-plugin/marketplace.json`, `.agents/plugins/marketplace.json`,
+`.github/plugin/marketplace.json`), `skills/**`, `.plugin/pins.json`, and the mcp file. The stamp
+re-derives the catalogs too, so leaving them out leaves them a release behind.
+
+`doctor` reports `semantic-release-no-stamp` when no `prepareCmd` runs `plugin version`, and
+`semantic-release-npm-unshipped` when a plugin that ships to no npm package still runs
+`@semantic-release/npm`.
+
+### release-please with no `package.json`
+
+release-please releases a plugin with no `package.json`. `release-type: simple` keeps the number in
+`.release-please-manifest.json` (`{ ".": "1.2.3" }`) and updates only `CHANGELOG.md` and a
+`version.txt` it skips when absent. `extra-files` bumps `plugin.json`:
+
+```json
+{
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "extra-files": [{ "type": "json", "path": "plugin.json", "jsonpath": "$.version" }]
+    }
+  }
+}
+```
+
+release-please runs no command before its release commit, so the vendor manifests, catalogs, skill
+pins and compiled scripts stay on the old number. Restamp the release PR in the same workflow, right
+after the action. `--from-manifest` takes the number `plugin.json` already holds.
+
+Both pushes need a token that starts workflow runs. A push made with the default `GITHUB_TOKEN`
+starts none, so the release PR's checks would never run on its head commit, and a required check
+would block the merge. Mint a GitHub App token for the run and give it to release-please and to
+`actions/checkout`, which pushes the restamp with it:
+
+```yaml
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+      - id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+      - if: ${{ steps.release.outputs.prs_created == 'true' }}
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}
+          token: ${{ steps.app-token.outputs.token }}
+      - if: ${{ steps.release.outputs.prs_created == 'true' }}
+        run: |
+          npx -y universal-plugin@0.18.0 plugin version --from-manifest
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --cached --quiet || { git commit -m "chore: restamp the plugin version"; git push; }
+```
+
+Set the App up once:
+
+1. Create a GitHub App with the repository permissions Contents, Pull requests and Issues set to
+   read and write. release-please labels its PR through the Issues API.
+2. Install it on the repository.
+3. Store its client ID as the variable `RELEASE_APP_CLIENT_ID` and a private key as the secret
+   `RELEASE_APP_PRIVATE_KEY`.
+
+The workflow's own `GITHUB_TOKEN` then needs only `contents: read`, because every write goes through
+the App token.
+
+- release-please force-pushes its branch each time it updates the PR, which drops the restamp commit.
+  The action reports an updated PR in `prs_created` as well, so the step runs again and restamps it.
+- The App token is minted for this run, expires within an hour, and is revoked when the job ends.
+  The private key is the one standing secret, and it reaches only the repositories the App is
+  installed on. A personal access token works too, but it is long-lived and acts as a person.
+- Do not re-run CI with `workflow_dispatch` (`gh workflow run`) instead. Checks from a
+  `workflow_dispatch` run do not count toward a required check.
+- Do not list the stamped files in `extra-files` instead. The skill pins and the compiled script
+  headers are not a `$.version` field, and the vendor manifests and catalogs belong to `plugin build`.
+- With `packagePath` declared, bump the package and run `--from-package` instead. `--from-manifest` is
+  refused there.
+
+`doctor` reports `release-please-no-restamp` when `extra-files` bumps `plugin.json` and no workflow runs
+`plugin version`, and `release-please-restamp-no-ci` when the restamp is pushed with the default
+`GITHUB_TOKEN`.
+
+### release-it reads the version from the git tag
+
+With `"npm": false`, release-it needs no `package.json`. Its `after:bump` hook runs before the release
+commit and tag, and the commit includes every tracked file the hook changed, so the stamp ships in the
+tagged commit. In `.release-it.json`:
+
+```json
+{
+  "npm": false,
+  "hooks": { "after:bump": "universal-plugin plugin version ${version}" }
+}
+```
+
+Before the first release, tag the commit that carries the current version (`git tag v1.2.0`).
+release-it reads the tag, not `plugin.json`: without one it starts from `0.0.0`, and
+`plugin version` refuses a number that does not advance.
 
 ## Step 2 — Run it
 
 ```bash
 node scripts/version.mjs <bump-or-number>
 node scripts/version.mjs --from-package
+node scripts/version.mjs --from-manifest
 ```
 
 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.17.0` pinned to this skill's version.
+(`pnpm exec universal-plugin`), else `npx universal-plugin@0.18.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.
 
@@ -89,6 +206,7 @@ source is decided.
 | Flag | Effect |
 |---|---|
 | `--from-package` | Take the version the package's `package.json` already holds |
+| `--from-manifest` | Restamp at the version `plugin.json` already holds; refused under `packagePath` |
 | `--preid <id>` | Prerelease identifier for the `pre*` release types |
 | `--dry-run` | Print the plan, write nothing. Run this first when unsure |
 | `--force` | Allow a target that does not advance on the current version |
@@ -129,6 +247,7 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 | 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 |
+| `--from-manifest` under `packagePath` | the package owns the number | run `--from-package` 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
@@ -138,8 +257,8 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
   `plugin build`; the bump already re-derived them.
 - **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`.
+- **Use the deprecated commands.** `plugin bundle` and `publish sync-version` print a deprecation
+  warning; use `plugin version` instead. `sync-version` now runs `plugin version --from-package`.
 
 ## Related skills
 
@@ -148,7 +267,7 @@ 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 every place agrees (`unstamped`, `version-drift`) | `doctor-universal-plugin` |
-| Add a changeset for the change being released | `add-changeset` |
+| Add a changeset for the change being released | `buddy-changesets:changesets` |
 | Refresh the repository's own marketplace catalogs after a bump | `marketplace` |
 | List the released plugin in the shared marketplace | `publish-plugin` |
 

package/skills/version/scripts/version.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.0","entry":"skills/version/scripts/version.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/version/scripts/version.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