terminux 0.1.0__py3-none-any.whl

terminux/__init__.py

@@ -0,0 +1,5 @@
+"""terminux — a cross-platform desktop terminal with workspaces and tabs."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

terminux/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m terminux`` → launch the app."""
+
+from __future__ import annotations
+
+from terminux.app import main
+
+if __name__ == "__main__":
+    main()

terminux/app.py

@@ -0,0 +1,123 @@
+"""Entrypoint: run the loopback server, then host it in a pywebview window.
+
+``--no-window`` runs the server headless (browse to the printed URL) — used
+for development and e2e tests, and a preview of the future "web mode".
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import logging
+import socket
+import threading
+import time
+from typing import cast
+
+import uvicorn
+
+from terminux.server.asgi import AppController, build_app
+from terminux.server.auth import SESSION_TOKEN
+
+log = logging.getLogger(__name__)
+HOST = "127.0.0.1"
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind((HOST, 0))
+        return int(s.getsockname()[1])
+
+
+def _serve(server: uvicorn.Server) -> None:
+    server.run()
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=logging.INFO, format="%(levelname)s %(name)s: %(message)s"
+    )
+    parser = argparse.ArgumentParser(prog="terminux")
+    parser.add_argument(
+        "--no-window",
+        action="store_true",
+        help="run the server only (no desktop window)",
+    )
+    parser.add_argument("--port", type=int, default=0, help="bind port (0 = ephemeral)")
+    args = parser.parse_args()
+
+    port = args.port or _free_port()
+    app = build_app(persist=True)
+    config = uvicorn.Config(
+        app,
+        host=HOST,
+        port=port,
+        log_level="warning",
+        ws="websockets-sansio",  # avoid the deprecated legacy websockets impl
+    )
+    server = uvicorn.Server(config)
+
+    thread = threading.Thread(target=_serve, args=(server,), daemon=True)
+    thread.start()
+    while not server.started:
+        time.sleep(0.02)
+
+    url = f"http://{HOST}:{port}/?t={SESSION_TOKEN}"
+    log.info("terminux server ready at %s", url)
+
+    if args.no_window:
+        with contextlib.suppress(KeyboardInterrupt):
+            thread.join()
+        return
+
+    _run_windowed(url, app.state.controller, server)
+
+
+def _run_windowed(url: str, ctl: AppController, server: uvicorn.Server) -> None:
+    import webview  # noqa: PLC0415  (heavy GUI import; only when windowing)
+    from webview.dom import DOMEventHandler  # noqa: PLC0415
+
+    window = webview.create_window("terminux", url, width=1100, height=720)
+    if window is None:
+        msg = "failed to create application window"
+        raise RuntimeError(msg)
+
+    def _on_drop(event: dict[str, object]) -> None:
+        # WKWebView hides file paths from JS; pywebview injects the real path
+        # as ``pywebviewFullPath`` only for a Python drop handler (registering
+        # one also enables the native Cocoa path capture). Route them to the
+        # active terminal, shell-quoted — drop a file into Claude Code.
+        # ``event`` is pywebview's loosely-typed JSON event dict.
+        if not isinstance(event, dict):
+            return
+        transfer = event.get("dataTransfer")
+        files = (
+            cast("dict[str, object]", transfer).get("files")
+            if isinstance(transfer, dict)
+            else None
+        )
+        paths: list[str] = []
+        for f in files if isinstance(files, list) else []:
+            if isinstance(f, dict):
+                p = cast("dict[str, object]", f).get("pywebviewFullPath")
+                if isinstance(p, str):
+                    paths.append(p)
+        if paths:
+            ctl.paste_paths(paths)
+
+    def _register_drop() -> None:
+        # Must run after the DOM is loaded; prevent_default stops the webview
+        # from navigating to the dropped file.
+        window.dom.document.on("drop", DOMEventHandler(_on_drop, prevent_default=True))
+
+    def _shutdown() -> None:
+        ctl.terminals.close_all()
+        server.should_exit = True
+
+    window.events.loaded += _register_drop
+    window.events.closed += _shutdown
+    webview.start()
+
+
+if __name__ == "__main__":
+    main()

terminux/core/__init__.py

@@ -0,0 +1,3 @@
+"""Core domain: state model, persistence, and PTY-backed terminals."""
+
+from __future__ import annotations

terminux/core/model.py

@@ -0,0 +1,291 @@
+"""In-memory authoritative app state: workspaces and tabs.
+
+Only structure (ids, names, order, active selection, UI prefs) is persisted.
+Live terminals are transient and rebuilt on demand; see ``core.terminal``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex
+
+
+class WorkspaceStatus(str, Enum):
+    """Auto-derived sidebar status (functional spec §4.4)."""
+
+    ACTIVE = "active"
+    RUNNING = "running"
+    IDLE = "idle"
+    EXITED = "exited"
+
+
+@dataclass
+class Tab:
+    """One terminal session inside a workspace."""
+
+    id: str = field(default_factory=_new_id)
+    title: str = "shell"
+    user_set_title: bool = False
+    # Transient (never persisted):
+    terminal_id: str | None = None
+    has_unseen_output: bool = False
+    spawn_cwd: str | None = None  # directory inherited from the previous tab
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "user_set_title": self.user_set_title,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Tab:
+        return cls(
+            id=str(data["id"]),
+            title=str(data.get("title", "shell")),
+            user_set_title=bool(data.get("user_set_title")),
+        )
+
+
+@dataclass
+class Workspace:
+    """A named container for a set of terminal tabs."""
+
+    id: str = field(default_factory=_new_id)
+    name: str = "workspace"
+    tab_ids: list[str] = field(default_factory=list)
+    active_tab_id: str | None = None
+    # Transient: set when a tab produces output while this workspace is not active.
+    has_unseen_output: bool = False
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "tab_ids": list(self.tab_ids),
+            "active_tab_id": self.active_tab_id,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Workspace:
+        return cls(
+            id=str(data["id"]),
+            name=str(data.get("name", "workspace")),
+            tab_ids=[str(t) for t in data.get("tab_ids", [])],
+            active_tab_id=(
+                str(data["active_tab_id"])
+                if data.get("active_tab_id") is not None
+                else None
+            ),
+        )
+
+
+@dataclass
+class UiPrefs:
+    """Persisted UI preferences."""
+
+    sidebar_width: int = 220
+    sidebar_collapsed: bool = False
+    font_size: int = 13
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "sidebar_width": self.sidebar_width,
+            "sidebar_collapsed": self.sidebar_collapsed,
+            "font_size": self.font_size,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> UiPrefs:
+        return cls(
+            sidebar_width=int(data.get("sidebar_width", 220)),
+            sidebar_collapsed=bool(data.get("sidebar_collapsed")),
+            font_size=int(data.get("font_size", 13)),
+        )
+
+
+SCHEMA_VERSION = 1
+
+
+@dataclass
+class AppState:
+    """Authoritative state. All mutation happens on the backend event loop."""
+
+    workspaces: list[Workspace] = field(default_factory=list)
+    tabs: dict[str, Tab] = field(default_factory=dict)
+    active_workspace_id: str | None = None
+    ui: UiPrefs = field(default_factory=UiPrefs)
+
+    # ----- construction -------------------------------------------------
+
+    @classmethod
+    def default(cls) -> AppState:
+        """A single workspace with one tab — the always-valid baseline."""
+        state = cls()
+        ws = state.add_workspace(name="workspace 1")
+        state.add_tab(ws.id)
+        state.active_workspace_id = ws.id
+        return state
+
+    # ----- workspace ops ------------------------------------------------
+
+    def add_workspace(self, name: str | None = None) -> Workspace:
+        ws = Workspace(name=name or self._next_workspace_name())
+        self.workspaces.append(ws)
+        return ws
+
+    def _next_workspace_name(self) -> str:
+        used = {w.name for w in self.workspaces}
+        i = 1
+        while f"workspace {i}" in used:
+            i += 1
+        return f"workspace {i}"
+
+    def get_workspace(self, ws_id: str) -> Workspace | None:
+        return next((w for w in self.workspaces if w.id == ws_id), None)
+
+    def remove_workspace(self, ws_id: str) -> list[str]:
+        """Remove a workspace; return the ids of its tabs (caller kills terminals)."""
+        ws = self.get_workspace(ws_id)
+        if ws is None:
+            return []
+        tab_ids = list(ws.tab_ids)
+        for tid in tab_ids:
+            self.tabs.pop(tid, None)
+        self.workspaces = [w for w in self.workspaces if w.id != ws_id]
+        if self.active_workspace_id == ws_id:
+            self.active_workspace_id = (
+                self.workspaces[0].id if self.workspaces else None
+            )
+        return tab_ids
+
+    def set_active_workspace(self, ws_id: str) -> None:
+        if self.get_workspace(ws_id) is None:
+            return
+        self.active_workspace_id = ws_id
+        ws = self.get_workspace(ws_id)
+        if ws is not None:
+            ws.has_unseen_output = False
+            for tid in ws.tab_ids:
+                tab = self.tabs.get(tid)
+                if tab is not None and tid == ws.active_tab_id:
+                    tab.has_unseen_output = False
+
+    # ----- tab ops ------------------------------------------------------
+
+    def add_tab(
+        self,
+        ws_id: str,
+        title: str = "shell",
+        spawn_cwd: str | None = None,
+    ) -> Tab | None:
+        ws = self.get_workspace(ws_id)
+        if ws is None:
+            return None
+        tab = Tab(title=title, spawn_cwd=spawn_cwd)
+        self.tabs[tab.id] = tab
+        ws.tab_ids.append(tab.id)
+        ws.active_tab_id = tab.id
+        return tab
+
+    def remove_tab(self, tab_id: str) -> None:
+        for ws in self.workspaces:
+            if tab_id in ws.tab_ids:
+                ws.tab_ids.remove(tab_id)
+                if ws.active_tab_id == tab_id:
+                    ws.active_tab_id = ws.tab_ids[-1] if ws.tab_ids else None
+        self.tabs.pop(tab_id, None)
+
+    # ----- status -------------------------------------------------------
+
+    def workspace_status(self, ws_id: str) -> WorkspaceStatus:
+        ws = self.get_workspace(ws_id)
+        if ws is None:
+            return WorkspaceStatus.IDLE
+        if ws_id == self.active_workspace_id:
+            return WorkspaceStatus.ACTIVE
+        has_live = any(
+            (t := self.tabs.get(tid)) is not None and t.terminal_id is not None
+            for tid in ws.tab_ids
+        )
+        if not has_live and ws.tab_ids:
+            return WorkspaceStatus.EXITED
+        if ws.has_unseen_output:
+            return WorkspaceStatus.RUNNING
+        return WorkspaceStatus.IDLE
+
+    # ----- serialization ------------------------------------------------
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "version": SCHEMA_VERSION,
+            "workspaces": [w.to_json() for w in self.workspaces],
+            "tabs": [t.to_json() for t in self.tabs.values()],
+            "active_workspace_id": self.active_workspace_id,
+            "ui": self.ui.to_json(),
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> AppState:
+        tabs = {}
+        for raw in data.get("tabs", []):
+            tab = Tab.from_json(raw)
+            tabs[tab.id] = tab
+        workspaces = [Workspace.from_json(w) for w in data.get("workspaces", [])]
+        state = cls(
+            workspaces=workspaces,
+            tabs=tabs,
+            active_workspace_id=data.get("active_workspace_id"),
+            ui=UiPrefs.from_json(data.get("ui", {})),
+        )
+        state._repair()
+        return state
+
+    def _repair(self) -> AppState:
+        """Drop dangling references; guarantee >= 1 workspace with >= 1 tab."""
+        for ws in self.workspaces:
+            ws.tab_ids = [tid for tid in ws.tab_ids if tid in self.tabs]
+            if ws.active_tab_id not in ws.tab_ids:
+                ws.active_tab_id = ws.tab_ids[-1] if ws.tab_ids else None
+            if not ws.tab_ids:
+                tab = Tab()
+                self.tabs[tab.id] = tab
+                ws.tab_ids.append(tab.id)
+                ws.active_tab_id = tab.id
+        # drop orphan tabs not referenced by any workspace
+        referenced = {tid for ws in self.workspaces for tid in ws.tab_ids}
+        self.tabs = {tid: t for tid, t in self.tabs.items() if tid in referenced}
+        if not self.workspaces:
+            ws = self.add_workspace(name="workspace 1")
+            self.add_tab(ws.id)
+        if self.get_workspace(self.active_workspace_id or "") is None:
+            self.active_workspace_id = self.workspaces[0].id
+        return self
+
+    def view_json(self) -> dict[str, Any]:
+        """Snapshot for the frontend, including derived status."""
+        return {
+            "workspaces": [
+                {
+                    **w.to_json(),
+                    "status": self.workspace_status(w.id).value,
+                }
+                for w in self.workspaces
+            ],
+            "tabs": {
+                tid: {
+                    **t.to_json(),
+                    "live": t.terminal_id is not None,
+                    "has_unseen_output": t.has_unseen_output,
+                }
+                for tid, t in self.tabs.items()
+            },
+            "active_workspace_id": self.active_workspace_id,
+            "ui": self.ui.to_json(),
+        }

terminux/core/persistence.py

@@ -0,0 +1,58 @@
+"""Atomic, versioned JSON persistence of structural state.
+
+Live processes and scrollback are never persisted (functional spec §7):
+a restored tab starts a fresh shell.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+import platformdirs
+
+from terminux.core.model import AppState
+
+log = logging.getLogger(__name__)
+
+
+def state_path() -> Path:
+    data_dir = Path(platformdirs.user_data_dir("terminux"))
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir / "state.json"
+
+
+def load_state(path: Path | None = None) -> AppState:
+    """Load persisted state, falling back to a sane default on any error."""
+    path = path or state_path()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        return AppState.from_json(raw)
+    except FileNotFoundError:
+        log.info("no persisted state at %s; starting fresh", path)
+    except (json.JSONDecodeError, KeyError, TypeError, ValueError, OSError) as exc:
+        log.warning("could not load state from %s (%s); starting fresh", path, exc)
+    return AppState.default()
+
+
+def save_state(state: AppState, path: Path | None = None) -> None:
+    """Write state atomically (temp file + os.replace)."""
+    path = path or state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(state.to_json(), indent=2)
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=".state-", suffix=".tmp")
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+            fh.flush()
+            os.fsync(fh.fileno())
+        tmp_path.replace(path)
+    except OSError:
+        log.exception("failed to persist state to %s", path)
+        with contextlib.suppress(OSError):
+            tmp_path.unlink(missing_ok=True)

terminux/core/pty_backend.py

@@ -0,0 +1,137 @@
+"""PTY backend abstraction.
+
+Unix is implemented via ``ptyprocess``. Windows (``pywinpty``/ConPTY) is a
+future addition behind this same Protocol — see technical spec §10.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import signal
+import subprocess  # noqa: S404  (fixed argv to `lsof`, no shell, resolved path)
+import sys
+from pathlib import Path
+from typing import Protocol, cast, runtime_checkable
+
+
+@runtime_checkable
+class PtyBackend(Protocol):
+    """OS-agnostic PTY interface used by ``core.terminal``."""
+
+    @property
+    def fd(self) -> int: ...
+
+    def write(self, data: bytes) -> None: ...
+
+    def resize(self, cols: int, rows: int) -> None: ...
+
+    def is_alive(self) -> bool: ...
+
+    def terminate(self) -> None: ...
+
+    def exit_code(self) -> int | None: ...
+
+    def cwd(self) -> str | None: ...
+
+
+class UnixPty:
+    """PTY-backed child process for POSIX systems."""
+
+    def __init__(self, argv: list[str], cwd: str, cols: int, rows: int) -> None:
+        from ptyprocess import PtyProcess  # noqa: PLC0415  (optional/heavy import)
+
+        env = dict(os.environ)
+        env.setdefault("TERM", "xterm-256color")
+        env["TERMINUX"] = "1"
+        self._proc = PtyProcess.spawn(
+            argv,
+            cwd=cwd,
+            env=env,
+            dimensions=(rows, cols),
+        )
+
+    @property
+    def fd(self) -> int:
+        return int(self._proc.fd)
+
+    def write(self, data: bytes) -> None:
+        with contextlib.suppress(OSError):
+            os.write(self._proc.fd, data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        with contextlib.suppress(OSError, ValueError):
+            self._proc.setwinsize(rows, cols)
+
+    def is_alive(self) -> bool:
+        return bool(self._proc.isalive())
+
+    def terminate(self) -> None:
+        """SIGHUP → SIGTERM → SIGKILL escalation (functional spec §10)."""
+        if not self._proc.isalive():
+            return
+        for sig in (signal.SIGHUP, signal.SIGTERM, signal.SIGKILL):
+            try:
+                self._proc.kill(sig)
+            except OSError:
+                return
+            if not self._proc.isalive():
+                return
+
+    def exit_code(self) -> int | None:
+        if self._proc.isalive():
+            return None
+        try:
+            self._proc.wait()
+        except Exception:  # noqa: BLE001  (best-effort reap)
+            return None
+        return cast("int | None", self._proc.exitstatus)
+
+    def cwd(self) -> str | None:
+        """Best-effort current directory of the shell process.
+
+        Lets a new tab open where the previously active shell was (cmux
+        behaviour), without requiring shell-side OSC 7 configuration.
+        """
+        pid = self._proc.pid
+        if pid is None:
+            return None
+        if sys.platform == "linux":
+            return _linux_cwd(pid)
+        if sys.platform == "darwin":
+            return _darwin_cwd(pid)
+        return None
+
+
+def _linux_cwd(pid: int) -> str | None:
+    with contextlib.suppress(OSError):
+        return str(Path(f"/proc/{pid}/cwd").readlink())
+    return None
+
+
+def _darwin_cwd(pid: int) -> str | None:
+    lsof = shutil.which("lsof")
+    if lsof is None:
+        return None
+    try:
+        result = subprocess.run(  # noqa: S603  (fixed argv, resolved path, no shell)
+            [lsof, "-a", "-d", "cwd", "-p", str(pid), "-Fn"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    for line in result.stdout.splitlines():
+        if line.startswith("n"):
+            return line[1:]
+    return None
+
+
+def spawn_pty(argv: list[str], cwd: str, cols: int, rows: int) -> PtyBackend:
+    if sys.platform == "win32":
+        msg = "Windows PTY backend is not implemented yet (technical spec §10)."
+        raise NotImplementedError(msg)
+    return UnixPty(argv, cwd, cols, rows)

terminux/core/shellprobe.py

@@ -0,0 +1,33 @@
+"""Resolve the default shell and starting directory per OS."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def default_shell() -> list[str]:
+    """Return the argv for a fresh interactive login shell."""
+    if sys.platform == "win32":
+        for candidate in ("pwsh.exe", "powershell.exe", "cmd.exe"):
+            found = shutil.which(candidate)
+            if found:
+                return [found]
+        return ["cmd.exe"]
+    shell = os.environ.get("SHELL")
+    if shell and Path(shell).exists():
+        return [shell, "-l"]
+    for candidate in ("/bin/zsh", "/bin/bash", "/bin/sh"):
+        if Path(candidate).exists():
+            return [candidate, "-l"]
+    return ["/bin/sh"]
+
+
+def default_cwd() -> str:
+    """Starting directory for a new terminal (home, with cwd fallback)."""
+    home = Path.home()
+    if home.is_dir():
+        return str(home)
+    return str(Path.cwd())