@jmruthers/pace-core 0.6.5 → 0.6.7

package/cursor-rules/00-pace-core-compliance.mdc

@@ -1,331 +0,0 @@
----
-description: Enforce pace-core usage patterns and prevent custom solutions when pace-core provides functionality
-globs: ["src/**/*.{ts,tsx,js,jsx}"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# pace-core Compliance Guide
-
-This guide ensures consuming apps use pace-core components, hooks, and utilities correctly, preventing duplication and maintaining consistency across the PACE suite.
-
-## 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.
-
-### Components
-
-**MUST use pace-core components:**
-- `Button`, `Card`, `Input`, `Label`, `Textarea` - Basic UI components
-- `Dialog`, `Select`, `Tabs`, `Calendar`, `Toast`, `Tooltip` - Advanced UI components
-- `DataTable` - Complex data tables with RBAC integration
-- `Form`, `FormField`, `LoginForm` - Form components
-- `Header`, `Footer`, `PaceAppLayout` - Layout components
-- `FileUpload`, `FileDisplay` - Storage components
-
-**MUST NOT:**
-- Create custom button components when `Button` from pace-core exists
-- Use native HTML elements (`<button>`, `<input>`) when pace-core provides components
-- Import directly from `@radix-ui/*` - Use pace-core wrappers instead
-- Import directly from `lucide-react` - Use pace-core components that include icons
-
-**Example:**
-```tsx
-// ❌ WRONG: <button className="btn">Click me</button>
-// ✅ CORRECT: import { Button } from '@jmruthers/pace-core'; <Button>Click me</Button>
-```
-
-### Hooks
-
-**MUST use pace-core hooks:**
-- `useUnifiedAuth`, `useEvents`, `useOrganisations` - Authentication and data
-- `usePermissions`, `useCan`, `useSecureSupabase` - RBAC hooks
-- `useToast`, `useDebounce`, `useZodForm` - Utility hooks
-- `useFileReference`, `useFileUpload` - File management hooks
-
-**MUST NOT:**
-- Create custom `useAuth` when `useUnifiedAuth` exists
-- Create custom `useToast` when pace-core provides it
-- Create custom `useDebounce` when pace-core provides it
-- Create custom form hooks when `useZodForm` exists
-
-**Example:**
-```tsx
-// ❌ WRONG: Custom useDebounce hook implementation
-// ✅ CORRECT: import { useDebounce } from '@jmruthers/pace-core'; const debouncedValue = useDebounce(value, 500);
-```
-
-### Utilities
-
-**MUST use pace-core utilities:**
-- `cn` - Class name utility (replaces clsx/tailwind-merge)
-- `formatDate`, `formatTime`, `formatDateTime` - Date formatting
-- `formatCurrency`, `formatNumber`, `formatPercent` - Number formatting
-- `emailSchema`, `nameSchema`, `passwordSchema` - Validation schemas
-- `validateUserInput`, `sanitizeUserInput` - Input validation
-
-**MUST NOT:**
-- Create custom `formatDate` when pace-core provides it
-- Use `clsx` directly - Use `cn` from pace-core
-- Create custom validation when pace-core schemas exist
-
-**Example:**
-```tsx
-// ❌ WRONG: Custom formatDate implementation
-// ✅ CORRECT: import { formatDate } from '@jmruthers/pace-core'; const formatted = formatDate(date);
-```
-
-## MUST: Use Secure Supabase Client
-
-**You MUST use `useSecureSupabase()` for all database operations.** Never use the base Supabase client directly.
-
-**CRITICAL SECURITY REQUIREMENT:** Using `createClient()` from `@supabase/supabase-js` directly bypasses organisation context enforcement and RLS policies, which can lead to:
-- Cross-organisation data access
-- Security vulnerabilities  
-- Data leakage between organisations
-
-```tsx
-// ❌ WRONG: Direct Supabase client creation
-import { createClient } from '@supabase/supabase-js';
-const supabase = createClient(url, key);
-// This bypasses organisation context and RLS policies!
-
-// ✅ CORRECT: Use secure Supabase client
-import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
-const secureSupabase = useSecureSupabase();
-// Organisation context is automatically enforced
-```
-
-### Detection and Enforcement
-
-pace-core provides multiple layers of protection:
-
-1. **ESLint Rule**: The `no-direct-supabase-client` rule detects `createClient` calls and reports errors
-2. **Runtime Warnings**: Development mode warnings when insecure clients are detected
-3. **Type Safety**: Use `isSecureClient()` to verify clients are secure
-
-```tsx
-// Verify client is secure (optional, but recommended)
-import { isSecureClient, warnIfInsecureClient } from '@jmruthers/pace-core/rbac/utils/clientSecurity';
-
-const supabase = useSecureSupabase();
-warnIfInsecureClient(supabase, 'MyComponent'); // Warns in dev if insecure
-
-if (isSecureClient(supabase)) {
-  // Client is secure, safe to use
-}
-```
-
-## MUST: Setup RBAC Before Use
-
-**You MUST call `setupRBAC()` before any RBAC usage.** This is non-negotiable.
-
-```tsx
-// main.tsx - MUST be first
-import { setupRBAC } from '@jmruthers/pace-core/rbac';
-setupRBAC(supabase);
-// Then render app
-```
-
-## 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.
-
-### Where to Find Documentation
-
-**Component API Reference:**
-- Location: `node_modules/@jmruthers/pace-core/docs/api-reference/components.md`
-- Or: Check pace-core repository `packages/core/docs/api-reference/components.md`
-- Contains: Complete prop definitions, type information, usage examples
-
-**Implementation Guides:**
-- Location: `node_modules/@jmruthers/pace-core/docs/implementation-guides/`
-- Contains: Detailed guides for complex components like DataTable, Forms, etc.
-- Examples:
-  - `data-tables.md` - DataTable component guide
-  - `forms.md` - Form components guide
-  - `file-upload-storage.md` - FileUpload/FileDisplay guide
-
-**Detailed API Documentation:**
-- Location: `node_modules/@jmruthers/pace-core/docs/api/`
-- Contains: In-depth API documentation for all exports
-
-**Quick Reference:**
-- Location: `node_modules/@jmruthers/pace-core/docs/getting-started/quick-reference.md`
-- Contains: Quick lookup for common patterns
-
-### How to Find Component-Specific Docs
-
-1. **Check API Reference First:**
-   ```bash
-   # In your consuming app
-   cat node_modules/@jmruthers/pace-core/docs/api-reference/components.md
-   ```
-
-2. **Search Implementation Guides:**
-   - Look for component name in `implementation-guides/` directory
-   - Complex components have dedicated guides
-
-3. **Check Type Definitions:**
-   ```tsx
-   // Import and check TypeScript types
-   import type { DataTableProps } from '@jmruthers/pace-core';
-   // Hover over type to see prop definitions
-   ```
-
-4. **Use IDE IntelliSense:**
-   - TypeScript types provide inline documentation
-   - Hover over component name to see prop types
-   - Use autocomplete to discover available props
-
-### MUST NOT: Guess About Props or Usage
-
-**❌ WRONG - Guessing props:**
-```tsx
-<DataTable data={data} columns={columns} /> // Missing required rbac prop
-```
-
-**✅ CORRECT - Read documentation first:**
-```tsx
-import { DataTable } from '@jmruthers/pace-core';
-<DataTable data={data} columns={columns} rbac={{ pageName: 'users' }} features={{ search: true }} />
-```
-
-### Documentation Checklist
-
-Before using any pace-core component:
-- [ ] Read component API reference
-- [ ] Check for implementation guide if component is complex
-- [ ] Review TypeScript types for prop definitions
-- [ ] Check examples in documentation
-- [ ] Verify required vs optional props
-- [ ] Understand component behavior and limitations
-
-### Common Documentation Locations
-
-| Component Type | Documentation Location |
-|----------------|----------------------|
-| Basic UI (Button, Card, etc.) | `api-reference/components.md` |
-| DataTable | `implementation-guides/data-tables.md` |
-| Forms | `implementation-guides/forms.md` |
-| RBAC Components | `rbac/getting-started.md` |
-| File Upload/Display | `implementation-guides/file-upload-storage.md` |
-| Hooks | `api-reference/hooks.md` |
-| Utilities | `api-reference/utilities.md` |
-
-## SHOULD: Check pace-core Before Creating New Components
-
-**Before creating a new component, hook, or utility:**
-
-1. Check pace-core exports: `@jmruthers/pace-core`
-2. Review pace-core documentation
-3. Check `core-usage-manifest.json` for available exports
-4. Search pace-core source if needed
-
-**If pace-core doesn't provide what you need:**
-- Consider if it should be added to pace-core (for shared use)
-- Document why custom solution is needed
-- Follow pace-core patterns for consistency
-
-## MUST: Use pace-core Providers
-
-**You MUST wrap your app with required providers:**
-
-```tsx
-import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
-<UnifiedAuthProvider supabaseClient={supabase} appName="Your App">
-  <OrganisationProvider>{/* Your app */}</OrganisationProvider>
-</UnifiedAuthProvider>
-```
-
-## MUST: Import Core Styles
-
-**You MUST import pace-core styles:**
-
-```tsx
-// main.tsx or App.tsx
-import '@jmruthers/pace-core/styles/core.css';
-```
-
-## MUST NOT: Use Inline Styles
-
-**You MUST NOT use inline styles (`style={{...}}`).** All styling MUST come from pace-core components and Tailwind classes.
-
-### Why No Inline Styles
-
-- Inline styles override pace-core component styles
-- Inline styles break consistency across the PACE suite
-- Inline styles are harder to maintain and update
-- Inline styles don't benefit from theme variables and design system
-
-### Use pace-core Components for Styling
-
-**All styling MUST come from:**
-1. **pace-core components** - Components already have correct styling
-2. **Tailwind utility classes** - Use Tailwind classes for layout and spacing
-3. **Semantic classes** - Use semantic classes from pace-core (e.g., `bg-background`, `text-foreground`)
-
-**MUST NOT:**
-- Use `style={{...}}` prop
-- Use inline CSS strings
-- Override component styles with inline styles
-- Create custom CSS for styling that pace-core provides
-
-**Example:**
-```tsx
-// ❌ WRONG: <div style={{ backgroundColor: 'blue' }}> or <Button style={{...}}>
-// ✅ CORRECT: <Card className="bg-main-500 p-4"> or <Button variant="default"> or <div className="flex gap-4">
-```
-
-### When Tailwind Classes Are Acceptable
-
-**Tailwind classes are acceptable for:**
-- Layout (flex, grid, positioning)
-- Spacing (margin, padding, gap)
-- Responsive design (breakpoints)
-- Layout-specific styling not provided by pace-core components
-
-**Tailwind classes MUST NOT:**
-- Override pace-core component internal styles
-- Duplicate styling that pace-core components already provide
-- Use standard Tailwind colors (use `main-*`, `sec-*`, `acc-*` namespaces)
-
-### Styling Checklist
-
-Before adding any styling:
-- [ ] Check if pace-core component provides the styling you need
-- [ ] Use pace-core component variants/props for styling
-- [ ] Use Tailwind classes only for layout/spacing
-- [ ] Never use inline `style={{...}}` prop
-- [ ] Never override component styles with inline styles
-- [ ] Use semantic classes (`bg-background`, `text-foreground`) when available
-
-## SHOULD: Use pace-core Patterns
-
-**Follow pace-core patterns for consistency:**
-- Component structure and composition
-- Error handling patterns
-- Loading state patterns
-- Form validation patterns
-- RBAC permission checking patterns
-
-## 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
-
-## Reference
-
-- **pace-core Exports**: See `pace-core-exports.mdc` for complete export reference
-- **RBAC Implementation**: See `rbac-implementation.mdc` 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/`
-  - Detailed API: `node_modules/@jmruthers/pace-core/docs/api/`
-- **Always read documentation before using components** - Never guess about props or usage

package/cursor-rules/01-standards-compliance.mdc

@@ -1,244 +0,0 @@
----
-description: Enforce compliance with all pace-core standards across architecture, API, components, code style, security, testing, and RBAC/RLS
-globs: ["src/**/*.{ts,tsx,js,jsx}", "supabase/migrations/**/*.sql"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# Standards Compliance Guide
-
-This guide ensures consuming apps comply with all pace-core standards. Follow these standards to maintain quality, security, and consistency.
-
-## Architecture Standard
-
-### MUST: Follow Architecture Principles
-
-**MUST adhere to:**
-- Composition over complexity
-- Separation of concerns
-- Domain-agnostic design
-- Extensible, stable APIs
-- Secure by default
-- Performance-conscious
-
-### MUST: Use Helper Functions in RLS Policies
-
-**RLS policies MUST use helper functions, NEVER subqueries.**
-
-```sql
--- ❌ WRONG: Subquery in RLS policy (causes N+1 queries)
-CREATE POLICY rbac_select_users ON users FOR SELECT USING (
-  organisation_id IN (SELECT organisation_id FROM organisation_memberships WHERE user_id = auth.uid())
-);
-
--- ✅ CORRECT: Helper function with STABLE SECURITY DEFINER
-CREATE OR REPLACE FUNCTION get_user_organisation_ids() RETURNS uuid[] LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path TO public AS $$
-BEGIN RETURN ARRAY(SELECT organisation_id FROM organisation_memberships WHERE user_id = get_effective_user_id()); END;
-$$;
-CREATE POLICY rbac_select_users ON users FOR SELECT USING (organisation_id = ANY(get_user_organisation_ids()));
-```
-
-### MUST: Test Database Migrations
-
-**MUST verify migrations don't cause query timeouts or performance degradation.**
-
-## API & RPC Standard
-
-### MUST: Follow RPC Naming Convention
-
-**RPCs MUST follow pattern: `<family>_<domain>_<verb>`**
-
-- `data_*` prefix for read operations: `data_cake_dishes_list`, `data_file_reference_list`
-- `app_*` prefix for write operations: `app_cake_dish_create`, `app_cake_dish_update`
-- CRUD verbs only: `create`, `read`, `update`, `delete`, `list`, `get`
-- Bulk operations: `_bulk` suffix (e.g., `app_cake_dish_create_bulk`)
-
-```sql
--- ✅ CORRECT: data_cake_dishes_list, app_cake_dish_create, app_cake_dish_create_bulk
--- ❌ WRONG: getDishes, create_dish (wrong naming pattern)
-```
-
-### MUST: Use ApiResult Shape
-
-**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 };
-```
-
-### MUST: Enforce RLS in RPCs
-
-**RPCs MUST enforce RLS and tenant boundaries.** Never bypass RLS.
-
-### SHOULD: Make Write RPCs Idempotent
-
-**Write RPCs SHOULD be idempotent when possible.**
-
-## Component Standard
-
-### 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
-
-## Code Style Standard
-
-### MUST: Follow TypeScript Rules
-
-**MUST:**
-- Use strict mode (`strict: true` in tsconfig)
-- Prefer discriminated unions
-- Use ReadonlyArray where possible
-- Avoid boolean mode flags (use unions instead)
-
-**MUST NOT:**
-- Use `any` (use `unknown` if type is truly unknown)
-- Use implicit any
-- Use unnecessary type assertions
-
-### MUST: Follow Naming Conventions
-
-- Hooks: `useSomething`
-- Providers: `SomethingProvider`
-- Utilities: `camelCase`
-- Components: `PascalCase`
-
-### SHOULD: Use Preferred Patterns
-
-**SHOULD:**
-- Use pure functions
-- Prefer composition over inheritance
-- Use early returns
-- Extract large functions into small helpers
-
-## Security Standard
-
-### MUST: Never Bypass RLS
-
-**MUST enforce RLS on all tables.** Never bypass RLS policies.
-
-### MUST: Validate All Inputs
-
-**MUST validate all inputs using Zod schemas or similar.**
-
-### MUST: Sanitize Logs
-
-**MUST NOT log:**
-- Passwords
-- Tokens
-- Sensitive data (PII)
-
-**MAY log:**
-- IDs
-- Non-PII metadata
-
-### MUST: Use Safe Error Messaging
-
-**MUST NOT expose internal details in error messages.**
-
-### MUST: Use Helper Functions in RLS
-
-**RLS policies MUST use STABLE SECURITY DEFINER helper functions:**
-- `STABLE` - Results consistent within transaction
-- `SECURITY DEFINER` - Bypass RLS to avoid recursion
-- `SET search_path TO 'public'` - Prevent search path injection
-
-## Testing Standard
-
-### MUST: Meet Coverage Requirements
-
-**MUST achieve:**
-- ≥90% coverage for utils & hooks
-- ≥70% coverage for components
-
-### MUST: Use React Testing Library
-
-**MUST use React Testing Library + userEvent for component tests.**
-
-### SHOULD: Colocate Tests
-
-**Tests SHOULD be colocated: `*.test.ts` or `*.test.tsx`**
-
-### SHOULD: Test Critical Paths
-
-**SHOULD test:**
-- Key user interactions
-- Error handling
-- Edge cases
-- Critical business logic
-
-## RBAC & RLS Standard
-
-### MUST: Use Helper Functions
-
-**All RLS policies MUST use helper functions with:**
-- `STABLE` attribute
-- `SECURITY DEFINER` attribute
-- `SET search_path TO 'public'`
-
-### MUST: Follow Policy Naming
-
-**RLS policies MUST follow pattern: `rbac_{operation}_{table_name}_{scope}`**
-
-Example: `rbac_select_users_organisation`
-
-### MUST: Include Organisation Context
-
-**RLS policies MUST include `organisation_id` for multi-tenant isolation.**
-
-### MUST: Include Super Admin Checks
-
-**RLS policies SHOULD include super admin checks where appropriate.**
-
-## Standards Precedence
-
-When standards conflict, follow this order:
-1. Security Standard (highest priority)
-2. API & RPC Standard
-3. Component Standard
-4. Code Style Standard
-5. Testing Standard
-6. Documentation Standard
-
-## Compliance Checklist
-
-Before committing code, verify:
-- [ ] RLS policies use helper functions (no subqueries)
-- [ ] RPCs follow naming convention
-- [ ] Components are accessible and typed
-- [ ] No `any` types used
-- [ ] Inputs are validated
-- [ ] Tests meet coverage requirements
-- [ ] No sensitive data in logs
-- [ ] Error messages are safe
-
-## Reference
-
-See `packages/core/docs/standards/` for complete standards documentation:
-- 01-architecture-standard.md
-- 02-api-and-rpc-standard.md
-- 03-component-standard.md
-- 04-code-style-standard.md
-- 05-security-standard.md
-- 06-testing-and-docs-standard.md
-- 07-rbac-and-rls-standard.md