xenfra 0.1.0__tar.gz

xenfra-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: xenfra
+Version: 0.1.0
+Summary: A 'Zen Mode' infrastructure engine for Python developers.
+Author: xenfra-cloud
+Author-email: xenfra-cloud <xenfracloud@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: fabric>=3.2.2
+Requires-Dist: python-digitalocean>=1.17.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'test'
+Requires-Dist: pytest-mock>=3.12.0 ; extra == 'test'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/xenfra-cloud/xenfra
+Project-URL: Issues, https://github.com/xenfra-cloud/xenfra/issues
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# 🧘 Xenfra: Infrastructure in Zen Mode
+
+**Xenfra** is a modular infrastructure engine for Python developers that automates the deployment of applications to DigitalOcean. It is designed as a library first, with a beautiful and interactive CLI as the default frontend.
+
+It handles the complexity of server provisioning, context-aware configuration, Dockerization, and automatic HTTPS, allowing you to focus on your code.
+
+## ✨ Core Philosophy
+
+*   **Engine as the Brain**: `xenfra.engine` is the core library. It owns the DigitalOcean API, the SSH "Auto-Heal" retry loops, and the Dockerizer services. It is stateful, robust, and can be imported into any Python project.
+*   **Clients as the Face**: Frontends like the default CLI (`xenfra.cli`) are thin, stateless clients responsible only for user interaction.
+*   **Zen Mode**: If a server setup fails due to common issues like a locked package manager, the Engine automatically fixes it without exposing raw errors to the user.
+
+## 🚀 Quickstart: As a Library
+
+This demonstrates the power of Xenfra's engine for programmatic infrastructure management.
+
+### 1. Installation
+
+```bash
+# Install from PyPI (once published)
+pip install xenfra
+```
+
+### 2. Prerequisites
+
+Ensure your DigitalOcean API token is available as an environment variable:
+
+```bash
+export DIGITAL_OCEAN_TOKEN="your_secret_token_here"
+```
+
+### 3. Programmatic Usage
+
+```python
+from xenfra.engine import InfraEngine
+
+# Optional: a logger to receive status updates
+def my_logger(message):
+    print(f"[My App] {message}")
+
+try:
+    # The engine automatically finds and validates the API token
+    engine = InfraEngine()
+
+    # Define the server and deploy
+    result = engine.deploy_server(
+        name="my-app-server",
+        region="nyc3",
+        size="s-1vcpu-1gb",
+        image="ubuntu-24-04-x64",
+        logger=my_logger
+    )
+
+    print(f"🎉 Deployment successful! IP Address: {result.get('ip')}")
+
+except Exception as e:
+    print(f"❌ Deployment failed: {e}")
+```
+
+## 💻 CLI Usage
+
+Xenfra also provides a beautiful, interactive CLI for manual control.
+
+### 1. Installation
+
+```bash
+pip install xenfra
+```
+
+### 2. Configuration
+
+Create a `.env` file in your project root with your DigitalOcean token:
+
+```env
+DIGITAL_OCEAN_TOKEN=dop_v1_your_token_here
+```
+
+### 3. Run the CLI
+
+Once installed, simply run the `xenfra` command:
+
+```bash
+xenfra
+```
+
+This will launch the interactive menu where you can:
+- **🚀 Deploy New Server**: A guided workflow to provision and deploy your application.
+- **📋 List Active Servers**: View your current DigitalOcean droplets.
+- **🧨 Destroy a Server**: Decommission servers you no longer need.
+
+## 📦 Supported Frameworks & Features
+
+*   **Smart Context Detection**: Automatically detects your package manager (`uv` or `pip`).
+*   **Automatic Dockerization**: If a web framework is detected (`FastAPI`, `Flask`), Xenfra will:
+    *   Generate a `Dockerfile`, `docker-compose.yml`, and `Caddyfile`.
+    *   Deploy your application as a container.
+    *   Configure **Caddy** as a reverse proxy with **automatic HTTPS**.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please check our `CONTRIBUTING.md` for more details.
+
+## 📄 Created by DevHusnainAi

xenfra-0.1.0/README.md

@@ -0,0 +1,103 @@
+# 🧘 Xenfra: Infrastructure in Zen Mode
+
+**Xenfra** is a modular infrastructure engine for Python developers that automates the deployment of applications to DigitalOcean. It is designed as a library first, with a beautiful and interactive CLI as the default frontend.
+
+It handles the complexity of server provisioning, context-aware configuration, Dockerization, and automatic HTTPS, allowing you to focus on your code.
+
+## ✨ Core Philosophy
+
+*   **Engine as the Brain**: `xenfra.engine` is the core library. It owns the DigitalOcean API, the SSH "Auto-Heal" retry loops, and the Dockerizer services. It is stateful, robust, and can be imported into any Python project.
+*   **Clients as the Face**: Frontends like the default CLI (`xenfra.cli`) are thin, stateless clients responsible only for user interaction.
+*   **Zen Mode**: If a server setup fails due to common issues like a locked package manager, the Engine automatically fixes it without exposing raw errors to the user.
+
+## 🚀 Quickstart: As a Library
+
+This demonstrates the power of Xenfra's engine for programmatic infrastructure management.
+
+### 1. Installation
+
+```bash
+# Install from PyPI (once published)
+pip install xenfra
+```
+
+### 2. Prerequisites
+
+Ensure your DigitalOcean API token is available as an environment variable:
+
+```bash
+export DIGITAL_OCEAN_TOKEN="your_secret_token_here"
+```
+
+### 3. Programmatic Usage
+
+```python
+from xenfra.engine import InfraEngine
+
+# Optional: a logger to receive status updates
+def my_logger(message):
+    print(f"[My App] {message}")
+
+try:
+    # The engine automatically finds and validates the API token
+    engine = InfraEngine()
+
+    # Define the server and deploy
+    result = engine.deploy_server(
+        name="my-app-server",
+        region="nyc3",
+        size="s-1vcpu-1gb",
+        image="ubuntu-24-04-x64",
+        logger=my_logger
+    )
+
+    print(f"🎉 Deployment successful! IP Address: {result.get('ip')}")
+
+except Exception as e:
+    print(f"❌ Deployment failed: {e}")
+```
+
+## 💻 CLI Usage
+
+Xenfra also provides a beautiful, interactive CLI for manual control.
+
+### 1. Installation
+
+```bash
+pip install xenfra
+```
+
+### 2. Configuration
+
+Create a `.env` file in your project root with your DigitalOcean token:
+
+```env
+DIGITAL_OCEAN_TOKEN=dop_v1_your_token_here
+```
+
+### 3. Run the CLI
+
+Once installed, simply run the `xenfra` command:
+
+```bash
+xenfra
+```
+
+This will launch the interactive menu where you can:
+- **🚀 Deploy New Server**: A guided workflow to provision and deploy your application.
+- **📋 List Active Servers**: View your current DigitalOcean droplets.
+- **🧨 Destroy a Server**: Decommission servers you no longer need.
+
+## 📦 Supported Frameworks & Features
+
+*   **Smart Context Detection**: Automatically detects your package manager (`uv` or `pip`).
+*   **Automatic Dockerization**: If a web framework is detected (`FastAPI`, `Flask`), Xenfra will:
+    *   Generate a `Dockerfile`, `docker-compose.yml`, and `Caddyfile`.
+    *   Deploy your application as a container.
+    *   Configure **Caddy** as a reverse proxy with **automatic HTTPS**.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please check our `CONTRIBUTING.md` for more details.
+
+## 📄 Created by DevHusnainAi

xenfra-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "xenfra"
+version = "0.1.0"
+description = "A 'Zen Mode' infrastructure engine for Python developers."
+readme = "README.md"
+authors = [
+    { name = "xenfra-cloud", email = "xenfracloud@gmail.com" }
+]
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "fabric>=3.2.2",
+    "python-digitalocean>=1.17.0",
+    "python-dotenv>=1.2.1",
+    "rich>=14.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/xenfra-cloud/xenfra"
+Issues = "https://github.com/xenfra-cloud/xenfra/issues"
+
+[project.scripts]
+xenfra = "xenfra.cli:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-mock>=3.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"

xenfra-0.1.0/src/xenfra/__init__.py

@@ -0,0 +1 @@
+# This file makes src/xenfra a Python package.

xenfra-0.1.0/src/xenfra/cli.py

@@ -0,0 +1,162 @@
+from rich.console import Console
+from rich.table import Table
+from rich.prompt import Prompt, Confirm, IntPrompt
+from rich.panel import Panel
+
+# Import Custom Logic
+from xenfra.engine import InfraEngine
+
+console = Console()
+
+# --- CONSTANTS ---
+SIZES = {
+    "1": ("s-1vcpu-1gb", "$6/mo", "1GB RAM / 1 CPU"),
+    "2": ("s-1vcpu-2gb", "$12/mo", "2GB RAM / 1 CPU"),
+    "3": ("s-2vcpu-4gb", "$24/mo", "4GB RAM / 2 CPU"),
+}
+
+IMAGES = {
+    "1": ("ubuntu-24-04-x64", "Ubuntu 24.04 LTS"),
+    "2": ("debian-12-x64", "Debian 12"),
+    "3": ("fedora-39-x64", "Fedora 39"),
+}
+
+def print_header(email):
+    console.clear()
+    grid = Table.grid(expand=True)
+    grid.add_column(justify="center", ratio=1)
+    grid.add_row("[bold cyan]🧘 XENFRA[/bold cyan] [dim]v0.1.0[/dim]")
+    grid.add_row("[italic]Infrastructure in Zen Mode[/italic]")
+    console.print(Panel(
+        grid,
+        style="cyan",
+        subtitle=f"👤 {email} | 📧 support@xenfracloud.com"
+    ))
+
+def deploy_menu(engine: InfraEngine):
+    console.print("\n[bold green]🛠️  CONFIGURE YOUR SERVER[/bold green]")
+
+    # 1. Name
+    name = Prompt.ask("   🏷️  Server Name", default="xenfra-node-01")
+
+    # 2. Image Selection
+    console.print("\n   [bold]Select Operating System:[/bold]")
+    for k, v in IMAGES.items():
+        console.print(f"   [cyan]{k}[/cyan]. {v[1]}")
+    img_choice = Prompt.ask("   Choice", choices=list(IMAGES.keys()), default="1")
+    selected_image = IMAGES[img_choice][0]
+
+    # 3. Size Selection
+    console.print("\n   [bold]Select Power Size:[/bold]")
+    for k, v in SIZES.items():
+        console.print(f"   [cyan]{k}[/cyan]. {v[2]} ({v[1]})")
+    size_choice = Prompt.ask("   Choice", choices=list(SIZES.keys()), default="1")
+    selected_size = SIZES[size_choice][0]
+
+    # 4. Final Confirm
+    if not Confirm.ask(f"\n🚀 Deploy [cyan]{name}[/cyan]?"):
+        return
+
+    # 5. EXECUTE (Delegate to Engine)
+    try:
+        # This is now a single, blocking call to the stateful engine.
+        # The engine handles all the complexity. The CLI just shows the final result.
+        result = engine.deploy_server(
+            name=name,
+            region="blr1", # region can be prompted for in the future
+            size=selected_size,
+            image=selected_image,
+            logger=console.log
+        )
+        console.print(Panel(
+            f"[bold green]✅ SERVER ONLINE & DEPLOYED![/bold green]\n\n"
+            f"🌍 IP Address: [bold cyan]{result['ip']}[/bold cyan]\n"
+            f"📂 App Path:   [yellow]/root/app[/yellow]\n"
+            f"🔑 Login:      ssh root@{result['ip']}",
+            title="Deployment Success",
+            border_style="green"
+        ))
+    except Exception as e:
+        console.print(Panel(
+            f"[bold red]⚠️  DEPLOYMENT FAILED[/bold red]\n\n"
+            f"The engine reported a critical error: {e}\n"
+            f"Check logs if available on the server.",
+            title="Fatal Error",
+            border_style="red"
+        ))
+
+    Prompt.ask("\nPress Enter to return to menu")
+
+def list_menu(engine: InfraEngine):
+    console.print("\n[bold]📡 SCANNING FLEET...[/bold]")
+    with console.status("Calling DigitalOcean API..."):
+        servers = engine.list_servers()
+    
+    if not servers:
+        console.print("[yellow]   No active servers found.[/yellow]")
+    else:
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("ID", style="dim", width=12)
+        table.add_column("Name", style="cyan")
+        table.add_column("IP Address", style="green")
+        table.add_column("Status")
+        table.add_column("Cost", justify="right")
+        for s in servers:
+            table.add_row(str(s.id), s.name, s.ip_address, s.status, f"${s.size['price_monthly']}/mo")
+        console.print(table)
+    Prompt.ask("\nPress Enter to return to menu")
+
+def destroy_menu(engine: InfraEngine):
+    console.print("\n[bold red]🧨 DESTROY SERVER[/bold red]")
+    with console.status("Calling DigitalOcean API..."):
+        servers = engine.list_servers()
+
+    if not servers:
+        console.print("[yellow]   No servers to destroy.[/yellow]")
+        Prompt.ask("\nPress Enter to return")
+        return
+
+    for i, s in enumerate(servers):
+        console.print(f"   [{i+1}] {s.name} ({s.ip_address})")
+
+    choice = IntPrompt.ask("\n   Select Server to Destroy (0 to cancel)", choices=[str(i) for i in range(len(servers) + 1)], show_choices=False)
+    if choice == 0:
+        return
+
+    target = servers[choice-1]
+
+    if Confirm.ask(f"   Are you SURE you want to delete [red]{target.name}[/red]?"):
+        with console.status(f"💥 Destroying {target.name}..."):
+            engine.destroy_server(target.id)
+        console.print(f"[green]   Server {target.name} destroyed.[/green]")
+    
+    Prompt.ask("\nPress Enter to return")
+
+
+def main():
+    try:
+        engine = InfraEngine()
+        user = engine.get_user_info()
+        while True:
+            print_header(user['email'])
+            console.print("\n[bold]MAIN MENU:[/bold]")
+            console.print("   [1] 🚀 Deploy New Server")
+            console.print("   [2] 📋 List Active Servers")
+            console.print("   [3] 🧨 Destroy a Server")
+            console.print("   [4] 🚪 Exit")
+            choice = Prompt.ask("\n   👉 Select Option", choices=["1", "2", "3", "4"], default="2")
+
+            if choice == "1":
+                deploy_menu(engine)
+            elif choice == "2":
+                list_menu(engine)
+            elif choice == "3":
+                destroy_menu(engine)
+            elif choice == "4":
+                console.print("[cyan]Goodbye, CEO.[/cyan]")
+                break
+    except Exception as e:
+        console.print(f"[bold red]CRITICAL ERROR:[/bold red] {e}")
+
+if __name__ == "__main__":
+    main()

xenfra-0.1.0/src/xenfra/dockerizer.py

@@ -0,0 +1,129 @@
+import os
+
+def detect_framework():
+    """
+    Scans files to guess the framework and entrypoint.
+    Returns: (framework_name, default_port, start_command) or (None, None, None)
+    """
+    # 1. FastAPI Scan
+    if os.path.exists("main.py"):
+        with open("main.py", "r") as f:
+            content = f.read()
+            if "FastAPI" in content:
+                return "fastapi", 8000, "uvicorn main:app --host 0.0.0.0 --port 8000"
+
+    # 2. Flask Scan
+    if os.path.exists("app.py"):
+         with open("app.py", "r") as f:
+            content = f.read()
+            if "Flask" in content:
+                return "flask", 5000, "gunicorn app:app -b 0.0.0.0:5000"
+
+    # No framework detected
+    return None, None, None
+
+def generate_deployment_assets(context):
+    """
+    Creates Dockerfile, docker-compose.yml, and Caddyfile
+    if a web framework is detected.
+    """
+    framework, port, cmd = detect_framework()
+    if not framework:
+        return []
+
+    generated = []
+    print(f"   ✨ Web framework detected: {framework.upper()}. Generating deployment assets...")
+
+    # --- 1. DOCKERFILE ---
+    if not os.path.exists("Dockerfile"):
+        # Use UV if detected, otherwise Pip
+        install_cmd = "RUN pip install --no-cache-dir -r requirements.txt"
+        if context.get("type") == "uv":
+            # Assuming uv.lock or pyproject.toml is copied
+            install_cmd = "RUN pip install uv && uv pip install --system -r requirements.txt"
+
+        dockerfile_content = f"""# Generated by Xenfra
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install System Deps
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
+
+# Copy all dependency definition files
+COPY requirements.txt* .
+COPY pyproject.toml* .
+COPY uv.lock* .
+
+# Install Python Deps
+{install_cmd}
+
+# Copy Code
+COPY . .
+
+# Expose Port
+EXPOSE {port}
+
+# Start Command
+CMD ["/bin/sh", "-c", "{cmd}"]
+"""
+        with open("Dockerfile", "w") as f:
+            f.write(dockerfile_content)
+        generated.append("Dockerfile")
+
+    # --- 2. CADDYFILE ---
+    if not os.path.exists("Caddyfile"):
+        caddy_content = f"""{{
+    # Enable automatic HTTPS for all sites
+    email your_email@example.com
+}}
+
+:443 {{
+    reverse_proxy app:{port}
+}}
+
+:80 {{
+    redir https://{{host}}{{uri}}
+}}
+"""
+        with open("Caddyfile", "w") as f:
+            f.write(caddy_content)
+        generated.append("Caddyfile")
+
+    # --- 3. DOCKER COMPOSE ---
+    if not os.path.exists("docker-compose.yml"):
+        compose_content = f"""
+version: '3.8'
+
+services:
+  app:
+    build: .
+    container_name: xenfra_app
+    restart: always
+    # The internal port is exposed to other services in this network
+    expose:
+      - "{port}"
+
+  caddy:
+    image: caddy:latest
+    container_name: xenfra_caddy
+    restart: always
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - app
+
+volumes:
+  caddy_data:
+  caddy_config:
+"""
+        with open("docker-compose.yml", "w") as f:
+            f.write(compose_content)
+        generated.append("docker-compose.yml")
+
+    return generated

xenfra-0.1.0/src/xenfra/engine.py

@@ -0,0 +1,264 @@
+import digitalocean
+import os
+import time
+from dotenv import load_dotenv
+from pathlib import Path
+from fabric import Connection
+
+# Internal imports
+from .utils import get_project_context
+from .recipes import generate_stack
+from .dockerizer import detect_framework, generate_deployment_assets
+
+
+class InfraEngine:
+    """
+    The Core SDK.
+    This class handles all communication with DigitalOcean.
+    It is designed to be used by a CLI or an AI Agent.
+    """
+
+    def __init__(self):
+        # Load secrets immediately
+        load_dotenv()
+        self.token = os.getenv("DIGITAL_OCEAN_TOKEN")
+        
+        if not self.token:
+            raise ValueError("❌ FATAL: No DIGITAL_OCEAN_TOKEN found in .env or environment.")
+            
+        self.manager = digitalocean.Manager(token=self.token)
+
+    def get_user_info(self):
+        """Returns the current user's email and account status."""
+        try:
+            account = self.manager.get_account()
+            return {"email": account.email, "status": account.status, "limit": account.droplet_limit}
+        except Exception as e:
+            raise ConnectionError(f"Could not connect to DigitalOcean: {e}")
+
+    def _ensure_ssh_key(self):
+        """
+        Private method.
+        1. Dynamically finds local public SSH keys in ~/.ssh/.
+        2. Checks if any of them exist on DigitalOcean.
+        3. If not, uploads the first one found.
+        Returns: The SSHKey object.
+        """
+        # 1. Find Local Keys
+        ssh_dir = Path.home() / ".ssh"
+        pub_keys = list(ssh_dir.glob("*.pub"))
+
+        if not pub_keys:
+            raise FileNotFoundError(f"No public SSH keys found in {ssh_dir}. Run 'ssh-keygen' first.")
+
+        # 2. Check Remote Keys against Local Keys
+        remote_keys = self.manager.get_all_sshkeys()
+        remote_key_map = {k.public_key.strip(): k for k in remote_keys}
+
+        first_local_key_content = None
+        for key_path in pub_keys:
+            local_pub_key = key_path.read_text().strip()
+            if not first_local_key_content:
+                first_local_key_content = local_pub_key
+            
+            if local_pub_key in remote_key_map:
+                print(f"✨ Found existing SSH key on DigitalOcean: {key_path.name}")
+                return remote_key_map[local_pub_key]
+
+        # 3. If no matches, upload the first key found
+        if not first_local_key_content:
+             raise FileNotFoundError(f"Could not read any public keys in {ssh_dir}.")
+
+        print(f"✨ No matching SSH key found on DigitalOcean. Uploading new key from {pub_keys[0].name}...")
+        new_key = digitalocean.SSHKey(token=self.token,
+                                      name=f"xenfra-{pub_keys[0].name}-{int(time.time())}",
+                                      public_key=first_local_key_content)
+        new_key.create()
+        return new_key
+
+    def _get_connection(self, ip_address: str):
+        """Creates a standardized Fabric connection."""
+        return Connection(
+            host=ip_address,
+            user="root",
+            connect_kwargs={
+                "timeout": 10
+            }
+        )
+
+    def _is_setup_complete(self, ip_address: str) -> bool:
+        """Checks for the setup completion marker file on the remote server."""
+        try:
+            c = self._get_connection(ip_address)
+            if c.run("test -f /root/setup_complete", warn=True, hide=True).ok:
+                return True
+        except Exception:
+            # This can happen if the server is not ready for SSH
+            return False
+        return False
+
+    def _auto_heal_server(self, ip_address: str):
+        """
+        Diagnoses issues and attempts to fix them remotely.
+        This is the 'nuclear option' for a stalled setup.
+        """
+        print(f"\n[ENGINE] 🚑 INITIATING AUTO-HEAL PROTOCOL for {ip_address}...")
+        c = self._get_connection(ip_address)
+
+        # A. STOP SERVICES (Prevent Respawn)
+        print("[ENGINE] 🛑 Stopping background update services...")
+        c.run("systemctl stop unattended-upgrades.service", warn=True, hide=True)
+        c.run("systemctl stop apt-daily.service", warn=True, hide=True)
+        c.run("systemctl stop apt-daily-upgrade.service", warn=True, hide=True)
+
+        # B. KILL PROCESSES
+        print("[ENGINE] 🔪 Killing stuck processes...")
+        c.run("pkill apt", warn=True, hide=True)
+        c.run("pkill apt-get", warn=True, hide=True)
+        c.run("pkill dpkg", warn=True, hide=True)
+
+        # C. REMOVE LOCKS
+        print("[ENGINE] PWN: Removing lock files...")
+        c.run("rm -f /var/lib/dpkg/lock*", warn=True, hide=True)
+        c.run("rm -f /var/lib/apt/lists/lock", warn=True, hide=True)
+        c.run("rm -f /var/cache/apt/archives/lock", warn=True, hide=True)
+
+        # D. REPAIR DPKG
+        print("[ENGINE] 🔧 Repairing package database...")
+        c.run("dpkg --configure -a", warn=True, hide=True)
+
+        # E. RE-MARK AS COMPLETE (to unblock the health check)
+        c.run("touch /root/setup_complete", warn=True, hide=True)
+        print("[ENGINE] ✅ Auto-Heal Complete.")
+
+    def upload_code(self, ip_address: str) -> bool:
+        """Uses Fabric to upload project files to the /root/app directory."""
+        print(f"\n[ENGINE] 🚁 INITIATING CODE AIRLIFT to {ip_address}...")
+        
+        ignored = {'.git', '.venv', 'venv', '__pycache__', '.pytest_cache', '.DS_Store', '.env'}
+        
+        try:
+            c = self._get_connection(ip_address)
+            
+            print("[ENGINE] 📤 Uploading Project Files...")
+            count = 0
+            for root, dirs, files in os.walk("."):
+                dirs[:] = [d for d in dirs if d not in ignored]
+                
+                for file in files:
+                    if file.endswith(".pyc"): continue
+                    
+                    local_path = os.path.join(root, file)
+                    rel_path = os.path.relpath(local_path, ".")
+                    remote_path = f"/root/app/{rel_path}"
+                    
+                    remote_dir = os.path.dirname(remote_path)
+                    c.run(f"mkdir -p {remote_dir}", hide=True)
+                    
+                    c.put(local_path, remote_path)
+                    count += 1
+
+            print(f"[ENGINE] ✅ Airlift Complete: {count} files transferred.")
+            return True
+
+        except Exception as e:
+            print(f"[ENGINE] ❌ Upload failed: {e}")
+            print("[ENGINE] 🔑 Ensure your SSH Agent is running and keys are added.")
+            return False
+
+    def list_servers(self):
+        """Returns a list of all active servers."""
+        return self.manager.get_all_droplets()
+
+    def deploy_server(self, name, region="blr1", size="s-1vcpu-1gb", image="ubuntu-24-04-x64", logger=None):
+        """
+        Provisions a new server, runs setup, and deploys the application.
+        This is a stateful, blocking method that orchestrates the entire process.
+        """
+        def log(msg):
+            if logger:
+                logger(f"[ENGINE] {msg}")
+            else:
+                print(f"[ENGINE] {msg}")
+
+        log(f"🚀 Starting deployment for '{name}'...")
+
+        try:
+            # 1. Project Context & Asset Generation
+            log("🔎 Detecting project context...")
+            context = get_project_context()
+            framework, _, _ = detect_framework()
+            is_dockerized = False
+            if framework:
+                log(f"✨ Web framework '{framework}' detected.")
+                generate_deployment_assets(context)
+                is_dockerized = True
+
+            # 2. Get SSH Key
+            ssh_key = self._ensure_ssh_key()
+
+            # 3. Generate Setup Script
+            log("📦 Generating cloud-init setup script...")
+            setup_script = generate_stack(context, is_dockerized=is_dockerized)
+
+            # 4. Create Droplet
+            log(f"☁️  Provisioning droplet '{name}'...")
+            droplet = digitalocean.Droplet(token=self.token,
+                                           name=name,
+                                           region=region,
+                                           image=image,
+                                           size_slug=size,
+                                           ssh_keys=[ssh_key],
+                                           user_data=setup_script)
+            droplet.create()
+
+            # 5. Wait for Droplet to become active and get IP
+            log("⏳ Waiting for droplet to become active and get IP address...")
+            while not droplet.ip_address:
+                droplet.load()
+                time.sleep(5)
+            log(f"🌍 Droplet is active at {droplet.ip_address}")
+
+            # 6. Health Check & Auto-Heal Loop
+            log("🩺 Performing health checks on the new server...")
+            attempts = 0
+            max_retries = 18 # ~90 seconds
+            is_healthy = False
+            while attempts < max_retries:
+                if self._is_setup_complete(droplet.ip_address):
+                    log("✅ Server setup complete and healthy.")
+                    is_healthy = True
+                    break
+                log(f"   - Still waiting for setup to complete... (attempt {attempts+1}/{max_retries})")
+                time.sleep(5)
+                attempts += 1
+            
+            if not is_healthy:
+                log("⚠️ Server setup stalled. Initiating auto-heal protocol...")
+                self._auto_heal_server(droplet.ip_address)
+                if not self._is_setup_complete(droplet.ip_address):
+                     raise Exception("Deployment failed: Auto-heal could not recover the server.")
+                log("✅ Server recovered successfully after auto-heal.")
+
+            # 7. Upload Code
+            self.upload_code(droplet.ip_address)
+
+            # 8. Run Docker Compose if applicable
+            if is_dockerized:
+                log("🚀 Starting application with Docker Compose...")
+                c = self._get_connection(droplet.ip_address)
+                c.run("cd /root/app && docker-compose up -d", hide=True)
+
+            log("🎉 Deployment successful!")
+            return {"status": "success", "ip": droplet.ip_address, "name": name}
+
+        except Exception as e:
+            log(f"❌ CRITICAL DEPLOYMENT FAILURE: {e}")
+            # Optionally, trigger a cleanup action here
+            raise e
+
+    def destroy_server(self, droplet_id):
+        """Destroys a server by ID. IRREVERSIBLE."""
+        droplet = self.manager.get_droplet(droplet_id)
+        droplet.destroy()
+        return True

xenfra-0.1.0/src/xenfra/recipes.py

@@ -0,0 +1,115 @@
+def generate_stack(context, is_dockerized=False):
+    """
+    Generates a startup script.
+    INCLUDES 'AGGRESSIVE MODE' to kill background updates.
+    """
+    project_type = context.get("type", "pip")
+    packages = context.get("packages", "")
+
+    script = """#!/bin/bash
+export DEBIAN_FRONTEND=noninteractive
+LOG="/root/setup.log"
+touch $LOG
+
+echo "--------------------------------" >> $LOG
+echo "🧘 XENFRA: Context-Aware Boot" >> $LOG
+echo "--------------------------------" >> $LOG
+
+# Create App Directory
+mkdir -p /root/app
+cd /root/app
+
+# --- AGGRESSIVE FIX: KILL BACKGROUND UPDATES ---
+echo "⚔️  [0/6] Stopping Background Updates..." >> $LOG
+systemctl stop unattended-upgrades.service
+systemctl stop apt-daily.service
+systemctl stop apt-daily-upgrade.service
+systemctl kill --kill-who=all apt-daily.service
+systemctl kill --kill-who=all apt-daily-upgrade.service
+
+# Force remove locks if they exist (The Nuclear Option)
+rm -f /var/lib/dpkg/lock*
+rm -f /var/lib/apt/lists/lock
+rm -f /var/cache/apt/archives/lock
+dpkg --configure -a
+# -----------------------------------------------
+
+# 1. System Updates
+echo "🔄 [1/6] Refreshing Package Lists..." >> $LOG
+apt-get update
+apt-get install -y python3-pip python3-venv git curl
+
+# 2. Install Docker & Compose
+echo "🐳 [2/6] Installing Docker..." >> $LOG
+apt-get install -y docker.io || (curl -fsSL https://get.docker.com | sh)
+echo "🎶 [3/6] Installing Docker Compose..." >> $LOG
+apt-get install -y docker-compose-v2
+"""
+
+    if is_dockerized:
+        script += """
+# --- DOCKERIZED DEPLOYMENT ---
+echo "📦 [4/6] Installing Caddy..." >> $LOG
+apt-get install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -LsSf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -LsSf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
+apt-get update
+apt-get install -y caddy
+
+echo "🚀 [5/6] Starting application with Docker Compose..." >> $LOG
+cd /root/app
+docker-compose -f /root/app/docker-compose.yml up -d
+
+echo "🔒 [6/6] Reloading Caddy..." >> $LOG
+# Caddy will automatically use the Caddyfile from the mounted volume in docker-compose
+# We just need to make sure it's running. Docker-compose handles this.
+# A system reload might be useful if Caddy was installed as a host service.
+systemctl reload caddy || systemctl start caddy
+"""
+    else:
+        # 3. Virtual Environment Setup (Non-Dockerized)
+        if project_type == "uv":
+            script += """
+# --- STANDARD NON-DOCKER DEPLOYMENT (UV) ---
+echo "⚡ [4/6] Installing UV..." >> $LOG
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.local/bin/env
+export PATH="/root/.local/bin:$PATH"
+
+echo "⚡ [5/6] Creating UV Venv..." >> $LOG
+uv venv /root/venv
+source /root/venv/bin/activate
+"""
+        else:
+            script += """
+# --- STANDARD NON-DOCKER DEPLOYMENT (PIP) ---
+echo "🐍 [4/6] Creating Python Venv..." >> $LOG
+python3 -m venv /root/venv
+source /root/venv/bin/activate
+echo "🐍 [5/6] Upgrading Pip..." >> $LOG
+pip install --upgrade pip
+"""
+        # 4. Install Packages (Non-Dockerized)
+        if packages:
+            if project_type == "uv":
+                script += f"""
+echo "📦 [6/6] UV Installing Deps: {packages}..." >> $LOG
+source /root/venv/bin/activate
+uv pip install {packages}
+"""
+            else:
+                script += f"""
+echo "📦 [6/6] Pip Installing Deps: {packages}..." >> $LOG
+source /root/venv/bin/activate
+pip install {packages}
+"""
+        else:
+            script += 'echo "ℹ️  [6/6] No packages detected." >> $LOG\n'
+
+    # Finish
+    script += """
+
+echo "✅ SETUP COMPLETE" >> $LOG
+touch /root/setup_complete
+"""
+    return script

xenfra-0.1.0/src/xenfra/utils.py

@@ -0,0 +1,69 @@
+import os
+import tomllib  # Python 3.11+
+
+def get_project_context():
+    """
+    Scans for project configuration.
+    Prioritizes: pyproject.toml > requirements.txt
+    Prioritizes: uv > poetry > pip
+    """
+    options = {}
+    
+    # 1. Check for Lockfiles (Determines the Manager)
+    if os.path.exists("uv.lock"):
+        options["uv"] = True
+    if os.path.exists("poetry.lock"):
+        options["poetry"] = True
+    
+    # 2. Extract Dependencies from pyproject.toml (Best source for names)
+    if os.path.exists("pyproject.toml"):
+        try:
+            with open("pyproject.toml", "rb") as f:
+                data = tomllib.load(f)
+                deps = data.get("project", {}).get("dependencies", [])
+                if deps:
+                    # Clean versions if needed, or just pass them to pip/uv
+                    options["toml"] = " ".join(deps)
+        except Exception:
+            pass
+
+    # 3. Extract Dependencies from requirements.txt (Fallback source)
+    if os.path.exists("requirements.txt"):
+        try:
+            with open("requirements.txt", "r") as f:
+                pkgs = [l.strip() for l in f if l.strip() and not l.startswith("#")]
+                if pkgs:
+                    options["pip"] = " ".join(pkgs)
+        except:
+            pass
+
+    # --- DECISION LOGIC ---
+    context = {"type": "pip", "packages": None, "conflict": False}
+    
+    # A. Determine the Manager (Type)
+    if "uv" in options:
+        context["type"] = "uv"
+    elif "poetry" in options:
+        context["type"] = "poetry"
+    else:
+        context["type"] = "pip"
+
+    # B. Determine the Packages (Content)
+    # We prefer TOML because it's the modern standard usually paired with UV/Poetry
+    if "toml" in options:
+        context["packages"] = options["toml"]
+    elif "pip" in options:
+        context["packages"] = options["pip"]
+
+    # C. Check for "True" Conflicts
+    # A conflict is when we have ambiguous package sources (TOML vs Requirements)
+    # AND we aren't sure which one the user wants.
+    if "toml" in options and "pip" in options:
+        # If we have both, we flag it so the UI can ask (or default to TOML)
+        context["conflict"] = True
+        context["choices"] = {
+            "1": {"name": "pyproject.toml", "pkgs": options["toml"]},
+            "2": {"name": "requirements.txt", "pkgs": options["pip"]}
+        }
+
+    return context