@jmruthers/pace-core 0.6.6 → 0.6.8

package/docs/standards/README.md

@@ -1,104 +1,203 @@
-# 📚 PACE Standards — Master README
-
-## Purpose
-This document is the single source of truth for all engineering standards for pace-core and consuming apps.
-
-## pace-core Standards (aligned with Cursor rule filenames)
-
-Each standard document has a corresponding Cursor rule file (`.mdc`) that enforces the standard automatically. The numbering ensures traceability. Standards 00-09 are core standards, while 10-12 are enhanced standards covering additional best practices.
-
-| Standard | Cursor Rule | Purpose |
-|----------|------------|---------|
-| **00-pace-core-compliance.md** | `00-pace-core-compliance.mdc` | Enforce pace-core usage patterns and prevent custom solutions |
-| **01-standards-compliance.md** | `01-standards-compliance.mdc` | Enforce all pace-core standards across architecture, API, components, code style, security, testing, and RBAC/RLS |
-| **02-project-structure.md** | `02-project-structure.mdc` | Define standard folder structure and file organization |
-| **03-solid-principles.md** | `03-solid-principles.mdc` | Enforce SOLID architecture principles |
-| **04-testing-standards.md** | `04-testing-standards.mdc` | Enforce testing framework consistency and standards |
-| **05-bug-reports-and-features.md** | `05-bug-reports-and-features.mdc` | Standardized templates for bug reports and feature requests |
-| **06-code-quality.md** | `06-code-quality.mdc` | Enforce code quality standards including TypeScript, ESLint, formatting, performance, and accessibility |
-| **07-tech-stack-compliance.md** | `07-tech-stack-compliance.mdc` | Enforce tech stack compliance including Tailwind v4, React 19+, Supabase, and other required technologies |
-| **08-markup-quality.md** | `08-markup-quality.mdc` | Enforce clean markup standards, semantic HTML usage, and pace-core component patterns |
-| **09-rbac-compliance.md** | `09-rbac-compliance.mdc` | Enforce RBAC contract compliance - strict rules for permission checking, page protection, and RBAC usage patterns |
-| **10-error-handling-patterns.md** | `10-error-handling-patterns.mdc` | Enforce consistent error handling patterns including type-safe errors, user-friendly messages, and proper logging |
-| **11-performance-optimization.md** | `11-performance-optimization.mdc` | Enforce performance optimization patterns including React memoization, database query optimization, and caching strategies |
-| **12-ci-cd-integration.md** | `12-ci-cd-integration.mdc` | Enforce CI/CD integration patterns including automated quality checks, deployment processes, and security scanning |
-
-**Note**: Standards are human-readable documentation. Rules are AI-optimized directives for Cursor. Both should be kept in sync. Standards 00-09 are core standards, while 10-12 are enhanced standards covering additional best practices.
-
-## Consuming App Standards
-
-All standards in this directory apply to consuming apps. The standards are organized by topic:
-
-### Core Standards (00-09)
-These are fundamental standards that all consuming apps must follow:
-- **00-pace-core-compliance.md** - Use pace-core components, hooks, and utilities
-- **01-standards-compliance.md** - Meta-standard for precedence and traceability
-- **02-project-structure.md** - Standard folder structure and file organization
-- **03-solid-principles.md** - SOLID architecture principles
-- **04-testing-standards.md** - Testing framework consistency
-- **05-bug-reports-and-features.md** - Issue reporting templates
-- **06-code-quality.md** - TypeScript, ESLint, formatting, accessibility
-- **07-tech-stack-compliance.md** - Required technology versions
-- **08-markup-quality.md** - Clean markup, semantic HTML, CSS configuration
-- **09-rbac-compliance.md** - RBAC contract and RLS policy patterns
-
-### Enhanced Standards (10-12)
-These are best practice standards for advanced patterns:
-- **10-error-handling-patterns.md** - Consistent error handling
-- **11-performance-optimization.md** - Performance best practices
-- **12-ci-cd-integration.md** - CI/CD pipeline patterns
-
-## Precedence
-1. Security
-2. API/RPC
-3. Components
-4. Code Style
-5. Testing
-6. Documentation
-7. Consuming App Standards
-
-## AI Rules
-- Read relevant standards
-- Apply Cursor Checklists
-- Prefer pace-core for reusable logic
-- Update docs on API changes
-
-## Cursor Rules
-
-pace-core provides comprehensive Cursor rules that automatically enforce these standards in consuming apps.
-
-### Installation
-
-Install cursor rules in your consuming app:
-
-```bash
-node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
-```
-
-### Rule Files
-
-The cursor rules automatically enforce the corresponding standards. Each rule file (`.mdc`) is optimized for AI agents with:
-- Clear MUST/SHOULD/MAY directives
-- Decision trees for common scenarios
-- ✅/❌ code examples
-- Actionable checklists
-
-**Rule → Standard Mapping:**
-- **00-pace-core-compliance.mdc** → `00-pace-core-compliance.md`
-- **01-standards-compliance.mdc** → `01-standards-compliance.md`
-- **02-project-structure.mdc** → `02-project-structure.md`
-- **03-solid-principles.mdc** → `03-solid-principles.md`
-- **04-testing-standards.mdc** → `04-testing-standards.md`
-- **05-bug-reports-and-features.mdc** → `05-bug-reports-and-features.md`
-- **06-code-quality.mdc** → `06-code-quality.md`
-- **07-tech-stack-compliance.mdc** → `07-tech-stack-compliance.md`
-- **08-markup-quality.mdc** → `08-markup-quality.md`
-- **09-rbac-compliance.mdc** → `09-rbac-compliance.md`
-- **10-error-handling-patterns.mdc** → `10-error-handling-patterns.md`
-- **11-performance-optimization.mdc** → `11-performance-optimization.md`
-- **12-ci-cd-integration.mdc** → `12-ci-cd-integration.md`
-
-### Documentation
-
-- [Cursor Rules Quick Start](../getting-started/cursor-rules.md)
-- [Cursor Rules README](../../cursor-rules/README.md)
+# Pace Standards
+
+This repository defines the **canonical development standards** for **pace-core** and **all consuming applications** in the pace-suite.
+
+These standards are **human-readable first**, but are deliberately structured so they can be **enforced by automation**, including Cursor rules, ESLint, and custom audit tooling.
+
+They are the **single source of truth**.  
+All other quality tools must align *to these standards*, not reinterpret them.
+
+---
+
+## How to use these standards
+
+### pace-core
+- Treat these standards as **hard constraints**
+- pace-core sets the bar and defines the contracts
+- Any deviation must be explicitly documented here
+
+### Consuming applications
+- Inherit these standards by default
+- Only diverge where a documented exception exists
+- Consuming apps should never weaken standards silently
+
+### AI agents (Cursor, Codex, etc.)
+- Follow these standards **strictly**
+- Do **not** silence rules to "make things pass"
+- If compliance is unclear, stop and report rather than guessing
+
+---
+
+## The Four Layers of Quality Enforcement
+
+The pace-suite uses **four complementary quality layers**, each with a distinct responsibility.  
+They are intentionally overlapping in *coverage*, but **not duplicative in purpose**.
+
+Think of this as *defence in depth*, not redundancy.
+
+---
+
+### 1. Standards Documents (Source of Truth)
+
+**What they are**
+- Human-readable `.md` documents
+- Describe *intent*, *principles*, and *expectations*
+- Technology-agnostic where possible
+
+**What they are used for**
+- Defining *what "good" looks like*
+- Onboarding humans and AI agents
+- Resolving ambiguity when tools disagree
+- Designing new rules, lint checks, and audits
+
+**What they are NOT**
+- They are not executable
+- They do not enforce anything by themselves
+- They should not contain implementation hacks
+
+➡️ **If there is a conflict, the standards win.**
+
+---
+
+### 2. Cursor Rules (Real-time Guidance)
+
+**What they are**
+- AI-optimised interpretations of the standards
+- Applied while code is being written or modified
+- Prevent mistakes *before* they land
+
+**What they are used for**
+- Steering AI agents toward correct patterns
+- Enforcing architectural intent during development
+- Reducing rework later in linting or audits
+
+**What they are NOT**
+- They are not a replacement for lint or audits
+- They should not invent new standards
+- They should not silence problems "to move on"
+
+➡️ Cursor rules **translate standards into behaviour**, but do not redefine them.
+
+---
+
+### 3. ESLint (Fast, Local Static Analysis)
+
+**What it is**
+- Deterministic, file-level static analysis
+- Runs locally and in CI
+- Focused on correctness, safety, and consistency
+
+**What it is used for**
+- Catching obvious issues early (types, hooks, imports, patterns)
+- Enforcing mechanically checkable rules
+- Preventing regressions during refactors
+
+**What it is NOT**
+- ESLint should not encode complex business rules
+- It should not contain subjective or architectural debates
+- It should not be silenced to "get green builds"
+
+➡️ ESLint enforces *how code is written*, not *whether the system is correct*.
+
+---
+
+### 4. Audit Tool (Deep, System-Level Analysis)
+
+**What it is**
+- A custom static analysis tool
+- Operates across files, folders, and systems
+- Understands pace-core contracts and invariants
+
+**What it is used for**
+- Validating architectural compliance (RBAC, data access, boundaries)
+- Catching issues ESLint cannot see
+- Providing actionable remediation plans
+
+**What it is NOT**
+- It is not a linter replacement
+- It should not report stylistic issues
+- It should not contradict the standards
+
+➡️ The audit tool answers: *"Is this system actually compliant?"*
+
+---
+
+## How the layers work together
+
+| Layer        | Strength                         | Timing          |
+|--------------|----------------------------------|-----------------|
+| Standards    | Intent & clarity                 | Design time     |
+| Cursor rules | Preventive guidance              | Write time      |
+| ESLint       | Fast mechanical enforcement      | Dev / CI        |
+| Audit tool   | Deep architectural verification  | Review / CI     |
+
+No single layer is sufficient on its own.  
+Together, they create a **repeatable, scalable quality system** for both humans and AI.
+
+---
+
+## Standards Documents
+
+The standards are organized into **10 files**, each covering a specific domain:
+
+### 0. [Standards Overview](./0-standards-overview.md)
+Entry point, precedence, how standards work, and the four layers of quality enforcement.
+
+### 1. [pace-core Compliance](./1-pace-core-compliance-standards.md)
+pace-core usage patterns, ESLint rules, secure Supabase client requirements, and compliance enforcement.
+
+### 2. [Project Structure](./2-project-structure-standards.md)
+Standard directory structure, file organization patterns, naming conventions, and migration guides.
+
+### 3. [Architecture](./3-architecture-standards.md)
+SOLID principles, component design, API design, and architectural patterns.
+
+### 4. [Code Quality](./4-code-quality-standards.md)
+TypeScript rules, naming conventions, code style patterns, and React patterns.
+
+### 5. [Styling](./5-styling-standards.md)
+**CRITICAL:** Required CSS configuration, Tailwind v4 setup, markup quality, and styling patterns.
+
+### 6. [Security & RBAC](./6-security-rbac-standards.md)
+RLS policy patterns, RBAC integration, helper functions, and security requirements.
+
+### 7. [API & Tech Stack](./7-api-tech-stack-standards.md)
+Required tech stack, API/RPC naming conventions, result shapes, and deprecation policy.
+
+### 8. [Testing & Documentation](./8-testing-documentation-standards.md)
+Testing strategy, documentation requirements, bug report templates, and feature request templates.
+
+### 9. [Operations](./9-operations-standards.md)
+Error handling patterns, performance optimization, caching strategies, and CI/CD integration.
+
+---
+
+## Key Principles
+
+- **Do not silence tools** — fix the underlying issue
+- **Do not duplicate rules** — each layer has a purpose
+- **Do not diverge silently** — document exceptions explicitly
+- **Standards always win** — tools must align to them
+
+---
+
+## Getting Started
+
+1. **Read the Overview** - Start with [0-standards-overview.md](./0-standards-overview.md) to understand the system
+2. **Review Critical Standards** - Pay special attention to:
+   - [5-styling-standards.md](./5-styling-standards.md) - **CRITICAL CSS configuration**
+   - [1-pace-core-compliance-standards.md](./1-pace-core-compliance-standards.md) - pace-core usage
+   - [6-security-rbac-standards.md](./6-security-rbac-standards.md) - Security and RBAC
+3. **Set Up Quality Enforcement** - Install Cursor rules and ESLint config:
+   - `npm run setup:cursor-rules` - Install Cursor rules for AI-assisted enforcement
+   - `npm run setup:eslint` - Install ESLint config for real-time linting
+4. **Run Audits** - Use the audit tool to validate compliance:
+   - `npm run audit:pace-core` - Run comprehensive audit organized by standards
+5. **Follow the Standards** - Use the standards as your guide for all development work
+6. **Reference When Needed** - Use the standards to resolve conflicts and answer questions
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 2.0.0  
+**Applies to:** All pace-core and consuming apps

package/docs/troubleshooting/README.md

@@ -84,7 +84,7 @@ import '@jmruthers/pace-core/src/styles/core.css';
 ```tsx
 // ✅ Check if user has proper context
 const { hasPermission, isLoading } = useCan();
-if (isLoading) return <div>Loading permissions...</div>;
+if (isLoading) return <p>Loading permissions...</p>;
 
 // ✅ Ensure proper scope
 <PermissionGuard
@@ -525,8 +525,8 @@ function useDebugRender(componentName: string, props?: any) {
 function MyComponent({ data, loading }) {
   useDebugRender('MyComponent', { data, loading });
   
-  if (loading) return <div>Loading...</div>;
-  return <div>{data}</div>;
+  if (loading) return <p>Loading...</p>;
+  return <p>{data}</p>;
 }
 ```
 
@@ -922,5 +922,5 @@ When issues occur intermittently:
 - [Common Issues](./common-issues.md) - Specific problem solutions
 - [Styling Issues](./styling-issues.md) - Component styling problems
 - [Authentication Guide](../implementation-guides/authentication.md) - Auth troubleshooting
-- [Performance Guide](../best-practices/performance.md) - Performance debugging
+- [Performance Optimization](../standards/9-operations-standards.md#performance-optimization) - Performance debugging
 - [API Reference](../api-reference/) - Component documentation

package/docs/troubleshooting/common-issues.md

@@ -142,7 +142,7 @@ import { useUnifiedAuth } from '@jmruthers/pace-core'
 function DebugComponent() {
   const auth = useUnifiedAuth()
   console.log('Auth context:', auth)
-  return <div>Check console for auth context</div>
+  return <p>Check console for auth context</p>
 }
 ```
 
@@ -154,7 +154,7 @@ import { useRBAC } from '@jmruthers/pace-core'
 function DebugRBAC() {
   const rbac = useRBAC()
   console.log('RBAC context:', rbac)
-  return <div>Check console for RBAC context</div>
+  return <p>Check console for RBAC context</p>
 }
 ```
 

package/docs/troubleshooting/debugging.md

@@ -46,8 +46,8 @@ function useDebugRender(componentName: string, props?: any) {
 function MyComponent({ data, loading }) {
   useDebugRender('MyComponent', { data, loading });
   
-  if (loading) return <div>Loading...</div>;
-  return <div>{data}</div>;
+  if (loading) return <p>Loading...</p>;
+  return <p>{data}</p>;
 }
 ```
 
@@ -205,7 +205,7 @@ function MyComponent() {
     prevState.current = state;
   }, [state]);
   
-  return <div>{state.count}</div>;
+  return <p>{state.count}</p>;
 }
 ```
 
@@ -273,7 +273,7 @@ function ExpensiveComponent() {
   useRenderDebug('ExpensiveComponent');
   
   // Component logic here
-  return <div>Expensive content</div>;
+  return <p>Expensive content</p>;
 }
 ```
 
@@ -320,11 +320,11 @@ export function useAuthDebug() {
 function AuthDebugger() {
   const auth = useAuthDebug();
   
-  if (auth.loading) return <div>Loading auth...</div>;
-  if (auth.error) return <div>Auth error: {auth.error}</div>;
-  if (!auth.user) return <div>Not authenticated</div>;
+  if (auth.loading) return <p>Loading auth...</p>;
+  if (auth.error) return <p>Auth error: {auth.error}</p>;
+  if (!auth.user) return <p>Not authenticated</p>;
   
-  return <div>Authenticated as: {auth.user.email}</div>;
+  return <p>Authenticated as: {auth.user.email}</p>;
 }
 ```
 
@@ -589,7 +589,7 @@ function MyComponent() {
   useMemoryLeakDetection('MyComponent');
   
   // Component logic
-  return <div>Content</div>;
+  return <p>Content</p>;
 }
 ```
 

package/docs/troubleshooting/migration.md

@@ -31,10 +31,10 @@ function MyComponent() {
   const { hasPermission } = usePermissions();
   
   return (
-    <div>
+    <section>
       {user && <p>Welcome, {user.email}</p>}
       {hasPermission('read:users') && <UserList />}
-    </div>
+    </section>
   );
 }
 
@@ -47,10 +47,10 @@ function MyComponent() {
   const { hasPermission } = useCan();
   
   return (
-    <div>
+    <section>
       {user && <p>Welcome, {user.email}</p>}
       {hasPermission('read:users') && <UserList />}
-    </div>
+    </section>
   );
 }
 ```

package/eslint-config-pace-core.cjs

@@ -31,40 +31,45 @@ try {
   console.warn('Warning: Could not load core-usage-manifest.json for ESLint config');
 }
 
-// Load pace-core compliance rules
+// Load pace-core ESLint rules
 let paceCoreRules = {};
+const sourceRulesPath = path.resolve(__dirname, 'eslint-rules/index.cjs');
+const distRulesPath = path.resolve(__dirname, 'dist/eslint-rules/index.cjs');
+const cwdRulesPath = path.resolve(process.cwd(), 'node_modules/@jmruthers/pace-core/dist/eslint-rules/index.cjs');
+
 try {
-  // Try source path first (for development)
-  const sourceRulesPath = path.resolve(__dirname, 'src/eslint-rules/index.cjs');
+  // Try source path first (for development) - new location at package root
   if (fs.existsSync(sourceRulesPath)) {
     paceCoreRules = require(sourceRulesPath).rules;
   } else {
     // Try dist path (for published package)
-    const distRulesPath = path.resolve(__dirname, 'dist/eslint-rules/index.cjs');
     if (fs.existsSync(distRulesPath)) {
       paceCoreRules = require(distRulesPath).rules;
     } else {
       // Try relative to current working directory (for consuming apps)
-      const cwdRulesPath = path.resolve(process.cwd(), 'node_modules/@jmruthers/pace-core/dist/eslint-rules/index.cjs');
       if (fs.existsSync(cwdRulesPath)) {
         paceCoreRules = require(cwdRulesPath).rules;
       }
     }
   }
 } catch (error) {
-  // Silently fail - rules will be empty, but config will still work
+  // Log warning in development but don't fail - rules will be empty, but config will still work
   // This allows the config to be used even if rules aren't available
+  if (process.env.NODE_ENV !== 'production') {
+    console.warn(`Warning: Could not load pace-core ESLint rules: ${error.message}`);
+    console.warn(`  Tried paths: ${sourceRulesPath}, ${distRulesPath}, ${cwdRulesPath}`);
+  }
 }
 
 // Build restricted imports for no-restricted-imports rule (ESLint 9 flat config format)
-// ESLint 9 expects an array of objects with 'name' (string or regex) and 'message'
-const restrictedImportRules = restrictedImports.map(({ module, reason }) => ({
+// ESLint 9 expects an object with 'paths' array - all restrictions use 'name' property
+const restrictedPaths = restrictedImports.map(({ module, reason }) => ({
   name: module,
   message: reason || `Use pace-core alternative instead of direct import of '${module}'`
 }));
 
-// Also add pattern for @radix-ui/* (catch-all) - use string pattern format
-restrictedImportRules.push({
+// Add @radix-ui/* pattern (also uses 'name' property, wildcards work with 'name')
+restrictedPaths.push({
   name: '@radix-ui/*',
   message: 'Use pace-core components instead of direct Radix UI imports'
 });
@@ -77,20 +82,22 @@ module.exports = [
       }
     },
     rules: {
-      // Import rules
-      'pace-core-compliance/no-restricted-imports': 'error',
-      
-      // Compliance rules
+      // Standard 1: pace-core Compliance
       'pace-core-compliance/prefer-pace-core-components': 'warn',
       'pace-core-compliance/prefer-pace-core-hooks': 'warn',
       'pace-core-compliance/prefer-pace-core-utils': 'warn',
       'pace-core-compliance/no-local-component-duplication': 'error',
-      'pace-core-compliance/no-inline-styles': 'error',
-      
-      // Component rules
       'pace-core-compliance/prefer-pace-core-form': 'error',
       
-      // RBAC rules
+      // Standard 4: Code Quality
+      'pace-core-compliance/naming-convention': 'warn',
+      'pace-core-compliance/component-naming': 'warn',
+      'pace-core-compliance/type-naming': 'warn',
+      
+      // Standard 5: Styling
+      'pace-core-compliance/no-inline-styles': 'error',
+      
+      // Standard 6: Security & RBAC
       'pace-core-compliance/no-direct-supabase-client': 'error',
       'pace-core-compliance/rbac-permission-loading': 'error',
       'pace-core-compliance/no-direct-rbac-rpc': 'error',
@@ -100,9 +107,32 @@ module.exports = [
       'pace-core-compliance/no-rbac-wrapper-components': 'error',
       'pace-core-compliance/no-rbac-wrapper-functions': 'error',
       
+      // Standard 7: API & Tech Stack
+      'pace-core-compliance/rpc-naming-pattern': 'warn',
+      'pace-core-compliance/no-class-components': 'error',
+      'pace-core-compliance/prefer-import-meta-env': 'error',
+      
+      // Standard 8: Testing
+      'pace-core-compliance/test-file-naming': 'warn',
+      
       // Also use standard no-restricted-imports (ESLint 9 flat config format)
-      // Note: ESLint 9 uses a simpler array format
-      'no-restricted-imports': ['error', ...restrictedImportRules]
+      // ESLint 9 expects an object with 'paths' array containing objects with 'name' property
+      'no-restricted-imports': ['error', {
+        paths: restrictedPaths
+      }]
+    }
+  },
+  // Override for Edge Functions (Deno runtime)
+  // Edge Functions run in Deno, not React, so they cannot use React hooks
+  // They need direct Supabase client access and console.log for debugging
+  {
+    files: ['**/supabase/functions/**/*.{ts,js}'],
+    rules: {
+      // Allow console.log in Edge Functions for debugging and monitoring
+      'no-console': 'off',
+      // Edge Functions cannot use React hooks, so they must use createClient directly
+      // The rule already excludes Edge Functions, but we explicitly allow it here for clarity
+      'pace-core-compliance/no-direct-supabase-client': 'off',
     }
   }
 ];