@jmruthers/pace-core 0.5.185 → 0.5.186

package/scripts/check-pace-core-compliance.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+
+/**
+ * Static Analysis Script for pace-core Compliance
+ * @package @jmruthers/pace-core
+ * @module Scripts/check-pace-core-compliance
+ * 
+ * Scans a consuming app's codebase to check compliance with pace-core usage.
+ * Generates a report of violations and suggestions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m'
+};
+
+// Load manifest
+function loadManifest() {
+  const manifestPath = path.join(__dirname, '../core-usage-manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    console.error(`${colors.red}Error: core-usage-manifest.json not found at ${manifestPath}${colors.reset}`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+// Find project root (look for package.json, going up from current dir or script location)
+function findProjectRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  while (current !== path.dirname(current)) {
+    if (fs.existsSync(path.join(current, 'package.json'))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  return startDir;
+}
+
+// Scan file for violations
+function scanFile(filePath, manifest) {
+  const violations = {
+    restrictedImports: [],
+    duplicateComponents: [],
+    duplicateHooks: [],
+    duplicateUtils: [],
+    suggestions: [],
+    customAuthCode: [],
+    duplicateConfig: [],
+    unprotectedPages: [],
+    directSupabaseAuth: []
+  };
+  
+  const content = fs.readFileSync(filePath, 'utf8');
+  const relativePath = path.relative(process.cwd(), filePath);
+  
+  // Check for restricted imports
+  manifest.restrictedImports.forEach(({ module, reason }) => {
+    const importPattern = new RegExp(`from\\s+['"]${module.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`, 'g');
+    if (importPattern.test(content)) {
+      violations.restrictedImports.push({
+        module,
+        reason,
+        file: relativePath,
+        line: getLineNumber(content, content.match(importPattern)[0])
+      });
+    }
+    
+    // Also check for @radix-ui/* pattern
+    if (module.startsWith('@radix-ui/')) {
+      const radixPattern = /from\s+['"]@radix-ui\/[^'"]+['"]/g;
+      const matches = content.match(radixPattern);
+      if (matches) {
+        matches.forEach(match => {
+          const matchedModule = match.match(/['"]([^'"]+)['"]/)[1];
+          if (!manifest.restrictedImports.find(ri => ri.module === matchedModule)) {
+            violations.restrictedImports.push({
+              module: matchedModule,
+              reason: 'Use pace-core component instead of direct Radix UI import',
+              file: relativePath,
+              line: getLineNumber(content, match)
+            });
+          }
+        });
+      }
+    }
+  });
+  
+  // Check for duplicate component names
+  const filename = path.basename(filePath);
+  const componentName = filename.replace(/\.(tsx?|jsx?)$/, '').replace(/\.(test|spec)$/, '');
+  
+  if (manifest.components.includes(componentName)) {
+    // Check if this file exports a component
+    if (content.match(/export\s+(default\s+)?(function|const|class)\s+(\w+)?/)) {
+      violations.duplicateComponents.push({
+        component: componentName,
+        file: relativePath
+      });
+    }
+  }
+  
+  // Check for duplicate hook names
+  if (filename.startsWith('use') && filename.endsWith('.ts') || filename.endsWith('.tsx')) {
+    const hookName = filename.replace(/\.(tsx?|jsx?)$/, '').replace(/\.(test|spec)$/, '');
+    if (manifest.hooks.includes(hookName)) {
+      if (content.match(/export\s+(default\s+)?(function|const)\s+(\w+)?/)) {
+        violations.duplicateHooks.push({
+          hook: hookName,
+          file: relativePath
+        });
+      }
+    }
+  }
+  
+  // Check for duplicate util names
+  const utilName = filename.replace(/\.(ts|js)$/, '').replace(/\.(test|spec)$/, '');
+  if (manifest.utils.includes(utilName)) {
+    if (content.match(/export\s+(default\s+)?(function|const)\s+(\w+)?/)) {
+      violations.duplicateUtils.push({
+        util: utilName,
+        file: relativePath
+      });
+    }
+  }
+  
+  // Check for native HTML elements that should use pace-core components
+  const nativeElementPatterns = {
+    '<button': { suggestion: 'Use Button from @jmruthers/pace-core' },
+    '<input': { suggestion: 'Use Input from @jmruthers/pace-core' },
+    '<textarea': { suggestion: 'Use Textarea from @jmruthers/pace-core' },
+    '<label': { suggestion: 'Use Label from @jmruthers/pace-core' }
+  };
+  
+  Object.entries(nativeElementPatterns).forEach(([pattern, { suggestion }]) => {
+    if (content.includes(pattern) && !content.includes('from \'@jmruthers/pace-core\'')) {
+      violations.suggestions.push({
+        type: 'native-element',
+        suggestion,
+        file: relativePath,
+        pattern
+      });
+    }
+  });
+  
+  // ============================================
+  // RBAC/Auth Compliance Checks
+  // ============================================
+  
+  // Check for custom auth/rbac/permission code that doesn't import from pace-core
+  const authRbacPatterns = [
+    // Custom auth hooks
+    { pattern: /export\s+(default\s+)?(function|const)\s+useAuth\s*[=\(]/g, name: 'useAuth', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useLogin\s*[=\(]/g, name: 'useLogin', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useLogout\s*[=\(]/g, name: 'useLogout', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useSession\s*[=\(]/g, name: 'useSession', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useUser\s*[=\(]/g, name: 'useUser', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useAuthentication\s*[=\(]/g, name: 'useAuthentication', type: 'hook' },
+    // Custom RBAC hooks
+    { pattern: /export\s+(default\s+)?(function|const)\s+usePermissions\s*[=\(]/g, name: 'usePermissions', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useCan\s*[=\(]/g, name: 'useCan', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useAccessLevel\s*[=\(]/g, name: 'useAccessLevel', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useRole\s*[=\(]/g, name: 'useRole', type: 'hook' },
+    // Custom RBAC components
+    { pattern: /export\s+(default\s+)?(function|const)\s+PermissionGuard\s*[=\(]/g, name: 'PermissionGuard', type: 'component' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+AuthGuard\s*[=\(]/g, name: 'AuthGuard', type: 'component' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+RoleGuard\s*[=\(]/g, name: 'RoleGuard', type: 'component' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+AccessGuard\s*[=\(]/g, name: 'AccessGuard', type: 'component' },
+    // Custom permission utilities
+    { pattern: /export\s+(default\s+)?(function|const)\s+checkPermission\s*[=\(]/g, name: 'checkPermission', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+hasPermission\s*[=\(]/g, name: 'hasPermission', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+hasAccess\s*[=\(]/g, name: 'hasAccess', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+canAccess\s*[=\(]/g, name: 'canAccess', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+isPermitted\s*[=\(]/g, name: 'isPermitted', type: 'util' }
+  ];
+  
+  // Check if file imports from pace-core for auth/rbac
+  const hasPaceCoreImport = /from\s+['"]@jmruthers\/pace-core/.test(content) || 
+                            /from\s+['"]@jmruthers\/pace-core\/rbac/.test(content) ||
+                            /from\s+['"]@jmruthers\/pace-core\/providers/.test(content);
+  
+  authRbacPatterns.forEach(({ pattern, name, type }) => {
+    if (pattern.test(content) && !hasPaceCoreImport) {
+      violations.customAuthCode.push({
+        name,
+        type,
+        file: relativePath,
+        line: getLineNumber(content, content.match(pattern)[0]),
+        reason: `Custom ${type} '${name}' detected. Use pace-core's ${name} instead.`
+      });
+    }
+  });
+  
+  // Check for duplicate Supabase client configurations
+  const supabaseCreateClientPattern = /createClient\s*\(/g;
+  const supabaseCreateClientMatches = content.match(supabaseCreateClientPattern);
+  if (supabaseCreateClientMatches && supabaseCreateClientMatches.length > 1) {
+    violations.duplicateConfig.push({
+      type: 'supabase-client',
+      file: relativePath,
+      count: supabaseCreateClientMatches.length,
+      reason: `Multiple Supabase client instantiations found (${supabaseCreateClientMatches.length}). Consolidate to a single client configuration.`
+    });
+  }
+  
+  // Check for Supabase URL/key configuration in multiple places
+  const supabaseUrlPattern = /(SUPABASE_URL|VITE_SUPABASE_URL|NEXT_PUBLIC_SUPABASE_URL|REACT_APP_SUPABASE_URL)/g;
+  const supabaseKeyPattern = /(SUPABASE_ANON_KEY|VITE_SUPABASE_ANON_KEY|NEXT_PUBLIC_SUPABASE_ANON_KEY|REACT_APP_SUPABASE_ANON_KEY)/g;
+  const urlMatches = content.match(supabaseUrlPattern);
+  const keyMatches = content.match(supabaseKeyPattern);
+  
+  if ((urlMatches && urlMatches.length > 2) || (keyMatches && keyMatches.length > 2)) {
+    violations.duplicateConfig.push({
+      type: 'supabase-env',
+      file: relativePath,
+      reason: 'Supabase environment variables referenced multiple times. Consider centralizing configuration.'
+    });
+  }
+  
+  // Check for unprotected pages/routes
+  // Look for route definitions without PagePermissionGuard
+  const routePatterns = [
+    /<Route\s+path=["'][^"']+["']/g,
+    /<Route\s+element\s*=/g,
+    /createBrowserRouter\s*\(/g,
+    /createRoutesFromElements/g
+  ];
+  
+  const isRouteFile = routePatterns.some(pattern => pattern.test(content));
+  const hasPagePermissionGuard = /PagePermissionGuard/.test(content) || 
+                                  /from\s+['"]@jmruthers\/pace-core\/rbac['"]/.test(content);
+  
+  if (isRouteFile && !hasPagePermissionGuard && !relativePath.includes('test') && !relativePath.includes('spec')) {
+    violations.unprotectedPages.push({
+      file: relativePath,
+      reason: 'Route file found without PagePermissionGuard. All routes should be protected with PagePermissionGuard from pace-core.'
+    });
+  }
+  
+  // Check for direct Supabase auth usage (should use UnifiedAuthProvider)
+  const directSupabaseAuthPatterns = [
+    /\.auth\.signIn/g,
+    /\.auth\.signUp/g,
+    /\.auth\.signOut/g,
+    /\.auth\.getSession/g,
+    /\.auth\.getUser/g,
+    /supabase\.auth\./g
+  ];
+  
+  const hasUnifiedAuthImport = /UnifiedAuthProvider/.test(content) || 
+                               /useUnifiedAuth/.test(content) ||
+                               /from\s+['"]@jmruthers\/pace-core\/providers/.test(content);
+  
+  directSupabaseAuthPatterns.forEach(pattern => {
+    if (pattern.test(content) && !hasUnifiedAuthImport && !hasPaceCoreImport) {
+      violations.directSupabaseAuth.push({
+        file: relativePath,
+        line: getLineNumber(content, content.match(pattern)[0]),
+        reason: 'Direct Supabase auth usage detected. Use UnifiedAuthProvider and useUnifiedAuth from pace-core instead.'
+      });
+    }
+  });
+  
+  return violations;
+}
+
+// Get line number for a match
+function getLineNumber(content, match) {
+  const lines = content.substring(0, content.indexOf(match)).split('\n');
+  return lines.length;
+}
+
+// Generate report
+function generateReport(allViolations, manifest) {
+  const totalRestricted = allViolations.restrictedImports.length;
+  const totalDuplicates = 
+    allViolations.duplicateComponents.length +
+    allViolations.duplicateHooks.length +
+    allViolations.duplicateUtils.length;
+  const totalSuggestions = allViolations.suggestions.length;
+  const totalRbacAuth = 
+    allViolations.customAuthCode.length +
+    allViolations.duplicateConfig.length +
+    allViolations.unprotectedPages.length +
+    allViolations.directSupabaseAuth.length;
+  const totalIssues = totalRestricted + totalDuplicates + totalSuggestions + totalRbacAuth;
+  
+  console.log(`\n${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+  console.log(`${colors.bold}${colors.cyan}  pace-core Compliance Report${colors.reset}`);
+  console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}\n`);
+  
+  // Restricted Imports
+  if (totalRestricted > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Restricted Imports Found: ${totalRestricted}${colors.reset}\n`);
+    allViolations.restrictedImports.forEach(({ module, reason, file, line }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+      console.log(`    Import: ${colors.cyan}${module}${colors.reset}`);
+      console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+    });
+  } else {
+    console.log(`${colors.green}✅ No restricted imports found${colors.reset}\n`);
+  }
+  
+  // Duplicate Components
+  if (allViolations.duplicateComponents.length > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicate Components Found: ${allViolations.duplicateComponents.length}${colors.reset}\n`);
+    allViolations.duplicateComponents.forEach(({ component, file }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      console.log(`    Component '${colors.cyan}${component}${colors.reset}' conflicts with pace-core component`);
+      console.log(`    ${colors.yellow}Suggestion:${colors.reset} Use '${component}' from '@jmruthers/pace-core' instead\n`);
+    });
+  }
+  
+  // Duplicate Hooks
+  if (allViolations.duplicateHooks.length > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicate Hooks Found: ${allViolations.duplicateHooks.length}${colors.reset}\n`);
+    allViolations.duplicateHooks.forEach(({ hook, file }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      console.log(`    Hook '${colors.cyan}${hook}${colors.reset}' conflicts with pace-core hook`);
+      console.log(`    ${colors.yellow}Suggestion:${colors.reset} Use '${hook}' from '@jmruthers/pace-core' instead\n`);
+    });
+  }
+  
+  // Duplicate Utils
+  if (allViolations.duplicateUtils.length > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicate Utils Found: ${allViolations.duplicateUtils.length}${colors.reset}\n`);
+    allViolations.duplicateUtils.forEach(({ util, file }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      console.log(`    Util '${colors.cyan}${util}${colors.reset}' conflicts with pace-core util`);
+      console.log(`    ${colors.yellow}Suggestion:${colors.reset} Use '${util}' from '@jmruthers/pace-core' instead\n`);
+    });
+  }
+  
+  // Suggestions
+  if (totalSuggestions > 0) {
+    console.log(`${colors.yellow}${colors.bold}💡 Suggestions: ${totalSuggestions}${colors.reset}\n`);
+    const grouped = {};
+    allViolations.suggestions.forEach(s => {
+      if (!grouped[s.file]) grouped[s.file] = [];
+      grouped[s.file].push(s);
+    });
+    Object.entries(grouped).forEach(([file, suggestions]) => {
+      console.log(`  ${colors.yellow}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      suggestions.forEach(s => {
+        console.log(`    ${s.suggestion}\n`);
+      });
+    });
+  }
+  
+  // RBAC/Auth Compliance Section
+  if (totalRbacAuth > 0) {
+    console.log(`\n${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}  RBAC/Auth Compliance${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}\n`);
+    
+    // Custom Auth/RBAC Code
+    if (allViolations.customAuthCode.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Custom Auth/RBAC Code Found: ${allViolations.customAuthCode.length}${colors.reset}\n`);
+      allViolations.customAuthCode.forEach(({ name, type, file, line, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+        console.log(`    ${type}: ${colors.cyan}${name}${colors.reset}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+    
+    // Duplicate Configurations
+    if (allViolations.duplicateConfig.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Duplicate Configurations Found: ${allViolations.duplicateConfig.length}${colors.reset}\n`);
+      allViolations.duplicateConfig.forEach(({ type, file, count, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+        console.log(`    Type: ${colors.cyan}${type}${colors.reset}${count ? ` (${count} instances)` : ''}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+    
+    // Unprotected Pages
+    if (allViolations.unprotectedPages.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Unprotected Pages Found: ${allViolations.unprotectedPages.length}${colors.reset}\n`);
+      allViolations.unprotectedPages.forEach(({ file, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+    
+    // Direct Supabase Auth Usage
+    if (allViolations.directSupabaseAuth.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Direct Supabase Auth Usage Found: ${allViolations.directSupabaseAuth.length}${colors.reset}\n`);
+      allViolations.directSupabaseAuth.forEach(({ file, line, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+  } else {
+    console.log(`\n${colors.green}✅ RBAC/Auth compliance: All checks passed${colors.reset}\n`);
+  }
+  
+  // Summary
+  console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+  console.log(`${colors.bold}Summary:${colors.reset}`);
+  console.log(`  Total Issues: ${totalIssues > 0 ? colors.red : colors.green}${totalIssues}${colors.reset}`);
+  console.log(`  - Restricted Imports: ${totalRestricted > 0 ? colors.red : colors.green}${totalRestricted}${colors.reset}`);
+  console.log(`  - Duplicate Components/Hooks/Utils: ${totalDuplicates > 0 ? colors.red : colors.green}${totalDuplicates}${colors.reset}`);
+  console.log(`  - Suggestions: ${colors.yellow}${totalSuggestions}${colors.reset}`);
+  console.log(`  - RBAC/Auth Issues: ${totalRbacAuth > 0 ? colors.red : colors.green}${totalRbacAuth}${colors.reset}`);
+  
+  if (totalIssues === 0) {
+    console.log(`\n${colors.green}${colors.bold}✅ Excellent! Your codebase is fully compliant with pace-core standards.${colors.reset}\n`);
+    return 0;
+  } else {
+    console.log(`\n${colors.yellow}${colors.bold}⚠️  Please review the issues above and migrate to pace-core components/hooks/utils.${colors.reset}\n`);
+    return 1;
+  }
+}
+
+// Recursively find source files
+function findSourceFiles(dir, fileList = []) {
+  const ignoreDirs = ['node_modules', 'dist', 'build', '.next', 'coverage', '__tests__', '__mocks__'];
+  const ignoreFiles = /\.(test|spec)\.(ts|tsx|js|jsx)$/;
+  const sourceExtensions = /\.(ts|tsx|js|jsx)$/;
+  
+  try {
+    const items = fs.readdirSync(dir);
+    
+    items.forEach(item => {
+      const fullPath = path.join(dir, item);
+      const stat = fs.statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        if (!ignoreDirs.includes(item) && !item.startsWith('.')) {
+          findSourceFiles(fullPath, fileList);
+        }
+      } else if (stat.isFile()) {
+        if (sourceExtensions.test(item) && !ignoreFiles.test(item)) {
+          fileList.push(fullPath);
+        }
+      }
+    });
+  } catch (error) {
+    // Skip directories we can't read
+  }
+  
+  return fileList;
+}
+
+// Main function
+function main() {
+  const manifest = loadManifest();
+  const projectRoot = findProjectRoot();
+  
+  console.log(`${colors.cyan}Scanning project at: ${projectRoot}${colors.reset}`);
+  
+  // Find all TypeScript/JavaScript files (excluding node_modules, dist, etc.)
+  const files = findSourceFiles(projectRoot);
+  
+  console.log(`Found ${files.length} files to scan...\n`);
+  
+  // Scan all files
+  const allViolations = {
+    restrictedImports: [],
+    duplicateComponents: [],
+    duplicateHooks: [],
+    duplicateUtils: [],
+    suggestions: [],
+    customAuthCode: [],
+    duplicateConfig: [],
+    unprotectedPages: [],
+    directSupabaseAuth: []
+  };
+  
+  files.forEach(file => {
+    try {
+      const violations = scanFile(file, manifest);
+      allViolations.restrictedImports.push(...violations.restrictedImports);
+      allViolations.duplicateComponents.push(...violations.duplicateComponents);
+      allViolations.duplicateHooks.push(...violations.duplicateHooks);
+      allViolations.duplicateUtils.push(...violations.duplicateUtils);
+      allViolations.suggestions.push(...violations.suggestions);
+      allViolations.customAuthCode.push(...violations.customAuthCode);
+      allViolations.duplicateConfig.push(...violations.duplicateConfig);
+      allViolations.unprotectedPages.push(...violations.unprotectedPages);
+      allViolations.directSupabaseAuth.push(...violations.directSupabaseAuth);
+    } catch (error) {
+      console.error(`${colors.red}Error scanning ${file}: ${error.message}${colors.reset}`);
+    }
+  });
+  
+  // Generate and display report
+  const exitCode = generateReport(allViolations, manifest);
+  process.exit(exitCode);
+}
+
+// Run if called directly
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+module.exports = { main, scanFile, generateReport };
+

package/src/components/FileUpload/FileUpload.test.tsx

@@ -71,6 +71,8 @@ describe('[component] FileUpload', () => {
     organisation_id: 'org-1',
     app_id: 'app-123',
     category: FileCategory.PROFILE_PHOTOS,
+    folder: 'profile_photos',
+    pageContext: 'test',
     accept: 'image/*',
   } as const;
 

package/src/components/FileUpload/FileUpload.tsx

@@ -22,7 +22,9 @@ export interface FileUploadProps {
   organisation_id: string;
   app_id?: string; // Optional - will be resolved from app name if not provided
   category: FileCategory;
+  folder: string; // Folder name in storage bucket (e.g., 'profile_photos', 'documents')
   pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
+  event_id?: string; // Optional event ID for event-scoped permission checks (required for event-based apps)
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
@@ -51,7 +53,9 @@ export function FileUpload({
   organisation_id,
   app_id,
   category,
+  folder,
   pageContext,
+  event_id,
   accept = '*/*',
   maxSize = 10 * 1024 * 1024, // 10MB default
   multiple = false,
@@ -286,7 +290,9 @@ export function FileUpload({
           organisation_id,
           app_id: resolvedAppId ? assertAppId(resolvedAppId) : assertAppId(''),
           category,
+          folder,
           pageContext,
+          event_id,
           is_public: isPublic
         }, file);
 
@@ -384,7 +390,7 @@ export function FileUpload({
         onUploadError?.(errorMessage, file);
       }
     }
-  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError]);
+  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, folder, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError]);
 
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();

package/src/components/Header/Header.tsx

@@ -260,7 +260,7 @@ export function Header({
       "w-full border-b border-main-200 h-16 shadow-sm bg-main-100 ",
       className
     )} role="banner">
-      <nav className="px-4 w-[min(var(--app-width),100%)] mx-auto grid grid-cols-[auto_auto_1fr_auto] gap-4 h-full items-center">
+      <nav className="px-4 w-[min(var(--app-width),100%)] mx-auto flex items-center gap-4 h-full">
           {/* Logo */}
           {logo ? (
             logoHref ? (
@@ -318,7 +318,7 @@ export function Header({
         
 
         {/* Right side: Organisation Selector, Event Selector, Actions, and User Menu */}
-        <div className="flex items-center gap-4 justify-end">
+        <div className="flex items-center gap-4 ml-auto">
           {/* Organisation Selector */}
           {showOrgSelector ? (
             <OrganisationSelector 
@@ -337,10 +337,7 @@ export function Header({
               data-testid="event-selector" 
             />
           ) : null}
-        </div>
           
-        {/* Custom Actions and User Menu */}
-        <div className="flex items-center gap-4">
           {/* Custom Actions */}
           {actions}