From ee8e5ecec9d8179d80d6eac2ee1e107cb481c43c Mon Sep 17 00:00:00 2001 From: xyzbk <54625068+xyzbk@users.noreply.github.com> Date: Wed, 2 Sep 2026 20:33:22 +0300 Subject: [PATCH 1/2] docs: document version pinning and the release routine Co-authored-by: Cursor --- README.md | 19 +++++++++++++++++++ plugins/offcut/README.md | 19 +++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/README.md b/README.md index 05f35fe..509f7f9 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ no dependencies. git diff | npx --yes github:skelvar/offcut scan --diff - ``` +Pin a version with `npx --yes github:skelvar/offcut#v0.4.0 scan --diff -`; marketplace installs accept the same tag as `--ref v0.4.0`. + ```text src/phone.js (1) [new-dependency] Offcut: new dependency — what does this replace that four lines could not do? @@ -124,6 +126,23 @@ node scripts/build-agents-md.js # AGENTS.md is generated from rules/offcut.md Harness notes and benchmark receipts: [docs/development](docs/development/README.md). +### Release + +1. Bump every version field (`package.json`, `plugin.json`, the three plugin manifests, the two `marketplace.json` files, `scripts/build-agents-md.js`, `skills/offcut-{review,audit,help}/SKILL.md`), then run: + + ```bash + node scripts/build-agents-md.js + node scripts/build-plugin-package.mjs + ``` + +2. Merge the bump to main through a pull request (CI checks version parity and the generated files). + +3. ```bash + gh release create vX.Y.Z --target main --title "Offcut vX.Y.Z" --notes-file notes.md --latest + ``` + + The Releases page is not updated by the version fields; this step is what updates it. + ## License MIT — see [LICENSE](LICENSE). diff --git a/plugins/offcut/README.md b/plugins/offcut/README.md index 05f35fe..509f7f9 100644 --- a/plugins/offcut/README.md +++ b/plugins/offcut/README.md @@ -17,6 +17,8 @@ no dependencies. git diff | npx --yes github:skelvar/offcut scan --diff - ``` +Pin a version with `npx --yes github:skelvar/offcut#v0.4.0 scan --diff -`; marketplace installs accept the same tag as `--ref v0.4.0`. + ```text src/phone.js (1) [new-dependency] Offcut: new dependency — what does this replace that four lines could not do? @@ -124,6 +126,23 @@ node scripts/build-agents-md.js # AGENTS.md is generated from rules/offcut.md Harness notes and benchmark receipts: [docs/development](docs/development/README.md). +### Release + +1. Bump every version field (`package.json`, `plugin.json`, the three plugin manifests, the two `marketplace.json` files, `scripts/build-agents-md.js`, `skills/offcut-{review,audit,help}/SKILL.md`), then run: + + ```bash + node scripts/build-agents-md.js + node scripts/build-plugin-package.mjs + ``` + +2. Merge the bump to main through a pull request (CI checks version parity and the generated files). + +3. ```bash + gh release create vX.Y.Z --target main --title "Offcut vX.Y.Z" --notes-file notes.md --latest + ``` + + The Releases page is not updated by the version fields; this step is what updates it. + ## License MIT — see [LICENSE](LICENSE). From aba41e5ae441948e15c6390fbc5514bc79d518dd Mon Sep 17 00:00:00 2001 From: xyzbk <54625068+xyzbk@users.noreply.github.com> Date: Wed, 2 Sep 2026 20:34:04 +0300 Subject: [PATCH 2/2] ci: publish to npmjs on GitHub release Co-authored-by: Cursor --- .github/workflows/publish.yml | 27 +++++++++++++++++++++++++++ README.md | 2 ++ plugins/offcut/README.md | 2 ++ 3 files changed, 31 insertions(+) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..73343f5 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,27 @@ +name: publish +on: + release: + types: [published] +permissions: + contents: read + id-token: write +jobs: + npm: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ github.event.release.tag_name }} + - uses: actions/setup-node@v7 + with: + node-version: '22' + registry-url: https://registry.npmjs.org + - name: Tag must match package.json + run: | + tag="${{ github.event.release.tag_name }}" + ver="$(node -p "require('./package.json').version")" + test "$tag" = "v$ver" || { echo "tag $tag != package.json v$ver"; exit 1; } + - run: node --test tests/*.test.js + - run: npm publish --provenance --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/README.md b/README.md index 509f7f9..608909a 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,8 @@ Harness notes and benchmark receipts: [docs/development](docs/development/README The Releases page is not updated by the version fields; this step is what updates it. +4. Publishing the release triggers `.github/workflows/publish.yml`, which publishes `@skelvar/offcut` to npmjs with provenance. It needs a repository secret `NPM_TOKEN` (an npm granular access token with publish rights on the `@skelvar` scope). + ## License MIT — see [LICENSE](LICENSE). diff --git a/plugins/offcut/README.md b/plugins/offcut/README.md index 509f7f9..608909a 100644 --- a/plugins/offcut/README.md +++ b/plugins/offcut/README.md @@ -143,6 +143,8 @@ Harness notes and benchmark receipts: [docs/development](docs/development/README The Releases page is not updated by the version fields; this step is what updates it. +4. Publishing the release triggers `.github/workflows/publish.yml`, which publishes `@skelvar/offcut` to npmjs with provenance. It needs a repository secret `NPM_TOKEN` (an npm granular access token with publish rights on the `@skelvar` scope). + ## License MIT — see [LICENSE](LICENSE).