ots-shared 0.2.0__tar.gz

ots_shared-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*.txt
+
+# OS
+.DS_Store
+Thumbs.db
+
+.claude
+.serena
+.coverage

ots_shared-0.2.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: ots-shared
+Version: 0.2.0
+Summary: Shared constants and utilities for OTS operations tools
+Project-URL: Repository, https://github.com/onetimesecret/rots
+Author: Onetime
+License-Expression: MIT
+Keywords: cli,infrastructure,shared
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: cyclopts>=3.9
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.390; extra == 'dev'
+Provides-Extra: ssh
+Requires-Dist: paramiko>=3.4; extra == 'ssh'
+Provides-Extra: test
+Requires-Dist: pytest-mock>=3.14; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/plain
+
+Shared constants and utilities for OTS operations tools.

ots_shared-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "ots-shared"
+version = "0.2.0"
+description = "Shared constants and utilities for OTS operations tools"
+readme = {text = "Shared constants and utilities for OTS operations tools.", content-type = "text/plain"}
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Onetime" }]
+keywords = ["cli", "infrastructure", "shared"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = ["cyclopts>=3.9"]
+
+[project.urls]
+Repository = "https://github.com/onetimesecret/rots"
+
+[project.optional-dependencies]
+ssh = ["paramiko>=3.4"]
+dev = ["pyright>=1.1.390"]
+test = ["pytest>=8.0", "pytest-mock>=3.14"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ots_shared"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+include = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]

ots_shared-0.2.0/src/ots_shared/__init__.py

@@ -0,0 +1 @@
+"""Shared constants and utilities for OTS operations tools."""

ots_shared-0.2.0/src/ots_shared/cli.py

@@ -0,0 +1,70 @@
+"""Shared cyclopts type aliases for consistent CLI flags across OTS tools.
+
+All common flags use long+short forms for consistency:
+  --quiet, -q
+  --dry-run, -n
+  --yes, -y
+  --follow, -f
+  --lines, -l
+  --json, -j
+"""
+
+from typing import Annotated
+
+import cyclopts
+
+# Output control
+Quiet = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--quiet", "-q"],
+        help="Suppress output",
+    ),
+]
+
+DryRun = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--dry-run", "-n"],
+        help="Show what would be done without doing it",
+        negative=[],  # Disable --no-dry-run generation
+    ),
+]
+
+
+# Confirmation
+Yes = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--yes", "-y"],
+        help="Skip confirmation prompts",
+    ),
+]
+
+
+# Log viewing
+Follow = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--follow", "-f"],
+        help="Follow log output",
+    ),
+]
+
+Lines = Annotated[
+    int,
+    cyclopts.Parameter(
+        name=["--lines", "-l"],
+        help="Number of lines to show",
+    ),
+]
+
+
+# JSON output
+JsonOutput = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--json", "-j"],
+        help="Output as JSON",
+    ),
+]

ots_shared-0.2.0/src/ots_shared/exit_codes.py

@@ -0,0 +1,29 @@
+"""Standardised exit codes for all OTS CLI tools.
+
+All commands across ots-containers, hcloud-manager, otsinfra, and
+ots-cloudinit use this scheme so that CI pipelines and shell scripts
+can distinguish between different failure modes.
+
+Usage::
+
+    from ots_shared.exit_codes import EXIT_SUCCESS, EXIT_FAILURE, EXIT_PARTIAL, EXIT_PRECOND
+
+    raise SystemExit(EXIT_PARTIAL)
+"""
+
+EXIT_SUCCESS: int = 0
+"""Command completed successfully; all operations applied."""
+
+EXIT_FAILURE: int = 1
+"""General command failure (unexpected error, bad arguments, etc.)."""
+
+EXIT_PARTIAL: int = 2
+"""Partial success: at least one operation succeeded and at least one failed.
+
+Check the command output for details on which operations failed."""
+
+EXIT_PRECOND: int = 3
+"""Precondition not met: required configuration is absent.
+
+Examples: missing env file, missing secrets, image not pulled.
+No destructive action was attempted."""

ots_shared-0.2.0/src/ots_shared/ssh/__init__.py

@@ -0,0 +1,51 @@
+"""SSH remote execution support for OTS operations tools.
+
+Public API:
+    - Environment: find_env_file, load_env_file, resolve_config_dir, resolve_host
+    - Executor: Result, CommandError, Executor, LocalExecutor, SSHExecutor, is_remote
+    - Connection: ssh_connect
+"""
+
+from .env import (
+    find_env_file,
+    generate_env_template,
+    load_env_file,
+    resolve_config_dir,
+    resolve_host,
+)
+from .executor import (
+    SSH_DEFAULT_TIMEOUT,
+    CommandError,
+    Executor,
+    LocalExecutor,
+    Result,
+    SSHExecutor,
+    is_remote,
+)
+
+__all__ = [
+    "find_env_file",
+    "generate_env_template",
+    "load_env_file",
+    "resolve_config_dir",
+    "resolve_host",
+    "SSH_DEFAULT_TIMEOUT",
+    "CommandError",
+    "Executor",
+    "LocalExecutor",
+    "Result",
+    "SSHExecutor",
+    "is_remote",
+    "ssh_connect",
+]
+
+
+def ssh_connect(
+    hostname: str,
+    ssh_config_path: object | None = None,
+    timeout: int = 15,
+) -> object:
+    """Open an SSH connection. Deferred import to avoid requiring paramiko."""
+    from .connection import ssh_connect as _ssh_connect
+
+    return _ssh_connect(hostname, ssh_config_path=ssh_config_path, timeout=timeout)  # type: ignore[arg-type]

ots_shared-0.2.0/src/ots_shared/ssh/_pty.py

@@ -0,0 +1,172 @@
+"""PTY helper for interactive SSH sessions.
+
+Internal module — not exported from ots_shared.ssh.__init__.
+Provides terminal save/restore, raw mode, SIGWINCH propagation,
+and a bidirectional select loop for full-PTY SSH channels.
+
+All termios/tty/signal usage is guarded for portability (Windows
+lacks these modules). Functions raise RuntimeError if called on
+a platform without PTY support.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import select
+import shutil
+import sys
+
+logger = logging.getLogger(__name__)
+
+# Guarded imports — these are Unix-only.
+try:
+    import signal
+    import termios
+    import tty
+
+    _HAS_PTY_SUPPORT = True
+except ImportError:
+    _HAS_PTY_SUPPORT = False
+
+
+def _require_pty_support() -> None:
+    """Raise RuntimeError if termios/tty are unavailable."""
+    if not _HAS_PTY_SUPPORT:
+        raise RuntimeError(
+            "PTY support requires termios/tty (Unix-only). "
+            "Interactive SSH sessions are not available on this platform."
+        )
+
+
+def get_terminal_size() -> tuple[int, int]:
+    """Return (columns, rows) of the current terminal.
+
+    Falls back to (80, 24) if detection fails.
+    """
+    size = shutil.get_terminal_size(fallback=(80, 24))
+    return (size.columns, size.lines)
+
+
+def set_raw(fd: int) -> list:
+    """Save terminal attributes and switch *fd* to raw mode.
+
+    Returns the saved attributes (pass to :func:`restore`).
+    Raises RuntimeError on platforms without termios.
+    """
+    _require_pty_support()
+    old_attrs = termios.tcgetattr(fd)
+    tty.setraw(fd)
+    tty.setcbreak(fd)
+    return old_attrs
+
+
+def restore(fd: int, attrs: list) -> None:
+    """Restore terminal attributes previously saved by :func:`set_raw`.
+
+    Uses TCSADRAIN so queued output finishes before the change.
+    Raises RuntimeError on platforms without termios.
+    """
+    _require_pty_support()
+    termios.tcsetattr(fd, termios.TCSADRAIN, attrs)
+
+
+def install_sigwinch_handler(channel: object) -> object | None:
+    """Install a SIGWINCH handler that resizes *channel*'s PTY.
+
+    Returns the previous signal handler so callers can restore it.
+    On platforms without SIGWINCH this is a no-op and returns None.
+    """
+    if not _HAS_PTY_SUPPORT:
+        return None
+
+    if not hasattr(signal, "SIGWINCH"):
+        return None
+
+    def _handler(signum: int, frame: object) -> None:
+        try:
+            cols, rows = get_terminal_size()
+            channel.resize_pty(width=cols, height=rows)  # type: ignore[union-attr]
+        except OSError:
+            pass
+
+    old_handler = signal.signal(signal.SIGWINCH, _handler)
+    return old_handler
+
+
+def restore_sigwinch_handler(old_handler: object | None) -> None:
+    """Restore the SIGWINCH handler saved by :func:`install_sigwinch_handler`."""
+    if old_handler is None:
+        return
+    if not _HAS_PTY_SUPPORT:
+        return
+    if not hasattr(signal, "SIGWINCH"):
+        return
+    signal.signal(signal.SIGWINCH, old_handler)  # type: ignore[arg-type]
+
+
+def interactive_loop(
+    channel: object,
+    stdin_fd: int,
+    stdout_buffer: object | None = None,
+) -> int:
+    """Bidirectional select loop between *channel* and *stdin_fd*.
+
+    Reads from the Paramiko channel and writes to *stdout_buffer*
+    (defaults to ``sys.stdout.buffer``). Reads from *stdin_fd* and
+    sends to the channel. Runs until the channel exits.
+
+    Returns the remote process exit code.
+    """
+    if stdout_buffer is None:
+        stdout_buffer = sys.stdout.buffer
+
+    while True:
+        readable, _, _ = select.select([channel, stdin_fd], [], [], 0.1)
+
+        if channel in readable:
+            if channel.recv_ready():  # type: ignore[union-attr]
+                data = channel.recv(4096)  # type: ignore[union-attr]
+                if data:
+                    stdout_buffer.write(data)  # type: ignore[union-attr]
+                    stdout_buffer.flush()  # type: ignore[union-attr]
+                elif channel.exit_status_ready():  # type: ignore[union-attr]
+                    break
+            elif channel.exit_status_ready():  # type: ignore[union-attr]
+                break
+
+        if stdin_fd in readable:
+            user_input = os.read(stdin_fd, 1024)
+            if user_input:
+                channel.sendall(user_input)  # type: ignore[union-attr]
+
+        if channel.exit_status_ready() and not channel.recv_ready():  # type: ignore[union-attr]
+            break
+
+    return channel.recv_exit_status()  # type: ignore[union-attr]
+
+
+def run_pty_session(channel: object) -> int:
+    """High-level PTY session driver for SSHExecutor.run_interactive().
+
+    Saves terminal state, sets raw mode, installs SIGWINCH handler,
+    runs the bidirectional loop, and restores everything in ``finally``.
+
+    Returns the remote process exit code.
+    """
+    _require_pty_support()
+
+    stdin_fd = sys.stdin.fileno()
+    old_attrs = termios.tcgetattr(stdin_fd)
+    old_sigwinch = None
+
+    try:
+        old_sigwinch = install_sigwinch_handler(channel)
+        tty.setraw(stdin_fd)
+        tty.setcbreak(stdin_fd)
+        exit_code = interactive_loop(channel, stdin_fd)
+    finally:
+        termios.tcsetattr(stdin_fd, termios.TCSADRAIN, old_attrs)
+        restore_sigwinch_handler(old_sigwinch)
+
+    return exit_code

ots_shared-0.2.0/src/ots_shared/ssh/connection.py

@@ -0,0 +1,152 @@
+"""Paramiko SSHClient factory using ~/.ssh/config.
+
+Creates SSH connections that honour the user's SSH config for Host,
+User, Port, IdentityFile, and ProxyCommand settings.
+
+Paramiko does not process ``Include`` directives, so we resolve them
+recursively before parsing.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+from glob import glob
+from pathlib import Path
+
+import paramiko
+
+logger = logging.getLogger(__name__)
+
+# Connection timeout in seconds
+DEFAULT_TIMEOUT = 15
+
+
+def _resolve_includes(config_path: Path, _seen: set[Path] | None = None) -> str:
+    """Recursively expand ``Include`` directives in an SSH config file.
+
+    Paramiko's SSHConfig parser silently ignores Include directives.
+    This function reads the config, expands any Include lines (handling
+    ``~`` expansion, relative paths, and glob patterns), and returns a
+    single merged string suitable for ``SSHConfig.parse()``.
+    """
+    if _seen is None:
+        _seen = set()
+
+    resolved = config_path.resolve()
+    if resolved in _seen:
+        return ""
+    _seen.add(resolved)
+
+    if not config_path.is_file():
+        return ""
+
+    lines: list[str] = []
+    for line in config_path.read_text().splitlines():
+        stripped = line.strip()
+        if stripped.lower().startswith("include "):
+            pattern = stripped.split(None, 1)[1].strip()
+            # Strip surrounding quotes
+            if len(pattern) >= 2 and pattern[0] == pattern[-1] and pattern[0] in ('"', "'"):
+                pattern = pattern[1:-1]
+            # Expand ~ and resolve relative paths against config dir
+            pattern = str(Path(pattern).expanduser())
+            if not Path(pattern).is_absolute():
+                pattern = str(config_path.parent / pattern)
+            for included_path in sorted(glob(pattern)):
+                included = Path(included_path)
+                if included.is_file():
+                    lines.append(_resolve_includes(included, _seen))
+        else:
+            lines.append(line)
+
+    return "\n".join(lines)
+
+
+def ssh_connect(
+    hostname: str,
+    ssh_config_path: Path | None = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> paramiko.SSHClient:
+    """Open an SSH connection to *hostname* using SSH config.
+
+    Uses paramiko with RejectPolicy — the host must already be in
+    known_hosts. Returns a connected paramiko.SSHClient.
+
+    Raises:
+        paramiko.SSHException: If connection or authentication fails.
+    """
+    config_path = ssh_config_path or Path.home() / ".ssh" / "config"
+
+    # Parse SSH config with Include directives resolved
+    ssh_config = paramiko.SSHConfig()
+    if config_path.exists():
+        merged = _resolve_includes(config_path)
+        ssh_config.parse(io.StringIO(merged))
+
+    host_config = ssh_config.lookup(hostname)
+
+    # Build connection kwargs from SSH config
+    connect_kwargs: dict = {
+        "hostname": host_config.get("hostname", hostname),
+        "timeout": timeout,
+    }
+
+    if "port" in host_config:
+        connect_kwargs["port"] = int(host_config["port"])
+
+    if "user" in host_config:
+        connect_kwargs["username"] = host_config["user"]
+
+    if "identityfile" in host_config:
+        # SSH config may list multiple identity files; pass all that exist
+        key_files = [
+            str(Path(kf).expanduser())
+            for kf in host_config["identityfile"]
+            if Path(kf).expanduser().exists()
+        ]
+        if key_files:
+            connect_kwargs["key_filename"] = key_files
+
+    # ProxyCommand support
+    proxy_cmd = host_config.get("proxycommand")
+    if proxy_cmd:
+        connect_kwargs["sock"] = paramiko.ProxyCommand(proxy_cmd)
+
+    # Create client with RejectPolicy (security requirement)
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.RejectPolicy())
+
+    # Load known hosts
+    known_hosts = Path.home() / ".ssh" / "known_hosts"
+    if known_hosts.exists():
+        client.load_host_keys(str(known_hosts))
+    client.load_system_host_keys()
+
+    # Paramiko looks up non-standard ports as [host]:port in known_hosts,
+    # but OpenSSH also accepts bare host entries as a fallback.  Mirror
+    # that behaviour so existing known_hosts files work without needing
+    # port-specific entries.
+    port = connect_kwargs.get("port", 22)
+    actual_host = connect_kwargs["hostname"]
+    if port != 22:
+        bracketed = f"[{actual_host}]:{port}"
+        host_keys = client.get_host_keys()
+        if bracketed not in host_keys and actual_host in host_keys:
+            for key_type in host_keys[actual_host]:
+                host_keys.add(bracketed, key_type, host_keys[actual_host][key_type])
+
+    logger.info("SSH connecting to %s", connect_kwargs.get("hostname", hostname))
+    try:
+        client.connect(**connect_kwargs)
+    except paramiko.PasswordRequiredException:
+        # Key file is encrypted and no passphrase was provided.  Drop
+        # key_filename so paramiko falls through to the SSH agent, which
+        # typically has the decrypted key loaded (via AddKeysToAgent/UseKeychain).
+        if "key_filename" in connect_kwargs:
+            logger.debug("Encrypted key file, falling back to SSH agent")
+            del connect_kwargs["key_filename"]
+            client.connect(**connect_kwargs)
+        else:
+            raise
+    return client