100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# 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.
|