Initial Commit

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.