@jmruthers/pace-core 0.6.6 → 0.6.7

package/cursor-rules/06-code-quality.mdc

@@ -1,311 +0,0 @@
----
-description: Enforce code quality standards including TypeScript, ESLint, formatting, performance, and accessibility
-globs: ["src/**/*.{ts,tsx,js,jsx}"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# Code Quality Guide
-
-**📚 Human-Readable Standard**: See [06-code-quality.md](../../packages/core/docs/standards/06-code-quality.md) for complete documentation.
-
-This guide enforces code quality standards to ensure maintainable, performant, and accessible code.
-
-## TypeScript Standards
-
-### MUST: Use Strict Mode
-
-**TypeScript MUST use strict mode:**
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "strictBindCallApply": true,
-    "strictPropertyInitialization": true,
-    "noImplicitThis": true,
-    "alwaysStrict": true
-  }
-}
-```
-
-### MUST NOT: Use `any`
-
-**MUST NOT use `any` type. Use `unknown` if type is truly unknown:**
-
-```tsx
-// ❌ WRONG: Using any
-function processData(data: any) { return data.value; }
-
-// ✅ CORRECT: Using unknown with type guard or proper types
-function processData(data: unknown) {
-  if (typeof data === 'object' && data !== null && 'value' in data) {
-    return (data as { value: string }).value;
-  }
-  throw new Error('Invalid data');
-}
-// Or: interface Data { value: string; } function processData(data: Data) { return data.value; }
-```
-
-### MUST: Use Discriminated Unions
-
-**MUST use discriminated unions instead of boolean flags:**
-
-```tsx
-// ❌ WRONG: Boolean flags (confusing: what if both are true?)
-interface User { isAdmin: boolean; isGuest: boolean; }
-
-// ✅ CORRECT: Discriminated union
-type User = { type: 'admin'; permissions: Permission[] } | { type: 'guest'; limitedAccess: boolean } | { type: 'user'; role: UserRole };
-```
-
-### SHOULD: Use ReadonlyArray
-
-**SHOULD use ReadonlyArray for immutable arrays:**
-
-```tsx
-// ✅ CORRECT - ReadonlyArray
-function processItems(items: ReadonlyArray<Item>) {
-  // Can't mutate items
-  return items.map(item => transform(item));
-}
-```
-
-## ESLint Configuration
-
-### MUST: Use pace-core ESLint Config
-
-**MUST extend pace-core ESLint configuration:**
-
-```javascript
-// eslint.config.js
-import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
-
-export default [
-  ...paceCoreConfig,
-  // Your additional config
-];
-```
-
-### MUST: Fix ESLint Errors
-
-**MUST fix all ESLint errors before committing:**
-
-```bash
-npm run lint
-npm run lint:fix  # Auto-fix where possible
-```
-
-## Code Formatting
-
-### MUST: Use Consistent Formatting
-
-**MUST use Prettier or equivalent for consistent formatting:**
-
-```json
-// .prettierrc
-{
-  "semi": true,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "trailingComma": "es5",
-  "printWidth": 100
-}
-```
-
-### MUST: Format Before Committing
-
-**MUST format code before committing:**
-
-```bash
-npm run format
-# Or use pre-commit hook
-```
-
-## Performance Considerations
-
-### SHOULD: Optimize Re-renders
-
-**SHOULD use React.memo, useMemo, useCallback appropriately:**
-
-```tsx
-// ✅ CORRECT: Memoize expensive computations, callbacks, and components
-const expensiveValue = useMemo(() => computeExpensiveValue(data), [data]);
-const handleClick = useCallback(() => doSomething(id), [id]);
-const ExpensiveComponent = React.memo(({ data }) => <div>{/* ... */}</div>);
-```
-
-### SHOULD: Avoid Unnecessary Re-renders
-
-**SHOULD avoid causing unnecessary re-renders:**
-
-```tsx
-// ❌ WRONG: New object on every render (causes unnecessary re-renders)
-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} />;
-}
-```
-
-### SHOULD: Lazy Load Heavy Components
-
-**SHOULD lazy load heavy components:**
-
-```tsx
-// ✅ CORRECT: Lazy load heavy components
-import { lazy, Suspense } from 'react';
-const HeavyComponent = lazy(() => import('./HeavyComponent'));
-function App() {
-  return <Suspense fallback={<Loading />}><HeavyComponent /></Suspense>;
-}
-```
-
-## Accessibility Requirements
-
-### MUST: Use Semantic HTML
-
-**MUST use semantic HTML elements:**
-
-```tsx
-// ❌ WRONG: Non-semantic (<div onClick={...}>)
-// ✅ CORRECT: Semantic HTML (<button onClick={...}>)
-```
-
-### MUST: Provide ARIA Labels
-
-**MUST provide ARIA labels for interactive elements:**
-
-```tsx
-// ✅ CORRECT: Provide ARIA labels for interactive elements
-<button aria-label="Close dialog">×</button>
-<input aria-label="Search" type="search" />
-```
-
-### MUST: Ensure Keyboard Navigation
-
-**MUST ensure all interactive elements are keyboard accessible:**
-
-```tsx
-// ✅ CORRECT: Ensure keyboard navigation (Enter or Space key)
-<button onClick={handleClick} onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') handleClick(); }}>Click me</button>
-```
-
-### MUST: Provide Focus Indicators
-
-**MUST provide visible focus indicators:**
-
-```tsx
-// ✅ CORRECT: Provide visible focus indicators
-<button className="focus:outline-none focus:ring-2 focus:ring-main-500">Click me</button>
-```
-
-## Code Review Checklist
-
-**Before submitting code for review, verify:**
-
-- [ ] TypeScript strict mode enabled
-- [ ] No `any` types used
-- [ ] ESLint passes with no errors
-- [ ] Code is formatted consistently
-- [ ] Performance optimizations applied where needed
-- [ ] Accessibility requirements met
-- [ ] Semantic HTML used
-- [ ] ARIA labels provided
-- [ ] Keyboard navigation works
-- [ ] Focus indicators visible
-- [ ] Code is readable and maintainable
-- [ ] Comments explain "why", not "what"
-
-## Code Complexity
-
-### SHOULD: Keep Functions Small
-
-**Functions SHOULD be small and focused:**
-
-```tsx
-// ❌ WRONG: Large function (100+ lines, multiple responsibilities)
-function processUserData(user) { /* 100+ lines of logic */ }
-
-// ✅ CORRECT: Small, focused functions
-function validateUser(user: User): ValidationResult { /* Validation logic */ }
-function transformUser(user: User): TransformedUser { /* Transformation logic */ }
-function processUserData(user: User) {
-  const validation = validateUser(user);
-  if (!validation.valid) return validation;
-  return transformUser(user);
-}
-```
-
-### SHOULD: Limit Cyclomatic Complexity
-
-**Functions SHOULD have low cyclomatic complexity (< 10):**
-
-```tsx
-// ❌ WRONG: High complexity (many nested conditions)
-function processData(data) { if (condition1) { if (condition2) { if (condition3) { /* ... */ } } } }
-
-// ✅ CORRECT: Lower complexity (early returns)
-function processData(data) { if (!condition1) return; if (!condition2) return; if (!condition3) return; /* Process */ }
-```
-
-## Error Handling
-
-### MUST: Handle Errors Gracefully
-
-**MUST handle errors and provide user feedback:**
-
-```tsx
-// ✅ CORRECT: Handle errors gracefully with user feedback
-try {
-  const data = await fetchData();
-  setData(data);
-} catch (error) {
-  logger.error('Failed to fetch data', error);
-  toast.error('Failed to load data. Please try again.');
-}
-```
-
-### MUST: Use Type-Safe Error Handling
-
-**MUST use type-safe error handling:**
-
-```tsx
-// ✅ CORRECT: Type-safe error handling
-function isApiError(error: unknown): error is ApiError {
-  return typeof error === 'object' && error !== null && 'code' in error && 'message' in error;
-}
-try {
-  await apiCall();
-} catch (error) {
-  if (isApiError(error)) handleApiError(error);
-  else handleUnknownError(error);
-}
-```
-
-## Code Quality Checklist
-
-Before committing, verify:
-- [ ] TypeScript strict mode enabled
-- [ ] No `any` types
-- [ ] ESLint passes
-- [ ] Code formatted
-- [ ] Performance optimized
-- [ ] Accessible (semantic HTML, ARIA, keyboard)
-- [ ] Functions are small and focused
-- [ ] Error handling in place
-- [ ] Code is readable
-- [ ] Comments explain "why"
-
-## Reference
-
-- TypeScript Handbook: https://www.typescriptlang.org/docs/
-- ESLint Rules: pace-core eslint-config
-- React Performance: https://react.dev/learn/render-and-commit
-- Web Accessibility: https://www.w3.org/WAI/

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