@jmruthers/pace-core 0.5.193 → 0.6.2

package/docs/architecture/database-schema-requirements.md

@@ -123,6 +123,167 @@ The RBAC system uses a **single source of truth** approach:
 - All functions use `rbac_organisation_roles` table for role management
 - Views inherit RLS policies from the underlying `rbac_organisation_roles` table
 
+## App Access Tables Architecture
+
+The system uses three complementary tables to manage app availability and user permissions:
+
+### Table Relationship Overview
+
+| Table | Purpose | Question It Answers |
+|-------|---------|-------------------|
+| `core_organisation_app_access` | Organisation-level app configuration | "Is this app available for this organisation?" |
+| `core_event_app_access` | Event-level app availability | "Is this app available for this event?" |
+| `rbac_event_app_roles` | User-specific role grants | "Who can do what for this event-app?" |
+
+### 1. `core_organisation_app_access`
+
+**Purpose:** Organisation-level app configuration and feature flags.
+
+**Schema:**
+```sql
+CREATE TABLE core_organisation_app_access (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id) ON DELETE CASCADE,
+    app_id UUID NOT NULL REFERENCES rbac_apps(id),
+    is_enabled BOOLEAN DEFAULT true,
+    settings JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    created_by UUID REFERENCES auth.users(id),
+    updated_by UUID REFERENCES auth.users(id)
+);
+```
+
+**Use Cases:**
+- Enable/disable apps at the organisation level
+- Store organisation-specific app settings (e.g., feature flags, configuration)
+- Control which apps are available to an organisation
+
+**Key Characteristics:**
+- Organisation-scoped (one record per organisation-app combination)
+- Contains `is_enabled` flag for feature toggling
+- Contains `settings` JSONB field for app-specific configuration
+
+### 2. `core_event_app_access`
+
+**Purpose:** Event-level app availability flag.
+
+**Schema:**
+```sql
+CREATE TABLE core_event_app_access (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    event_id VARCHAR NOT NULL REFERENCES core_events(event_id),
+    app_id UUID NOT NULL REFERENCES rbac_apps(id) ON DELETE CASCADE,
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id),
+    created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+    updated_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+    created_by UUID REFERENCES auth.users(id),
+    updated_by UUID REFERENCES auth.users(id),
+    CONSTRAINT core_event_app_access_unique UNIQUE (event_id, app_id, organisation_id)
+);
+```
+
+**Use Cases:**
+- Enable an app for a specific event
+- Track which apps are available for each event
+- Quick check: "Is this app enabled for this event?"
+
+**Key Characteristics:**
+- Event-scoped (one record per event-app-organisation combination)
+- Unique constraint prevents duplicate entries
+- Simple boolean flag (existence = enabled)
+
+### 3. `rbac_event_app_roles`
+
+**Purpose:** User-specific role grants for event-app combinations.
+
+**Schema:**
+```sql
+CREATE TABLE rbac_event_app_roles (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    event_id VARCHAR NOT NULL REFERENCES core_events(event_id) ON DELETE CASCADE,
+    app_id UUID NOT NULL REFERENCES rbac_apps(id),
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id),
+    role rbac_event_app_role NOT NULL, -- ENUM: 'viewer', 'participant', 'planner', 'event_admin'
+    status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'inactive', 'suspended')),
+    granted_at TIMESTAMPTZ DEFAULT NOW(),
+    granted_by UUID REFERENCES auth.users(id),
+    valid_from TIMESTAMPTZ DEFAULT NOW(),
+    valid_to TIMESTAMPTZ,
+    CONSTRAINT rbac_event_app_roles_unique UNIQUE (user_id, event_id, app_id, role)
+);
+```
+
+**Use Cases:**
+- Grant specific roles to users for event-app combinations
+- Control what users can do (viewer, participant, planner, event_admin)
+- Time-based role validity (valid_from, valid_to)
+- Role status management (active, inactive, suspended)
+
+**Key Characteristics:**
+- User-scoped (one record per user-event-app-role combination)
+- Includes role hierarchy and permissions
+- Time-based validity support
+- Status tracking for role lifecycle
+
+### Relationship Summary
+
+**Access Tables = "Is this app available?"**
+- `core_organisation_app_access`: Organisation-level availability and settings
+- `core_event_app_access`: Event-level availability flag
+
+**Roles Table = "Who can do what?"**
+- `rbac_event_app_roles`: User-specific role grants with permissions
+
+### Important Notes
+
+1. **Separation of Concerns:**
+   - Access tables handle **configuration** (feature flags, availability)
+   - Roles table handles **authorization** (user permissions)
+
+2. **Independence:**
+   - Access records can exist without roles (app enabled, no users yet)
+   - Roles can exist without access records (legacy data or data inconsistency)
+   - These are intentionally independent to allow flexible configuration
+
+3. **Performance:**
+   - Access tables provide fast feature flag checks without querying user roles
+   - Roles table provides detailed permission information when needed
+
+4. **Data Integrity:**
+   - `core_event_app_access` has unique constraint on `(event_id, app_id, organisation_id)`
+   - `rbac_event_app_roles` has unique constraint on `(user_id, event_id, app_id, role)`
+
+### Example Usage Patterns
+
+```sql
+-- Check if app is available for an event (configuration check)
+SELECT EXISTS (
+    SELECT 1 FROM core_event_app_access
+    WHERE event_id = 'event-123'
+    AND app_id = 'app-456'
+    AND organisation_id = 'org-789'
+);
+
+-- Check if user has access to an event-app (authorization check)
+SELECT EXISTS (
+    SELECT 1 FROM rbac_event_app_roles
+    WHERE user_id = 'user-abc'
+    AND event_id = 'event-123'
+    AND app_id = 'app-456'
+    AND status = 'active'
+    AND valid_from <= NOW()
+    AND (valid_to IS NULL OR valid_to > NOW())
+);
+
+-- Get organisation-level app settings
+SELECT settings FROM core_organisation_app_access
+WHERE organisation_id = 'org-789'
+AND app_id = 'app-456'
+AND is_enabled = true;
+```
+
 ## Required RPC Functions
 
 The following RPC functions are required and should be updated to use the correct tables/views:

package/docs/core-concepts/rbac-system.md

@@ -10,7 +10,7 @@ reviewedBy: documentation-standards-audit
 
 PACE Core provides a comprehensive Role-Based Access Control (RBAC) system that manages user permissions through roles, ensuring secure and scalable access control across your application.
 
-> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/rbac-migration.md) for step-by-step instructions.
+> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/V0.4.0_rbac-migration.md) for step-by-step instructions.
 
 > **⚠️ IMPORTANT**: You **must** call `setupRBAC()` before using any RBAC features. See the [Quick Start Guide](../rbac/quick-start.md) for setup instructions.
 
@@ -278,7 +278,7 @@ If you're upgrading from a system with hardcoded permissions:
 3. **Replace 'manage' Operations** - Use specific CRUD operations instead
 4. **Enable Cache Invalidation** - Ensure realtime subscriptions are active
 
-For detailed migration instructions, see the **[RBAC Migration Guide](../migration/rbac-migration.md)**.
+For detailed migration instructions, see the **[RBAC Migration Guide](../migration/V0.4.0_rbac-migration.md)**.
 
 ## What's Next?
 
@@ -286,7 +286,7 @@ For detailed migration instructions, see the **[RBAC Migration Guide](../migrati
 - **[RBAC Quick Start](../rbac/quick-start.md)** - Build your first RBAC-enabled app
 - **[RBAC API Reference](../rbac/api-reference.md)** - Complete API documentation
 - **[RBAC Examples](../rbac/examples.md)** - Practical usage examples
-- **[Migration Guide](../migration/rbac-migration.md)** - Migrate from legacy RBAC
+- **[Migration Guide](../migration/V0.4.0_rbac-migration.md)** - Migrate from legacy RBAC
 - **[Installation](../getting-started/installation-guide.md)** - Get PACE Core set up
 - **[Authentication](./authentication.md)** - Understand authentication system
 - **[Organisations](./organisations.md)** - Learn about multi-tenancy

package/docs/documentation-index.md

@@ -96,10 +96,8 @@ This index mirrors the folder layout in `packages/core/docs/` so teams can quick
 
 - [Migration overview](./migration/README.md)
 - [Unified migration guide](./migration/MIGRATION_GUIDE.md)
-- [Quick migration guide](./migration/quick-migration-guide.md)
-- [Organisation context timing fix](./migration/organisation-context-timing-fix.md)
-- [Service architecture changes](./migration/service-architecture.md)
-- [RBAC migration](./migration/rbac-migration.md)
+- [Organisation context timing fix](./migration/V0.3.44_organisation-context-timing-fix.md)
+- [RBAC migration](./migration/V0.4.0_rbac-migration.md)
 - [Tailwind scanning updates](./migration/v0.4.15-tailwind-scanning.md)
 - [CSS-first migration (v0.4.16)](./migration/v0.4.16-css-first-approach.md)
 - [Source path fix (v0.4.17)](./migration/v0.4.17-source-path-fix.md)

package/docs/getting-started/cursor-rules.md

@@ -0,0 +1,263 @@
+# Cursor Rules Quick Start Guide
+
+This guide helps you get started with pace-core cursor rules in your consuming app.
+
+## What are Cursor Rules?
+
+Cursor rules are `.mdc` (Markdown Cursor) files that guide AI assistants (like Cursor) to follow specific patterns and standards when writing code. pace-core provides a comprehensive set of rules that ensure your app maintains quality, consistency, and compliance with pace-core standards.
+
+## Installation
+
+### Step 1: Install pace-core
+
+Make sure pace-core is installed in your project:
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### Step 2: Install Cursor Rules
+
+Run the installation script from your app root:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "setup:cursor-rules": "node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run setup:cursor-rules
+```
+
+The script will:
+- Create `.cursor/rules/` directory if it doesn't exist
+- Copy all pace-core rules (00-08) to your project
+- **Automatically update** pace-core rules (00-09) if they've changed
+- Preserve any existing custom rules (50+)
+- Skip files that are already up to date
+
+## Quick Start Snippet
+
+When working with Cursor, you can explicitly reference rules:
+
+> "Use pace-core components and follow rules 00–04."
+
+This helps Cursor focus on specific rule sets and ensures consistency.
+
+## Rule Files Overview
+
+The installed rules are numbered for ordering:
+
+- **00-pace-core-compliance.mdc** - Enforce pace-core usage patterns
+- **01-standards-compliance.mdc** - Enforce all pace-core standards
+- **02-project-structure.mdc** - Define standard folder structure
+- **03-solid-principles.mdc** - Enforce SOLID architecture principles
+- **04-testing-standards.mdc** - Enforce testing framework consistency
+- **05-bug-reports-and-features.mdc** - Templates for bug reports (guidance-only)
+- **06-code-quality.mdc** - Enforce code quality standards
+- **07-tech-stack-compliance.mdc** - Enforce tech stack versions and patterns
+- **08-markup-quality.mdc** - Enforce clean markup standards, semantic HTML usage, and pace-core component patterns
+
+## Using Rules with Cursor
+
+### Automatic Loading
+
+Cursor automatically loads all `.mdc` files from `.cursor/rules/` when:
+- You open a file that matches the rule's `globs` pattern
+- You ask Cursor to write or modify code
+- Cursor needs context for code generation
+
+### Explicit References
+
+You can explicitly reference rules in your prompts:
+
+```
+"Create a new component following rules 00, 01, and 03"
+"Refactor this code to follow SOLID principles (rule 03)"
+"Write tests following rule 04"
+```
+
+### Rule Semantics
+
+Rules use clear semantics:
+- **MUST** - Hard requirement, non-negotiable
+- **SHOULD** - Strong recommendation, best practice
+- **MAY** - Optional, acceptable alternative
+
+## Custom Rules
+
+### Creating Your Own Rules
+
+Create your own rules in `.cursor/rules/` with numbers starting at `50`:
+
+```
+.cursor/rules/
+├── 00-pace-core-compliance.mdc      # pace-core rule
+├── 01-standards-compliance.mdc     # pace-core rule
+├── ...
+├── 50-my-custom-rule.mdc           # Your custom rule
+└── 51-another-custom-rule.mdc      # Your custom rule
+```
+
+### Rule Format
+
+Your custom rules should follow the same format:
+
+```markdown
+---
+description: Brief description of your rule
+globs: ["targeted/path/**/*.{ts,tsx}"]
+alwaysApply: true
+---
+
+# Your Rule Title
+
+Content with examples and guidelines.
+```
+
+## Running Audits
+
+### Comprehensive Audit
+
+Run the comprehensive audit tool to check compliance:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "audit:pace-core": "node node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs"
+  }
+}
+```
+
+This generates a timestamped markdown report in `audit/` directory.
+
+### Compliance Check
+
+For a quick compliance check:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+```
+
+## Updating Rules
+
+When pace-core is updated, run the installation script again:
+
+```bash
+npm run setup:cursor-rules
+```
+
+The script will:
+- **Automatically update** pace-core rules (00-09) if they've changed (version or content differs)
+- Preserve your custom rules (50+)
+- Skip files that are already up to date
+
+### Force Update
+
+To force update all rules (even when versions match):
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs --force
+```
+
+**Note**: Normally, pace-core rules are automatically updated when they change. The `--force` flag forces an update even when versions match (useful if content changed but version metadata wasn't updated).
+
+## Monorepo Setup
+
+For monorepos, run the installation script from each app's root directory:
+
+```
+monorepo/
+├── apps/
+│   ├── app1/
+│   │   └── .cursor/rules/  # Run script here
+│   └── app2/
+│       └── .cursor/rules/  # Run script here
+```
+
+Each app maintains its own `.cursor/rules/` directory.
+
+## Troubleshooting
+
+### Rules Not Loading
+
+1. Verify rules are in `.cursor/rules/` directory
+2. Check file extensions are `.mdc`
+3. Restart Cursor if rules were just installed
+4. Check rule frontmatter is valid YAML
+
+### Rules Conflicting
+
+1. Check rule numbering (pace-core: 00-09, yours: 50+)
+2. Verify `globs` patterns don't overlap unnecessarily
+3. Review rule priorities in frontmatter
+
+### Installation Fails
+
+1. Check you're in the app root directory
+2. Verify `node_modules/@jmruthers/pace-core/` exists
+3. Check file permissions
+4. Try with `--force` flag if needed
+
+## Best Practices
+
+1. **Run audits regularly** - Check compliance before major commits
+2. **Update rules** - Keep pace-core rules up to date
+3. **Reference rules explicitly** - Tell Cursor which rules to follow
+4. **Create custom rules** - Add app-specific rules starting at 50
+5. **Review audit reports** - Address issues systematically
+
+## Example Workflow
+
+1. **Initial Setup:**
+   ```bash
+   npm install @jmruthers/pace-core
+   npm run setup:cursor-rules
+   ```
+
+2. **Daily Development:**
+   - Cursor automatically uses rules when writing code
+   - Explicitly reference rules when needed: "Follow rules 00-04"
+
+3. **Before Committing:**
+   ```bash
+   npm run audit:pace-core
+   ```
+   Review the generated report in `audit/` directory
+
+4. **After pace-core Updates:**
+   ```bash
+   npm update @jmruthers/pace-core
+   npm run setup:cursor-rules
+   ```
+
+## Related Documentation
+
+- [Cursor Rules README](../../cursor-rules/README.md)
+- [pace-core Standards](../standards/README.md)
+- [pace-core Exports](../api-reference/README.md)
+
+## Support
+
+For issues with cursor rules:
+1. Check this guide
+2. Review rule files for guidance
+3. File an issue in pace-core repository
+4. Check pace-core documentation

package/docs/getting-started/installation-guide.md

@@ -71,7 +71,12 @@ import path from 'path'
 
 export default defineConfig({
   plugins: [
-    react(),
+    react({
+      // React Compiler for automatic optimizations (React 19+)
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
     tailwindcss({
       // CRITICAL: Include pace-core source files for Tailwind scanning
       content: [

package/docs/getting-started/quick-start.md

@@ -57,7 +57,12 @@ import path from 'path';
 
 export default defineConfig({
   plugins: [
-    react(),
+    react({
+      // React Compiler for automatic optimizations (React 19+)
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
     tailwindcss({
       content: [
         './src/**/*.{js,ts,jsx,tsx}',