From d2420a145be623f2cc8d0e799fb66944a8f3a8c1 Mon Sep 17 00:00:00 2001
From: Mathieu Chambaud <mathchambaud2000@gmail.com>
Date: Thu, 29 Oct 2026 22:43:01 +0100
Subject: [PATCH] build: release with npm version and tagged GitHub releases

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 25 +++++++++++++++++++++++++
 .npmrc                        |  1 +
 README.md                     | 12 ++++++++++++
 package.json                  |  4 +++-
 4 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/release.yml
 create mode 100644 .npmrc

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..78111d3
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check tag matches package.json
+        run: |
+          version="v$(node -p 'require("./package.json").version')"
+          if [ "$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match package.json ($version)" >&2
+            exit 1
+          fi
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --verify-tag --generate-notes
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 0000000..6249b89
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1 @@
+message="chore(release): v%s"
diff --git a/README.md b/README.md
index d460f38..61c3305 100644
--- a/README.md
+++ b/README.md
@@ -102,3 +102,15 @@ Design notes live in [`docs/`](docs/).
 ## License
 
 [MIT](LICENSE) © Mathieu Chambaud
+
+## Releasing
+
+Versions follow [SemVer](https://semver.org/) and are cut from an up-to-date `main`:
+
+```sh
+npm version patch   # or minor / major
+```
+
+This runs the CI checks, bumps `package.json`, commits `chore(release): vX.Y.Z`, tags `vX.Y.Z`
+and pushes. The tag triggers the Release workflow, which publishes a GitHub release with
+generated notes.
diff --git a/package.json b/package.json
index 72c9d7b..6cfa7ae 100644
--- a/package.json
+++ b/package.json
@@ -45,7 +45,9 @@
   "scripts": {
     "check-types": "tsc --noEmit",
     "test": "bun test",
-    "verify:ds": "node scripts/verify-ds.mjs"
+    "verify:ds": "node scripts/verify-ds.mjs",
+    "preversion": "test \"$(git branch --show-current)\" = main && git fetch -q origin main && test \"$(git rev-parse HEAD)\" = \"$(git rev-parse origin/main)\" && bun run check-types && bun test && bun run verify:ds && npm pack --dry-run",
+    "postversion": "git push --follow-tags"
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.6",