@cubis/foundry 0.3.67 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/legacy-modernizer/references/refactoring-patterns.md

@@ -1,395 +0,0 @@
-# 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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/legacy-modernizer/references/strangler-fig-pattern.md

@@ -1,281 +0,0 @@
-# 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 |