@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/rbac/compliance/compliance-guide.md

@@ -1,544 +0,0 @@
-# RBAC/Auth Compliance Guide
-
-> **📚 RBAC Compliance** | [← Back to RBAC Documentation](../README.md) | [Troubleshooting](./troubleshooting-compliance.md) | [Migrating Custom Auth](./migrating-custom-auth.md)
-
-This guide explains how to achieve RBAC/auth compliance in your pace app to ensure proper security and consistent usage of pace-core.
-
-## Overview
-
-The RBAC/auth compliance system ensures that:
-- All auth/rbac/permission functionality uses pace-core exclusively
-- RBAC system is properly initialized
-- All pages are protected with PagePermissionGuard
-- Supabase configuration is centralized
-- No custom auth/rbac code exists
-
-## Compliance Checks
-
-The compliance system checks for:
-
-### 1. Custom Auth/RBAC Code
-
-**What it checks:**
-- Custom auth hooks (useAuth, useLogin, useLogout, etc.)
-- Custom RBAC components (PermissionGuard, AuthGuard, etc.)
-- Custom permission utilities (checkPermission, hasAccess, etc.)
-
-**How to fix:**
-- Remove custom implementations
-- Import equivalent from `@jmruthers/pace-core` or `@jmruthers/pace-core/rbac`
-- Update all usages
-
-See [Migrating Custom Auth](./migrating-custom-auth.md) for detailed migration steps.
-
-### 2. Duplicate Supabase Configuration
-
-**What it checks:**
-- Multiple `createClient` calls
-- Supabase environment variables in multiple files
-
-**How to fix:**
-- Create a single `supabase.ts` file
-- Export the client instance
-- Import from the shared location everywhere
-
-### 3. Unprotected Pages
-
-**What it checks:**
-- Routes without PagePermissionGuard
-- Pages without permission checks
-
-**How to fix:**
-- Wrap all routes with PagePermissionGuard
-- Set `pageName` and `operation` props
-- Ensure pages exist in `rbac_app_pages` table
-
-### 4. Direct Supabase Auth Usage
-
-**What it checks:**
-- Direct calls to `supabase.auth.signIn`, `supabase.auth.signUp`, etc.
-
-**How to fix:**
-- Use `useUnifiedAuth` hook from pace-core
-- Use `UnifiedAuthProvider` to wrap your app
-- Replace all direct auth calls with pace-core methods
-
-### 5. Provider Setup Issues
-
-**What it checks:**
-- Missing `UnifiedAuthProvider` or `OrganisationProvider`
-- Incorrect provider nesting order
-- Providers placed in wrong locations
-
-**How to fix:**
-- Ensure correct nesting: `QueryClientProvider` → `BrowserRouter` → `UnifiedAuthProvider` → `OrganisationProvider` → `App`
-- Place providers in `main.tsx` or `App.tsx` entry file
-- See [Provider Setup](#provider-setup) section below
-
-### 6. Vite Configuration Issues
-
-**What it checks:**
-- `@jmruthers/pace-core` in `optimizeDeps.include` (should be excluded)
-- Missing `@jmruthers/pace-core` in `optimizeDeps.exclude`
-- Missing `react-router-dom` in `resolve.dedupe`
-
-**How to fix:**
-- Add `@jmruthers/pace-core` to `optimizeDeps.exclude`
-- Remove `@jmruthers/pace-core` from `optimizeDeps.include`
-- Add `react-router-dom` to `resolve.dedupe`
-- See [Vite Configuration](#vite-configuration) section below
-
-### 7. Router Setup Issues
-
-**What it checks:**
-- Missing `BrowserRouter`
-- `BrowserRouter` placed incorrectly (inside `UnifiedAuthProvider` instead of wrapping it)
-- `Routes` used without `BrowserRouter`
-
-**How to fix:**
-- Wrap app with `BrowserRouter` from `react-router-dom`
-- Ensure `BrowserRouter` wraps `UnifiedAuthProvider` (not the other way around)
-- See [Router Setup](#router-setup) section below
-
-## Running Compliance Checks
-
-### Static Analysis
-
-Run the compliance check script:
-
-```bash
-npm run check:pace-core
-```
-
-This will scan your codebase and report:
-- Custom auth/rbac code
-- Duplicate configurations
-- Unprotected pages
-- Direct Supabase auth usage
-- Provider setup issues
-- Vite configuration problems
-- Router setup issues
-
-### ESLint Rules
-
-The compliance system includes ESLint rules that run during development:
-
-- `no-custom-auth-code` - Disallows custom auth/rbac implementations
-- `no-duplicate-supabase-config` - Disallows multiple Supabase configurations
-- `require-page-permission-guard` - Requires PagePermissionGuard on routes
-- `no-direct-supabase-auth` - Disallows direct Supabase auth usage
-
-### Runtime Validation
-
-Check runtime compliance programmatically:
-
-```typescript
-import { checkRuntimeCompliance } from '@jmruthers/pace-core/rbac';
-
-const result = checkRuntimeCompliance();
-if (!result.setup.isCompliant) {
-  console.warn('RBAC setup issues:', result.setup.issues);
-}
-```
-
-## Achieving Compliance
-
-### Step 1: Initialize RBAC
-
-```typescript
-// main.tsx or App.tsx
-import { setupRBAC } from '@jmruthers/pace-core/rbac';
-import { createClient } from '@supabase/supabase-js';
-
-const supabase = createClient(
-  import.meta.env.VITE_SUPABASE_URL,
-  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
-);
-
-// ⚠️ REQUIRED: Call setupRBAC before rendering
-setupRBAC(supabase);
-```
-
-### Step 2: Set Up Providers
-
-**⚠️ CRITICAL: Provider nesting order matters!**
-
-The correct nesting order is:
-1. `QueryClientProvider` (outermost)
-2. `BrowserRouter`
-3. `UnifiedAuthProvider`
-4. `OrganisationProvider`
-5. `App` (innermost)
-
-```tsx
-// main.tsx - Correct setup
-import { BrowserRouter } from 'react-router-dom';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
-
-const queryClient = new QueryClient();
-
-createRoot(document.getElementById("root")!).render(
-  <QueryClientProvider client={queryClient}>
-    <BrowserRouter>
-      <UnifiedAuthProvider supabaseClient={supabase} appName={APP_NAME}>
-        <OrganisationProvider>
-          <App />
-        </OrganisationProvider>
-      </UnifiedAuthProvider>
-    </BrowserRouter>
-  </QueryClientProvider>
-);
-```
-
-**Common mistakes to avoid:**
-- ❌ `BrowserRouter` inside `UnifiedAuthProvider` (causes Router context errors)
-- ❌ `UnifiedAuthProvider` wrapping `BrowserRouter` (causes context errors)
-- ❌ Missing `BrowserRouter` (causes `useNavigate` errors)
-
-### Step 3: Protect All Pages
-
-```tsx
-// pages/Dashboard.tsx
-import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
-
-function Dashboard() {
-  return (
-    <PagePermissionGuard pageName="dashboard" operation="read">
-      <DashboardContent />
-    </PagePermissionGuard>
-  );
-}
-```
-
-### Step 4: Use pace-core Auth
-
-```tsx
-// components/Login.tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function Login() {
-  const { signIn } = useUnifiedAuth();
-  
-  const handleLogin = async () => {
-    await signIn({ email, password });
-  };
-  
-  return <button onClick={handleLogin}>Login</button>;
-}
-```
-
-### Step 5: Configure Vite
-
-**⚠️ CRITICAL: Vite configuration prevents React context mismatches!**
-
-Add to your `vite.config.ts`:
-
-```typescript
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  resolve: {
-    dedupe: ['react', 'react-dom', 'react-router-dom']
-  },
-  optimizeDeps: {
-    include: [
-      'react',
-      'react-dom',
-      'react/jsx-runtime'
-    ],
-    // CRITICAL: Exclude pace-core to prevent React context mismatches
-    exclude: ['@jmruthers/pace-core', 'react-router-dom']
-  }
-});
-```
-
-**Why this matters:**
-- Pre-bundling `@jmruthers/pace-core` creates separate React instances
-- This causes "useUnifiedAuth must be used within a UnifiedAuthProvider" errors
-- Excluding it ensures pace-core uses the same React instance as your app
-
-### Step 6: Centralize Supabase Config
-
-```typescript
-// src/lib/supabase.ts
-import { createClient } from '@supabase/supabase-js';
-
-export const supabase = createClient(
-  import.meta.env.VITE_SUPABASE_URL,
-  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
-);
-```
-
-## Database Configuration
-
-Ensure your database is properly configured:
-
-1. **App Registration**: App must exist in `rbac_apps` table
-2. **Pages**: All pages must be registered in `rbac_app_pages` table
-3. **Permissions**: Permissions must be configured in `rbac_page_permissions` table
-4. **User Roles**: Users must have roles in `rbac_organisation_roles` table
-
-See [RBAC Quick Start](../quick-start.md) for database setup instructions.
-
-## Quick Fixes
-
-The compliance system provides quick fix suggestions:
-
-```typescript
-import { getQuickFixes } from '@jmruthers/pace-core/rbac';
-
-const fixes = getQuickFixes('custom-auth-code', { name: 'useAuth', type: 'hook' });
-fixes.forEach(fix => {
-  console.log(fix.suggestion);
-  console.log(fix.codeExample);
-});
-```
-
-## CI/CD Integration
-
-Add compliance checks to your CI/CD pipeline:
-
-```yaml
-# .github/workflows/compliance.yml
-- name: Check pace-core compliance
-  run: npm run check:pace-core
-```
-
-The script exits with code 1 if compliance issues are found, causing the build to fail.
-
-## Troubleshooting Common Issues
-
-### Provider Setup Issues
-
-**Issue:** "useUnifiedAuth must be used within a UnifiedAuthProvider" error
-
-**Possible causes:**
-1. `UnifiedAuthProvider` is missing or not wrapping your app
-2. `BrowserRouter` is inside `UnifiedAuthProvider` (wrong nesting)
-3. Vite is pre-bundling `@jmruthers/pace-core` (React context mismatch)
-
-**Solution:**
-1. **Check provider nesting** in `main.tsx`:
-   ```tsx
-   // ✅ CORRECT
-   <QueryClientProvider>
-     <BrowserRouter>
-       <UnifiedAuthProvider>
-         <OrganisationProvider>
-           <App />
-         </OrganisationProvider>
-       </UnifiedAuthProvider>
-     </BrowserRouter>
-   </QueryClientProvider>
-   
-   // ❌ WRONG - BrowserRouter inside UnifiedAuthProvider
-   <UnifiedAuthProvider>
-     <BrowserRouter>
-       <App />
-     </BrowserRouter>
-   </UnifiedAuthProvider>
-   ```
-
-2. **Check Vite config** - ensure `@jmruthers/pace-core` is in `optimizeDeps.exclude`:
-   ```typescript
-   optimizeDeps: {
-     exclude: ['@jmruthers/pace-core', 'react-router-dom']
-   }
-   ```
-
-3. **Clear Vite cache** and restart dev server:
-   ```bash
-   rm -rf node_modules/.vite
-   npm run dev
-   ```
-
-### Router Context Issues
-
-**Issue:** "useNavigate() may be used only in the context of a <Router> component" error
-
-**Possible causes:**
-1. Missing `BrowserRouter`
-2. `BrowserRouter` placed incorrectly
-3. `react-router-dom` being pre-bundled by Vite
-
-**Solution:**
-1. **Add BrowserRouter** wrapping your app:
-   ```tsx
-   import { BrowserRouter } from 'react-router-dom';
-   
-   <BrowserRouter>
-     <UnifiedAuthProvider>
-       <App />
-     </UnifiedAuthProvider>
-   </BrowserRouter>
-   ```
-
-2. **Update Vite config**:
-   ```typescript
-   resolve: {
-     dedupe: ['react', 'react-dom', 'react-router-dom']
-   },
-   optimizeDeps: {
-     exclude: ['react-router-dom']
-   }
-   ```
-
-3. **Clear Vite cache** and restart
-
-### Vite Configuration Issues
-
-**Issue:** React context mismatch errors, components can't find providers
-
-**Possible causes:**
-1. `@jmruthers/pace-core` is being pre-bundled by Vite
-2. Multiple React instances in the bundle
-
-**Solution:**
-1. **Exclude pace-core from pre-bundling**:
-   ```typescript
-   optimizeDeps: {
-     exclude: ['@jmruthers/pace-core']
-   }
-   ```
-
-2. **Dedupe React dependencies**:
-   ```typescript
-   resolve: {
-     dedupe: ['react', 'react-dom', 'react-router-dom']
-   }
-   ```
-
-3. **Clear Vite cache**:
-   ```bash
-   rm -rf node_modules/.vite
-   ```
-
-### Custom Auth/RBAC Code Detected
-
-**Issue:** Custom `useAuth` hook or `PermissionGuard` component found
-
-**Solution:**
-1. Remove your custom implementation
-2. Import from pace-core:
-   ```typescript
-   import { useUnifiedAuth } from '@jmruthers/pace-core';
-   import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
-   ```
-3. Update all usages - see [Migration Examples](#migrating-from-custom-code) below
-
-### Duplicate Supabase Configuration
-
-**Issue:** Multiple `createClient` calls found
-
-**Solution:**
-1. Create a single `supabase.ts` file:
-   ```typescript
-   // src/lib/supabase.ts
-   export const supabase = createClient(url, key);
-   ```
-2. Remove all other `createClient` calls
-3. Import from the shared location everywhere
-
-### Unprotected Pages
-
-**Issue:** Route without PagePermissionGuard
-
-**Solution:**
-1. Wrap all routes with PagePermissionGuard:
-   ```tsx
-   <PagePermissionGuard pageName="dashboard" operation="read">
-     <Dashboard />
-   </PagePermissionGuard>
-   ```
-2. Ensure pages exist in `rbac_app_pages` table
-
-### Direct Supabase Auth Usage
-
-**Issue:** Direct `supabase.auth` calls detected
-
-**Solution:**
-1. Use `useUnifiedAuth` hook instead:
-   ```typescript
-   const { signIn } = useUnifiedAuth();
-   await signIn({ email, password });
-   ```
-2. Ensure `UnifiedAuthProvider` wraps your app
-
-### RBAC Not Initialized
-
-**Issue:** `setupRBAC()` not called
-
-**Solution:**
-```typescript
-// main.tsx - Must be called before rendering
-import { setupRBAC } from '@jmruthers/pace-core/rbac';
-setupRBAC(supabase);
-```
-
-## Migrating from Custom Code
-
-### Migrating `useAuth` Hook
-
-**Before:**
-```typescript
-// src/hooks/useAuth.ts
-export function useAuth() {
-  const [user, setUser] = useState(null);
-  // ... custom logic
-}
-```
-
-**After:**
-```typescript
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-const { user } = useUnifiedAuth();
-```
-
-### Migrating `PermissionGuard` Component
-
-**Before:**
-```tsx
-<PermissionGuard permission="read:users">
-  <UsersPage />
-</PermissionGuard>
-```
-
-**After:**
-```tsx
-<PagePermissionGuard pageName="users" operation="read">
-  <UsersPage />
-</PagePermissionGuard>
-```
-
-### Migrating `checkPermission` Utility
-
-**Before:**
-```typescript
-const hasAccess = checkPermission(user, 'read:users');
-```
-
-**After:**
-```typescript
-import { isPermitted } from '@jmruthers/pace-core/rbac';
-const hasAccess = await isPermitted({
-  userId: user.id,
-  scope: { organisationId: org.id },
-  permission: 'read:page.users'
-});
-```
-
-### Step-by-Step Migration Process
-
-1. **Audit:** Run `npm run check:pace-core` to find all custom code
-2. **Setup:** Ensure `setupRBAC()` is called and providers are configured
-3. **Migrate:** Replace custom code with pace-core equivalents one component at a time
-4. **Test:** Verify all auth flows and permission checks work
-5. **Clean:** Remove custom files and update all imports
-
-## Next Steps
-
-- [RBAC Troubleshooting](../troubleshooting.md) - General RBAC issues
-- [RBAC Quick Start](../quick-start.md) - Getting started with RBAC
-- [RBAC API Reference](../api-reference.md) - Complete API documentation
-

package/docs/standards/01-architecture-standard.md

@@ -1,44 +0,0 @@
-# Architecture Standard
-
-## Purpose
-Define the core architectural principles for pace-core so that components, APIs, RPCs, utilities, and documentation evolve consistently and sustainably.
-
-## Principles
-- Composition over complexity
-- Separation of concerns
-- Domain-agnostic
-- Extensible, stable APIs
-- Secure by default
-- Performance-conscious
-
-## Performance Requirements
-- **RLS policies must use helper functions** - Never use subqueries in RLS policies as they cause N+1 query patterns
-- **Database migrations must be tested** - Verify migrations don't cause query timeouts or performance degradation
-- **Monitor query performance** - Use EXPLAIN ANALYZE to verify RLS policies don't create expensive execution plans
-
-## Boundaries
-### In scope
-- UI primitives
-- Generic hooks
-- Shared API patterns
-- Error-handling conventions
-- RPC shape conventions
-
-### Out of scope
-- App-specific domain logic
-- App-specific styling
-- Business workflows
-
-## Precedence
-1. Security Standard
-2. API & RPC Standard
-3. Component Standard
-4. Code Style Standard
-5. Testing Standard
-6. Documentation Standard
-
-## Cursor Checklist
-- Ensure changes fit boundaries
-- Do not introduce domain logic
-- Follow precedence ordering
-- Prefer additive changes

package/docs/standards/02-api-and-rpc-standard.md

@@ -1,39 +0,0 @@
-# API & RPC Standard
-
-## Naming
-- `<family>_<domain>_<verb>` pattern (e.g., `data_cake_dishes_list`, `app_cake_dish_create`)
-- `data_*` prefix for read operations (e.g., `data_file_reference_list`)
-- `app_*` prefix for write operations (e.g., `app_cake_dish_create`)
-- CRUD verbs only: create, read, update, delete, list, get
-- Bulk operations use `_bulk` suffix (e.g., `app_cake_dish_create_bulk`)
-
-## Result Shape
-```ts
-type ApiResult<T> =
-  | { ok: true; data: T }
-  | { ok: false; error: ApiError };
-
-type ApiError = {
-  code: string;
-  message: string;
-  details?: object;
-};
-```
-
-## RPC Rules
-- Read RPCs never mutate
-- Write RPCs should be idempotent when possible
-- Never accept dynamic SQL
-- Must enforce RLS + tenant boundaries
-- Errors must be user-safe
-
-## Deprecation Rules
-- Mark outdated RPCs with @deprecated
-- Retirement window: 2 stable releases
-
-## Cursor Checklist
-- Enforce ApiResult shape
-- Follow naming rules
-- Do not bypass RLS
-- Avoid overlapping or redundant RPCs
-- Ensure idempotency for writes

package/docs/standards/03-component-standard.md

@@ -1,32 +0,0 @@
-# Component Development Standard
-
-## Principles
-- Stateless when possible
-- Composable structure
-- Accessible by default
-- Fully typed
-- Small surface area
-
-## Architecture
-- UI primitives only
-- Never add domain logic
-- No data fetching inside components
-- Support controlled + uncontrolled usage
-
-## Accessibility Checklist
-- Keyboard operable
-- Correct ARIA roles
-- Visible focus states
-- No inaccessible interactions
-
-## Testing Requirements
-- Use React Testing Library
-- Test key interactions
-- Snapshot tests only for simple components
-
-## Cursor Checklist
-- Do not add domain logic
-- Validate accessibility rules
-- Keep components small
-- Move non-UI logic to hooks
-- Enforce strict typings

package/docs/standards/04-code-style-standard.md

@@ -1,32 +0,0 @@
-# TypeScript & Code Style Standard
-
-## TypeScript Rules
-- No any
-- Prefer discriminated unions
-- Avoid assertions unless in escape hatches
-- Use ReadonlyArray where possible
-- Avoid boolean mode flags
-
-## Naming Conventions
-- Hooks: useSomething
-- Providers: SomethingProvider
-- Utilities: camelCase
-- Components: PascalCase
-
-## Preferred Patterns
-- Pure functions
-- Composition over inheritance
-- Early returns
-- Small private helpers
-
-## Forbidden
-- Implicit any
-- Bloated components
-- Domain-specific types in pace-core
-
-## Cursor Checklist
-- No any / unknown / unnecessary assertions
-- Convert flags into unions
-- Enforce naming rules
-- Extract large functions into helpers
-- Prevent domain types from leaking in