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

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.