ptn 0.1.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

porterminal/__init__.py

@@ -8,7 +8,10 @@ This package provides:
 - Configuration system with shell auto-detection
 """
 
-__version__ = "0.1.4"
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0-dev"  # Fallback before first build
 
 import os
 import subprocess
@@ -139,6 +142,11 @@ def _run_in_background(args) -> int:
 def main() -> int:
     """Main entry point."""
     args = parse_args()
+
+    # Check for updates (notification only, never exec's)
+    from porterminal.updater import check_and_notify
+
+    check_and_notify()
     verbose = args.verbose
 
     # Handle background mode
@@ -257,10 +265,18 @@ def main() -> int:
     try:
         while True:
             if server_process is not None and server_process.poll() is not None:
-                console.print("\n[red]Server stopped unexpectedly[/red]")
+                code = server_process.returncode
+                if code == 0 or code < 0:
+                    console.print("\n[dim]Server stopped[/dim]")
+                else:
+                    console.print(f"\n[yellow]Server stopped (exit code {code})[/yellow]")
                 break
             if tunnel_process is not None and tunnel_process.poll() is not None:
-                console.print("\n[red]Tunnel stopped unexpectedly[/red]")
+                code = tunnel_process.returncode
+                if code == 0 or code < 0:
+                    console.print("\n[dim]Tunnel closed[/dim]")
+                else:
+                    console.print(f"\n[yellow]Tunnel stopped (exit code {code})[/yellow]")
                 break
             time.sleep(1)
 

porterminal/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.2.5'
+__version_tuple__ = version_tuple = (0, 2, 5)
+
+__commit_id__ = commit_id = None

porterminal/app.py

@@ -13,6 +13,7 @@ from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.middleware.base import RequestResponseEndpoint
 
+from . import __version__
 from .composition import create_container
 from .container import Container
 from .domain import UserId
@@ -51,10 +52,10 @@ async def lifespan(app: FastAPI):
     security_preflight_checks()
 
     # Create DI container with all wired dependencies
-    config_path = os.environ.get("PORTERMINAL_CONFIG_PATH", "config.yaml")
+    # config_path=None uses find_config_file() to search standard locations
     cwd = os.environ.get("PORTERMINAL_CWD")
 
-    container = create_container(config_path=config_path, cwd=cwd)
+    container = create_container(config_path=None, cwd=cwd)
     app.state.container = container
 
     # Wire up cascade: when session is destroyed, close associated tabs and broadcast
@@ -82,7 +83,7 @@ def create_app() -> FastAPI:
     app = FastAPI(
         title="Porterminal",
         description="Web-based terminal accessible from phone via Cloudflare Tunnel",
-        version="0.1.2",
+        version=__version__,
         lifespan=lifespan,
     )
 
@@ -339,13 +340,16 @@ def create_app() -> FastAPI:
             # Register connection for broadcasts
             await connection_registry.register(user_id, connection)
 
-            # Send session info
+            # Send session info including current dimensions
+            # New clients should adapt to existing dimensions to prevent rendering issues
             await connection.send_message(
                 {
                     "type": "session_info",
                     "session_id": session.session_id,
                     "shell": session.shell_id,
                     "tab_id": tab.tab_id,
+                    "cols": session.dimensions.cols,
+                    "rows": session.dimensions.rows,
                 }
             )
 

porterminal/application/services/terminal_service.py

@@ -63,11 +63,23 @@ class TerminalService:
         # Multi-client support: track connections and read loops per session
         self._session_connections: dict[str, set[ConnectionPort]] = {}
         self._session_read_tasks: dict[str, asyncio.Task[None]] = {}
+        # Per-session locks to prevent race between buffer replay and broadcast
+        self._session_locks: dict[str, asyncio.Lock] = {}
 
     # -------------------------------------------------------------------------
     # Multi-client connection tracking
     # -------------------------------------------------------------------------
 
+    def _get_session_lock(self, session_id: str) -> asyncio.Lock:
+        """Get or create a lock for a session."""
+        if session_id not in self._session_locks:
+            self._session_locks[session_id] = asyncio.Lock()
+        return self._session_locks[session_id]
+
+    def _cleanup_session_lock(self, session_id: str) -> None:
+        """Remove session lock when no longer needed."""
+        self._session_locks.pop(session_id, None)
+
     def _register_connection(self, session_id: str, connection: ConnectionPort) -> int:
         """Register a connection for a session. Returns connection count."""
         if session_id not in self._session_connections:
@@ -85,8 +97,21 @@ class TerminalService:
             del self._session_connections[session_id]
         return count
 
+    async def _send_to_connections(self, connections: list[ConnectionPort], data: bytes) -> None:
+        """Send data to a list of connections (used with pre-snapshotted list)."""
+        for conn in connections:
+            try:
+                await conn.send_output(data)
+            except Exception:
+                pass  # Connection cleanup handled elsewhere
+
     async def _broadcast_output(self, session_id: str, data: bytes) -> None:
-        """Broadcast PTY output to all connections for a session."""
+        """Broadcast PTY output to all connections for a session.
+
+        Note: This is only used for error/status messages where the race
+        condition doesn't matter. For PTY data, use _send_to_connections
+        with a lock-protected snapshot.
+        """
         connections = self._session_connections.get(session_id, set())
         dead: list[ConnectionPort] = []
         for conn in list(connections):  # Copy to avoid mutation during iteration
@@ -128,31 +153,41 @@ class TerminalService:
         session_id = str(session.id)
         clock = AsyncioClock()
         rate_limiter = TokenBucketRateLimiter(self._rate_limit_config, clock)
+        lock = self._get_session_lock(session_id)
+
+        # Register atomically to prevent race with broadcast.
+        # Without this lock, a new client could register between add_output and
+        # broadcast, receiving the same data twice (once from buffer, once broadcast).
+        #
+        # Buffer snapshot and read loop start are also under lock to ensure:
+        # - Buffer is captured before any new data arrives
+        # - Only one read loop starts per session (prevents duplicate PTY reads)
+        # - I/O (send_output) happens OUTSIDE lock to avoid blocking other clients
+        buffered = None
+        async with lock:
+            connection_count = self._register_connection(session_id, connection)
+            is_first_client = connection_count == 1
 
-        # Register this connection
-        connection_count = self._register_connection(session_id, connection)
-        is_first_client = connection_count == 1
-
-        logger.info(
-            "Client connected session_id=%s connection_count=%d",
-            session_id,
-            connection_count,
-        )
+            logger.info(
+                "Client connected session_id=%s connection_count=%d",
+                session_id,
+                connection_count,
+            )
 
-        try:
-            # First client starts the shared PTY read loop
+            # First client starts the shared PTY read loop (under lock to prevent duplicates)
             if is_first_client:
                 self._start_broadcast_read_loop(session, session_id)
 
+            # Snapshot buffer while under lock (ensures consistency with broadcast)
             # Note: session_info is sent by the caller (app.py) to include tab_id
-
-            # Replay buffered output to THIS connection only (not broadcast)
             if not skip_buffer and not session.output_buffer.is_empty:
                 buffered = session.get_buffered_output()
-                # Don't clear buffer - other clients may need it too
-                if buffered:
-                    await connection.send_output(buffered)
 
+        # Replay buffer OUTSIDE lock to avoid blocking other clients during I/O
+        if buffered:
+            await connection.send_output(buffered)
+
+        try:
             # Start heartbeat for this connection
             heartbeat_task = asyncio.create_task(self._heartbeat_loop(connection))
 
@@ -173,9 +208,10 @@ class TerminalService:
                 remaining,
             )
 
-            # Last client: stop the read loop
+            # Last client: stop the read loop and cleanup lock
             if remaining == 0:
                 await self._stop_broadcast_read_loop(session_id)
+                self._cleanup_session_lock(session_id)
 
     def _start_broadcast_read_loop(
         self,
@@ -212,6 +248,11 @@ class TerminalService:
         - Small data (<64 bytes): flush immediately for interactive responsiveness
         - Large data: batch for ~16ms to reduce WebSocket message frequency
         - Flush if batch exceeds 16KB to prevent memory buildup
+
+        Thread safety:
+        - Uses session lock to prevent race between add_output/broadcast and
+          new client registration/buffer replay. Lock is held briefly during
+          buffer update and connection snapshot, not during actual I/O.
         """
         # Check if PTY is alive at start
         if not session.pty_handle.is_alive():
@@ -219,18 +260,29 @@ class TerminalService:
             await self._broadcast_output(session_id, b"\r\n[PTY failed to start]\r\n")
             return
 
+        lock = self._get_session_lock(session_id)
         batch_buffer: list[bytes] = []
         batch_size = 0
         last_flush_time = asyncio.get_running_loop().time()
 
         async def flush_batch() -> None:
+            """Flush batched data with lock protection."""
             nonlocal batch_buffer, batch_size, last_flush_time
-            if batch_buffer:
-                combined = b"".join(batch_buffer)
-                batch_buffer = []
-                batch_size = 0
-                last_flush_time = asyncio.get_running_loop().time()
-                await self._broadcast_output(session_id, combined)
+            if not batch_buffer:
+                return
+
+            combined = b"".join(batch_buffer)
+            batch_buffer = []
+            batch_size = 0
+            last_flush_time = asyncio.get_running_loop().time()
+
+            # Acquire lock, add to buffer, snapshot connections, release lock
+            async with lock:
+                session.add_output(combined)
+                connections = list(self._session_connections.get(session_id, set()))
+
+            # Broadcast outside lock (I/O can be slow)
+            await self._send_to_connections(connections, combined)
 
         def has_connections() -> bool:
             return (
@@ -242,12 +294,16 @@ class TerminalService:
             try:
                 data = session.pty_handle.read(4096)
                 if data:
-                    session.add_output(data)
                     session.touch(datetime.now(UTC))
 
                     # Small data (interactive): flush immediately for responsiveness
                     if len(data) < INTERACTIVE_THRESHOLD and not batch_buffer:
-                        await self._broadcast_output(session_id, data)
+                        # Acquire lock, add to buffer, snapshot connections
+                        async with lock:
+                            session.add_output(data)
+                            connections = list(self._session_connections.get(session_id, set()))
+                        # Broadcast outside lock
+                        await self._send_to_connections(connections, data)
                     else:
                         # Batch larger data
                         batch_buffer.append(data)
@@ -351,7 +407,7 @@ class TerminalService:
         msg_type = message.get("type")
 
         if msg_type == "resize":
-            await self._handle_resize(session, message)
+            await self._handle_resize(session, message, connection)
         elif msg_type == "input":
             await self._handle_json_input(session, message, rate_limiter, connection)
         elif msg_type == "ping":
@@ -366,8 +422,17 @@ class TerminalService:
         self,
         session: Session[PTYPort],
         message: dict[str, Any],
+        connection: ConnectionPort,
     ) -> None:
-        """Handle terminal resize message."""
+        """Handle terminal resize message.
+
+        Multi-client strategy:
+        - When multiple clients share a session, PTY dimensions are locked
+        - Only the first client (or when all clients agree) can resize
+        - New clients receive current dimensions and must adapt locally
+        - This prevents rendering artifacts from dimension mismatches
+        """
+        session_id = str(session.id)
         cols = int(message.get("cols", 120))
         rows = int(message.get("rows", 30))
 
@@ -377,6 +442,29 @@ class TerminalService:
         if session.dimensions == new_dims:
             return
 
+        # Check if multiple clients are connected
+        connections = self._session_connections.get(session_id, set())
+        if len(connections) > 1:
+            # Multiple clients: reject resize, tell client to use current dimensions
+            logger.info(
+                "Resize rejected (multi-client) session_id=%s requested=%dx%d current=%dx%d",
+                session.id,
+                new_dims.cols,
+                new_dims.rows,
+                session.dimensions.cols,
+                session.dimensions.rows,
+            )
+            # Send current dimensions back so client can adapt
+            await connection.send_message(
+                {
+                    "type": "resize_sync",
+                    "cols": session.dimensions.cols,
+                    "rows": session.dimensions.rows,
+                }
+            )
+            return
+
+        # Single client: allow resize
         session.update_dimensions(new_dims)
         session.pty_handle.resize(new_dims)
         session.touch(datetime.now(UTC))

porterminal/asgi.py

@@ -17,15 +17,20 @@ def create_app_from_env():
 
     This is called by uvicorn when using the --factory flag.
     Environment variables:
-        PORTERMINAL_CONFIG_PATH: Path to config file (default: config.yaml)
+        PORTERMINAL_CONFIG_PATH: Path to config file (overrides search)
         PORTERMINAL_CWD: Working directory for PTY sessions
+
+    Config search order (when env var not set):
+        1. ptn.yaml in cwd
+        2. .ptn/ptn.yaml in cwd
+        3. ~/.ptn/ptn.yaml
     """
     from porterminal.app import create_app
 
-    config_path = os.environ.get("PORTERMINAL_CONFIG_PATH", "config.yaml")
     cwd = os.environ.get("PORTERMINAL_CWD")
 
-    container = create_container(config_path=config_path, cwd=cwd)
+    # config_path=None uses find_config_file() to search standard locations
+    container = create_container(config_path=None, cwd=cwd)
 
     # Create app with container
     # Note: The current app.py doesn't accept container yet,

porterminal/cli/args.py

@@ -61,6 +61,11 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Run in background and return immediately",
     )
+    parser.add_argument(
+        "--init",
+        action="store_true",
+        help="Create .ptn/ptn.yaml config file in current directory",
+    )
     # Internal argument for background mode communication
     parser.add_argument(
         "--_url-file",
@@ -88,4 +93,49 @@ def parse_args() -> argparse.Namespace:
         success = update_package()
         sys.exit(0 if success else 1)
 
+    if args.init:
+        _init_config()
+        sys.exit(0)
+
     return args
+
+
+DEFAULT_CONFIG = """\
+# ptn configuration file
+# Docs: https://github.com/lyehe/porterminal/blob/master/docs/configuration.md
+
+# Custom buttons (appear in third toolbar row)
+buttons:
+  - label: "git"
+    send: "git status\\r"
+  - label: "build"
+    send: "npm run build\\r"
+  # Multi-step button with delays (ms):
+  # - label: "deploy"
+  #   send:
+  #     - "npm run build"
+  #     - 100
+  #     - "\\r"
+
+# Terminal settings (optional)
+# terminal:
+#   default_shell: bash
+#   cols: 120
+#   rows: 30
+"""
+
+
+def _init_config() -> None:
+    """Create .ptn/ptn.yaml in current directory."""
+    from pathlib import Path
+
+    config_dir = Path.cwd() / ".ptn"
+    config_file = config_dir / "ptn.yaml"
+
+    if config_file.exists():
+        print(f"Config already exists: {config_file}")
+        return
+
+    config_dir.mkdir(exist_ok=True)
+    config_file.write_text(DEFAULT_CONFIG)
+    print(f"Created: {config_file}")

porterminal/composition.py

@@ -3,12 +3,15 @@
 from collections.abc import Callable
 from pathlib import Path
 
+import yaml
+
 from porterminal.application.services import (
     ManagementService,
     SessionService,
     TabService,
     TerminalService,
 )
+from porterminal.config import find_config_file
 from porterminal.container import Container
 from porterminal.domain import (
     EnvironmentRules,
@@ -19,7 +22,7 @@ from porterminal.domain import (
     TabLimitChecker,
     TerminalDimensions,
 )
-from porterminal.infrastructure.config import ShellDetector, YAMLConfigLoader
+from porterminal.infrastructure.config import ShellDetector
 from porterminal.infrastructure.registry import UserConnectionRegistry
 from porterminal.infrastructure.repositories import InMemorySessionRepository, InMemoryTabRepository
 
@@ -107,7 +110,7 @@ class PTYManagerAdapter:
 
 
 def create_container(
-    config_path: Path | str = "config.yaml",
+    config_path: Path | str | None = None,
     cwd: str | None = None,
 ) -> Container:
     """Create the dependency container with all wired dependencies.
@@ -116,15 +119,20 @@ def create_container(
     dependencies are created and wired together.
 
     Args:
-        config_path: Path to config file.
+        config_path: Path to config file, or None to search standard locations.
         cwd: Working directory for PTY sessions.
 
     Returns:
         Fully wired dependency container.
     """
     # Load configuration
-    loader = YAMLConfigLoader(config_path)
-    config_data = loader.load()
+    if config_path is None:
+        config_path = find_config_file()
+
+    config_data: dict = {}
+    if config_path is not None and Path(config_path).exists():
+        with open(config_path, encoding="utf-8") as f:
+            config_data = yaml.safe_load(f) or {}
 
     # Detect shells
     detector = ShellDetector()