fbuild 1.2.8__py3-none-any.whl

fbuild/daemon/status_manager.py

@@ -0,0 +1,238 @@
+"""
+Status Manager - Centralized status file management for daemon operations.
+
+This module provides the StatusManager class which handles all status file
+I/O operations with proper locking and atomic writes. It eliminates the
+scattered update_status() calls throughout daemon.py and provides a clean
+API for status management.
+"""
+
+import json
+import logging
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from fbuild.daemon.messages import DaemonState, DaemonStatus
+from fbuild.daemon.port_state_manager import PortStateManager
+from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+if TYPE_CHECKING:
+    from fbuild.daemon.lock_manager import ResourceLockManager
+
+
+class StatusManager:
+    """Manages daemon status file operations.
+
+    This class provides centralized management of the daemon status file,
+    ensuring:
+    - Atomic writes (write to temp file + rename)
+    - Thread-safe operations (internal locking)
+    - Consistent status structure
+    - Request ID validation
+
+    The status file is used for communication between the daemon and client,
+    allowing the client to monitor the progress of operations.
+
+    Example:
+        >>> manager = StatusManager(status_file_path, daemon_pid=1234)
+        >>> manager.update_status(
+        ...     DaemonState.BUILDING,
+        ...     "Building firmware",
+        ...     environment="esp32dev",
+        ...     project_dir="/path/to/project"
+        ... )
+        >>> status = manager.read_status()
+        >>> print(status.state)
+        DaemonState.BUILDING
+    """
+
+    def __init__(
+        self,
+        status_file: Path,
+        daemon_pid: int,
+        daemon_started_at: float | None = None,
+        port_state_manager: PortStateManager | None = None,
+        lock_manager: "ResourceLockManager | None" = None,
+    ):
+        """Initialize the StatusManager.
+
+        Args:
+            status_file: Path to the status file
+            daemon_pid: PID of the daemon process
+            daemon_started_at: Timestamp when daemon started (defaults to now)
+            port_state_manager: Optional PortStateManager for including port state in status
+            lock_manager: Optional ResourceLockManager for including lock state in status
+        """
+        self.status_file = status_file
+        self.daemon_pid = daemon_pid
+        self.daemon_started_at = daemon_started_at if daemon_started_at is not None else time.time()
+        self._lock = threading.Lock()
+        self._operation_in_progress = False
+        self._port_state_manager = port_state_manager
+        self._lock_manager = lock_manager
+
+        # Ensure parent directory exists
+        self.status_file.parent.mkdir(parents=True, exist_ok=True)
+
+    def update_status(
+        self,
+        state: DaemonState,
+        message: str,
+        operation_in_progress: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Update the status file with current daemon state.
+
+        This method is thread-safe and performs atomic writes to prevent
+        corruption during concurrent access.
+
+        Args:
+            state: DaemonState enum value
+            message: Human-readable status message
+            operation_in_progress: Whether an operation is in progress (None = use current value)
+            **kwargs: Additional fields to include in status (e.g., environment, project_dir)
+
+        Example:
+            >>> manager.update_status(
+            ...     DaemonState.BUILDING,
+            ...     "Building firmware",
+            ...     environment="esp32dev",
+            ...     project_dir="/path/to/project",
+            ...     request_id="build_1234567890",
+            ... )
+        """
+        with self._lock:
+
+            # Update internal operation state if provided
+            if operation_in_progress is not None:
+                self._operation_in_progress = operation_in_progress
+
+            # Get port state summary if port_state_manager is available
+            ports_summary: dict[str, Any] = {}
+            if self._port_state_manager is not None:
+                ports_summary = self._port_state_manager.get_ports_summary()
+
+            # Get lock state summary if lock_manager is available
+            locks_summary: dict[str, Any] = {}
+            if self._lock_manager is not None:
+                locks_summary = self._lock_manager.get_lock_details()
+
+            # Create typed DaemonStatus object
+            status_obj = DaemonStatus(
+                state=state,
+                message=message,
+                updated_at=time.time(),
+                daemon_pid=self.daemon_pid,
+                daemon_started_at=self.daemon_started_at,
+                operation_in_progress=self._operation_in_progress,
+                ports=ports_summary,
+                locks=locks_summary,
+                **kwargs,
+            )
+
+            logging.debug(f"Writing status to file (additional fields: {len(kwargs)})")
+            self._write_status_atomic(status_obj.to_dict())
+
+    def read_status(self) -> DaemonStatus:
+        """Read and parse the status file.
+
+        Returns:
+            DaemonStatus object with current daemon state
+
+        If the file doesn't exist or is corrupted, returns a default status
+        indicating the daemon is idle.
+        """
+        with self._lock:
+            if not self.status_file.exists():
+                return self._get_default_status()
+
+            try:
+                with open(self.status_file, encoding="utf-8") as f:
+                    data = json.load(f)
+
+                status = DaemonStatus.from_dict(data)
+                return status
+
+            except KeyboardInterrupt as ke:
+                handle_keyboard_interrupt_properly(ke)
+            except (json.JSONDecodeError, ValueError) as e:
+                logging.warning(f"Corrupted status file detected: {e}")
+                logging.warning("Creating fresh status file")
+
+                # Write fresh status file
+                default_status = self._get_default_status()
+                self._write_status_atomic(default_status.to_dict())
+                return default_status
+
+            except Exception as e:
+                logging.error(f"Unexpected error reading status file: {e}")
+                default_status = self._get_default_status()
+                self._write_status_atomic(default_status.to_dict())
+                return default_status
+
+    def set_operation_in_progress(self, in_progress: bool) -> None:
+        """Set the operation_in_progress flag.
+
+        This is used to track whether the daemon is currently executing
+        an operation. It's typically set to True when starting an operation
+        and False when completing or failing.
+
+        Args:
+            in_progress: Whether an operation is in progress
+        """
+        with self._lock:
+            self._operation_in_progress = in_progress
+
+    def get_operation_in_progress(self) -> bool:
+        """Get the current operation_in_progress flag.
+
+        Returns:
+            True if an operation is in progress, False otherwise
+        """
+        with self._lock:
+            return self._operation_in_progress
+
+    def _write_status_atomic(self, status: dict[str, Any]) -> None:
+        """Write status file atomically to prevent corruption during writes.
+
+        This method writes to a temporary file first, then atomically renames
+        it to the actual status file. This ensures the status file is never
+        in a partially-written state.
+
+        Args:
+            status: Status dictionary to write
+        """
+        temp_file = self.status_file.with_suffix(".tmp")
+        logging.debug(f"Using temp file: {temp_file}")
+
+        try:
+            logging.debug(f"Writing JSON to temp file ({len(status)} keys)...")
+            with open(temp_file, "w", encoding="utf-8") as f:
+                json.dump(status, f, indent=2)
+            # Atomic rename
+            temp_file.replace(self.status_file)
+
+        except KeyboardInterrupt:  # noqa: KBI002
+            logging.warning("KeyboardInterrupt during status file write, cleaning up temp file")
+            temp_file.unlink(missing_ok=True)
+            raise
+        except Exception as e:
+            logging.error(f"Failed to write status file: {e}")
+            temp_file.unlink(missing_ok=True)
+
+    def _get_default_status(self) -> DaemonStatus:
+        """Get default idle status.
+
+        Returns:
+            DaemonStatus object indicating daemon is idle
+        """
+        return DaemonStatus(
+            state=DaemonState.IDLE,
+            message="Daemon is idle",
+            updated_at=time.time(),
+            daemon_pid=self.daemon_pid,
+            daemon_started_at=self.daemon_started_at,
+            operation_in_progress=False,
+        )

fbuild/daemon/subprocess_manager.py

@@ -0,0 +1,316 @@
+"""Centralized subprocess execution manager for daemon operations.
+
+This module provides a unified interface for executing subprocesses with tracking,
+logging, and statistics. All subprocess calls should go through this manager for
+consistent error handling and monitoring.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+from ..interrupt_utils import handle_keyboard_interrupt_properly
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SubprocessExecution:
+    """Single subprocess execution with full tracking."""
+
+    execution_id: str
+    command: list[str]
+    cwd: Optional[Path]
+    env: Optional[dict[str, str]]
+    timeout: Optional[float]
+    returncode: Optional[int] = None
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None
+    start_time: Optional[float] = None
+    end_time: Optional[float] = None
+    error: Optional[str] = None
+
+    def duration(self) -> Optional[float]:
+        """Calculate execution duration in seconds."""
+        if self.start_time and self.end_time:
+            return self.end_time - self.start_time
+        return None
+
+    def success(self) -> bool:
+        """Check if execution was successful."""
+        return self.returncode == 0 and self.error is None
+
+
+class SubprocessManager:
+    """Centralized subprocess execution manager.
+
+    Provides tracking, logging, and statistics for all subprocess executions
+    in the daemon. Thread-safe for concurrent use.
+    """
+
+    def __init__(self, max_history: int = 1000):
+        """Initialize subprocess manager.
+
+        Args:
+            max_history: Maximum number of executions to keep in history
+        """
+        self.executions: dict[str, SubprocessExecution] = {}
+        self.lock = threading.Lock()
+        self.max_history = max_history
+        self._execution_counter = 0
+        logger.info(f"SubprocessManager initialized successfully (max_history={max_history})")
+
+    def execute(
+        self,
+        command: list[str],
+        cwd: Optional[Path] = None,
+        env: Optional[dict[str, str]] = None,
+        timeout: Optional[float] = 60,
+        capture_output: bool = True,
+        check: bool = False,
+    ) -> SubprocessExecution:
+        """Execute subprocess with tracking.
+
+        Args:
+            command: Command and arguments to execute
+            cwd: Working directory for subprocess
+            env: Environment variables
+            timeout: Timeout in seconds (None = no timeout)
+            capture_output: Whether to capture stdout/stderr
+            check: Whether to raise exception on non-zero exit code
+
+        Returns:
+            SubprocessExecution with results and timing information
+        """
+        # Generate unique execution ID
+        with self.lock:
+            self._execution_counter += 1
+            execution_id = f"subprocess_{int(time.time() * 1000000)}_{self._execution_counter}"
+        logger.debug(f"Subprocess command: {' '.join(str(c) for c in command)}")
+        logger.debug(f"Environment variables: {len(env) if env else 0} vars")
+        logger.debug(f"Capture output: {capture_output}")
+
+        execution = SubprocessExecution(
+            execution_id=execution_id,
+            command=command,
+            cwd=cwd,
+            env=env,
+            timeout=timeout,
+            start_time=time.time(),
+        )
+
+        # Store execution
+        with self.lock:
+            self.executions[execution_id] = execution
+            logger.debug(f"Stored execution {execution_id} in history (total: {len(self.executions)})")
+            self._cleanup_old_executions()
+
+        # Log execution start
+        cmd_str = " ".join(str(c) for c in command[:3])  # First 3 args
+        if len(command) > 3:
+            cmd_str += "..."
+        logger.info(f"Starting subprocess {execution_id}: {cmd_str}")
+
+        try:
+            # Execute subprocess
+            logger.debug(f"Executing subprocess.run() for {execution_id}")
+            result = subprocess.run(
+                command,
+                cwd=cwd,
+                env=env,
+                capture_output=capture_output,
+                text=True,
+                timeout=timeout,
+                check=check,
+            )
+            execution.returncode = result.returncode
+            execution.stdout = result.stdout if capture_output else None
+            execution.stderr = result.stderr if capture_output else None
+            execution.end_time = time.time()
+
+            # Log output details
+            if capture_output:
+                logger.debug(f"Subprocess {execution_id} stdout: {len(result.stdout) if result.stdout else 0} bytes")
+                logger.debug(f"Subprocess {execution_id} stderr: {len(result.stderr) if result.stderr else 0} bytes")
+
+            # Log result
+            duration = execution.duration()
+            if result.returncode == 0:
+                logger.info(f"Subprocess {execution_id}: SUCCESS in {duration:.2f}s")
+            else:
+                logger.warning(f"Subprocess {execution_id}: FAILED with code {result.returncode} in {duration:.2f}s")
+                if result.stderr and capture_output:
+                    logger.debug(f"Subprocess {execution_id} stderr: {result.stderr[:200]}")
+
+        except subprocess.TimeoutExpired as e:
+            logger.error(f"Subprocess {execution_id}: TIMEOUT after {timeout}s")
+            execution.error = f"Timeout after {timeout}s"
+            execution.returncode = -1
+            execution.stderr = str(e)
+            execution.end_time = time.time()
+
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Subprocess {execution_id}: CalledProcessError with exit code {e.returncode}")
+            execution.error = f"Process failed with exit code {e.returncode}"
+            execution.returncode = e.returncode
+            execution.stdout = e.stdout if capture_output else None
+            execution.stderr = e.stderr if capture_output else None
+            execution.end_time = time.time()
+
+        except KeyboardInterrupt as ke:
+            logger.warning(f"Subprocess {execution_id}: KeyboardInterrupt received")
+            handle_keyboard_interrupt_properly(ke)
+
+        except Exception as e:
+            logger.error(f"Subprocess {execution_id}: Unexpected exception: {e}", exc_info=True)
+            execution.error = str(e)
+            execution.returncode = -1
+            execution.end_time = time.time()
+
+        logger.debug(f"Returning execution result for {execution_id} (success={execution.success()})")
+        return execution
+
+    def get_execution(self, execution_id: str) -> Optional[SubprocessExecution]:
+        """Get execution by ID.
+
+        Args:
+            execution_id: Execution ID to retrieve
+
+        Returns:
+            SubprocessExecution if found, None otherwise
+        """
+        with self.lock:
+            execution = self.executions.get(execution_id)
+            if execution:
+                logger.debug(f"Found execution {execution_id} (success={execution.success()})")
+            else:
+                logger.debug(f"Execution {execution_id} not found")
+            return execution
+
+    def get_statistics(self) -> dict[str, Any]:
+        """Get subprocess execution statistics.
+
+        Returns:
+            Dictionary with execution counts and statistics
+        """
+        with self.lock:
+            total = len(self.executions)
+            successful = sum(1 for e in self.executions.values() if e.success())
+            failed = sum(1 for e in self.executions.values() if not e.success())
+
+            # Calculate average duration for successful executions
+            successful_durations: list[float] = []
+            for e in self.executions.values():
+                if e.success():
+                    duration = e.duration()
+                    if duration is not None:
+                        successful_durations.append(duration)
+            avg_duration = sum(successful_durations) / len(successful_durations) if successful_durations else 0.0
+
+            logger.debug(f"Average execution duration: {avg_duration:.3f}s (from {len(successful_durations)} successful executions)")
+
+            success_rate = (successful / total * 100) if total > 0 else 0.0
+            logger.info(f"Subprocess statistics: {successful}/{total} successful ({success_rate:.1f}% success rate)")
+
+            return {
+                "total_executions": total,
+                "successful": successful,
+                "failed": failed,
+                "average_duration_seconds": round(avg_duration, 3),
+            }
+
+    def get_recent_failures(self, count: int = 10) -> list[SubprocessExecution]:
+        """Get most recent failed executions.
+
+        Args:
+            count: Maximum number of failures to return
+
+        Returns:
+            List of failed SubprocessExecution objects
+        """
+        with self.lock:
+            failures = [e for e in self.executions.values() if not e.success()]
+            logger.debug(f"Found {len(failures)} total failures in history")
+            # Sort by end_time descending (most recent first)
+            failures.sort(key=lambda e: e.end_time or 0, reverse=True)
+            result = failures[:count]
+            logger.debug(f"Returning {len(result)} most recent failures")
+            if result:
+                logger.info(f"Recent subprocess failures: {len(result)} failures found")
+            return result
+
+    def clear_history(self):
+        """Clear all execution history."""
+        with self.lock:
+            count = len(self.executions)
+            self.executions.clear()
+            logger.info(f"Subprocess execution history cleared ({count} records removed)")
+
+    def _cleanup_old_executions(self):
+        """Remove old executions beyond max_history limit.
+
+        Keeps successful executions to max_history, but always keeps all recent failures.
+        """
+        current_count = len(self.executions)
+        if current_count <= self.max_history:
+            return
+
+        # Get all executions sorted by end time
+        all_executions = sorted(self.executions.values(), key=lambda e: e.end_time or 0)
+        logger.debug(f"Sorted {len(all_executions)} executions by end time")
+
+        # Keep all failures and recent successes
+        successes = [e for e in all_executions if e.success()]
+        failures = [e for e in all_executions if not e.success()]
+        logger.debug(f"Execution breakdown: {len(successes)} successes, {len(failures)} failures")
+
+        # Remove oldest successes if we're over limit
+        to_remove = len(self.executions) - self.max_history
+        if to_remove > 0 and len(successes) > to_remove:
+            for execution in successes[:to_remove]:
+                del self.executions[execution.execution_id]
+
+            logger.info(f"Cleaned up {to_remove} old successful subprocess executions (history now: {len(self.executions)})")
+        else:
+            logger.debug(f"Cannot remove {to_remove} executions (only {len(successes)} successes available)")
+
+
+# Global subprocess manager instance (initialized by daemon)
+_subprocess_manager: Optional[SubprocessManager] = None
+
+
+def get_subprocess_manager() -> SubprocessManager:
+    """Get global subprocess manager instance.
+
+    Returns:
+        Global SubprocessManager instance
+
+    Raises:
+        RuntimeError: If subprocess manager not initialized
+    """
+    global _subprocess_manager
+    if _subprocess_manager is None:
+        logger.error("SubprocessManager accessed before initialization")
+        raise RuntimeError("SubprocessManager not initialized. Call init_subprocess_manager() first.")
+    return _subprocess_manager
+
+
+def init_subprocess_manager(max_history: int = 1000) -> SubprocessManager:
+    """Initialize global subprocess manager.
+
+    Args:
+        max_history: Maximum number of executions to keep in history
+
+    Returns:
+        Initialized SubprocessManager instance
+    """
+    global _subprocess_manager
+    _subprocess_manager = SubprocessManager(max_history=max_history)
+    logger.info("Global SubprocessManager initialized successfully")
+    return _subprocess_manager

fbuild/deploy/__init__.py

@@ -0,0 +1,21 @@
+"""
+Firmware deployment functionality for fbuild.
+
+This module provides deployment capabilities for uploading firmware to devices.
+"""
+
+from .deployer import DeploymentError, DeploymentResult, IDeployer
+from .deployer_esp32 import ESP32Deployer
+from .monitor import SerialMonitor
+from .qemu_runner import QEMURunner, check_docker_available, map_board_to_machine
+
+__all__ = [
+    "IDeployer",
+    "ESP32Deployer",
+    "DeploymentResult",
+    "DeploymentError",
+    "SerialMonitor",
+    "QEMURunner",
+    "check_docker_available",
+    "map_board_to_machine",
+]

fbuild/deploy/deployer.py

@@ -0,0 +1,67 @@
+"""Abstract base class for firmware deployers.
+
+This module defines the interface for platform-specific deployers
+to ensure consistent behavior across different platforms.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class DeploymentResult:
+    """Result of a firmware deployment operation."""
+
+    success: bool
+    message: str
+    port: Optional[str] = None
+
+
+class DeploymentError(Exception):
+    """Base exception for deployment errors."""
+
+    pass
+
+
+class IDeployer(ABC):
+    """Interface for firmware deployers.
+
+    Deployers handle uploading firmware to embedded devices:
+    1. Locate firmware binaries
+    2. Detect or validate serial port
+    3. Flash firmware to device
+    4. Verify upload success
+    """
+
+    @abstractmethod
+    def deploy(
+        self,
+        project_dir: Path,
+        env_name: str,
+        port: Optional[str] = None,
+    ) -> DeploymentResult:
+        """Deploy firmware to a device.
+
+        Args:
+            project_dir: Path to project directory
+            env_name: Environment name to deploy
+            port: Serial port to use (auto-detect if None)
+
+        Returns:
+            DeploymentResult with success status and message
+
+        Raises:
+            DeploymentError: If deployment fails
+        """
+        pass
+
+    @abstractmethod
+    def _detect_serial_port(self) -> Optional[str]:
+        """Auto-detect serial port for device.
+
+        Returns:
+            Serial port name or None if not found
+        """
+        pass