@jmruthers/pace-core 0.6.9 → 0.6.11

package/docs/api-reference/components.md

@@ -889,7 +889,7 @@ import {
 
 ## Alert
 
-A flexible and accessible alert component for displaying important messages. Uses semantic HTML (`<aside>`) for better accessibility and semantic meaning.
+A flexible and accessible alert component for displaying important messages. Uses semantic HTML (`<div>`) with ARIA roles for better accessibility and semantic meaning.
 
 ### Props
 
@@ -913,7 +913,7 @@ interface AlertDescriptionProps extends React.HTMLAttributes<HTMLParagraphElemen
 ```tsx
 import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
 
-// Basic alert (renders as <aside> element)
+// Basic alert (renders as <div> element)
 <Alert>
   <AlertTitle>Success</AlertTitle>
   <AlertDescription>Your changes have been saved.</AlertDescription>
@@ -934,14 +934,14 @@ import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
 
 ### Variants
 
-- **default**: Standard alert with background and border (renders as `<aside>`)
-- **destructive**: Red alert for errors and warnings (renders as `<aside>`)
+- **default**: Standard alert with background and border (renders as `<div>`)
+- **destructive**: Red alert for errors and warnings (renders as `<div>`)
 - **inline**: Lightweight text formatting without background (renders as fragment)
 
 ### Semantic HTML
 
 The Alert component uses semantic HTML for better accessibility:
-- **Default and destructive variants**: Render as `<aside>` elements with `role="alert"`
+- **Default and destructive variants**: Render as `<div>` elements with `role="alert"`
 - **Inline variant**: Renders as a React Fragment (no wrapper element)
 - **AlertTitle**: Renders as `<h5>` (default/destructive) or `<strong>` (inline)
 - **AlertDescription**: Renders as `<p>` (default/destructive) or `<span>` (inline)

package/docs/api-reference/rpc-functions.md

@@ -146,7 +146,7 @@ Documented in [RBAC API Reference](../rbac/api-reference.md):
 **Data Access (RBAC-protected):**
 - `data_user_organisations_get` - Get all organisations for a user
 - `data_user_organisation_roles_get` - Get user roles in organisations
-- `get_organisation_members` - (exception to naming standard) Returns distinct active organisation role assignments for dashboard statistics. Enforces `check_user_organisation_access` so only super admins or organisation members can call it.
+- `data_rbac_roles_list` - List all roles (global, organisation, event-app) for a user. **Explicit parameters are the source of truth:** the function uses only `p_user_id`, `p_organisation_id`, `p_event_id`, `p_app_id`; it does **not** use `x-organisation-id` or request/session org. RLS on `rbac_organisation_roles` and `rbac_event_app_roles` uses caller identity (JWT) via `app.current_user_id` set by the RPC. **Note:** This RPC returns roles for **one** user (the caller when `p_user_id` is null, or the given `p_user_id`). It does **not** return `user_id` and does **not** support "list all users in org X". For that, see "User list for one organisation" below.
 - `data_user_events_get` - Get events accessible to a user
 - `data_cake_meals_get` - Get cake meals for an event (application-specific, RBAC-protected)
 
@@ -168,6 +168,16 @@ Documented in [RBAC API Reference](../rbac/api-reference.md):
 
 **Note**: For public event access, use `usePublicEvent()` hook from pace-core, which handles direct table queries internally.
 
+### User list for one organisation
+
+Apps that need to show **all users (or user IDs) in a given organisation** have two options:
+
+1. **Direct query (recommended):** Query the `rbac_organisation_roles` table with a filter on `organisation_id`. Use the secure client from `useSecureSupabase()`. When the "current org" is derived from the URL (e.g. `/users?org=scouts-victoria`), ensure the secure client has that organisation context for the request (e.g. keep `selectedOrganisation` in sync with the URL, or use a client created with that org via `withContext({ organisationId: urlOrgId })`). The caller must have access to that org (or be a super admin). Select distinct `user_id` (and optionally `role`, etc.) as needed.
+
+2. **Alternative:** If pace-core adds a dedicated RPC that returns `(user_id, role, ...)` for a given `p_organisation_id`, use that and pass the org ID explicitly; such an RPC would use only explicit parameters and caller auth/RLS.
+
+**Not supported:** Calling `data_rbac_roles_list` with only `p_organisation_id` does **not** return "all users in the org". It returns the **caller's** roles in that org (when `p_user_id` is null), and the return type has no `user_id` column.
+
 ## Removed Legacy RPC Functions
 
 The following RPC functions have been **removed** in v0.6.x. All consuming apps have been migrated to modern alternatives.
@@ -233,8 +243,7 @@ These functions are used internally by pace-core and should **NOT** be called di
 - ~~`get_organisation_context`~~ - **REMOVED** - No longer needed
 - ~~`get_page_scope_type`~~ - **REMOVED** - Replaced with direct table queries
 
-**Active Functions** (pace-core internal, do not call directly):
-- `grant_event_app_role` - Used by `useRoleManagement` hook (use hook instead)
+**Event-app role grants:** Use `rbac_role_grant` with `p_role_type: 'event_app'` and `p_context_id: '<event_id>:<app_id>'`. The `useRoleManagement().grantEventAppRole` hook calls this RPC.
 
 **Note**: The removed functions have been replaced with direct table queries or are no longer needed. Organisation context is automatically handled by the secure Supabase client from `useSecureSupabase()` hook.
 

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

@@ -236,6 +236,14 @@ SELECT rbac_role_grant(
 
 For complete documentation on role management functions, see **[Role Management Functions](../rbac/role-management-functions.md)**.
 
+### Required migrations for role management
+
+Granting roles (including event-app roles) requires the **`rbac_role_grant`** RPC to exist in the database. The Supabase project must have the migration that creates or updates this function applied.
+
+- **Migration:** `20260109112708_fix_rbac_role_grant_reactivate_inactive_roles.sql` (or a later migration that defines `public.rbac_role_grant`).
+- **Symptom:** If `POST …/rest/v1/rpc/rbac_role_grant` returns **404**, the function is missing — apply pending Supabase migrations to the project.
+- Consuming apps (e.g. pace-admin) that use `useRoleManagement().grantEventAppRole` call this RPC; ensure the project’s migrations are applied before using role grant features.
+
 ## RBAC Compliance & Recent Changes
 
 ### Database-Driven Permissions

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

@@ -18,26 +18,21 @@ npm install @jmruthers/pace-core
 
 ### Step 2: Install Cursor Rules
 
-Run the installation script from your app root:
+Run the combined setup script from your app root:
 
 ```bash
-node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+npm run setup
 ```
 
-Or add to your `package.json`:
+This will install:
+- Cursor rules for AI-assisted enforcement
+- ESLint configuration for real-time linting
+- Standards documentation to `docs/standards/`
 
-```json
-{
-  "scripts": {
-    "setup:cursor-rules": "node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs"
-  }
-}
-```
-
-Then run:
+Or to force update existing configs:
 
 ```bash
-npm run setup:cursor-rules
+npm run setup -- --force
 ```
 
 The script will:
@@ -131,18 +126,20 @@ Content with examples and guidelines.
 
 ### Compliance Check
 
-For a quick compliance check:
+For full validation including the pace-core audit:
 
 ```bash
-node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+npm run validate
 ```
 
+Review `audit/<timestamp>-pace-core-audit.md` for pace-core compliance and other standards.
+
 ## Updating Rules
 
-When pace-core is updated, run the installation script again:
+When pace-core is updated, run the setup script again:
 
 ```bash
-npm run setup:cursor-rules
+npm run setup
 ```
 
 The script will:
@@ -155,7 +152,7 @@ The script will:
 To force update all rules (even when versions match):
 
 ```bash
-node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs --force
+npm run setup -- --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).
@@ -210,7 +207,7 @@ Each app maintains its own `.cursor/rules/` directory.
 1. **Initial Setup:**
    ```bash
    npm install @jmruthers/pace-core
-   npm run setup:cursor-rules
+   npm run setup
    ```
 
 2. **Daily Development:**
@@ -225,7 +222,7 @@ Each app maintains its own `.cursor/rules/` directory.
 4. **After pace-core Updates:**
    ```bash
    npm update @jmruthers/pace-core
-   npm run setup:cursor-rules
+   npm run setup
    ```
 
 ## Related Documentation

package/docs/getting-started/dependencies.md

@@ -48,7 +48,7 @@ reviewedBy: dependency-clarity-audit
 - Validation runs automatically before publishing via `prepublishOnly` hook
 
 **For consuming apps:**
-- Use the audit tool (`npm run audit:pace-core`) to check your dependencies
+- Use the pace-core Audit step in `npm run validate` to check your dependencies
 - The audit tool reads the current `package.json` from the installed pace-core package
 - Version requirements shown by the audit tool come directly from `package.json`
 

package/docs/getting-started/setup.md

@@ -0,0 +1,235 @@
+# pace-core Setup Guide
+
+This guide explains how to set up pace-core in your consuming app with a single command.
+
+## Quick Start
+
+After installing `@jmruthers/pace-core`, run:
+
+```bash
+npm run setup
+```
+
+This single command will:
+- ✅ Set up ESLint configuration for real-time compliance checking
+- ✅ Install Cursor rules for AI-assisted enforcement
+- ✅ Copy standards documentation to `docs/standards/`
+
+## Installation
+
+### Step 1: Install pace-core
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### Step 2: Add Setup Scripts to package.json
+
+**Important:** Add the setup and validate scripts to your consuming app's `package.json`. Do NOT create local script files.
+
+```json
+{
+  "scripts": {
+    "setup": "node node_modules/@jmruthers/pace-core/scripts/setup.cjs",
+    "validate": "node node_modules/@jmruthers/pace-core/scripts/validate.cjs"
+  }
+}
+```
+
+**Note:** These scripts come from the `@jmruthers/pace-core` package, not from your local project. Make sure you're pointing to `node_modules/@jmruthers/pace-core/scripts/`.
+
+### Step 3: Run Setup
+
+```bash
+npm run setup
+```
+
+That's it! All pace-core tools are now configured.
+
+### Step 4: Run Validation (Optional)
+
+After setup, you can run quick validation checks:
+
+```bash
+npm run validate
+```
+
+This runs (in order, when the corresponding script exists):
+- **Type check** – summary in terminal
+- **Lint** – summary in terminal, full output in `audit/<timestamp>-eslint-report.md`
+- **Build** – summary in terminal
+- **Tests** – summary in terminal (runs `test:coverage` if present, otherwise `test`; add `test:coverage` to generate `coverage/index.html`)
+- **pace-core Audit** – standards audit; report in `audit/<timestamp>-pace-core-audit.md`
+
+Reports are written to the `audit/` directory. To get a coverage report during validate, add a `test:coverage` script to your `package.json` (e.g. with Vitest: `vitest run --coverage`).
+
+## What Gets Set Up
+
+### 1. ESLint Configuration
+
+The setup script automatically:
+- Finds your ESLint config file (supports `.js`, `.cjs`, `.mjs`, `.json`, `.yaml`, `.yml`)
+- Adds pace-core ESLint rules to your config
+- Creates a backup of your existing config
+- Handles both ES modules and CommonJS formats
+- Supports `tseslint.config()` wrapper
+
+### 2. Cursor Rules
+
+The setup script:
+- Creates `.cursor/rules/` directory if it doesn't exist
+- Copies all pace-core rules (00-09) to your project
+- **Automatically updates** pace-core rules when they change
+- Preserves your custom rules (50+)
+- Skips files that are already up to date
+
+### 3. Standards Documentation
+
+The setup script:
+- Copies `packages/core/docs/standards/` to `docs/standards/` in your app
+- Provides offline access to all pace-core standards
+- Updates when you run setup again
+
+## Force Update
+
+To force update all configurations (overwrites existing):
+
+```bash
+npm run setup -- --force
+```
+
+Use this when:
+- You want to update to the latest pace-core rules
+- Your ESLint config needs to be regenerated
+- You want to refresh the standards documentation
+
+## Manual Setup
+
+The setup script handles all three tasks (ESLint, Cursor rules, and standards docs) in one command. There are no separate scripts for individual components - use `npm run setup` for everything.
+
+## Verification
+
+After running setup, verify everything is working:
+
+### Run Validation
+
+The easiest way to verify everything is working:
+
+```bash
+npm run validate
+```
+
+This runs all available checks (type-check, lint, tests, pace-core audit).
+
+### Manual Verification
+
+You can also check individual components:
+
+**Check ESLint:**
+```bash
+npm run lint
+```
+
+**Check Cursor Rules:**
+1. Restart Cursor
+2. Open a file that matches the rule patterns
+3. Rules should be automatically loaded
+
+**Check Standards:**
+```bash
+ls docs/standards/
+```
+
+You should see all the standards markdown files.
+
+## Troubleshooting
+
+### Error: Cannot find module 'scripts/setup.cjs'
+
+**Problem:** Your `package.json` has a `setup` script pointing to a local file that doesn't exist:
+```json
+{
+  "scripts": {
+    "setup": "node scripts/setup.cjs"  // ❌ WRONG - This file doesn't exist in consuming apps
+  }
+}
+```
+
+**Solution:** Update your `package.json` to use the script from the pace-core package:
+```json
+{
+  "scripts": {
+    "setup": "node node_modules/@jmruthers/pace-core/scripts/setup.cjs"  // ✅ CORRECT
+  }
+}
+```
+
+**Important:** The setup script comes from `@jmruthers/pace-core`, not from your local project. You should NOT create a local `scripts/setup.cjs` file.
+
+### Setup Script Not Found
+
+If you get an error that the script can't be found:
+
+1. Verify pace-core is installed:
+   ```bash
+   npm list @jmruthers/pace-core
+   ```
+
+2. Check the script path:
+   ```bash
+   ls node_modules/@jmruthers/pace-core/scripts/setup.cjs
+   ```
+
+3. If the file doesn't exist, you may need to update pace-core:
+   ```bash
+   npm update @jmruthers/pace-core
+   ```
+
+4. Make sure your `package.json` script points to `node_modules/@jmruthers/pace-core/scripts/setup.cjs`, not a local `scripts/setup.cjs`
+
+### ESLint Config Issues
+
+If ESLint setup fails:
+
+1. Check your ESLint config file exists
+2. Try with `--force` flag:
+   ```bash
+   npm run setup -- --force
+   ```
+3. Check the backup file created (`.backup.{timestamp}`)
+4. See [ESLint Setup Troubleshooting](../standards/1-pace-core-compliance-standards.md#eslint-setup-issues)
+
+### Cursor Rules Not Loading
+
+1. Verify rules are in `.cursor/rules/` directory
+2. Check file extensions are `.mdc`
+3. Restart Cursor
+4. Check rule frontmatter is valid YAML
+
+### Standards Not Copied
+
+If standards aren't copied:
+
+1. Check pace-core package has docs:
+   ```bash
+   ls node_modules/@jmruthers/pace-core/docs/standards/
+   ```
+2. Try with `--force` flag:
+   ```bash
+   npm run setup -- --force
+   ```
+
+## Next Steps
+
+After setup:
+
+1. **Restart Cursor** to load the new rules
+2. **Run validation**: `npm run validate` (type-check, lint, build, tests, pace-core audit; reports in `audit/`)
+3. **Review standards** in `docs/standards/` for complete documentation
+
+## Related Documentation
+
+- [Cursor Rules Guide](./cursor-rules.md) - Using Cursor rules effectively
+- [Standards Documentation](../standards/README.md) - Complete standards reference
+- [pace-core Compliance](../standards/1-pace-core-compliance-standards.md) - Compliance requirements
+- [Local Development](./local-development.md) - Using pace-core locally

package/docs/implementation-guides/authentication.md

@@ -263,6 +263,22 @@ function App() {
 
 **Important:** The `ProtectedRoute` component solves the common chicken-and-egg problem where apps check for `selectedEvent` before rendering, which blocks the event selector (typically in the `PaceAppLayout` header) from being visible. The component allows rendering when events exist but none is selected, enabling users to see and use the event selector dropdown.
 
+### Critical: Auth routing pattern
+
+To avoid "login succeeds but redirect doesn't happen" or the login form resetting after submit, follow this pattern:
+
+- **MUST** use a single public `/login` route and wrap all other routes in **ProtectedRoute**. Do not wrap the whole app in a custom "auth gate" that redirects when `!isAuthenticated`.
+- **MUST NOT** wrap `<Routes>` in a component that, when `!isAuthenticated`, renders `<Navigate to="/login" />` for non-login paths. That races with post-login context updates and can send the user back to the login page with a reset form.
+- **SHOULD** avoid `BrowserRouter` `future: { v7_startTransition: true, v7_relativeSplatPath: true }` until compatibility with auth context updates is verified; use plain `<BrowserRouter>`.
+
+See [Redirect not happening after login](#1-login-not-working) in Troubleshooting if you see this behaviour.
+
+**Auth and routing checklist (new apps):**
+- [ ] `/login` is a public route; all other routes are under `<Route element={<ProtectedRoute />}>` (or `requireEvent={false}` variant).
+- [ ] No wrapper component that redirects to `/login` when `!isAuthenticated` for the whole app.
+- [ ] `BrowserRouter` used without `future` flags (or login and logout verified if using them).
+- [ ] Verify login and logout in the app after setup.
+
 ## Configuration Options
 
 ### UnifiedAuthProvider Props
@@ -801,6 +817,7 @@ function App() {
 - [ ] User credentials are valid in Supabase
 - [ ] Network connectivity working
 - [ ] Browser not blocking cookies
+- [ ] **Auth routing pattern**: You use a public `/login` route and wrap other routes in `ProtectedRoute`; you do not use a global auth gate that redirects to `/login` when `!isAuthenticated`. See [Critical: Auth routing pattern](#critical-auth-routing-pattern) above.
 
 #### 2. Session Not Persisting
 
@@ -858,6 +875,16 @@ function AuthTest() {
 }
 ```
 
+#### 4. Logout does nothing / 403 on logout
+
+**Symptoms:**
+- Logout button does nothing; user stays on the app
+- Network tab shows `POST .../auth/v1/logout` returning 403
+
+**Cause:** Supabase sign-out with default (global) scope can return 403 in some environments (e.g. cookie domain, CORS). pace-core handles this by clearing local auth state and calling `signOut({ scope: 'local' })`, so the UI should still show the user as logged out and redirect to login.
+
+**If logout still does nothing:** Check cookie domain and CORS for your Supabase project and app origin. The app should still clear local state; if it does not, ensure you are on a version of pace-core that includes the signOut error-handling fix.
+
 ### Detailed Solutions
 
 #### Wrong Supabase Configuration