@jmruthers/pace-core 0.6.6 → 0.6.8

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

@@ -1,285 +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.
-
-## MUST: Include Complete Cursor Ruleset
-
-Consuming apps **MUST** include the complete pace-core ruleset in the repository so audits are deterministic and repeatable.
-
-- **MUST** include these files under `.cursor/rules/` (exact filenames):
-  - `00-pace-core-compliance.mdc`
-  - `01-standards-compliance.mdc`
-  - `02-project-structure.mdc`
-  - `03-solid-principles.mdc`
-  - `06-code-quality.mdc`
-  - `07-tech-stack-compliance.mdc`
-  - `08-markup-quality.mdc`
-  - `09-rbac-compliance.mdc`
-  - `10-error-handling-patterns.mdc`
-  - `11-performance-optimization.mdc`
-- **MUST NOT** rename or partially copy rules files.
-- If a rule does not apply to a given app, document the exception and the reason, but keep the rule file present.
-
-
-## 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: Enforce Coverage Thresholds in Tooling
-
-Coverage requirements must be **machine-enforced**, not aspirational:
-
-- **MUST** provide a script: `npm run test:coverage`
-- **MUST** configure the test runner (Vitest/Jest) to enforce the thresholds:
-  - ≥90% for utils & hooks
-  - ≥70% for components
-- **MUST** fail the command when thresholds are not met (CI or local execution).
-
-**Verification:**
-- `npm run test:coverage` exits non-zero when below threshold.
-- A coverage summary artifact is produced (e.g., `coverage/coverage-summary.json` or equivalent).
-
-### 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
-
-**📚 Human-Readable Standard**: See [01-standards-compliance.md](../../packages/core/docs/standards/01-standards-compliance.md) for complete documentation.
-
-**Related Standards** (all have corresponding cursor rules):
-- **00-pace-core-compliance.mdc** - pace-core usage patterns
-- **02-project-structure.mdc** - Project structure and organization
-- **03-solid-principles.mdc** - SOLID architecture principles
-- **04-testing-standards.mdc** - Testing framework standards
-- **05-bug-reports-and-features.mdc** - Issue reporting templates
-- **06-code-quality.mdc** - Code quality and TypeScript standards
-- **07-tech-stack-compliance.mdc** - Tech stack and API/RPC standards
-- **08-markup-quality.mdc** - Markup and styling standards
-- **09-rbac-compliance.mdc** - RBAC and RLS standards
-- **10-error-handling-patterns.mdc** - Error handling patterns
-- **11-performance-optimization.mdc** - Performance optimization
-- **12-ci-cd-integration.mdc** - CI/CD integration patterns

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

@@ -1,270 +0,0 @@
----
-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
-
-**📚 Human-Readable Standard**: See [04-testing-standards.md](../../packages/core/docs/standards/04-testing-standards.md) for complete documentation.
-
-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