ptn 0.3.2__py3-none-any.whl → 0.4.6__py3-none-any.whl

porterminal/__init__.py

@@ -19,7 +19,7 @@ import subprocess
 import sys
 import time
 from pathlib import Path
-from threading import Thread
+from threading import Event, Thread
 
 from rich.console import Console
 
@@ -287,9 +287,15 @@ def main() -> int:
     if tunnel_process is not None:
         Thread(target=drain_process_output, args=(tunnel_process,), daemon=True).start()
 
-    # Wait for Ctrl+C or process exit
+    # Use an event for responsive Ctrl+C handling on Windows
+    shutdown_event = Event()
+
+    def signal_handler(signum: int, frame: object) -> None:
+        shutdown_event.set()
+
+    old_handler = signal.signal(signal.SIGINT, signal_handler)
     try:
-        while True:
+        while not shutdown_event.is_set():
             if server_process is not None and server_process.poll() is not None:
                 code = server_process.returncode
                 if code == 0 or code < 0:
@@ -304,9 +310,11 @@ def main() -> int:
                 else:
                     console.print(f"\n[yellow]Tunnel stopped (exit code {code})[/yellow]")
                 break
-            time.sleep(1)
+            shutdown_event.wait(0.1)
+    finally:
+        signal.signal(signal.SIGINT, old_handler)
 
-    except KeyboardInterrupt:
+    if shutdown_event.is_set():
         console.print("\n[dim]Shutting down...[/dim]")
 
     # Cleanup - terminate gracefully, then kill if needed

porterminal/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.4.6'
+__version_tuple__ = version_tuple = (0, 4, 6)
 
 __commit_id__ = commit_id = None

porterminal/application/services/management_service.py

@@ -36,6 +36,23 @@ class ManagementService:
         self._get_shell = shell_provider
         self._default_dims = default_dimensions
 
+    async def _send_error(
+        self,
+        connection: ConnectionPort,
+        response_type: str,
+        request_id: str,
+        error: str,
+    ) -> None:
+        """Send an error response to a connection."""
+        await connection.send_message(
+            {
+                "type": response_type,
+                "request_id": request_id,
+                "success": False,
+                "error": error,
+            }
+        )
+
     async def handle_message(
         self,
         user_id: UserId,
@@ -76,13 +93,8 @@ class ManagementService:
             # Get shell
             shell = self._get_shell(shell_id)
             if not shell:
-                await connection.send_message(
-                    {
-                        "type": "create_tab_response",
-                        "request_id": request_id,
-                        "success": False,
-                        "error": "Invalid shell",
-                    }
+                await self._send_error(
+                    connection, "create_tab_response", request_id, "Invalid shell"
                 )
                 return
 
@@ -127,14 +139,7 @@ class ManagementService:
 
         except ValueError as e:
             logger.warning("Tab creation failed: %s", e)
-            await connection.send_message(
-                {
-                    "type": "create_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": str(e),
-                }
-            )
+            await self._send_error(connection, "create_tab_response", request_id, str(e))
 
     async def _handle_close_tab(
         self,
@@ -147,27 +152,13 @@ class ManagementService:
         tab_id = message.get("tab_id")
 
         if not tab_id:
-            await connection.send_message(
-                {
-                    "type": "close_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Missing tab_id",
-                }
-            )
+            await self._send_error(connection, "close_tab_response", request_id, "Missing tab_id")
             return
 
         # Get tab and session info before closing
         tab = self._tab_service.get_tab(tab_id)
         if not tab:
-            await connection.send_message(
-                {
-                    "type": "close_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Tab not found",
-                }
-            )
+            await self._send_error(connection, "close_tab_response", request_id, "Tab not found")
             return
 
         session_id = tab.session_id
@@ -175,13 +166,8 @@ class ManagementService:
         # Close the tab
         closed_tab = self._tab_service.close_tab(tab_id, user_id)
         if not closed_tab:
-            await connection.send_message(
-                {
-                    "type": "close_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Failed to close tab",
-                }
+            await self._send_error(
+                connection, "close_tab_response", request_id, "Failed to close tab"
             )
             return
 
@@ -222,26 +208,16 @@ class ManagementService:
         new_name = message.get("name")
 
         if not tab_id or not new_name:
-            await connection.send_message(
-                {
-                    "type": "rename_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Missing tab_id or name",
-                }
+            await self._send_error(
+                connection, "rename_tab_response", request_id, "Missing tab_id or name"
             )
             return
 
         # Rename the tab
         tab = self._tab_service.rename_tab(tab_id, user_id, new_name)
         if not tab:
-            await connection.send_message(
-                {
-                    "type": "rename_tab_response",
-                    "request_id": request_id,
-                    "success": False,
-                    "error": "Failed to rename tab",
-                }
+            await self._send_error(
+                connection, "rename_tab_response", request_id, "Failed to rename tab"
             )
             return
 

porterminal/application/services/session_service.py

@@ -2,14 +2,11 @@
 
 import asyncio
 import logging
-import os
 import uuid
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 
 from porterminal.domain import (
-    EnvironmentRules,
-    EnvironmentSanitizer,
     PTYPort,
     Session,
     SessionId,
@@ -32,17 +29,13 @@ class SessionService:
     def __init__(
         self,
         repository: SessionRepository[PTYPort],
-        pty_factory: Callable[
-            [ShellCommand, TerminalDimensions, dict[str, str], str | None], PTYPort
-        ],
+        pty_factory: Callable[[ShellCommand, TerminalDimensions, str | None], PTYPort],
         limit_checker: SessionLimitChecker | None = None,
-        environment_sanitizer: EnvironmentSanitizer | None = None,
         working_directory: str | None = None,
     ) -> None:
         self._repository = repository
         self._pty_factory = pty_factory
         self._limit_checker = limit_checker or SessionLimitChecker()
-        self._sanitizer = environment_sanitizer or EnvironmentSanitizer(EnvironmentRules())
         self._cwd = working_directory
         self._running = False
         self._cleanup_task: asyncio.Task | None = None
@@ -108,9 +101,8 @@ class SessionService:
         if not limit_result.allowed:
             raise ValueError(limit_result.reason)
 
-        # Create PTY with sanitized environment
-        env = self._sanitizer.sanitize(dict(os.environ))
-        pty = self._pty_factory(shell, dimensions, env, self._cwd)
+        # Create PTY (environment sanitization handled by PTY layer)
+        pty = self._pty_factory(shell, dimensions, self._cwd)
 
         # Create session (starts with 0 clients, caller adds via add_client())
         now = datetime.now(UTC)

porterminal/application/services/terminal_service.py

@@ -3,7 +3,9 @@
 import asyncio
 import logging
 import re
+import time
 from contextlib import suppress
+from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import Any
 
@@ -19,6 +21,20 @@ from ..ports.connection_port import ConnectionPort
 
 logger = logging.getLogger(__name__)
 
+
+@dataclass
+class ConnectionFlowState:
+    """Per-connection flow control state.
+
+    Implements xterm.js recommended watermark-based flow control.
+    When client sends 'pause', we stop sending to that connection.
+    When client sends 'ack', we resume sending.
+    """
+
+    paused: bool = False
+    pause_time: float | None = None
+
+
 # Terminal response sequences that should NOT be written to PTY.
 # These are responses from the terminal emulator to queries from applications.
 # If written to PTY, they get echoed back and displayed as garbage.
@@ -31,11 +47,20 @@ TERMINAL_RESPONSE_PATTERN = re.compile(rb"\x1b\[\?[\d;]*c|\x1b\[[\d;]*R")
 # Constants
 HEARTBEAT_INTERVAL = 30  # seconds
 HEARTBEAT_TIMEOUT = 300  # 5 minutes
-PTY_READ_INTERVAL = 0.008  # ~120Hz polling
-OUTPUT_BATCH_INTERVAL = 0.016  # ~60Hz output (batch writes for smoother rendering)
+
+# Adaptive PTY read interval: fast when data flowing, slow when idle
+PTY_READ_INTERVAL_MIN = 0.001  # 1ms when data is flowing (high throughput)
+PTY_READ_INTERVAL_MAX = 0.008  # 8ms when idle (save CPU)
+PTY_READ_BURST_THRESHOLD = 5  # Consecutive reads with data before going fast
+
+# Tiered batch intervals: faster for interactive, slower for bulk
+OUTPUT_BATCH_INTERVAL_INTERACTIVE = 0.004  # 4ms for small data (<256 bytes)
+OUTPUT_BATCH_INTERVAL_BULK = 0.016  # 16ms for larger data
+OUTPUT_BATCH_SIZE_THRESHOLD = 256  # Bytes - threshold for interactive vs bulk
 OUTPUT_BATCH_MAX_SIZE = 16384  # Flush if batch exceeds 16KB
-INTERACTIVE_THRESHOLD = 64  # Bytes - flush immediately for small interactive data
+INTERACTIVE_THRESHOLD = 64  # Bytes - flush immediately for very small data
 MAX_INPUT_SIZE = 4096
+FLOW_PAUSE_TIMEOUT = 5.0  # seconds - auto-resume if client stops sending ACKs (was 15s)
 
 
 class AsyncioClock:
@@ -65,6 +90,8 @@ class TerminalService:
         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] = {}
+        # Per-connection flow control state (watermark-based backpressure)
+        self._flow_state: dict[ConnectionPort, ConnectionFlowState] = {}
 
     # -------------------------------------------------------------------------
     # Multi-client connection tracking
@@ -72,9 +99,7 @@ class TerminalService:
 
     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]
+        return self._session_locks.setdefault(session_id, asyncio.Lock())
 
     def _cleanup_session_lock(self, session_id: str) -> None:
         """Remove session lock when no longer needed."""
@@ -82,13 +107,17 @@ class TerminalService:
 
     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:
-            self._session_connections[session_id] = set()
-        self._session_connections[session_id].add(connection)
-        return len(self._session_connections[session_id])
+        connections = self._session_connections.setdefault(session_id, set())
+        connections.add(connection)
+        # Initialize flow control state for this connection
+        self._flow_state[connection] = ConnectionFlowState()
+        return len(connections)
 
     def _unregister_connection(self, session_id: str, connection: ConnectionPort) -> int:
         """Unregister a connection. Returns remaining count."""
+        # Clean up flow control state
+        self._flow_state.pop(connection, None)
+
         if session_id not in self._session_connections:
             return 0
         self._session_connections[session_id].discard(connection)
@@ -98,12 +127,27 @@ class TerminalService:
         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)."""
+        """Send data to connections, respecting flow control.
+
+        Skips paused connections (client overwhelmed) but auto-resumes
+        after FLOW_PAUSE_TIMEOUT to prevent permanent pause from dead clients.
+        """
+        current_time = time.time()
         for conn in connections:
+            flow = self._flow_state.get(conn)
+            if flow and flow.paused:
+                # Check timeout - auto-resume if client stopped responding
+                if flow.pause_time and (current_time - flow.pause_time) > FLOW_PAUSE_TIMEOUT:
+                    flow.paused = False
+                    flow.pause_time = None
+                    logger.debug("Auto-resumed paused connection after timeout")
+                else:
+                    continue  # Skip paused connection
+
             try:
                 await conn.send_output(data)
-            except Exception:
-                pass  # Connection cleanup handled elsewhere
+            except Exception as e:
+                logger.debug("Failed to send output to connection: %s", e)
 
     async def _broadcast_output(self, session_id: str, data: bytes) -> None:
         """Broadcast PTY output to all connections for a session.
@@ -264,6 +308,7 @@ class TerminalService:
         batch_buffer: list[bytes] = []
         batch_size = 0
         last_flush_time = asyncio.get_running_loop().time()
+        consecutive_data_reads = 0  # Track consecutive reads with data for adaptive sleep
 
         async def flush_batch() -> None:
             """Flush batched data with lock protection."""
@@ -295,6 +340,10 @@ class TerminalService:
                 data = session.pty_handle.read(4096)
                 if data:
                     session.touch(datetime.now(UTC))
+                    # Track consecutive reads with data for adaptive sleep
+                    consecutive_data_reads = min(
+                        consecutive_data_reads + 1, PTY_READ_BURST_THRESHOLD
+                    )
 
                     # Small data (interactive): flush immediately for responsiveness
                     if len(data) < INTERACTIVE_THRESHOLD and not batch_buffer:
@@ -312,6 +361,9 @@ class TerminalService:
                         # Flush if batch is large enough
                         if batch_size >= OUTPUT_BATCH_MAX_SIZE:
                             await flush_batch()
+                else:
+                    # No data - reset burst counter
+                    consecutive_data_reads = 0
 
             except Exception as e:
                 logger.error("PTY read error session_id=%s: %s", session.id, e)
@@ -319,12 +371,25 @@ class TerminalService:
                 await self._broadcast_output(session_id, f"\r\n[PTY error: {e}]\r\n".encode())
                 break
 
+            # Tiered batch interval: faster for small batches, slower for large
+            batch_interval = (
+                OUTPUT_BATCH_INTERVAL_INTERACTIVE
+                if batch_size < OUTPUT_BATCH_SIZE_THRESHOLD
+                else OUTPUT_BATCH_INTERVAL_BULK
+            )
+
             # Check if we should flush based on time
             current_time = asyncio.get_running_loop().time()
-            if batch_buffer and (current_time - last_flush_time) >= OUTPUT_BATCH_INTERVAL:
+            if batch_buffer and (current_time - last_flush_time) >= batch_interval:
                 await flush_batch()
 
-            await asyncio.sleep(PTY_READ_INTERVAL)
+            # Adaptive sleep: fast when data flowing, slow when idle
+            sleep_time = (
+                PTY_READ_INTERVAL_MIN
+                if consecutive_data_reads >= PTY_READ_BURST_THRESHOLD
+                else PTY_READ_INTERVAL_MAX
+            )
+            await asyncio.sleep(sleep_time)
 
         # Flush any remaining data
         await flush_batch()
@@ -358,7 +423,7 @@ class TerminalService:
             if isinstance(message, bytes):
                 await self._handle_binary_input(session, message, rate_limiter, connection)
             elif isinstance(message, dict):
-                await self._handle_json_message(session, message, rate_limiter, connection)
+                await self._handle_json_message(session, message, connection)
 
     async def _handle_binary_input(
         self,
@@ -400,7 +465,6 @@ class TerminalService:
         self,
         session: Session[PTYPort],
         message: dict[str, Any],
-        rate_limiter: TokenBucketRateLimiter,
         connection: ConnectionPort,
     ) -> None:
         """Handle JSON control message."""
@@ -408,13 +472,27 @@ class TerminalService:
 
         if msg_type == "resize":
             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":
             await connection.send_message({"type": "pong"})
             session.touch(datetime.now(UTC))
         elif msg_type == "pong":
             session.touch(datetime.now(UTC))
+        elif msg_type == "pause":
+            # Client is overwhelmed - stop sending data to this connection
+            flow = self._flow_state.get(connection)
+            if flow:
+                flow.paused = True
+                flow.pause_time = time.time()
+                # Send confirmation so client knows pause was received
+                await connection.send_message({"type": "pause_ack"})
+                logger.debug("Connection paused (client overwhelmed) session_id=%s", session.id)
+        elif msg_type == "ack":
+            # Client caught up - resume sending data
+            flow = self._flow_state.get(connection)
+            if flow and flow.paused:
+                flow.paused = False
+                flow.pause_time = None
+                logger.debug("Connection resumed (client caught up) session_id=%s", session.id)
         else:
             logger.warning("Unknown message type session_id=%s type=%s", session.id, msg_type)
 
@@ -475,40 +553,3 @@ class TerminalService:
             new_dims.cols,
             new_dims.rows,
         )
-
-    async def _handle_json_input(
-        self,
-        session: Session[PTYPort],
-        message: dict[str, Any],
-        rate_limiter: TokenBucketRateLimiter,
-        connection: ConnectionPort,
-    ) -> None:
-        """Handle JSON-encoded terminal input."""
-        data = message.get("data", "")
-
-        if len(data) > self._max_input_size:
-            await connection.send_message(
-                {
-                    "type": "error",
-                    "message": "Input too large",
-                }
-            )
-            return
-
-        if data:
-            input_bytes = data.encode("utf-8")
-            # Filter terminal response sequences
-            filtered = TERMINAL_RESPONSE_PATTERN.sub(b"", input_bytes)
-            if not filtered:
-                return
-
-            if rate_limiter.try_acquire(len(filtered)):
-                session.pty_handle.write(filtered)
-                session.touch(datetime.now(UTC))
-            else:
-                await connection.send_message(
-                    {
-                        "type": "error",
-                        "message": "Rate limit exceeded",
-                    }
-                )

porterminal/cli/args.py

@@ -22,7 +22,6 @@ def parse_args() -> argparse.Namespace:
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
-        "-V",
         "--version",
         action="version",
         version=f"%(prog)s {__version__}",
@@ -34,6 +33,7 @@ def parse_args() -> argparse.Namespace:
         help="Starting directory for the shell (default: current directory)",
     )
     parser.add_argument(
+        "-n",
         "--no-tunnel",
         action="store_true",
         help="Start server only, without Cloudflare tunnel",
@@ -45,12 +45,13 @@ def parse_args() -> argparse.Namespace:
         help="Show detailed startup logs",
     )
     parser.add_argument(
-        "-U",
+        "-u",
         "--update",
         action="store_true",
         help="Update to the latest version",
     )
     parser.add_argument(
+        "-c",
         "--check-update",
         action="store_true",
         help="Check if a newer version is available",
@@ -62,9 +63,13 @@ def parse_args() -> argparse.Namespace:
         help="Run in background and return immediately",
     )
     parser.add_argument(
+        "-i",
         "--init",
-        action="store_true",
-        help="Create .ptn/ptn.yaml config file in current directory",
+        nargs="?",
+        const=True,
+        default=False,
+        metavar="URL_OR_PATH",
+        help="Create .ptn/ptn.yaml config (optionally from URL or file path)",
     )
     parser.add_argument(
         "-p",
@@ -106,8 +111,8 @@ def parse_args() -> argparse.Namespace:
         sys.exit(0 if success else 1)
 
     if args.init:
-        _init_config()
-        sys.exit(0)
+        _init_config(args.init if args.init is not True else None)
+        # Continue to launch ptn after creating config
 
     if args.default_password:
         _toggle_password_requirement()
@@ -116,45 +121,89 @@ def parse_args() -> argparse.Namespace:
     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."""
+def _init_config(source: str | None = None) -> None:
+    """Create .ptn/ptn.yaml in current directory.
+
+    Args:
+        source: Optional URL or file path to use as config source.
+                If None, auto-discovers scripts and creates default config.
+    """
     from pathlib import Path
+    from urllib.error import URLError
+    from urllib.request import urlopen
+
+    import yaml
+
+    from porterminal.cli.script_discovery import discover_scripts
 
-    config_dir = Path.cwd() / ".ptn"
+    cwd = Path.cwd()
+    config_dir = cwd / ".ptn"
     config_file = config_dir / "ptn.yaml"
 
+    # If source is provided, fetch/copy it
+    if source:
+        config_dir.mkdir(exist_ok=True)
+
+        if source.startswith(("http://", "https://")):
+            # Download from URL
+            try:
+                print(f"Downloading config from {source}...")
+                with urlopen(source, timeout=10) as response:
+                    content = response.read().decode("utf-8")
+                config_file.write_text(content)
+                print(f"Created: {config_file}")
+            except (URLError, OSError, TimeoutError) as e:
+                print(f"Error downloading config: {e}")
+                return
+        else:
+            # Copy from local file
+            source_path = Path(source).expanduser().resolve()
+            if not source_path.exists():
+                print(f"Error: File not found: {source_path}")
+                return
+            try:
+                content = source_path.read_text(encoding="utf-8")
+                config_file.write_text(content)
+                print(f"Created: {config_file} (from {source_path})")
+            except OSError as e:
+                print(f"Error reading config: {e}")
+                return
+        return
+
+    # No source - use auto-discovery
     if config_file.exists():
         print(f"Config already exists: {config_file}")
         return
 
+    # Build config with default buttons (row 1: AI coding tools)
+    config: dict = {
+        "buttons": [
+            {"label": "new", "send": ["/new", 100, "\r"]},
+            {"label": "init", "send": ["/init", 100, "\r"]},
+            {"label": "resume", "send": ["/resume", 100, "\r"]},
+            {"label": "compact", "send": ["/compact", 100, "\r"]},
+            {"label": "claude", "send": ["claude", 100, "\r"]},
+            {"label": "codex", "send": ["codex", 100, "\r"]},
+        ]
+    }
+
+    # Auto-discover project scripts and add to row 2
+    discovered = discover_scripts(cwd)
+    if discovered:
+        config["buttons"].extend(discovered)
+
     config_dir.mkdir(exist_ok=True)
-    config_file.write_text(DEFAULT_CONFIG)
+
+    # Write YAML with comment header
+    header = "# ptn configuration file\n# Docs: https://github.com/lyehe/porterminal\n\n"
+    yaml_content = yaml.safe_dump(config, default_flow_style=False, sort_keys=False)
+    config_file.write_text(header + yaml_content)
+
     print(f"Created: {config_file}")
+    if discovered:
+        print(
+            f"Discovered {len(discovered)} project script(s): {', '.join(b['label'] for b in discovered)}"
+        )
 
 
 def _toggle_password_requirement() -> None: