terminux 0.1.0__tar.gz

terminux-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

terminux-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

terminux-0.1.0/Makefile

@@ -0,0 +1,34 @@
+.PHONY: all test build format check lint clean
+
+all: test lint
+
+check: lint
+
+lint:
+	uv run --active ruff check
+	uv run --active ruff format --check
+	uv run --active ty check src
+	uv run --active pyrefly check src
+	uv run --active mypy src
+
+format:
+	uv run --active ruff format src tests
+	uv run --active ruff check src tests --fix
+	uv run --active ruff format src tests
+
+test:
+	uv run pytest
+
+test-cov:
+	uv run pytest --cov=terminux --cov-report=html --cov-report=term tests
+
+clean:
+	rm -rf .pytest_cache .ruff_cache dist build __pycache__ .mypy_cache \
+		.coverage htmlcov .coverage.* *.egg-info
+	adt clean
+
+build: clean
+	uv build
+
+publish: build
+	uv publish

terminux-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: terminux
+Version: 0.1.0
+Summary: A cross-platform desktop terminal with workspaces and tabs
+Requires-Python: >=3.12
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: ptyprocess>=0.7
+Requires-Dist: pywebview>=5.0
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=13.0

terminux-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "terminux"
+version = "0.1.0"
+description = "A cross-platform desktop terminal with workspaces and tabs"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pywebview>=5.0",
+    "starlette>=0.40",
+    "uvicorn>=0.30",
+    "ptyprocess>=0.7",
+    "platformdirs>=4.0",
+    "websockets>=13.0",
+]
+
+[project.scripts]
+terminux = "terminux.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/terminux"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "nox>=2026.4.10",
+    "pre-commit>=4.6.0",
+    "pyrefly>=1.0.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.13",
+    "ty>=0.0.37",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "unit: fast isolated unit tests",
+    "integration: component-interaction tests",
+    "e2e: end-to-end workflow tests",
+]
+filterwarnings = [
+    # Inherent to spawning a PTY from our multi-threaded process (ptyprocess
+    # uses pty.fork, then execs immediately); safe here, not actionable.
+    "ignore:This process .* is multi-threaded, use of forkpty.*:DeprecationWarning",
+]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["ptyprocess", "webview", "webview.*"]
+ignore_missing_imports = true
+
+[tool.coverage.run]
+branch = true
+source = ["terminux"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "\\.\\.\\.",
+]
+
+[tool.pyrefly]
+preset = "legacy"
+ignore-missing-imports = [
+    "ptyprocess",
+    "webview",
+    "webview.*",
+]

terminux-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/terminux/core/__init__.py

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

terminux-0.1.0/src/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-0.1.0/src/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)