@el-j/magic-helix-plugins 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/patterns/architecture/repository-pattern.md

@@ -0,0 +1,408 @@
+# Repository Pattern
+
+## Purpose
+Abstract data access logic, providing a collection-like interface for domain objects. Decouples business logic from data persistence.
+
+## Core Concept
+
+**Repository = Collection of Domain Objects**
+
+Think of a repository as an in-memory collection (like a List or Set) that persists to a database.
+
+```typescript
+// ✅ Repository interface acts like a collection
+interface IProductRepository {
+  // Collection-like operations
+  getById(id: string): Promise<Product | null>;
+  getAll(): Promise<Product[]>;
+  add(product: Product): Promise<void>;
+  update(product: Product): Promise<void>;
+  remove(id: string): Promise<void>;
+  
+  // Domain-specific queries
+  findByCategory(category: string): Promise<Product[]>;
+  findInPriceRange(min: number, max: number): Promise<Product[]>;
+}
+```
+
+## Implementation
+
+### 1. Define Repository Interface (in domain/use case layer)
+
+```typescript
+// ✅ Interface lives in domain layer (no implementation details)
+export interface IUserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  findAll(filters?: UserFilters): Promise<User[]>;
+  save(user: User): Promise<void>;
+  delete(id: string): Promise<void>;
+  
+  // Domain-specific queries
+  findActiveUsers(): Promise<User[]>;
+  findUsersByRole(role: string): Promise<User[]>;
+}
+
+export interface UserFilters {
+  role?: string;
+  isActive?: boolean;
+  registeredAfter?: Date;
+}
+```
+
+### 2. Implement Repository (in infrastructure layer)
+
+```typescript
+// ✅ Implementation with actual database
+export class PostgresUserRepository implements IUserRepository {
+  constructor(private db: Database) {}
+
+  async findById(id: string): Promise<User | null> {
+    const row = await this.db.queryOne(
+      'SELECT * FROM users WHERE id = $1',
+      [id]
+    );
+    
+    return row ? this.toDomain(row) : null;
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    const row = await this.db.queryOne(
+      'SELECT * FROM users WHERE email = $1',
+      [email]
+    );
+    
+    return row ? this.toDomain(row) : null;
+  }
+
+  async save(user: User): Promise<void> {
+    // Handle both insert and update (upsert)
+    await this.db.query(
+      `INSERT INTO users (id, email, password, role, created_at)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (id) DO UPDATE SET
+         email = $2,
+         password = $3,
+         role = $4`,
+      [user.id, user.email, user.password, user.role, user.createdAt]
+    );
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.db.query('DELETE FROM users WHERE id = $1', [id]);
+  }
+
+  async findActiveUsers(): Promise<User[]> {
+    const rows = await this.db.query(
+      'SELECT * FROM users WHERE is_active = true ORDER BY created_at DESC'
+    );
+    
+    return rows.map(row => this.toDomain(row));
+  }
+
+  async findUsersByRole(role: string): Promise<User[]> {
+    const rows = await this.db.query(
+      'SELECT * FROM users WHERE role = $1',
+      [role]
+    );
+    
+    return rows.map(row => this.toDomain(row));
+  }
+
+  // Map database row to domain object
+  private toDomain(row: any): User {
+    return new User(
+      row.id,
+      row.email,
+      row.password,
+      row.role,
+      row.created_at,
+      row.is_active
+    );
+  }
+
+  // Map domain object to database row
+  private toRow(user: User): any {
+    return {
+      id: user.id,
+      email: user.email,
+      password: user.password,
+      role: user.role,
+      created_at: user.createdAt,
+      is_active: user.isActive,
+    };
+  }
+}
+```
+
+### 3. Use Repository in Service/Use Case
+
+```typescript
+// ✅ Service depends on interface, not implementation
+export class UserService {
+  constructor(private userRepository: IUserRepository) {}
+
+  async registerUser(email: string, password: string): Promise<User> {
+    // Check if user exists
+    const existing = await this.userRepository.findByEmail(email);
+    if (existing) {
+      throw new Error('User already exists');
+    }
+
+    // Create domain object
+    const user = User.create(email, password);
+
+    // Persist
+    await this.userRepository.save(user);
+
+    return user;
+  }
+
+  async getActiveAdmins(): Promise<User[]> {
+    const admins = await this.userRepository.findUsersByRole('admin');
+    return admins.filter(user => user.isActive);
+  }
+}
+```
+
+## Multiple Implementations
+
+### In-Memory Repository (for testing)
+
+```typescript
+// ✅ In-memory implementation for fast tests
+export class InMemoryUserRepository implements IUserRepository {
+  private users: Map<string, User> = new Map();
+
+  async findById(id: string): Promise<User | null> {
+    return this.users.get(id) || null;
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return Array.from(this.users.values())
+      .find(user => user.email === email) || null;
+  }
+
+  async save(user: User): Promise<void> {
+    this.users.set(user.id, user);
+  }
+
+  async delete(id: string): Promise<void> {
+    this.users.delete(id);
+  }
+
+  async findActiveUsers(): Promise<User[]> {
+    return Array.from(this.users.values())
+      .filter(user => user.isActive);
+  }
+
+  async findUsersByRole(role: string): Promise<User[]> {
+    return Array.from(this.users.values())
+      .filter(user => user.role === role);
+  }
+
+  // Test helper
+  clear(): void {
+    this.users.clear();
+  }
+}
+```
+
+### Redis Repository (for caching)
+
+```typescript
+// ✅ Redis implementation for caching layer
+export class RedisUserRepository implements IUserRepository {
+  constructor(
+    private redis: Redis,
+    private fallbackRepo: IUserRepository // Delegate to DB if cache miss
+  ) {}
+
+  async findById(id: string): Promise<User | null> {
+    // Try cache first
+    const cached = await this.redis.get(`user:${id}`);
+    if (cached) {
+      return JSON.parse(cached);
+    }
+
+    // Fall back to database
+    const user = await this.fallbackRepo.findById(id);
+    if (user) {
+      await this.redis.setex(`user:${id}`, 3600, JSON.stringify(user));
+    }
+
+    return user;
+  }
+
+  async save(user: User): Promise<void> {
+    // Save to database
+    await this.fallbackRepo.save(user);
+
+    // Update cache
+    await this.redis.setex(`user:${user.id}`, 3600, JSON.stringify(user));
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.fallbackRepo.delete(id);
+    await this.redis.del(`user:${id}`);
+  }
+
+  // Other methods...
+}
+```
+
+## Specification Pattern (Advanced)
+
+For complex queries, use specification pattern:
+
+```typescript
+// ✅ Specification for complex filtering
+export interface Specification<T> {
+  isSatisfiedBy(item: T): boolean;
+  toSql(): { where: string; params: any[] }; // Optional for DB queries
+}
+
+export class ActiveUserSpec implements Specification<User> {
+  isSatisfiedBy(user: User): boolean {
+    return user.isActive;
+  }
+
+  toSql() {
+    return { where: 'is_active = true', params: [] };
+  }
+}
+
+export class RoleSpec implements Specification<User> {
+  constructor(private role: string) {}
+
+  isSatisfiedBy(user: User): boolean {
+    return user.role === this.role;
+  }
+
+  toSql() {
+    return { where: 'role = $1', params: [this.role] };
+  }
+}
+
+// ✅ Combine specifications
+export class AndSpec<T> implements Specification<T> {
+  constructor(private specs: Specification<T>[]) {}
+
+  isSatisfiedBy(item: T): boolean {
+    return this.specs.every(spec => spec.isSatisfiedBy(item));
+  }
+
+  toSql() {
+    const sqlParts = this.specs.map(s => s.toSql());
+    const where = sqlParts.map((s, i) => `(${s.where})`).join(' AND ');
+    const params = sqlParts.flatMap(s => s.params);
+    return { where, params };
+  }
+}
+
+// ✅ Repository accepts specifications
+interface IUserRepository {
+  find(spec: Specification<User>): Promise<User[]>;
+}
+
+// Usage
+const activeAdmins = await userRepo.find(
+  new AndSpec([
+    new ActiveUserSpec(),
+    new RoleSpec('admin')
+  ])
+);
+```
+
+## Testing Strategy
+
+```typescript
+// ✅ Test service with in-memory repository
+describe('UserService', () => {
+  let service: UserService;
+  let repo: InMemoryUserRepository;
+
+  beforeEach(() => {
+    repo = new InMemoryUserRepository();
+    service = new UserService(repo);
+  });
+
+  it('registers new user', async () => {
+    const user = await service.registerUser('test@example.com', 'password');
+    
+    expect(user.email).toBe('test@example.com');
+    
+    // Verify persisted
+    const found = await repo.findById(user.id);
+    expect(found).toBeTruthy();
+  });
+
+  it('throws if user already exists', async () => {
+    await service.registerUser('test@example.com', 'password');
+    
+    await expect(
+      service.registerUser('test@example.com', 'password')
+    ).rejects.toThrow('User already exists');
+  });
+});
+
+// ✅ Test repository with real database (integration test)
+describe('PostgresUserRepository', () => {
+  let repo: PostgresUserRepository;
+  let db: Database;
+
+  beforeEach(async () => {
+    db = await createTestDatabase();
+    repo = new PostgresUserRepository(db);
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  it('saves and retrieves user', async () => {
+    const user = new User('1', 'test@example.com', 'hash', 'user');
+    
+    await repo.save(user);
+    const found = await repo.findById('1');
+    
+    expect(found?.email).toBe('test@example.com');
+  });
+});
+```
+
+## File Organization
+
+```
+src/
+├── domain/
+│   ├── models/
+│   │   └── User.ts
+│   └── repositories/           # Interfaces only
+│       ├── IUserRepository.ts
+│       └── IOrderRepository.ts
+│
+├── application/
+│   └── services/
+│       └── UserService.ts      # Uses IUserRepository
+│
+└── infrastructure/
+    └── repositories/           # Implementations
+        ├── PostgresUserRepository.ts
+        ├── InMemoryUserRepository.ts
+        └── RedisUserRepository.ts
+```
+
+## Rules Summary
+
+- **ALWAYS** define repository interfaces in domain layer
+- **ALWAYS** implement repositories in infrastructure layer
+- **ALWAYS** use collection-like method names (add, remove, getById)
+- **ALWAYS** return domain objects, not database rows
+- **ALWAYS** make repositories responsible for data mapping only
+- **NEVER** put business logic in repositories
+- **NEVER** return database-specific types (like ORM entities)
+- **PREFER** one repository per aggregate root
+- **PREFER** repository methods that work with domain objects, not primitive types
+- **CONSIDER** using in-memory implementation for testing
+- **CONSIDER** specification pattern for complex queries

package/dist/patterns/domain-expertise/nextjs-rules.md

@@ -0,0 +1,115 @@
+# Next.js Rules Pattern
+
+## Purpose
+Enforce Next.js-specific best practices and constraints. From **v0** pattern.
+
+## Template
+
+```markdown
+## Next.js {VERSION} Guidelines
+
+### App Router (Next.js 13+)
+- {RULE_ABOUT_SERVER_COMPONENTS}
+- {RULE_ABOUT_CLIENT_COMPONENTS}
+- {RULE_ABOUT_FILE_CONVENTIONS}
+- {RULE_ABOUT_ROUTING}
+
+### Data Fetching
+- {RULE_ABOUT_ASYNC_COMPONENTS}
+- {RULE_ABOUT_CACHING}
+- {RULE_ABOUT_REVALIDATION}
+
+### Performance
+- {RULE_ABOUT_IMAGES}
+- {RULE_ABOUT_FONTS}
+- {RULE_ABOUT_BUNDLING}
+```
+
+## Examples
+
+### v0 (Next.js 14 App Router)
+```markdown
+## Next.js 14 App Router Guidelines
+
+### Server vs Client Components
+- **Default to Server Components**: All components in app/ are Server Components unless marked with 'use client'
+- **Use 'use client' only when**:
+  - Component uses React hooks (useState, useEffect, useContext)
+  - Component uses browser APIs (window, document, localStorage)
+  - Component needs event handlers (onClick, onSubmit, etc.)
+  - Component uses third-party libraries that depend on browser features
+
+**Example**:
+```typescript
+// ✅ Server Component (default) - good for static content
+export default function ProductList({ products }: Props) {
+  return <div>{products.map(p => <ProductCard key={p.id} {...p} />)}</div>;
+}
+
+// ✅ Client Component - needed for interactivity
+'use client';
+export default function SearchBar() {
+  const [query, setQuery] = useState('');
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+```
+
+### File Conventions
+- **page.tsx**: Route segment UI (exported as default)
+- **layout.tsx**: Shared UI across route segments
+- **loading.tsx**: Loading UI (Suspense boundary)
+- **error.tsx**: Error UI (Error boundary)
+- **not-found.tsx**: 404 UI
+- **route.ts**: API endpoint (GET, POST, etc.)
+
+**Route Groups**: Use (folder) to organize without affecting URL structure
+
+### Data Fetching
+- **Async Server Components**: Fetch data directly in component
+  ```typescript
+  export default async function Page() {
+    const data = await fetch('https://api.example.com/data').then(r => r.json());
+    return <div>{data.title}</div>;
+  }
+  ```
+- **Caching**: Fetch requests are automatically cached
+- **Revalidation**: Use `revalidate` or `revalidatePath` for on-demand updates
+
+### Performance
+- **Image Optimization**: Always use `next/image` component
+  ```typescript
+  import Image from 'next/image';
+  <Image src="/photo.jpg" width={500} height={300} alt="Photo" />
+  ```
+- **Font Optimization**: Use `next/font` for self-hosted fonts
+  ```typescript
+  import { Inter } from 'next/font/google';
+  const inter = Inter({ subsets: ['latin'] });
+  ```
+- **Dynamic Imports**: Code-split heavy components
+  ```typescript
+  const HeavyComponent = dynamic(() => import('./HeavyComponent'), { ssr: false });
+  ```
+
+### Metadata
+- Export `metadata` object or `generateMetadata` function for SEO
+  ```typescript
+  export const metadata = {
+    title: 'Page Title',
+    description: 'Page description',
+  };
+  ```
+```
+
+## Variables
+- `{VERSION}`: Next.js version (13, 14, 15)
+- `{RULE_ABOUT_X}`: Specific guideline for feature X
+
+## Best Practices
+1. Specify Next.js version (APIs change between versions)
+2. Distinguish Pages Router vs App Router
+3. Highlight breaking changes from previous versions
+4. Show code examples (good ✅ vs bad ❌)
+5. Link to official docs for deep dives
+6. Update when new Next.js versions release
+7. Benefits: Version-appropriate code, avoids deprecated patterns, follows framework conventions

package/dist/patterns/domain-expertise/react-patterns.md

@@ -0,0 +1,181 @@
+# React Patterns Pattern
+
+## Purpose
+Enforce React best practices and common patterns. From **v0** and **same.new**.
+
+## Template
+
+```markdown
+## React Best Practices
+
+### Component Structure
+- {RULE_ABOUT_FUNCTIONAL_VS_CLASS}
+- {RULE_ABOUT_HOOKS_USAGE}
+- {RULE_ABOUT_COMPOSITION}
+
+### State Management
+- {RULE_ABOUT_LOCAL_STATE}
+- {RULE_ABOUT_PROP_DRILLING}
+- {RULE_ABOUT_CONTEXT}
+
+### Performance
+- {RULE_ABOUT_MEMOIZATION}
+- {RULE_ABOUT_KEYS}
+- {RULE_ABOUT_EFFECTS}
+```
+
+## Examples
+
+### v0 (React 18+ Patterns)
+```markdown
+## React 18+ Best Practices
+
+### Component Structure
+- **Use Functional Components**: No class components (deprecated pattern)
+  ```typescript
+  // ✅ Functional component with TypeScript
+  interface ButtonProps {
+    label: string;
+    onClick: () => void;
+  }
+  
+  export const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
+    return <button onClick={onClick}>{label}</button>;
+  };
+  
+  // ❌ Class component (outdated)
+  class Button extends React.Component { /* ... */ }
+  ```
+
+- **Extract Custom Hooks**: Reuse stateful logic
+  ```typescript
+  // ✅ Custom hook for form state
+  function useFormField(initialValue: string) {
+    const [value, setValue] = useState(initialValue);
+    const [error, setError] = useState<string | null>(null);
+    
+    const validate = () => {
+      if (!value) setError('Required');
+      else setError(null);
+    };
+    
+    return { value, setValue, error, validate };
+  }
+  
+  // Usage in component
+  function SignupForm() {
+    const email = useFormField('');
+    const password = useFormField('');
+    // ...
+  }
+  ```
+
+- **Prefer Composition over Inheritance**
+  ```typescript
+  // ✅ Composition with children prop
+  function Card({ children }: { children: React.ReactNode }) {
+    return <div className="card">{children}</div>;
+  }
+  
+  function ProductCard() {
+    return (
+      <Card>
+        <h2>Product Name</h2>
+        <p>Description</p>
+      </Card>
+    );
+  }
+  ```
+
+### State Management
+- **Start with Local State**: Use useState for component-specific state
+- **Lift State Up**: Move state to common parent when multiple children need it
+- **Use Context for Global State**: Avoid prop drilling for deeply nested components
+  ```typescript
+  // ✅ Context for theme (accessed by many components)
+  const ThemeContext = createContext<'light' | 'dark'>('light');
+  
+  function ThemeProvider({ children }: { children: React.ReactNode }) {
+    const [theme, setTheme] = useState<'light' | 'dark'>('light');
+    return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+  }
+  ```
+
+- **Consider Zustand/Jotai**: For complex client-side state (alternative to Redux)
+
+### Performance
+- **Memoize Expensive Calculations**: Use useMemo
+  ```typescript
+  const sortedItems = useMemo(() => 
+    items.sort((a, b) => a.price - b.price),
+    [items]
+  );
+  ```
+
+- **Memoize Callbacks**: Use useCallback for props passed to children
+  ```typescript
+  const handleClick = useCallback(() => {
+    console.log('Clicked');
+  }, []); // Empty deps = never recreated
+  ```
+
+- **Always Provide Keys**: For lists (use stable IDs, not indexes)
+  ```typescript
+  // ✅ Stable unique key
+  {products.map(p => <ProductCard key={p.id} {...p} />)}
+  
+  // ❌ Index as key (causes bugs when list changes)
+  {products.map((p, i) => <ProductCard key={i} {...p} />)}
+  ```
+
+- **Avoid Side Effects in Render**: Use useEffect for side effects
+  ```typescript
+  // ❌ Side effect in render (runs every render)
+  function Component() {
+    document.title = 'New Title'; // Bad!
+    return <div>Content</div>;
+  }
+  
+  // ✅ Side effect in useEffect (runs only when needed)
+  function Component() {
+    useEffect(() => {
+      document.title = 'New Title';
+    }, []);
+    return <div>Content</div>;
+  }
+  ```
+
+### TypeScript Integration
+- **Define Prop Interfaces**: Explicit types for all components
+- **Use React.FC sparingly**: Prefer explicit return types
+  ```typescript
+  // ✅ Explicit props and return type
+  interface Props {
+    name: string;
+    age: number;
+  }
+  
+  function UserCard({ name, age }: Props): JSX.Element {
+    return <div>{name}, {age}</div>;
+  }
+  ```
+
+- **Type Event Handlers**: Use React's event types
+  ```typescript
+  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    console.log(e.target.value);
+  }
+  ```
+```
+
+## Variables
+- `{RULE_ABOUT_X}`: Specific React guideline
+
+## Best Practices
+1. Cover React fundamentals (components, hooks, effects)
+2. Show TypeScript integration examples
+3. Include good/bad code comparisons
+4. Address common mistakes (useEffect dependencies, key props)
+5. Mention state management options (Context, Zustand, Redux)
+6. Update for React version features (18+: Suspense, Concurrent Rendering)
+7. Benefits: Consistent React patterns, avoids common pitfalls, TypeScript-safe code