feat!: migrate to Bun, publish ESM-only exports, add framework integrations (#30)

- Tooling: switch scripts/CI to Bun
- Packaging: ESM-only build, modern exports map + wildcard subpath exports for integrations (permask/<integration>)
- Integrations: express, fastify, h3, nitro, nestjs, hono, koa, itty-router, elysia (thin adapters)
- Core: add PermaskError, base64 helpers, portable packBitmasks/unpackBitmasks, add formatBitmask

  BREAKING CHANGE: package is ESM-only (CJS/UMD entry points removed)
  BREAKING CHANGE: unpackBitmasks now throws PermaskError on invalid input
  BREAKING CHANGE: createPermask().create now throws PermaskError for unknown groups

Author: dschewchenko

.github/workflows/release.yml

@@ -5,13 +5,7 @@ on:
       - main
 
 permissions:
-  contents: write # to be able to publish a GitHub release
-  issues: write # to be able to comment on released issues
-  pull-requests: write # to be able to comment on released pull requests
-  id-token: write # to enable use of OIDC for npm provenance
-  pages: write # to deploy to Pages
-  actions: read # to read workflow artifacts
-
+  contents: read
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -21,57 +15,80 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 10
+          bun-version: "1.3.1"
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+
+      - name: Use cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            */*/node_modules
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
       - name: Install dependencies
-        run: pnpm install
+        run: bun install --frozen-lockfile
       - name: Build
-        run: pnpm build
+        run: bun run build
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm dlx semantic-release
+        run: npx semantic-release
 
   playground:
     name: Playground
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     needs: release
     if: github.ref == 'refs/heads/main'
 
     steps:
       - uses: actions/checkout@v4
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 10
-      - name: Use Node.js
-        uses: actions/setup-node@v4
+          bun-version: "1.3.1"
+
+      - name: Use cache
+        uses: actions/cache@v4
         with:
-          node-version: 22
-          cache: 'pnpm'
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            */*/node_modules
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
       - name: Install dependencies
-        run: |
-          cd playground/vue
-          pnpm install
+        run: bun install --frozen-lockfile
       - name: Build playground
-        run: |
-          cd playground/vue
-          pnpm build
+        working-directory: playground/vue
+        run: bun run build
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./playground/vue/dist
-

.github/workflows/test.yml

@@ -1,5 +1,9 @@
 name: Test
+
 on:
+  push:
+    branches:
+      - main
   pull_request:
     branches:
       - main
@@ -8,9 +12,6 @@ jobs:
   test:
     name: Test
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [ 22 ]
 
     permissions:
       # Required to checkout the code
@@ -20,19 +21,27 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 10
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+          bun-version: "1.3.1"
+
+      - name: Use cache
+        uses: actions/cache@v4
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'pnpm'
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            */*/node_modules
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
       - name: Install dependencies
-        run: pnpm install
+        run: bun install --frozen-lockfile
+
       - name: 'Test'
-        run: pnpm test:coverage
+        run: bun run test:coverage
       - name: 'Report Coverage'
         if: always() # Also generate the report if tests are failing
         uses:  davelosert/vitest-coverage-report-action@v2

AGENTS.md

@@ -0,0 +1,54 @@
+# Repository Guidelines
+
+## Project Structure
+
+- `src/`: main TypeScript source (utilities, constants, integrations).
+- `src/**/*.test.ts`: Vitest unit tests colocated with code.
+- `playground/vue/`: Vue playground for interactive/manual validation.
+- `dist/`: build output (generated; don’t edit by hand).
+- `.github/workflows/`: CI and release pipelines (Bun-based).
+
+## Build, Test, and Development Commands
+
+This repo uses **Bun** as the package manager and runtime.
+Use the version pinned in `package.json#packageManager` (CI matches it).
+
+```bash
+bun install                 # install deps (uses bun.lock)
+bun run build               # build library bundles + types into dist/
+bun run test                # run vitest (watch/default mode)
+bun run test:coverage       # run tests + V8 coverage summary
+bun run lint                # biome check for formatting + lint
+bun run lint:fix            # apply biome fixes where safe
+```
+
+Playground (from repo root):
+
+```bash
+bun --cwd=playground/vue run dev
+bun --cwd=playground/vue run build
+```
+
+## Coding Style & Naming Conventions
+
+- Language: TypeScript (ESM, `strict`).
+- Formatting/linting: **Biome** (`bunx biome check .`).
+- Indentation: 2 spaces; line width: 120.
+- File naming: `kebab-case.ts` for modules; tests as `*.test.ts`.
+
+## Testing Guidelines
+
+- Framework: **Vitest**.
+- Keep tests close to the code they validate (`src/**`).
+- Add/extend tests for new behavior and bug fixes; prefer deterministic tests.
+- Run locally before pushing: `bun run test:coverage`.
+
+## Commit & Pull Request Guidelines
+
+- This repo’s public changelog is generated by **semantic-release**, so commit messages must follow **Conventional Commits** (enforced by commitlint).
+- Prefer small, focused commits (one logical change per commit), because release notes are derived from them.
+- Use scopes to keep the changelog readable: `core`, `integrations`, `docs`, `playground`, `ci`, `build`.
+  - Examples: `feat(core): add formatBitmask utility`, `feat(integrations): add elysia adapter`, `fix(pack): throw on invalid base64`, `chore(ci): switch workflows to bun`.
+- Breaking changes: use `feat!:` / `fix!:` or add a `BREAKING CHANGE:` footer.
+- PRs should include: a short description, rationale, and any relevant usage notes.
+- Requirements: `bun run lint`, `bun run test:coverage`, and `bun run build` must pass; avoid committing generated `dist/` output.