@jmruthers/pace-core 0.5.191 → 0.6.1

package/cursor-rules/02-project-structure.mdc

@@ -0,0 +1,200 @@
+---
+description: Define standard folder structure and file organization for consuming apps
+globs: ["**/*.{ts,tsx,js,jsx,md}"]
+alwaysApply: true
+paceCoreVersion: "0.5.x"
+rulesVersion: "2025-01-15"
+---
+# Project Structure Standard
+
+This guide defines the standard folder structure and file organization for consuming apps in the PACE suite.
+
+## MUST: Follow Standard Directory Structure
+
+**Consuming apps MUST follow this structure:**
+
+```
+your-app/
+├── .cursor/
+│   └── rules/          # Cursor rules (pace-core rules + local rules)
+├── src/
+│   ├── components/     # App-specific components
+│   ├── hooks/          # App-specific hooks
+│   ├── services/       # App-specific services
+│   ├── pages/          # Page components
+│   ├── types/          # TypeScript type definitions
+│   ├── utils/          # App-specific utilities
+│   ├── App.tsx         # Main app component
+│   └── main.tsx        # Entry point
+├── supabase/
+│   ├── migrations/     # Database migrations
+│   └── functions/      # Edge functions (if used)
+├── public/             # Static assets
+├── tests/              # Integration/E2E tests (optional)
+├── audit/              # Audit reports (generated)
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── vitest.config.ts
+```
+
+## MUST: Organize Components by Feature
+
+**Components SHOULD be organized by feature/domain, not by type:**
+
+```
+src/
+├── components/
+│   ├── events/         # Event-related components
+│   │   ├── EventCard.tsx
+│   │   └── EventList.tsx
+│   ├── users/          # User-related components
+│   │   ├── UserProfile.tsx
+│   │   └── UserList.tsx
+│   └── shared/         # Shared app-specific components
+│       ├── Layout.tsx
+│       └── Navigation.tsx
+```
+
+**MUST NOT:**
+- Organize by component type (`buttons/`, `inputs/`, etc.) - use pace-core instead
+- Create duplicate components that pace-core provides
+
+## MUST: Colocate Tests
+
+**Tests MUST be colocated with source files:**
+
+```
+src/
+├── components/
+│   └── EventCard/
+│       ├── EventCard.tsx
+│       └── EventCard.test.tsx
+├── hooks/
+│   ├── useEventData.ts
+│   └── useEventData.test.ts
+└── utils/
+    ├── formatEvent.ts
+    └── formatEvent.test.ts
+```
+
+## MUST: Follow Naming Conventions
+
+### Files
+- Components: `PascalCase.tsx` (e.g., `EventCard.tsx`)
+- Hooks: `camelCase.ts` with `use` prefix (e.g., `useEventData.ts`)
+- Utilities: `camelCase.ts` (e.g., `formatEvent.ts`)
+- Types: `camelCase.ts` or `types.ts` (e.g., `eventTypes.ts`)
+- Tests: `*.test.ts` or `*.test.tsx`
+- Config: `kebab-case.config.js` (e.g., `vite.config.ts`)
+
+### Directories
+- Use `kebab-case` for directories (e.g., `event-management/`)
+- Match feature/domain names
+
+## MUST: Place Migrations Correctly
+
+**Database migrations MUST be in `supabase/migrations/`:**
+- Format: `YYYYMMDDHHMMSS_description.sql`
+- Example: `20250115143022_add_user_preferences.sql`
+
+## SHOULD: Organize by Domain
+
+**For larger apps, SHOULD organize by domain/feature:**
+
+```
+src/
+├── domains/
+│   ├── events/
+│   │   ├── components/
+│   │   ├── hooks/
+│   │   ├── services/
+│   │   └── types.ts
+│   └── users/
+│       ├── components/
+│       ├── hooks/
+│       ├── services/
+│       └── types.ts
+├── shared/              # Shared across domains
+│   ├── components/
+│   ├── hooks/
+│   └── utils/
+└── App.tsx
+```
+
+## MUST: Keep Root Directory Clean
+
+**Root directory SHOULD only contain:**
+- Configuration files (`package.json`, `tsconfig.json`, etc.)
+- Documentation (`README.md`, `CHANGELOG.md`)
+- Build outputs (`.gitignore` them)
+- `.cursor/` directory
+
+**MUST NOT:**
+- Place source files in root
+- Place test files in root
+- Place component files in root
+
+## MUST: Use Consistent Import Paths
+
+**MUST use consistent import patterns:**
+
+```tsx
+// ✅ CORRECT - Absolute imports from src
+import { EventCard } from '@/components/events/EventCard';
+import { useEventData } from '@/hooks/useEventData';
+import { formatEvent } from '@/utils/formatEvent';
+
+// ✅ CORRECT - pace-core imports
+import { Button, Card } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+// ❌ WRONG - Relative imports for distant files
+import { EventCard } from '../../../components/events/EventCard';
+```
+
+**Configure path aliases in `tsconfig.json`:**
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+## MUST: Separate App Code from pace-core
+
+**MUST NOT:**
+- Modify pace-core code directly
+- Create components that duplicate pace-core functionality
+- Import from pace-core source (use published package)
+
+**MUST:**
+- Use pace-core as a dependency
+- Import from `@jmruthers/pace-core`
+- Create app-specific components only when pace-core doesn't provide them
+
+## SHOULD: Document Structure Decisions
+
+**For non-standard structures, SHOULD document why:**
+- Add `STRUCTURE.md` or section in `README.md`
+- Explain deviations from standard
+- Justify custom organization
+
+## File Organization Checklist
+
+Before committing, verify:
+- [ ] Components organized by feature, not type
+- [ ] Tests colocated with source files
+- [ ] Naming conventions followed
+- [ ] Migrations in `supabase/migrations/`
+- [ ] Root directory clean
+- [ ] Import paths consistent
+- [ ] No pace-core code modifications
+- [ ] Structure documented if non-standard
+
+## Reference
+
+See `project-structure.mdc` in pace-core for detailed structure patterns.

package/cursor-rules/03-solid-principles.mdc

@@ -0,0 +1,341 @@
+---
+description: Enforce SOLID architecture principles in consuming apps
+globs: ["src/**/*.{ts,tsx}"]
+alwaysApply: true
+paceCoreVersion: "0.5.x"
+rulesVersion: "2025-01-15"
+---
+# SOLID Principles Guide
+
+This guide enforces SOLID architecture principles to ensure maintainable, extensible, and testable code.
+
+## Single Responsibility Principle (SRP)
+
+**A class or function SHOULD have only one reason to change.**
+
+### MUST: Single Responsibility
+
+**Each function/component SHOULD do one thing:**
+
+```tsx
+// ❌ WRONG - Multiple responsibilities
+function UserProfile({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null);
+  const [events, setEvents] = useState([]);
+  
+  useEffect(() => {
+    // Fetching user
+    fetchUser(userId).then(setUser);
+    // Fetching events
+    fetchEvents(userId).then(setEvents);
+    // Formatting data
+    const formatted = formatUserData(user);
+    // Rendering UI
+    return <div>...</div>;
+  }, [userId]);
+  
+  return <div>...</div>;
+}
+
+// ✅ CORRECT - Separated responsibilities
+function UserProfile({ userId }: { userId: string }) {
+  const user = useUser(userId);
+  const events = useUserEvents(userId);
+  
+  return (
+    <div>
+      <UserInfo user={user} />
+      <UserEvents events={events} />
+    </div>
+  );
+}
+```
+
+### MUST: Extract Complex Logic
+
+**Complex logic SHOULD be extracted into hooks, services, or utilities:**
+
+```tsx
+// ❌ WRONG - Business logic in component
+function EventList() {
+  const [events, setEvents] = useState([]);
+  const [filtered, setFiltered] = useState([]);
+  
+  useEffect(() => {
+    fetchEvents().then(setEvents);
+  }, []);
+  
+  useEffect(() => {
+    const filtered = events
+      .filter(e => e.status === 'active')
+      .sort((a, b) => a.date - b.date)
+      .map(e => ({ ...e, formattedDate: formatDate(e.date) }));
+    setFiltered(filtered);
+  }, [events]);
+  
+  return <div>{filtered.map(...)}</div>;
+}
+
+// ✅ CORRECT - Logic in hook
+function useFilteredEvents() {
+  const events = useEvents();
+  return useMemo(() => {
+    return events
+      .filter(e => e.status === 'active')
+      .sort((a, b) => a.date - b.date)
+      .map(e => ({ ...e, formattedDate: formatDate(e.date) }));
+  }, [events]);
+}
+
+function EventList() {
+  const filteredEvents = useFilteredEvents();
+  return <div>{filteredEvents.map(...)}</div>;
+}
+```
+
+## Open/Closed Principle (OCP)
+
+**Software entities SHOULD be open for extension but closed for modification.**
+
+### SHOULD: Use Composition Over Modification
+
+**Extend functionality through composition, not modification:**
+
+```tsx
+// ❌ WRONG - Modifying base component
+function BaseButton({ onClick, ...props }) {
+  return <button onClick={onClick} {...props} />;
+}
+
+function SpecialButton({ onClick, ...props }) {
+  // Modifying base behavior
+  const handleClick = (e) => {
+    trackEvent('button-click');
+    onClick?.(e);
+  };
+  return <BaseButton onClick={handleClick} {...props} />;
+}
+
+// ✅ CORRECT - Composition with pace-core
+import { Button } from '@jmruthers/pace-core';
+
+function SpecialButton({ onClick, ...props }) {
+  const handleClick = (e) => {
+    trackEvent('button-click');
+    onClick?.(e);
+  };
+  return <Button onClick={handleClick} {...props} />;
+}
+```
+
+### SHOULD: Use Configuration Over Code Changes
+
+**Extend behavior through configuration:**
+
+```tsx
+// ✅ CORRECT - Configurable behavior
+interface DataTableConfig {
+  columns: Column[];
+  features: FeatureConfig;
+  rbac: RBACConfig;
+}
+
+function MyDataTable({ config }: { config: DataTableConfig }) {
+  return <DataTable {...config} />;
+}
+```
+
+## Liskov Substitution Principle (LSP)
+
+**Subtypes MUST be substitutable for their base types.**
+
+### MUST: Maintain Interface Contracts
+
+**Derived components/hooks MUST maintain the same interface:**
+
+```tsx
+// ✅ CORRECT - Maintains interface
+interface BaseHook {
+  data: Data | null;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+function useBaseData(): BaseHook { ... }
+
+function useExtendedData(): BaseHook {
+  const base = useBaseData();
+  // Extends but maintains same interface
+  return {
+    ...base,
+    // Additional properties are optional
+  };
+}
+```
+
+## Interface Segregation Principle (ISP)
+
+**Clients SHOULD NOT depend on interfaces they don't use.**
+
+### MUST: Create Focused Interfaces
+
+**Interfaces SHOULD be small and focused:**
+
+```tsx
+// ❌ WRONG - Large interface
+interface UserService {
+  getUser(id: string): Promise<User>;
+  createUser(data: UserData): Promise<User>;
+  updateUser(id: string, data: Partial<User>): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+  getUserEvents(id: string): Promise<Event[]>;
+  getUserOrganisations(id: string): Promise<Organisation[]>;
+  // ... many more methods
+}
+
+// ✅ CORRECT - Segregated interfaces
+interface UserReader {
+  getUser(id: string): Promise<User>;
+  getUserEvents(id: string): Promise<Event[]>;
+}
+
+interface UserWriter {
+  createUser(data: UserData): Promise<User>;
+  updateUser(id: string, data: Partial<User>): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+}
+
+interface UserOrganisationService {
+  getUserOrganisations(id: string): Promise<Organisation[]>;
+}
+```
+
+### SHOULD: Use Specific Props
+
+**Component props SHOULD be specific, not generic:**
+
+```tsx
+// ❌ WRONG - Generic props object
+function UserCard({ user, config }: { user: User; config: any }) {
+  // ...
+}
+
+// ✅ CORRECT - Specific props
+interface UserCardProps {
+  user: User;
+  showEmail?: boolean;
+  showAvatar?: boolean;
+  onEdit?: (user: User) => void;
+}
+
+function UserCard({ user, showEmail, showAvatar, onEdit }: UserCardProps) {
+  // ...
+}
+```
+
+## Dependency Inversion Principle (DIP)
+
+**High-level modules SHOULD NOT depend on low-level modules. Both SHOULD depend on abstractions.**
+
+### MUST: Depend on Abstractions
+
+**Depend on interfaces/types, not concrete implementations:**
+
+```tsx
+// ❌ WRONG - Direct dependency on implementation
+function UserService() {
+  const supabase = useSecureSupabase();
+  
+  async function getUser(id: string) {
+    const { data } = await supabase
+      .from('users')
+      .select('*')
+      .eq('id', id)
+      .single();
+    return data;
+  }
+  
+  return { getUser };
+}
+
+// ✅ CORRECT - Abstracted interface
+interface UserRepository {
+  getUser(id: string): Promise<User | null>;
+}
+
+function createUserRepository(supabase: SupabaseClient): UserRepository {
+  return {
+    async getUser(id: string) {
+      const { data } = await supabase
+        .from('users')
+        .select('*')
+        .eq('id', id)
+        .single();
+      return data;
+    }
+  };
+}
+
+function useUserService() {
+  const supabase = useSecureSupabase();
+  const repository = useMemo(
+    () => createUserRepository(supabase),
+    [supabase]
+  );
+  
+  return {
+    getUser: repository.getUser,
+  };
+}
+```
+
+### SHOULD: Use Dependency Injection
+
+**Inject dependencies rather than creating them:**
+
+```tsx
+// ❌ WRONG - Hard-coded dependency
+function EventService() {
+  const api = new ApiClient('https://api.example.com');
+  // ...
+}
+
+// ✅ CORRECT - Injected dependency
+function EventService(api: ApiClient) {
+  // ...
+}
+
+// Or with React context
+function useEventService() {
+  const api = useApiClient(); // From context
+  return useMemo(() => new EventService(api), [api]);
+}
+```
+
+## SOLID Checklist
+
+Before committing code, verify:
+- [ ] Each function/component has single responsibility
+- [ ] Complex logic extracted to hooks/services
+- [ ] Extension through composition, not modification
+- [ ] Interfaces are focused and specific
+- [ ] Dependencies are abstracted
+- [ ] No god objects or bloated components
+- [ ] Code is testable and maintainable
+
+## Anti-Patterns to Avoid
+
+1. **God Objects** - Classes/components that do too much
+2. **Feature Envy** - Functions that use more of another object than their own
+3. **Data Clumps** - Groups of data that should be objects
+4. **Long Parameter Lists** - Use objects/interfaces instead
+5. **Divergent Change** - One class changed for multiple reasons
+6. **Shotgun Surgery** - One change requires many class modifications
+
+## Reference
+
+- Single Responsibility: Each module has one reason to change
+- Open/Closed: Open for extension, closed for modification
+- Liskov Substitution: Subtypes must be substitutable
+- Interface Segregation: Many specific interfaces, not one general
+- Dependency Inversion: Depend on abstractions, not concretions