ptn 0.1.4__py3-none-any.whl

porterminal/config.py

@@ -0,0 +1,195 @@
+"""Configuration loading and validation using Pydantic."""
+
+import shutil
+import sys
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+
+class ServerConfig(BaseModel):
+    """Server configuration."""
+
+    host: str = "127.0.0.1"
+    port: int = Field(default=8000, ge=1, le=65535)
+
+
+class ShellConfig(BaseModel):
+    """Shell configuration."""
+
+    name: str
+    id: str
+    command: str
+    args: list[str] = Field(default_factory=list)
+
+    @field_validator("command")
+    @classmethod
+    def validate_command_exists(cls, v: str) -> str:
+        """Validate shell executable exists."""
+        # Check if it's a full path
+        path = Path(v)
+        if path.exists():
+            return v
+        # Check if it's in PATH
+        if shutil.which(v):
+            return v
+        raise ValueError(f"Shell executable not found: {v}")
+
+
+def detect_available_shells() -> list[ShellConfig]:
+    """Auto-detect available shells based on the platform."""
+    shells = []
+
+    if sys.platform == "win32":
+        # Windows shells
+        candidates = [
+            ("PowerShell", "powershell", "powershell.exe", ["-NoLogo"]),
+            ("PowerShell 7", "pwsh", "pwsh.exe", ["-NoLogo"]),
+            ("CMD", "cmd", "cmd.exe", []),
+            ("WSL", "wsl", "wsl.exe", []),
+            ("Git Bash", "gitbash", r"C:\Program Files\Git\bin\bash.exe", ["--login"]),
+        ]
+    else:
+        # Unix-like shells (Linux, macOS)
+        candidates = [
+            ("Bash", "bash", "bash", ["--login"]),
+            ("Zsh", "zsh", "zsh", ["--login"]),
+            ("Fish", "fish", "fish", []),
+            ("Sh", "sh", "sh", []),
+        ]
+
+    for name, shell_id, command, args in candidates:
+        # Check if shell exists
+        shell_path = shutil.which(command)
+        if shell_path or Path(command).exists():
+            shells.append(
+                ShellConfig(
+                    name=name,
+                    id=shell_id,
+                    command=shell_path or command,
+                    args=args,
+                )
+            )
+
+    return shells
+
+
+def get_default_shell_id() -> str:
+    """Get the default shell ID for the current platform."""
+    if sys.platform == "win32":
+        # Prefer PowerShell 7, then PowerShell, then CMD
+        if shutil.which("pwsh"):
+            return "pwsh"
+        if shutil.which("powershell"):
+            return "powershell"
+        return "cmd"
+    elif sys.platform == "darwin":
+        # macOS defaults to zsh
+        if shutil.which("zsh"):
+            return "zsh"
+        return "bash"
+    else:
+        # Linux - prefer bash
+        if shutil.which("bash"):
+            return "bash"
+        if shutil.which("zsh"):
+            return "zsh"
+        return "sh"
+
+
+class TerminalConfig(BaseModel):
+    """Terminal configuration."""
+
+    default_shell: str = ""
+    cols: int = Field(default=120, ge=40, le=500)
+    rows: int = Field(default=30, ge=10, le=200)
+    shells: list[ShellConfig] = Field(default_factory=list)
+
+    def get_shell(self, shell_id: str) -> ShellConfig | None:
+        """Get shell config by ID."""
+        for shell in self.shells:
+            if shell.id == shell_id:
+                return shell
+        return None
+
+
+class ButtonConfig(BaseModel):
+    """Custom button configuration."""
+
+    label: str
+    send: str
+
+
+class CloudflareConfig(BaseModel):
+    """Cloudflare Access configuration."""
+
+    team_domain: str = ""
+    access_aud: str = ""
+
+
+class Config(BaseModel):
+    """Application configuration."""
+
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    terminal: TerminalConfig = Field(default_factory=TerminalConfig)
+    buttons: list[ButtonConfig] = Field(default_factory=list)
+    cloudflare: CloudflareConfig = Field(default_factory=CloudflareConfig)
+
+
+def load_config(config_path: Path | str = "config.yaml") -> Config:
+    """Load configuration from YAML file."""
+    config_path = Path(config_path)
+
+    if not config_path.exists():
+        data = {}
+    else:
+        with open(config_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+
+    # Auto-detect shells if not specified or empty
+    terminal_data = data.get("terminal", {})
+    shells_data = terminal_data.get("shells", [])
+
+    # Filter out shells that don't exist on this system
+    valid_shells = []
+    for shell in shells_data:
+        try:
+            # Validate the shell exists
+            cmd = shell.get("command", "")
+            if shutil.which(cmd) or Path(cmd).exists():
+                valid_shells.append(shell)
+        except Exception:
+            pass
+
+    # If no valid shells from config, auto-detect
+    if not valid_shells:
+        detected = detect_available_shells()
+        terminal_data["shells"] = [s.model_dump() for s in detected]
+    else:
+        terminal_data["shells"] = valid_shells
+
+    # Auto-detect default shell if not specified or invalid
+    default_shell = terminal_data.get("default_shell", "")
+    shell_ids = [s.get("id") or s.get("name", "").lower() for s in terminal_data.get("shells", [])]
+    if not default_shell or default_shell not in shell_ids:
+        terminal_data["default_shell"] = get_default_shell_id()
+        # Make sure the default shell is in the list
+        if terminal_data["default_shell"] not in shell_ids and terminal_data.get("shells"):
+            terminal_data["default_shell"] = terminal_data["shells"][0].get("id", "")
+
+    data["terminal"] = terminal_data
+
+    return Config.model_validate(data)
+
+
+# Global config instance (loaded on import)
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get the global config instance."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config

porterminal/container.py

@@ -0,0 +1,65 @@
+"""Dependency container - holds all wired dependencies."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from porterminal.application.services import (
+    ManagementService,
+    SessionService,
+    TabService,
+    TerminalService,
+)
+from porterminal.domain import PTYPort, ShellCommand, TerminalDimensions
+from porterminal.domain.ports import SessionRepository, TabRepository
+
+if TYPE_CHECKING:
+    from porterminal.infrastructure.registry import UserConnectionRegistry
+
+
+@dataclass(frozen=True)
+class Container:
+    """Immutable dependency container.
+
+    All dependencies are wired at startup and cannot be modified.
+    This ensures thread-safety and predictable behavior.
+    """
+
+    # Services
+    session_service: SessionService
+    tab_service: TabService
+    terminal_service: TerminalService
+    management_service: ManagementService
+
+    # Repositories
+    session_repository: SessionRepository
+    tab_repository: TabRepository
+
+    # Registry for broadcasting
+    connection_registry: "UserConnectionRegistry"
+
+    # Factories
+    pty_factory: Callable[[ShellCommand, TerminalDimensions, dict[str, str], str | None], PTYPort]
+
+    # Configuration
+    available_shells: list[ShellCommand]
+    default_shell_id: str
+    server_host: str
+    server_port: int
+    default_cols: int
+    default_rows: int
+    buttons: list[dict]
+
+    # Working directory
+    cwd: str | None = None
+
+    def get_shell(self, shell_id: str | None = None) -> ShellCommand | None:
+        """Get shell by ID or default."""
+        target_id = shell_id or self.default_shell_id
+
+        for shell in self.available_shells:
+            if shell.id == target_id:
+                return shell
+
+        # Return first available if target not found
+        return self.available_shells[0] if self.available_shells else None

porterminal/domain/__init__.py

@@ -0,0 +1,91 @@
+"""Pure domain layer - no infrastructure dependencies."""
+
+# Value Objects
+# Entities
+from .entities import (
+    CLEAR_SCREEN_SEQUENCE,
+    MAX_SESSIONS_PER_USER,
+    MAX_TABS_PER_USER,
+    MAX_TOTAL_SESSIONS,
+    OUTPUT_BUFFER_MAX_BYTES,
+    OutputBuffer,
+    Session,
+    Tab,
+)
+
+# Ports
+from .ports import (
+    PTYFactory,
+    PTYPort,
+    SessionRepository,
+    TabRepository,
+)
+
+# Services
+from .services import (
+    Clock,
+    EnvironmentSanitizer,
+    SessionLimitChecker,
+    SessionLimitConfig,
+    SessionLimitResult,
+    TabLimitChecker,
+    TabLimitConfig,
+    TabLimitResult,
+    TokenBucketRateLimiter,
+)
+from .values import (
+    DEFAULT_BLOCKED_VARS,
+    DEFAULT_SAFE_VARS,
+    MAX_COLS,
+    MAX_ROWS,
+    MIN_COLS,
+    MIN_ROWS,
+    EnvironmentRules,
+    RateLimitConfig,
+    SessionId,
+    ShellCommand,
+    TabId,
+    TerminalDimensions,
+    UserId,
+)
+
+__all__ = [
+    # Values
+    "TerminalDimensions",
+    "MIN_COLS",
+    "MAX_COLS",
+    "MIN_ROWS",
+    "MAX_ROWS",
+    "SessionId",
+    "UserId",
+    "TabId",
+    "ShellCommand",
+    "RateLimitConfig",
+    "EnvironmentRules",
+    "DEFAULT_SAFE_VARS",
+    "DEFAULT_BLOCKED_VARS",
+    # Entities
+    "Session",
+    "MAX_SESSIONS_PER_USER",
+    "MAX_TOTAL_SESSIONS",
+    "OutputBuffer",
+    "OUTPUT_BUFFER_MAX_BYTES",
+    "CLEAR_SCREEN_SEQUENCE",
+    "Tab",
+    "MAX_TABS_PER_USER",
+    # Services
+    "TokenBucketRateLimiter",
+    "Clock",
+    "EnvironmentSanitizer",
+    "SessionLimitChecker",
+    "SessionLimitConfig",
+    "SessionLimitResult",
+    "TabLimitChecker",
+    "TabLimitConfig",
+    "TabLimitResult",
+    # Ports
+    "SessionRepository",
+    "TabRepository",
+    "PTYPort",
+    "PTYFactory",
+]

porterminal/domain/entities/__init__.py

@@ -0,0 +1,16 @@
+"""Domain entities - objects with identity and lifecycle."""
+
+from .output_buffer import CLEAR_SCREEN_SEQUENCE, OUTPUT_BUFFER_MAX_BYTES, OutputBuffer
+from .session import MAX_SESSIONS_PER_USER, MAX_TOTAL_SESSIONS, Session
+from .tab import MAX_TABS_PER_USER, Tab
+
+__all__ = [
+    "Session",
+    "MAX_SESSIONS_PER_USER",
+    "MAX_TOTAL_SESSIONS",
+    "OutputBuffer",
+    "OUTPUT_BUFFER_MAX_BYTES",
+    "CLEAR_SCREEN_SEQUENCE",
+    "Tab",
+    "MAX_TABS_PER_USER",
+]

porterminal/domain/entities/output_buffer.py

@@ -0,0 +1,73 @@
+"""Output buffer entity for session reconnection."""
+
+from collections import deque
+from dataclasses import dataclass, field
+
+# Business rules
+OUTPUT_BUFFER_MAX_BYTES = 1_000_000  # 1MB
+
+# Terminal escape sequence for clear screen (ED2)
+CLEAR_SCREEN_SEQUENCE = b"\x1b[2J"
+
+
+@dataclass
+class OutputBuffer:
+    """Output buffer for session reconnection.
+
+    Pure domain logic for buffering terminal output.
+    No async, no WebSocket - just data management.
+    """
+
+    max_bytes: int = OUTPUT_BUFFER_MAX_BYTES
+    _buffer: deque[bytes] = field(default_factory=deque)
+    _size: int = 0
+
+    @property
+    def size(self) -> int:
+        """Current buffer size in bytes."""
+        return self._size
+
+    @property
+    def is_empty(self) -> bool:
+        """Check if buffer is empty."""
+        return self._size == 0
+
+    def add(self, data: bytes) -> None:
+        """Add data to the buffer.
+
+        Handles clear screen detection and size limits.
+        When clear screen is detected, only keep content AFTER the last clear sequence.
+        """
+        # Check for clear screen sequence
+        if CLEAR_SCREEN_SEQUENCE in data:
+            # Clear old buffer
+            self.clear()
+            # Find the LAST occurrence of clear screen and only keep content after it
+            last_clear_pos = data.rfind(CLEAR_SCREEN_SEQUENCE)
+            data_after_clear = data[last_clear_pos + len(CLEAR_SCREEN_SEQUENCE) :]
+            # Only add if there's meaningful content after clear
+            if data_after_clear:
+                self._buffer.append(data_after_clear)
+                self._size += len(data_after_clear)
+            return
+
+        self._buffer.append(data)
+        self._size += len(data)
+
+        # Trim if over limit
+        while self._size > self.max_bytes and self._buffer:
+            removed = self._buffer.popleft()
+            self._size -= len(removed)
+
+    def get_all(self) -> bytes:
+        """Get all buffered output as single bytes object."""
+        return b"".join(self._buffer)
+
+    def clear(self) -> None:
+        """Clear the buffer."""
+        self._buffer.clear()
+        self._size = 0
+
+    def __len__(self) -> int:
+        """Return number of chunks in buffer."""
+        return len(self._buffer)

porterminal/domain/entities/session.py

@@ -0,0 +1,86 @@
+"""Session entity - pure domain representation."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TypeVar
+
+from ..values.session_id import SessionId
+from ..values.terminal_dimensions import TerminalDimensions
+from ..values.user_id import UserId
+from .output_buffer import OutputBuffer
+
+# Generic type for PTY handle - infrastructure provides concrete type
+PTYHandle = TypeVar("PTYHandle")
+
+# Business rule constants
+MAX_SESSIONS_PER_USER = 10
+MAX_TOTAL_SESSIONS = 100
+RECONNECT_WINDOW_SECONDS = 0  # 0 = unlimited
+SESSION_MAX_DURATION_SECONDS = 0  # 0 = unlimited
+
+
+@dataclass
+class Session[PTYHandle]:
+    """Terminal session entity.
+
+    This is the domain representation of a session.
+    It does NOT hold WebSocket or any infrastructure references.
+    The PTYHandle is a generic type provided by infrastructure.
+    """
+
+    id: SessionId
+    user_id: UserId
+    shell_id: str
+    dimensions: TerminalDimensions
+    created_at: datetime
+    last_activity: datetime
+
+    # PTY handle is generic - concrete type provided by infrastructure
+    pty_handle: PTYHandle
+
+    # Output buffer for reconnection
+    output_buffer: OutputBuffer = field(default_factory=OutputBuffer)
+
+    # Connection state (managed by application layer)
+    # Tracks number of connected clients (supports multi-client sessions)
+    connected_clients: int = 0
+
+    def add_client(self) -> int:
+        """Add a client connection, return new count."""
+        self.connected_clients += 1
+        return self.connected_clients
+
+    def remove_client(self) -> int:
+        """Remove a client connection, return new count."""
+        self.connected_clients = max(0, self.connected_clients - 1)
+        return self.connected_clients
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if any clients connected."""
+        return self.connected_clients > 0
+
+    def touch(self, now: datetime) -> None:
+        """Update last activity timestamp."""
+        self.last_activity = now
+
+    def update_dimensions(self, dimensions: TerminalDimensions) -> None:
+        """Update terminal dimensions."""
+        self.dimensions = dimensions
+
+    def add_output(self, data: bytes) -> None:
+        """Add output to buffer for reconnection."""
+        self.output_buffer.add(data)
+
+    def get_buffered_output(self) -> bytes:
+        """Get all buffered output."""
+        return self.output_buffer.get_all()
+
+    def clear_buffer(self) -> None:
+        """Clear the output buffer."""
+        self.output_buffer.clear()
+
+    @property
+    def session_id(self) -> str:
+        """Get session ID as string (compatibility helper)."""
+        return str(self.id)

porterminal/domain/entities/tab.py

@@ -0,0 +1,71 @@
+"""Tab entity - lightweight reference to a session."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ..values.session_id import SessionId
+from ..values.tab_id import TabId
+from ..values.user_id import UserId
+
+# Business rule constants
+MAX_TABS_PER_USER = 20
+TAB_NAME_MIN_LENGTH = 1
+TAB_NAME_MAX_LENGTH = 50
+
+
+@dataclass
+class Tab:
+    """Terminal tab entity.
+
+    Lightweight entity that references a session.
+    Does NOT hold PTY or any infrastructure references.
+
+    Invariants:
+    - Tab always references exactly one Session
+    - Tab is owned by exactly one User (same user who owns the Session)
+    - Tab name is 1-50 characters, non-empty
+    """
+
+    id: TabId
+    user_id: UserId
+    session_id: SessionId
+    shell_id: str
+    name: str
+    created_at: datetime
+    last_accessed: datetime
+
+    def __post_init__(self) -> None:
+        if not (TAB_NAME_MIN_LENGTH <= len(self.name) <= TAB_NAME_MAX_LENGTH):
+            raise ValueError(
+                f"Tab name must be {TAB_NAME_MIN_LENGTH}-{TAB_NAME_MAX_LENGTH} "
+                f"characters, got {len(self.name)}"
+            )
+
+    @property
+    def tab_id(self) -> str:
+        """String representation of tab ID."""
+        return str(self.id)
+
+    def touch(self, now: datetime) -> None:
+        """Update last accessed timestamp."""
+        self.last_accessed = now
+
+    def rename(self, new_name: str) -> None:
+        """Rename the tab with validation."""
+        if not (TAB_NAME_MIN_LENGTH <= len(new_name) <= TAB_NAME_MAX_LENGTH):
+            raise ValueError(
+                f"Tab name must be {TAB_NAME_MIN_LENGTH}-{TAB_NAME_MAX_LENGTH} "
+                f"characters, got {len(new_name)}"
+            )
+        self.name = new_name
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "id": str(self.id),
+            "session_id": str(self.session_id),
+            "shell_id": self.shell_id,
+            "name": self.name,
+            "created_at": self.created_at.isoformat(),
+            "last_accessed": self.last_accessed.isoformat(),
+        }

porterminal/domain/ports/__init__.py

@@ -0,0 +1,12 @@
+"""Domain ports - interfaces for infrastructure to implement."""
+
+from .pty_port import PTYFactory, PTYPort
+from .session_repository import SessionRepository
+from .tab_repository import TabRepository
+
+__all__ = [
+    "SessionRepository",
+    "TabRepository",
+    "PTYPort",
+    "PTYFactory",
+]

porterminal/domain/ports/pty_port.py

@@ -0,0 +1,80 @@
+"""PTY port - interface for PTY operations."""
+
+from abc import ABC, abstractmethod
+
+from ..values.shell_command import ShellCommand
+from ..values.terminal_dimensions import TerminalDimensions
+
+
+class PTYPort(ABC):
+    """Abstract interface for PTY operations.
+
+    Infrastructure provides platform-specific implementations.
+    """
+
+    @abstractmethod
+    def spawn(self) -> None:
+        """Spawn the PTY process."""
+        ...
+
+    @abstractmethod
+    def read(self, size: int = 4096) -> bytes:
+        """Read from PTY (non-blocking).
+
+        Returns empty bytes if no data available.
+        """
+        ...
+
+    @abstractmethod
+    def write(self, data: bytes) -> None:
+        """Write to PTY."""
+        ...
+
+    @abstractmethod
+    def resize(self, dimensions: TerminalDimensions) -> None:
+        """Resize PTY to new dimensions."""
+        ...
+
+    @abstractmethod
+    def is_alive(self) -> bool:
+        """Check if PTY process is still running."""
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close PTY and cleanup resources."""
+        ...
+
+    @property
+    @abstractmethod
+    def dimensions(self) -> TerminalDimensions:
+        """Get current terminal dimensions."""
+        ...
+
+
+class PTYFactory(ABC):
+    """Abstract interface for PTY creation.
+
+    Infrastructure provides platform-specific factory.
+    """
+
+    @abstractmethod
+    def create(
+        self,
+        shell: ShellCommand,
+        dimensions: TerminalDimensions,
+        environment: dict[str, str],
+        working_directory: str | None = None,
+    ) -> PTYPort:
+        """Create and spawn a new PTY.
+
+        Args:
+            shell: Shell command to run.
+            dimensions: Initial terminal dimensions.
+            environment: Sanitized environment variables.
+            working_directory: Optional working directory.
+
+        Returns:
+            PTY port implementation.
+        """
+        ...