xenfra 0.4.3__py3-none-any.whl → 0.4.5__py3-none-any.whl

xenfra/blueprints/__init__.py

@@ -0,0 +1,55 @@
+"""
+Blueprint factory for framework detection and build plan generation.
+
+Implements Railpack-first routing with 3-tier dry-run validation:
+- Tier 1: Local validation (~100ms) - Syntax, imports, config
+- Tier 2: Railpack plan (~1-2s) - Build plan generation  
+- Tier 3: E2B Sandbox (~30-60s) - Full build validation via Xenfra API
+
+Tier 3 runs on Xenfra's servers - users don't need E2B installed.
+
+Environment Variables:
+- XENFRA_AI=off: Disable all AI features
+- XENFRA_SANDBOX=force: Always run Tier 3 validation
+- XENFRA_SANDBOX=skip: Skip Tier 3 validation  
+- XENFRA_SANDBOX=auto: Smart detection (default)
+"""
+
+from .base import Blueprint, BuildPlan
+from .factory import BlueprintFactory, get_factory, detect_project
+from .railpack import RailpackBlueprint
+from .dry_run import (
+    DryRunEngine,
+    DryRunResult,
+    run_dry_run,
+    quick_validate,
+)
+from .validation import ValidationResult, validate_project
+from .e2b import E2BSandbox, SandboxResult, get_sandbox
+
+__all__ = [
+    # Base classes
+    "Blueprint",
+    "BuildPlan",
+    
+    # Factory
+    "BlueprintFactory",
+    "get_factory",
+    "detect_project",
+    "RailpackBlueprint",
+    
+    # 3-Tier Dry Run
+    "DryRunEngine",
+    "DryRunResult",
+    "run_dry_run",
+    "quick_validate",
+    
+    # Tier 1
+    "ValidationResult",
+    "validate_project",
+    
+    # Tier 3
+    "E2BSandbox",
+    "SandboxResult",
+    "get_sandbox",
+]

xenfra/blueprints/base.py

@@ -0,0 +1,85 @@
+"""
+Base blueprint interface for build plan generation.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional
+from pathlib import Path
+
+
+@dataclass
+class BuildPlan:
+    """A build plan containing all information needed to build and deploy."""
+    
+    framework: str
+    language: str
+    package_manager: str
+    dependency_file: str
+    build_command: Optional[str] = None
+    start_command: Optional[str] = None
+    port: int = 8000
+    dockerfile: Optional[str] = None
+    env_vars: dict = field(default_factory=dict)
+    detected_from: str = "unknown"  # How the framework was detected
+    
+    def to_dict(self) -> dict:
+        """Convert build plan to dictionary."""
+        return {
+            "framework": self.framework,
+            "language": self.language,
+            "package_manager": self.package_manager,
+            "dependency_file": self.dependency_file,
+            "build_command": self.build_command,
+            "start_command": self.start_command,
+            "port": self.port,
+            "dockerfile": self.dockerfile,
+            "env_vars": self.env_vars,
+            "detected_from": self.detected_from,
+        }
+
+
+class Blueprint(ABC):
+    """
+    Abstract base class for deployment blueprints.
+    
+    Blueprints analyze project structure and generate build plans.
+    """
+    
+    name: str = "base"
+    languages: list[str] = []
+    
+    @abstractmethod
+    def detect(self, project_path: Path) -> bool:
+        """
+        Detect if this blueprint applies to the given project.
+        
+        Args:
+            project_path: Path to the project directory
+            
+        Returns:
+            True if this blueprint can handle the project
+        """
+        pass
+    
+    @abstractmethod
+    def generate_plan(self, project_path: Path) -> BuildPlan:
+        """
+        Generate a build plan for the project.
+        
+        Args:
+            project_path: Path to the project directory
+            
+        Returns:
+            BuildPlan with all build/deployment information
+        """
+        pass
+    
+    def get_priority(self) -> int:
+        """
+        Get the priority of this blueprint (higher = tried first).
+        
+        Returns:
+            Priority integer
+        """
+        return 100

xenfra/blueprints/cache.py

@@ -0,0 +1,286 @@
+"""
+Smart detection and caching for Tier 3 validation decisions.
+
+Tracks build state to determine when full sandbox validation is needed.
+"""
+
+import hashlib
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class BuildState:
+    """Cached state of a successful build."""
+    project_name: str
+    framework: str
+    language: str
+    dependency_hash: str
+    config_hash: str
+    build_plan_hash: str
+    status: str  # "success" or "failed"
+    timestamp: str
+    
+    def to_dict(self) -> dict:
+        return asdict(self)
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "BuildState":
+        return cls(**data)
+
+
+class BuildCache:
+    """
+    Manages build state cache for smart detection.
+    
+    Stores hashes of key files to detect changes that would
+    require re-validation in the sandbox.
+    """
+    
+    CACHE_DIR_NAME = ".xenfra"
+    CACHE_FILE_NAME = "build_state.json"
+    
+    def __init__(self, project_path: Path):
+        self.project_path = project_path
+        self.cache_dir = project_path / self.CACHE_DIR_NAME
+        self.cache_file = self.cache_dir / self.CACHE_FILE_NAME
+    
+    def get_cached_state(self) -> Optional[BuildState]:
+        """
+        Get the cached build state if it exists.
+        
+        Returns:
+            BuildState if cache exists, None otherwise
+        """
+        if not self.cache_file.exists():
+            return None
+        
+        try:
+            content = self.cache_file.read_text()
+            data = json.loads(content)
+            return BuildState.from_dict(data)
+        except (json.JSONDecodeError, KeyError, TypeError):
+            return None
+    
+    def save_state(self, state: BuildState):
+        """
+        Save the build state to cache.
+        
+        Args:
+            state: BuildState to cache
+        """
+        self.cache_dir.mkdir(exist_ok=True)
+        # Add to .gitignore if not already there
+        self._ensure_gitignore()
+        
+        self.cache_file.write_text(json.dumps(state.to_dict(), indent=2))
+    
+    def _ensure_gitignore(self):
+        """Ensure .xenfra is in .gitignore."""
+        gitignore = self.project_path / ".gitignore"
+        entry = ".xenfra/"
+        
+        if gitignore.exists():
+            content = gitignore.read_text()
+            if entry not in content:
+                with open(gitignore, "a") as f:
+                    f.write(f"\n{entry}\n")
+        else:
+            gitignore.write_text(f"{entry}\n")
+    
+    def compute_dependency_hash(self, plan: "BuildPlan") -> str:
+        """
+        Compute hash of dependency files.
+        
+        Args:
+            plan: BuildPlan with dependency information
+            
+        Returns:
+            Hash string of dependency files
+        """
+        hasher = hashlib.sha256()
+        
+        # Main dependency file
+        dep_file = self.project_path / plan.dependency_file
+        if dep_file.exists():
+            hasher.update(dep_file.read_bytes())
+        
+        # Lock files
+        lock_files = {
+            "python": ["poetry.lock", "uv.lock", "Pipfile.lock"],
+            "node": ["package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb"],
+            "go": ["go.sum"],
+            "rust": ["Cargo.lock"],
+            "ruby": ["Gemfile.lock"],
+        }
+        
+        for lock in lock_files.get(plan.language, []):
+            lock_path = self.project_path / lock
+            if lock_path.exists():
+                hasher.update(lock_path.read_bytes())
+        
+        return hasher.hexdigest()[:16]
+    
+    def compute_config_hash(self, plan: "BuildPlan") -> str:
+        """
+        Compute hash of configuration files.
+        
+        Args:
+            plan: BuildPlan with configuration information
+            
+        Returns:
+            Hash string of config files
+        """
+        hasher = hashlib.sha256()
+        
+        # xenfra.yaml
+        config_file = self.project_path / "xenfra.yaml"
+        if config_file.exists():
+            hasher.update(config_file.read_bytes())
+        
+        # Dockerfile
+        dockerfile = self.project_path / "Dockerfile"
+        if dockerfile.exists():
+            hasher.update(dockerfile.read_bytes())
+        
+        # Docker Compose
+        compose_files = ["docker-compose.yml", "docker-compose.yaml"]
+        for cf in compose_files:
+            cf_path = self.project_path / cf
+            if cf_path.exists():
+                hasher.update(cf_path.read_bytes())
+        
+        return hasher.hexdigest()[:16]
+    
+    def compute_build_plan_hash(self, plan: "BuildPlan") -> str:
+        """
+        Compute hash of the build plan itself.
+        
+        Args:
+            plan: BuildPlan to hash
+            
+        Returns:
+            Hash string of build plan
+        """
+        plan_dict = plan.to_dict()
+        plan_str = json.dumps(plan_dict, sort_keys=True)
+        return hashlib.sha256(plan_str.encode()).hexdigest()[:16]
+
+
+class SmartDetector:
+    """
+    Smart detection for Tier 3 (E2B) validation.
+    
+    Determines when full sandbox validation is needed based on
+    changes to dependencies, config, or previous build failures.
+    """
+    
+    def __init__(self, project_path: Path):
+        self.project_path = project_path
+        self.cache = BuildCache(project_path)
+    
+    def should_run_sandbox(
+        self, 
+        plan: "BuildPlan",
+        force: bool = False
+    ) -> tuple[bool, str]:
+        """
+        Determine if Tier 3 (E2B) validation should run.
+        
+        Args:
+            plan: BuildPlan for the project
+            force: If True, always run sandbox
+            
+        Returns:
+            Tuple of (should_run, reason)
+        """
+        if force:
+            return True, "Forced by --force flag"
+        
+        # Check for environment variable override
+        sandbox_mode = os.environ.get("XENFRA_SANDBOX", "auto").lower()
+        
+        if sandbox_mode == "force":
+            return True, "Forced by XENFRA_SANDBOX=force"
+        
+        if sandbox_mode == "skip":
+            return False, "Skipped by XENFRA_SANDBOX=skip"
+        
+        # Get cached state
+        cached = self.cache.get_cached_state()
+        if not cached:
+            return True, "First deployment - validation required"
+        
+        # Compute current hashes
+        current_dep_hash = self.cache.compute_dependency_hash(plan)
+        current_config_hash = self.cache.compute_config_hash(plan)
+        current_plan_hash = self.cache.compute_build_plan_hash(plan)
+        
+        # Check for failures
+        if cached.status == "failed":
+            return True, "Previous build failed - re-validation required"
+        
+        # Check for dependency changes
+        if current_dep_hash != cached.dependency_hash:
+            return True, "Dependencies changed - validation required"
+        
+        # Check for config changes
+        if current_config_hash != cached.config_hash:
+            return True, "Build configuration changed - validation required"
+        
+        # Check for framework changes
+        if plan.framework != cached.framework:
+            return True, "Framework changed - validation required"
+        
+        # Check for build plan changes
+        if current_plan_hash != cached.build_plan_hash:
+            return True, "Build plan changed - validation required"
+        
+        return False, "No significant changes - skipping sandbox"
+    
+    def record_success(self, plan: "BuildPlan"):
+        """
+        Record a successful build.
+        
+        Args:
+            plan: BuildPlan that succeeded
+        """
+        state = BuildState(
+            project_name=self.project_path.name,
+            framework=plan.framework,
+            language=plan.language,
+            dependency_hash=self.cache.compute_dependency_hash(plan),
+            config_hash=self.cache.compute_config_hash(plan),
+            build_plan_hash=self.cache.compute_build_plan_hash(plan),
+            status="success",
+            timestamp=datetime.utcnow().isoformat()
+        )
+        self.cache.save_state(state)
+    
+    def record_failure(self, plan: "BuildPlan"):
+        """
+        Record a failed build.
+        
+        Args:
+            plan: BuildPlan that failed
+        """
+        state = BuildState(
+            project_name=self.project_path.name,
+            framework=plan.framework,
+            language=plan.language,
+            dependency_hash=self.cache.compute_dependency_hash(plan),
+            config_hash=self.cache.compute_config_hash(plan),
+            build_plan_hash=self.cache.compute_build_plan_hash(plan),
+            status="failed",
+            timestamp=datetime.utcnow().isoformat()
+        )
+        self.cache.save_state(state)
+
+
+def get_detector(project_path: Path) -> SmartDetector:
+    """Get smart detector for a project."""
+    return SmartDetector(project_path)

xenfra/blueprints/dry_run.py

@@ -0,0 +1,251 @@
+"""
+3-Tier Dry Run System - "Dry Run First" Architecture
+
+Every deployment is validated through 3 tiers:
+- Tier 1: Local validation (~100ms) - Syntax, imports, config
+- Tier 2: Railpack plan (~1-2s) - Build plan generation
+- Tier 3: E2B Sandbox (~30-60s) - Full build validation (smart detection)
+
+This ensures deployments never fail due to avoidable errors.
+"""
+
+from pathlib import Path
+from typing import Optional
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .base import BuildPlan
+from .validation import validate_project, ValidationResult
+from .e2b import get_sandbox, SandboxResult
+from .cache import get_detector
+from .factory import get_factory
+
+
+class TierStatus(Enum):
+    """Status of a tier validation."""
+    PENDING = "pending"
+    RUNNING = "running"
+    PASSED = "passed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class DryRunResult:
+    """Complete result of dry-run validation."""
+    success: bool
+    tier1: ValidationResult
+    tier2: Optional[BuildPlan]
+    tier3: Optional[SandboxResult]
+    tier3_ran: bool
+    tier3_reason: str
+    errors: list[str] = field(default_factory=list)
+    
+    @property
+    def all_tiers_passed(self) -> bool:
+        """Check if all executed tiers passed."""
+        if not self.tier1.success:
+            return False
+        if self.tier2 is None:
+            return False
+        if self.tier3_ran and (self.tier3 is None or not self.tier3.success):
+            return False
+        return True
+    
+    def get_summary(self) -> str:
+        """Get human-readable summary."""
+        lines = ["Dry Run Results:", ""]
+        
+        # Tier 1
+        t1_status = "✅ PASSED" if self.tier1.success else "❌ FAILED"
+        lines.append(f"Tier 1 (Local): {t1_status}")
+        if self.tier1.errors:
+            for err in self.tier1.errors:
+                lines.append(f"  - {err}")
+        
+        # Tier 2
+        if self.tier2:
+            lines.append(f"Tier 2 (Railpack): ✅ PASSED - {self.tier2.framework}")
+        else:
+            lines.append("Tier 2 (Railpack): ❌ FAILED")
+        
+        # Tier 3
+        if self.tier3_ran:
+            if self.tier3 and self.tier3.success:
+                lines.append(f"Tier 3 (Sandbox): ✅ PASSED ({self.tier3.build_time_seconds:.1f}s)")
+            else:
+                lines.append("Tier 3 (Sandbox): ❌ FAILED")
+                if self.tier3 and self.tier3.error_message:
+                    lines.append(f"  - {self.tier3.error_message}")
+        else:
+            lines.append(f"Tier 3 (Sandbox): ⏭️ SKIPPED - {self.tier3_reason}")
+        
+        return "\n".join(lines)
+
+
+class DryRunEngine:
+    """
+    3-Tier Dry Run Engine.
+    
+    Validates deployments through increasingly thorough checks,
+    ensuring builds succeed before touching real infrastructure.
+    """
+    
+    def __init__(self, project_path: Path, api_client=None, file_manifest=None):
+        self.project_path = project_path
+        self.file_manifest = file_manifest
+        self.factory = get_factory()
+        self.sandbox = get_sandbox(api_client)
+        self.detector = get_detector(project_path)
+    
+    def run(
+        self,
+        force_sandbox: bool = False,
+        skip_sandbox: bool = False
+    ) -> DryRunResult:
+        """
+        Run full dry-run validation.
+        
+        Args:
+            force_sandbox: Always run Tier 3 even if not needed
+            skip_sandbox: Never run Tier 3 (for quick iteration)
+            
+        Returns:
+            DryRunResult with all tier results
+        """
+        errors = []
+        
+        # ========== TIER 1: Local Validation ==========
+        tier1_result = validate_project(self.project_path)
+        
+        if not tier1_result.success:
+            return DryRunResult(
+                success=False,
+                tier1=tier1_result,
+                tier2=None,
+                tier3=None,
+                tier3_ran=False,
+                tier3_reason="Skipped due to Tier 1 failures",
+                errors=tier1_result.errors
+            )
+        
+        # ========== TIER 2: Railpack Plan ==========
+        try:
+            tier2_plan = self.factory.get_build_plan(self.project_path)
+        except Exception as e:
+            errors.append(f"Railpack plan generation failed: {e}")
+            return DryRunResult(
+                success=False,
+                tier1=tier1_result,
+                tier2=None,
+                tier3=None,
+                tier3_ran=False,
+                tier3_reason="Skipped due to Tier 2 failure",
+                errors=errors
+            )
+        
+        # ========== TIER 3: E2B Sandbox ==========
+        tier3_result: Optional[SandboxResult] = None
+        tier3_ran = False
+        tier3_reason = ""
+        
+        if skip_sandbox:
+            tier3_reason = "Skipped by user (--skip-sandbox)"
+        else:
+            # Check if we should run sandbox
+            should_run, reason = self.detector.should_run_sandbox(
+                tier2_plan, 
+                force=force_sandbox
+            )
+            tier3_reason = reason
+            
+            if should_run and self.sandbox.is_available:
+                tier3_ran = True
+                tier3_result = self.sandbox.validate_build(
+                    self.project_path,
+                    tier2_plan,
+                    file_manifest=self.file_manifest or []
+                )
+                
+                # Record result for smart detection
+                if tier3_result.success:
+                    self.detector.record_success(tier2_plan)
+                else:
+                    self.detector.record_failure(tier2_plan)
+                    errors.append(
+                        tier3_result.error_message or "Sandbox build failed"
+                    )
+            elif should_run and not self.sandbox.is_available:
+                tier3_reason = "Sandbox unavailable (not authenticated)"
+            
+        # Determine overall success
+        success = (
+            tier1_result.success and
+            tier2_plan is not None and
+            (not tier3_ran or (tier3_result and tier3_result.success))
+        )
+        
+        return DryRunResult(
+            success=success,
+            tier1=tier1_result,
+            tier2=tier2_plan,
+            tier3=tier3_result,
+            tier3_ran=tier3_ran,
+            tier3_reason=tier3_reason,
+            errors=errors
+        )
+    
+    def quick_check(self) -> ValidationResult:
+        """
+        Run only Tier 1 validation for quick feedback.
+        
+        Returns:
+            ValidationResult from local validation
+        """
+        return validate_project(self.project_path)
+    
+    def generate_plan(self) -> BuildPlan:
+        """
+        Generate build plan (Tier 2).
+        
+        Returns:
+            BuildPlan from Railpack analysis
+        """
+        return self.factory.get_build_plan(self.project_path)
+
+
+def run_dry_run(
+    project_path: Path,
+    force_sandbox: bool = False,
+    skip_sandbox: bool = False,
+    api_client=None,
+    file_manifest: list = None
+) -> DryRunResult:
+    """
+    Convenience function to run dry-run validation.
+    
+    Args:
+        project_path: Path to project directory
+        force_sandbox: Always run sandbox
+        skip_sandbox: Skip sandbox validation
+        api_client: Xenfra API client for Tier 3 sandbox
+        file_manifest: List of file info dicts for the project
+        
+    Returns:
+        DryRunResult with full validation results
+    """
+    engine = DryRunEngine(project_path, api_client=api_client, file_manifest=file_manifest)
+    return engine.run(force_sandbox=force_sandbox, skip_sandbox=skip_sandbox)
+
+
+def quick_validate(project_path: Path) -> ValidationResult:
+    """
+    Quick validation (Tier 1 only).
+    
+    Args:
+        project_path: Path to project directory
+        
+    Returns:
+        ValidationResult
+    """
+    return validate_project(project_path)