xenfra-sdk 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

xenfra_sdk/__init__.py

@@ -1,16 +1,23 @@
 # This file makes src/xenfra_sdk a Python package.
 
 from .client import XenfraClient
-from .exceptions import AuthenticationError, XenfraAPIError, XenfraError
+from .engine import InfraEngine
+from .events import BuildEvent, DeploymentPhase, EventEmitter, EventStatus
+from .exceptions import AuthenticationError, DeploymentError, XenfraAPIError, XenfraError
+from .protocol import ProtocolRegistry
 from .models import (
+    BalanceRead,
     CodebaseAnalysisResponse,
     DiagnosisResponse,
+    DropletCostRead,
     PatchObject,
     ProjectRead,
 )
 
-# Microservices support
+# Microservices & Config support
 from .manifest import (
+    XenfraConfig,
+    load_xenfra_config,
     ServiceDefinition,
     load_services_from_xenfra_yaml,
     is_microservices_project,
@@ -37,6 +44,22 @@ from .security_scanner import (
     Severity,
 )
 
+# Railpack Integration
+from .railpack_detector import (
+    RailpackDetector,
+    RailpackDetectionResult,
+    EnvVariable,
+    get_railpack_detector,
+)
+from .railpack_manager import (
+    RailpackManager,
+    get_railpack_manager,
+)
+from .railpack_adapter import (
+    RailpackAdapter,
+    RailpackPlan,
+)
+
 __all__ = [
     "XenfraClient",
     "XenfraError",
@@ -46,6 +69,11 @@ __all__ = [
     "CodebaseAnalysisResponse",
     "PatchObject",
     "ProjectRead",
+    "BalanceRead",
+    "DropletCostRead",
+    # Config
+    "XenfraConfig",
+    "load_xenfra_config",
     # Microservices
     "ServiceDefinition",
     "load_services_from_xenfra_yaml",
@@ -58,4 +86,20 @@ __all__ = [
     "detect_pyproject_services",
     "ServiceOrchestrator",
     "get_orchestrator_for_project",
+    "InfraEngine",
+    "DeploymentError",
+    "ProtocolRegistry",
+    "EventEmitter",
+    "BuildEvent",
+    "DeploymentPhase",
+    "EventStatus",
+    # Railpack Integration
+    "RailpackDetector",
+    "RailpackDetectionResult",
+    "EnvVariable",
+    "get_railpack_detector",
+    "RailpackManager",
+    "get_railpack_manager",
+    "RailpackAdapter",
+    "RailpackPlan",
 ]

xenfra_sdk/blueprints/base.py

@@ -0,0 +1,150 @@
+import yaml
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+from pathlib import Path
+
+from xenfra_sdk.blueprints.schema import (
+    DeploymentBlueprintManifest, DockerfileModel, ComposeModel, ServiceDetail,
+    DeployModel, DeployResourcesModel, ResourceLimitsModel, ResourceReservationsModel
+)
+
+from xenfra_sdk.constants import DEFAULT_PORT_RANGE_START
+
+class BaseBlueprint(ABC):
+    """
+    Abstract base class for all Xenfra Blueprints (Build Packs).
+    
+    A Blueprint is responsible for:
+    1. Analyzing code to detect requirements.
+    2. Building a valid Pydantic manifest.
+    3. Rendering that manifest to files (Dockerfile, compose, env).
+    """
+
+    def __init__(self, context: dict):
+        self.context = context
+        self.framework = context.get("framework")
+        self.port = context.get("port") or DEFAULT_PORT_RANGE_START
+        self.file_manifest = context.get("file_manifest", [])
+        self.resource_limits = context.get("resource_limits", {})
+
+    def _generate_deploy_model(self) -> DeployModel:
+        """Centralized helper for resource governance."""
+        return DeployModel(
+            resources=DeployResourcesModel(
+                limits=ResourceLimitsModel(
+                    memory=self.resource_limits.get("memory", "512m"),
+                    cpus=self.resource_limits.get("cpus", "0.5"),
+                ),
+                reservations=ResourceReservationsModel(
+                    memory=self.resource_limits.get("memory_reserved", "128m"),
+                    cpus=self.resource_limits.get("cpus_reserved", "0.25"),
+                ),
+            )
+        )
+
+    @abstractmethod
+    def generate_manifest(self) -> DeploymentBlueprintManifest:
+        """Analyze context and files to build the Pydantic manifest."""
+        pass
+
+    def render(self) -> Dict[str, str]:
+        """Renders the generated manifest into final deployment strings."""
+        manifest = self.generate_manifest()
+        result = {}
+
+        # 1. Render Dockerfile
+        result["Dockerfile"] = self._render_dockerfile(manifest.dockerfile)
+
+        # 2. Render docker-compose.yml
+        result["docker-compose.yml"] = self._render_compose(manifest.compose)
+
+        # 3. Render .env
+        if manifest.env_file:
+            result[".env"] = "\n".join([f'{k}="{v}"' for k, v in manifest.env_file.items()])
+
+        # 4. Render Caddyfile (if provided)
+        if manifest.caddyfile:
+            result["Caddyfile"] = manifest.caddyfile
+
+        # 5. Render Railpack Plan (if provided)
+        if hasattr(manifest, "railpack_plan") and manifest.railpack_plan:
+            result["railpack-plan.json"] = manifest.railpack_plan
+
+        return result
+
+    def _render_dockerfile(self, model: DockerfileModel) -> str:
+        """Converts DockerfileModel to a string."""
+        lines = [f"FROM {model.base_image}"]
+        
+        # Inject ARG instructions (Build-time variables)
+        # Must come after FROM (usually) or before depending on if they affect FROM
+        # Standard practice: FROM -> ARG -> WORKDIR -> COPY -> RUN
+        if model.args:
+            for arg in model.args:
+                lines.append(f"ARG {arg}")
+
+        # APT packages
+        if model.system_packages:
+            packages = " ".join(model.system_packages)
+            lines.append("RUN apt-get update && apt-get install -y " + packages + " && rm -rf /var/lib/apt/lists/*")
+
+        lines.append(f"WORKDIR {model.workdir}")
+
+        # Env vars (Non-secret defaults only)
+        # We rely on .env + docker-compose for actual deployment values.
+        # ARGs are already available during build.
+        arg_keys = set(model.args)
+        for k, v in model.env_vars.items():
+            if k in arg_keys:
+                # Skip ENV if it's already an ARG, to keep secrets out of Dockerfile and fix syntax errors
+                continue
+            # Quote values for safety
+            lines.append(f'ENV {k}="{v}"')
+
+        # Copy commands
+        if model.copy_dirs:
+            for d in model.copy_dirs:
+                lines.append(f"COPY {d} .")
+        else:
+            lines.append("COPY . .")
+
+        # Custom RUN commands
+        for cmd in model.run_commands:
+            lines.append(f"RUN {cmd}")
+
+        if model.expose_port:
+            lines.append(f"EXPOSE {model.expose_port}")
+
+        if model.entrypoint:
+            if isinstance(model.entrypoint, list):
+                ep = ", ".join([f'"{x}"' for x in model.entrypoint])
+                lines.append(f"ENTRYPOINT [{ep}]")
+            else:
+                lines.append(f"ENTRYPOINT {model.entrypoint}")
+
+        if model.command:
+            if isinstance(model.command, list):
+                cmd = ", ".join([f'"{x}"' for x in model.command])
+                lines.append(f"CMD [{cmd}]")
+            else:
+                lines.append(f"CMD {model.command}")
+
+        return "\n".join(lines)
+
+    def _render_compose(self, model: ComposeModel) -> str:
+        """Converts ComposeModel to a YAML string."""
+        # We use a custom dumper to ensure services come first etc if needed
+        # But standard yaml works for start
+        data = model.model_dump(by_alias=True, exclude_none=True)
+        return yaml.dump(data, sort_keys=False, default_flow_style=False)
+
+    def has_file(self, filename: str) -> bool:
+        """Helper to check if a file exists in the manifest."""
+        return any(f.get("path") == filename for f in self.file_manifest)
+
+    def get_file_content(self, filename: str) -> Optional[str]:
+        """Helper to get file content from manifest."""
+        for f in self.file_manifest:
+            if f.get("path") == filename:
+                return f.get("content")
+        return None

xenfra_sdk/blueprints/factory.py

@@ -0,0 +1,99 @@
+from typing import Type, Dict, List
+from xenfra_sdk.blueprints.base import BaseBlueprint
+from xenfra_sdk.blueprints.python import PythonBlueprint
+from xenfra_sdk.blueprints.node import NodeBlueprint
+from xenfra_sdk.blueprints.railpack import RailpackBlueprint
+from xenfra_sdk.governance import get_resource_limits, ResourceLimits
+
+
+def resolve_blueprint_class(context: dict) -> Type[BaseBlueprint]:
+    """
+    The 'Check-In Desk' for manifest generation.
+    Decides between Sovereign (Lean) and Specialist (Railpack) paths.
+    
+    Priority:
+    1. Explicit framework selection (user-specified)
+    2. File-based detection fallback
+    """
+    framework = str(context.get("framework", "")).lower().strip()
+    file_manifest = context.get("file_manifest", [])
+    file_names = {f.get("path") for f in file_manifest}
+
+    # 1. EXPLICIT FRAMEWORK SELECTION (takes priority)
+    # If user explicitly selected a framework, respect that choice
+    SOVEREIGN_PYTHON = ("python", "fastapi", "flask", "django")
+    
+    # Modern Node.js frameworks that need railpack (auto-detect + build)
+    # These have complex build pipelines that railpack/nixpacks handles better
+    RAILPACK_NODE = ("next", "nextjs", "nuxt", "vite", "nestjs", "nest")
+    
+    # Simple Node.js that can use our lean NodeBlueprint
+    # Only for Express-style apps without complex build steps
+    SOVEREIGN_NODE = ("express",)
+    
+    if framework in SOVEREIGN_PYTHON:
+        # Check for complex package managers (uv, poetry, pipenv) -> Use Railpack
+        if any(f in file_names for f in ("uv.lock", "poetry.lock", "Pipfile.lock")):
+            return RailpackBlueprint
+        return PythonBlueprint
+    
+    # Route modern frameworks to RailpackBlueprint
+    if framework in RAILPACK_NODE:
+        return RailpackBlueprint
+    
+    # Generic "node" or "nodejs" → check file_manifest for framework hints
+    if framework in ("node", "nodejs"):
+        # Check for Next.js, Nuxt, etc. config files
+        nextjs_configs = {"next.config.js", "next.config.ts", "next.config.mjs"}
+        nuxt_configs = {"nuxt.config.js", "nuxt.config.ts"}
+        vite_configs = {"vite.config.js", "vite.config.ts"}
+        
+        if nextjs_configs & file_names or nuxt_configs & file_names or vite_configs & file_names:
+            return RailpackBlueprint
+        
+        # Default to RailpackBlueprint for generic Node.js (safer, handles more cases)
+        return RailpackBlueprint
+    
+    if framework in SOVEREIGN_NODE:
+        return NodeBlueprint
+        
+    # 2. FILE-BASED DETECTION FALLBACK (only if no explicit framework)
+    # Check for Python Sovereign Path (Strict Golden Path)
+    if "requirements.txt" in file_names and "pyproject.toml" not in file_names:
+        return PythonBlueprint
+        
+    # Check for Node Sovereign Path (Strict Golden Path) 
+    # Only for simple Express apps with package-lock.json
+    if "package-lock.json" in file_names and "package.json" in file_names:
+        # If has modern framework config files, use Railpack
+        nextjs_configs = {"next.config.js", "next.config.ts", "next.config.mjs"}
+        if nextjs_configs & file_names:
+            return RailpackBlueprint
+        # Otherwise, still prefer RailpackBlueprint for safety
+        return RailpackBlueprint
+
+    # 3. Specialist Path (The Delegate)
+    # Handles EVERYTHING else: Rust, Go, Bun, UV, Poetry, etc.
+    return RailpackBlueprint
+
+
+def render_blueprint(context: dict) -> Dict[str, str]:
+    """
+    Main entry point for manifest generation.
+    Resolves the blueprint and renders it to strings.
+
+    ZEN GAP FIX: Automatically injects tier-based resource limits.
+    """
+    # Inject resource limits if tier is provided but resource_limits isn't
+    if "resource_limits" not in context and "tier" in context:
+        limits = get_resource_limits(context["tier"])
+        context["resource_limits"] = {
+            "memory": limits.memory,
+            "cpus": limits.cpus,
+            "memory_reserved": limits.memory_reserved,
+            "cpus_reserved": limits.cpus_reserved,
+        }
+
+    blueprint_class = resolve_blueprint_class(context)
+    blueprint = blueprint_class(context)
+    return blueprint.render()

xenfra_sdk/blueprints/node.py

@@ -0,0 +1,219 @@
+import subprocess
+import json
+from typing import Dict, Any, List
+from xenfra_sdk.blueprints.base import BaseBlueprint
+from xenfra_sdk.blueprints.schema import DeploymentBlueprintManifest, DockerfileModel, ComposeModel, ServiceDetail
+
+
+class NodeBlueprint(BaseBlueprint):
+    """
+    Sovereign Lean Build-Pack for Node.js with Smart Detection.
+    
+    Detects sub-frameworks: Next.js, Vite, Express, Nest, etc.
+    Detects package managers: npm, pnpm, yarn, bun.
+    """
+
+    # === PROTOCOL COMPLIANT: Static Recipe Pattern ===
+    # No if-else chains - use dictionary-based detection
+    PACKAGE_MANAGER_RECIPES = {
+        "bun.lockb": {"install": "bun install", "run": "bun run", "binary": "bun"},
+        "pnpm-lock.yaml": {"install": "pnpm install", "run": "pnpm run", "binary": "pnpm"},
+        "yarn.lock": {"install": "yarn install", "run": "yarn", "binary": "yarn"},
+        "package-lock.json": {"install": "npm install", "run": "npm run", "binary": "npm"},
+    }
+
+    FRAMEWORK_RECIPES = {
+        "next": {
+            "build": "{run} build",
+            "start": "{run} start",
+            "base_image": "node:18-slim",
+        },
+        "vite": {
+            "build": "{run} build",
+            "start": "{run} preview",
+            "base_image": "node:18-slim",
+        },
+        "nuxt": {
+            "build": "{run} build",
+            "start": "node .output/server/index.mjs",
+            "base_image": "node:18-slim",
+        },
+        "express": {
+            "build": None,  # Express usually doesn't need build
+            "start": "node {entrypoint}",
+            "base_image": "node:18-slim",
+        },
+        "nestjs": {
+            "build": "{run} build",
+            "start": "node dist/main.js",
+            "base_image": "node:18-slim",
+        },
+    }
+
+    def generate_manifest(self) -> DeploymentBlueprintManifest:
+        # Smart Detection: Try nixpacks -> Static Recipes -> Default
+        detection = self._detect_node_environment()
+        
+        # 1. Build Dockerfile
+        dockerfile = DockerfileModel(
+            base_image=detection["base_image"],
+            expose_port=self.port,
+            run_commands=detection["run_commands"],
+            command=detection["command"],
+            env_vars={"PORT": str(self.port)}
+        )
+
+        # 2. Build Compose with Resource Governance
+        service = ServiceDetail(
+            build=".",
+            ports=[f"{self.port}:{self.port}"],
+            environment={
+                **self.context.get("env_vars", {}),
+                "PORT": str(self.port),
+                "NODE_ENV": "production"
+            },
+            command=detection["command"],
+            deploy=self._generate_deploy_model()
+        )
+
+        return DeploymentBlueprintManifest(
+            dockerfile=dockerfile,
+            compose=ComposeModel(services={"app": service}),
+            env_file=self.context.get("env_vars", {})
+        )
+
+    def _detect_node_environment(self) -> Dict[str, Any]:
+        """
+        Multi-stage detection for Node.js projects.
+        Stage A: Try nixpacks CLI (most accurate)
+        Stage B: Parse package.json for framework/package manager
+        Stage C: Default npm start fallback
+        """
+        file_names = {f.get("path", "") for f in self.file_manifest}
+        pkg_json = self._get_package_json()
+
+        # Stage A: Try Railpack CLI (Railway's latest buildpack)
+        try:
+            result = subprocess.run(
+                ["railpack", "plan", ".", "--json"],
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=30
+            )
+            plan = json.loads(result.stdout)
+            phases = plan.get("phases", {})
+            
+            # Extract nixpacks detection
+            build_cmds = phases.get("build", {}).get("cmds", [])
+            start_cmd = phases.get("start", {}).get("cmd", "npm start")
+            
+            return {
+                "base_image": "node:18-slim",
+                "run_commands": self._build_run_commands(build_cmds),
+                "command": start_cmd,
+                "detection": "nixpacks"
+            }
+        except (subprocess.CalledProcessError, FileNotFoundError, 
+                subprocess.TimeoutExpired, json.JSONDecodeError):
+            pass  # Fall through to Stage B
+
+        # Stage B: Static Recipe Detection
+        pkg_manager = self._detect_package_manager(file_names)
+        framework = self._detect_node_framework(pkg_json)
+        entrypoint = self._detect_entrypoint(pkg_json, file_names)
+
+        # Build commands based on detected framework
+        run_prefix = pkg_manager["run"]
+        recipe = self.FRAMEWORK_RECIPES.get(framework, {})
+        
+        build_cmd = recipe.get("build")
+        start_cmd = recipe.get("start", "{run} start")
+        
+        # Format commands with detected values
+        if build_cmd:
+            build_cmd = build_cmd.format(run=run_prefix)
+        start_cmd = start_cmd.format(run=run_prefix, entrypoint=entrypoint)
+
+        run_commands = [
+            pkg_manager['install'],  # e.g., "npm install" - renderer adds RUN
+        ]
+        if build_cmd:
+            run_commands.append(build_cmd)  # e.g., "npm run build" - renderer adds RUN
+
+        return {
+            "base_image": recipe.get("base_image", "node:18-slim"),
+            "run_commands": run_commands,
+            "command": start_cmd,
+            "detection": f"static:{framework}:{pkg_manager['binary']}"
+        }
+
+    def _detect_package_manager(self, file_names: set) -> Dict[str, str]:
+        """Detect package manager from lockfile."""
+        for lockfile, recipe in self.PACKAGE_MANAGER_RECIPES.items():
+            if lockfile in file_names:
+                return {**recipe, "lockfile": lockfile}
+        # Default to npm
+        return {**self.PACKAGE_MANAGER_RECIPES["package-lock.json"], "lockfile": "package*.json"}
+
+    def _detect_node_framework(self, pkg_json: Dict) -> str:
+        """Detect Node.js framework from package.json dependencies."""
+        deps = {
+            **pkg_json.get("dependencies", {}),
+            **pkg_json.get("devDependencies", {})
+        }
+        
+        # Priority order for framework detection
+        framework_deps = [
+            ("next", "next"),
+            ("@nestjs/core", "nestjs"),
+            ("nuxt", "nuxt"),
+            ("vite", "vite"),
+            ("express", "express"),
+        ]
+        
+        for dep_name, framework in framework_deps:
+            if dep_name in deps:
+                return framework
+        
+        return "express"  # Default assumption for Node.js
+
+    def _detect_entrypoint(self, pkg_json: Dict, file_names: set) -> str:
+        """Detect main entrypoint file."""
+        # Check package.json main field
+        main = pkg_json.get("main")
+        if main:
+            return main
+        
+        # Check common entrypoint patterns
+        common_entrypoints = ["index.js", "server.js", "app.js", "src/index.js", "src/server.js"]
+        for entry in common_entrypoints:
+            if entry in file_names:
+                return entry
+        
+        return "index.js"
+
+    def _get_package_json(self) -> Dict:
+        """Extract package.json content from file manifest."""
+        for f in self.file_manifest:
+            if f.get("path") == "package.json":
+                content = f.get("content", "{}")
+                try:
+                    return json.loads(content)
+                except json.JSONDecodeError:
+                    return {}
+        return {}
+
+    def _build_run_commands(self, build_cmds: List[str]) -> List[str]:
+        """Format build commands for Dockerfile (without RUN prefix - renderer adds it)."""
+        commands = [
+            "npm install",  # Renderer adds RUN prefix
+        ]
+        for cmd in build_cmds:
+            if cmd and not cmd.startswith("npm install"):
+                commands.append(cmd)  # Renderer adds RUN prefix
+        return commands
+
+    def _get_default_command(self) -> str:
+        """Return default command for this blueprint."""
+        return "npm start"

xenfra_sdk/blueprints/python.py

@@ -0,0 +1,57 @@
+from xenfra_sdk.blueprints.base import BaseBlueprint
+from xenfra_sdk.blueprints.schema import DeploymentBlueprintManifest, DockerfileModel, ComposeModel, ServiceDetail
+from xenfra_sdk.dockerizer import detect_entrypoint
+
+class PythonBlueprint(BaseBlueprint):
+    """
+    Sovereign Lean Build-Pack for Python.
+    Only handles the 'Golden Path' (requirements.txt).
+    """
+
+    def generate_manifest(self) -> DeploymentBlueprintManifest:
+        # 1. Deterministic Defaults (with proactive detection)
+        base_image = "python:3.11-slim"
+        entrypoint = self.context.get("entrypoint")
+        if not entrypoint:
+            entrypoint = detect_entrypoint(self.file_manifest, framework=self.framework)
+        
+        command = self.context.get("command")
+        if not command:
+            if self.framework == "fastapi":
+                command = f"uvicorn {entrypoint} --host 0.0.0.0 --port {self.port}"
+            elif self.framework == "django":
+                # Django typically needs migrations and runs with gunicorn
+                app_name = entrypoint.split(":")[0]
+                command = f"python manage.py migrate && gunicorn {app_name}.wsgi:application --bind 0.0.0.0:{self.port}"
+            elif self.framework == "flask":
+                # Flask also runs well with gunicorn
+                command = f"gunicorn --bind 0.0.0.0:{self.port} {entrypoint}"
+            else:
+                py_file = entrypoint.split(":")[0].replace(".", "/") + ".py"
+                command = f"python -u {py_file}"
+        
+        # 2. Build Dockerfile
+        dockerfile = DockerfileModel(
+            base_image="python:3.11", # Using non-slim for build tools
+            expose_port=self.port,
+            run_commands=[
+                "pip install --upgrade pip",
+                "pip install --no-cache-dir -r requirements.txt"
+            ],
+            command=command.split()
+        )
+
+        # 3. Build Compose with Resource Governance
+        service = ServiceDetail(
+            build=".",
+            ports=[f"{self.port}:{self.port}"],
+            environment=self.context.get("env_vars", {}),
+            command=command,
+            deploy=self._generate_deploy_model()
+        )
+
+        return DeploymentBlueprintManifest(
+            dockerfile=dockerfile,
+            compose=ComposeModel(services={"app": service}),
+            env_file=self.context.get("env_vars", {})
+        )