@jmruthers/pace-core 0.6.6 → 0.6.7

package/cursor-rules/{00-pace-core-compliance.mdc → 01-pace-core-compliance.mdc}

@@ -7,15 +7,41 @@ rulesVersion: "2025-01-28"
 ---
 # pace-core Compliance Guide
 
-**📚 Human-Readable Standard**: See [00-pace-core-compliance.md](../../packages/core/docs/standards/00-pace-core-compliance.md) for complete documentation.
+**📚 Human-Readable Standard**: See [1-pace-core-compliance-standards.md](../../packages/core/docs/standards/1-pace-core-compliance-standards.md) for complete documentation.
 
 This guide ensures consuming apps use pace-core components, hooks, and utilities correctly, preventing duplication and maintaining consistency across the PACE suite.
 
-This guide ensures consuming apps use pace-core components, hooks, and utilities correctly, preventing duplication and maintaining consistency across the PACE suite.
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Check pace-core first** - Before creating any component, hook, or utility, verify if pace-core provides it
+2. **Use pace-core components** - Never use native HTML elements (`<button>`, `<input>`) when pace-core provides components
+3. **Use pace-core hooks** - Never create custom hooks when pace-core provides equivalent functionality
+4. **Use secure Supabase client** - Always use `useSecureSupabase()`, never `createClient()` for queries
+5. **Read documentation** - Before using any pace-core component, check its documentation for required props and usage patterns
+6. **Follow provider nesting** - Always nest providers in the correct order (QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider)
+7. **Configure Vite correctly** - Always exclude `@jmruthers/pace-core` and `react-router-dom` from pre-bundling
+
+**Decision Tree: Should I create this or use pace-core?**
+```
+1. What am I trying to create?
+   ├─ Component (Button, Input, Card, etc.) → Use pace-core
+   ├─ Hook (auth, permissions, debounce, etc.) → Use pace-core
+   ├─ Utility (formatDate, cn, validation, etc.) → Use pace-core
+   └─ App-specific domain logic → Create custom (but follow pace-core patterns)
+
+2. Does pace-core provide this?
+   ├─ YES → Use pace-core (import from '@jmruthers/pace-core')
+   └─ NO → Check if it should be added to pace-core (for shared use)
+
+3. Am I about to use native HTML?
+   ├─ YES → Check if pace-core has equivalent component
+   └─ NO → Continue
+```
 
 ## MUST: Use pace-core Instead of Custom Solutions
 
-**You MUST use pace-core components, hooks, and utilities when they exist.** Creating custom solutions duplicates functionality and breaks consistency.
+**ALWAYS use pace-core components, hooks, and utilities when they exist.** Creating custom solutions duplicates functionality and breaks consistency.
 
 ### Components
 
@@ -33,10 +59,28 @@ This guide ensures consuming apps use pace-core components, hooks, and utilities
 - Import directly from `@radix-ui/*` - Use pace-core wrappers instead
 - Import directly from `lucide-react` - Import icons from `@jmruthers/pace-core/icons` instead
 
-**Example:**
+**Examples:**
 ```tsx
-// ❌ WRONG: <button className="btn">Click me</button>
-// ✅ CORRECT: import { Button } from '@jmruthers/pace-core'; <Button>Click me</Button>
+// ❌ WRONG: Native HTML button
+<button className="btn-primary" onClick={handleClick}>
+  Click me
+</button>
+
+// ✅ CORRECT: pace-core Button component
+import { Button } from '@jmruthers/pace-core';
+<Button onClick={handleClick}>Click me</Button>
+
+// ❌ WRONG: Native HTML input
+<input 
+  type="text" 
+  className="form-input" 
+  value={value} 
+  onChange={handleChange} 
+/>
+
+// ✅ CORRECT: pace-core Input component
+import { Input } from '@jmruthers/pace-core';
+<Input type="text" value={value} onChange={handleChange} />
 ```
 
 ### Hooks
@@ -81,8 +125,13 @@ This guide ensures consuming apps use pace-core components, hooks, and utilities
 
 ## MUST: Use Secure Supabase Client
 
-**All database operations MUST use `useSecureSupabase()` (or the contract-approved pace-core secure client wrapper).**
-Consuming apps **MUST NOT** use the base Supabase client directly for queries.
+**ALWAYS use `useSecureSupabase()` for all database operations.** Never use the base Supabase client directly for queries.
+
+**When writing database code:**
+1. Import: `import { useSecureSupabase } from '@jmruthers/pace-core/rbac'`
+2. Call hook: `const secureSupabase = useSecureSupabase()`
+3. Use for queries: `await secureSupabase.from('table').select('*')`
+4. Never use: `createClient()` for queries (only for provider setup)
 
 ### Hard Requirements
 
@@ -174,16 +223,11 @@ const { data } = await supabase.from('users').select('*'); // Bypasses RLS
 
 **NO OTHER EXCEPTIONS ARE PERMITTED** - All other uses of `createClient()` are security violations and MUST be fixed.
 
-### Detection / Audit
-
-- `rg "createClient\(" src` must return **exactly ONE match** in the file that creates the base client for `UnifiedAuthProvider`.
-- That file MUST be one of: `main.tsx`, `App.tsx`, or `lib/supabase.ts` (or `.jsx`/`.js` equivalents).
-- No `.from(` / `.rpc(` calls may be performed on an insecure client reference.
-- All `useSecureSupabase()` calls should be without parameters.
+**Note**: System-level validation of Supabase client usage is handled by the audit tool. See [1-pace-core-compliance-standards.md](../../packages/core/docs/standards/1-pace-core-compliance-standards.md) for complete enforcement details.
 
 ## MUST: Setup RBAC Before Use
 
-**You MUST call `setupRBAC()` before any RBAC usage.** This is non-negotiable.
+**ALWAYS call `setupRBAC()` before any RBAC usage.** This is non-negotiable.
 
 ```tsx
 // main.tsx - MUST be first
@@ -194,7 +238,7 @@ setupRBAC(supabase);
 
 ## MUST: Read Documentation Before Using Components
 
-**You MUST read pace-core component documentation before using any component.** Never guess about props, usage patterns, or behavior.
+**ALWAYS read pace-core component documentation before using any component.** Never guess about props, usage patterns, or behavior.
 
 ### Where to Find Documentation
 
@@ -292,20 +336,97 @@ Before using any pace-core component:
 - Document why custom solution is needed
 - Follow pace-core patterns for consistency
 
-## MUST: Use pace-core Providers
+## MUST: Provider Nesting Order
 
-**You MUST wrap your app with required providers:**
+**⚠️ CRITICAL: Provider nesting order matters!** Incorrect nesting causes React context errors.
+
+**MUST** nest providers in this exact order (outermost to innermost):
+
+1. `QueryClientProvider` (outermost)
+2. `BrowserRouter`
+3. `UnifiedAuthProvider`
+4. `OrganisationProvider`
+5. `App` (innermost)
 
 ```tsx
+// ✅ CORRECT: main.tsx
+import { BrowserRouter } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
-<UnifiedAuthProvider supabaseClient={supabase} appName="Your App">
-  <OrganisationProvider>{/* Your app */}</OrganisationProvider>
-</UnifiedAuthProvider>
+import { createClient } from '@supabase/supabase-js';
+
+const queryClient = new QueryClient();
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+);
+
+createRoot(document.getElementById("root")!).render(
+  <QueryClientProvider client={queryClient}>
+    <BrowserRouter>
+      <UnifiedAuthProvider supabaseClient={supabase} appName="YourApp">
+        <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)
+
+## MUST: Vite Configuration
+
+**⚠️ CRITICAL: Vite configuration prevents React context mismatches!**
+
+**MUST** configure Vite to exclude `@jmruthers/pace-core` and `react-router-dom` from pre-bundling:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+    // CRITICAL: Dedupe React dependencies
+    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
+- `react-router-dom` must also be excluded and deduped to prevent Router context errors
+
+**If you encounter context errors:**
+1. Verify `@jmruthers/pace-core` is in `optimizeDeps.exclude`
+2. Verify `react-router-dom` is in both `resolve.dedupe` and `optimizeDeps.exclude`
+3. Clear Vite cache: `rm -rf node_modules/.vite`
+4. Restart dev server
+
 ## MUST: Import Core Styles
 
-**You MUST import pace-core styles via app.css:**
+**ALWAYS import pace-core styles via app.css:**
 
 The correct pattern is a two-file CSS architecture:
 1. `src/app.css` - Contains `@import "@jmruthers/pace-core/styles/core.css";` (CSS @import)
@@ -326,11 +447,11 @@ import './app.css';  // ✅ CORRECT - app.css imports core.css
 - Import `core.css` directly in `main.tsx` or `App.tsx` - This causes duplicate imports
 - Use JavaScript import for `core.css` - Use CSS `@import` in `app.css` instead
 
-**See [08-markup-quality.md](../../packages/core/docs/standards/08-markup-quality.md) for complete CSS setup instructions.**
+**See [5-styling-standards.md](../../packages/core/docs/standards/5-styling-standards.md) for complete CSS setup instructions.**
 
 ## MUST NOT: Use Inline Styles
 
-**You MUST NOT use inline styles (`style={{...}}`).** All styling MUST come from pace-core components and Tailwind classes.
+**NEVER use inline styles (`style={{...}}`).** All styling MUST come from pace-core components and Tailwind classes.
 
 ### Why No Inline Styles
 
@@ -392,14 +513,46 @@ Before adding any styling:
 
 ## Common Mistakes to Avoid
 
-1. **Using inline styles** - Never use `style={{...}}`, use pace-core components and Tailwind classes
-2. **Guessing component props** - Always read documentation first
-3. **Creating duplicate components** - Always check pace-core first
-4. **Using base Supabase client** - Always use `useSecureSupabase()`
-5. **Missing RBAC setup** - Always call `setupRBAC()` first
-6. **Missing providers** - Always wrap with required providers
-7. **Missing styles** - Always import core.css
-8. **Direct library imports** - Use pace-core wrappers instead
+**When writing code, NEVER:**
+1. **Use native HTML when pace-core provides components** - Always check pace-core first
+   ```tsx
+   // ❌ WRONG
+   <button>Click</button>
+   <input type="text" />
+   
+   // ✅ CORRECT
+   <Button>Click</Button>
+   <Input type="text" />
+   ```
+
+2. **Create wrapper functions around pace-core hooks** - Use hooks directly
+   ```tsx
+   // ❌ WRONG
+   function useMyAuth() {
+     const auth = useUnifiedAuth();
+     return { user: auth.user, isAdmin: auth.user?.role === 'admin' };
+   }
+   
+   // ✅ CORRECT
+   const { user } = useUnifiedAuth();
+   const { canManage } = useCan(user?.id, scope, 'manage:users');
+   ```
+
+3. **Use createClient() for queries** - Always use `useSecureSupabase()`
+   ```tsx
+   // ❌ WRONG
+   const supabase = createClient(url, key);
+   const { data } = await supabase.from('users').select('*');
+   
+   // ✅ CORRECT
+   const secureSupabase = useSecureSupabase();
+   const { data } = await secureSupabase.from('users').select('*');
+   ```
+
+4. **Guess component props** - Always read documentation first
+5. **Use inline styles** - Use pace-core components and Tailwind classes
+6. **Skip provider nesting** - Always nest in correct order
+7. **Skip Vite configuration** - Always exclude pace-core from pre-bundling
 
 ## Compliance Exceptions
 
@@ -424,8 +577,8 @@ If you encounter a situation where a rule seems to conflict with a legitimate re
 
 ## Reference
 
-- **pace-core Exports**: See `pace-core-exports.mdc` for complete export reference
-- **RBAC Implementation**: See `rbac-implementation.mdc` for RBAC patterns
+- **pace-core Exports**: See [pace-core documentation](../../packages/core/docs/README.md) for complete export reference
+- **RBAC Implementation**: See [6-security-rbac-standards.md](../../packages/core/docs/standards/6-security-rbac-standards.md) for RBAC patterns
 - **Component Documentation**: 
   - API Reference: `node_modules/@jmruthers/pace-core/docs/api-reference/components.md`
   - Implementation Guides: `node_modules/@jmruthers/pace-core/docs/implementation-guides/`

package/cursor-rules/02-project-structure.mdc

@@ -7,10 +7,42 @@ rulesVersion: "2025-01-28"
 ---
 # Project Structure Standard
 
-**📚 Human-Readable Standard**: See [02-project-structure.md](../../packages/core/docs/standards/02-project-structure.md) for complete documentation including migration guides and detailed examples.
+**📚 Human-Readable Standard**: See [2-project-structure-standards.md](../../packages/core/docs/standards/2-project-structure-standards.md) for complete documentation including migration guides and detailed examples.
 
 This guide defines the standard folder structure and file organization for consuming apps in the PACE suite.
 
+## AI Agent Instructions
+
+**When creating or organizing files, ALWAYS:**
+1. **Organize by feature** - Group components, hooks, and utilities by feature/domain, not by type
+2. **Colocate tests** - Place test files next to source files (`Component.test.tsx` next to `Component.tsx`)
+3. **Follow naming conventions** - Components: `PascalCase.tsx`, Hooks: `use*.ts`, Utils: `camelCase.ts`
+4. **Use absolute imports** - Use `@/` path alias for imports, never relative imports for distant files
+5. **Keep root clean** - Only configuration files and documentation in root, never source files
+6. **Place migrations correctly** - All migrations in `supabase/migrations/` with timestamp format
+
+**Decision Tree: File Organization**
+```
+1. Where should this file go?
+   ├─ Component → src/components/<feature>/ComponentName.tsx
+   ├─ Hook → src/hooks/useHookName.ts (or colocated with component)
+   ├─ Utility → src/utils/utilityName.ts
+   ├─ Type → src/types/typeName.ts (or colocated with feature)
+   ├─ Test → Next to source file (ComponentName.test.tsx)
+   └─ Migration → supabase/migrations/YYYYMMDDHHMMSS_description.sql
+
+2. How should I name it?
+   ├─ Component → PascalCase (EventCard.tsx)
+   ├─ Hook → camelCase with use prefix (useEventData.ts)
+   ├─ Utility → camelCase (formatEvent.ts)
+   └─ Test → Same as source + .test (EventCard.test.tsx)
+
+3. Should I use absolute or relative imports?
+   ├─ Same directory → Relative (./Component)
+   ├─ Different directory → Absolute (@/components/events/EventCard)
+   └─ pace-core → Package import (@jmruthers/pace-core)
+```
+
 ## MUST: Follow Standard Directory Structure
 
 **Consuming apps MUST follow this structure:**
@@ -42,7 +74,7 @@ your-app/
 
 ## MUST: Organize Components by Feature
 
-**Components SHOULD be organized by feature/domain, not by type:**
+**ALWAYS organize components by feature/domain, not by type:**
 
 ```
 src/
@@ -64,7 +96,7 @@ src/
 
 ## MUST: Colocate Tests
 
-**Tests MUST be colocated with source files:**
+**ALWAYS colocate tests with source files:**
 
 ```
 src/
@@ -143,7 +175,7 @@ src/
 
 ## MUST: Use Consistent Import Paths
 
-**MUST use consistent import patterns:**
+**ALWAYS use consistent import patterns:**
 
 ```tsx
 // ✅ CORRECT - Absolute imports from src
@@ -203,4 +235,4 @@ Before committing, verify:
 
 ## Reference
 
-See `project-structure.mdc` in pace-core for detailed structure patterns.
+**Note**: File structure validation is handled by the audit tool. See [2-project-structure-standards.md](../../packages/core/docs/standards/2-project-structure-standards.md) for complete enforcement details.

package/cursor-rules/{03-solid-principles.mdc → 03-architecture.mdc}

@@ -1,15 +1,43 @@
 ---
-description: Enforce SOLID architecture principles in consuming apps
+description: Enforce SOLID architecture principles, component design, and API design patterns
 globs: ["src/**/*.{ts,tsx}"]
 alwaysApply: false
 paceCoreVersion: "0.6.x"
 rulesVersion: "2025-01-28"
 ---
-# SOLID Principles Guide
+# Architecture Standards Guide
 
-**📚 Human-Readable Standard**: See [03-solid-principles.md](../../packages/core/docs/standards/03-solid-principles.md) for complete documentation.
+**📚 Human-Readable Standard**: See [3-architecture-standards.md](../../packages/core/docs/standards/3-architecture-standards.md) for complete documentation.
 
-This guide enforces SOLID architecture principles to ensure maintainable, extensible, and testable code.
+This guide enforces SOLID architecture principles, component design patterns, and API design patterns to ensure maintainable, extensible, and testable code.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Extract complex logic** - Move business logic out of components into hooks, services, or utilities
+2. **Use composition** - Extend functionality through composition, not modification of pace-core components
+3. **Keep components simple** - Components should only handle UI rendering, not data fetching or business logic
+4. **Use focused interfaces** - Create small, specific interfaces instead of large, generic ones
+5. **Depend on abstractions** - Use interfaces/types, not concrete implementations
+6. **Follow ApiResult pattern** - All RPCs must return ApiResult shape with proper error handling
+
+**Decision Tree: Where should this logic live?**
+```
+1. What type of logic is this?
+   ├─ UI rendering → Component
+   ├─ Data fetching → Hook or service
+   ├─ Business logic → Hook, service, or utility
+   ├─ Formatting/transformation → Utility function
+   └─ Validation → Zod schema or utility
+
+2. Is this logic complex?
+   ├─ YES → Extract to hook/service/utility
+   └─ NO → Can stay in component if simple
+
+3. Does this modify pace-core behavior?
+   ├─ YES → Use composition (wrap pace-core component)
+   └─ NO → Continue
+```
 
 ## Single Responsibility Principle (SRP)
 
@@ -206,17 +234,103 @@ Before committing code, verify:
 - [ ] No god objects or bloated components
 - [ ] Code is testable and maintainable
 
-## Anti-Patterns to Avoid
+## Common Mistakes to Avoid
+
+**When writing code, NEVER:**
+1. **Create god objects** - Components/classes that do too much
+   ```tsx
+   // ❌ WRONG: Component does everything
+   function UserDashboard({ userId }) {
+     const [user, setUser] = useState(null);
+     const [events, setEvents] = useState([]);
+     const [organisations, setOrganisations] = useState([]);
+     // 200+ lines of logic...
+   }
+   
+   // ✅ CORRECT: Separated concerns
+   function UserDashboard({ userId }) {
+     const user = useUser(userId);
+     const events = useUserEvents(userId);
+     const organisations = useUserOrganisations(userId);
+     return <DashboardContent user={user} events={events} organisations={organisations} />;
+   }
+   ```
+
+2. **Put business logic in components** - Extract to hooks/services
+3. **Create large interfaces** - Use focused, specific interfaces
+4. **Depend on concrete implementations** - Use abstractions (interfaces/types)
+5. **Modify pace-core components** - Use composition instead
+6. **Use boolean flags for states** - Use discriminated unions
+
+## API Design Patterns
+
+### MUST: Follow API Design Principles
+
+**APIs MUST be:**
+- Intuitive and consistent
+- Extensible without breaking changes
+- Clear about errors and edge cases
+
+### MUST: Use ApiResult Pattern
+
+**All RPCs MUST return ApiResult shape:**
+
+```typescript
+type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError };
+type ApiError = { code: string; message: string; details?: object };
+```
+
+```tsx
+// ✅ CORRECT: RPC returns ApiResult
+const result = await supabase.rpc('app_events_create', { name, date });
+if (!result.ok) {
+  // Handle error
+  return { ok: false, error: result.error };
+}
+return { ok: true, data: result.data };
+```
+
+### SHOULD: Make Write RPCs Idempotent
 
-1. **God Objects** - Classes/components that do too much
-2. **Feature Envy** - Functions that use more of another object than their own
-3. **Data Clumps** - Groups of data that should be objects
-4. **Long Parameter Lists** - Use objects/interfaces instead
-5. **Divergent Change** - One class changed for multiple reasons
-6. **Shotgun Surgery** - One change requires many class modifications
+**Write RPCs SHOULD be idempotent when possible:**
+
+```sql
+-- ✅ CORRECT: Idempotent create (ON CONFLICT DO NOTHING)
+INSERT INTO events (id, name, date)
+VALUES (p_event_id, p_name, p_date)
+ON CONFLICT (id) DO NOTHING;
+```
+
+## Component Design Patterns
+
+### MUST: Follow Component Principles
+
+**Components MUST:**
+- Be stateless when possible
+- Use composable structure
+- Be accessible by default
+- Be fully typed
+- Have small surface area
+
+### MUST NOT: Add Domain Logic to Components
+
+**Components MUST NOT:**
+- Include domain-specific logic
+- Fetch data directly (use hooks/services)
+- Include business workflows
+
+### MUST: Ensure Accessibility
+
+**Components MUST:**
+- Be keyboard operable
+- Have correct ARIA roles
+- Have visible focus states
+- Avoid inaccessible interactions
 
 ## Reference
 
+**Note**: RLS policy validation is handled by the audit tool. See [3-architecture-standards.md](../../packages/core/docs/standards/3-architecture-standards.md) for complete enforcement details.
+
 - Single Responsibility: Each module has one reason to change
 - Open/Closed: Open for extension, closed for modification
 - Liskov Substitution: Subtypes must be substitutable