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

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,10 +63,23 @@ 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",
     )
+    parser.add_argument(
+        "-p",
+        "--password",
+        action="store_true",
+        help="Prompt for password to protect terminal access",
+    )
+    parser.add_argument(
+        "-dp",
+        "--default-password",
+        action="store_true",
+        help="Toggle password requirement in config (on/off)",
+    )
     # Internal argument for background mode communication
     parser.add_argument(
         "--_url-file",
@@ -95,47 +109,94 @@ def parse_args() -> argparse.Namespace:
 
     if args.init:
         _init_config()
+        # Continue to launch ptn after creating config
+
+    if args.default_password:
+        _toggle_password_requirement()
         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."""
+    """Create .ptn/ptn.yaml in current directory with auto-discovered scripts."""
     from pathlib import Path
 
-    config_dir = Path.cwd() / ".ptn"
+    import yaml
+
+    from porterminal.cli.script_discovery import discover_scripts
+
+    cwd = Path.cwd()
+    config_dir = cwd / ".ptn"
     config_file = config_dir / "ptn.yaml"
 
     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:
+    """Toggle security.require_password in config file."""
+    from pathlib import Path
+
+    import yaml
+
+    from porterminal.config import find_config_file
+
+    # Find existing config or use default location
+    config_path = find_config_file()
+    if config_path is None:
+        config_dir = Path.cwd() / ".ptn"
+        config_path = config_dir / "ptn.yaml"
+        config_dir.mkdir(exist_ok=True)
+
+    # Read existing config or create empty
+    if config_path.exists():
+        with open(config_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    else:
+        data = {}
+
+    # Toggle the value
+    if "security" not in data:
+        data["security"] = {}
+    current = data["security"].get("require_password", False)
+    data["security"]["require_password"] = not current
+
+    # Write back
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False)
+
+    new_value = data["security"]["require_password"]
+    status = "enabled" if new_value else "disabled"
+    print(f"Password requirement {status} in {config_path}")

porterminal/cli/display.py

@@ -58,6 +58,14 @@ def get_caution() -> str:
     return CAUTION_DEFAULT
 
 
+def _apply_gradient(lines: list[str], colors: list[str]) -> list[str]:
+    """Apply color gradient to text lines."""
+    return [
+        f"[{colors[min(i, len(colors) - 1)]}]{line}[/{colors[min(i, len(colors) - 1)]}]"
+        for i, line in enumerate(lines)
+    ]
+
+
 def get_qr_code(url: str) -> str:
     """Generate QR code as ASCII string.
 
@@ -112,21 +120,15 @@ def display_startup_screen(
     else:
         status = "[yellow]●[/yellow] LOCAL MODE"
 
-    # Build logo with gradient
-    logo_lines = LOGO.strip().split("\n")
-    colors = ["bold bright_cyan", "bright_cyan", "cyan", "bright_blue", "blue"]
-    logo_colored = []
-    for i, line in enumerate(logo_lines):
-        color = colors[i] if i < len(colors) else colors[-1]
-        logo_colored.append(f"[{color}]{line}[/{color}]")
-
-    # Build tagline with gradient
-    tagline_lines = TAGLINE.split("\n")
-    tagline_colors = ["bright_magenta", "magenta"]
-    tagline_colored = []
-    for i, line in enumerate(tagline_lines):
-        color = tagline_colors[i] if i < len(tagline_colors) else tagline_colors[-1]
-        tagline_colored.append(f"[{color}]{line}[/{color}]")
+    # Build logo and tagline with gradients
+    logo_colored = _apply_gradient(
+        LOGO.strip().split("\n"),
+        ["bold bright_cyan", "bright_cyan", "cyan", "bright_blue", "blue"],
+    )
+    tagline_colored = _apply_gradient(
+        TAGLINE.split("\n"),
+        ["bright_magenta", "magenta"],
+    )
 
     # Left side content
     left_lines = [
@@ -136,7 +138,7 @@ def display_startup_screen(
         *tagline_colored,
         "",
         f"[bold yellow]{get_caution()}[/bold yellow]",
-        "[bright_red]The URL is the only security. Use at your own risk.[/bright_red]",
+        "[bright_red]Use -p for password protection if your screen is exposed[/bright_red]",
         status,
         f"[bold cyan]{url}[/bold cyan]",
     ]

porterminal/cli/script_discovery.py

@@ -0,0 +1,112 @@
+"""Auto-discover project scripts for config initialization."""
+
+import json
+import re
+import tomllib
+from pathlib import Path
+
+# Pattern for safe script names (alphanumeric, hyphens, underscores only)
+_SAFE_NAME = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+
+def _is_safe_name(name: str) -> bool:
+    """Check if script name contains only safe characters."""
+    return bool(_SAFE_NAME.match(name)) and len(name) <= 50
+
+
+def discover_scripts(cwd: Path | None = None) -> list[dict]:
+    """Discover project scripts in current directory.
+
+    Returns list of button configs: [{"label": "build", "send": "npm run build\\r", "row": 2}]
+    Only includes scripts explicitly defined in project files.
+    """
+    base = cwd or Path.cwd()
+    buttons = []
+
+    # Check each project type (only those with explicit scripts)
+    buttons.extend(_discover_npm_scripts(base))
+    buttons.extend(_discover_python_scripts(base))
+    buttons.extend(_discover_makefile_targets(base))
+
+    # Dedupe by label, keep first occurrence
+    unique: dict[str, dict] = {}
+    for btn in buttons:
+        unique.setdefault(btn["label"], btn)
+    return list(unique.values())
+
+
+def _discover_npm_scripts(base: Path) -> list[dict]:
+    """Extract scripts from package.json."""
+    pkg_file = base / "package.json"
+    if not pkg_file.exists():
+        return []
+
+    try:
+        data = json.loads(pkg_file.read_text(encoding="utf-8"))
+        scripts = data.get("scripts", {})
+
+        # Common useful scripts to include (if defined)
+        priority = ["build", "dev", "start", "test", "lint", "format", "watch"]
+
+        buttons = []
+        for name in priority:
+            if name in scripts:
+                buttons.append({"label": name, "send": f"npm run {name}\r", "row": 2})
+
+        return buttons[:6]  # Limit to 6 buttons
+    except Exception:
+        return []
+
+
+def _discover_python_scripts(base: Path) -> list[dict]:
+    """Extract scripts from pyproject.toml."""
+    toml_file = base / "pyproject.toml"
+    if not toml_file.exists():
+        return []
+
+    try:
+        data = tomllib.loads(toml_file.read_text(encoding="utf-8"))
+        buttons = []
+
+        # Check [project.scripts] (PEP 621)
+        project_scripts = data.get("project", {}).get("scripts", {})
+        for name in list(project_scripts.keys())[:4]:
+            if _is_safe_name(name):
+                buttons.append({"label": name, "send": f"{name}\r", "row": 2})
+
+        # Check [tool.poetry.scripts]
+        poetry_scripts = data.get("tool", {}).get("poetry", {}).get("scripts", {})
+        for name in list(poetry_scripts.keys())[:4]:
+            if _is_safe_name(name) and not any(b["label"] == name for b in buttons):
+                buttons.append({"label": name, "send": f"{name}\r", "row": 2})
+
+        return buttons[:6]
+    except Exception:
+        return []
+
+
+def _discover_makefile_targets(base: Path) -> list[dict]:
+    """Extract targets from Makefile."""
+    makefile = base / "Makefile"
+    if not makefile.exists():
+        return []
+
+    try:
+        content = makefile.read_text(encoding="utf-8")
+        # Match target definitions: "target:" at start of line
+        # Regex excludes targets starting with . (internal targets like .PHONY)
+        pattern = r"^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:"
+        targets = re.findall(pattern, content, re.MULTILINE)
+
+        # Priority order for common targets (use set for O(1) lookup)
+        priority = ["build", "test", "run", "clean", "install", "dev", "lint", "all"]
+        priority_set = set(priority)
+        target_set = set(targets)
+
+        # Priority targets first, then remaining targets
+        ordered = [t for t in priority if t in target_set]
+        ordered.extend(t for t in targets if t not in priority_set)
+
+        return [{"label": name, "send": f"make {name}\r", "row": 2} for name in ordered[:6]]
+    except Exception:
+        return []