terminaide 0.0.1__tar.gz

terminaide-0.0.1/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.1
+Name: terminaide
+Version: 0.0.1
+Summary: Serve Python CLI applications in the browser using ttyd
+Home-page: https://github.com/anotherbazeinthewall/terminaide
+License: MIT
+Author: Alex Basile
+Author-email: basileaw@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: chatline (>=0.0.5)
+Requires-Dist: fastapi (>=0.104.0)
+Requires-Dist: httpx (>=0.25.0)
+Requires-Dist: jinja2 (>=3.1.2)
+Requires-Dist: pydantic (>=2.4.2)
+Requires-Dist: uvicorn (>=0.24.0)
+Requires-Dist: websockets (>=12.0)
+Project-URL: Repository, https://github.com/anotherbazeinthewall/terminaide
+Description-Content-Type: text/markdown
+
+# terminaide
+
+A Python package for serving CLI applications in the browser using ttyd.
+
+## Installation
+
+```bash
+pip install terminaide
+```
+
+## Usage
+
+```python
+from fastapi import FastAPI
+from terminaide import serve_tty
+
+app = FastAPI()
+
+serve_tty(app, client_script="path/to/your/script.py")
+```
+
+## Development
+
+```bash
+# Install dependencies
+poetry install
+
+# Run test server
+poetry run python test-server/main.py
+```

terminaide-0.0.1/README.md

@@ -0,0 +1,30 @@
+# terminaide
+
+A Python package for serving CLI applications in the browser using ttyd.
+
+## Installation
+
+```bash
+pip install terminaide
+```
+
+## Usage
+
+```python
+from fastapi import FastAPI
+from terminaide import serve_tty
+
+app = FastAPI()
+
+serve_tty(app, client_script="path/to/your/script.py")
+```
+
+## Development
+
+```bash
+# Install dependencies
+poetry install
+
+# Run test server
+poetry run python test-server/main.py
+```

terminaide-0.0.1/pyproject.toml

@@ -0,0 +1,100 @@
+[tool.poetry]
+name = "terminaide"
+version = "0.0.1"
+description = "Serve Python CLI applications in the browser using ttyd"
+authors = ["Alex Basile <basileaw@gmail.com>"]
+packages = [{ include = "terminaide" }]
+readme = "README.md"
+repository = "https://github.com/anotherbazeinthewall/terminaide"
+license = "MIT"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+fastapi = ">=0.104.0"
+uvicorn = ">=0.24.0"
+jinja2 = ">=3.1.2"
+httpx = ">=0.25.0"
+websockets = ">=12.0"
+pydantic = ">=2.4.2"
+chatline = ">=0.0.5"
+
+[tool.poetry.group.test-server.dependencies]
+bs4 = ">=0.0.2"
+requests = ">=2.32.3"
+rich = "*"
+
+[tool.poetry.group.dev.dependencies]
+pyyaml = "*"
+boto3 = "*"
+botocore = "*"
+
+[tool.poe.tasks]
+serve-local = "python example/server.py"
+serve-container = "docker compose up --build"
+
+# Publish scripts
+check-changes = "bash -c 'if [ ! -z \"$(git status --porcelain)\" ]; then echo \"Error: You have uncommitted changes.\"; exit 1; fi'"
+
+publish-patch = """
+bash -c '
+  poe check-changes && \
+  git pull origin main && \
+  VERSION=$(poetry version -s) && \
+  if git rev-parse "v$VERSION" >/dev/null 2>&1; then \
+    echo "Error: Tag v$VERSION already exists" && exit 1; \
+  fi && \
+  poetry version patch && \
+  VERSION=$(poetry version -s) && \
+  poetry build && \
+  poetry publish && \
+  git add pyproject.toml && \
+  git commit -m "release v$VERSION" && \
+  git tag v$VERSION && \
+  git push origin main && \
+  git push origin --tags
+'
+"""
+
+publish-minor = """
+bash -c '
+  poe check-changes && \
+  git pull origin main && \
+  VERSION=$(poetry version -s) && \
+  if git rev-parse "v$VERSION" >/dev/null 2>&1; then \
+    echo "Error: Tag v$VERSION already exists" && exit 1; \
+  fi && \
+  poetry version minor && \
+  VERSION=$(poetry version -s) && \
+  poetry build && \
+  poetry publish && \
+  git add pyproject.toml && \
+  git commit -m "release v$VERSION" && \
+  git tag v$VERSION && \
+  git push origin main && \
+  git push origin --tags
+'
+"""
+
+publish-major = """
+bash -c '
+  poe check-changes && \
+  git pull origin main && \
+  VERSION=$(poetry version -s) && \
+  if git rev-parse "v$VERSION" >/dev/null 2>&1; then \
+    echo "Error: Tag v$VERSION already exists" && exit 1; \
+  fi && \
+  poetry version major && \
+  VERSION=$(poetry version -s) && \
+  poetry build && \
+  poetry publish && \
+  git add pyproject.toml && \
+  git commit -m "release v$VERSION" && \
+  git tag v$VERSION && \
+  git push origin main && \
+  git push origin --tags
+'
+"""

terminaide-0.0.1/terminaide/__init__.py

@@ -0,0 +1,148 @@
+# terminaide/__init__.py
+
+"""
+terminaide: Serve Python CLI applications in the browser using ttyd.
+
+This package provides tools to easily serve Python CLI applications through
+a browser-based terminal using ttyd. It handles binary installation and
+management automatically across supported platforms.
+
+Supported Platforms:
+- Linux x86_64 (Docker containers)
+- macOS ARM64 (Apple Silicon)
+"""
+
+import logging
+from fastapi import FastAPI
+from pathlib import Path
+from typing import Optional, Dict, Any, Union
+
+# Configure package-level logging
+logging.getLogger("terminaide").addHandler(logging.NullHandler())
+
+# Core functionality
+from .core.settings import TTYDConfig
+from .serve import serve_tty, _configure_app
+
+# Installation management
+from .installer import setup_ttyd, get_platform_info
+
+# Expose all exceptions
+from .exceptions import (
+    terminaideError,
+    BinaryError,
+    InstallationError,
+    PlatformNotSupportedError,
+    DependencyError,
+    DownloadError,
+    TTYDStartupError,
+    TTYDProcessError,
+    ClientScriptError,
+    TemplateError,
+    ProxyError,
+    ConfigurationError
+)
+
+__version__ = "0.2.0"  # Updated version number
+__all__ = [
+    # Main functionality
+    "serve_tty",
+    "TTYDConfig",
+    
+    # Binary management
+    "setup_ttyd",
+    "get_platform_info",
+    
+    # Exceptions
+    "terminaideError",
+    "BinaryError",
+    "InstallationError",
+    "PlatformNotSupportedError",
+    "DependencyError",
+    "DownloadError",
+    "TTYDStartupError",
+    "TTYDProcessError",
+    "ClientScriptError",
+    "TemplateError",
+    "ProxyError",
+    "ConfigurationError"
+]
+
+# Type aliases for better documentation
+ThemeConfig = Dict[str, str]
+TTYDOptions = Dict[str, Any]
+
+def serve_tty(
+    app: FastAPI,
+    client_script: Union[str, Path],
+    *,
+    mount_path: str = "/tty",
+    port: int = 7681,
+    theme: Optional[ThemeConfig] = None,
+    ttyd_options: Optional[TTYDOptions] = None,
+    template_override: Optional[Union[str, Path]] = None,
+    debug: bool = False
+) -> None:
+    """
+    Configure FastAPI application to serve a Python script through a browser-based terminal.
+
+    This function automatically handles ttyd binary installation and setup for the
+    current platform. Supported platforms are Linux x86_64 (for Docker) and
+    macOS ARM64 (Apple Silicon).
+
+    Args:
+        app: FastAPI application instance
+        client_script: Path to Python script to run in terminal
+        mount_path: URL path to mount terminal (default: "/tty")
+        port: Port for ttyd process (default: 7681)
+        theme: Terminal theme configuration (default: {"background": "black"})
+        ttyd_options: Additional ttyd process options
+        template_override: Custom HTML template path
+        debug: Enable development mode with auto-reload (default: False)
+
+    Raises:
+        InstallationError: If ttyd binary installation fails
+        PlatformNotSupportedError: If running on an unsupported platform
+        DependencyError: If required system libraries are missing
+        TTYDStartupError: If ttyd fails to start
+        ClientScriptError: If client script cannot be found or executed
+        ConfigurationError: If provided configuration values are invalid
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        from terminaide import serve_tty
+
+        app = FastAPI()
+        
+        # Basic usage
+        serve_tty(app, "client.py")
+
+        # Custom configuration
+        serve_tty(
+            app,
+            "client.py",
+            mount_path="/terminal",
+            theme={"background": "#1a1a1a"},
+            debug=True
+        )
+        ```
+
+    Notes:
+        - For Docker deployments, the package automatically handles ttyd installation
+        - Binary installation happens on first use and is cached for subsequent runs
+        - In Docker, required system libraries (libwebsockets, json-c) must be present
+    """
+    # Create configuration object
+    config = TTYDConfig(
+        client_script=client_script,
+        mount_path=mount_path,
+        port=port,
+        theme=theme or {"background": "black"},
+        ttyd_options=ttyd_options or {},
+        template_override=template_override,
+        debug=debug
+    )
+    
+    # Configure the application with our ttyd setup
+    _configure_app(app, config)

terminaide-0.0.1/terminaide/core/manager.py

@@ -0,0 +1,272 @@
+# terminaide/core/manager.py
+
+"""
+TTYd process management and lifecycle control.
+
+This module is responsible for starting, monitoring, and stopping the ttyd process.
+It ensures proper process cleanup and provides health monitoring capabilities.
+The manager adapts its behavior based on whether we're using root or non-root
+mounting configurations.
+"""
+
+import os
+import signal
+import logging
+import subprocess
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from ..exceptions import TTYDStartupError, TTYDProcessError
+from ..installer import setup_ttyd
+from .settings import TTYDConfig
+
+logger = logging.getLogger("terminaide")
+
+class TTYDManager:
+    """
+    Manages the lifecycle of the ttyd process.
+    
+    This class handles all aspects of the ttyd process, including:
+    - Process startup and shutdown
+    - Health monitoring
+    - Resource cleanup
+    - Signal handling
+    """
+    
+    def __init__(self, config: TTYDConfig):
+        """
+        Initialize the TTYDManager.
+
+        Args:
+            config: TTYDConfig instance with process configuration
+        """
+        self.config = config
+        self.process: Optional[subprocess.Popen] = None
+        self._start_time: Optional[datetime] = None
+        self._ttyd_path: Optional[Path] = None
+        self._setup_ttyd()
+
+    def _setup_ttyd(self) -> None:
+        """
+        Set up ttyd binary and verify it's ready to use.
+        
+        This method handles the installation and verification of the ttyd binary,
+        using our installer module to manage platform-specific binaries.
+        """
+        try:
+            self._ttyd_path = setup_ttyd()
+            logger.info(f"Using ttyd binary at: {self._ttyd_path}")
+        except Exception as e:
+            logger.error(f"Failed to set up ttyd: {e}")
+            raise TTYDStartupError(f"Failed to set up ttyd: {e}")
+
+    def _build_command(self) -> List[str]:
+        """
+        Build the ttyd command with all necessary arguments.
+        
+        This method constructs the command line arguments for ttyd based on
+        the current configuration, taking into account both root and non-root
+        mounting scenarios.
+        
+        Returns:
+            List of command arguments for ttyd process
+        """
+        if not self._ttyd_path:
+            raise TTYDStartupError("ttyd binary path not set")
+            
+        cmd = [str(self._ttyd_path)]
+        
+        # Basic configuration
+        cmd.extend(['-p', str(self.config.port)])
+        cmd.extend(['-i', self.config.ttyd_options.interface])
+        
+        # Security settings
+        if not self.config.ttyd_options.check_origin:
+            cmd.append('--no-check-origin')
+        
+        if self.config.ttyd_options.credential_required:
+            if not (self.config.ttyd_options.username and self.config.ttyd_options.password):
+                raise TTYDStartupError("Credentials required but not provided")
+            cmd.extend([
+                '-c', 
+                f"{self.config.ttyd_options.username}:{self.config.ttyd_options.password}"
+            ])
+        
+        # Debug mode settings
+        if self.config.debug:
+            cmd.extend(['-d', '3'])  # Maximum debug output
+        
+        # Terminal customization
+        theme_json = self.config.theme.model_dump_json()
+        cmd.extend(['-t', f'theme={theme_json}'])
+        
+        # Explicitly set writable or read-only mode
+        if self.config.ttyd_options.writable:
+            cmd.append('--writable')
+        else:
+            cmd.append('-R')
+        
+        # Add client script to run in the terminal
+        cmd.extend([
+            'python',
+            str(self.config.client_script)
+        ])
+        
+        return cmd
+
+    def start(self) -> None:
+        """
+        Start the ttyd process with the current configuration.
+        
+        This method launches ttyd with appropriate settings and monitors
+        its startup to ensure it's running correctly.
+
+        Raises:
+            TTYDStartupError: If process fails to start
+            TTYDProcessError: If process is already running
+        """
+        if self.is_running:
+            raise TTYDProcessError("TTYd process is already running")
+
+        cmd = self._build_command()
+        cmd_str = ' '.join(cmd)
+        logger.info(f"Starting ttyd with command: {cmd_str}")
+
+        try:
+            # Start the process in a new session to isolate signals
+            self.process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                start_new_session=True
+            )
+            self._start_time = datetime.now()
+
+            # Monitor startup with longer timeout in debug mode
+            timeout = 4 if self.config.debug else 2
+            check_interval = 0.1
+            checks = int(timeout / check_interval)
+
+            for _ in range(checks):
+                if self.process.poll() is not None:
+                    stderr = self.process.stderr.read().decode('utf-8')
+                    logger.error(f"ttyd failed to start. Error: {stderr}")
+                    raise TTYDStartupError(stderr=stderr)
+                    
+                if self.is_running:
+                    mount_type = "root" if self.config.is_root_mounted else "non-root"
+                    logger.info(
+                        f"ttyd process started successfully with PID {self.process.pid} "
+                        f"({mount_type} mounting)"
+                    )
+                    return
+                    
+                import time
+                time.sleep(check_interval)
+                
+            logger.error("ttyd process did not start within timeout")
+            raise TTYDStartupError("ttyd process did not start within timeout")
+
+        except subprocess.SubprocessError as e:
+            logger.error(f"Failed to start ttyd: {e}")
+            raise TTYDStartupError(str(e))
+
+    def stop(self) -> None:
+        """
+        Stop the ttyd process if it's running.
+        
+        This method ensures clean process termination using SIGTERM first,
+        followed by SIGKILL if necessary. It handles cases where the process
+        might have already been terminated.
+        """
+        if self.process:
+            logger.info("Stopping ttyd process...")
+            
+            try:
+                # Try graceful shutdown first
+                if os.name == 'nt':  # Windows
+                    self.process.terminate()
+                else:  # Unix-like
+                    try:
+                        pgid = os.getpgid(self.process.pid)
+                        os.killpg(pgid, signal.SIGTERM)
+                    except ProcessLookupError:
+                        # Process is already gone, which is fine
+                        pass
+
+                try:
+                    self.process.wait(timeout=5)  # Wait up to 5 seconds
+                except subprocess.TimeoutExpired:
+                    # Force kill if graceful shutdown fails
+                    if os.name == 'nt':
+                        self.process.kill()
+                    else:
+                        try:
+                            pgid = os.getpgid(self.process.pid)
+                            os.killpg(pgid, signal.SIGKILL)
+                        except ProcessLookupError:
+                            # Process is already gone, which is fine
+                            pass
+                    
+                    try:
+                        self.process.wait(timeout=1)
+                    except subprocess.TimeoutExpired:
+                        # If we still can't wait, the process is probably zombie or gone
+                        pass
+
+            except Exception as e:
+                logger.warning(f"Error during process cleanup: {e}")
+            
+            self.process = None
+            self._start_time = None
+            logger.info("ttyd process stopped successfully")
+
+    @property
+    def is_running(self) -> bool:
+        """Check if ttyd process is currently running."""
+        return bool(self.process and self.process.poll() is None)
+
+    @property
+    def uptime(self) -> Optional[float]:
+        """Get process uptime in seconds, if running."""
+        if self._start_time and self.is_running:
+            return (datetime.now() - self._start_time).total_seconds()
+        return None
+
+    def check_health(self) -> Dict[str, Any]:
+        """
+        Get comprehensive health check information about the process.
+        
+        Returns:
+            Dictionary containing process status, uptime, and configuration details
+        """
+        return {
+            "status": "running" if self.is_running else "stopped",
+            "uptime": self.uptime,
+            "pid": self.process.pid if self.process else None,
+            "mounting": "root" if self.config.is_root_mounted else "non-root",
+            "terminal_path": self.config.terminal_path,
+            "ttyd_path": str(self._ttyd_path) if self._ttyd_path else None,
+            **self.config.get_health_check_info()
+        }
+
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI):
+        """
+        Manage ttyd process lifecycle within FastAPI application.
+        
+        This context manager ensures proper startup and cleanup of the ttyd
+        process during the application lifecycle.
+        
+        Usage:
+            app = FastAPI(lifespan=manager.lifespan)
+        """
+        try:
+            self.start()
+            yield
+        finally:
+            self.stop()