Merge pull request #85 from themashcodee/npm-run-release-script

chore: 🚀 replace changesets with one-command release + PR previews

Author: themashcodee

.changeset/README.md

@@ -0,0 +1,35 @@
+name: Preview Release
+
+# Publishes an installable preview build of every PR (and of `main`) to pkg.pr.new,
+# so contributors and testers can `npm install` a branch WITHOUT it ever touching the
+# real `slack-blocks-to-jsx` npm package or needing your npm token.
+#
+# Each new commit on a PR republishes and updates the PR comment with a fresh install
+# command — no version bumping or cleanup needed. See the "more commits" note in RELEASING.md.
+#
+# ONE-TIME SETUP: install the pkg.pr.new GitHub App on this repo (only an owner can):
+#   https://github.com/apps/pkg-pr-new
+# No secrets/tokens are required — it works for fork PRs too.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.13
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm dlx pkg-pr-new publish

.changeset/config.json

@@ -1,5 +1,6 @@
-.changeset
 .github
+scripts
+RELEASING.md
 node_modules
 src
 .env

.github/workflows/preview.yml

@@ -612,8 +612,11 @@ Input: `src/style.css`. Output: `dist/style.css` (~40 KB).
 | `dev`                       | tsup watch                                 |
 | `dev:css`                   | PostCSS watch                              |
 | `lint`                      | `tsc --noEmit`                             |
-| `release`                   | `pnpm run build && changeset publish`      |
-| `release-alpha-without-git` | Publish `--tag alpha --no-git-checks`      |
+| `test`                      | `tsc --noEmit` (typecheck; no unit tests)  |
+| `release`                   | `node scripts/release.mjs` (see Ch. 11)    |
+| `release:dry`               | Preview a release; changes nothing         |
+| `release:beta`              | Publish next `beta` prerelease (tag: beta) |
+| `release:alpha`             | Publish next `alpha` prerelease (tag: alpha) |
 
 ### 10.4 dist/ output
 
@@ -626,7 +629,7 @@ Input: `src/style.css`. Output: `dist/style.css` (~40 KB).
 
 ### 10.5 npm publish hygiene
 
-`.npmignore` excludes: `.changeset`, `.github`, `node_modules`, `src`, `.env`, `.prettierrc`, `CHANGELOG.md`, `pnpm-lock.yaml`, `tailwind.config.js`, `tsconfig.json`, `.DS_Store`, `postcss.config.js`.
+`.npmignore` excludes: `.github`, `scripts`, `RELEASING.md`, `node_modules`, `src`, `.env`, `.prettierrc`, `CHANGELOG.md`, `pnpm-lock.yaml`, `tailwind.config.js`, `tsconfig.json`, `.DS_Store`, `postcss.config.js`.
 
 `.npmrc`: `auto-install-peers=true`.
 
@@ -636,14 +639,37 @@ Input: `src/style.css`. Output: `dist/style.css` (~40 KB).
 
 ## Chapter 11 — Release process
 
-From `PUBLISH_GUIDE.md`, in short:
-
-1. Commit source changes.
-2. `pnpm changeset` — pick patch / minor / major; write summary.
-3. `git push origin main` — triggers GitHub Actions (`.github/workflows/`).
-4. CI runs lint + build.
-5. Changesets bot opens a "Version Packages" PR (bumps version, updates `CHANGELOG.md`).
-6. Merge that PR → publish workflow runs `pnpm run release` → `pnpm run build && changeset publish`.
+Releasing is a single local command: **`pnpm release`** (see `RELEASING.md`). It is driven by
+`scripts/release.mjs` — a dependency-free Node script that, in order:
+
+1. **Pre-flight checks** — clean working tree, on `main`, not behind `origin/main`, and authenticated
+   to both npm (`npm whoami`) and GitHub (`gh auth status`).
+2. **Lint / typecheck** (`pnpm run lint`) and **build** (`pnpm run build`).
+3. **Bumps the version** in `package.json` (interactive patch/minor/major/custom, or passed as an arg).
+4. **Commits** (`chore: release vX.Y.Z`) and **tags** (`vX.Y.Z`).
+5. **Publishes to npm** (`pnpm publish --no-git-checks --tag <dist-tag>`).
+6. **Pushes** the commit + tag, then **creates a GitHub release** via `gh release create --generate-notes`.
+
+`pnpm release:dry` previews the whole thing (runs checks + build, mutates nothing).
+
+**Prereleases (beta / alpha):** `pnpm release:beta` / `pnpm release:alpha` cut the next prerelease
+(`1.0.4` → `1.0.5-beta.0` → `-beta.1` …). Each publishes under its own npm dist-tag (`beta`, `alpha`,
+`rc`…) so it never becomes `latest`, and is flagged as a pre-release on GitHub — testers opt in with
+`npm install slack-blocks-to-jsx@beta`. Bump types `prepatch`/`preminor`/`premajor`/`prerelease` plus
+`--preid=<id>` give finer control; a normal `pnpm release patch` on a prerelease graduates it to stable
+(`1.0.5-beta.2` → `1.0.5`). The version maths mirror semver's `inc`. See `RELEASING.md`.
+
+The old Changesets flow (`pnpm changeset` + the `publish.yml` "Version Packages" bot) has been removed
+in favour of this. CI (`.github/workflows/main.yml`) still runs lint + build on every push/PR, but no
+longer publishes — releasing is now a deliberate local action. There is no `CHANGELOG.md`; release notes
+are auto-generated from merged PRs/commits on each GitHub release.
+
+**PR preview releases:** `.github/workflows/preview.yml` publishes every PR (and `main`) to
+[pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) so reviewers can `npm install`
+a branch (`https://pkg.pr.new/slack-blocks-to-jsx@<commit-or-PR>`) without it ever hitting the
+real npm package. It needs no npm token, works for fork PRs, and re-publishes + updates the PR
+comment on every new commit. Requires the pkg.pr.new GitHub App installed on the repo. These
+previews are distinct from intentional `pnpm release:beta` prereleases (which do go to npm).
 
 `RELEASE_NOTES.md` tells the story of v1.0.1 — the "full Block Kit parity" release — after 80+ iterative releases. Major breaking changes from that version:
 
@@ -683,8 +709,9 @@ Folder: `test-blocks/`. Used as manual/visual test inputs. Each file is a comple
 
 ```
 slack blocks to jsx library/
-├── .changeset/
 ├── .github/
+├── scripts/
+│   └── release.mjs                       # One-command release (see Ch. 11)
 ├── dist/
 │   ├── index.js  index.mjs  index.d.ts  index.d.mts  style.css
 ├── src/
@@ -751,7 +778,7 @@ slack blocks to jsx library/
 │       ├── main.tsx  App.tsx  fixtures.ts  index.css
 ├── package.json  tsconfig.json  tsup.config.ts
 ├── tailwind.config.js  postcss.config.js  .prettierrc
-├── readme.md  PUBLISH_GUIDE.md  RELEASE_NOTES.md
+├── readme.md  RELEASING.md  KNOWLEDGE_BASE.md
 ├── .npmignore  .npmrc  .env  .gitignore
 └── pnpm-lock.yaml
 ```
@@ -771,7 +798,7 @@ Rules worth knowing before making changes:
 7. **Externalization:** `react-markdown`, `remark-gfm`, `node-emoji` must stay external in tsup config — bundling them again will break Next.js ESM interop.
 8. **Accessibility:** preserve the `accessibility_label` prop on buttons; use semantic tags (button, a, input) — this mirrors Slack's own a11y posture.
 9. **Type-first:** every block/element addition requires a matching interface in `src/types/` before the component lands.
-10. **Changesets:** any user-facing change needs a changeset before merge.
+10. **Releasing:** versioning + publishing is a single local command, `pnpm release` (see Ch. 11 / `RELEASING.md`). No changeset files are needed.
 
 ---
 
@@ -856,3 +883,4 @@ The sidebar picks it up automatically on next HMR. Keep fixtures small (≤ 10 b
 | 2026-04-17 | Claude + Mash | Added Ch. 0 — How to use this knowledge base (usage, reading strategy, update triggers, update procedure, style rules, ownership).                                                                                                                                                                                                                                                                                                             |
 | 2026-04-17 | Claude + Mash | v1.1.0 release prep: added three new blocks (`alert`, `card`, `carousel`) matching Slack's 2026-04-16 Block Kit launch. Ch. 4 block count 14 → 17 (new §4.6 "Status & rich-container blocks"). Ch. 6.1 type list updated with `AlertBlock`, `CardBlock`, `CarouselBlock`, `CardImage`, `AlertLevel`. Ch. 12 gained `11-alert-card-carousel.json` fixture. Ch. 13 file tree updated. Changeset: `.changeset/add-alert-card-carousel-blocks.md`. |
 | 2026-04-17 | Claude + Mash | Added Ch. 15 — Playground. New `playground/` folder (Vite + React 18) that source-aliases `slack-blocks-to-jsx` to `../src/index.ts` for instant HMR. Committed to git, excluded from npm via `.npmignore`. Ch. 15 renumbered from change log → playground; change log moved to Ch. 16. Root `package.json` gained `playground`, `playground:install`, `playground:build` scripts. Ch. 13 file tree extended.                                  |
+| 2026-06-06 | Claude + Mash | Replaced the Changesets release flow with a single local command `pnpm release` (`scripts/release.mjs`): checks → lint → build → bump → commit/tag → npm publish → push → GitHub release. Removed `.changeset/`, `@changesets/cli`, and `.github/workflows/publish.yml`; added `test`/`release`/`release:dry` scripts and `RELEASING.md`. Rewrote Ch. 11, updated §10.3/§10.5 scripts + hygiene, Ch. 13 file tree (`scripts/`), and Ch. 14 rule 10. Added first-class beta/alpha prereleases: `release:beta`/`release:alpha` scripts, `prepatch`/`preminor`/`premajor`/`prerelease` bump types + `--preid`, auto dist-tag per channel, prerelease graduation, and a "Trying a prerelease" section in `readme.md`. Added `.github/workflows/preview.yml` (pkg.pr.new) for automatic per-PR/per-commit preview installs (no npm token, fork-safe). |

.github/workflows/publish.yml

@@ -0,0 +1,134 @@
+# Releasing
+
+Releasing is one command:
+
+```bash
+pnpm release
+```
+
+It walks you through everything — pick **patch / minor / major** (or a custom version) and confirm. The script then runs the whole pipeline for you:
+
+1. **Pre-flight checks** — clean working tree, on `main`, up to date with the remote, and logged in to both npm and GitHub.
+2. **Lint / typecheck** (`pnpm run lint`).
+3. **Build** (`pnpm run build`).
+4. **Bump the version** in `package.json`.
+5. **Commit** (`chore: release vX.Y.Z`) and **tag** (`vX.Y.Z`).
+6. **Publish to npm** (`pnpm publish`).
+7. **Push** the commit and tag to GitHub.
+8. **Create a GitHub release** with auto-generated notes.
+
+## One-time setup
+
+You only need to do these once per machine:
+
+```bash
+npm login          # so the script can publish to npm
+gh auth login      # so it can create the GitHub release (you're likely already logged in)
+```
+
+## Usage
+
+```bash
+pnpm release              # interactive — pick patch / minor / major / prerelease / custom
+pnpm release patch        # 1.0.4 -> 1.0.5
+pnpm release minor        # 1.0.4 -> 1.1.0
+pnpm release major        # 1.0.4 -> 2.0.0
+pnpm release 1.2.3        # set an exact version
+pnpm release patch --yes  # skip the confirmation prompt
+pnpm release:dry          # preview the whole thing, change nothing
+```
+
+## Beta / alpha prereleases
+
+Ship a version for people to test **before** it becomes the default `latest`:
+
+```bash
+pnpm release:beta     # 1.0.4 -> 1.0.5-beta.0   (npm dist-tag: beta)
+pnpm release:beta     # run again -> 1.0.5-beta.1, 1.0.5-beta.2 …
+pnpm release:alpha    # same idea on the "alpha" channel -> 1.0.5-alpha.0
+```
+
+Each prerelease is published under its own npm **dist-tag** (`beta`, `alpha`, …), so it never
+becomes the version people get by default, and it's marked as a *pre-release* on GitHub. Testers opt in:
+
+```bash
+npm install slack-blocks-to-jsx@beta      # latest beta
+npm install slack-blocks-to-jsx@alpha     # latest alpha
+npm install slack-blocks-to-jsx@1.0.5-beta.2   # an exact prerelease
+```
+
+Meanwhile `npm install slack-blocks-to-jsx` keeps installing the stable `latest` release.
+
+When the beta is solid, **graduate it to stable** — a normal release drops the prerelease suffix:
+
+```bash
+pnpm release patch    # from 1.0.5-beta.2  ->  1.0.5  (dist-tag: latest)
+```
+
+More control:
+
+```bash
+pnpm release prerelease --preid=rc    # release-candidate channel (1.0.5-rc.0, tag: rc)
+pnpm release preminor --preid=beta    # start a beta off the next minor (1.1.0-beta.0)
+pnpm release premajor --preid=beta    # start a beta off the next major (2.0.0-beta.0)
+pnpm release 1.2.3-beta.0             # any exact prerelease version you want
+```
+
+## Dry run
+
+Not sure? Preview first — it runs the checks, lint, and build but changes nothing:
+
+```bash
+pnpm release:dry
+```
+
+## PR preview releases (pkg.pr.new)
+
+Every pull request automatically gets an **installable preview build** so reviewers and
+testers can try the change before it's merged — without it ever touching the real
+`slack-blocks-to-jsx` package on npm. This is handled by
+[pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) via
+`.github/workflows/preview.yml`.
+
+When a PR opens, a bot comments with an install command, e.g.:
+
+```bash
+npm install https://pkg.pr.new/slack-blocks-to-jsx@<commit-or-PR>
+```
+
+**What about new commits on the PR?** Nothing to do. Every push re-runs the workflow and
+republishes; the bot **edits its existing comment** with the fresh command, and the
+per-PR URL always resolves to the PR's latest commit. So testers just re-install the same
+URL to get the newest build — no version bumping, no cleanup, no npm clutter.
+
+This needs **no npm token** and works for PRs from forks. One-time setup (owner only):
+install the **pkg.pr.new GitHub App** → <https://github.com/apps/pkg-pr-new>.
+
+> PR previews are **not** the same as `pnpm release:beta`. Previews are automatic, throwaway,
+> and never published to npm. A `beta`/`alpha` (via `pnpm release:beta`) is an intentional,
+> maintainer-cut prerelease published to the real npm package under the `beta`/`alpha` dist-tag.
+
+## If something fails midway
+
+The script does the irreversible steps (commit → tag → publish → push → GitHub release) in
+an order that keeps things recoverable, and prints exact recovery commands if a step fails.
+The common cases:
+
+- **Failed before publishing** — nothing was pushed. Undo the local bump:
+  ```bash
+  git tag -d vX.Y.Z
+  git reset --hard HEAD~1
+  ```
+- **Published, but a later step failed** — the package is already on npm; just finish the rest:
+  ```bash
+  git push --follow-tags origin main
+  gh release create vX.Y.Z --title vX.Y.Z --generate-notes
+  ```
+
+## Notes
+
+- **"Tests"** currently means the TypeScript typecheck (`pnpm run lint` / `pnpm test`); there is
+  no unit-test suite yet. When one is added, wire it into the `test` script and the release will
+  pick it up.
+- CI (`.github/workflows/main.yml`) still runs lint + build on every push and PR. Releasing is now
+  a deliberate local action rather than an automated CI publish.

.npmignore

@@ -24,10 +24,12 @@
     "build:css": "postcss ./src/style.css -o ./dist/style.css",
     "dev:css": "postcss ./src/style.css -o ./dist/style.css --watch",
     "dev": "tsup --watch",
-    "new-version": "pnpm changeset",
     "lint": "tsc",
-    "release": "pnpm run build && changeset publish",
-    "release-alpha-without-git": "pnpm run build && pnpm publish --tag alpha --no-git-checks",
+    "test": "tsc",
+    "release": "node scripts/release.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "release:beta": "node scripts/release.mjs prerelease --preid=beta",
+    "release:alpha": "node scripts/release.mjs prerelease --preid=alpha",
     "playground:install": "cd playground && npm install",
     "playground": "cd playground && npm run dev",
     "playground:build": "cd playground && npm run build"
@@ -46,7 +48,6 @@
     "@yozora/character": "^2.3.2",
     "@yozora/core-tokenizer": "^2.3.2",
     "@yozora/parser": "^2.3.2",
-    "@changesets/cli": "^2.26.2",
     "@types/react": "^17 || ^18 || ^19",
     "@types/react-dom": "^17 || ^18 || ^19",
     "autoprefixer": "^10.4.17",