khal-os 1.260324.2

package/.genie/wishes/workos-prod-rbac/WISH.md

@@ -0,0 +1,345 @@
+# Wish: WorkOS Production + RBAC Enforcement (Phase 1)
+
+| Field | Value |
+|-------|-------|
+| **Status** | DRAFT |
+| **Slug** | `workos-prod-rbac` |
+| **Date** | 2026-03-23 |
+| **GitHub Issue** | [namastexlabs/genie-os#13](https://github.com/namastexlabs/genie-os/issues/13) |
+| **Architecture** | [namastexlabs/genie-os#16](https://github.com/namastexlabs/genie-os/issues/16) |
+
+## Summary
+
+Phase 1 of the multi-tenant Genie OS platform. Flip WorkOS from staging to production, remove the TEMP BYPASS that grants all users admin, and enforce role-based access control using WorkOS's native RBAC. This is the auth foundation that all subsequent phases (multi-org, fleet management, FGA, marketplace) build on.
+
+## Context: Multi-Tenant Vision
+
+This wish is Phase 1 of a 6-phase platform build (see [#16](https://github.com/namastexlabs/genie-os/issues/16)):
+
+```
+Phase 1: WorkOS prod + RBAC enforcement     ← THIS WISH
+Phase 2: Multi-org + client isolation
+Phase 3: Instance fleet management
+Phase 4: FGA per-app permissions
+Phase 5: Enterprise (Admin Portal, SCIM, Audit Logs)
+Phase 6: App marketplace
+```
+
+**Full hierarchy (future):**
+| Scope | Role | Access |
+|-------|------|--------|
+| Platform | `platform-owner` | Everything across all clients |
+| Platform | `platform-admin` | All instances + monitoring |
+| Platform | `platform-dev` | Assigned instances + dev tools |
+| Client | `client-owner` | All apps deployed to their org |
+| Client | `client-admin` | Apps + manage employees |
+| Client | `client-member` | Only assigned apps |
+
+**Phase 1 implements the platform scope only** (NamasteX org, our roles). Client scope comes in Phase 2.
+
+## Scope
+
+### IN
+- **WorkOS production environment**: Swap staging API key, client ID, redirect URI, cookie password for production values
+- **Remove TEMP BYPASS**: In `src/lib/auth/use-auth.ts`, replace hardcoded admin grant with actual session role
+- **Server→client role plumbing**: Create a server component that calls `withAuth()` and passes role/permissions to client components (the `useAuth()` client hook doesn't expose role directly)
+- **WorkOS Dashboard config**: Document exact roles, permissions, and org setup needed
+- **Permission enforcement**: Return real role + derived permissions so `minRole` app gates work
+- **Webhook endpoint**: Add `/api/webhooks/workos` route for role/membership change events
+- **Preserve HeadlessChrome bypass**: Machine auth for d3k must keep working
+- **Forward-compatible role slugs**: Use `platform-owner`, `platform-admin`, `platform-dev`, `member` — slugs that won't collide when client-scoped roles are added in Phase 2
+
+### OUT
+- **Multi-org / client organizations** — Phase 2
+- **Instance fleet management** — Phase 3
+- **FGA / per-app sharing** — Phase 4
+- **Admin Portal, SCIM, Audit Logs** — Phase 5
+- **App Directory / Marketplace** — Phase 6
+- **Permissions management app in Genie OS** — Phase 2 (needs multi-org first)
+- **Custom WorkOS UI / Widgets** — use hosted AuthKit for now
+- **Feature flags** — available free but not needed yet
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Use WorkOS hosted AuthKit UI, not custom | Zero frontend auth code. Free up to 1M MAUs. |
+| Server component for role plumbing | `useAuth()` client hook returns `{ user, loading }` only. `withAuth()` server-side returns `{ user, role, permissions }`. Use a server component wrapper that calls `withAuth()` and passes role to client context. |
+| Role slugs: `platform-owner`, `platform-admin`, `platform-dev`, `member` | Forward-compatible with Phase 2 multi-org. WorkOS auto-prefixes org roles with `org-`, so platform roles need distinct slugs. `member` is WorkOS's default role for new memberships. |
+| Single org for Phase 1 | Our NamasteX org only. Multi-org in Phase 2. |
+| Webhook logs events + broadcasts via NATS | On role change, broadcast to connected clients via NATS so UI updates without full page reload. No server-side session store to invalidate — AuthKit manages cookies. |
+| `ROLE_DEFAULTS` as fallback | If JWT permissions are empty (edge case during migration), fall back to role-based defaults. |
+
+## Success Criteria
+
+- [ ] WorkOS production environment active with production API key and client ID
+- [ ] `NEXT_PUBLIC_WORKOS_REDIRECT_URI` points to production domain
+- [ ] TEMP BYPASS removed from `use-auth.ts` — users get their actual role
+- [ ] Server component passes role from `withAuth()` to client-side auth context
+- [ ] A `member` role user can only access the Files app
+- [ ] A `platform-dev` role user can access Terminal, Files, Settings, NATS Viewer
+- [ ] A `platform-admin`/`platform-owner` role user can access all apps
+- [ ] HeadlessChrome bypass still works for d3k
+- [ ] Login/logout flow works end-to-end on production domain
+- [ ] `/api/webhooks/workos` receives and processes role change events
+- [ ] `WORKOS_WEBHOOK_SECRET` in `.env.example`
+- [ ] `bun biome check .` and `bunx tsc --noEmit` pass
+
+## Execution Strategy
+
+### Wave 1 (foundation — docs + server-side role plumbing)
+| Group | Agent | Description |
+|-------|-------|-------------|
+| 1 | engineer | WorkOS Dashboard setup guide + env config + server-side role provider |
+
+### Wave 2 (parallel — client enforcement + webhooks)
+| Group | Agent | Description |
+|-------|-------|-------------|
+| 2 | engineer | Remove TEMP BYPASS + wire role enforcement across UI |
+| 3 | engineer | Webhook endpoint + NATS role-change broadcast |
+
+### Wave 3 (quality gate)
+| Group | Agent | Description |
+|-------|-------|-------------|
+| review | reviewer | Review all groups, run validation |
+
+## Execution Groups
+
+### Group 1: WorkOS Config + Server-Side Role Provider
+
+**Goal:** Document dashboard setup and create the server→client role bridge that the review identified as missing.
+
+**Deliverables:**
+
+1. `docs/workos-setup.md` — Step-by-step guide for WorkOS dashboard:
+   - Create production environment (or switch from staging)
+   - Create NamasteX organization
+   - Define environment roles with these slugs:
+     - `platform-owner`: all permissions (NamasteX founders)
+     - `platform-admin`: `apps:access`, `settings:manage`, `members:manage` (NamasteX senior)
+     - `platform-dev`: `apps:access` (NamasteX builders)
+     - `member`: (WorkOS default — base access, maps to viewer)
+   - Define permissions using `resource:action` pattern:
+     - `apps:access` — base app access
+     - `apps:install` — install from marketplace (future)
+     - `settings:manage` — OS settings
+     - `members:manage` — invite/remove users
+     - `billing:manage` — billing/subscription (future)
+     - `instances:manage` — fleet management (future)
+   - Configure redirect URI, email verification, session config
+   - Configure webhook endpoint URL + signing secret
+
+2. `.env.example` — Update with all WorkOS env vars:
+   ```
+   WORKOS_API_KEY=sk_live_...
+   WORKOS_CLIENT_ID=client_...
+   NEXT_PUBLIC_WORKOS_REDIRECT_URI=https://<prod-domain>/auth/callback
+   WORKOS_COOKIE_PASSWORD=<32+ char random string>
+   WORKOS_WEBHOOK_SECRET=whsec_...
+   ```
+
+3. `src/app/desktop/page.tsx` (or existing server component) — Server-side role injection:
+   - Call `withAuth()` to get `{ user, role, permissions, organizationId }`
+   - Pass `role` and `permissions` as props to the client-side desktop shell
+   - This solves the architectural gap: server `withAuth()` → prop drilling → client context
+
+4. `src/lib/auth/roles.ts` — Update role hierarchy and aliases:
+   - Role hierarchy: `['member', 'platform-dev', 'platform-admin', 'platform-owner']`
+   - Aliases: `admin` → `platform-admin`, `developer` → `platform-dev`, `owner` → `platform-owner`, `viewer` → `member`, `user` → `member`
+
+5. `src/components/apps/app-manifest.ts` — Update `ROLE_HIERARCHY`:
+   - `['member', 'platform-dev', 'platform-admin', 'platform-owner'] as const`
+   - Update `Role` type accordingly
+
+**Acceptance Criteria:**
+- [ ] `docs/workos-setup.md` exists with complete dashboard instructions
+- [ ] `.env.example` has `WORKOS_WEBHOOK_SECRET`
+- [ ] Server component calls `withAuth()` and passes role to client
+- [ ] `ROLE_HIERARCHY` uses forward-compatible slugs
+- [ ] `normalizeRole()` maps legacy slugs (`admin` → `platform-admin`, etc.)
+- [ ] `bunx tsc --noEmit` passes
+
+**Validation:**
+```bash
+test -f docs/workos-setup.md && \
+grep -q "platform-owner" docs/workos-setup.md && \
+grep -q "WORKOS_WEBHOOK_SECRET" .env.example && \
+grep -q "platform-owner" src/components/apps/app-manifest.ts && \
+grep -q "withAuth" src/app/desktop/page.tsx && \
+bunx tsc --noEmit && \
+echo "PASS" || echo "FAIL"
+```
+
+**depends-on:** none
+
+---
+
+### Group 2: Remove TEMP BYPASS + Enforce Roles
+
+**Goal:** Wire the actual WorkOS session role into the permission system so app gates work.
+
+**Deliverables:**
+
+1. `src/lib/auth/use-auth.ts` — Remove TEMP BYPASS:
+   - Accept role from server component props (passed via React context or prop drilling)
+   - Remove hardcoded `effectiveRole = 'admin'` (lines 42-44)
+   - Map server-provided role to internal role via `normalizeRole()`
+   - Derive permissions from role using `getRolePermissions()`
+   - Keep HeadlessChrome bypass intact — use `platform-owner` permissions (new top of hierarchy)
+
+2. `src/lib/auth/workos.ts` — Align `ROLE_DEFAULTS` with new role slugs:
+   - `platform-owner`: `{ apps: ['*'], manageMembers: true }`
+   - `platform-admin`: `{ apps: ['*'], manageMembers: true }`
+   - `platform-dev`: `{ apps: ['terminal', 'files', 'settings', 'nats-viewer'], manageMembers: false }`
+   - `member`: `{ apps: ['files'], manageMembers: false }`
+
+3. `src/components/taskbar/UserMenu.tsx` — Update role colors:
+   - Add `platform-owner` color (distinct from admin)
+   - Add `platform-admin` color
+   - Add `platform-dev` color
+   - `member` uses muted color (existing viewer color)
+
+4. Update any component that checks role strings to use new slugs
+
+**Acceptance Criteria:**
+- [ ] TEMP BYPASS removed — no hardcoded `'admin'` assignment for all users
+- [ ] `member` role user sees only Files app in desktop
+- [ ] `platform-dev` role user sees Terminal, Files, Settings, NATS Viewer
+- [ ] `platform-admin`/`platform-owner` sees all apps
+- [ ] HeadlessChrome bypass returns `platform-owner`-level access
+- [ ] `ROLE_COLORS` includes all 4 role slugs
+- [ ] `bunx tsc --noEmit` passes
+- [ ] `bun biome check .` passes
+
+**Validation:**
+```bash
+# No TEMP BYPASS remaining
+! grep -q "TEMP BYPASS" src/lib/auth/use-auth.ts && \
+# New role slugs in use
+grep -q "platform-owner" src/lib/auth/workos.ts && \
+grep -q "platform-owner" src/components/taskbar/UserMenu.tsx && \
+# Typecheck + lint pass
+bunx tsc --noEmit && \
+bun biome check . && \
+echo "PASS" || echo "FAIL"
+```
+
+**depends-on:** Group 1
+
+---
+
+### Group 3: Webhook Endpoint + NATS Role Broadcast
+
+**Goal:** Receive WorkOS webhook events and broadcast role changes to connected clients via NATS.
+
+**Deliverables:**
+
+1. `src/app/api/webhooks/workos/route.ts` — Webhook handler:
+   - Verify webhook signature using WorkOS SDK (`constructEvent()` or manual HMAC)
+   - Handle `organization_membership.updated` — extract new role, broadcast via NATS
+   - Handle `organization_membership.deleted` — broadcast membership revocation
+   - Handle `user.updated` — broadcast user metadata changes
+   - Return 200 OK on success, 400 on signature failure
+   - Route is already covered by `unauthenticatedPaths: ['/api/webhooks/:path*']`
+
+2. `src/lib/auth/webhook-handler.ts` — Event processing + NATS broadcast:
+   - Parse WorkOS webhook payload by event type
+   - On role change: publish to NATS subject `os.auth.role-changed` with `{ userId, newRole, orgId }`
+   - On membership deleted: publish to `os.auth.membership-revoked` with `{ userId, orgId }`
+   - Connected WS clients subscribed to these subjects can force re-auth
+   - Log events for debugging (console OK in service files)
+
+3. Clarification on session invalidation approach:
+   - AuthKit manages sessions via encrypted cookies — no server-side session store
+   - On `membership.deleted`: broadcast via NATS; client-side listener forces logout
+   - On `membership.updated` (role change): broadcast via NATS; client-side listener refreshes role from server
+   - Sessions expire naturally per WorkOS session config; webhook provides faster feedback
+
+**Acceptance Criteria:**
+- [ ] `POST /api/webhooks/workos` returns 200 for valid signed payloads
+- [ ] `POST /api/webhooks/workos` returns 400 for invalid signatures
+- [ ] NATS subjects `os.auth.role-changed` and `os.auth.membership-revoked` documented
+- [ ] `bunx tsc --noEmit` passes
+
+**Validation:**
+```bash
+test -f src/app/api/webhooks/workos/route.ts && \
+grep -q "organization_membership" src/lib/auth/webhook-handler.ts && \
+grep -q "os.auth" src/lib/auth/webhook-handler.ts && \
+bunx tsc --noEmit && \
+echo "PASS" || echo "FAIL"
+```
+
+**depends-on:** Group 1
+
+---
+
+## QA Criteria
+
+_What must be verified on dev after merge._
+
+- [ ] Login with WorkOS production credentials works end-to-end
+- [ ] User with `member` role sees only Files app on desktop
+- [ ] User with `platform-dev` role sees Terminal, Files, Settings, NATS Viewer
+- [ ] User with `platform-admin` role sees all apps + can manage members
+- [ ] Role change in WorkOS dashboard reflects in app after webhook + NATS broadcast
+- [ ] HeadlessChrome d3k bypass still renders desktop without login
+- [ ] Logout clears session and redirects to login
+- [ ] Invalid/expired sessions redirect to login
+- [ ] Role slugs are forward-compatible (no refactoring needed for Phase 2 multi-org)
+
+## Assumptions / Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| WorkOS staging→prod migration breaks existing sessions | Medium | Schedule during low-traffic; all users re-login once |
+| `platform-owner` slug not yet in WorkOS dashboard | Low | Create in dashboard before deploying code. `normalizeRole()` fallback to `platform-admin`. |
+| JWT permissions empty for existing users | Low | `ROLE_DEFAULTS` fallback handles this |
+| Webhook signature verification needs shared secret | Low | `WORKOS_WEBHOOK_SECRET` in `.env` |
+| Renaming roles from `admin`→`platform-admin` breaks existing code | Medium | `normalizeRole()` maps old→new. Grep for hardcoded role strings in all files. |
+| `withAuth()` not available in all server component contexts | Low | Use Next.js middleware or layout-level server component. AuthKit middleware already runs on all protected routes. |
+
+## Review Results
+
+### Review 1 — Plan Review (pre-fix)
+
+**Verdict:** FIX-FIRST
+
+| # | Severity | Gap | Resolution |
+|---|----------|-----|------------|
+| 1 | HIGH | Client-side role access: `useAuth()` doesn't expose role | **Fixed:** Added server component deliverable in Group 1 that calls `withAuth()` and passes role as props |
+| 2 | MEDIUM | `WORKOS_WEBHOOK_SECRET` missing from `.env.example` | **Fixed:** Added to Group 1, deliverable 2 |
+| 3 | MEDIUM | Webhook session invalidation unspecified | **Fixed:** Added NATS broadcast approach in Group 3, deliverable 3 |
+| 4 | LOW | `ROLE_COLORS` missing `owner` | **Fixed:** Incorporated in Group 2, deliverable 3 |
+| 5 | LOW | HeadlessChrome should use top-of-hierarchy | **Fixed:** Group 2 specifies `platform-owner` permissions |
+
+---
+
+## Files to Create/Modify
+
+```
+# Create
+docs/workos-setup.md                          — Dashboard setup guide (roles, permissions, session config)
+src/app/api/webhooks/workos/route.ts          — Webhook endpoint
+src/lib/auth/webhook-handler.ts               — Webhook event processing + NATS broadcast
+
+# Modify
+.env.example                                  — Add WORKOS_WEBHOOK_SECRET
+src/app/desktop/page.tsx                       — Server-side withAuth() → pass role to client
+src/lib/auth/use-auth.ts                      — Remove TEMP BYPASS, accept role from server
+src/lib/auth/workos.ts                        — Update ROLE_DEFAULTS to new slugs
+src/lib/auth/roles.ts                         — New hierarchy + slug aliases
+src/components/apps/app-manifest.ts           — New ROLE_HIERARCHY with platform-* slugs
+src/components/taskbar/UserMenu.tsx            — ROLE_COLORS for all 4 slugs
+```
+
+## Future Wishes (Pre-Drafted)
+
+| Phase | Wish | GitHub Issue | What |
+|-------|------|-------------|------|
+| 2 | Multi-Org + Client Isolation | [#16](https://github.com/namastexlabs/genie-os/issues/16) | WorkOS Organizations per client, org-level roles, org switcher, permissions management app |
+| 3 | Instance Fleet Management | [#16](https://github.com/namastexlabs/genie-os/issues/16) | Instance registry, central admin panel, FGA instance resources |
+| 4 | FGA App Permissions | [#14](https://github.com/namastexlabs/genie-os/issues/14) | Per-app per-instance per-user permissions, "share like Google Docs" |
+| 5 | Enterprise Features | TBD | Admin Portal embed, Directory Sync, Audit Logs, Domain Verification |
+| 6 | App Marketplace | [#14](https://github.com/namastexlabs/genie-os/issues/14) | Browse, publish, upvote apps; success/cost metrics; creator attribution |
+| — | Braindump / Idea Pool | [#15](https://github.com/namastexlabs/genie-os/issues/15) | Non-disruptive idea capture in Genie OS |

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality-gate:
+    name: Quality Gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm exec tsc --noEmit
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Build
+        run: pnpm build

package/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create Release
+    if: "!startsWith(github.event.head_commit.message, '[skip ci]')"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve version
+        id: ver
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          TAG="v${VERSION}"
+
+          if gh release view "${TAG}" > /dev/null 2>&1; then
+            echo "Release ${TAG} already exists — skipping"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Find previous release tag
+        id: prev
+        if: steps.ver.outputs.skip == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${{ steps.ver.outputs.tag }}"
+          PREV=$(gh release list --limit 50 --json tagName -q '.[].tagName' | grep -v "^${TAG}$" | head -1)
+          if [ -n "$PREV" ] && git merge-base --is-ancestor "$PREV" HEAD 2>/dev/null; then
+            echo "tag=${PREV}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate changelog
+        id: changelog
+        if: steps.ver.outputs.skip == 'false' && steps.prev.outputs.tag != ''
+        run: |
+          PREV="${{ steps.prev.outputs.tag }}"
+          NOTES=$(git log --oneline "${PREV}..HEAD" --pretty="- %s" | head -50)
+          echo "notes<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$NOTES" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Create release
+        if: steps.ver.outputs.skip == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${{ steps.ver.outputs.tag }}"
+          NOTES="${{ steps.changelog.outputs.notes }}"
+          if [ -z "$NOTES" ]; then
+            NOTES="Genie OS release ${TAG}"
+          fi
+          printf '%s' "$NOTES" > /tmp/release-notes.md
+          gh release create "${TAG}" \
+            --target "${{ github.sha }}" \
+            --title "${TAG}" \
+            --notes-file /tmp/release-notes.md

package/.github/workflows/version.yml

@@ -0,0 +1,122 @@
+name: Version
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [main, dev]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: version-${{ github.event.workflow_run.head_branch || 'manual' }}
+  cancel-in-progress: false
+
+jobs:
+  auto-version:
+    name: Auto Version
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: >-
+      (github.event_name == 'workflow_dispatch') ||
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push' &&
+       !contains(github.event.workflow_run.head_commit.message, '[skip ci]') &&
+       (
+         (github.event.workflow_run.head_branch == 'main' &&
+          startsWith(github.event.workflow_run.head_commit.message, 'Merge pull request') &&
+          contains(github.event.workflow_run.head_commit.message, '/dev'))
+         ||
+         (github.event.workflow_run.head_branch == 'dev')
+       ))
+
+    steps:
+      - name: Determine branch and version prefix
+        id: context
+        run: |
+          BRANCH="${{ github.event.workflow_run.head_branch || 'dev' }}"
+          if [ "$BRANCH" = "main" ]; then
+            echo "branch=dev" >> "$GITHUB_OUTPUT"
+            echo "prefix=1" >> "$GITHUB_OUTPUT"
+            echo "npm_tag=latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "branch=dev" >> "$GITHUB_OUTPUT"
+            echo "prefix=1" >> "$GITHUB_OUTPUT"
+            echo "npm_tag=next" >> "$GITHUB_OUTPUT"
+          fi
+          echo "Resolved: branch=dev, npm_tag=$([ "$BRANCH" = "main" ] && echo latest || echo next)"
+
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.context.outputs.branch }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Derive version
+        id: version
+        run: |
+          PREFIX="${{ steps.context.outputs.prefix }}"
+          TODAY=$(date -u +%y%m%d)
+          EXISTING=$(git tag --list "v${PREFIX}.${TODAY}.*" | wc -l)
+          BUILD_NUMBER=$((EXISTING + 1))
+          VERSION="${PREFIX}.${TODAY}.${BUILD_NUMBER}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "build_number=${BUILD_NUMBER}" >> "$GITHUB_OUTPUT"
+          echo "Derived version: ${VERSION}"
+
+      - name: Update package.json version
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          node -e "
+            const pkg = require('./package.json');
+            pkg.version = '${VERSION}';
+            require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, '\t') + '\n');
+          "
+
+      - name: Commit and tag
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          BRANCH="${{ steps.context.outputs.branch }}"
+
+          git add package.json
+          if git diff --cached --quiet; then
+            echo "No version changes to commit"
+          else
+            git commit -m "chore(version): bump to ${VERSION} [skip ci]"
+          fi
+
+          git tag "v${VERSION}"
+          git push --atomic origin "HEAD:refs/heads/${BRANCH}" "refs/tags/v${VERSION}"
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+          HUSKY: "0"
+        run: |
+          if [ -z "$NPM_TOKEN" ]; then
+            echo "⚠️ NPM_TOKEN not set — skipping publish"
+            exit 0
+          fi
+          echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+          npm publish --access public --tag ${{ steps.context.outputs.npm_tag }} || echo "Publish failed — version may already exist"

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint

package/.pnpm-approve-builds.json

@@ -0,0 +1 @@
+{ "node-pty@1.1.0": true }