@jmruthers/pace-core 0.5.121 → 0.5.123

package/docs/troubleshooting/migration.md

@@ -0,0 +1,918 @@
+# Migration Guide
+
+This guide provides comprehensive migration strategies for upgrading `@jmruthers/pace-core` applications between versions and handling breaking changes.
+
+## Overview
+
+Migration in `@jmruthers/pace-core` covers:
+
+- **Version Upgrades**: Upgrading between major/minor versions
+- **Breaking Changes**: Handling API changes and deprecations
+- **Database Migrations**: Schema updates and data transformations
+- **Configuration Updates**: Environment and build configuration changes
+- **Dependency Updates**: Third-party library compatibility
+
+## Version Migration
+
+### 1. Major Version Migration (v1.x to v2.x)
+
+```typescript
+// Before v2.0.0
+import { useAuth, usePermissions } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { user, signIn, signOut } = useAuth();
+  const { hasPermission } = usePermissions();
+  
+  return (
+    <div>
+      {user && <p>Welcome, {user.email}</p>}
+      {hasPermission('read:users') && <UserList />}
+    </div>
+  );
+}
+
+// After v2.0.0
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+import { useCan } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const { user, signIn, signOut } = useUnifiedAuth();
+  const { hasPermission } = useCan();
+  
+  return (
+    <div>
+      {user && <p>Welcome, {user.email}</p>}
+      {hasPermission('read:users') && <UserList />}
+    </div>
+  );
+}
+```
+
+### 2. Hook Migration Patterns
+
+```typescript
+// Migration helper for gradual updates
+function useLegacyAuth() {
+  const auth = useUnifiedAuth();
+  
+  // Provide legacy API compatibility
+  return {
+    user: auth.user,
+    loading: auth.loading,
+    error: auth.error,
+    signIn: auth.signIn,
+    signOut: auth.signOut,
+    // Legacy methods
+    login: auth.signIn,
+    logout: auth.signOut,
+    isAuthenticated: !!auth.user,
+  };
+}
+
+// Migration helper for RBAC
+import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
+
+function useLegacyPermissions() {
+  const { hasPermission } = useCan();
+  const { permissions } = usePermissions();
+  
+  return {
+    hasPermission,
+    permissions,
+    // Legacy methods
+    can: hasPermission,
+    userPermissions: permissions,
+  };
+}
+```
+
+### 3. Component Migration
+
+```typescript
+// Before: Old component API
+<Button 
+  variant="primary"
+  onClick={handleClick}
+  disabled={loading}
+>
+  Submit
+</Button>
+
+// After: New component API
+<Button 
+  variant="primary"
+  onClick={handleClick}
+  disabled={loading}
+  loading={loading}
+  size="md"
+>
+  Submit
+</Button>
+```
+
+## Breaking Changes Migration
+
+### 1. Authentication API Changes
+
+```typescript
+// Migration script for authentication changes
+function migrateAuthAPI() {
+  // Old API
+  const oldAuth = {
+    user: null,
+    signIn: async (email: string, password: string) => {
+      // Old implementation
+    },
+    signOut: async () => {
+      // Old implementation
+    },
+  };
+  
+  // New API
+  const newAuth = {
+    user: null,
+    signIn: async (credentials: { email: string; password: string }) => {
+      // New implementation
+    },
+    signOut: async () => {
+      // New implementation
+    },
+    // Additional methods
+    signUp: async (credentials: { email: string; password: string }) => {
+      // New signup implementation
+    },
+    resetPassword: async (email: string) => {
+      // New password reset implementation
+    },
+  };
+  
+  return newAuth;
+}
+
+// Migration helper
+function useAuthMigration() {
+  const auth = useUnifiedAuth();
+  
+  // Provide backward compatibility
+  const legacySignIn = useCallback((email: string, password: string) => {
+    return auth.signIn({ email, password });
+  }, [auth.signIn]);
+  
+  return {
+    ...auth,
+    // Legacy API
+    login: legacySignIn,
+    logout: auth.signOut,
+  };
+}
+```
+
+### 2. Permission System Changes
+
+```typescript
+// Migration script for permission changes
+function migratePermissions() {
+  // Old permission format
+  const oldPermissions = [
+    'read_users',
+    'write_events',
+    'delete_posts',
+  ];
+  
+  // New permission format
+  const newPermissions = [
+    'read:users',
+    'write:events',
+    'delete:posts',
+  ];
+  
+  // Migration function
+  function migratePermissionFormat(oldPermission: string): string {
+    return oldPermission.replace('_', ':');
+  }
+  
+  return {
+    oldPermissions,
+    newPermissions: oldPermissions.map(migratePermissionFormat),
+    migratePermissionFormat,
+  };
+}
+
+// Migration helper for permission checks
+function usePermissionMigration() {
+  const rbac = useRBAC();
+  
+  // Legacy permission check
+  const legacyHasPermission = useCallback((permission: string) => {
+    // Convert old format to new format
+    const newPermission = permission.replace('_', ':');
+    return rbac.hasPermission(newPermission);
+  }, [rbac]);
+  
+  return {
+    ...rbac,
+    // Legacy API
+    can: legacyHasPermission,
+    hasAccess: legacyHasPermission,
+  };
+}
+```
+
+### 3. Component Prop Changes
+
+```typescript
+// Migration script for component prop changes
+function migrateComponentProps() {
+  // Old Button props
+  const oldButtonProps = {
+    type: 'primary',
+    onClick: () => {},
+    disabled: false,
+    children: 'Click me',
+  };
+  
+  // New Button props
+  const newButtonProps = {
+    variant: 'primary', // type -> variant
+    onClick: () => {},
+    disabled: false,
+    loading: false, // New prop
+    size: 'md', // New prop
+    children: 'Click me',
+  };
+  
+  // Migration function
+  function migrateButtonProps(oldProps: any) {
+    return {
+      variant: oldProps.type,
+      onClick: oldProps.onClick,
+      disabled: oldProps.disabled,
+      loading: false, // Default value
+      size: 'md', // Default value
+      children: oldProps.children,
+    };
+  }
+  
+  return {
+    oldButtonProps,
+    newButtonProps,
+    migrateButtonProps,
+  };
+}
+```
+
+## Database Migration
+
+### 1. Schema Migration
+
+```sql
+-- Migration script for database schema changes
+-- 001_migrate_users_table.sql
+
+-- Add new columns to users table
+ALTER TABLE users 
+ADD COLUMN IF NOT EXISTS organisation_id UUID REFERENCES organisations(id),
+ADD COLUMN IF NOT EXISTS role VARCHAR(50) DEFAULT 'user',
+ADD COLUMN IF NOT EXISTS permissions JSONB DEFAULT '[]';
+
+-- Create index for performance
+CREATE INDEX IF NOT EXISTS idx_users_organisation_id ON users(organisation_id);
+CREATE INDEX IF NOT EXISTS idx_users_role ON users(role);
+
+-- Update existing users with default values
+UPDATE users 
+SET 
+  organisation_id = (SELECT id FROM organisations LIMIT 1),
+  role = 'user',
+  permissions = '[]'
+WHERE organisation_id IS NULL;
+
+-- Add constraints
+ALTER TABLE users 
+ALTER COLUMN organisation_id SET NOT NULL,
+ALTER COLUMN role SET NOT NULL;
+```
+
+### 2. Data Migration
+
+```typescript
+// Migration script for data transformation
+async function migrateUserData() {
+  const { supabase } = useSupabase();
+  
+  // Get all users
+  const { data: users, error } = await supabase
+    .from('users')
+    .select('*');
+  
+  if (error) {
+    console.error('Failed to fetch users:', error);
+    return;
+  }
+  
+  // Transform user data
+  const migratedUsers = users.map(user => ({
+    ...user,
+    // Convert old permission format to new format
+    permissions: user.permissions?.map((permission: string) => 
+      permission.replace('_', ':')
+    ) || [],
+    // Add default role if missing
+    role: user.role || 'user',
+    // Add organisation if missing
+    organisation_id: user.organisation_id || 'default-org-id',
+  }));
+  
+  // Update users in batches
+  const batchSize = 100;
+  for (let i = 0; i < migratedUsers.length; i += batchSize) {
+    const batch = migratedUsers.slice(i, i + batchSize);
+    
+    const { error: updateError } = await supabase
+      .from('users')
+      .upsert(batch);
+    
+    if (updateError) {
+      console.error(`Failed to update batch ${i / batchSize + 1}:`, updateError);
+    }
+  }
+  
+  console.log('User data migration completed');
+}
+```
+
+### 3. RLS Policy Migration
+
+```sql
+-- Migration script for RLS policies
+-- 002_migrate_rls_policies.sql
+
+-- Drop old policies
+DROP POLICY IF EXISTS "Users can view their own data" ON users;
+DROP POLICY IF EXISTS "Users can update their own data" ON users;
+
+-- Create new policies with organisation isolation
+CREATE POLICY "Users can view their own organisation's data" ON users
+  FOR SELECT USING (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
+
+CREATE POLICY "Users can update their own data" ON users
+  FOR UPDATE USING (
+    id = auth.uid() AND
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
+
+CREATE POLICY "Users can insert their own data" ON users
+  FOR INSERT WITH CHECK (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
+
+-- Apply similar policies to other tables
+-- events table
+CREATE POLICY "Users can view their organisation's events" ON events
+  FOR SELECT USING (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
+
+CREATE POLICY "Users can manage their organisation's events" ON events
+  FOR ALL USING (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
+```
+
+## Configuration Migration
+
+### 1. Environment Variables Migration
+
+```bash
+# Migration script for environment variables
+# old.env -> new.env
+
+# Old environment variables
+VITE_AUTH_URL=https://old-auth.example.com
+VITE_API_KEY=old-api-key
+VITE_DEBUG_MODE=true
+
+# New environment variables
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+VITE_APP_ENV=development
+VITE_DEBUG=false
+
+# Migration script
+#!/bin/bash
+# migrate-env.sh
+
+echo "Migrating environment variables..."
+
+# Backup old environment file
+cp .env .env.backup
+
+# Create new environment file
+cat > .env << EOF
+# Supabase Configuration
+VITE_SUPABASE_URL=${VITE_SUPABASE_URL:-https://your-project.supabase.co}
+VITE_SUPABASE_ANON_KEY=${VITE_SUPABASE_ANON_KEY:-your-anon-key}
+
+# Application Configuration
+VITE_APP_ENV=${VITE_APP_ENV:-development}
+VITE_DEBUG=${VITE_DEBUG:-false}
+
+# Feature Flags
+VITE_FEATURE_ANALYTICS=${VITE_FEATURE_ANALYTICS:-false}
+VITE_FEATURE_BETA=${VITE_FEATURE_BETA:-false}
+
+# Monitoring
+VITE_SENTRY_DSN=${VITE_SENTRY_DSN:-}
+VITE_ANALYTICS_ID=${VITE_ANALYTICS_ID:-}
+EOF
+
+echo "Environment migration completed"
+```
+
+### 2. Build Configuration Migration
+
+```typescript
+// Migration script for build configuration
+// vite.config.old.ts -> vite.config.ts
+
+// Old configuration
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    outDir: 'build',
+    sourcemap: true,
+  },
+  define: {
+    global: 'globalThis',
+  },
+});
+
+// New configuration
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    target: 'es2015',
+    outDir: 'dist',
+    sourcemap: false, // Disable in production
+    minify: 'terser',
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+          paceCore: ['@jmruthers/pace-core'],
+          supabase: ['@supabase/supabase-js'],
+        },
+      },
+    },
+    terserOptions: {
+      compress: {
+        drop_console: true,
+        drop_debugger: true,
+      },
+    },
+  },
+  define: {
+    __DEV__: JSON.stringify(process.env.NODE_ENV === 'development'),
+  },
+  optimizeDeps: {
+    include: ['@jmruthers/pace-core'],
+  },
+});
+```
+
+### 3. Package.json Migration
+
+```json
+// Migration script for package.json dependencies
+// package.json.old -> package.json
+
+{
+  "name": "my-app",
+  "version": "2.0.0",
+  "dependencies": {
+    // Old dependencies
+    "@jmruthers/pace-core": "^1.5.0",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    
+    // New dependencies
+    "@jmruthers/pace-core": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@supabase/supabase-js": "^2.38.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    // Old dev dependencies
+    "@types/react": "^17.0.0",
+    "@types/react-dom": "^17.0.0",
+    
+    // New dev dependencies
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "vite": "^4.4.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    // Old scripts
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test",
+    
+    // New scripts
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}
+```
+
+## Migration Tools and Utilities
+
+### 1. Migration Helper Functions
+
+```typescript
+// utils/migrationHelpers.ts
+export class MigrationHelpers {
+  // Check if migration is needed
+  static needsMigration(currentVersion: string, targetVersion: string): boolean {
+    const current = this.parseVersion(currentVersion);
+    const target = this.parseVersion(targetVersion);
+    
+    return current.major < target.major || 
+           (current.major === target.major && current.minor < target.minor);
+  }
+  
+  // Parse version string
+  static parseVersion(version: string) {
+    const [major, minor, patch] = version.split('.').map(Number);
+    return { major, minor, patch };
+  }
+  
+  // Migrate component props
+  static migrateComponentProps(oldProps: any, componentName: string) {
+    const migrations = {
+      Button: {
+        type: 'variant',
+        size: 'md',
+        loading: false,
+      },
+      DataTable: {
+        data: 'rows',
+        columns: 'columns',
+        pagination: 'enablePagination',
+      },
+      Form: {
+        onSubmit: 'onSubmit',
+        validation: 'schema',
+      },
+    };
+    
+    const migration = migrations[componentName];
+    if (!migration) return oldProps;
+    
+    const newProps = { ...oldProps };
+    
+    Object.entries(migration).forEach(([oldKey, newKey]) => {
+      if (oldProps[oldKey] !== undefined) {
+        newProps[newKey] = oldProps[oldKey];
+        delete newProps[oldKey];
+      }
+    });
+    
+    return newProps;
+  }
+  
+  // Migrate permission format
+  static migratePermissionFormat(permission: string): string {
+    return permission.replace('_', ':');
+  }
+  
+  // Migrate user data
+  static migrateUserData(user: any) {
+    return {
+      ...user,
+      permissions: user.permissions?.map(this.migratePermissionFormat) || [],
+      role: user.role || 'user',
+      organisation_id: user.organisation_id || 'default',
+    };
+  }
+  
+  // Generate migration report
+  static generateMigrationReport(changes: any[]) {
+    return {
+      timestamp: new Date().toISOString(),
+      changes,
+      summary: {
+        total: changes.length,
+        breaking: changes.filter(c => c.breaking).length,
+        nonBreaking: changes.filter(c => !c.breaking).length,
+      },
+    };
+  }
+}
+```
+
+### 2. Migration Validation
+
+```typescript
+// utils/migrationValidation.ts
+export class MigrationValidation {
+  // Validate component usage
+  static validateComponentUsage(componentName: string, props: any) {
+    const validations = {
+      Button: {
+        required: ['children'],
+        optional: ['variant', 'size', 'loading', 'disabled', 'onClick'],
+        deprecated: ['type'],
+      },
+      DataTable: {
+        required: ['data', 'columns'],
+        optional: ['pagination', 'sorting', 'filtering'],
+        deprecated: ['rows'],
+      },
+    };
+    
+    const validation = validations[componentName];
+    if (!validation) return { valid: true, warnings: [] };
+    
+    const warnings = [];
+    
+    // Check for deprecated props
+    validation.deprecated.forEach(prop => {
+      if (props[prop] !== undefined) {
+        warnings.push(`Prop '${prop}' is deprecated in ${componentName}`);
+      }
+    });
+    
+    // Check for missing required props
+    validation.required.forEach(prop => {
+      if (props[prop] === undefined) {
+        warnings.push(`Required prop '${prop}' is missing in ${componentName}`);
+      }
+    });
+    
+    return {
+      valid: warnings.length === 0,
+      warnings,
+    };
+  }
+  
+  // Validate hook usage
+  static validateHookUsage(hookName: string, args: any[]) {
+    const validations = {
+      useUnifiedAuth: {
+        args: 0,
+        description: 'No arguments required',
+      },
+      useRBAC: {
+        args: 0,
+        description: 'No arguments required',
+      },
+      useEvents: {
+        args: 0,
+        description: 'No arguments required',
+      },
+    };
+    
+    const validation = validations[hookName];
+    if (!validation) return { valid: true, warnings: [] };
+    
+    const warnings = [];
+    
+    if (args.length !== validation.args) {
+      warnings.push(`${hookName} expects ${validation.args} arguments, got ${args.length}`);
+    }
+    
+    return {
+      valid: warnings.length === 0,
+      warnings,
+    };
+  }
+  
+  // Validate configuration
+  static validateConfiguration(config: any) {
+    const required = [
+      'VITE_SUPABASE_URL',
+      'VITE_SUPABASE_ANON_KEY',
+    ];
+    
+    const warnings = [];
+    
+    required.forEach(key => {
+      if (!config[key]) {
+        warnings.push(`Required environment variable '${key}' is missing`);
+      }
+    });
+    
+    return {
+      valid: warnings.length === 0,
+      warnings,
+    };
+  }
+}
+```
+
+### 3. Migration Testing
+
+```typescript
+// utils/migrationTesting.ts
+export class MigrationTesting {
+  // Test component migration
+  static testComponentMigration(componentName: string, oldProps: any, newProps: any) {
+    const migratedProps = MigrationHelpers.migrateComponentProps(oldProps, componentName);
+    
+    const validation = MigrationValidation.validateComponentUsage(componentName, migratedProps);
+    
+    return {
+      success: validation.valid,
+      warnings: validation.warnings,
+      oldProps,
+      newProps: migratedProps,
+    };
+  }
+  
+  // Test hook migration
+  static testHookMigration(hookName: string, oldUsage: any, newUsage: any) {
+    const validation = MigrationValidation.validateHookUsage(hookName, newUsage.args);
+    
+    return {
+      success: validation.valid,
+      warnings: validation.warnings,
+      oldUsage,
+      newUsage,
+    };
+  }
+  
+  // Test data migration
+  static testDataMigration(oldData: any, newData: any) {
+    const migratedData = MigrationHelpers.migrateUserData(oldData);
+    
+    return {
+      success: JSON.stringify(migratedData) === JSON.stringify(newData),
+      oldData,
+      newData: migratedData,
+      differences: this.findDifferences(oldData, migratedData),
+    };
+  }
+  
+  // Find differences between objects
+  static findDifferences(obj1: any, obj2: any): Record<string, any> {
+    const differences: Record<string, any> = {};
+    
+    const allKeys = new Set([...Object.keys(obj1), ...Object.keys(obj2)]);
+    
+    allKeys.forEach(key => {
+      if (obj1[key] !== obj2[key]) {
+        differences[key] = {
+          old: obj1[key],
+          new: obj2[key],
+        };
+      }
+    });
+    
+    return differences;
+  }
+}
+```
+
+## Migration Best Practices
+
+### 1. Migration Checklist
+
+- [ ] Review breaking changes documentation
+- [ ] Create migration plan
+- [ ] Set up staging environment
+- [ ] Backup current data
+- [ ] Test migration in staging
+- [ ] Update dependencies
+- [ ] Migrate configuration
+- [ ] Update code for new APIs
+- [ ] Test all functionality
+- [ ] Deploy to production
+- [ ] Monitor for issues
+- [ ] Clean up old code
+
+### 2. Migration Strategy
+
+```typescript
+// Migration strategy implementation
+export class MigrationStrategy {
+  static async executeMigration(fromVersion: string, toVersion: string) {
+    console.log(`Starting migration from ${fromVersion} to ${toVersion}`);
+    
+    // 1. Pre-migration checks
+    const preChecks = await this.performPreChecks();
+    if (!preChecks.success) {
+      throw new Error(`Pre-migration checks failed: ${preChecks.errors.join(', ')}`);
+    }
+    
+    // 2. Backup current state
+    const backup = await this.createBackup();
+    console.log('Backup created:', backup.location);
+    
+    // 3. Update dependencies
+    await this.updateDependencies(toVersion);
+    
+    // 4. Migrate configuration
+    await this.migrateConfiguration();
+    
+    // 5. Migrate code
+    await this.migrateCode();
+    
+    // 6. Migrate data
+    await this.migrateData();
+    
+    // 7. Post-migration validation
+    const validation = await this.validateMigration();
+    if (!validation.success) {
+      console.error('Migration validation failed:', validation.errors);
+      await this.rollback(backup);
+      throw new Error('Migration failed validation');
+    }
+    
+    console.log('Migration completed successfully');
+    return { success: true, backup };
+  }
+  
+  static async performPreChecks() {
+    const checks = [
+      this.checkDependencies(),
+      this.checkConfiguration(),
+      this.checkDataIntegrity(),
+    ];
+    
+    const results = await Promise.all(checks);
+    const errors = results.flatMap(r => r.errors || []);
+    
+    return {
+      success: errors.length === 0,
+      errors,
+    };
+  }
+  
+  static async createBackup() {
+    // Implementation for creating backup
+    return {
+      location: '/backups/migration-backup-' + Date.now(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+  
+  static async rollback(backup: any) {
+    console.log('Rolling back to backup:', backup.location);
+    // Implementation for rollback
+  }
+}
+```
+
+### 3. Rollback Strategy
+
+```typescript
+// Rollback strategy implementation
+export class RollbackStrategy {
+  static async rollbackMigration(backup: any) {
+    console.log('Starting rollback process...');
+    
+    try {
+      // 1. Restore database
+      await this.restoreDatabase(backup.database);
+      
+      // 2. Restore configuration
+      await this.restoreConfiguration(backup.config);
+      
+      // 3. Restore code
+      await this.restoreCode(backup.code);
+      
+      // 4. Restore dependencies
+      await this.restoreDependencies(backup.dependencies);
+      
+      // 5. Validate rollback
+      const validation = await this.validateRollback();
+      
+      if (validation.success) {
+        console.log('Rollback completed successfully');
+        return { success: true };
+      } else {
+        throw new Error('Rollback validation failed');
+      }
+    } catch (error) {
+      console.error('Rollback failed:', error);
+      throw error;
+    }
+  }
+  
+  static async validateRollback() {
+    // Implementation for rollback validation
+    return { success: true };
+  }
+}
+```
+
+For more information about migrating your application, see the [Common Issues Guide](./common-issues.md) and [Debugging Guide](./debugging.md).