fbuild 1.1.0__py3-none-any.whl

fbuild/daemon/client.py

@@ -0,0 +1,929 @@
+"""
+fbuild Daemon Client
+
+Client interface for requesting deploy and monitor operations from the daemon.
+Handles daemon lifecycle, request submission, and progress monitoring.
+"""
+
+import _thread
+import json
+import os
+import subprocess
+import sys
+import time
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+import psutil
+
+from fbuild.daemon.messages import (
+    BuildRequest,
+    DaemonState,
+    DaemonStatus,
+    DeployRequest,
+    MonitorRequest,
+)
+
+# Daemon configuration (must match daemon settings)
+DAEMON_NAME = "fbuild_daemon"
+DAEMON_DIR = Path.home() / ".fbuild" / "daemon"
+PID_FILE = DAEMON_DIR / f"{DAEMON_NAME}.pid"
+STATUS_FILE = DAEMON_DIR / "daemon_status.json"
+BUILD_REQUEST_FILE = DAEMON_DIR / "build_request.json"
+DEPLOY_REQUEST_FILE = DAEMON_DIR / "deploy_request.json"
+MONITOR_REQUEST_FILE = DAEMON_DIR / "monitor_request.json"
+
+
+def is_daemon_running() -> bool:
+    """Check if daemon is running, clean up stale PID files.
+
+    Returns:
+        True if daemon is running, False otherwise
+    """
+    if not PID_FILE.exists():
+        return False
+
+    try:
+        with open(PID_FILE) as f:
+            pid = int(f.read().strip())
+
+        # Check if process exists
+        if psutil.pid_exists(pid):
+            return True
+        else:
+            # Stale PID file - remove it
+            print(f"Removing stale PID file: {PID_FILE}")
+            PID_FILE.unlink()
+            return False
+    except KeyboardInterrupt:
+        _thread.interrupt_main()
+        raise
+    except Exception:
+        # Corrupted PID file - remove it
+        try:
+            PID_FILE.unlink(missing_ok=True)
+        except KeyboardInterrupt:
+            _thread.interrupt_main()
+            raise
+        except Exception:
+            pass
+        return False
+
+
+def start_daemon() -> None:
+    """Start the daemon process."""
+    daemon_script = Path(__file__).parent / "daemon.py"
+
+    if not daemon_script.exists():
+        raise RuntimeError(f"Daemon script not found: {daemon_script}")
+
+    # Start daemon in background
+    subprocess.Popen(
+        [sys.executable, str(daemon_script)],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+    )
+
+
+def read_status_file() -> DaemonStatus:
+    """Read current daemon status with corruption recovery.
+
+    Returns:
+        DaemonStatus object (or default status if file doesn't exist or corrupted)
+    """
+    if not STATUS_FILE.exists():
+        return DaemonStatus(
+            state=DaemonState.UNKNOWN,
+            message="Status file not found",
+            updated_at=time.time(),
+        )
+
+    try:
+        with open(STATUS_FILE) as f:
+            data = json.load(f)
+
+        # Parse into typed DaemonStatus
+        return DaemonStatus.from_dict(data)
+
+    except (json.JSONDecodeError, ValueError):
+        # Corrupted JSON - return default status
+        return DaemonStatus(
+            state=DaemonState.UNKNOWN,
+            message="Status file corrupted (invalid JSON)",
+            updated_at=time.time(),
+        )
+    except KeyboardInterrupt:
+        _thread.interrupt_main()
+        raise
+    except Exception:
+        return DaemonStatus(
+            state=DaemonState.UNKNOWN,
+            message="Failed to read status",
+            updated_at=time.time(),
+        )
+
+
+def write_request_file(request_file: Path, request: Any) -> None:
+    """Atomically write request file.
+
+    Args:
+        request_file: Path to request file
+        request: Request object (DeployRequest or MonitorRequest)
+    """
+    DAEMON_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Atomic write using temporary file
+    temp_file = request_file.with_suffix(".tmp")
+    with open(temp_file, "w") as f:
+        json.dump(request.to_dict(), f, indent=2)
+
+    # Atomic rename
+    temp_file.replace(request_file)
+
+
+def display_status(status: DaemonStatus, prefix: str = "  ") -> None:
+    """Display status update to user.
+
+    Args:
+        status: DaemonStatus object
+        prefix: Line prefix for indentation
+    """
+    # Show current operation if available, otherwise use message
+    display_text = status.current_operation or status.message
+
+    if status.state == DaemonState.DEPLOYING:
+        print(f"{prefix}📦 {display_text}", flush=True)
+    elif status.state == DaemonState.MONITORING:
+        print(f"{prefix}👁️  {display_text}", flush=True)
+    elif status.state == DaemonState.BUILDING:
+        print(f"{prefix}🔨 {display_text}", flush=True)
+    elif status.state == DaemonState.COMPLETED:
+        print(f"{prefix}✅ {display_text}", flush=True)
+    elif status.state == DaemonState.FAILED:
+        print(f"{prefix}❌ {display_text}", flush=True)
+    else:
+        print(f"{prefix}ℹ️  {display_text}", flush=True)
+
+
+def ensure_daemon_running() -> bool:
+    """Ensure daemon is running, start if needed.
+
+    Returns:
+        True if daemon is running or started successfully, False otherwise
+    """
+    if is_daemon_running():
+        return True
+
+    # If we reach here, daemon is not running (stale PID was cleaned by is_daemon_running)
+    # Clear stale status file to prevent race condition where client reads old status
+    # from previous daemon run before new daemon writes fresh status
+    if STATUS_FILE.exists():
+        try:
+            STATUS_FILE.unlink()
+        except KeyboardInterrupt:
+            _thread.interrupt_main()
+            raise
+        except Exception:
+            pass  # Best effort - continue even if delete fails
+
+    print("🔗 Starting fbuild daemon...")
+    start_daemon()
+
+    # Wait up to 10 seconds for daemon to start and write fresh status
+    for _ in range(10):
+        if is_daemon_running():
+            # Daemon is running - check if status file is fresh
+            status = read_status_file()
+            if status.state != DaemonState.UNKNOWN:
+                # Valid status received from new daemon
+                print("✅ Daemon started successfully")
+                return True
+        time.sleep(1)
+
+    print("❌ Failed to start daemon")
+    return False
+
+
+def request_build(
+    project_dir: Path,
+    environment: str,
+    clean_build: bool = False,
+    verbose: bool = False,
+    timeout: float = 1800,
+) -> bool:
+    """Request a build operation from the daemon.
+
+    Args:
+        project_dir: Project directory
+        environment: Build environment
+        clean_build: Whether to perform clean build
+        verbose: Enable verbose build output
+        timeout: Maximum wait time in seconds (default: 30 minutes)
+
+    Returns:
+        True if build successful, False otherwise
+    """
+    handler = BuildRequestHandler(
+        project_dir=project_dir,
+        environment=environment,
+        clean_build=clean_build,
+        verbose=verbose,
+        timeout=timeout,
+    )
+    return handler.execute()
+
+
+def _display_monitor_summary(project_dir: Path) -> None:
+    """Display monitor summary from JSON file.
+
+    Args:
+        project_dir: Project directory where summary file is located
+    """
+    summary_file = project_dir / ".fbuild" / "monitor_summary.json"
+    if not summary_file.exists():
+        return
+
+    try:
+        with open(summary_file, "r", encoding="utf-8") as f:
+            summary = json.load(f)
+
+        print("\n" + "=" * 50)
+        print("Monitor Summary")
+        print("=" * 50)
+
+        # Display expect pattern result
+        if summary.get("expect_pattern"):
+            pattern = summary["expect_pattern"]
+            found = summary.get("expect_found", False)
+            status = "FOUND ✓" if found else "NOT FOUND ✗"
+            print(f'Expected pattern: "{pattern}" - {status}')
+
+        # Display halt on error pattern result
+        if summary.get("halt_on_error_pattern"):
+            pattern = summary["halt_on_error_pattern"]
+            found = summary.get("halt_on_error_found", False)
+            status = "FOUND ✗" if found else "NOT FOUND ✓"
+            print(f'Error pattern: "{pattern}" - {status}')
+
+        # Display halt on success pattern result
+        if summary.get("halt_on_success_pattern"):
+            pattern = summary["halt_on_success_pattern"]
+            found = summary.get("halt_on_success_found", False)
+            status = "FOUND ✓" if found else "NOT FOUND ✗"
+            print(f'Success pattern: "{pattern}" - {status}')
+
+        # Display statistics
+        lines = summary.get("lines_processed", 0)
+        elapsed = summary.get("elapsed_time", 0.0)
+        exit_reason = summary.get("exit_reason", "unknown")
+
+        print(f"Lines processed: {lines}")
+        print(f"Time elapsed: {elapsed:.2f}s")
+
+        # Translate exit_reason to user-friendly text
+        reason_text = {
+            "timeout": "Timeout reached",
+            "expect_found": "Expected pattern found",
+            "halt_error": "Error pattern detected",
+            "halt_success": "Success pattern detected",
+            "interrupted": "Interrupted by user",
+            "error": "Serial port error",
+        }.get(exit_reason, exit_reason)
+
+        print(f"Exit reason: {reason_text}")
+        print("=" * 50)
+
+    except KeyboardInterrupt:  # noqa: KBI002
+        raise
+    except Exception:
+        # Silently fail - don't disrupt the user experience
+        pass
+
+
+# ============================================================================
+# REQUEST HANDLER ARCHITECTURE
+# ============================================================================
+
+
+class BaseRequestHandler(ABC):
+    """Base class for handling daemon requests with common functionality.
+
+    Implements the template method pattern to eliminate duplication across
+    build, deploy, and monitor request handlers.
+    """
+
+    def __init__(self, project_dir: Path, environment: str, timeout: float = 1800):
+        """Initialize request handler.
+
+        Args:
+            project_dir: Project directory
+            environment: Build environment
+            timeout: Maximum wait time in seconds (default: 30 minutes)
+        """
+        self.project_dir = project_dir
+        self.environment = environment
+        self.timeout = timeout
+        self.start_time = 0.0
+        self.last_message: str | None = None
+        self.monitoring_started = False
+        self.output_file_position = 0
+
+    @abstractmethod
+    def create_request(self) -> BuildRequest | DeployRequest | MonitorRequest:
+        """Create the specific request object.
+
+        Returns:
+            Request object (BuildRequest, DeployRequest, or MonitorRequest)
+        """
+        pass
+
+    @abstractmethod
+    def get_request_file(self) -> Path:
+        """Get the request file path.
+
+        Returns:
+            Path to request file
+        """
+        pass
+
+    @abstractmethod
+    def get_operation_name(self) -> str:
+        """Get the operation name for display.
+
+        Returns:
+            Operation name (e.g., "Build", "Deploy", "Monitor")
+        """
+        pass
+
+    @abstractmethod
+    def get_operation_emoji(self) -> str:
+        """Get the operation emoji for display.
+
+        Returns:
+            Operation emoji (e.g., "🔨", "📦", "👁️")
+        """
+        pass
+
+    def should_tail_output(self) -> bool:
+        """Check if output file should be tailed.
+
+        Returns:
+            True if output should be tailed, False otherwise
+        """
+        return False
+
+    def on_monitoring_started(self) -> None:
+        """Hook called when monitoring phase starts."""
+        pass
+
+    def on_completion(self, elapsed: float) -> None:
+        """Hook called on successful completion.
+
+        Args:
+            elapsed: Elapsed time in seconds
+        """
+        pass
+
+    def on_failure(self, status: DaemonStatus, elapsed: float) -> None:
+        """Hook called on failure.
+
+        Args:
+            status: Current daemon status
+            elapsed: Elapsed time in seconds
+        """
+        pass
+
+    def print_submission_info(self) -> None:
+        """Print request submission information."""
+        print(f"\n📤 Submitting {self.get_operation_name().lower()} request...")
+        print(f"   Project: {self.project_dir}")
+        print(f"   Environment: {self.environment}")
+
+    def tail_output_file(self) -> None:
+        """Tail the output file and print new lines."""
+        output_file = self.project_dir / ".fbuild" / "monitor_output.txt"
+        if output_file.exists():
+            try:
+                with open(output_file, "r", encoding="utf-8", errors="replace") as f:
+                    f.seek(self.output_file_position)
+                    new_lines = f.read()
+                    if new_lines:
+                        print(new_lines, end="", flush=True)
+                        self.output_file_position = f.tell()
+            except KeyboardInterrupt:  # noqa: KBI002
+                raise
+            except Exception:
+                pass  # Ignore read errors
+
+    def read_remaining_output(self) -> None:
+        """Read any remaining output from output file."""
+        if not self.monitoring_started:
+            return
+
+        output_file = self.project_dir / ".fbuild" / "monitor_output.txt"
+        if output_file.exists():
+            try:
+                with open(output_file, "r", encoding="utf-8", errors="replace") as f:
+                    f.seek(self.output_file_position)
+                    new_lines = f.read()
+                    if new_lines:
+                        print(new_lines, end="", flush=True)
+            except KeyboardInterrupt:  # noqa: KBI002
+                raise
+            except Exception:
+                pass
+
+    def handle_keyboard_interrupt(self, request_id: str) -> bool:
+        """Handle keyboard interrupt with background option.
+
+        Args:
+            request_id: Request ID for cancellation
+
+        Returns:
+            False (operation not completed or cancelled)
+        """
+        print("\n\n⚠️  Interrupted by user (Ctrl-C)")
+        response = input("Keep operation running in background? (y/n): ").strip().lower()
+
+        if response in ("y", "yes"):
+            print("\n✅ Operation continues in background")
+            print("   Check status: fbuild daemon status")
+            print("   Stop daemon: fbuild daemon stop")
+            return False
+        else:
+            print("\n🛑 Requesting daemon to stop operation...")
+            cancel_file = DAEMON_DIR / f"cancel_{request_id}.signal"
+            cancel_file.touch()
+            print("   Operation cancellation requested")
+            return False
+
+    def execute(self) -> bool:
+        """Execute the request and monitor progress.
+
+        Returns:
+            True if operation successful, False otherwise
+        """
+        # Ensure daemon is running
+        if not ensure_daemon_running():
+            return False
+
+        # Print submission info
+        self.print_submission_info()
+
+        # Create and submit request
+        request = self.create_request()
+        write_request_file(self.get_request_file(), request)
+        print(f"   Request ID: {request.request_id}")
+        print("   ✅ Submitted\n")
+
+        # Monitor progress
+        print(f"{self.get_operation_emoji()} {self.get_operation_name()} Progress:")
+        self.start_time = time.time()
+
+        while True:
+            try:
+                elapsed = time.time() - self.start_time
+
+                # Check timeout
+                if elapsed > self.timeout:
+                    print(f"\n❌ {self.get_operation_name()} timeout ({self.timeout}s)")
+                    return False
+
+                # Read status
+                status = read_status_file()
+
+                # Display progress when message changes
+                if status.message != self.last_message:
+                    display_status(status)
+                    self.last_message = status.message
+
+                # Handle monitoring phase
+                if self.should_tail_output() and status.state == DaemonState.MONITORING:
+                    if not self.monitoring_started:
+                        self.monitoring_started = True
+                        print()  # Blank line before serial output
+                        self.on_monitoring_started()
+
+                if self.monitoring_started and self.should_tail_output():
+                    self.tail_output_file()
+
+                # Check completion
+                if status.state == DaemonState.COMPLETED:
+                    if status.request_id == request.request_id:
+                        self.read_remaining_output()
+                        self.on_completion(elapsed)
+                        print(f"\n✅ {self.get_operation_name()} completed in {elapsed:.1f}s")
+                        return True
+
+                elif status.state == DaemonState.FAILED:
+                    if status.request_id == request.request_id:
+                        self.read_remaining_output()
+                        self.on_failure(status, elapsed)
+                        print(f"\n❌ {self.get_operation_name()} failed: {status.message}")
+                        return False
+
+                # Sleep before next poll
+                poll_interval = 0.1 if self.monitoring_started else 0.5
+                time.sleep(poll_interval)
+
+            except KeyboardInterrupt:  # noqa: KBI002
+                return self.handle_keyboard_interrupt(request.request_id)
+
+
+class BuildRequestHandler(BaseRequestHandler):
+    """Handler for build requests."""
+
+    def __init__(
+        self,
+        project_dir: Path,
+        environment: str,
+        clean_build: bool = False,
+        verbose: bool = False,
+        timeout: float = 1800,
+    ):
+        """Initialize build request handler.
+
+        Args:
+            project_dir: Project directory
+            environment: Build environment
+            clean_build: Whether to perform clean build
+            verbose: Enable verbose build output
+            timeout: Maximum wait time in seconds
+        """
+        super().__init__(project_dir, environment, timeout)
+        self.clean_build = clean_build
+        self.verbose = verbose
+
+    def create_request(self) -> BuildRequest:
+        """Create build request."""
+        return BuildRequest(
+            project_dir=str(self.project_dir.absolute()),
+            environment=self.environment,
+            clean_build=self.clean_build,
+            verbose=self.verbose,
+            caller_pid=os.getpid(),
+            caller_cwd=os.getcwd(),
+        )
+
+    def get_request_file(self) -> Path:
+        """Get build request file path."""
+        return BUILD_REQUEST_FILE
+
+    def get_operation_name(self) -> str:
+        """Get operation name."""
+        return "Build"
+
+    def get_operation_emoji(self) -> str:
+        """Get operation emoji."""
+        return "🔨"
+
+    def print_submission_info(self) -> None:
+        """Print build submission information."""
+        super().print_submission_info()
+        if self.clean_build:
+            print("   Clean build: Yes")
+
+
+class DeployRequestHandler(BaseRequestHandler):
+    """Handler for deploy requests."""
+
+    def __init__(
+        self,
+        project_dir: Path,
+        environment: str,
+        port: str | None = None,
+        clean_build: bool = False,
+        monitor_after: bool = False,
+        monitor_timeout: float | None = None,
+        monitor_halt_on_error: str | None = None,
+        monitor_halt_on_success: str | None = None,
+        monitor_expect: str | None = None,
+        timeout: float = 1800,
+    ):
+        """Initialize deploy request handler.
+
+        Args:
+            project_dir: Project directory
+            environment: Build environment
+            port: Serial port (optional)
+            clean_build: Whether to perform clean build
+            monitor_after: Whether to start monitor after deploy
+            monitor_timeout: Timeout for monitor
+            monitor_halt_on_error: Pattern to halt on error
+            monitor_halt_on_success: Pattern to halt on success
+            monitor_expect: Expected pattern to check
+            timeout: Maximum wait time in seconds
+        """
+        super().__init__(project_dir, environment, timeout)
+        self.port = port
+        self.clean_build = clean_build
+        self.monitor_after = monitor_after
+        self.monitor_timeout = monitor_timeout
+        self.monitor_halt_on_error = monitor_halt_on_error
+        self.monitor_halt_on_success = monitor_halt_on_success
+        self.monitor_expect = monitor_expect
+
+    def create_request(self) -> DeployRequest:
+        """Create deploy request."""
+        return DeployRequest(
+            project_dir=str(self.project_dir.absolute()),
+            environment=self.environment,
+            port=self.port,
+            clean_build=self.clean_build,
+            monitor_after=self.monitor_after,
+            monitor_timeout=self.monitor_timeout,
+            monitor_halt_on_error=self.monitor_halt_on_error,
+            monitor_halt_on_success=self.monitor_halt_on_success,
+            monitor_expect=self.monitor_expect,
+            caller_pid=os.getpid(),
+            caller_cwd=os.getcwd(),
+        )
+
+    def get_request_file(self) -> Path:
+        """Get deploy request file path."""
+        return DEPLOY_REQUEST_FILE
+
+    def get_operation_name(self) -> str:
+        """Get operation name."""
+        return "Deploy"
+
+    def get_operation_emoji(self) -> str:
+        """Get operation emoji."""
+        return "📦"
+
+    def should_tail_output(self) -> bool:
+        """Check if output should be tailed."""
+        return self.monitor_after
+
+    def print_submission_info(self) -> None:
+        """Print deploy submission information."""
+        super().print_submission_info()
+        if self.port:
+            print(f"   Port: {self.port}")
+
+    def on_completion(self, elapsed: float) -> None:
+        """Handle completion with monitor summary."""
+        if self.monitoring_started:
+            _display_monitor_summary(self.project_dir)
+
+    def on_failure(self, status: DaemonStatus, elapsed: float) -> None:
+        """Handle failure with monitor summary."""
+        if self.monitoring_started:
+            _display_monitor_summary(self.project_dir)
+
+
+class MonitorRequestHandler(BaseRequestHandler):
+    """Handler for monitor requests."""
+
+    def __init__(
+        self,
+        project_dir: Path,
+        environment: str,
+        port: str | None = None,
+        baud_rate: int | None = None,
+        halt_on_error: str | None = None,
+        halt_on_success: str | None = None,
+        expect: str | None = None,
+        timeout: float | None = None,
+    ):
+        """Initialize monitor request handler.
+
+        Args:
+            project_dir: Project directory
+            environment: Build environment
+            port: Serial port (optional)
+            baud_rate: Serial baud rate (optional)
+            halt_on_error: Pattern to halt on error
+            halt_on_success: Pattern to halt on success
+            expect: Expected pattern to check
+            timeout: Maximum monitoring time in seconds
+        """
+        super().__init__(project_dir, environment, timeout or 3600)
+        self.port = port
+        self.baud_rate = baud_rate
+        self.halt_on_error = halt_on_error
+        self.halt_on_success = halt_on_success
+        self.expect = expect
+        self.monitor_timeout = timeout
+
+    def create_request(self) -> MonitorRequest:
+        """Create monitor request."""
+        return MonitorRequest(
+            project_dir=str(self.project_dir.absolute()),
+            environment=self.environment,
+            port=self.port,
+            baud_rate=self.baud_rate,
+            halt_on_error=self.halt_on_error,
+            halt_on_success=self.halt_on_success,
+            expect=self.expect,
+            timeout=self.monitor_timeout,
+            caller_pid=os.getpid(),
+            caller_cwd=os.getcwd(),
+        )
+
+    def get_request_file(self) -> Path:
+        """Get monitor request file path."""
+        return MONITOR_REQUEST_FILE
+
+    def get_operation_name(self) -> str:
+        """Get operation name."""
+        return "Monitor"
+
+    def get_operation_emoji(self) -> str:
+        """Get operation emoji."""
+        return "👁️"
+
+    def should_tail_output(self) -> bool:
+        """Check if output should be tailed."""
+        return True
+
+    def print_submission_info(self) -> None:
+        """Print monitor submission information."""
+        super().print_submission_info()
+        if self.port:
+            print(f"   Port: {self.port}")
+        if self.baud_rate:
+            print(f"   Baud rate: {self.baud_rate}")
+        if self.monitor_timeout:
+            print(f"   Timeout: {self.monitor_timeout}s")
+
+    def on_completion(self, elapsed: float) -> None:
+        """Handle completion with monitor summary."""
+        if self.monitoring_started:
+            _display_monitor_summary(self.project_dir)
+
+    def on_failure(self, status: DaemonStatus, elapsed: float) -> None:
+        """Handle failure with monitor summary."""
+        if self.monitoring_started:
+            _display_monitor_summary(self.project_dir)
+
+
+def request_deploy(
+    project_dir: Path,
+    environment: str,
+    port: str | None = None,
+    clean_build: bool = False,
+    monitor_after: bool = False,
+    monitor_timeout: float | None = None,
+    monitor_halt_on_error: str | None = None,
+    monitor_halt_on_success: str | None = None,
+    monitor_expect: str | None = None,
+    timeout: float = 1800,
+) -> bool:
+    """Request a deploy operation from the daemon.
+
+    Args:
+        project_dir: Project directory
+        environment: Build environment
+        port: Serial port (optional, auto-detect if None)
+        clean_build: Whether to perform clean build
+        monitor_after: Whether to start monitor after deploy
+        monitor_timeout: Timeout for monitor (if monitor_after=True)
+        monitor_halt_on_error: Pattern to halt on error (if monitor_after=True)
+        monitor_halt_on_success: Pattern to halt on success (if monitor_after=True)
+        monitor_expect: Expected pattern to check at timeout/success (if monitor_after=True)
+        timeout: Maximum wait time in seconds (default: 30 minutes)
+
+    Returns:
+        True if deploy successful, False otherwise
+    """
+    handler = DeployRequestHandler(
+        project_dir=project_dir,
+        environment=environment,
+        port=port,
+        clean_build=clean_build,
+        monitor_after=monitor_after,
+        monitor_timeout=monitor_timeout,
+        monitor_halt_on_error=monitor_halt_on_error,
+        monitor_halt_on_success=monitor_halt_on_success,
+        monitor_expect=monitor_expect,
+        timeout=timeout,
+    )
+    return handler.execute()
+
+
+def request_monitor(
+    project_dir: Path,
+    environment: str,
+    port: str | None = None,
+    baud_rate: int | None = None,
+    halt_on_error: str | None = None,
+    halt_on_success: str | None = None,
+    expect: str | None = None,
+    timeout: float | None = None,
+) -> bool:
+    """Request a monitor operation from the daemon.
+
+    Args:
+        project_dir: Project directory
+        environment: Build environment
+        port: Serial port (optional, auto-detect if None)
+        baud_rate: Serial baud rate (optional)
+        halt_on_error: Pattern to halt on (error detection)
+        halt_on_success: Pattern to halt on (success detection)
+        expect: Expected pattern to check at timeout/success
+        timeout: Maximum monitoring time in seconds
+
+    Returns:
+        True if monitoring successful, False otherwise
+    """
+    handler = MonitorRequestHandler(
+        project_dir=project_dir,
+        environment=environment,
+        port=port,
+        baud_rate=baud_rate,
+        halt_on_error=halt_on_error,
+        halt_on_success=halt_on_success,
+        expect=expect,
+        timeout=timeout,
+    )
+    return handler.execute()
+
+
+def stop_daemon() -> bool:
+    """Stop the daemon gracefully.
+
+    Returns:
+        True if daemon was stopped, False otherwise
+    """
+    if not is_daemon_running():
+        print("Daemon is not running")
+        return False
+
+    # Create shutdown signal file
+    shutdown_file = DAEMON_DIR / "shutdown.signal"
+    shutdown_file.touch()
+
+    # Wait for daemon to exit
+    print("Stopping daemon...")
+    for _ in range(10):
+        if not is_daemon_running():
+            print("✅ Daemon stopped")
+            return True
+        time.sleep(1)
+
+    print("⚠️  Daemon did not stop gracefully")
+    return False
+
+
+def get_daemon_status() -> dict[str, Any]:
+    """Get current daemon status.
+
+    Returns:
+        Dictionary with daemon status information
+    """
+    status: dict[str, Any] = {
+        "running": is_daemon_running(),
+        "pid_file_exists": PID_FILE.exists(),
+        "status_file_exists": STATUS_FILE.exists(),
+    }
+
+    if PID_FILE.exists():
+        try:
+            with open(PID_FILE) as f:
+                status["pid"] = int(f.read().strip())
+        except KeyboardInterrupt:
+            _thread.interrupt_main()
+            raise
+        except Exception:
+            status["pid"] = None
+
+    if STATUS_FILE.exists():
+        daemon_status = read_status_file()
+        # Convert DaemonStatus to dict for JSON serialization
+        status["current_status"] = daemon_status.to_dict()
+
+    return status
+
+
+def main() -> int:
+    """Command-line interface for client."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="fbuild Daemon Client")
+    parser.add_argument("--status", action="store_true", help="Show daemon status")
+    parser.add_argument("--stop", action="store_true", help="Stop the daemon")
+
+    args = parser.parse_args()
+
+    if args.status:
+        status = get_daemon_status()
+        print("Daemon Status:")
+        print(json.dumps(status, indent=2))
+        return 0
+
+    if args.stop:
+        return 0 if stop_daemon() else 1
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:  # noqa: KBI002
+        print("\nInterrupted by user")
+        sys.exit(130)