graphical-ssh 0.1.1__py3-none-any.whl

graphical_ssh-0.1.1.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: graphical-ssh
+Version: 0.1.1
+Summary: Graphical SSH client connection and configuration manager for Debian
+Keywords: ssh,terminal,config,gui,pyqt,debian
+Author: Greg Grace
+Author-email: Greg Grace <ggrace@519lab.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Terminals
+Requires-Dist: pyqt6>=6.7
+Requires-Dist: pyte>=0.8
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Requires-Dist: pytest-qt>=4.4 ; extra == 'dev'
+Requires-Dist: ruff>=0.6 ; extra == 'dev'
+Requires-Python: >=3.12
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# gssh
+
+A graphical SSH client connection and configuration manager for Debian/Linux. Manage your `~/.ssh/config` hosts through a GUI, edit connection parameters, and open SSH sessions — either in an embedded terminal or by launching your preferred external terminal emulator.
+
+## Features
+
+- **Visual host management** — view, add, edit, and delete Host entries from `~/.ssh/config`
+- **Dedicated fields** for the common options: HostName, User, Port, IdentityFile, ProxyJump, ForwardAgent
+- **Extra options** — any arbitrary ssh_config directive via a freeform text area
+- **Safe writes** — atomic file replacement with automatic timestamped backups (`.config.bak.YYYYMMDD_HHMMSS`) and `0600` permissions
+- **Config linter** — catches unknown/deprecated options, insecure key permissions, invalid ports, undefined ProxyJump references, and pattern-overlap conflicts (first-match-wins)
+- **Connection test** — TCP ping-before-connect with latency display
+- **Wildcard hosts** — supports patterns like `*.lab.local`
+- **Search/filter** — live filter by alias, hostname, or user
+- **In-app terminal** — embedded PTY-based terminal using [pyte](https://github.com/selectel/pyte) for VT220 emulation with 5000-line scrollback and 16-colour ANSI
+- **External terminal** — toggle to launch `ssh` in konsole, gnome-terminal, xterm, or any detected emulator
+- **Round-trip safe** — preserves comments, preamble, and unknown directives
+
+## Requirements
+
+- Python 3.12+
+- PyQt6
+- pyte
+- (Optional) a terminal emulator for external mode: konsole, gnome-terminal, xterm, etc.
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+pip install gssh
+gssh
+```
+
+Or run without installing:
+
+```bash
+uvx gssh          # via uv
+pipx run gssh     # via pipx
+```
+
+### From source
+
+```bash
+git clone https://github.com/ggrace519/graphical-ssh.git
+cd graphical-ssh
+uv sync
+uv run gssh
+```
+
+### Desktop integration
+
+To add gssh to your application menu:
+
+```bash
+# If installed via pip, the data files are inside the package:
+python -c "import gssh.data; print(gssh.data.__path__)"
+sudo cp $(python -c "import gssh.data; print(gssh.data.__path__[0])")/gssh.desktop /usr/share/applications/
+sudo cp $(python -c "import gssh.data; print(gssh.data.__path__[0])")/gssh.svg /usr/share/icons/hicolor/scalable/apps/
+sudo update-desktop-database
+```
+
+## Usage
+
+```bash
+# Use default ~/.ssh/config
+uv run gssh
+
+# Specify a custom config file
+uv run gssh -c /path/to/ssh/config
+```
+
+### GUI controls
+
+| Action | How |
+|---|---|
+| Add a host | **Add Host** button → fill in the dialog |
+| Edit a host | Select row → **Edit** button (or double-click to connect) |
+| Delete a host | Select row → **Delete** button → confirm |
+| Connect | Select row → **Connect** (or double-click the row) |
+| Toggle terminal mode | **In-App Terminal** / **External Terminal** toggle |
+| Filter hosts | Type in the search bar |
+| Save changes | **Save** button (writes to config file with backup) |
+| Reload from disk | **Reload** button |
+
+## Development
+
+```bash
+# Run tests with coverage
+uv run pytest
+
+# Run the app
+uv run gssh
+
+# Run with a test config
+uv run gssh -c /tmp/test-config
+```
+
+## Project structure
+
+```
+src/gssh/
+├── __init__.py       # package metadata
+├── __main__.py       # CLI entry point (argparse + QApplication)
+├── config.py         # SSH config parser/writer (round-trip safe, atomic writes)
+├── models.py         # Qt table model for host entries
+├── host_editor.py    # Add/Edit host dialog
+├── connect.py        # SSH command builder + launch (in-app or external)
+├── terminal.py       # In-app terminal widget (pyte + PTY)
+└── main_window.py    # Main window: host list, toolbar, terminal container
+
+tests/
+└── test_config.py    # Parser/writer tests (20 tests, 90% config coverage)
+```
+
+## Roadmap
+
+- **Tier 2:** key file management (generate, view, copy public key), known-hosts viewer, connection test, import/export
+- **Tier 3:** port-forwarding manager, per-host tags/notes, system tray quick-connect
+
+## License
+
+MIT

graphical_ssh-0.1.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+gssh/__init__.py,sha256=LNUYGX1heB0vqMGb4wPmdGx_QB3LNkz64l-jRPqUQRg,97
+gssh/__main__.py,sha256=ohqkL2bQPsMrA6jUDil_-8Z2ftbEXoFBaDwSH2TBews,910
+gssh/config.py,sha256=DXm15fXdXbo64ekejgJGv_WxlFwRG5HKvSnrso07qpY,7461
+gssh/connect.py,sha256=78Y7RM14QJbIU4gk9vQdzjDVtzfcyDpAbMeZI1eCjdA,4846
+gssh/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gssh/data/gssh.desktop,sha256=bfGIkMCtElNbBJNRvqdz7rhr4ZYgIj4yCAzRbude7zk,253
+gssh/data/gssh.svg,sha256=Wta2J2s6MYxT5lCk52m3bQBHGcCymCMf2LC97YUUDjo,1420
+gssh/host_editor.py,sha256=umeHZpKSJ_6MBP6m-shjMMVUKAdCS9D7gnQL76B_qNM,5743
+gssh/linter.py,sha256=UlTIAmFnaYPVtgeAlC1qwKA4A0e5rDtnftZ2diImyXw,14332
+gssh/main_window.py,sha256=dOtET9JXXonMi21Gn3WtJ0baUqXjYU800TnOwqW4BSw,14772
+gssh/models.py,sha256=P7E8Y9odGAIjmhXNjZSdXboSdgTnq4q80Pq4VkBAKPg,3248
+gssh/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gssh/terminal.py,sha256=SpB2slF7jl3OqxIjxGIHdB_3VYoGWrqLegDJrxkkVr8,17378
+graphical_ssh-0.1.1.dist-info/licenses/LICENSE,sha256=uQMF9ITa2aEl5F3I8Lpdx2k12NPpsTc1wekmpSIaH4o,1066
+graphical_ssh-0.1.1.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
+graphical_ssh-0.1.1.dist-info/entry_points.txt,sha256=G8FgJ05c1l3-OTvk_k-YzXkdp3VddiG9aur3Cv8u7KM,45
+graphical_ssh-0.1.1.dist-info/METADATA,sha256=OBRkwh4dN1Y2yVXglMKF3aatNisEmx0s-IwT8r_ZM9I,5108
+graphical_ssh-0.1.1.dist-info/RECORD,,

graphical_ssh-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.5
+Root-Is-Purelib: true
+Tag: py3-none-any

graphical_ssh-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gssh = gssh.__main__:main
+

graphical_ssh-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Grace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gssh/__init__.py

@@ -0,0 +1,3 @@
+"""gssh — Graphical SSH client connection and configuration manager."""
+
+__version__ = "0.1.1"

gssh/__main__.py

@@ -0,0 +1,43 @@
+"""Entry point for gssh."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from PyQt6.QtWidgets import QApplication
+
+from . import __version__
+from .main_window import MainWindow
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="gssh",
+        description="Graphical SSH client connection and configuration manager",
+    )
+    parser.add_argument(
+        "-c", "--config",
+        type=Path,
+        default=None,
+        help="Path to ssh config file (default: ~/.ssh/config)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"gssh {__version__}",
+    )
+    args = parser.parse_args()
+
+    app = QApplication(sys.argv)
+    app.setApplicationName("gssh")
+
+    window = MainWindow(config_path=args.config)
+    window.show()
+
+    return app.exec()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gssh/config.py

@@ -0,0 +1,245 @@
+"""SSH client configuration parser and writer.
+
+Reads and writes ~/.ssh/config in a round-trip-safe manner. Preserves
+global options (outside Host blocks) and per-host options. Unknown
+directives are kept verbatim so nothing is lost on save.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import tempfile
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+__all__ = ["HostEntry", "SSHConfig", "load_config", "save_config"]
+
+
+# Keys that are commonly edited in the GUI — shown as dedicated fields.
+# Everything else goes into the "extra options" area.
+GUI_FIELDS = {
+    "hostname", "user", "port", "identityfile",
+    "proxyjump", "forwardagent",
+}
+
+
+@dataclass
+class HostEntry:
+    """A single Host block in ssh_config."""
+
+    pattern: str  # the pattern(s) after "Host ", e.g. "myserver" or "*.example.com"
+    options: dict[str, str] = field(default_factory=dict)
+    # Raw lines that belong to this block but weren't key/value (comments, blank lines)
+    raw_trailing: list[str] = field(default_factory=list)
+
+    @property
+    def alias(self) -> str:
+        """Primary alias — first pattern, stripped of wildcards for display."""
+        return self.pattern.split()[0] if self.pattern else ""
+
+    @property
+    def hostname(self) -> str:
+        return self.options.get("hostname", "")
+
+    @property
+    def user(self) -> str:
+        return self.options.get("user", "")
+
+    @property
+    def port(self) -> str:
+        return self.options.get("port", "")
+
+    @property
+    def identity_file(self) -> str:
+        return self.options.get("identityfile", "")
+
+    @property
+    def proxy_jump(self) -> str:
+        return self.options.get("proxyjump", "")
+
+    @property
+    def forward_agent(self) -> str:
+        return self.options.get("forwardagent", "")
+
+    def extra_options(self) -> dict[str, str]:
+        """Options not shown as dedicated GUI fields."""
+        return {k: v for k, v in self.options.items() if k not in GUI_FIELDS}
+
+
+@dataclass
+class SSHConfig:
+    """Full ssh_config file representation."""
+
+    # Global lines before any Host block (comments, includes, global options)
+    preamble: list[str] = field(default_factory=list)
+    hosts: list[HostEntry] = field(default_factory=list)
+    # Trailing lines after the last Host block
+    postamble: list[str] = field(default_factory=list)
+
+    def find_host(self, alias: str) -> HostEntry | None:
+        for h in self.hosts:
+            if h.alias == alias:
+                return h
+        return None
+
+    def __iter__(self) -> Iterator[HostEntry]:
+        return iter(self.hosts)
+
+
+_LINE_RE = re.compile(r"^\s*(\S+)\s+(.+?)\s*$")
+_HOST_RE = re.compile(r"^\s*[Hh]ost\s+(.+?)\s*$")
+
+
+def _parse_value(raw: str) -> str:
+    """Strip quotes and whitespace from a value."""
+    v = raw.strip()
+    if len(v) >= 2 and v[0] in "\"'" and v[-1] == v[0]:
+        v = v[1:-1]
+    return v
+
+
+def load_config(path: Path | None = None) -> SSHConfig:
+    """Parse an ssh_config file into an SSHConfig structure.
+
+    If *path* is None, defaults to ~/.ssh/config. If the file does not
+    exist, returns an empty SSHConfig.
+    """
+    if path is None:
+        path = Path.home() / ".ssh" / "config"
+
+    config = SSHConfig()
+
+    if not path.exists():
+        return config
+
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines(keepends=False)
+
+    preamble: list[str] = []
+    hosts: list[HostEntry] = []
+    postamble: list[str] = []
+
+    current_host: HostEntry | None = None
+    current_lines: list[str] = []
+
+    for line in lines:
+        m = _HOST_RE.match(line)
+        if m:
+            # Finish previous host
+            if current_host is not None:
+                current_host.raw_trailing = _extract_trailing(current_lines)
+                hosts.append(current_host)
+            else:
+                preamble.extend(current_lines)
+
+            current_lines = []
+            current_host = HostEntry(pattern=m.group(1))
+            continue
+
+        if current_host is not None:
+            # Parse option line inside a Host block
+            stripped = line.strip()
+            if stripped == "" or stripped.startswith("#"):
+                current_lines.append(line)
+            else:
+                kv = _LINE_RE.match(line)
+                if kv:
+                    key = kv.group(1).lower()
+                    val = _parse_value(kv.group(2))
+                    current_host.options[key] = val
+                else:
+                    current_lines.append(line)
+        else:
+            current_lines.append(line)
+
+    # Finish up
+    if current_host is not None:
+        current_host.raw_trailing = _extract_trailing(current_lines)
+        hosts.append(current_host)
+    else:
+        preamble.extend(current_lines)
+
+    # Split preamble vs postamble — everything before first host is preamble,
+    # anything after the last host is postamble (already empty since we append
+    # trailing lines to the host). For simplicity, postamble is empty.
+    config.preamble = preamble
+    config.hosts = hosts
+    config.postamble = postamble
+
+    return config
+
+
+def _extract_trailing(lines: list[str]) -> list[str]:
+    """Extract trailing comment/blank lines that belong to a host block."""
+    result: list[str] = []
+    # Collect trailing blank lines and comments
+    for line in reversed(lines):
+        stripped = line.strip()
+        if stripped == "" or stripped.startswith("#"):
+            result.insert(0, line)
+        else:
+            break
+    return result
+
+
+def save_config(config: SSHConfig, path: Path | None = None) -> Path:
+    """Write an SSHConfig back to disk atomically.
+
+    Creates a backup of the existing file with a .bak timestamp suffix.
+    Returns the path written.
+    """
+    if path is None:
+        path = Path.home() / ".ssh" / "config"
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Backup existing file
+    if path.exists():
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup = path.with_suffix(f".config.bak.{ts}")
+        shutil.copy2(path, backup)
+
+    # Build output
+    out_lines: list[str] = []
+
+    if config.preamble:
+        out_lines.extend(config.preamble)
+        if out_lines and out_lines[-1].strip() != "":
+            out_lines.append("")
+
+    for host in config.hosts:
+        out_lines.append(f"Host {host.pattern}")
+        for key, val in host.options.items():
+            # Capitalize first letter for ssh_config convention
+            display_key = key[0].upper() + key[1:]
+            out_lines.append(f"    {display_key} {val}")
+        if host.raw_trailing:
+            out_lines.extend(host.raw_trailing)
+        out_lines.append("")
+
+    if config.postamble:
+        out_lines.extend(config.postamble)
+
+    content = "\n".join(out_lines)
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    # Atomic write: temp file in same dir, then rename
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".config.", suffix=".tmp"
+    )
+    try:
+    # Set restrictive permissions (ssh requires config to not be group/world writable)
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        os.replace(tmp_path, path)
+    except Exception:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+    return path

gssh/connect.py

@@ -0,0 +1,156 @@
+"""Connection launcher — spawns SSH sessions either in-app or in an external terminal."""
+
+from __future__ import annotations
+
+import shutil
+import socket
+import subprocess
+import time
+from dataclasses import dataclass
+
+from .config import HostEntry
+from .terminal import TerminalWidget
+
+
+@dataclass
+class ConnectionTestResult:
+    """Result of a connection test."""
+    success: bool
+    latency_ms: float
+    error: str = ""
+
+
+def build_ssh_command(host: HostEntry) -> list[str]:
+    """Build the ssh command line for a host entry.
+
+    Uses the alias so that all ssh_config options (ProxyJump, IdentityFile,
+    etc.) are applied automatically by the ssh client.
+    """
+    cmd = ["ssh"]
+    # Use the first pattern that isn't a wildcard
+    alias = host.alias
+    if "*" in alias:
+        # For wildcard hosts, build explicit connection
+        if host.hostname:
+            target = host.hostname
+            if host.user:
+                target = f"{host.user}@{target}"
+            cmd.append(target)
+            if host.port and host.port != "22":
+                cmd.extend(["-p", host.port])
+            if host.identity_file:
+                cmd.extend(["-i", host.identity_file])
+            if host.proxy_jump:
+                cmd.extend(["-J", host.proxy_jump])
+            return cmd
+        else:
+            # Can't connect to a wildcard without a hostname
+            return []
+    cmd.append(alias)
+    return cmd
+
+
+def launch_in_app(host: HostEntry) -> TerminalWidget | None:
+    """Spawn SSH in an in-app terminal widget. Returns the widget."""
+    cmd = build_ssh_command(host)
+    if not cmd:
+        return None
+    widget = TerminalWidget()
+    widget.start(cmd)
+    return widget
+
+
+def launch_external(host: HostEntry) -> subprocess.Popen | None:
+    """Spawn SSH in an external terminal emulator.
+
+    Tries x-terminal-emulator, then common emulators.
+    """
+    cmd = build_ssh_command(host)
+    if not cmd:
+        return None
+
+    # Find a terminal emulator
+    term = _find_terminal_emulator()
+    if term is None:
+        # Fallback: try x-terminal-emulator
+        return None
+
+    # Build the full command
+    if term in ("gnome-terminal", "xfce4-terminal", "mate-terminal", "lxterminal"):
+        full_cmd = [term, "--", *cmd]
+    elif term == "konsole":
+        full_cmd = [term, "-e", *cmd]
+    elif term == "xterm":
+        full_cmd = [term, "-e", *cmd]
+    elif term == "kitty":
+        full_cmd = [term, *cmd]
+    elif term == "alacritty":
+        full_cmd = [term, "-e", *cmd]
+    elif term == "foot":
+        full_cmd = [term, *cmd]
+    elif term == "wezterm":
+        full_cmd = [term, "start", "--", *cmd]
+    else:
+        full_cmd = [term, "-e", *cmd]
+
+    return subprocess.Popen(full_cmd, start_new_session=True)
+
+
+def _find_terminal_emulator() -> str | None:
+    """Find an available terminal emulator."""
+    # Check x-terminal-emulator first (Debian alternative system)
+    xte = shutil.which("x-terminal-emulator")
+    if xte:
+        return "x-terminal-emulator"
+
+    candidates = [
+        "konsole",       # KDE
+        "gnome-terminal",  # GNOME
+        "xfce4-terminal",  # XFCE
+        "mate-terminal",   # MATE
+        "lxterminal",      # LXDE
+        "qterminal",       # LXQt
+        "kitty",
+        "alacritty",
+        "foot",
+        "wezterm",
+        "xterm",         # fallback
+    ]
+    for t in candidates:
+        if shutil.which(t):
+            return t
+    return None
+
+
+def test_connection(host: HostEntry, timeout: float = 5.0) -> ConnectionTestResult:
+    """Test TCP connectivity to a host without opening an SSH session.
+
+    Does a TCP connect to host:port and measures latency. For wildcard
+    hosts with no HostName, returns an error immediately.
+    """
+    hostname = host.hostname
+    if not hostname:
+        if "*" not in host.alias:
+            hostname = host.alias
+        else:
+            return ConnectionTestResult(
+                success=False, latency_ms=0,
+                error="Wildcard host with no HostName — cannot test.",
+            )
+
+    port = int(host.port) if host.port else 22
+
+    try:
+        start = time.monotonic()
+        sock = socket.create_connection((hostname, port), timeout=timeout)
+        elapsed = (time.monotonic() - start) * 1000
+        sock.close()
+        return ConnectionTestResult(success=True, latency_ms=round(elapsed, 1))
+    except socket.gaierror as e:
+        return ConnectionTestResult(success=False, latency_ms=0, error=f"DNS error: {e}")
+    except TimeoutError:
+        return ConnectionTestResult(success=False, latency_ms=0, error=f"Timeout after {timeout}s")
+    except ConnectionRefusedError:
+        return ConnectionTestResult(success=False, latency_ms=0, error="Connection refused")
+    except OSError as e:
+        return ConnectionTestResult(success=False, latency_ms=0, error=str(e))

gssh/data/gssh.desktop

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Type=Application
+Name=gssh
+GenericName=SSH Connection Manager
+Comment=Manage SSH connections and configuration
+Exec=gssh
+Icon=gssh
+Terminal=false
+Categories=Network;System;TerminalEmulator;
+Keywords=ssh;terminal;remote;connection;config;