portacode 0.1.0__tar.gz

portacode-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: portacode
+Version: 0.1.0
+Summary: Portacode CLI client and SDK
+Home-page: https://github.com/portacode/portacode
+Author: Meena Erian
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: platformdirs>=3.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyte>=0.8
+Requires-Dist: pywinpty>=2.0; platform_system == "Windows"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Portacode
+
+Portacode is a modular Python package that provides a command-line interface for connecting your local machine to the Portacode cloud gateway.
+
+```
+$ pip install portacode
+$ portacode connect
+```
+
+The first release only ships the `connect` command which:
+
+1. Creates an RSA public/private key-pair (if not already present) in a platform-specific data directory.
+2. Guides you through adding the public key to your Portacode account.
+3. Establishes and maintains a resilient WebSocket connection to `wss://portacode.com/gateway`.
+
+Future releases will add more sub-commands and build upon the multiplexing channel infrastructure already included in this version.
+
+## Project layout
+
+```
+portacode/          ‑ Top-level package
+├── cli.py          ‑ Click-based CLI entry-point
+├── data.py         ‑ Cross-platform data-directory helpers
+├── keypair.py      ‑ RSA key generation & storage
+├── connection/     ‑ Networking & multiplexing logic
+│   ├── client.py   ‑ WebSocket client with auto-reconnect
+│   └── multiplex.py- Virtual channel multiplexer
+└── …
+```
+
+See the README files inside each sub-module for more details. 

portacode-0.1.0/README.md

@@ -0,0 +1,31 @@
+# Portacode
+
+Portacode is a modular Python package that provides a command-line interface for connecting your local machine to the Portacode cloud gateway.
+
+```
+$ pip install portacode
+$ portacode connect
+```
+
+The first release only ships the `connect` command which:
+
+1. Creates an RSA public/private key-pair (if not already present) in a platform-specific data directory.
+2. Guides you through adding the public key to your Portacode account.
+3. Establishes and maintains a resilient WebSocket connection to `wss://portacode.com/gateway`.
+
+Future releases will add more sub-commands and build upon the multiplexing channel infrastructure already included in this version.
+
+## Project layout
+
+```
+portacode/          ‑ Top-level package
+├── cli.py          ‑ Click-based CLI entry-point
+├── data.py         ‑ Cross-platform data-directory helpers
+├── keypair.py      ‑ RSA key generation & storage
+├── connection/     ‑ Networking & multiplexing logic
+│   ├── client.py   ‑ WebSocket client with auto-reconnect
+│   └── multiplex.py- Virtual channel multiplexer
+└── …
+```
+
+See the README files inside each sub-module for more details. 

portacode-0.1.0/portacode/__init__.py

@@ -0,0 +1,16 @@
+"""Portacode SDK & CLI.
+
+This package exposes a top-level `cli` entry-point for interacting with the
+Portacode gateway and also provides programmatic helpers for managing user
+configuration and network connections.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("portacode")  # type: ignore[arg-type]
+except PackageNotFoundError:  # pragma: no cover
+    # Package is not installed – most likely running from source tree.
+    __version__ = "0.0.0.dev0"
+
+__all__: list[str] = ["__version__"] 

portacode-0.1.0/portacode/cli.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from multiprocessing import Process
+from pathlib import Path
+import signal
+import json
+
+import click
+import pyperclip
+
+from .data import get_pid_file, is_process_running
+from .keypair import get_or_create_keypair, fingerprint_public_key
+from .connection.client import ConnectionManager, run_until_interrupt
+
+GATEWAY_URL = "wss://portacode.com/gateway"
+GATEWAY_ENV = "PORTACODE_GATEWAY"
+
+
+@click.group()
+def cli() -> None:
+    """Portacode command-line interface."""
+
+
+@cli.command()
+@click.option("--gateway", "gateway", "-g", help="Gateway websocket URL (overrides env/ default)")
+@click.option("--detach", "detach", "-d", is_flag=True, help="Run connection in background")
+def connect(gateway: str | None, detach: bool) -> None:  # noqa: D401 – Click callback
+    """Connect this machine to Portacode gateway."""
+
+    # 1. Ensure only a single connection per user
+    pid_file = get_pid_file()
+    if pid_file.exists():
+        try:
+            other_pid = int(pid_file.read_text())
+        except ValueError:
+            other_pid = None
+
+        if other_pid and is_process_running(other_pid):
+            click.echo(
+                click.style(
+                    f"Another portacode connection (PID {other_pid}) is active.", fg="yellow"
+                )
+            )
+            if click.confirm("Terminate the existing connection?", default=False):
+                _terminate_process(other_pid)
+                pid_file.unlink(missing_ok=True)
+            else:
+                click.echo("Aborting.")
+                sys.exit(1)
+        else:
+            # Stale pidfile
+            pid_file.unlink(missing_ok=True)
+
+    # Determine gateway URL
+    target_gateway = gateway or os.getenv(GATEWAY_ENV) or GATEWAY_URL
+
+    # 2. Load or create keypair
+    keypair = get_or_create_keypair()
+    fingerprint = fingerprint_public_key(keypair.public_key_pem)
+
+    pubkey_b64 = keypair.public_key_der_b64()
+    click.echo()
+    click.echo(click.style("✔ Generated / loaded RSA keypair", fg="green"))
+
+    click.echo()
+    click.echo(click.style("Public key (copy & paste to your Portacode account):", bold=True))
+    click.echo("-" * 60)
+    click.echo(pubkey_b64)
+    click.echo("-" * 60)
+    try:
+        pyperclip.copy(pubkey_b64)
+        click.echo(click.style("(Copied to clipboard!)", fg="cyan"))
+    except Exception:
+        click.echo(click.style("(Could not copy to clipboard. Please copy manually.)", fg="yellow"))
+    click.echo(f"Fingerprint: {fingerprint}")
+    click.echo()
+    click.prompt("Press <enter> once the key is added", default="", show_default=False)
+
+    # 3. Start connection manager
+    if detach:
+        click.echo("Establishing connection in the background…")
+        p = Process(target=_run_connection_forever, args=(target_gateway, keypair, pid_file))
+        p.daemon = False  # We want it to live beyond parent process on POSIX; on Windows it's anyway independent
+        p.start()
+        click.echo(click.style(f"Background process PID: {p.pid}", fg="green"))
+        return
+
+    # Foreground mode → run in current event-loop
+    pid_file.write_text(str(os.getpid()))
+
+    async def _main() -> None:
+        mgr = ConnectionManager(target_gateway, keypair)
+        await run_until_interrupt(mgr)
+
+    try:
+        asyncio.run(_main())
+    finally:
+        pid_file.unlink(missing_ok=True)
+
+
+def _run_connection_forever(url: str, keypair, pid_file: Path):
+    """Entry-point for detached background process."""
+    try:
+        pid_file.write_text(str(os.getpid()))
+
+        async def _main() -> None:
+            mgr = ConnectionManager(url, keypair)
+            await run_until_interrupt(mgr)
+
+        asyncio.run(_main())
+    finally:
+        pid_file.unlink(missing_ok=True)
+
+
+def _terminate_process(pid: int):
+    if sys.platform.startswith("win"):
+        import ctypes
+        PROCESS_TERMINATE = 1
+        handle = ctypes.windll.kernel32.OpenProcess(PROCESS_TERMINATE, False, pid)
+        if handle:
+            ctypes.windll.kernel32.TerminateProcess(handle, -1)
+            ctypes.windll.kernel32.CloseHandle(handle)
+    else:
+        try:
+            os.kill(pid, signal.SIGTERM)  # type: ignore[name-defined]
+        except OSError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Debug helpers – NOT intended for production use
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.argument("message", nargs=1)
+@click.option("--gateway", "gateway", "-g", help="Gateway websocket URL (overrides env/ default)")
+def send_control(message: str, gateway: str | None) -> None:  # noqa: D401 – Click callback
+    """Send a raw JSON *control* message on channel 0 and print replies.
+
+    Example::
+
+        portacode send-control '{"cmd": "system_info"}'
+
+    The command opens a short-lived connection, authenticates, sends the
+    control message and waits up to 5 seconds for responses which are then
+    pretty-printed to stdout.
+    """
+
+    try:
+        payload = json.loads(message)
+    except json.JSONDecodeError as exc:
+        raise click.BadParameter(f"Invalid JSON: {exc}") from exc
+
+    target_gateway = gateway or os.getenv(GATEWAY_ENV) or GATEWAY_URL
+
+    async def _run() -> None:
+        keypair = get_or_create_keypair()
+        mgr = ConnectionManager(target_gateway, keypair)
+        await mgr.start()
+
+        # Wait until mux is available & authenticated (rudimentary – 2s timeout)
+        for _ in range(20):
+            if mgr.mux is not None:
+                break
+            await asyncio.sleep(0.1)
+        if mgr.mux is None:
+            click.echo("Failed to initialise connection – aborting.")
+            await mgr.stop()
+            return
+
+        # Send control frame on channel 0
+        ctl = mgr.mux.get_channel(0)
+        await ctl.send(payload)
+
+        # Print replies for a short time
+        try:
+            with click.progressbar(length=50, label="Waiting for replies") as bar:
+                for _ in range(50):
+                    try:
+                        reply = await asyncio.wait_for(ctl.recv(), timeout=0.1)
+                        click.echo(click.style("< " + json.dumps(reply, indent=2), fg="cyan"))
+                    except asyncio.TimeoutError:
+                        pass
+                    bar.update(1)
+        finally:
+            await mgr.stop()
+
+    asyncio.run(_run()) 

portacode-0.1.0/portacode/connection/__init__.py

@@ -0,0 +1,7 @@
+"""Networking primitives for Portacode.
+
+The :pymod:`portacode.connection` package provides a resilient WebSocket client
+with built-in multiplexer/demultiplexer for arbitrary virtual channels.
+"""
+
+from .client import ConnectionManager  # noqa: F401 

portacode-0.1.0/portacode/connection/client.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+from pathlib import Path
+from typing import Optional
+import json
+import base64
+import sys
+
+import websockets
+from websockets import WebSocketClientProtocol
+
+from ..keypair import KeyPair
+from .multiplex import Multiplexer
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    """Maintain a persistent connection to the Portacode gateway.
+
+    Parameters
+    ----------
+    gateway_url: str
+        WebSocket URL, e.g. ``wss://portacode.com/gateway``
+    keypair: KeyPair
+        User's public/private keypair used for authentication.
+    reconnect_delay: float
+        Seconds to wait before attempting to reconnect after an unexpected drop.
+    max_retries: int
+        Maximum number of reconnect attempts before giving up.
+    """
+
+    def __init__(self, gateway_url: str, keypair: KeyPair, reconnect_delay: float = 1.0, max_retries: int = 10):
+        self.gateway_url = gateway_url
+        self.keypair = keypair
+        self.reconnect_delay = reconnect_delay
+        self.max_retries = max_retries
+
+        self._task: Optional[asyncio.Task[None]] = None
+        self._stop_event = asyncio.Event()
+
+        self.websocket: Optional[WebSocketClientProtocol] = None
+        self.mux: Optional[Multiplexer] = None
+
+    async def start(self) -> None:
+        """Start the background task that maintains the connection."""
+        if self._task is not None:
+            raise RuntimeError("Connection already running")
+        self._task = asyncio.create_task(self._runner())
+
+    async def stop(self) -> None:
+        """Request graceful shutdown."""
+        self._stop_event.set()
+        if self._task is not None:
+            await self._task
+
+    async def _runner(self) -> None:
+        attempt = 0
+        while not self._stop_event.is_set():
+            try:
+                if attempt:
+                    delay = min(self.reconnect_delay * 2 ** (attempt - 1), 30)
+                    logger.warning("Reconnecting in %.1f s (attempt %d/%d)…", delay, attempt, self.max_retries)
+                    await asyncio.sleep(delay)
+                logger.info("Connecting to gateway at %s", self.gateway_url)
+                async with websockets.connect(self.gateway_url) as ws:
+                    # Reset attempt counter after successful connection
+                    attempt = 0
+
+                    self.websocket = ws
+                    self.mux = Multiplexer(self.websocket.send)
+
+                    # ------------------------------------------------------------------
+                    # Initialise terminal/control management (channel 0)
+                    # ------------------------------------------------------------------
+                    try:
+                        from .terminal import TerminalManager  # local import to avoid heavy deps on startup
+                        self._terminal_manager = TerminalManager(self.mux)  # noqa: pylint=attribute-defined-outside-init
+                    except Exception as exc:
+                        logger.warning("TerminalManager unavailable: %s", exc)
+
+                    # Authenticate – abort loop on auth failures
+                    await self._authenticate()
+
+                    # Start main receive loop until closed or stop requested
+                    await self._listen()
+            except (OSError, websockets.WebSocketException) as exc:
+                attempt += 1
+                logger.warning("Connection error: %s", exc)
+                if attempt > self.max_retries:
+                    logger.error("Maximum reconnect attempts reached, giving up.")
+                    break
+            except Exception as exc:
+                logger.exception("Fatal error in connection manager: %s", exc)
+                break
+
+    async def _authenticate(self) -> None:
+        """Challenge-response authentication with the gateway using base64 DER public key."""
+        assert self.websocket is not None, "WebSocket not ready"
+        # Step 1: Send public key as base64 DER
+        await self.websocket.send(self.keypair.public_key_der_b64())
+        # Step 2: Receive challenge or error
+        response = await self.websocket.recv()
+        try:
+            data = json.loads(response)
+            challenge = data["challenge"]
+        except Exception:
+            # Not a challenge, must be an error
+            raise RuntimeError(f"Gateway rejected authentication: {response}")
+        # Step 3: Sign challenge and send signature
+        signature = self.keypair.sign_challenge(challenge)
+        signature_b64 = base64.b64encode(signature).decode()
+        await self.websocket.send(json.dumps({"signature": signature_b64}))
+        # Step 4: Receive final status
+        status = await self.websocket.recv()
+        if status != "ok":
+            raise RuntimeError(f"Gateway rejected authentication: {status}")
+        # Print success message in green and show close instructions
+        try:
+            import click
+            click.echo(click.style("Successfully authenticated with the gateway.", fg="green"))
+            if sys.platform == "darwin":
+                click.echo(click.style("Press Cmd+C to close the connection.", fg="cyan"))
+            else:
+                click.echo(click.style("Press Ctrl+C to close the connection.", fg="cyan"))
+        except ImportError:
+            print("Successfully authenticated with the gateway.")
+            if sys.platform == "darwin":
+                print("Press Cmd+C to close the connection.")
+            else:
+                print("Press Ctrl+C to close the connection.")
+
+    async def _listen(self) -> None:
+        assert self.websocket is not None, "WebSocket not ready"
+        while not self._stop_event.is_set():
+            try:
+                message = await asyncio.wait_for(self.websocket.recv(), timeout=1.0)
+                if self.mux:
+                    await self.mux.on_raw_message(message)
+            except asyncio.TimeoutError:
+                continue
+            except websockets.ConnectionClosed:
+                break
+        # Exit listen loop, trigger closure
+        try:
+            await self.websocket.close()
+        except Exception:
+            pass
+
+
+async def run_until_interrupt(manager: ConnectionManager) -> None:
+    stop_event = asyncio.Event()
+
+    def _stop(*_):
+        # TODO: Add cleanup logic here (e.g., close sockets, remove PID files, flush logs)
+        stop_event.set()
+
+    # Register SIGTERM handler (works on Unix, ignored on Windows)
+    try:
+        signal.signal(signal.SIGTERM, _stop)
+    except (AttributeError, ValueError):
+        pass  # Not available on some platforms
+
+    # Register SIGINT handler (Ctrl+C)
+    try:
+        signal.signal(signal.SIGINT, _stop)
+    except (AttributeError, ValueError):
+        pass
+
+    await manager.start()
+    try:
+        await stop_event.wait()
+    except KeyboardInterrupt:
+        # TODO: Add cleanup logic here (e.g., close sockets, remove PID files, flush logs)
+        pass
+    await manager.stop()
+    # TODO: Add any final cleanup logic here (e.g., remove PID files, flush logs) 

portacode-0.1.0/portacode/connection/multiplex.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from asyncio import Queue
+from typing import Any, Dict
+
+__all__ = ["Multiplexer", "Channel"]
+
+logger = logging.getLogger(__name__)
+
+
+class Channel:
+    """Represents a virtual duplex channel over a single WebSocket connection."""
+
+    def __init__(self, channel_id: int, multiplexer: "Multiplexer"):
+        self.id = channel_id
+        self._mux = multiplexer
+        self._incoming: "Queue[Any]" = asyncio.Queue()
+
+    async def send(self, payload: Any) -> None:
+        await self._mux._send_on_channel(self.id, payload)
+
+    async def recv(self) -> Any:
+        return await self._incoming.get()
+
+    # Internal API
+    async def _deliver(self, payload: Any) -> None:
+        await self._incoming.put(payload)
+
+
+class Multiplexer:
+    """Very small message-based multiplexer.
+
+    Messages exchanged over the WebSocket are JSON objects with two keys:
+
+    * ``channel`` – integer channel id.
+    * ``payload``  – arbitrary JSON-serialisable object.
+    """
+
+    def __init__(self, send_func):
+        self._send_func = send_func  # async function (str) -> None
+        self._channels: Dict[int, Channel] = {}
+
+    def get_channel(self, channel_id: int) -> Channel:
+        if channel_id not in self._channels:
+            self._channels[channel_id] = Channel(channel_id, self)
+        return self._channels[channel_id]
+
+    async def _send_on_channel(self, channel_id: int, payload: Any) -> None:
+        frame = json.dumps({"channel": channel_id, "payload": payload})
+        await self._send_func(frame)
+
+    async def on_raw_message(self, raw: str) -> None:
+        try:
+            data = json.loads(raw)
+            channel_id = int(data["channel"])
+            payload = data.get("payload")
+        except (ValueError, KeyError) as exc:
+            logger.warning("Discarding malformed frame: %s", exc)
+            return
+
+        channel = self.get_channel(channel_id)
+        await channel._deliver(payload) 

portacode-0.1.0/portacode/connection/terminal.py

@@ -0,0 +1,421 @@
+from __future__ import annotations
+
+"""Terminal session management for Portacode client.
+
+This module allows the Portacode gateway to remotely create interactive shell
+sessions on the client machine.  Each session gets its own *virtual* channel
+on the existing WebSocket connection so multiple interactive terminals can run
+concurrently without opening extra sockets.
+
+The current implementation intentionally stays simple so it works on both
+Unix and Windows without extra native dependencies:
+
+* On Unix we *try* to allocate a real PTY so command‐line applications detect
+  a TTY and are willing to emit colour sequences, progress bars, etc.
+* On Windows we fall back to a standard subprocess with pipes.  While this
+  means some programs may not detect a TTY, it still provides a usable shell
+  until winpty/pywinpty support is added in the future.
+
+Each message exchanged with the gateway uses JSON frames on the **control
+channel 0**.  The schema is kept deliberately small for now – it will evolve
+as we add more capabilities:
+
+Gateway → Client commands (via channel 0)
+-----------------------------------------
+
+1. Start new terminal::
+
+    {"cmd": "terminal_start", "shell": "/bin/bash"}  // *shell* optional
+
+   • Response (same channel):
+     {"event": "terminal_started", "terminal_id": "...", "channel": 123}
+
+2. Send data to running terminal::
+
+    {"cmd": "terminal_send", "terminal_id": "...", "data": "ls -l\n"}
+
+3. Close running terminal::
+
+    {"cmd": "terminal_stop", "terminal_id": "..."}
+
+4. List terminals::
+
+    {"cmd": "terminal_list"}
+   • Response: {"event": "terminal_list", "sessions": [...]}  // see code
+
+5. System information::
+
+    {"cmd": "system_info"}
+   • Response: {"event": "system_info", "info": {...}}
+
+Client → Gateway events (channel 0 unless stated otherwise)
+---------------------------------------------------------
+
+• Terminal exited (channel 0)::
+
+    {"event": "terminal_exit", "terminal_id": "...", "returncode": 0}
+
+• Terminal output (dedicated *session* channel)::
+
+    <raw utf-8 text frames>  // JSON encoding avoided for efficiency
+
+NOTE: For output we currently send **plain text** frames (not JSON) so binary
+streams like progress bars or colour escapes are delivered unchanged.  If the
+payload must be JSON for some transports, base64-encoding could be used – but
+that adds 33 % overhead so plain frames are preferred.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import uuid
+from asyncio.subprocess import Process
+from pathlib import Path
+from typing import Any, Dict, Optional
+from collections import deque
+
+import psutil  # type: ignore
+
+from .multiplex import Multiplexer, Channel
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "TerminalManager",
+]
+
+
+_IS_WINDOWS = sys.platform.startswith("win")
+
+
+class TerminalSession:
+    """Represents a local shell subprocess bound to a mux *channel*."""
+
+    def __init__(self, session_id: str, proc: Process, channel: Channel):
+        self.id = session_id
+        self.proc = proc
+        self.channel = channel
+        self._reader_task: Optional[asyncio.Task[None]] = None
+        self._buffer: deque[str] = deque(maxlen=400)  # keep last ~400 lines of raw output
+
+    async def start_io_forwarding(self) -> None:
+        """Spawn background task that copies stdout/stderr to the channel."""
+        assert self.proc.stdout is not None, "stdout pipe not set"
+
+        async def _pump() -> None:
+            try:
+                while True:
+                    data = await self.proc.stdout.read(1024)
+                    if not data:
+                        break
+                    # Send *raw* text – no JSON envelope, keep escapes intact.
+                    text = data.decode(errors="ignore")
+                    logging.getLogger("portacode.terminal").debug(f"[MUX] Terminal {self.id} output: {text!r}")
+                    self._buffer.append(text)
+                    try:
+                        await self.channel.send(text)
+                    except Exception as exc:
+                        logger.warning("Failed to forward terminal output: %s", exc)
+                        break
+            finally:
+                # Ensure process gets reaped if reader exits unexpectedly.
+                if self.proc and self.proc.returncode is None:
+                    self.proc.kill()
+
+        self._reader_task = asyncio.create_task(_pump())
+
+    async def write(self, data: str) -> None:
+        if self.proc.stdin is None:
+            logger.warning("stdin pipe closed for terminal %s", self.id)
+            return
+        try:
+            self.proc.stdin.write(data.encode())
+            await self.proc.stdin.drain()
+        except Exception as exc:
+            logger.warning("Failed to write to terminal %s: %s", self.id, exc)
+
+    async def stop(self) -> None:
+        if self.proc.returncode is None:
+            self.proc.terminate()
+        if self._reader_task:
+            await self._reader_task
+        await self.proc.wait()
+
+    # ------------------------------------------------------------------
+    # Introspection helpers
+    # ------------------------------------------------------------------
+
+    def snapshot_buffer(self) -> str:
+        """Return concatenated last buffer contents suitable for UI."""
+        return "".join(self._buffer)
+
+
+class TerminalManager:
+    """Manage multiple *TerminalSession*s controlled over a mux channel."""
+
+    CONTROL_CHANNEL_ID = 0  # messages with JSON commands/events
+
+    def __init__(self, mux: Multiplexer):
+        self.mux = mux
+        self._sessions: Dict[str, TerminalSession] = {}
+        self._next_channel = 100  # channel ids >=100 reserved for terminals
+        # Start control-loop task
+        self._control_channel = self.mux.get_channel(self.CONTROL_CHANNEL_ID)
+        self._ctl_task = asyncio.create_task(self._control_loop())
+
+    # ---------------------------------------------------------------------
+    # Control loop – receives commands from gateway
+    # ---------------------------------------------------------------------
+
+    async def _control_loop(self) -> None:
+        while True:
+            message = await self._control_channel.recv()
+            # Older parts of the system may send *raw* str.  Ensure dict.
+            if isinstance(message, str):
+                try:
+                    message = json.loads(message)
+                except Exception:
+                    logger.warning("Discarding non-JSON control frame: %s", message)
+                    continue
+            if not isinstance(message, dict):
+                logger.warning("Invalid control frame type: %r", type(message))
+                continue
+            cmd = message.get("cmd")
+            if not cmd:
+                # Ignore frames that are *events* coming from the remote side
+                if message.get("event"):
+                    continue
+                logger.warning("Missing 'cmd' in control frame: %s", message)
+                continue
+            try:
+                if cmd == "terminal_start":
+                    shell = message.get("shell")
+                    cwd = message.get("cwd")
+                    await self._cmd_terminal_start(shell=shell, cwd=cwd)
+                elif cmd == "terminal_send":
+                    await self._cmd_terminal_send(message)
+                elif cmd == "terminal_stop":
+                    await self._cmd_terminal_stop(message)
+                elif cmd == "terminal_list":
+                    await self._cmd_terminal_list()
+                elif cmd == "system_info":
+                    await self._cmd_system_info()
+                else:
+                    await self._send_error(f"Unknown cmd: {cmd}")
+            except Exception as exc:
+                logger.exception("Unhandled exception processing %s: %s", cmd, exc)
+                await self._send_error(str(exc))
+
+    # ------------------------------------------------------------------
+    # Individual command handlers
+    # ------------------------------------------------------------------
+
+    async def _cmd_terminal_start(self, *, shell: Optional[str], cwd: Optional[str] = None) -> None:
+        term_id = uuid.uuid4().hex
+        channel_id = self._allocate_channel_id()
+        channel = self.mux.get_channel(channel_id)
+        # Choose shell
+        if shell is None:
+            shell = os.getenv("SHELL") if not _IS_WINDOWS else os.getenv("COMSPEC", "cmd.exe")
+        logger.info("Launching terminal %s using shell=%s on channel=%d", term_id, shell, channel_id)
+        if _IS_WINDOWS:
+            # Windows: use ConPTY via pywinpty for full TTY semantics
+            try:
+                from winpty import PtyProcess  # type: ignore
+            except ImportError as exc:
+                logger.error("winpty (pywinpty) not found – please install pywinpty: %s", exc)
+                await self._send_error("pywinpty not installed on client")
+                return
+
+            pty_proc = PtyProcess.spawn(shell, cwd=cwd or None)
+
+            class _WinPTYProxy:
+                """Expose .pid and .returncode for compatibility with Linux branch."""
+
+                def __init__(self, pty):
+                    self._pty = pty
+
+                @property
+                def pid(self):
+                    return self._pty.pid
+
+                @property
+                def returncode(self):
+                    # None while running, else exitstatus
+                    return None if self._pty.isalive() else self._pty.exitstatus
+
+                async def wait(self):
+                    loop = asyncio.get_running_loop()
+                    await loop.run_in_executor(None, self._pty.wait)
+
+            class WindowsTerminalSession(TerminalSession):
+                """Terminal session backed by a Windows ConPTY."""
+
+                def __init__(self, session_id: str, pty, channel: Channel):
+                    super().__init__(session_id, _WinPTYProxy(pty), channel)
+                    self._pty = pty
+
+                async def start_io_forwarding(self) -> None:
+                    loop = asyncio.get_running_loop()
+
+                    async def _pump() -> None:
+                        try:
+                            while True:
+                                data = await loop.run_in_executor(None, self._pty.read, 1024)
+                                if not data:
+                                    if not self._pty.isalive():
+                                        break
+                                    await asyncio.sleep(0.05)
+                                    continue
+                                if isinstance(data, bytes):
+                                    text = data.decode(errors="ignore")
+                                else:
+                                    text = data
+                                logging.getLogger("portacode.terminal").debug(
+                                    f"[MUX] Terminal {self.id} output: {text!r}"
+                                )
+                                self._buffer.append(text)
+                                try:
+                                    await self.channel.send(text)
+                                except Exception as exc:
+                                    logger.warning("Failed to forward terminal output: %s", exc)
+                                    break
+                        finally:
+                            if self._pty and self._pty.isalive():
+                                self._pty.kill()
+
+                    self._reader_task = asyncio.create_task(_pump())
+
+                async def write(self, data: str) -> None:
+                    loop = asyncio.get_running_loop()
+                    try:
+                        await loop.run_in_executor(None, self._pty.write, data)
+                    except Exception as exc:
+                        logger.warning("Failed to write to terminal %s: %s", self.id, exc)
+
+                async def stop(self) -> None:
+                    if self._pty.isalive():
+                        self._pty.kill()
+                    if self._reader_task:
+                        await self._reader_task
+
+            session = WindowsTerminalSession(term_id, pty_proc, channel)
+            self._sessions[term_id] = session
+            await session.start_io_forwarding()
+            await self._control_channel.send(
+                {
+                    "event": "terminal_started",
+                    "terminal_id": term_id,
+                    "channel": channel_id,
+                }
+            )
+
+            asyncio.create_task(self._watch_process_exit(session))
+            return  # windows branch done
+        else:
+            # Unix: try real PTY for proper TTY semantics
+            try:
+                import pty
+                master_fd, slave_fd = pty.openpty()
+                proc = await asyncio.create_subprocess_exec(
+                    shell,
+                    stdin=slave_fd,
+                    stdout=slave_fd,
+                    stderr=slave_fd,
+                    preexec_fn=os.setsid,
+                    cwd=cwd,
+                )
+                # Wrap master_fd into a StreamReader
+                loop = asyncio.get_running_loop()
+                reader = asyncio.StreamReader()
+                protocol = asyncio.StreamReaderProtocol(reader)
+                await loop.connect_read_pipe(lambda: protocol, os.fdopen(master_fd, "rb", buffering=0))
+                proc.stdout = reader  # type: ignore[assignment]
+                # Use writer for stdin
+                writer_transport, writer_protocol = await loop.connect_write_pipe(lambda: asyncio.Protocol(), os.fdopen(master_fd, "wb", buffering=0))
+                proc.stdin = asyncio.StreamWriter(writer_transport, writer_protocol, reader, loop)  # type: ignore[assignment]
+            except Exception:
+                logger.warning("Failed to allocate PTY, falling back to pipes")
+                proc = await asyncio.create_subprocess_exec(
+                    shell,
+                    stdin=asyncio.subprocess.PIPE,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    cwd=cwd,
+                )
+            session = TerminalSession(term_id, proc, channel)
+            self._sessions[term_id] = session
+            await session.start_io_forwarding()
+            await self._control_channel.send(
+                {
+                    "event": "terminal_started",
+                    "terminal_id": term_id,
+                    "channel": channel_id,
+                }
+            )
+
+            # Also create background watcher for process exit
+            asyncio.create_task(self._watch_process_exit(session))
+
+    async def _cmd_terminal_send(self, msg: Dict[str, Any]) -> None:
+        term_id = msg.get("terminal_id")
+        data = msg.get("data", "")
+        session = self._sessions.get(term_id)
+        if not session:
+            await self._send_error(f"terminal_id {term_id} not found")
+            return
+        await session.write(data)
+
+    async def _cmd_terminal_stop(self, msg: Dict[str, Any]) -> None:
+        term_id = msg.get("terminal_id")
+        session = self._sessions.pop(term_id, None)
+        if not session:
+            await self._send_error(f"terminal_id {term_id} not found")
+            return
+        await session.stop()
+        await self._control_channel.send({"event": "terminal_stopped", "terminal_id": term_id})
+
+    async def _cmd_terminal_list(self) -> None:
+        sessions = [
+            {
+                "terminal_id": s.id,
+                "channel": s.channel.id,
+                "pid": s.proc.pid,
+                "returncode": s.proc.returncode,
+                "buffer": s.snapshot_buffer(),
+            }
+            for s in self._sessions.values()
+        ]
+        await self._control_channel.send({"event": "terminal_list", "sessions": sessions})
+
+    async def _cmd_system_info(self) -> None:
+        info = {
+            "cpu_percent": psutil.cpu_percent(interval=0.1),
+            "memory": psutil.virtual_memory()._asdict(),
+            "disk": psutil.disk_usage(str(Path.home()))._asdict(),
+        }
+        await self._control_channel.send({"event": "system_info", "info": info})
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    async def _send_error(self, message: str) -> None:
+        await self._control_channel.send({"event": "error", "message": message})
+
+    def _allocate_channel_id(self) -> int:
+        cid = self._next_channel
+        self._next_channel += 1
+        return cid
+
+    async def _watch_process_exit(self, session: TerminalSession) -> None:
+        await session.proc.wait()
+        await self._control_channel.send({
+            "event": "terminal_exit",
+            "terminal_id": session.id,
+            "returncode": session.proc.returncode,
+        })
+        # Cleanup session table
+        self._sessions.pop(session.id, None) 

portacode-0.1.0/portacode/data.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from platformdirs import user_data_dir
+
+APP_NAME = "portacode"
+APP_AUTHOR = "Portacode"
+
+
+def get_data_dir() -> Path:
+    """Return the platform-specific *user data* directory for Portacode.
+
+    This is where all persistent user data (keypairs, logs, pid files, …) is stored.
+    The directory is created on first use.
+    """
+
+    data_dir = Path(user_data_dir(APP_NAME, APP_AUTHOR))
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir
+
+
+def get_key_dir() -> Path:
+    key_dir = get_data_dir() / "keys"
+    key_dir.mkdir(parents=True, exist_ok=True)
+    return key_dir
+
+
+def get_runtime_dir() -> Path:
+    """Return directory for runtime files (pid, sockets, …)."""
+    runtime_dir = get_data_dir() / "run"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    return runtime_dir
+
+
+def get_pid_file() -> Path:
+    return get_runtime_dir() / "gateway.pid"
+
+
+def is_process_running(pid: int) -> bool:
+    """Check whether *pid* refers to a currently running process."""
+    if sys.platform.startswith("win"):
+        import ctypes
+        import ctypes.wintypes as wintypes
+
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        handle = ctypes.windll.kernel32.OpenProcess(
+            PROCESS_QUERY_LIMITED_INFORMATION, False, pid
+        )
+        if handle == 0:
+            return False
+        ctypes.windll.kernel32.CloseHandle(handle)
+        return True
+    else:
+        try:
+            os.kill(pid, 0)
+        except OSError:
+            return False
+        return True 

portacode-0.1.0/portacode/keypair.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Tuple
+import logging
+import base64
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa, padding
+from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption, PrivateFormat, PublicFormat
+
+from .data import get_key_dir
+
+PRIVATE_KEY_FILE = "id_portacode"
+PUBLIC_KEY_FILE = "id_portacode.pub"
+
+logging.basicConfig(level=logging.INFO, format='[%(levelname)s] %(message)s')
+
+class KeyPair:
+    """Container for RSA keypair paths and objects."""
+
+    def __init__(self, private_key_path: Path, public_key_path: Path):
+        self.private_key_path = private_key_path
+        self.public_key_path = public_key_path
+
+    @property
+    def private_key_pem(self) -> bytes:
+        return self.private_key_path.read_bytes()
+
+    @property
+    def public_key_pem(self) -> bytes:
+        return self.public_key_path.read_bytes()
+
+    def sign_challenge(self, challenge: str) -> bytes:
+        """Sign a challenge string with the private key."""
+        private_key = serialization.load_pem_private_key(
+            self.private_key_pem, password=None
+        )
+        return private_key.sign(
+            challenge.encode(),
+            padding.PKCS1v15(),
+            hashes.SHA256(),
+        )
+
+    def public_key_der_b64(self) -> str:
+        """Return the public key as base64-encoded DER (single line)."""
+        pubkey = serialization.load_pem_public_key(self.public_key_pem)
+        der = pubkey.public_bytes(encoding=serialization.Encoding.DER, format=serialization.PublicFormat.SubjectPublicKeyInfo)
+        return base64.b64encode(der).decode()
+
+    @staticmethod
+    def der_b64_to_pem(der_b64: str) -> bytes:
+        """Convert base64 DER to PEM format."""
+        der = base64.b64decode(der_b64)
+        pubkey = serialization.load_der_public_key(der)
+        return pubkey.public_bytes(encoding=serialization.Encoding.PEM, format=serialization.PublicFormat.SubjectPublicKeyInfo)
+
+
+def _generate_keypair() -> Tuple[bytes, bytes]:
+    # Use 1024 bits for smaller demo keys (not secure for production)
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=1024)
+    private_pem = private_key.private_bytes(
+        encoding=Encoding.PEM,
+        format=PrivateFormat.TraditionalOpenSSL,
+        encryption_algorithm=NoEncryption(),
+    )
+    public_pem = (
+        private_key.public_key()
+        .public_bytes(Encoding.PEM, PublicFormat.SubjectPublicKeyInfo)
+    )
+    return private_pem, public_pem
+
+
+def get_or_create_keypair() -> KeyPair:
+    """Return the existing keypair or generate a new one if missing."""
+    key_dir = get_key_dir()
+    priv_path = key_dir / PRIVATE_KEY_FILE
+    pub_path = key_dir / PUBLIC_KEY_FILE
+
+    if not priv_path.exists() or not pub_path.exists():
+        logging.info(f"No keys found, generating new one and saving to {key_dir}")
+        private_pem, public_pem = _generate_keypair()
+        priv_path.write_bytes(private_pem)
+        pub_path.write_bytes(public_pem)
+    else:
+        logging.info(f"Found existing keys at {key_dir}")
+
+    return KeyPair(priv_path, pub_path)
+
+
+def fingerprint_public_key(pem: bytes) -> str:
+    """Return a short fingerprint for display purposes (SHA-256)."""
+    digest = hashes.Hash(hashes.SHA256())
+    digest.update(pem)
+    return digest.finalize().hex()[:16] 

portacode-0.1.0/portacode.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: portacode
+Version: 0.1.0
+Summary: Portacode CLI client and SDK
+Home-page: https://github.com/portacode/portacode
+Author: Meena Erian
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: platformdirs>=3.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyte>=0.8
+Requires-Dist: pywinpty>=2.0; platform_system == "Windows"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Portacode
+
+Portacode is a modular Python package that provides a command-line interface for connecting your local machine to the Portacode cloud gateway.
+
+```
+$ pip install portacode
+$ portacode connect
+```
+
+The first release only ships the `connect` command which:
+
+1. Creates an RSA public/private key-pair (if not already present) in a platform-specific data directory.
+2. Guides you through adding the public key to your Portacode account.
+3. Establishes and maintains a resilient WebSocket connection to `wss://portacode.com/gateway`.
+
+Future releases will add more sub-commands and build upon the multiplexing channel infrastructure already included in this version.
+
+## Project layout
+
+```
+portacode/          ‑ Top-level package
+├── cli.py          ‑ Click-based CLI entry-point
+├── data.py         ‑ Cross-platform data-directory helpers
+├── keypair.py      ‑ RSA key generation & storage
+├── connection/     ‑ Networking & multiplexing logic
+│   ├── client.py   ‑ WebSocket client with auto-reconnect
+│   └── multiplex.py- Virtual channel multiplexer
+└── …
+```
+
+See the README files inside each sub-module for more details. 

portacode-0.1.0/portacode.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+MANIFEST.in
+README.md
+setup.py
+portacode/__init__.py
+portacode/cli.py
+portacode/data.py
+portacode/keypair.py
+portacode.egg-info/PKG-INFO
+portacode.egg-info/SOURCES.txt
+portacode.egg-info/dependency_links.txt
+portacode.egg-info/entry_points.txt
+portacode.egg-info/requires.txt
+portacode.egg-info/top_level.txt
+portacode/connection/__init__.py
+portacode/connection/client.py
+portacode/connection/multiplex.py
+portacode/connection/terminal.py

portacode-0.1.0/portacode.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

portacode-0.1.0/portacode.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+portacode = portacode.cli:cli

portacode-0.1.0/portacode.egg-info/requires.txt

@@ -0,0 +1,15 @@
+click>=8.0
+platformdirs>=3.0
+cryptography>=41.0
+websockets>=12.0
+pyperclip>=1.8
+psutil>=5.9
+pyte>=0.8
+
+[:platform_system == "Windows"]
+pywinpty>=2.0
+
+[dev]
+black
+flake8
+pytest

portacode-0.1.0/portacode.egg-info/top_level.txt

@@ -0,0 +1 @@
+portacode

portacode-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

portacode-0.1.0/setup.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+
+from setuptools import find_packages, setup
+
+PACKAGE_NAME = "portacode"
+ROOT = Path(__file__).parent
+README = (ROOT / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name=PACKAGE_NAME,
+    version="0.1.0",
+    description="Portacode CLI client and SDK",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    author="Meena Erian",
+    url="https://github.com/portacode/portacode",
+    packages=find_packages(exclude=("tests", "server")),
+    python_requires=">=3.8",
+    install_requires=[
+        "click>=8.0",
+        "platformdirs>=3.0",
+        "cryptography>=41.0",
+        "websockets>=12.0",
+        "pyperclip>=1.8",
+        "psutil>=5.9",
+        "pyte>=0.8",
+        "pywinpty>=2.0; platform_system=='Windows'",
+    ],
+    extras_require={
+        "dev": ["black", "flake8", "pytest"],
+    },
+    entry_points={
+        "console_scripts": [
+            "portacode=portacode.cli:cli",
+        ]
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    include_package_data=True,
+)