@jmruthers/pace-core 0.6.9 → 0.6.11

package/CHANGELOG.md

@@ -11,6 +11,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **DataTable: Automatic label display for select fields** - Select fields with `fieldType: 'select'` and `fieldOptions` now automatically display labels (e.g., "Mobile") instead of raw values (e.g., `1`) in read mode. This eliminates the need for custom cell renderers for common select field patterns. The feature supports simple options, grouped options, type coercion, and gracefully falls back to raw values when labels aren't found. Custom cell renderers are preserved if already defined.
 
 ### Breaking Changes
+- **Async API-style functions now return `ApiResult<T>` (error handling)**: All async API-style functions in pace-core now return `Promise<ApiResult<T>>` instead of throwing or returning raw values. Affected surfaces: RBAC (`isPermitted`, `getAccessLevel`, etc.), auth (auth-utils, `IAuthService`/`AuthService`), file-reference service and storage helpers (`extractFileMetadata`, `getSignedUrl`, `listFiles`, `downloadFile`, `generateFileUrlsBatch`), context/app utilities (`organisationContext`, `appIdResolver`), Google Places and CSRF, and security (`validateUserSession`, etc.).
+  - **Action Required**: Check `result.ok` and use `result.data` or `result.error` at every call site.
+  - **Migration**:
+    ```ts
+    // ❌ OLD: Direct value or throw
+    const data = await someApi();
+    if (!data) throw new Error('Failed');
+    use(data);
+
+    // ✅ NEW: ApiResult shape
+    const result = await someApi();
+    if (!result.ok) {
+      console.error(result.error.code, result.error.message);
+      return;
+    }
+    use(result.data);
+    ```
+  - **Types**: Import `ApiResult`, `ApiError`, and helpers `ok`, `err`, `isOk`, `isErr` from `@jmruthers/pace-core`.
+  - See [API & Tech Stack Standard](./docs/standards/7-api-tech-stack-standards.md) and [Architecture Standard](./docs/standards/3-architecture-standards.md).
+  - See [ApiResult migration guide](./docs/migration/ApiResult-migration.md) for affected surfaces and migration steps.
+
 - **@supabase/supabase-js is now an included dependency (security enforcement)**: Moved from peer dependency to included dependency to enforce security rules. Consuming apps can no longer import `createClient` directly.
   - **Action Required**: 
     - Remove `@supabase/supabase-js` from your `package.json` if installed

package/audit-tool/00-dependencies.cjs

@@ -154,22 +154,37 @@ function checkVersion(installed, required) {
 }
 
 // Main audit function - returns data structure for programmatic use
-function runDependencyAudit(consumingAppPath = process.cwd()) {
+// auditContext: { isPaceCorePackage?: boolean } - when true, skip audit (package does not install itself)
+function runDependencyAudit(consumingAppPath = process.cwd(), auditContext = {}) {
   const packageJsonPath = path.join(consumingAppPath, 'package.json');
-  
+  const emptyIssues = { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] };
+
   if (!fs.existsSync(packageJsonPath)) {
     return {
       error: `package.json not found at ${packageJsonPath}`,
-      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
+      issues: emptyIssues
     };
   }
+
+  if (auditContext.isPaceCorePackage === true) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      return {
+        projectName: pkg.name || '@jmruthers/pace-core',
+        paceCoreVersion: 'self',
+        issues: emptyIssues
+      };
+    } catch (e) {
+      return { projectName: 'unknown', paceCoreVersion: 'self', issues: emptyIssues };
+    }
+  }
   
   // Load pace-core package.json
   const paceCorePath = findPaceCorePackageJson(consumingAppPath);
   if (!paceCorePath) {
     return {
       error: 'Could not find pace-core package.json. Make sure @jmruthers/pace-core is installed in your project.',
-      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
+      issues: emptyIssues
     };
   }
   
@@ -223,16 +238,34 @@ function runDependencyAudit(consumingAppPath = process.cwd()) {
     devVersionIssues: [],
   };
   
-  // Check for included dependencies
-  INCLUDED_DEPS.forEach(dep => {
-    if (allDeps[dep]) {
-      issues.includedDeps.push({
-        package: dep,
-        installed: allDeps[dep],
-        location: consumingPkg.dependencies?.[dep] ? 'dependencies' : 'devDependencies',
-      });
+  // When auditing the pace-core repo root (monorepo), skip "included deps" check:
+  // the root package.json is the workspace root and shares the dependency tree with packages/core.
+  const packagesCorePath = path.join(consumingAppPath, 'packages', 'core', 'package.json');
+  const isPaceCoreRepoRoot = fs.existsSync(packagesCorePath);
+  let skipIncludedDepsCheck = false;
+  if (isPaceCoreRepoRoot) {
+    try {
+      const corePkg = JSON.parse(fs.readFileSync(packagesCorePath, 'utf8'));
+      if (corePkg.name === '@jmruthers/pace-core') {
+        skipIncludedDepsCheck = true;
+      }
+    } catch (e) {
+      // ignore
     }
-  });
+  }
+  
+  // Check for included dependencies (skip when auditing pace-core repo root)
+  if (!skipIncludedDepsCheck) {
+    INCLUDED_DEPS.forEach(dep => {
+      if (allDeps[dep]) {
+        issues.includedDeps.push({
+          package: dep,
+          installed: allDeps[dep],
+          location: consumingPkg.dependencies?.[dep] ? 'dependencies' : 'devDependencies',
+        });
+      }
+    });
+  }
   
   // Check for required peer dependencies
   REQUIRED_PEERS.forEach(dep => {

package/audit-tool/audits/01-pace-core-compliance.cjs

@@ -47,7 +47,8 @@ function checkProviderNesting(consumingAppPath) {
       line: 0,
       message: 'main.tsx file not found. Cannot validate provider nesting order.',
       severity: 'error',
-      fix: 'Create src/main.tsx with proper provider nesting: QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider',
+      fix: 'Create src/main.tsx with proper provider nesting: QueryClientProvider → BrowserRouter → UnifiedAuthProvider',
+      standardSection: 'MUST: Provider Nesting Order',
     });
     return issues;
   }
@@ -59,18 +60,22 @@ function checkProviderNesting(consumingAppPath) {
   
   const relativePath = getRelativePath(mainFile, consumingAppPath);
   
-  // Required provider order: QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider
+  // Required provider order: QueryClientProvider → BrowserRouter → UnifiedAuthProvider
+  // OrganisationServiceProvider is inside UnifiedAuthProvider; consuming apps must not wrap with it.
   const requiredProviders = [
     { name: 'QueryClientProvider', import: '@tanstack/react-query' },
     { name: 'BrowserRouter', import: 'react-router-dom' },
     { name: 'UnifiedAuthProvider', import: '@jmruthers/pace-core' },
-    { name: 'OrganisationProvider', import: '@jmruthers/pace-core' },
   ];
   
-  // Check if all providers are imported
+  // Check if all required providers are imported
   const missingProviders = requiredProviders.filter(provider => {
-    const importPattern = new RegExp(`import.*${provider.name}.*from\\s+['"]${provider.import.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`);
-    return !importPattern.test(content);
+    const names = [provider.name].concat(provider.altName || []);
+    const hasImport = names.some(name => {
+      const importPattern = new RegExp(`import.*${name}.*from\\s+['"]${provider.import.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`);
+      return importPattern.test(content);
+    });
+    return !hasImport;
   });
   
   if (missingProviders.length > 0) {
@@ -81,6 +86,7 @@ function checkProviderNesting(consumingAppPath) {
       message: `Missing required providers: ${missingProviders.map(p => p.name).join(', ')}`,
       severity: 'error',
       fix: `Import and use all required providers in the correct order: ${requiredProviders.map(p => p.name).join(' → ')}`,
+      standardSection: 'MUST: Provider Nesting Order',
     });
     return issues;
   }
@@ -97,7 +103,8 @@ function checkProviderNesting(consumingAppPath) {
     }
     
     const providerName = match[1];
-    if (requiredProviders.some(p => p.name === providerName)) {
+    const isRequired = requiredProviders.some(p => p.name === providerName || (p.altName && p.altName === providerName));
+    if (isRequired) {
       providers.push({
         name: providerName,
         index: match.index,
@@ -106,10 +113,13 @@ function checkProviderNesting(consumingAppPath) {
     }
   }
   
-  // Check order
+  // Check order (normalize altName to canonical name for comparison)
   if (providers.length > 0) {
     const expectedOrder = requiredProviders.map(p => p.name);
-    const actualOrder = providers.map(p => p.name);
+    const actualOrder = providers.map(p => {
+      const def = requiredProviders.find(r => r.name === p.name || r.altName === p.name);
+      return def ? def.name : p.name;
+    });
     
     // Check if order matches
     let orderCorrect = true;
@@ -129,6 +139,7 @@ function checkProviderNesting(consumingAppPath) {
         code: getCodeSnippet(content, providers[0].index, 0, 200),
         severity: 'error',
         fix: `Reorder providers to: ${expectedOrder.join(' → ')}`,
+        standardSection: 'MUST: Provider Nesting Order',
       });
     }
   }
@@ -164,6 +175,7 @@ function checkCoreStylesImport(consumingAppPath) {
       message: 'app.css file not found. Required for pace-core styling.',
       severity: 'error',
       fix: 'Create src/app.css with @import "@jmruthers/pace-core/styles/core.css";',
+      standardSection: 'Core styles import (see Styling standard)',
     });
     return issues;
   }
@@ -190,6 +202,7 @@ function checkCoreStylesImport(consumingAppPath) {
         message: `Missing required import: ${name}`,
         severity: 'error',
         fix: `Add ${name}; to app.css`,
+        standardSection: 'Core styles import (see Styling standard)',
       });
     }
   });
@@ -204,6 +217,7 @@ function checkCoreStylesImport(consumingAppPath) {
       message: 'Missing @source directives for Tailwind v4 content scanning',
       severity: 'warning',
       fix: 'Add @source directives: @source "./**/*.{js,ts,jsx,tsx}"; @source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";',
+      standardSection: 'Core styles import (see Styling standard)',
     });
   }
   
@@ -244,6 +258,7 @@ function checkRBACSetup(consumingAppPath) {
       message: 'main.tsx file not found. setupRBAC() must be called in main.tsx before app rendering.',
       severity: 'error',
       fix: 'Create src/main.tsx and call setupRBAC(supabase) before rendering the app.',
+      standardSection: 'MUST: Setup RBAC Before Use',
     });
     return issues;
   }
@@ -265,6 +280,7 @@ function checkRBACSetup(consumingAppPath) {
       message: 'setupRBAC() call not found. Must be called in main.tsx before app rendering.',
       severity: 'error',
       fix: 'Add: import { setupRBAC } from \'@jmruthers/pace-core/rbac\'; setupRBAC(supabase);',
+      standardSection: 'MUST: Setup RBAC Before Use',
     });
   } else {
     // Check if it's called before React rendering
@@ -280,6 +296,7 @@ function checkRBACSetup(consumingAppPath) {
         code: getCodeSnippet(content, setupRBACIndex),
         severity: 'error',
         fix: 'Move setupRBAC() call before createRoot() or render() call.',
+        standardSection: 'MUST: Setup RBAC Before Use',
       });
     }
   }
@@ -337,6 +354,7 @@ function checkViteAliases(consumingAppPath) {
         code: getCodeSnippet(content, match.index),
         severity: 'error',
         fix: `Remove this alias and use @jmruthers/pace-core/${paceCoreExport} directly`,
+        standardSection: 'MUST: Vite Configuration',
       });
     }
   }
@@ -413,6 +431,7 @@ function checkSecureSupabaseClient(consumingAppPath) {
           code: getCodeSnippet(content, match.index),
           severity: 'error',
           fix: 'Move createClient() call to main.tsx or lib/supabase.ts. Use useSecureSupabase() hook for queries.',
+          standardSection: 'MUST: Use Secure Supabase Client',
         });
       }
     }
@@ -436,7 +455,8 @@ function checkCursorRules(consumingAppPath) {
       line: 0,
       message: 'Cursor rules directory not found. Cursor rules provide AI-assisted enforcement.',
       severity: 'warning',
-      fix: 'Run: npm run setup:cursor-rules',
+      fix: 'Run: npm run setup',
+      standardSection: 'Step 3: Setup Cursor Rules',
     });
     return issues;
   }
@@ -459,13 +479,62 @@ function checkCursorRules(consumingAppPath) {
       line: 0,
       message: `Missing pace-core cursor rules: ${missingRules.join(', ')}`,
       severity: 'warning',
-      fix: 'Run: npm run setup:cursor-rules',
+      fix: 'Run: npm run setup',
+      standardSection: 'Step 3: Setup Cursor Rules',
     });
   }
   
   return issues;
 }
 
+/**
+ * Check for global auth gate anti-pattern (redirect to /login when !isAuthenticated in a wrapper).
+ * MUST use public /login route and ProtectedRoute per route; MUST NOT wrap Routes in a component
+ * that redirects unauthenticated users to /login (races with post-login context updates).
+ */
+function checkAuthRoutingPattern(consumingAppPath) {
+  const issues = [];
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!fs.existsSync(srcDir)) {
+    return issues;
+  }
+
+  const sourceFiles = findSourceFiles(srcDir, ['.tsx', '.jsx']);
+  const hasNavigateToLogin = /<Navigate\s+[^>]*to\s*=\s*\{?['"`]\/login['"`]?\}?/;
+  const hasAuthCheck = /(isAuthenticated|useUnifiedAuth\s*\(|useAuth\s*\()/;
+  const hasRedirectWhenUnauthenticated = /(!\s*isAuthenticated|isAuthenticated\s*===\s*false|!\s*user\b)/;
+
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) return;
+
+    if (!hasNavigateToLogin.test(content)) return;
+    if (!hasAuthCheck.test(content)) return;
+    if (!hasRedirectWhenUnauthenticated.test(content)) return;
+
+    const normalizedPath = path.normalize(filePath);
+    if (normalizedPath.includes('ProtectedRoute') || normalizedPath.includes('packages' + path.sep + 'core')) return;
+
+    const relativePath = getRelativePath(filePath, consumingAppPath);
+    const navigateMatch = content.match(hasNavigateToLogin);
+    const line = navigateMatch ? getLineNumber(content, content.indexOf(navigateMatch[0])) : 1;
+
+    issues.push({
+      type: 'authRouting',
+      file: relativePath,
+      line,
+      message: 'Possible global auth gate: redirect to /login when not authenticated. This pattern can cause "login succeeds but redirect doesn\'t happen" or form reset.',
+      code: navigateMatch ? getCodeSnippet(content, content.indexOf(navigateMatch[0]), 0, 80) : undefined,
+      severity: 'error',
+      fix: 'Use a public /login route and wrap other routes in <Route element={<ProtectedRoute />}> (from @jmruthers/pace-core). Do not wrap <Routes> in a component that redirects when !isAuthenticated.',
+      standardSection: 'MUST: Auth routing',
+      details: 'See Authentication implementation guide: Critical: Auth routing pattern and troubleshooting "Login succeeds but redirect doesn\'t happen".',
+    });
+  });
+
+  return issues;
+}
+
 /**
  * Check ESLint config setup
  */
@@ -490,7 +559,8 @@ function checkESLintConfig(consumingAppPath) {
       line: 0,
       message: 'ESLint config file not found. ESLint provides real-time compliance checking.',
       severity: 'warning',
-      fix: 'Run: npm run setup:eslint',
+      fix: 'Run: npm run setup',
+      standardSection: 'Step 2: Setup ESLint',
     });
     return issues;
   }
@@ -514,7 +584,8 @@ function checkESLintConfig(consumingAppPath) {
       line: 1,
       message: 'ESLint config does not include pace-core config. pace-core ESLint rules provide real-time compliance checking.',
       severity: 'warning',
-      fix: 'Run: npm run setup:eslint or manually add: import paceCoreConfig from \'@jmruthers/pace-core/eslint-config\';',
+      fix: 'Run: npm run setup or manually add: import paceCoreConfig from \'@jmruthers/pace-core/eslint-config\';',
+      standardSection: 'Step 2: Setup ESLint',
     });
   }
   
@@ -524,20 +595,24 @@ function checkESLintConfig(consumingAppPath) {
 /**
  * Run audit for Standard 1: pace-core Compliance
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - When isPaceCorePackage, skip app-only checks (main.tsx, app.css, rbacSetup, cursorRules, eslintConfig)
  * @returns {object} - Audit results with issues array
  */
-function runStandard1Audit(consumingAppPath) {
+function runStandard1Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
-  
+  const isPaceCorePackage = auditContext.isPaceCorePackage === true;
+
   try {
-    // System-level checks only (ESLint handles file-level checks)
-    issues.push(...checkProviderNesting(consumingAppPath));
-    issues.push(...checkCoreStylesImport(consumingAppPath));
-    issues.push(...checkRBACSetup(consumingAppPath));
+    if (!isPaceCorePackage) {
+      issues.push(...checkProviderNesting(consumingAppPath));
+      issues.push(...checkCoreStylesImport(consumingAppPath));
+      issues.push(...checkRBACSetup(consumingAppPath));
+      issues.push(...checkCursorRules(consumingAppPath));
+      issues.push(...checkESLintConfig(consumingAppPath));
+    }
     issues.push(...checkViteAliases(consumingAppPath));
     issues.push(...checkSecureSupabaseClient(consumingAppPath));
-    issues.push(...checkCursorRules(consumingAppPath));
-    issues.push(...checkESLintConfig(consumingAppPath));
+    issues.push(...checkAuthRoutingPattern(consumingAppPath));
   } catch (error) {
     return {
       standard: '01-pace-core-compliance',

package/audit-tool/audits/02-project-structure.cjs

@@ -41,6 +41,7 @@ function checkDirectoryStructure(consumingAppPath) {
         message: `Required directory missing: ${dirPath} (${description})`,
         severity: 'error',
         fix: `Create ${dirPath}/ directory`,
+        standardSection: 'Standard Directory Structure',
       });
     }
   });
@@ -72,6 +73,7 @@ function checkConfigFiles(consumingAppPath) {
         message: `Required configuration file missing: ${name} (${description})`,
         severity: 'error',
         fix: `Create ${name} file`,
+        standardSection: 'Configuration Files',
       });
     }
   });
@@ -119,6 +121,7 @@ function checkImportPaths(consumingAppPath) {
       message: 'tsconfig.json missing paths configuration. Consider adding path aliases for cleaner imports.',
       severity: 'info',
       fix: 'Add paths configuration: { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }',
+      standardSection: 'Import Path Configuration',
     });
   }
   
@@ -190,6 +193,7 @@ function checkTestColocation(consumingAppPath) {
           message: `Test file is in a test directory but should be colocated with source file. Move to ${parentDir}`,
           severity: 'warning',
           fix: `Move test file to ${parentDir} to colocate with source file`,
+          standardSection: 'Testing Structure (Test Colocation)',
         });
       }
     }
@@ -198,6 +202,69 @@ function checkTestColocation(consumingAppPath) {
   return issues;
 }
 
+/**
+ * Check for domain-based organization (Pattern 2 - not allowed)
+ * Feature-based organization is the only standard
+ */
+function checkFeatureBasedOrganization(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!directoryExists(srcDir)) {
+    return issues;
+  }
+  
+  // Check for src/domains/ directory (Pattern 2 structure - not allowed)
+  const domainsDir = path.join(srcDir, 'domains');
+  if (directoryExists(domainsDir)) {
+    issues.push({
+      type: 'organizationPattern',
+      file: 'src/domains',
+      line: 0,
+      message: 'Domain-based organization (src/domains/) is not allowed. Use feature-based organization instead (src/components/[feature]/, src/hooks/[feature]/, etc.)',
+      severity: 'error',
+      fix: 'Reorganize to feature-based structure: move components from src/domains/[domain]/components/ to src/components/[domain]/, hooks to src/hooks/[domain]/, etc.',
+      standardSection: 'Component Organization / File Organization Standard',
+    });
+  }
+  
+  // Check components directory for type-based organization (anti-pattern)
+  const componentsDir = path.join(srcDir, 'components');
+  if (directoryExists(componentsDir)) {
+    const componentDirs = [];
+    function scanComponentsDir(dir) {
+      if (!fs.existsSync(dir)) return;
+      const entries = fs.readdirSync(dir);
+      entries.forEach(entry => {
+        const entryPath = path.join(dir, entry);
+        const stat = fs.statSync(entryPath);
+        if (stat.isDirectory()) {
+          componentDirs.push(entry);
+        }
+      });
+    }
+    scanComponentsDir(componentsDir);
+    
+    // Common type-based directory names that should not exist
+    const typeBasedPatterns = ['buttons', 'button', 'inputs', 'input', 'cards', 'card', 'forms', 'form', 'modals', 'modal', 'dialogs', 'dialog'];
+    const foundTypeBased = componentDirs.filter(dir => typeBasedPatterns.includes(dir.toLowerCase()));
+    
+    if (foundTypeBased.length > 0) {
+      issues.push({
+        type: 'organizationPattern',
+        file: `src/components/${foundTypeBased[0]}`,
+        line: 0,
+        message: `Components organized by type (${foundTypeBased.join(', ')}) instead of feature. Use pace-core components for UI primitives and organize app components by feature.`,
+        severity: 'error',
+        fix: `Reorganize components by feature. Use pace-core for ${foundTypeBased.join(', ')} components. Move feature-specific components to src/components/[feature]/`,
+        standardSection: 'Component Organization / File Organization Standard',
+      });
+    }
+  }
+  
+  return issues;
+}
+
 /**
  * Check Supabase structure
  * Note: Consuming apps don't need migrations directory - only pace-core handles migrations
@@ -214,16 +281,21 @@ function checkSupabaseStructure(consumingAppPath) {
 /**
  * Run audit for Standard 2: Project Structure
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - When isPaceCorePackage, skip organizationPattern (library organizes by type by design)
  * @returns {object} - Audit results with issues array
  */
-function runStandard2Audit(consumingAppPath) {
+function runStandard2Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
-  
+  const isPaceCorePackage = auditContext.isPaceCorePackage === true;
+
   try {
     issues.push(...checkDirectoryStructure(consumingAppPath));
     issues.push(...checkConfigFiles(consumingAppPath));
     issues.push(...checkImportPaths(consumingAppPath));
     issues.push(...checkTestColocation(consumingAppPath));
+    if (!isPaceCorePackage) {
+      issues.push(...checkFeatureBasedOrganization(consumingAppPath));
+    }
     issues.push(...checkSupabaseStructure(consumingAppPath));
   } catch (error) {
     return {