@jmruthers/pace-core 0.5.181 → 0.5.183

package/docs/troubleshooting/DEBUG_NETWORK_ERROR.md

@@ -1,152 +0,0 @@
-# Debugging NetworkError / CORS Error
-
-## The Real Issue
-
-If pace-cake works fine with the same Supabase instance, then **CORS is already configured correctly**. The "CORS request did not succeed" error message is often misleading - it usually means the request failed for another reason, not necessarily CORS policy.
-
-## How to Debug
-
-### Step 1: Check Network Tab in Browser DevTools
-
-1. Open browser DevTools (F12 or Cmd+Option+I)
-2. Go to **Network** tab
-3. Clear the network log
-4. Try to log in
-5. Look for the failed request to `/auth/v1/token`
-
-**What to check:**
-- **Status code**: What HTTP status code is returned? (200, 401, 500, etc.)
-- **Request headers**: Are the headers correct?
-- **Response**: What does the response say?
-- **Timing**: Does the request timeout or fail immediately?
-
-### Step 2: Check Console for Real Error
-
-The browser console might show the actual error. Look for:
-- Network timeout
-- Connection refused
-- SSL/TLS errors
-- Proxy errors
-- Request cancelled
-
-### Step 3: Compare with pace-cake
-
-Since pace-cake works:
-1. **Check pace-cake's network tab** - What does a successful login request look like?
-2. **Compare request headers** - Are they the same?
-3. **Compare Supabase client setup** - Is it identical?
-
-### Step 4: Check for Differences
-
-**Compare pace-trac vs pace-cake:**
-
-1. **Supabase client creation**:
-   ```typescript
-   // pace-trac - check this matches pace-cake
-   const supabase = createClient(url, key, {
-     auth: {
-       autoRefreshToken: true,
-       persistSession: true,
-       detectSessionInUrl: true
-     }
-   });
-   ```
-
-2. **setupRBAC call**:
-   ```typescript
-   // Should be identical
-   setupRBAC(supabase);
-   ```
-
-3. **Provider setup**:
-   ```typescript
-   // Should match pace-cake exactly
-   <UnifiedAuthProvider supabaseClient={supabase} appName={APP_NAME}>
-     <OrganisationProvider>
-       <App />
-     </OrganisationProvider>
-   </UnifiedAuthProvider>
-   ```
-
-### Step 5: Check Browser/Network Issues
-
-**Common causes of "CORS request did not succeed":**
-
-1. **Browser extension blocking requests**
-   - Try incognito/private mode
-   - Disable extensions one by one
-
-2. **Network/proxy issues**
-   - Check if corporate proxy is blocking
-   - Try different network (mobile hotspot)
-   - Check firewall settings
-
-3. **DNS issues**
-   - Can you reach `srqhjwivpohjcjqikjry.supabase.co`?
-   - Try pinging the domain
-
-4. **SSL/TLS issues**
-   - Check browser console for SSL errors
-   - Verify certificate is valid
-
-### Step 6: Check pace-trac Specific Issues
-
-**Things that might be different in pace-trac:**
-
-1. **Port number**: Are you using a different port than pace-cake?
-   - pace-cake might use `localhost:3000`
-   - pace-trac uses `localhost:8087`
-   - But if CORS is configured with wildcard, this shouldn't matter
-
-2. **Environment variables**: Are they correct?
-   ```bash
-   # Check these match pace-cake
-   VITE_SUPABASE_URL=...
-   VITE_SUPABASE_ANON_KEY=...
-   ```
-
-3. **Vite configuration**: Any proxy or network settings?
-   ```typescript
-   // vite.config.ts - check for any proxy settings
-   ```
-
-## Most Likely Causes
-
-Based on "pace-cake works but pace-trac doesn't":
-
-1. **Different port** - But CORS should allow both if configured correctly
-2. **Browser session issue** - Try clearing cache/cookies
-3. **Network timing** - Something interfering with the request
-4. **Code difference** - Something in pace-trac setup is different
-
-## Quick Fixes to Try
-
-1. **Clear browser cache and cookies**
-2. **Try incognito/private mode**
-3. **Try different browser**
-4. **Restart dev server**
-5. **Check if pace-cake still works** (verify Supabase is up)
-
-## If Still Failing
-
-**Check the actual network request details:**
-- Right-click the failed request in Network tab
-- Select "Copy" → "Copy as cURL"
-- Compare with pace-cake's successful request
-- Look for differences in headers, URL, or body
-
-**Check console for actual error:**
-- The "CORS request did not succeed" might be masking the real error
-- Look for other error messages before/after
-- Check if there are multiple failed requests
-
-## Summary
-
-Since pace-cake works, this is likely:
-- ✅ **NOT a CORS configuration issue** (already configured)
-- ✅ **NOT an RBAC issue** (RBAC doesn't interfere with auth)
-- ⚠️ **Likely a network/browser issue** specific to pace-trac
-- ⚠️ **Or a code difference** between pace-trac and pace-cake
-
-**Next step**: Check Network tab in DevTools to see the actual error, not just the CORS message.
-

package/docs/troubleshooting/FIX_SUPABASE_CORS.md

@@ -1,184 +0,0 @@
-# How to Fix CORS Error in Supabase
-
-## Problem
-
-You're seeing this error when trying to log in:
-```
-Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource 
-at https://srqhjwivpohjcjqikjry.supabase.co/auth/v1/token?grant_type=password
-(Reason: CORS request did not succeed)
-```
-
-This happens because Supabase is blocking requests from `localhost:8087` due to CORS (Cross-Origin Resource Sharing) policy.
-
-## Solution: Add Your Origin to Supabase CORS Settings
-
-### Step 1: Log into Supabase Dashboard
-
-1. Go to [https://app.supabase.com](https://app.supabase.com)
-2. Log in with your Supabase account
-3. Select your project (the one with URL `srqhjwivpohjcjqikjry.supabase.co`)
-
-### Step 2: Navigate to API Settings
-
-1. In the left sidebar, click on **"Settings"** (gear icon)
-2. Click on **"API"** in the settings menu
-
-### Step 3: Find CORS Settings
-
-Look for one of these sections (Supabase UI may vary):
-
-**Option A: "CORS" Section**
-- Scroll down to find **"CORS"** or **"Allowed Origins"** section
-- You'll see a text area or input field for allowed origins
-
-**Option B: "Additional Configuration"**
-- Look for **"Additional Configuration"** or **"Advanced Settings"**
-- Find **"CORS Origins"** or **"Allowed Origins"**
-
-**Option C: "Auth" Settings**
-- Sometimes CORS is under **"Auth"** → **"URL Configuration"**
-- Look for **"Site URL"** or **"Redirect URLs"** sections
-- CORS might be listed as **"Additional Redirect URLs"** or **"Allowed Origins"**
-
-### Step 4: Add Your Development Origin
-
-In the CORS/Allowed Origins field, add:
-
-```
-http://localhost:8087
-```
-
-**If there are already origins listed**, add yours on a new line or separated by commas:
-
-```
-http://localhost:3000
-http://localhost:8087
-http://localhost:5173
-```
-
-**For development, you can also use a wildcard** (less secure, but convenient):
-```
-*
-```
-
-⚠️ **Note**: Wildcard (`*`) allows ALL origins. Only use this for development, never in production!
-
-### Step 5: Save Changes
-
-1. Click **"Save"** or **"Update"** button
-2. Wait for confirmation that settings were saved
-3. Changes may take a few seconds to propagate
-
-### Step 6: Test Login
-
-1. Go back to your app (`http://localhost:8087`)
-2. Try logging in again
-3. Check browser console - CORS error should be gone
-
-## Alternative: Check Project Settings
-
-If you can't find CORS settings in API settings:
-
-### Method 1: Project Settings → API
-1. Go to **"Project Settings"** (top right, gear icon)
-2. Click **"API"**
-3. Look for **"CORS"** or **"Allowed Origins"**
-
-### Method 2: Auth Settings
-1. Go to **"Authentication"** in left sidebar
-2. Click **"URL Configuration"**
-3. Check **"Site URL"** and **"Redirect URLs"**
-4. Add `http://localhost:8087` to redirect URLs if needed
-
-### Method 3: Database Settings
-1. Go to **"Settings"** → **"Database"**
-2. Look for **"Connection Pooling"** or **"API"** settings
-3. CORS might be listed there
-
-## If CORS Settings Don't Exist
-
-Some Supabase projects might not have explicit CORS settings. In that case:
-
-### Option 1: Check Site URL
-1. Go to **"Authentication"** → **"URL Configuration"**
-2. Set **"Site URL"** to `http://localhost:8087`
-3. Add `http://localhost:8087` to **"Redirect URLs"**
-
-### Option 2: Use Supabase CLI
-If you have Supabase CLI installed:
-
-```bash
-# Update CORS settings via CLI
-supabase projects update <project-id> --cors-origins "http://localhost:8087"
-```
-
-### Option 3: Contact Supabase Support
-If you can't find CORS settings anywhere:
-1. Check Supabase documentation for your project version
-2. Contact Supabase support
-3. They can help configure CORS for your project
-
-## Production Setup
-
-For production, you'll need to:
-
-1. **Add your production domain**:
-   ```
-   https://yourdomain.com
-   https://www.yourdomain.com
-   ```
-
-2. **Remove wildcard** (`*`) if you used it for development
-
-3. **Set Site URL** in Auth settings to your production URL
-
-## Verification
-
-After making changes:
-
-1. **Clear browser cache** (important!)
-2. **Hard refresh** the page (Ctrl+Shift+R or Cmd+Shift+R)
-3. **Try login again**
-4. **Check browser console** - should see no CORS errors
-
-## Common Issues
-
-### "Settings saved but still getting CORS error"
-- Wait 30-60 seconds for changes to propagate
-- Clear browser cache
-- Try incognito/private browsing mode
-- Check if you're using the correct origin (http vs https, port number)
-
-### "Can't find CORS settings"
-- Supabase UI changes frequently
-- Try searching for "CORS", "origins", or "allowed"
-- Check Supabase documentation for your project version
-- Contact Supabase support
-
-### "Works in one browser but not another"
-- Clear cache in both browsers
-- Check browser security settings
-- Try disabling browser extensions
-- Check if one browser has stricter CORS policies
-
-## Still Having Issues?
-
-If CORS error persists after following these steps:
-
-1. **Double-check the origin**: Make sure `http://localhost:8087` matches exactly (including `http://` not `https://`)
-2. **Check network tab**: Open browser DevTools → Network tab, look for the failed request, check request headers
-3. **Verify Supabase project**: Make sure you're editing the correct project (check the URL in error message)
-4. **Check for typos**: Ensure no extra spaces or characters in CORS settings
-5. **Try different port**: If using a different port, add that too: `http://localhost:5173`, `http://localhost:3000`, etc.
-
-## Summary
-
-1. ✅ Go to Supabase Dashboard → Settings → API
-2. ✅ Find "CORS" or "Allowed Origins" section
-3. ✅ Add `http://localhost:8087`
-4. ✅ Save changes
-5. ✅ Clear browser cache and test
-
-The CORS error should be resolved after these steps!
-

package/docs/troubleshooting/cake-page-permission-guard-issue-summary.md

@@ -1,193 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# Cake PagePermissionGuard Issue - Summary & Action Plan
-
-## 🚨 Issue Status: CAKE APPLICATION BUG (Not pace-core)
-
-**Date**: January 16, 2025  
-**Priority**: Critical  
-**Status**: Requires Cake team action  
-
-## Problem Summary
-
-The `PagePermissionGuard` component from pace-core is working correctly, but Cake's implementation has a UI layering issue causing the Access Denied modal to persist despite correct permissions.
-
-### Evidence from Console Logs
-
-✅ **pace-core is working correctly**:
-- `useCan` returns `can: true`
-- `willShowAccessDenied: false`
-- `willShowContent: true`
-- `RENDERING CONTENT STATE` is logged
-
-❌ **Cake has implementation issues**:
-- Access Denied modal remains visible
-- Infinite re-render loop detected (same instance ID `14bp0efg9`)
-- UI state not updating despite correct component state
-
-## Root Cause Analysis
-
-Based on the console logs, this is **definitely a Cake application issue**, not a pace-core bug. The most likely causes are:
-
-1. **Multiple PagePermissionGuard instances** rendering simultaneously
-2. **Infinite re-render loop** in the Meals component
-3. **CSS/Modal layering conflicts** keeping the modal visible
-4. **React state management issues** preventing UI updates
-
-## Immediate Action Required
-
-### Step 1: Add Diagnostic Code
-
-Add this to your Meals component to identify the exact issue:
-
-```tsx
-import { useEffect, useRef } from 'react';
-
-export function Meals() {
-  const renderCount = useRef(0);
-  renderCount.current += 1;
-  
-  useEffect(() => {
-    // Check for infinite re-renders
-    if (renderCount.current > 10) {
-      console.error('🚨 INFINITE RE-RENDER DETECTED!', {
-        renderCount: renderCount.current,
-        component: 'Meals'
-      });
-    }
-    
-    // Check for multiple PagePermissionGuard instances
-    const guards = document.querySelectorAll('[data-testid*="page-permission-guard"]');
-    console.log('[Meals] PagePermissionGuard instances:', guards.length);
-    
-    // Check for multiple modals
-    const modals = document.querySelectorAll('[role="dialog"], .modal, [data-testid*="modal"]');
-    console.log('[Meals] Modal elements:', modals.length);
-    
-  }, []);
-  
-  console.log('[Meals] Component render count:', renderCount.current);
-  
-  return (
-    <div>
-      <PagePermissionGuard pageName="meals" operation="read">
-        <DataTable ... />
-      </PagePermissionGuard>
-    </div>
-  );
-}
-```
-
-### Step 2: Check for Common Issues
-
-1. **Multiple PagePermissionGuard wrappers**:
-   ```tsx
-   // ❌ WRONG - Don't do this
-   <PagePermissionGuard>
-     <PagePermissionGuard>
-       <DataTable />
-     </PagePermissionGuard>
-   </PagePermissionGuard>
-   ```
-
-2. **Conditional rendering**:
-   ```tsx
-   // ❌ WRONG - Don't conditionally render the guard
-   {someCondition && (
-     <PagePermissionGuard>
-       <DataTable />
-     </PagePermissionGuard>
-   )}
-   ```
-
-3. **State management causing re-renders**:
-   ```tsx
-   // ❌ WRONG - This can cause infinite loops
-   const [loading, setLoading] = useState(true);
-   useEffect(() => {
-     setLoading(false);
-   }, [loading]); // This dependency causes infinite loop
-   ```
-
-### Step 3: Simplify the Implementation
-
-Use this minimal implementation to test:
-
-```tsx
-import React from 'react';
-import { PagePermissionGuard, DataTable } from '@jmruthers/pace-core';
-
-export function Meals() {
-  console.log('[Meals] Rendering Meals component');
-  
-  return (
-    <div>
-      <h1>Meals</h1>
-      <p>Manage the meals available for AJ2025...</p>
-      
-      <PagePermissionGuard 
-        pageName="meals" 
-        operation="read"
-        fallback={
-          <div className="min-h-screen flex items-center justify-center">
-            <div className="text-center">
-              <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-sec-900 mx-auto mb-4"></div>
-              <p>Loading permissions...</p>
-            </div>
-          </div>
-        }
-      >
-        <DataTable
-          data={processedMeals || []}
-          columns={columns}
-          rbac={{
-            resource: 'meals',
-            pageId: 'meals'
-          }}
-          // ... other props
-        />
-      </PagePermissionGuard>
-    </div>
-  );
-}
-```
-
-## Expected Results After Fix
-
-After implementing the fix, you should see:
-
-1. ✅ Only one `PagePermissionGuard` instance in console
-2. ✅ No infinite re-render warnings
-3. ✅ `RENDERING CONTENT STATE` appears once
-4. ✅ Access Denied modal disappears
-5. ✅ DataTable content becomes visible
-
-## Files to Check
-
-1. **Meals component** - Look for multiple PagePermissionGuard wrappers
-2. **Parent components** - Check for conditional rendering
-3. **State management** - Look for infinite re-render causes
-4. **CSS files** - Check for modal z-index conflicts
-
-## Debugging Tools
-
-1. **React DevTools** - Check component tree for multiple instances
-2. **Browser DevTools** - Check for multiple modal elements
-3. **Console logs** - Look for infinite re-render warnings
-
-## Contact Information
-
-If you need further assistance after implementing these fixes, please provide:
-
-1. The complete Meals component code
-2. Console logs after adding the diagnostic code
-3. Screenshots of React DevTools component tree
-4. Any parent component that renders the Meals component
-
----
-
-**Note**: This is confirmed to be a Cake application issue, not a pace-core bug. The pace-core component is working correctly as evidenced by the console logs showing proper permission resolution and state management.

package/docs/troubleshooting/database-view-compatibility.md

@@ -1,125 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# Database View Compatibility
-
-## Problem: "column reference 'user_id' is ambiguous" Error
-
-If you're seeing errors like:
-```
-column reference 'user_id' is ambiguous
-```
-
-This typically occurs when your database uses **views** instead of base tables for `organisation_memberships` or `rbac_organisation_roles`, and these views join multiple tables that both contain `user_id` columns.
-
-## Understanding the Issue
-
-@jmruthers/pace-core expects these tables to be simple base tables:
-- `organisation_memberships`
-- `rbac_organisation_roles` 
-- `organisations`
-
-When your database uses **views with complex joins** for these table names, PostgreSQL cannot determine which `user_id` column to use in queries, causing the "ambiguous column reference" error.
-
-## Solution 1: Apply Compatibility Migration (Recommended)
-
-@jmruthers/pace-core includes a compatibility migration that provides SQL functions to handle this scenario.
-
-### Step 1: Apply the Migration
-Copy the migration file to your Supabase project:
-
-```bash
-# Copy the migration to your project
-cp node_modules/@jmruthers/pace-core/supabase/migrations/20250202000001_add_view_compatibility_functions.sql supabase/migrations/
-
-# Apply the migration
-supabase db push
-```
-
-### Step 2: Verify Functions Are Created
-The migration creates these functions:
-- `get_user_organisation_memberships(target_user_id UUID)`
-- `get_user_organisation_roles(target_user_id UUID, org_ids UUID[])`
-
-@jmruthers/pace-core will automatically detect and use these functions when it encounters ambiguous column errors.
-
-## Solution 2: Modify Your Database Views
-
-If you prefer to modify your database views instead, ensure they qualify column names explicitly:
-
-```sql
--- Example: Fix ambiguous columns in a view
-CREATE OR REPLACE VIEW organisation_memberships AS
-SELECT 
-    om.id,
-    om.user_id,        -- Explicitly qualify with table alias
-    om.organisation_id,
-    om.is_primary,
-    om.joined_at,
-    om.status,
-    om.created_at,
-    om.updated_at,
-    om.created_by,
-    om.updated_by,
-    -- Include other joined data with different column names
-    u.email as user_email,  -- Avoid column name conflicts
-    o.name as org_name
-FROM organisation_memberships_base om
-JOIN users u ON u.id = om.user_id
-JOIN organisations o ON o.id = om.organisation_id;
-```
-
-## Solution 3: Use Base Tables
-
-If possible, use base tables instead of views for the core @jmruthers/pace-core tables:
-- `organisation_memberships`
-- `rbac_organisation_roles`
-- `organisations`
-
-Keep your complex views with different names and use them for your application-specific queries.
-
-## Error Detection and Fallback
-
-@jmruthers/pace-core v0.3.17+ includes automatic detection of this issue:
-
-1. **First attempt**: Standard table query
-2. **Ambiguous error detected**: Automatically tries compatibility functions
-3. **Functions not available**: Provides clear error message with migration instructions
-
-## Missing user_profiles Table
-
-If you're also seeing "table 'user_profiles' doesn't exist":
-
-This table is not required by @jmruthers/pace-core. If your application needs it, create it separately:
-
-```sql
-CREATE TABLE user_profiles (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
-    display_name TEXT,
-    avatar_url TEXT,
-    created_at TIMESTAMPTZ DEFAULT NOW(),
-    updated_at TIMESTAMPTZ DEFAULT NOW()
-);
-```
-
-## Testing Your Fix
-
-After applying the fix, test that @jmruthers/pace-core loads correctly:
-
-1. Clear your browser cache/localStorage
-2. Reload your application
-3. Check the console for @jmruthers/pace-core organisation loading messages
-4. Verify no "ambiguous column reference" errors appear
-
-## Need Help?
-
-If you're still experiencing issues:
-
-1. Check your database views and their column names
-2. Ensure the compatibility migration was applied successfully
-3. Review the browser console for detailed error messages
-4. Consider simplifying your database views for the core @jmruthers/pace-core tables