Initial Commit

openspec/changes/enterprise-react-permissions/proposal.md

@@ -0,0 +1,82 @@
+# OpenSpec Change: enterprise-react-permissions
+
+- **Change ID**: enterprise-react-permissions
+- **Package**: `@suaveplan/react-permissions`
+- **Category**: react
+- **Target path**: `react/auth/react-permissions`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-permissions.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-permissions` on genesis from scratch at enterprise quality. React binding for RBAC/ABAC: `<Can>`, `<PermissionBoundary>`, `<RoleGuard>`, `AbilityProvider`/`AbilityContext`, `createAbilityContext()`, `createContextualCan()`, hooks (`useAbility`, `useCan`, `usePermissionCheck`). Genesis adds Storybook stories, Playwright E2E, `@suaveplan/error`-backed errors, OTel audit events for denied renders, and SSR safety tests.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `PermissionError` |
+| `@suaveplan/types` (`workspace:^`) | Shared types |
+| `@opentelemetry/api` (`catalog:observability`) | `permission.denied` span event |
+
+External: `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+Can, PermissionBoundary, RoleGuard
+AbilityContext, AbilityProvider, createAbilityContext
+useAbilityContext, useAbility, useCan, usePermissionCheck
+createContextualCan
+
+// Types
+CanProps, PermissionBoundaryProps, RoleGuardProps,
+AbilityProviderProps, PermissionCheckResult
+```
+
+---
+
+## New additions for genesis
+
+1. **`PermissionError`** — codes: `PERMISSION_CONTEXT_MISSING`, `PERMISSION_DENIED`.
+2. **OTel `permission.denied` span event** — attributes: `permission.action`, `permission.subject` — emitted when `<Can>` renders null due to denial.
+3. **SSR safety tests** — `AbilityProvider` hydration test.
+4. **Storybook** — `<Can>` allowed/denied, `<PermissionBoundary>` with fallback, `<RoleGuard>` role variants, multi-ability `createAbilityContext` demo.
+5. **Playwright E2E** — render `<Can>`, verify allowed/denied rendering.
+
+---
+
+## File layout
+
+```text
+react/auth/react-permissions/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    components/
+      can/ permission-boundary/ role-guard/
+    context/
+      ability-context/
+    hooks/
+      use-ability/ use-can/ use-permission-check/
+    utils/
+      create-contextual-can/
+    types/
+  e2e/
+    permissions.spec.ts
+```

openspec/changes/enterprise-react-permissions/tasks.md

@@ -0,0 +1,99 @@
+# Tasks: enterprise-react-permissions
+
+**Change ID**: enterprise-react-permissions
+**Package**: `@suaveplan/react-permissions`
+**Target path**: `react/auth/react-permissions`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create directory tree per proposal layout.
+- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, exports map (per-component subpaths).
+- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
+- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Error codes and types
+
+- [ ] Define `PermissionError` extending `SuaveplanError`; codes: `PERMISSION_CONTEXT_MISSING`, `PERMISSION_DENIED`.
+- [ ] Define `PermissionCheckResult`: `{ allowed: boolean; reason?: string }`.
+- [ ] Define `CanProps`, `PermissionBoundaryProps`, `RoleGuardProps`, `AbilityProviderProps`.
+
+---
+
+## 3. AbilityContext + createAbilityContext
+
+- [ ] `createAbilityContext<TAbility>()` — returns `{ AbilityContext, AbilityProvider, useAbilityContext }` for a given ability type.
+- [ ] Module-level default context created at import time.
+- [ ] `useAbilityContext()` throws `PermissionError(PERMISSION_CONTEXT_MISSING)` outside provider.
+- [ ] Write `ability-context.test.tsx`: provider renders, context consumed, missing throws. SSR test: render to string, no window errors. `{ timeout: 5000 }`.
+- [ ] Write `ability-context.md`.
+
+---
+
+## 4. Hooks
+
+### useAbility
+
+- [ ] Returns current `TAbility` instance from context. Write test + md.
+
+### useCan
+
+- [ ] `useCan(action, subject): PermissionCheckResult` — delegates to `ability.can(action, subject)`. Emits OTel `permission.denied` event when `allowed === false`. Write test (allowed + denied cases) + md.
+
+### usePermissionCheck
+
+- [ ] `usePermissionCheck(checks: Array<{action, subject}>): PermissionCheckResult[]` — bulk check. Write test + md.
+
+---
+
+## 5. Components
+
+### Can
+
+- [ ] `<Can action="read" subject="Post">` renders children if allowed; renders `fallback` prop (default null) if denied. Emits OTel event on denial.
+- [ ] Write test (allowed/denied/fallback), stories (allowed, denied, with-fallback, playground), md.
+
+### PermissionBoundary
+
+- [ ] Renders children if all specified permissions pass; renders `fallback` component otherwise.
+- [ ] Write test, stories, md.
+
+### RoleGuard
+
+- [ ] `<RoleGuard roles={['admin', 'editor']}>` renders children if user has at least one role.
+- [ ] Write test, stories (single-role, multi-role, denied), md.
+
+---
+
+## 6. createContextualCan
+
+- [ ] Factory returning a `<Can>`-shaped component bound to a given `AbilityContext`.
+- [ ] Write test (custom context) + md.
+
+---
+
+## 7. E2E
+
+- [ ] `e2e/permissions.spec.ts` — Playwright:
+  - Render `<Can action="read" subject="Post">` with allowed ability — children visible.
+  - Render with denied ability — children hidden, fallback shown.
+  - Render `<RoleGuard roles={['admin']}>` with non-admin user — children hidden.
+
+---
+
+## 8. Verify and publish
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-permissions` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-permissions` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/react-permissions`.
+- [ ] Archive change folder.