@jmruthers/pace-core 0.6.6 → 0.6.8

package/cursor-rules/07-tech-stack-compliance.mdc

@@ -1,216 +0,0 @@
----
-description: Enforce tech stack compliance including Tailwind v4, React 19+, Supabase, and other required technologies
-globs: ["src/**/*.{ts,tsx,js,jsx,css}", "*.config.{ts,js}"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# Tech Stack Compliance Guide
-
-**📚 Human-Readable Standard**: See [07-tech-stack-compliance.md](../../packages/core/docs/standards/07-tech-stack-compliance.md) for complete documentation.
-
-This guide ensures consuming apps use the correct versions and patterns for all technologies in the PACE stack.
-
-## Tailwind CSS v4
-
-### MUST: Use Tailwind v4 CSS-First Approach
-
-**MUST use Tailwind v4 CSS-first syntax, NOT v3 patterns:**
-
-```css
-/* ✅ CORRECT: Tailwind v4 CSS-first (@import 'tailwindcss'; @theme { ... }) */
-/* ❌ WRONG: Tailwind v3 (@tailwind base/components/utilities directives) */
-```
-
-### MUST NOT: Use Bracket Syntax
-
-**MUST NOT use bracket syntax like `bg-[oklch(...)]`. Map everything through theme variables:**
-
-```tsx
-// ❌ WRONG: Bracket syntax (bg-[oklch(...)])
-// ✅ CORRECT: Theme variable (bg-main-500)
-```
-
-### MUST: Use Custom Color Namespaces
-
-**MUST use custom color namespaces:**
-- `main-*` for primary colors (green, emerald, teal, cyan, sky, blue)
-- `sec-*` for secondary colors (indigo, violet, purple, fuchsia, slate, gray, zinc, neutral, stone)
-- `acc-*` for accent colors (red, orange, amber, yellow, lime, pink, rose)
-
-```tsx
-// ✅ CORRECT: Custom namespaces (main-*, sec-*, acc-*)
-// ❌ WRONG: Standard Tailwind colors (blue-*, gray-*, red-*)
-```
-
-### MUST: Use Semantic Classes
-
-**MUST use semantic classes mapped in index.css:**
-
-```tsx
-// ✅ CORRECT - Semantic classes
-<div className="bg-background text-foreground">
-
-// ❌ WRONG - Direct color classes (unless necessary)
-<div className="bg-main-50 text-main-950">
-```
-
-## React 19+
-
-### MUST: Use React 19+ Features
-
-**MUST use React 19+ patterns:**
-
-```tsx
-// ✅ CORRECT: React 19+ features (Suspense, useTransition, etc.)
-import { Suspense, useTransition } from 'react';
-function App() {
-  const [isPending, startTransition] = useTransition();
-  return <Suspense fallback={<Loading />}><Component /></Suspense>;
-}
-```
-
-### MUST: Use Functional Components
-
-**MUST use functional components with hooks exclusively:**
-
-```tsx
-// ✅ CORRECT: Functional components with hooks
-function MyComponent() { const [state, setState] = useState(); return <div>...</div>; }
-
-// ❌ WRONG: Class components
-```
-
-## Supabase
-
-### MUST: Use Secure Supabase Client
-
-**MUST use `useSecureSupabase()` for all database operations:**
-
-```tsx
-// ✅ CORRECT: useSecureSupabase() from '@jmruthers/pace-core/rbac'
-// ❌ WRONG: createClient() from '@supabase/supabase-js' (base client)
-```
-
-### MUST: Enforce RLS
-
-**MUST ensure RLS is enabled on all tables. Never bypass RLS.**
-
-### SHOULD: Use RPC Functions
-
-**SHOULD use RPC functions for complex queries:**
-
-```tsx
-// ✅ CORRECT: RPC functions for complex queries
-const { data } = await secureSupabase.rpc('data_events_list', { organisation_id: orgId });
-
-// ❌ AVOID: Complex client-side queries with many joins
-```
-
-## TanStack Query
-
-### MUST: Use TanStack Query for Server State
-
-**MUST use TanStack Query for all server state management:**
-
-```tsx
-// ✅ CORRECT: TanStack Query for server state
-import { useQuery, useMutation } from '@tanstack/react-query';
-const { data, isLoading } = useQuery({ queryKey: ['events', orgId], queryFn: () => fetchEvents(orgId) });
-
-// ❌ WRONG: useState + useEffect for server state
-```
-
-### SHOULD: Configure Query Client
-
-**SHOULD configure QueryClient with appropriate defaults:**
-
-```tsx
-// ✅ CORRECT: Configure QueryClient with appropriate defaults (staleTime, cacheTime, retry)
-const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, cacheTime: 10 * 60 * 1000, retry: 1 } } });
-```
-
-## React Hook Form + Zod
-
-### MUST: Use React Hook Form with Zod
-
-**MUST use React Hook Form with Zod for all forms:**
-
-```tsx
-// ✅ CORRECT: React Hook Form + Zod (useZodForm from pace-core)
-import { useZodForm } from '@jmruthers/pace-core';
-const schema = z.object({ email: z.string().email(), name: z.string().min(1) });
-const form = useZodForm(schema);
-
-// ❌ WRONG: Manual form handling (useState for form state)
-```
-
-## Vite
-
-### MUST: Use Vite for Build Tooling
-
-**MUST use Vite for all build tooling:**
-
-```typescript
-// ✅ CORRECT: Vite for build tooling
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-export default defineConfig({ plugins: [react()] });
-```
-
-### MUST: Use Environment Variables Correctly
-
-**MUST use `import.meta.env` for environment variables:**
-
-```tsx
-// ✅ CORRECT: import.meta.env.VITE_API_URL (Vite env vars)
-// ❌ WRONG: process.env.VITE_API_URL (Node.js env vars)
-```
-
-## TypeScript
-
-### MUST: Use TypeScript 5+
-
-**MUST use TypeScript 5+ with strict mode:**
-
-```json
-// ✅ CORRECT: TypeScript 5+ with strict mode
-{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "strict": true } }
-```
-
-## Version Requirements
-
-### MUST: Use Required Versions
-
-**MUST use compatible versions:**
-
-- React: `^19.0.0`
-- TypeScript: `^5.0.0`
-- Tailwind CSS: `^4.0.0`
-- Vite: `^6.0.0`
-- Supabase: `^2.49.0+`
-
-**Check `package.json` for exact versions required by pace-core.**
-
-## Tech Stack Checklist
-
-Before committing, verify:
-- [ ] Tailwind v4 CSS-first syntax (no @tailwind directives)
-- [ ] No bracket syntax for colors (use theme variables)
-- [ ] Custom color namespaces (main-*, sec-*, acc-*)
-- [ ] React 19+ functional components
-- [ ] Secure Supabase client (useSecureSupabase)
-- [ ] TanStack Query for server state
-- [ ] React Hook Form + Zod for forms
-- [ ] Vite for build tooling
-- [ ] TypeScript 5+ with strict mode
-- [ ] All versions compatible with pace-core
-
-## Reference
-
-- Tailwind v4: https://tailwindcss.com/blog/tailwindcss-v4
-- React 19: https://react.dev/blog/2024/04/25/react-19-upgrade-guide
-- Supabase: https://supabase.com/docs
-- TanStack Query: https://tanstack.com/query
-- React Hook Form: https://react-hook-form.com
-- Vite: https://vitejs.dev

package/cursor-rules/10-error-handling-patterns.mdc

@@ -1,179 +0,0 @@
----
-description: Enforce consistent error handling patterns including type-safe errors, user-friendly messages, and proper logging
-globs: ["src/**/*.{ts,tsx,js,jsx}"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# Error Handling Patterns Guide
-
-**📚 Human-Readable Standard**: See [10-error-handling-patterns.md](../../packages/core/docs/standards/10-error-handling-patterns.md) for complete documentation.
-
-This guide enforces consistent error handling patterns to ensure user-friendly errors, type-safe handling, and proper logging.
-
-**AI Agent Instructions**: When writing error handling code, ALWAYS follow these patterns. Never expose internal details to users. Always use type-safe error handling.
-
-## MUST: Use Type-Safe Error Handling
-
-**MUST use type guards or Result types, NEVER use `any`:**
-
-```tsx
-// ❌ WRONG: Using any
-catch (error: any) {
-  console.log(error.message);
-}
-
-// ✅ CORRECT: Type guard
-function isApiError(error: unknown): error is ApiError {
-  return typeof error === 'object' && error !== null && 'ok' in error && (error as ApiError).ok === false;
-}
-catch (error) {
-  if (isApiError(error)) {
-    handleApiError(error);
-  } else {
-    handleUnknownError(error);
-  }
-}
-
-// ✅ CORRECT: Result type
-type Result<T> = { ok: true; data: T } | { ok: false; error: ApiError };
-const result = await fetchData();
-if (result.ok) {
-  useData(result.data);
-} else {
-  showError(result.error.message);
-}
-```
-
-## MUST: Never Expose Internal Details
-
-**MUST NOT expose SQL, stack traces, file paths, or internal errors to users:**
-
-```tsx
-// ❌ WRONG: Exposing internal details
-toast.error(error.message); // May contain SQL, stack traces
-
-// ✅ CORRECT: User-friendly message
-toast.error('Unable to save changes. Please try again.');
-logger.error('Save failed', { error: error.message, context: 'saveUser' });
-```
-
-## MUST: Use Consistent Error Shapes
-
-**MUST use ApiResult shape for API errors:**
-
-```tsx
-// ✅ CORRECT: Consistent error shape
-type ApiError = {
-  ok: false;
-  error: {
-    code: string;
-    message: string; // User-friendly
-    details?: object; // Non-sensitive context
-  };
-};
-```
-
-## MUST: Log Errors with Context
-
-**MUST log errors with context, but NEVER log sensitive data:**
-
-```tsx
-// ✅ CORRECT: Log with context, no sensitive data
-logger.error('Failed to save user', {
-  userId: user.id,
-  operation: 'updateUser',
-  errorCode: error.code,
-});
-
-// ❌ WRONG: Logging sensitive data
-logger.error('Failed to save user', {
-  password: user.password, // NEVER
-  token: authToken,        // NEVER
-  ssn: user.ssn,          // NEVER
-});
-```
-
-## SHOULD: Provide Recovery Paths
-
-**SHOULD provide retry logic or fallback values when appropriate:**
-
-```tsx
-// ✅ CORRECT: Retry with exponential backoff
-async function fetchWithRetry<T>(fn: () => Promise<Result<T>>, maxRetries = 3): Promise<Result<T>> {
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    const result = await fn();
-    if (result.ok) return result;
-    if (result.error.code?.startsWith('4')) return result; // Don't retry 4xx
-    await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
-  }
-  return { ok: false, error: { code: 'MAX_RETRIES', message: 'Operation failed after retries' } };
-}
-
-// ✅ CORRECT: Fallback values
-const preferences = await fetchPreferences().catch(() => ({ theme: 'light', language: 'en' }));
-```
-
-## SHOULD: Use Error Boundaries for React
-
-**SHOULD use ErrorBoundary for React component errors:**
-
-```tsx
-// ✅ CORRECT: Error boundary
-import { ErrorBoundary } from '@jmruthers/pace-core';
-<ErrorBoundary fallback={<ErrorFallback />} onError={(error, errorInfo) => logger.error('React error', { error, errorInfo })}>
-  <YourApp />
-</ErrorBoundary>
-```
-
-## Decision Tree: Error Handling
-
-**ALWAYS follow this decision tree:**
-
-```
-1. What type of error is this?
-   ├─ API Error → Use ApiResult shape, user-friendly message
-   ├─ Validation Error → Use Zod errors, field-specific messages
-   ├─ Network Error → Retry logic, connection message
-   └─ Unknown Error → Generic user message, detailed log
-
-2. Should user see this error?
-   ├─ YES → User-friendly message (no internals)
-   └─ NO → Log only, show generic message
-
-3. Can we recover?
-   ├─ YES → Retry logic or fallback value
-   └─ NO → Show error, allow user to retry
-
-4. Is this sensitive data?
-   ├─ YES → Never log (passwords, tokens, PII)
-   └─ NO → Log with context
-```
-
-## Error Handling Checklist
-
-Before committing error handling code, verify:
-
-- [ ] Type-safe error handling (no `any`)
-- [ ] User-friendly error messages (no internals)
-- [ ] Errors logged with context (no sensitive data)
-- [ ] Recovery paths provided when possible
-- [ ] Consistent error shapes used
-- [ ] Error boundaries for React components
-- [ ] Async operations have proper error handling
-- [ ] Validation errors use Zod
-- [ ] Network errors handled gracefully
-
-## Common Mistakes to Avoid
-
-1. **Exposing internal details** - Never show SQL, stack traces, file paths
-2. **Using `any` for errors** - Always use type guards or Result types
-3. **Logging sensitive data** - Never log passwords, tokens, PII
-4. **Ignoring errors** - Always handle errors, even if just logging
-5. **Generic error messages** - Provide specific, actionable messages
-
-## Reference
-
-- **Standard**: `packages/core/docs/standards/10-error-handling-patterns.md`
-- **Code Quality**: See `06-code-quality.mdc` for TypeScript standards
-- **Security**: See `01-standards-compliance.mdc` for security requirements

package/cursor-rules/11-performance-optimization.mdc

@@ -1,169 +0,0 @@
----
-description: Enforce performance optimization patterns including React memoization, database query optimization, and caching strategies
-globs: ["src/**/*.{ts,tsx,js,jsx}", "supabase/migrations/**/*.sql"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# Performance Optimization Guide
-
-**📚 Human-Readable Standard**: See [11-performance-optimization.md](../../packages/core/docs/standards/11-performance-optimization.md) for complete documentation.
-
-This guide enforces performance optimization patterns to ensure fast, responsive applications.
-
-**AI Agent Instructions**: When writing performance-sensitive code, ALWAYS apply these optimizations. Use the decision trees below to determine when to optimize.
-
-## MUST: Optimize React Re-renders
-
-**MUST use memoization for expensive computations and stable references:**
-
-```tsx
-// ✅ CORRECT - Memoize expensive computation
-const expensiveValue = useMemo(() => computeExpensiveValue(data), [data]);
-
-// ✅ CORRECT - Stable callback reference
-const handleClick = useCallback(() => doSomething(id), [id]);
-
-// ✅ CORRECT - Memoize component
-const ExpensiveComponent = React.memo(({ data }) => <div>{/* ... */}</div>);
-
-// ❌ WRONG - Recomputes on every render
-const expensiveValue = computeExpensiveValue(data);
-const handleClick = () => doSomething(id);
-```
-
-## MUST: Avoid Creating New Objects in Render
-
-**MUST NOT create new objects/arrays in render:**
-
-```tsx
-// ❌ WRONG - New object on every render
-function Component({ items }) {
-  const config = { items, enabled: true };
-  return <Child config={config} />;
-}
-
-// ✅ CORRECT - Memoize object
-function Component({ items }) {
-  const config = useMemo(() => ({ items, enabled: true }), [items]);
-  return <Child config={config} />;
-}
-```
-
-## MUST: Use Helper Functions in RLS Policies
-
-**MUST use STABLE SECURITY DEFINER helper functions (never subqueries):**
-
-```sql
--- ✅ CORRECT - Helper function (evaluated once)
-CREATE POLICY "rbac_select_users" ON users FOR SELECT USING (
-  check_user_organisation_access(organisation_id)
-);
-
--- ❌ WRONG - Subquery (N+1 performance issue)
-CREATE POLICY "rbac_select_users" ON users FOR SELECT USING (
-  organisation_id IN (SELECT organisation_id FROM organisation_memberships WHERE user_id = auth.uid())
-);
-```
-
-## SHOULD: Lazy Load Heavy Components
-
-**SHOULD lazy load heavy components:**
-
-```tsx
-// ✅ CORRECT - Lazy load
-import { lazy, Suspense } from 'react';
-const HeavyComponent = lazy(() => import('./HeavyComponent'));
-<Suspense fallback={<Loading />}><HeavyComponent /></Suspense>
-```
-
-## SHOULD: Configure TanStack Query Cache
-
-**SHOULD configure appropriate cache times:**
-
-```tsx
-// ✅ CORRECT - Configure cache
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000,
-      cacheTime: 10 * 60 * 1000,
-      retry: 1,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-```
-
-## SHOULD: Use RPC Functions for Complex Queries
-
-**SHOULD use RPC functions instead of complex client-side queries:**
-
-```tsx
-// ✅ CORRECT - RPC for complex query
-const { data } = await supabase.rpc('data_events_list', { organisation_id: orgId });
-
-// ❌ AVOID - Complex client-side query
-const { data } = await supabase.from('events').select('*, users(*), organisations(*)').eq('organisation_id', orgId);
-```
-
-## Decision Tree: Performance Optimization
-
-**ALWAYS follow this decision tree:**
-
-```
-1. Is this expensive computation?
-   ├─ YES → Use useMemo
-   └─ NO → Don't memoize (overhead not worth it)
-
-2. Is this function passed as prop?
-   ├─ YES → Use useCallback
-   └─ NO → Regular function is fine
-
-3. Is this component expensive to render?
-   ├─ YES → Use React.memo
-   └─ NO → Regular component is fine
-
-4. Is this creating new object/array in render?
-   ├─ YES → Memoize with useMemo
-   └─ NO → Continue
-
-5. Is this RLS policy?
-   ├─ YES → Use helper function (STABLE SECURITY DEFINER)
-   └─ NO → Continue
-
-6. Is this complex query?
-   ├─ YES → Use RPC function
-   └─ NO → Client-side query is fine
-```
-
-## Performance Checklist
-
-Before committing performance-sensitive code, verify:
-
-- [ ] Expensive computations memoized
-- [ ] Callbacks stable with useCallback
-- [ ] Components memoized when appropriate
-- [ ] No new objects/arrays in render
-- [ ] Heavy components lazy loaded
-- [ ] RLS policies use helper functions
-- [ ] Queries use indexes appropriately
-- [ ] No N+1 query patterns
-- [ ] TanStack Query configured properly
-- [ ] Bundle size optimized
-
-## Common Performance Pitfalls
-
-1. **Creating new objects in render** - Memoize with useMemo
-2. **Using inline functions** - Use useCallback
-3. **Over-memoizing** - Only memoize expensive operations
-4. **Subqueries in RLS** - Use helper functions
-5. **N+1 queries** - Use joins or RPC functions
-6. **Not lazy loading** - Lazy load heavy components
-7. **Poor cache configuration** - Configure TanStack Query properly
-
-## Reference
-
-- **Standard**: `packages/core/docs/standards/11-performance-optimization.md`
-- **RLS**: See `09-rbac-compliance.mdc` for RLS performance requirements
-- **Code Quality**: See `06-code-quality.mdc` for React patterns

package/cursor-rules/12-ci-cd-integration.mdc

@@ -1,150 +0,0 @@
----
-description: Enforce CI/CD integration patterns including automated quality checks, deployment processes, and security scanning
-globs: [".github/workflows/**/*.yml", ".github/workflows/**/*.yaml", "package.json"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# CI/CD Integration Guide
-
-**📚 Human-Readable Standard**: See [12-ci-cd-integration.md](../../packages/core/docs/standards/12-ci-cd-integration.md) for complete documentation.
-
-This guide enforces CI/CD integration patterns to ensure automated quality checks and consistent deployments.
-
-**AI Agent Instructions**: When setting up CI/CD pipelines, ALWAYS include the required checks below. Use the decision tree to determine what checks are needed.
-
-## MUST: Include Required CI Checks
-
-**MUST run these checks in every CI pipeline:**
-
-```yaml
-# ✅ CORRECT - Required checks
-jobs:
-  quality-checks:
-    steps:
-      - name: Lint
-        run: npm run lint
-      - name: Type check
-        run: npx tsc --noEmit
-      - name: Run tests
-        run: npm run test
-      - name: Build
-        run: npm run build
-```
-
-## MUST: Have Required Scripts
-
-**MUST have these scripts in package.json:**
-
-```json
-// ✅ CORRECT - Required scripts
-{
-  "scripts": {
-    "lint": "eslint .",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "vite build"
-  }
-}
-```
-
-## SHOULD: Include Additional Checks
-
-**SHOULD include these checks:**
-
-```yaml
-# ✅ RECOMMENDED - Additional checks
-- name: Format check
-  run: npm run format:check
-- name: Security scan
-  run: npm audit --audit-level=moderate
-- name: Coverage check
-  run: npm run test:coverage
-```
-
-## MUST: Use Secrets for Sensitive Data
-
-**MUST NOT commit secrets to repository:**
-
-```yaml
-# ✅ CORRECT - Use secrets
-env:
-  SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
-  VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
-
-# ❌ WRONG - Hardcoded secrets
-env:
-  SUPABASE_URL: "https://hardcoded-url.supabase.co"
-```
-
-## SHOULD: Deploy to Staging First
-
-**SHOULD deploy to staging before production:**
-
-```yaml
-# ✅ CORRECT - Staging first
-deploy-staging:
-  if: github.ref == 'refs/heads/develop'
-  environment: staging
-
-deploy-production:
-  needs: deploy-staging
-  if: github.ref == 'refs/heads/main'
-  environment: production
-```
-
-## Decision Tree: CI/CD Setup
-
-**ALWAYS follow this decision tree:**
-
-```
-1. What type of check is this?
-   ├─ Lint → MUST include
-   ├─ Type Check → MUST include
-   ├─ Tests → MUST include
-   ├─ Build → MUST include
-   ├─ Compliance → MUST include
-   ├─ Format → SHOULD include
-   ├─ Security → SHOULD include
-   └─ Coverage → SHOULD include
-
-2. Is this sensitive data?
-   ├─ YES → Use secrets (never commit)
-   └─ NO → Can be in config
-
-3. What environment?
-   ├─ Staging → Deploy on develop branch
-   └─ Production → Deploy on main branch only
-
-4. Are migrations needed?
-   ├─ YES → Run in staging first, test in CI
-   └─ NO → Continue
-```
-
-## CI/CD Checklist
-
-Before committing CI/CD configuration, verify:
-
-- [ ] Lint check configured
-- [ ] Type check configured
-- [ ] Tests run in CI
-- [ ] Build succeeds in CI
-- [ ] Security scan configured (recommended)
-- [ ] Environment variables set as secrets
-- [ ] Staging deployment configured
-- [ ] Production deployment configured
-- [ ] Migration strategy defined
-- [ ] Required scripts in package.json
-
-## Common CI/CD Mistakes
-
-1. **Missing required checks** - Include all MUST checks
-2. **Hardcoded secrets** - Always use secrets
-3. **No staging environment** - Deploy to staging first
-4. **No rollback plan** - Document rollback process
-
-## Reference
-
-- **Standard**: `packages/core/docs/standards/12-ci-cd-integration.md`
-- **Testing**: See `04-testing-standards.mdc` for test configuration
-- **Code Quality**: See `06-code-quality.mdc` for linting