@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/legacy-modernizer/references/refactoring-patterns.md

@@ -0,0 +1,395 @@
+# Refactoring Patterns
+
+## Branch by Abstraction
+
+Enables large refactorings to happen incrementally without breaking existing code.
+
+```python
+# Step 1: Create abstraction
+from abc import ABC, abstractmethod
+
+class PaymentProcessor(ABC):
+    @abstractmethod
+    async def process_payment(self, amount: float, card: str) -> str:
+        """Returns transaction_id"""
+        pass
+
+# Step 2: Implement for legacy code
+class LegacyPaymentProcessor(PaymentProcessor):
+    async def process_payment(self, amount: float, card: str) -> str:
+        # Wrap existing legacy function
+        return await asyncio.to_thread(
+            legacy_payment_system.charge_card, amount, card
+        )
+
+# Step 3: Implement new version
+class StripePaymentProcessor(PaymentProcessor):
+    def __init__(self, stripe_client):
+        self.stripe = stripe_client
+
+    async def process_payment(self, amount: float, card: str) -> str:
+        charge = await self.stripe.charges.create(
+            amount=int(amount * 100),
+            currency="usd",
+            source=card,
+        )
+        return charge.id
+
+# Step 4: Replace all call sites with abstraction
+class OrderService:
+    def __init__(self, payment_processor: PaymentProcessor):
+        self.payment = payment_processor
+
+    async def checkout(self, cart, card):
+        # Now works with either implementation
+        tx_id = await self.payment.process_payment(cart.total, card)
+        return await self.create_order(cart, tx_id)
+
+# Step 5: Switch implementation via dependency injection
+def get_payment_processor() -> PaymentProcessor:
+    if feature_flags.is_enabled("stripe_payments"):
+        return StripePaymentProcessor(stripe_client)
+    return LegacyPaymentProcessor()
+```
+
+## Extract Service Pattern
+
+```python
+# Before: Monolithic order processing
+class OrderController:
+    def create_order(self, user_id, items):
+        # Validation
+        if not items:
+            raise ValueError("Empty order")
+
+        # Calculate total
+        total = sum(item.price * item.quantity for item in items)
+
+        # Apply discounts
+        discount = self.calculate_discount(user_id, total)
+        final_total = total - discount
+
+        # Process payment
+        payment_id = self.charge_card(user_id, final_total)
+
+        # Create order
+        order = self.db.create_order(user_id, items, final_total)
+
+        # Send notifications
+        self.send_email(user_id, order.id)
+        self.send_sms(user_id, "Order confirmed")
+
+        # Update inventory
+        self.update_inventory(items)
+
+        return order
+
+# After: Extracted services
+class OrderService:
+    def __init__(
+        self,
+        pricing: PricingService,
+        payment: PaymentService,
+        notification: NotificationService,
+        inventory: InventoryService,
+    ):
+        self.pricing = pricing
+        self.payment = payment
+        self.notification = notification
+        self.inventory = inventory
+
+    async def create_order(self, user_id: int, items: list[OrderItem]):
+        # Each service has single responsibility
+        total = await self.pricing.calculate_total(items, user_id)
+        payment_id = await self.payment.process(user_id, total)
+
+        order = await self._save_order(user_id, items, total, payment_id)
+
+        # Background tasks for non-critical operations
+        background_tasks.add_task(self.notification.send_order_confirmation, order)
+        background_tasks.add_task(self.inventory.update_stock, items)
+
+        return order
+
+# Extracted pricing service
+class PricingService:
+    async def calculate_total(
+        self,
+        items: list[OrderItem],
+        user_id: int,
+    ) -> Decimal:
+        subtotal = sum(item.price * item.quantity for item in items)
+        discount = await self.get_user_discount(user_id, subtotal)
+        return subtotal - discount
+
+    async def get_user_discount(self, user_id: int, subtotal: Decimal) -> Decimal:
+        user = await self.user_repo.get(user_id)
+        if user.is_premium:
+            return subtotal * Decimal("0.1")  # 10% off
+        return Decimal("0")
+```
+
+## Adapter Pattern for Legacy Integration
+
+```python
+# Legacy system with incompatible interface
+class LegacyInventorySystem:
+    def GetItemCount(self, itemCode: str) -> int:
+        """Legacy method with different naming convention"""
+        pass
+
+    def DecrementStock(self, itemCode: str, qty: int) -> bool:
+        pass
+
+# Modern interface
+class InventoryRepository(ABC):
+    @abstractmethod
+    async def get_stock_level(self, sku: str) -> int:
+        pass
+
+    @abstractmethod
+    async def reduce_stock(self, sku: str, quantity: int) -> None:
+        pass
+
+# Adapter bridges the gap
+class LegacyInventoryAdapter(InventoryRepository):
+    def __init__(self, legacy_system: LegacyInventorySystem):
+        self.legacy = legacy_system
+
+    async def get_stock_level(self, sku: str) -> int:
+        # Translate modern call to legacy method
+        return await asyncio.to_thread(self.legacy.GetItemCount, sku)
+
+    async def reduce_stock(self, sku: str, quantity: int) -> None:
+        success = await asyncio.to_thread(
+            self.legacy.DecrementStock, sku, quantity
+        )
+        if not success:
+            raise StockError(f"Failed to reduce stock for {sku}")
+
+# Modern code uses consistent interface
+class OrderFulfillment:
+    def __init__(self, inventory: InventoryRepository):
+        self.inventory = inventory
+
+    async def fulfill_order(self, order):
+        for item in order.items:
+            stock = await self.inventory.get_stock_level(item.sku)
+            if stock >= item.quantity:
+                await self.inventory.reduce_stock(item.sku, item.quantity)
+```
+
+## Facade Pattern for Simplification
+
+```python
+# Complex legacy subsystems
+class LegacyAuthSystem:
+    def authenticate_user(self, username, password): pass
+    def check_permissions(self, user_id, resource): pass
+    def get_user_roles(self, user_id): pass
+
+class LegacySessionManager:
+    def create_session(self, user_id): pass
+    def validate_session(self, session_id): pass
+
+class LegacyAuditLogger:
+    def log_login(self, user_id, ip_address): pass
+
+# Facade provides simple interface
+class AuthFacade:
+    """Simplified authentication interface wrapping legacy systems"""
+
+    def __init__(
+        self,
+        auth: LegacyAuthSystem,
+        sessions: LegacySessionManager,
+        audit: LegacyAuditLogger,
+    ):
+        self.auth = auth
+        self.sessions = sessions
+        self.audit = audit
+
+    async def login(
+        self,
+        username: str,
+        password: str,
+        ip_address: str,
+    ) -> str | None:
+        """One method instead of coordinating three systems"""
+        # Coordinate legacy systems
+        user = await asyncio.to_thread(
+            self.auth.authenticate_user, username, password
+        )
+        if not user:
+            return None
+
+        session_id = await asyncio.to_thread(
+            self.sessions.create_session, user.id
+        )
+
+        await asyncio.to_thread(
+            self.audit.log_login, user.id, ip_address
+        )
+
+        return session_id
+
+    async def check_access(self, session_id: str, resource: str) -> bool:
+        """Simplified permission check"""
+        session = await asyncio.to_thread(
+            self.sessions.validate_session, session_id
+        )
+        if not session:
+            return False
+
+        return await asyncio.to_thread(
+            self.auth.check_permissions, session.user_id, resource
+        )
+
+# Client code is much simpler
+@app.post("/login")
+async def login(credentials: LoginRequest):
+    session_id = await auth_facade.login(
+        credentials.username,
+        credentials.password,
+        request.client.host,
+    )
+    if session_id:
+        return {"session_id": session_id}
+    raise HTTPException(401, "Invalid credentials")
+```
+
+## Replace Algorithm Pattern
+
+```python
+# Legacy algorithm with poor performance
+def legacy_search_products(query: str, products: list) -> list:
+    """O(n) linear search through all products"""
+    results = []
+    for product in products:
+        if query.lower() in product.name.lower():
+            results.append(product)
+        elif query.lower() in product.description.lower():
+            results.append(product)
+    return results
+
+# Step 1: Extract algorithm to its own class
+class ProductSearchStrategy(ABC):
+    @abstractmethod
+    def search(self, query: str) -> list[Product]:
+        pass
+
+class LegacyProductSearch(ProductSearchStrategy):
+    def __init__(self, products: list):
+        self.products = products
+
+    def search(self, query: str) -> list[Product]:
+        return legacy_search_products(query, self.products)
+
+# Step 2: Implement improved algorithm
+class ElasticsearchProductSearch(ProductSearchStrategy):
+    def __init__(self, es_client):
+        self.es = es_client
+
+    async def search(self, query: str) -> list[Product]:
+        response = await self.es.search(
+            index="products",
+            body={
+                "query": {
+                    "multi_match": {
+                        "query": query,
+                        "fields": ["name^2", "description"],
+                        "fuzziness": "AUTO",
+                    }
+                }
+            },
+        )
+        return [Product.from_es(hit) for hit in response["hits"]["hits"]]
+
+# Step 3: Use strategy pattern for gradual rollout
+class ProductService:
+    def __init__(self, search_strategy: ProductSearchStrategy):
+        self.search = search_strategy
+
+    async def find_products(self, query: str) -> list[Product]:
+        return await self.search.search(query)
+
+# Dependency injection controls which algorithm is used
+def get_search_strategy() -> ProductSearchStrategy:
+    if feature_flags.is_enabled("elasticsearch_search"):
+        return ElasticsearchProductSearch(es_client)
+    return LegacyProductSearch(product_cache)
+```
+
+## Introduce Repository Pattern
+
+```python
+# Legacy data access scattered throughout code
+class OrderController:
+    def get_order(self, order_id):
+        # Direct SQL in controller
+        result = db.execute("SELECT * FROM orders WHERE id = ?", order_id)
+        return result.fetchone()
+
+# Step 1: Create repository interface
+class OrderRepository(ABC):
+    @abstractmethod
+    async def get_by_id(self, order_id: int) -> Order | None:
+        pass
+
+    @abstractmethod
+    async def create(self, order: Order) -> Order:
+        pass
+
+    @abstractmethod
+    async def update(self, order: Order) -> Order:
+        pass
+
+# Step 2: Implement for legacy database
+class LegacyOrderRepository(OrderRepository):
+    def __init__(self, db_connection):
+        self.db = db_connection
+
+    async def get_by_id(self, order_id: int) -> Order | None:
+        result = await asyncio.to_thread(
+            self.db.execute,
+            "SELECT * FROM orders WHERE id = ?",
+            order_id,
+        )
+        row = result.fetchone()
+        return Order.from_legacy_row(row) if row else None
+
+# Step 3: Implement modern version
+class SQLAlchemyOrderRepository(OrderRepository):
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def get_by_id(self, order_id: int) -> Order | None:
+        return await self.db.get(Order, order_id)
+
+    async def create(self, order: Order) -> Order:
+        self.db.add(order)
+        await self.db.flush()
+        return order
+
+# Controllers now use repository
+class OrderController:
+    def __init__(self, order_repo: OrderRepository):
+        self.orders = order_repo
+
+    async def get_order(self, order_id: int):
+        order = await self.orders.get_by_id(order_id)
+        if not order:
+            raise HTTPException(404)
+        return order
+```
+
+## Quick Reference
+
+| Pattern | Use When | Benefit |
+|---------|----------|---------|
+| Branch by Abstraction | Large refactoring needed | Incremental migration |
+| Extract Service | Class doing too much | Single responsibility |
+| Adapter | Legacy interface incompatible | Bridge old and new |
+| Facade | Complex subsystem | Simplified interface |
+| Replace Algorithm | Performance/maintainability | Swap implementations |
+| Repository | Data access scattered | Centralized data logic |

package/Ai Agent Workflow/skills/legacy-modernizer/references/strangler-fig-pattern.md

@@ -0,0 +1,281 @@
+# Strangler Fig Pattern
+
+## Pattern Overview
+
+The strangler fig pattern gradually replaces legacy systems by incrementally building new functionality around the old system, eventually "strangling" it out of existence.
+
+```
+Legacy System → Facade/Router → New System
+     ↓              ↓               ↓
+  Old Code    Feature Flags    Modern Code
+     ↓              ↓               ↓
+  Phase 1:    Route 10%       Validate New
+  Phase 2:    Route 50%       Monitor Metrics
+  Phase 3:    Route 100%      Remove Legacy
+```
+
+## API Gateway Strangler
+
+```python
+# Facade layer routing requests to old/new systems
+from fastapi import FastAPI, Request
+from typing import Literal
+
+app = FastAPI()
+
+MIGRATION_CONFIG = {
+    "users.create": {"new_percentage": 100, "module": "new"},
+    "users.update": {"new_percentage": 50, "module": "new"},
+    "users.list": {"new_percentage": 10, "module": "new"},
+    "orders.create": {"new_percentage": 0, "module": "legacy"},
+}
+
+@app.post("/api/users")
+async def create_user(request: Request):
+    feature = "users.create"
+    config = MIGRATION_CONFIG.get(feature, {"new_percentage": 0})
+
+    # Feature flag + canary rollout
+    use_new = should_use_new_system(request, config["new_percentage"])
+
+    if use_new:
+        return await new_user_service.create(request)
+    else:
+        return await legacy_user_service.create(request)
+
+def should_use_new_system(request: Request, percentage: int) -> bool:
+    """Determine routing based on percentage + user attributes"""
+    if percentage == 0:
+        return False
+    if percentage == 100:
+        return True
+
+    # Canary: use user_id hash for consistent routing
+    user_id = request.headers.get("X-User-Id", "")
+    hash_val = hash(user_id) % 100
+    return hash_val < percentage
+```
+
+## Service Extraction with Adapter
+
+```python
+# Legacy monolith code
+class LegacyOrderService:
+    def create_order(self, user_id: int, items: list) -> dict:
+        # Complex legacy logic with database calls
+        order = {"id": 123, "user_id": user_id, "items": items}
+        self.db.execute("INSERT INTO orders ...")
+        return order
+
+# Step 1: Extract interface
+from abc import ABC, abstractmethod
+
+class OrderServiceInterface(ABC):
+    @abstractmethod
+    async def create_order(self, user_id: int, items: list) -> dict:
+        pass
+
+# Step 2: Adapter for legacy code
+class LegacyOrderAdapter(OrderServiceInterface):
+    def __init__(self, legacy_service: LegacyOrderService):
+        self.legacy = legacy_service
+
+    async def create_order(self, user_id: int, items: list) -> dict:
+        # Wrap synchronous legacy in async
+        return await asyncio.to_thread(
+            self.legacy.create_order, user_id, items
+        )
+
+# Step 3: New implementation
+class ModernOrderService(OrderServiceInterface):
+    def __init__(self, db: AsyncSession, event_bus: EventBus):
+        self.db = db
+        self.event_bus = event_bus
+
+    async def create_order(self, user_id: int, items: list) -> dict:
+        async with self.db.begin():
+            order = Order(user_id=user_id, items=items)
+            self.db.add(order)
+            await self.db.flush()
+
+            # Emit event for other services
+            await self.event_bus.publish(
+                "order.created", {"order_id": order.id}
+            )
+            return order.to_dict()
+
+# Step 4: Feature flag routing
+async def get_order_service(
+    request: Request,
+    db: AsyncSession,
+) -> OrderServiceInterface:
+    if feature_flags.is_enabled("modern_orders", request):
+        return ModernOrderService(db, event_bus)
+    else:
+        return LegacyOrderAdapter(legacy_order_service)
+```
+
+## Database Strangler Pattern
+
+```python
+# Dual-write to old and new databases during migration
+class DualWriteOrderRepository:
+    def __init__(
+        self,
+        legacy_db: Connection,
+        modern_db: AsyncSession,
+    ):
+        self.legacy_db = legacy_db
+        self.modern_db = modern_db
+
+    async def create(self, order_data: dict) -> Order:
+        # Write to new system (source of truth)
+        async with self.modern_db.begin():
+            order = Order(**order_data)
+            self.modern_db.add(order)
+            await self.modern_db.flush()
+            order_id = order.id
+
+        # Background sync to legacy (best effort)
+        try:
+            await self._sync_to_legacy(order_id, order_data)
+        except Exception as e:
+            # Log but don't fail - new DB is source of truth
+            logger.error(f"Legacy sync failed: {e}")
+
+        return order
+
+    async def get(self, order_id: int) -> Order | None:
+        # Read from new system
+        result = await self.modern_db.get(Order, order_id)
+        if result:
+            return result
+
+        # Fallback to legacy if not found (migration in progress)
+        legacy_data = await self._read_from_legacy(order_id)
+        if legacy_data:
+            # Lazy migration: move to new DB
+            return await self._migrate_order(legacy_data)
+
+        return None
+```
+
+## UI Component Strangler
+
+```typescript
+// React: Replace legacy jQuery components incrementally
+import { lazy, Suspense } from 'react';
+
+// Feature flag component wrapper
+function StranglerComponent({
+  feature,
+  legacySelector,
+  NewComponent,
+  ...props
+}) {
+  const useNew = useFeatureFlag(feature);
+
+  if (useNew) {
+    return (
+      <Suspense fallback={<Spinner />}>
+        <NewComponent {...props} />
+      </Suspense>
+    );
+  }
+
+  // Render legacy jQuery component
+  return <LegacyWrapper selector={legacySelector} />;
+}
+
+// Usage
+const ModernUserTable = lazy(() => import('./UserTable'));
+
+export function UserManagement() {
+  return (
+    <StranglerComponent
+      feature="modern-user-table"
+      legacySelector="#legacy-user-table"
+      NewComponent={ModernUserTable}
+      onUserClick={handleUserClick}
+    />
+  );
+}
+```
+
+## Event Interception
+
+```python
+# Intercept events from legacy system
+from typing import Callable
+import functools
+
+def intercept_legacy_event(event_name: str):
+    """Decorator to intercept and modernize legacy events"""
+    def decorator(handler: Callable):
+        @functools.wraps(handler)
+        async def wrapper(*args, **kwargs):
+            # Transform legacy event to modern format
+            modern_event = transform_legacy_event(event_name, args, kwargs)
+
+            # Emit to new event bus
+            await event_bus.publish(event_name, modern_event)
+
+            # Still call legacy handler (during transition)
+            return await handler(*args, **kwargs)
+        return wrapper
+    return decorator
+
+# Apply to legacy code
+@intercept_legacy_event("user.registered")
+async def legacy_user_registration_handler(user_data):
+    # Old code continues to work
+    send_welcome_email(user_data["email"])
+
+# New services can now subscribe to modernized events
+@event_bus.subscribe("user.registered")
+async def modern_analytics_handler(event):
+    await analytics.track_registration(event["user_id"])
+```
+
+## Migration Phases
+
+```python
+# Phase tracking and rollback
+class MigrationPhase:
+    def __init__(self, name: str, percentage: int, metrics: dict):
+        self.name = name
+        self.percentage = percentage
+        self.metrics = metrics
+
+    async def validate(self) -> bool:
+        """Check if phase is successful before proceeding"""
+        for metric, threshold in self.metrics.items():
+            current = await monitoring.get_metric(metric)
+            if current > threshold:
+                await self.rollback()
+                return False
+        return True
+
+    async def rollback(self):
+        """Instant rollback to previous phase"""
+        await feature_flags.set_percentage(self.name, self.percentage - 10)
+        await alerts.send(f"Rollback triggered for {self.name}")
+
+# Migration plan
+PHASES = [
+    MigrationPhase("orders_v2", 0, {}),  # Setup
+    MigrationPhase("orders_v2", 10, {"error_rate": 0.01}),  # Canary
+    MigrationPhase("orders_v2", 50, {"error_rate": 0.005}),  # Ramp
+    MigrationPhase("orders_v2", 100, {"error_rate": 0.001}),  # Full
+]
+```
+
+## Quick Reference
+
+| Stage | Actions | Validation |
+|-------|---------|------------|
+| Setup | Create facade, feature flags | Smoke tests pass |
+| Canary | Route 10% traffic | Error rate < 1% |
+| Ramp | Route 50% traffic | Performance parity |
+| Full | Route 100% traffic | All metrics green |
+| Cleanup | Remove legacy code | Legacy unused 30 days |