@jmruthers/pace-core 0.5.193 → 0.6.2

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

@@ -0,0 +1,200 @@
+---
+description: Define standard folder structure and file organization for consuming apps
+globs: ["**/*.{ts,tsx,js,jsx,md}", "src/**"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Project Structure Standard
+
+This guide defines the standard folder structure and file organization for consuming apps in the PACE suite.
+
+## MUST: Follow Standard Directory Structure
+
+**Consuming apps MUST follow this structure:**
+
+```
+your-app/
+├── .cursor/
+│   └── rules/          # Cursor rules (pace-core rules + local rules)
+├── src/
+│   ├── components/     # App-specific components
+│   ├── hooks/          # App-specific hooks
+│   ├── services/       # App-specific services
+│   ├── pages/          # Page components
+│   ├── types/          # TypeScript type definitions
+│   ├── utils/          # App-specific utilities
+│   ├── App.tsx         # Main app component
+│   └── main.tsx        # Entry point
+├── supabase/
+│   ├── migrations/     # Database migrations
+│   └── functions/      # Edge functions (if used)
+├── public/             # Static assets
+├── tests/              # Integration/E2E tests (optional)
+├── audit/              # Audit reports (generated)
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── vitest.config.ts
+```
+
+## MUST: Organize Components by Feature
+
+**Components SHOULD be organized by feature/domain, not by type:**
+
+```
+src/
+├── components/
+│   ├── events/         # Event-related components
+│   │   ├── EventCard.tsx
+│   │   └── EventList.tsx
+│   ├── users/          # User-related components
+│   │   ├── UserProfile.tsx
+│   │   └── UserList.tsx
+│   └── shared/         # Shared app-specific components
+│       ├── Layout.tsx
+│       └── Navigation.tsx
+```
+
+**MUST NOT:**
+- Organize by component type (`buttons/`, `inputs/`, etc.) - use pace-core instead
+- Create duplicate components that pace-core provides
+
+## MUST: Colocate Tests
+
+**Tests MUST be colocated with source files:**
+
+```
+src/
+├── components/
+│   └── EventCard/
+│       ├── EventCard.tsx
+│       └── EventCard.test.tsx
+├── hooks/
+│   ├── useEventData.ts
+│   └── useEventData.test.ts
+└── utils/
+    ├── formatEvent.ts
+    └── formatEvent.test.ts
+```
+
+## MUST: Follow Naming Conventions
+
+### Files
+- Components: `PascalCase.tsx` (e.g., `EventCard.tsx`)
+- Hooks: `camelCase.ts` with `use` prefix (e.g., `useEventData.ts`)
+- Utilities: `camelCase.ts` (e.g., `formatEvent.ts`)
+- Types: `camelCase.ts` or `types.ts` (e.g., `eventTypes.ts`)
+- Tests: `*.test.ts` or `*.test.tsx`
+- Config: `kebab-case.config.js` (e.g., `vite.config.ts`)
+
+### Directories
+- Use `kebab-case` for directories (e.g., `event-management/`)
+- Match feature/domain names
+
+## MUST: Place Migrations Correctly
+
+**Database migrations MUST be in `supabase/migrations/`:**
+- Format: `YYYYMMDDHHMMSS_description.sql`
+- Example: `20250115143022_add_user_preferences.sql`
+
+## SHOULD: Organize by Domain
+
+**For larger apps, SHOULD organize by domain/feature:**
+
+```
+src/
+├── domains/
+│   ├── events/
+│   │   ├── components/
+│   │   ├── hooks/
+│   │   ├── services/
+│   │   └── types.ts
+│   └── users/
+│       ├── components/
+│       ├── hooks/
+│       ├── services/
+│       └── types.ts
+├── shared/              # Shared across domains
+│   ├── components/
+│   ├── hooks/
+│   └── utils/
+└── App.tsx
+```
+
+## MUST: Keep Root Directory Clean
+
+**Root directory SHOULD only contain:**
+- Configuration files (`package.json`, `tsconfig.json`, etc.)
+- Documentation (`README.md`, `CHANGELOG.md`)
+- Build outputs (`.gitignore` them)
+- `.cursor/` directory
+
+**MUST NOT:**
+- Place source files in root
+- Place test files in root
+- Place component files in root
+
+## MUST: Use Consistent Import Paths
+
+**MUST use consistent import patterns:**
+
+```tsx
+// ✅ CORRECT - Absolute imports from src
+import { EventCard } from '@/components/events/EventCard';
+import { useEventData } from '@/hooks/useEventData';
+import { formatEvent } from '@/utils/formatEvent';
+
+// ✅ CORRECT - pace-core imports
+import { Button, Card } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+// ❌ WRONG - Relative imports for distant files
+import { EventCard } from '../../../components/events/EventCard';
+```
+
+**Configure path aliases in `tsconfig.json`:**
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+## MUST: Separate App Code from pace-core
+
+**MUST NOT:**
+- Modify pace-core code directly
+- Create components that duplicate pace-core functionality
+- Import from pace-core source (use published package)
+
+**MUST:**
+- Use pace-core as a dependency
+- Import from `@jmruthers/pace-core`
+- Create app-specific components only when pace-core doesn't provide them
+
+## SHOULD: Document Structure Decisions
+
+**For non-standard structures, SHOULD document why:**
+- Add `STRUCTURE.md` or section in `README.md`
+- Explain deviations from standard
+- Justify custom organization
+
+## File Organization Checklist
+
+Before committing, verify:
+- [ ] Components organized by feature, not type
+- [ ] Tests colocated with source files
+- [ ] Naming conventions followed
+- [ ] Migrations in `supabase/migrations/`
+- [ ] Root directory clean
+- [ ] Import paths consistent
+- [ ] No pace-core code modifications
+- [ ] Structure documented if non-standard
+
+## Reference
+
+See `project-structure.mdc` in pace-core for detailed structure patterns.

package/cursor-rules/03-solid-principles.mdc

@@ -0,0 +1,222 @@
+---
+description: Enforce SOLID architecture principles in consuming apps
+globs: ["src/**/*.{ts,tsx}"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# SOLID Principles Guide
+
+This guide enforces SOLID architecture principles to ensure maintainable, extensible, and testable code.
+
+## Single Responsibility Principle (SRP)
+
+**A class or function SHOULD have only one reason to change.**
+
+### MUST: Single Responsibility
+
+**Each function/component SHOULD do one thing:**
+
+```tsx
+// ❌ WRONG: Multiple responsibilities (fetching, formatting, rendering in one component)
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  const [events, setEvents] = useState([]);
+  useEffect(() => { fetchUser(userId).then(setUser); fetchEvents(userId).then(setEvents); }, [userId]);
+  return <div>...</div>;
+}
+
+// ✅ CORRECT: Separated responsibilities (hooks for data, components for UI)
+function UserProfile({ userId }) {
+  const user = useUser(userId);
+  const events = useUserEvents(userId);
+  return <div><UserInfo user={user} /><UserEvents events={events} /></div>;
+}
+```
+
+### MUST: Extract Complex Logic
+
+**Complex logic SHOULD be extracted into hooks, services, or utilities:**
+
+```tsx
+// ❌ WRONG: Business logic in component (filtering, sorting, formatting)
+function EventList() {
+  const [events, setEvents] = useState([]);
+  const [filtered, setFiltered] = useState([]);
+  useEffect(() => { /* complex filtering/sorting logic */ }, [events]);
+  return <div>{filtered.map(...)}</div>;
+}
+
+// ✅ CORRECT: Logic extracted to hook
+function useFilteredEvents() {
+  const events = useEvents();
+  return useMemo(() => events.filter(...).sort(...).map(...), [events]);
+}
+function EventList() {
+  const filteredEvents = useFilteredEvents();
+  return <div>{filteredEvents.map(...)}</div>;
+}
+```
+
+## Open/Closed Principle (OCP)
+
+**Software entities SHOULD be open for extension but closed for modification.**
+
+### SHOULD: Use Composition Over Modification
+
+**Extend functionality through composition, not modification:**
+
+```tsx
+// ❌ WRONG: Modifying base component behavior
+function SpecialButton({ onClick, ...props }) {
+  const handleClick = (e) => { trackEvent('button-click'); onClick?.(e); };
+  return <BaseButton onClick={handleClick} {...props} />; // Modifies base
+}
+
+// ✅ CORRECT: Composition with pace-core (extend, don't modify)
+import { Button } from '@jmruthers/pace-core';
+function SpecialButton({ onClick, ...props }) {
+  const handleClick = (e) => { trackEvent('button-click'); onClick?.(e); };
+  return <Button onClick={handleClick} {...props} />;
+}
+```
+
+### SHOULD: Use Configuration Over Code Changes
+
+**Extend behavior through configuration:**
+
+```tsx
+// ✅ CORRECT: Extend through configuration, not code changes
+interface DataTableConfig { columns: Column[]; features: FeatureConfig; rbac: RBACConfig; }
+function MyDataTable({ config }: { config: DataTableConfig }) {
+  return <DataTable {...config} />;
+}
+```
+
+## Liskov Substitution Principle (LSP)
+
+**Subtypes MUST be substitutable for their base types.**
+
+### MUST: Maintain Interface Contracts
+
+**Derived components/hooks MUST maintain the same interface:**
+
+```tsx
+// ✅ CORRECT: Derived hooks maintain same interface (substitutable)
+interface BaseHook { data: Data | null; isLoading: boolean; error: Error | null; }
+function useBaseData(): BaseHook { ... }
+function useExtendedData(): BaseHook {
+  const base = useBaseData();
+  return { ...base }; // Maintains interface, extends behavior
+}
+```
+
+## Interface Segregation Principle (ISP)
+
+**Clients SHOULD NOT depend on interfaces they don't use.**
+
+### MUST: Create Focused Interfaces
+
+**Interfaces SHOULD be small and focused:**
+
+```tsx
+// ❌ WRONG: Large interface with many responsibilities
+interface UserService {
+  getUser(id: string): Promise<User>;
+  createUser(data: UserData): Promise<User>;
+  updateUser(id: string, data: Partial<User>): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+  getUserEvents(id: string): Promise<Event[]>;
+  getUserOrganisations(id: string): Promise<Organisation[]>;
+}
+
+// ✅ CORRECT: Segregated interfaces (focused, specific)
+interface UserReader { getUser(id: string): Promise<User>; getUserEvents(id: string): Promise<Event[]>; }
+interface UserWriter { createUser(data: UserData): Promise<User>; updateUser(id: string, data: Partial<User>): Promise<User>; deleteUser(id: string): Promise<void>; }
+interface UserOrganisationService { getUserOrganisations(id: string): Promise<Organisation[]>; }
+```
+
+### SHOULD: Use Specific Props
+
+**Component props SHOULD be specific, not generic:**
+
+```tsx
+// ❌ WRONG: Generic props object (config: any)
+function UserCard({ user, config }: { user: User; config: any }) { ... }
+
+// ✅ CORRECT: Specific, focused props interface
+interface UserCardProps { user: User; showEmail?: boolean; showAvatar?: boolean; onEdit?: (user: User) => void; }
+function UserCard({ user, showEmail, showAvatar, onEdit }: UserCardProps) { ... }
+```
+
+## Dependency Inversion Principle (DIP)
+
+**High-level modules SHOULD NOT depend on low-level modules. Both SHOULD depend on abstractions.**
+
+### MUST: Depend on Abstractions
+
+**Depend on interfaces/types, not concrete implementations:**
+
+```tsx
+// ❌ WRONG: Direct dependency on implementation (tight coupling)
+function UserService() {
+  const supabase = useSecureSupabase();
+  async function getUser(id: string) {
+    const { data } = await supabase.from('users').select('*').eq('id', id).single();
+    return data;
+  }
+  return { getUser };
+}
+
+// ✅ CORRECT: Abstracted interface (depend on abstraction)
+interface UserRepository { getUser(id: string): Promise<User | null>; }
+function createUserRepository(supabase: SupabaseClient): UserRepository {
+  return { async getUser(id: string) { /* implementation */ } };
+}
+function useUserService() {
+  const supabase = useSecureSupabase();
+  const repository = useMemo(() => createUserRepository(supabase), [supabase]);
+  return { getUser: repository.getUser };
+}
+```
+
+### SHOULD: Use Dependency Injection
+
+**Inject dependencies rather than creating them:**
+
+```tsx
+// ❌ WRONG: Hard-coded dependency
+function EventService() { const api = new ApiClient('https://api.example.com'); }
+
+// ✅ CORRECT: Injected dependency (dependency injection)
+function EventService(api: ApiClient) { ... }
+// Or with React context: const api = useApiClient(); useMemo(() => new EventService(api), [api]);
+```
+
+## SOLID Checklist
+
+Before committing code, verify:
+- [ ] Each function/component has single responsibility
+- [ ] Complex logic extracted to hooks/services
+- [ ] Extension through composition, not modification
+- [ ] Interfaces are focused and specific
+- [ ] Dependencies are abstracted
+- [ ] No god objects or bloated components
+- [ ] Code is testable and maintainable
+
+## Anti-Patterns to Avoid
+
+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
+
+## Reference
+
+- Single Responsibility: Each module has one reason to change
+- Open/Closed: Open for extension, closed for modification
+- Liskov Substitution: Subtypes must be substitutable
+- Interface Segregation: Many specific interfaces, not one general
+- Dependency Inversion: Depend on abstractions, not concretions

package/cursor-rules/04-testing-standards.mdc

@@ -0,0 +1,268 @@
+---
+description: Enforce testing framework consistency and standards for consuming apps
+globs: ["**/*.{test,spec}.{ts,tsx}"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Testing Standards Guide
+
+This guide ensures consistent, high-quality testing across consuming apps in the PACE suite.
+
+## MUST: Meet Coverage Requirements
+
+**MUST achieve minimum coverage:**
+- ≥90% coverage for utils & hooks
+- ≥70% coverage for components
+
+**Verify coverage:**
+```bash
+npm run test:coverage
+```
+
+## MUST: Use React Testing Library
+
+**MUST use React Testing Library + userEvent for all component tests.**
+
+```tsx
+// ✅ CORRECT: React Testing Library + userEvent
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+test('button clicks work', async () => {
+  const user = userEvent.setup();
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click me</Button>);
+  await user.click(screen.getByRole('button', { name: /click me/i }));
+  expect(handleClick).toHaveBeenCalledTimes(1);
+});
+
+// ❌ WRONG: Enzyme or other testing libraries
+```
+
+## MUST: Colocate Tests
+
+**Tests MUST be colocated with source files:**
+
+```
+src/
+├── components/
+│   └── EventCard/
+│       ├── EventCard.tsx
+│       └── EventCard.test.tsx
+├── hooks/
+│   ├── useEventData.ts
+│   └── useEventData.test.ts
+└── utils/
+    ├── formatEvent.ts
+    └── formatEvent.test.ts
+```
+
+## MUST: Use Vitest
+
+**MUST use Vitest for all testing:**
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 80,
+        statements: 80,
+      },
+    },
+  },
+});
+```
+
+## MUST: Test User Behavior, Not Implementation
+
+**Tests MUST focus on what users see and do:**
+
+```tsx
+// ❌ WRONG: Testing implementation (component.state.count)
+test('calls setState', () => { const component = render(<Counter />); expect(component.state.count).toBe(0); });
+
+// ✅ CORRECT: Testing user behavior (what user sees and does)
+test('displays count and increments on button click', async () => {
+  const user = userEvent.setup();
+  render(<Counter />);
+  expect(screen.getByText('Count: 0')).toBeInTheDocument();
+  await user.click(screen.getByRole('button', { name: /increment/i }));
+  expect(screen.getByText('Count: 1')).toBeInTheDocument();
+});
+```
+
+## MUST: Use Accessible Queries
+
+**MUST prefer accessible queries (byRole, byLabelText, etc.):**
+
+```tsx
+// ✅ CORRECT: Accessible queries (byRole, byLabelText, byText)
+screen.getByRole('button', { name: /submit/i });
+screen.getByLabelText(/email address/i);
+
+// ❌ AVOID: Non-accessible queries (getByTestId, getByClassName - use as last resort)
+```
+
+## SHOULD: Test Critical Paths
+
+**SHOULD test:**
+- User workflows and interactions
+- Error handling and edge cases
+- Form validation
+- Permission checks (RBAC)
+- Data loading states
+- Error states
+
+## SHOULD: Use Descriptive Test Names
+
+**Test names SHOULD describe behavior:**
+
+```tsx
+// ❌ WRONG - Vague
+test('button works', () => { ... });
+
+// ✅ CORRECT - Descriptive
+test('increments counter when increment button is clicked', () => { ... });
+test('displays error message when API call fails', () => { ... });
+```
+
+## SHOULD: Group Related Tests
+
+**SHOULD use `describe` blocks to group related tests:**
+
+```tsx
+describe('EventCard', () => {
+  describe('rendering', () => {
+    test('displays event title', () => { ... });
+    test('displays event date', () => { ... });
+  });
+  
+  describe('interactions', () => {
+    test('calls onEdit when edit button clicked', () => { ... });
+    test('calls onDelete when delete button clicked', () => { ... });
+  });
+});
+```
+
+## MUST: Avoid Unnecessary Mocks
+
+**MUST NOT mock unless necessary:**
+
+```tsx
+// ❌ WRONG: Unnecessary mock (global.fetch = mockFetch)
+// ✅ CORRECT: Use real implementation or MSW
+import { server } from './mocks/server';
+server.use(rest.get('/api/events', (req, res, ctx) => res(ctx.json([{ id: '1', name: 'Event' }]))));
+```
+
+## MUST: Test Async Code Properly
+
+**MUST handle async operations correctly:**
+
+```tsx
+// ✅ CORRECT: Async testing with waitFor
+test('loads and displays events', async () => {
+  render(<EventList />);
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  await waitFor(() => expect(screen.getByText('Event 1')).toBeInTheDocument());
+  expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+});
+```
+
+## MUST: Clean Up After Tests
+
+**MUST clean up resources:**
+
+```tsx
+// ✅ CORRECT: Cleanup after tests
+afterEach(() => { cleanup(); vi.clearAllMocks(); });
+```
+
+## SHOULD: Use Test Utilities
+
+**SHOULD create reusable test utilities:**
+
+```tsx
+// ✅ CORRECT: Reusable test utilities
+export function renderWithProviders(ui: React.ReactElement) {
+  return render(<UnifiedAuthProvider supabaseClient={mockSupabase} appName="Test App">{ui}</UnifiedAuthProvider>);
+}
+// Usage: renderWithProviders(<MyComponent />);
+```
+
+## MUST: Include Timeout Parameters
+
+**Tests MUST include timeout parameters to prevent hanging:**
+
+```tsx
+// ✅ CORRECT: Include timeout parameters to prevent hanging
+test('async operation completes', async () => {
+  await waitFor(() => expect(screen.getByText('Loaded')).toBeInTheDocument(), { timeout: 5000 });
+}, { timeout: 10000 });
+```
+
+## Testing Checklist
+
+Before committing tests, verify:
+- [ ] Coverage meets requirements (≥90% utils, ≥70% components)
+- [ ] Using React Testing Library + userEvent
+- [ ] Tests are colocated with source files
+- [ ] Testing user behavior, not implementation
+- [ ] Using accessible queries (byRole, byLabelText)
+- [ ] Test names are descriptive
+- [ ] Related tests grouped with describe
+- [ ] No unnecessary mocks
+- [ ] Async code tested properly
+- [ ] Cleanup after tests
+- [ ] Timeout parameters included
+
+## Test Structure Template
+
+```tsx
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ComponentName } from './ComponentName';
+
+describe('ComponentName', () => {
+  beforeEach(() => {
+    // Setup
+  });
+  
+  afterEach(() => {
+    // Cleanup
+    vi.clearAllMocks();
+  });
+  
+  describe('rendering', () => {
+    test('renders correctly', () => {
+      render(<ComponentName />);
+      // Assertions
+    });
+  });
+  
+  describe('interactions', () => {
+    test('handles user interaction', async () => {
+      const user = userEvent.setup();
+      render(<ComponentName />);
+      // Test interaction
+    });
+  });
+});
+```
+
+## Reference
+
+- React Testing Library: https://testing-library.com/react
+- Vitest: https://vitest.dev
+- Testing Standards: See `06-testing-and-docs-standard.md` in pace-core docs