@jmruthers/pace-core 0.6.4 → 0.6.6

package/cursor-rules/00-pace-core-compliance.mdc

@@ -7,6 +7,10 @@ rulesVersion: "2025-01-28"
 ---
 # pace-core Compliance Guide
 
+**📚 Human-Readable Standard**: See [00-pace-core-compliance.md](../../packages/core/docs/standards/00-pace-core-compliance.md) for complete documentation.
+
+This guide ensures consuming apps use pace-core components, hooks, and utilities correctly, preventing duplication and maintaining consistency across the PACE suite.
+
 This guide ensures consuming apps use pace-core components, hooks, and utilities correctly, preventing duplication and maintaining consistency across the PACE suite.
 
 ## MUST: Use pace-core Instead of Custom Solutions
@@ -27,7 +31,7 @@ This guide ensures consuming apps use pace-core components, hooks, and utilities
 - Create custom button components when `Button` from pace-core exists
 - Use native HTML elements (`<button>`, `<input>`) when pace-core provides components
 - Import directly from `@radix-ui/*` - Use pace-core wrappers instead
-- Import directly from `lucide-react` - Use pace-core components that include icons
+- Import directly from `lucide-react` - Import icons from `@jmruthers/pace-core/icons` instead
 
 **Example:**
 ```tsx
@@ -77,45 +81,106 @@ This guide ensures consuming apps use pace-core components, hooks, and utilities
 
 ## MUST: Use Secure Supabase Client
 
-**You MUST use `useSecureSupabase()` for all database operations.** Never use the base Supabase client directly.
+**All database operations MUST use `useSecureSupabase()` (or the contract-approved pace-core secure client wrapper).**
+Consuming apps **MUST NOT** use the base Supabase client directly for queries.
+
+### Hard Requirements
+
+- **MUST NOT** import or call `createClient()` from `@supabase/supabase-js` in consuming app code **except** for creating the base client passed to `UnifiedAuthProvider`.
+- **MUST NOT** export, pass, or store an insecure Supabase client instance for general use.
+- **MUST** perform all `.from(...)`, `.rpc(...)`, `.auth.*`, and storage operations via the secure client returned by `useSecureSupabase()` (or the approved pace-core equivalent).
+- **MUST** create the base Supabase client ONCE and pass it to `UnifiedAuthProvider` as `supabaseClient` prop.
+- **MUST** call `useSecureSupabase()` without parameters - it automatically uses the base client from `useUnifiedAuth()` provider layer.
+- **MUST NOT** pass a base client directly to `useSecureSupabase()` - the hook gets it from the provider automatically.
 
-**CRITICAL SECURITY REQUIREMENT:** Using `createClient()` from `@supabase/supabase-js` directly bypasses organisation context enforcement and RLS policies, which can lead to:
+### Why this is critical
+
+Using `createClient()` directly for queries can bypass organisation context enforcement and RLS policies, leading to:
 - Cross-organisation data access
-- Security vulnerabilities  
+- Security vulnerabilities
 - Data leakage between organisations
 
+### Correct Pattern
+
 ```tsx
-// ❌ WRONG: Direct Supabase client creation
+// ✅ CORRECT: Create base client ONCE for UnifiedAuthProvider
+// main.tsx or App.tsx
 import { createClient } from '@supabase/supabase-js';
-const supabase = createClient(url, key);
-// This bypasses organisation context and RLS policies!
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+);
+
+function App() {
+  return (
+    <UnifiedAuthProvider 
+      supabaseClient={supabase}  // Pass base client to provider
+      appName="YourApp"
+      // ... other props
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
 
-// ✅ CORRECT: Use secure Supabase client
+// ✅ CORRECT: Use secure client in components (no parameters needed)
+// YourComponent.tsx
 import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
-const secureSupabase = useSecureSupabase();
-// Organisation context is automatically enforced
-```
 
-### Detection and Enforcement
-
-pace-core provides multiple layers of protection:
+function YourComponent() {
+  const secureSupabase = useSecureSupabase(); // Gets client from provider automatically
+  
+  if (!secureSupabase) {
+    return <div>Loading...</div>;
+  }
+  
+  // Use secureSupabase for all queries
+  const { data } = await secureSupabase.from('users').select('*');
+}
+```
 
-1. **ESLint Rule**: The `no-direct-supabase-client` rule detects `createClient` calls and reports errors
-2. **Runtime Warnings**: Development mode warnings when insecure clients are detected
-3. **Type Safety**: Use `isSecureClient()` to verify clients are secure
+### Incorrect Patterns
 
 ```tsx
-// Verify client is secure (optional, but recommended)
-import { isSecureClient, warnIfInsecureClient } from '@jmruthers/pace-core/rbac/utils/clientSecurity';
+// ❌ FORBIDDEN: Creating client in component or service
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(url, key); // Don't do this for queries
 
-const supabase = useSecureSupabase();
-warnIfInsecureClient(supabase, 'MyComponent'); // Warns in dev if insecure
+// ❌ FORBIDDEN: Passing base client to useSecureSupabase
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+import { supabase } from './supabase'; // Don't export base client
+const secureSupabase = useSecureSupabase(supabase); // Don't pass it
 
-if (isSecureClient(supabase)) {
-  // Client is secure, safe to use
-}
+// ❌ FORBIDDEN: Using base client directly for queries
+const { data } = await supabase.from('users').select('*'); // Bypasses RLS
 ```
 
+### Acceptable Exceptions
+
+**The ONLY acceptable use of `createClient()` in consuming app code is:**
+
+1. **Creating the base client for `UnifiedAuthProvider`** - This MUST be in one of these files:
+   - `src/main.tsx` (or `main.jsx`)
+   - `src/App.tsx` (or `App.jsx`)
+   - `src/lib/supabase.ts` (or `supabase.js`) - ONLY if this file is ONLY used to create the base client for the provider
+
+**The file containing the base client creation MUST:**
+- Be clearly named (e.g., `supabase.ts`, `main.tsx`)
+- Only create the client once
+- Pass it directly to `UnifiedAuthProvider` (not export it for general use)
+- Include a comment explaining it's the base client for the provider
+
+**NO OTHER EXCEPTIONS ARE PERMITTED** - All other uses of `createClient()` are security violations and MUST be fixed.
+
+### Detection / Audit
+
+- `rg "createClient\(" src` must return **exactly ONE match** in the file that creates the base client for `UnifiedAuthProvider`.
+- That file MUST be one of: `main.tsx`, `App.tsx`, or `lib/supabase.ts` (or `.jsx`/`.js` equivalents).
+- No `.from(` / `.rpc(` calls may be performed on an insecure client reference.
+- All `useSecureSupabase()` calls should be without parameters.
+
 ## MUST: Setup RBAC Before Use
 
 **You MUST call `setupRBAC()` before any RBAC usage.** This is non-negotiable.
@@ -240,13 +305,29 @@ import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core'
 
 ## MUST: Import Core Styles
 
-**You MUST import pace-core styles:**
+**You MUST import pace-core styles via app.css:**
+
+The correct pattern is a two-file CSS architecture:
+1. `src/app.css` - Contains `@import "@jmruthers/pace-core/styles/core.css";` (CSS @import)
+2. `src/main.tsx` - Imports `./app.css` (JavaScript import)
 
 ```tsx
 // main.tsx or App.tsx
-import '@jmruthers/pace-core/styles/core.css';
+import './app.css';  // ✅ CORRECT - app.css imports core.css
 ```
 
+```css
+/* src/app.css */
+@import "tailwindcss";
+@import "@jmruthers/pace-core/styles/core.css";  // CSS @import, not JavaScript import
+```
+
+**MUST NOT:**
+- Import `core.css` directly in `main.tsx` or `App.tsx` - This causes duplicate imports
+- Use JavaScript import for `core.css` - Use CSS `@import` in `app.css` instead
+
+**See [08-markup-quality.md](../../packages/core/docs/standards/08-markup-quality.md) for complete CSS setup instructions.**
+
 ## MUST NOT: Use Inline Styles
 
 **You MUST NOT use inline styles (`style={{...}}`).** All styling MUST come from pace-core components and Tailwind classes.
@@ -320,6 +401,27 @@ Before adding any styling:
 7. **Missing styles** - Always import core.css
 8. **Direct library imports** - Use pace-core wrappers instead
 
+## Compliance Exceptions
+
+**In general, pace-core compliance rules do NOT allow exceptions.** The rules are designed to ensure security, consistency, and maintainability across the PACE suite.
+
+### When Exceptions Are NOT Allowed
+
+- **Security rules** (e.g., `createClient()` usage) - NO exceptions except the one documented above
+- **RBAC rules** - NO exceptions
+- **Component usage** - NO exceptions (use pace-core components)
+- **Hook usage** - NO exceptions (use pace-core hooks)
+
+### Documenting Legitimate Edge Cases
+
+If you encounter a situation where a rule seems to conflict with a legitimate requirement:
+
+1. **First**: Verify that pace-core doesn't provide a solution
+2. **Second**: Check if the requirement should be added to pace-core
+3. **Third**: If truly unavoidable, document the case clearly with a comment explaining why
+
+**Note**: Even with documentation, exceptions should be temporary, rare, reviewed, and tracked for eventual removal.
+
 ## Reference
 
 - **pace-core Exports**: See `pace-core-exports.mdc` for complete export reference

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

@@ -9,6 +9,25 @@ rulesVersion: "2025-01-28"
 
 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
@@ -171,6 +190,21 @@ type ApiError = { code: string; message: string; details?: object };
 - ≥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.**
@@ -234,11 +268,18 @@ Before committing code, verify:
 
 ## Reference
 
-See `packages/core/docs/standards/` for complete standards documentation:
-- 01-architecture-standard.md
-- 02-api-and-rpc-standard.md
-- 03-component-standard.md
-- 04-code-style-standard.md
-- 05-security-standard.md
-- 06-testing-and-docs-standard.md
-- 07-rbac-and-rls-standard.md
+**📚 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/02-project-structure.mdc

@@ -7,6 +7,8 @@ rulesVersion: "2025-01-28"
 ---
 # Project Structure Standard
 
+**📚 Human-Readable Standard**: See [02-project-structure.md](../../packages/core/docs/standards/02-project-structure.md) for complete documentation including migration guides and detailed examples.
+
 This guide defines the standard folder structure and file organization for consuming apps in the PACE suite.
 
 ## MUST: Follow Standard Directory Structure
@@ -98,6 +100,10 @@ src/
 - Format: `YYYYMMDDHHMMSS_description.sql`
 - Example: `20250115143022_add_user_preferences.sql`
 
+- If this app **intentionally has no app-owned migrations** (e.g., relies on shared DB managed elsewhere), you MUST add `supabase/README.md` explaining:
+  - where migrations/RLS policies are managed
+  - whether the app is expected to add migrations in the future
+
 ## SHOULD: Organize by Domain
 
 **For larger apps, SHOULD organize by domain/feature:**

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

@@ -7,6 +7,8 @@ rulesVersion: "2025-01-28"
 ---
 # SOLID Principles Guide
 
+**📚 Human-Readable Standard**: See [03-solid-principles.md](../../packages/core/docs/standards/03-solid-principles.md) for complete documentation.
+
 This guide enforces SOLID architecture principles to ensure maintainable, extensible, and testable code.
 
 ## Single Responsibility Principle (SRP)

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

@@ -7,6 +7,8 @@ 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

package/cursor-rules/05-bug-reports-and-features.mdc

@@ -7,6 +7,8 @@ rulesVersion: "2025-01-28"
 ---
 # Bug Reports and Feature Requests Guide
 
+**📚 Human-Readable Standard**: See [05-bug-reports-and-features.md](../../packages/core/docs/standards/05-bug-reports-and-features.md) for complete documentation.
+
 This guide provides standardized templates for reporting bugs and requesting features in pace-core. This is a reference guide - Cursor will use this for context when helping with issue reporting.
 
 ## Identifying Issues

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

@@ -7,6 +7,8 @@ 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

package/cursor-rules/07-tech-stack-compliance.mdc

@@ -7,6 +7,8 @@ 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

package/cursor-rules/08-markup-quality.mdc

@@ -7,6 +7,27 @@ rulesVersion: "2025-01-28"
 ---
 # Markup Quality Guide
 
+**📚 Human-Readable Standard**: See [08-markup-quality.md](../../packages/core/docs/standards/08-markup-quality.md) for complete documentation including **CRITICAL CSS configuration requirements**.
+
+**⚠️ IMPORTANT**: This rule is ALWAYS APPLIED. The standard includes required CSS setup that MUST be followed for pace-core components to render correctly.
+
+## ⚠️ CRITICAL: CSS Configuration Required
+
+**Before using pace-core components, you MUST configure CSS correctly.** Without proper configuration, pace-core components will appear unstyled or with incorrect styling.
+
+**MUST read the standard for complete CSS setup instructions**: [08-markup-quality.md](../../packages/core/docs/standards/08-markup-quality.md)
+
+**Quick checklist:**
+- [ ] `src/app.css` exists with `@import "tailwindcss";`
+- [ ] `@source` directives configured correctly (relative to CSS file location)
+- [ ] `@import "@jmruthers/pace-core/styles/core.css";` in `app.css`
+- [ ] All three color palettes defined (main, sec, acc) with all shades (50-950)
+- [ ] `app.css` imported in `main.tsx` (NOT `core.css` directly)
+
+**See the standard for detailed setup instructions and troubleshooting.**
+
+---
+
 This guide enforces clean markup standards, semantic HTML usage, and proper pace-core component patterns to ensure maintainable, accessible, and consistent code.
 
 ## pace-core First
@@ -88,41 +109,45 @@ import { Button, Input } from '@jmruthers/pace-core';
 <footer>Footer</footer>
 ```
 
-### MUST NOT: Use `<div>` Elements
+### MUST: Prefer Semantic HTML (Limit `<div>`)
+
+**You MUST prefer semantic HTML elements** (`<main>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, lists, etc.).
+Using semantic elements improves accessibility, maintainability, and consistency.
+
+#### `<div>` usage policy
+
+- **MUST NOT** use `<div>` when a clear semantic element exists.
+- `<div>` is **allowed only** for:
+  - purely presentational layout wrappers (flex/grid grouping) when no semantic element fits, OR
+  - React portal roots / app shell roots, OR
+  - third-party libraries that require specific DOM structure (document the reason in a short comment).
+
+#### Severity guidance (for audits)
 
-**MUST NOT use `<div>` elements (except for the first child of `<body>` in `index.html`, React portals, or when required by third-party libraries that mandate specific DOM structure):**
+- **HIGH/BLOCKER**: `<div>` used in place of landmark/semantic structure (e.g., main page wrapper that should be `<main>`, navigation that should be `<nav>`, lists that should be `<ul>/<ol>`).
+- **MEDIUM**: `<div>` used as a generic wrapper inside semantic structure where it could be a fragment or semantic element.
+- **LOW**: `<div>` used for unavoidable third-party structure with a comment justifying it.
+
+**Examples:**
 
 ```tsx
-// ❌ WRONG: Using div elements
-<div className="container">
-  <div className="content">Content</div>
+// ❌ WRONG: Non-semantic page structure
+<div className="page">
+  <div className="nav">...</div>
+  <div className="content">...</div>
 </div>
 
-// ✅ CORRECT: Use semantic elements or React Fragments
+// ✅ CORRECT: Semantic structure
 <main>
-  <section>Content</section>
+  <nav>...</nav>
+  <section>...</section>
 </main>
-// Or for grouping without semantic meaning:
-<>
-  <Component1 />
-  <Component2 />
-</>
-```
 
-### MUST: Choose Most Semantic Element
-
-**MUST choose the most semantically accurate element for the content:**
-
-```tsx
-// ✅ CORRECT: Choose appropriate semantic elements
-<main>Main content</main>
-<section>Section of content</section>
-<article>Article content</article>
-<header>Header content</header>
-<footer>Footer content</footer>
-<nav>Navigation</nav>
-<ul><li>List items</li></ul>
-<p>Paragraph text</p>
+// ✅ ACCEPTABLE: Layout-only wrapper (no semantic fit)
+// (Prefer fragments where possible)
+<section>
+  <div className="flex gap-2">...</div>
+</section>
 ```
 
 ## Typography & Styling