@jmruthers/pace-core 0.6.5 → 0.6.7

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

@@ -1,309 +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
-
-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,214 +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
-
-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/CHANGELOG.md

@@ -1,119 +0,0 @@
-# Cursor Rules Changelog
-
-All notable changes to pace-core cursor rules will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- **08-markup-quality.mdc** - Enforces clean markup standards, semantic HTML usage, and pace-core component patterns
-
-## [1.1.0] - 2025-01-28
-
-### Added
-- **08-markup-quality.mdc** - Comprehensive guide for markup quality, semantic HTML, and pace-core component usage patterns
-  - Enforces pace-core component usage over custom solutions
-  - Prohibits `<div>` elements (except first child of `<body>` in `index.html`)
-  - Requires semantic HTML elements (`<main>`, `<section>`, `<article>`, etc.)
-  - Prohibits typography styling (relies on pace-core core.css)
-  - Requires React Fragments for grouping without semantic meaning
-  - Enforces minimal element nesting and clear semantic purpose
-  - Includes decision tree and comprehensive checklist
-
-## [1.0.0] - 2025-01-15
-
-### Added
-- Initial release of cursor rules system
-- 8 comprehensive rule files covering compliance, standards, structure, SOLID, testing, bug reports, code quality, and tech stack
-- Installation script with safety guards
-- Comprehensive audit tool with Phase 1 (deterministic) and Phase 2 (heuristic) checks
-- Markdown report generation with timestamps
-
-## [1.0.0] - 2025-01-15
-
-### Added
-- **00-pace-core-compliance.mdc** - Enforces pace-core usage patterns
-- **01-standards-compliance.mdc** - Maps to all pace-core standards
-- **02-project-structure.mdc** - Defines standard folder structure
-- **03-solid-principles.mdc** - Enforces SOLID architecture principles
-- **04-testing-standards.mdc** - Enforces testing framework consistency
-- **05-bug-reports-and-features.mdc** - Templates for bug reports and feature requests
-- **06-code-quality.mdc** - Enforces code quality standards
-- **07-tech-stack-compliance.mdc** - Enforces tech stack versions and patterns
-
-### Features
-- Opt-in installation script (not automatic postinstall)
-- Safety guards (environment variable, git check)
-- Version tracking in rule files
-- Rule numbering system (pace-core: 00-09, apps: 50+)
-- Targeted globs for efficient rule application
-- MUST/SHOULD/MAY semantics for clear guidance
-- Comprehensive audit tool with markdown reports
-- Phase-based audit approach (deterministic vs heuristic)
-
-### Documentation
-- README.md with installation and usage guide
-- Getting started guide in docs
-- Updated standards README with cursor rules section
-
-## Migration Guide
-
-### From No Rules to Cursor Rules
-
-1. Install pace-core (if not already installed):
-   ```bash
-   npm install @jmruthers/pace-core
-   ```
-
-2. Install cursor rules:
-   ```bash
-   node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
-   ```
-
-3. Restart Cursor to load rules
-
-4. Run audit to check compliance:
-   ```bash
-   node node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs
-   ```
-
-### Updating Rules
-
-When pace-core is updated:
-
-1. Update pace-core:
-   ```bash
-   npm update @jmruthers/pace-core
-   ```
-
-2. Update rules:
-   ```bash
-   npm run setup:cursor-rules
-   ```
-
-3. Review any changes in rule files
-
-### Custom Rules
-
-If you have custom rules, number them starting at 50:
-- `50-my-custom-rule.mdc`
-- `51-another-rule.mdc`
-- etc.
-
-This ensures pace-core rules (00-09) load first.
-
-## Version History
-
-- **1.1.0** (2025-01-28) - Added markup quality rule (08-markup-quality.mdc)
-- **1.0.0** (2025-01-15) - Initial release
-
-## Future Enhancements
-
-Potential future enhancements:
-- CLI for rule validation
-- GitHub Action template for PR audits
-- Rule update notification system
-- Interactive rule configuration
-- Rule effectiveness metrics