ots-shared 0.2.0__py3-none-any.whl

ots_shared/__init__.py

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

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/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/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/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/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

ots_shared/ssh/env.py

@@ -0,0 +1,191 @@
+""".otsinfra.env discovery, parsing, and host resolution.
+
+The .otsinfra.env file provides targeting context for remote execution.
+It is discovered by walking up from the current directory, stopping at
+the repository root (.git) or the user's home directory.
+
+Standard variables:
+    OTS_HOST        Target host (SSH hostname or alias)
+    OTS_REPOSITORY  Container image repository
+    OTS_TAG         Release version tag (e.g. v0.24)
+    OTS_IMAGE       Container image override (optional)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+ENV_FILENAME = ".otsinfra.env"
+_CONFIG_DIR_PREFIX = "config-v"
+_CONFIG_SYMLINK = "config"
+
+
+def find_env_file(start: Path | None = None) -> Path | None:
+    """Walk up from *start* looking for a .otsinfra.env file.
+
+    Stops at the first directory containing .git or at the user's home
+    directory — whichever is reached first. Returns None if not found.
+    """
+    current = (start or Path.cwd()).resolve()
+    home = Path.home().resolve()
+
+    while True:
+        candidate = current / ENV_FILENAME
+        if candidate.is_file():
+            return candidate
+
+        # Stop at .git boundary
+        if (current / ".git").exists():
+            return None
+
+        # Stop at home directory ceiling
+        if current == home:
+            return None
+
+        parent = current.parent
+        # Filesystem root — stop
+        if parent == current:
+            return None
+
+        current = parent
+
+
+def load_env_file(path: Path) -> dict[str, str]:
+    """Parse a .otsinfra.env file into a dict.
+
+    Format: KEY=VALUE lines. Blank lines and lines starting with # are
+    ignored. Values are stripped of surrounding whitespace. Quoted values
+    (single or double) are unquoted.
+    """
+    result: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        # Strip matching quotes
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+            value = value[1:-1]
+        result[key] = value
+    return result
+
+
+def resolve_host(host_flag: str | None = None) -> str | None:
+    """Determine the target host using the resolution priority chain.
+
+    Priority:
+        1. Explicit --host flag value
+        2. OTS_HOST environment variable
+        3. OTS_HOST from .otsinfra.env (walk-up discovery)
+        4. None (local execution)
+    """
+    # 1. Explicit flag
+    if host_flag:
+        logger.debug("Host from --host flag: %s", host_flag)
+        return host_flag
+
+    # 2. Environment variable
+    env_host = os.environ.get("OTS_HOST")
+    if env_host:
+        logger.debug("Host from OTS_HOST env var: %s", env_host)
+        return env_host
+
+    # 3. Walk-up .otsinfra.env
+    env_path = find_env_file()
+    if env_path:
+        env_vars = load_env_file(env_path)
+        file_host = env_vars.get("OTS_HOST")
+        if file_host:
+            logger.info("Host from %s: %s", env_path, file_host)
+            return file_host
+
+    # 4. Local
+    return None
+
+
+def resolve_config_dir(start: Path | None = None) -> Path | None:
+    """Resolve the current config directory for a jurisdiction.
+
+    Resolution order:
+        1. A ``config`` symlink or directory sibling to the .otsinfra.env file
+           (stable pointer managed by the operator).
+        2. OTS_TAG from .otsinfra.env → versioned directory name
+           (e.g. ``v0.24`` → ``config-v0.24``).
+
+    The config directory is expected to be a sibling of the env file.
+    Returns the directory path if it exists, None otherwise.
+    """
+    env_path = find_env_file(start)
+    if env_path is None:
+        return None
+
+    parent = env_path.parent
+
+    # 1. Stable symlink convention: config -> config-v0.24
+    symlink = parent / _CONFIG_SYMLINK
+    if symlink.is_dir():
+        logger.debug("Config dir from symlink %s: %s", symlink, symlink.resolve())
+        return symlink
+
+    # 2. Derive from OTS_TAG
+    env_vars = load_env_file(env_path)
+    tag = env_vars.get("OTS_TAG")
+    if not tag:
+        logger.debug("No OTS_TAG in %s", env_path)
+        return None
+
+    version = _tag_to_version(tag)
+    if version is None:
+        logger.warning("Cannot parse version from OTS_TAG=%s in %s", tag, env_path)
+        return None
+
+    config_dir = parent / f"{_CONFIG_DIR_PREFIX}{version}"
+    if config_dir.is_dir():
+        logger.debug("Config dir from %s: %s", env_path, config_dir)
+        return config_dir
+
+    logger.debug("Config dir does not exist: %s", config_dir)
+    return None
+
+
+def generate_env_template(
+    host: str = "",
+    tag: str = "",
+    repository: str = "",
+) -> str:
+    """Generate a .otsinfra.env template with optional pre-filled values.
+
+    Returns the file content as a string.
+    """
+    lines = [
+        "# .otsinfra.env — targeting context for OTS remote operations",
+        "#",
+        "# Walk-up discovery: ots-containers commands search for this file",
+        "# starting from the current directory upward to the repo root.",
+        "",
+        f"OTS_HOST={host}",
+        f"OTS_TAG={tag}",
+    ]
+    if repository:
+        lines.append(f"OTS_REPOSITORY={repository}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _tag_to_version(tag: str) -> str | None:
+    """Extract major.minor version from a tag string.
+
+    Accepts formats like ``v0.24``, ``v0.24.1``, ``0.24``, ``0.24.1``.
+    Returns ``"0.24"`` (major.minor only) or None if unparseable.
+    """
+    m = re.match(r"v?(\d+\.\d+)", tag)
+    return m.group(1) if m else None

ots_shared/ssh/executor.py

@@ -0,0 +1,483 @@
+"""Command execution abstraction for local and remote (SSH) targets.
+
+Provides a Protocol-based executor pattern so callers can run shell commands
+without knowing whether they execute locally or over SSH.  Also supports
+individual file transfers via ``put_file`` / ``get_file`` (SFTP for SSH,
+local filesystem for local).  For bulk file operations, use rsync
+(see ``ots_containers.commands.host._rsync``).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import select
+import shlex
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+# Default timeout (in seconds) for SSH command execution.
+# Prevents hung remote processes from running indefinitely.
+# Individual call sites can override with an explicit timeout= kwarg.
+# Use None for truly open-ended operations (run_interactive handles this).
+SSH_DEFAULT_TIMEOUT: int = 120
+
+logger = logging.getLogger(__name__)
+
+REDACTED = "***"
+
+
+def _redact_cmd(cmd: list[str], sensitive: set[str] | None) -> list[str]:
+    """Return a copy of *cmd* with sensitive argument values replaced."""
+    if not sensitive:
+        return cmd
+    return [REDACTED if c in sensitive else c for c in cmd]
+
+
+@dataclass(frozen=True)
+class Result:
+    """Outcome of a command execution."""
+
+    command: str
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    def check(self) -> None:
+        """Raise CommandError if the command failed."""
+        if not self.ok:
+            raise CommandError(self)
+
+
+class CommandError(Exception):
+    """A command returned a non-zero exit code."""
+
+    def __init__(self, result: Result) -> None:
+        self.result = result
+        super().__init__(f"Command failed (exit {result.returncode}): {result.command}")
+
+
+@runtime_checkable
+class Executor(Protocol):
+    """Interface for running shell commands on a target host."""
+
+    def run(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        timeout: int | None = None,
+        check: bool = False,
+        input: str | None = None,
+        sensitive_args: set[str] | None = None,
+    ) -> Result: ...
+
+    def run_stream(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        timeout: int | None = None,
+        sensitive_args: set[str] | None = None,
+    ) -> int:
+        """Stream stdout/stderr to the caller's terminal in real time.
+
+        Returns the process exit code. Does not capture output — it flows
+        directly to the current terminal.
+        """
+        ...
+
+    def run_interactive(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        sensitive_args: set[str] | None = None,
+    ) -> int:
+        """Run with full PTY: bidirectional stdin/stdout, SIGWINCH propagation.
+
+        For interactive sessions (shells, exec -it) — no timeout since the
+        session is open-ended. Returns the process exit code.
+        """
+        ...
+
+    def put_file(
+        self,
+        local_path: str | Path,
+        remote_path: str | Path,
+        *,
+        permissions: int | None = None,
+    ) -> None:
+        """Transfer a file from the local machine to the target host.
+
+        Args:
+            local_path: Path to the file on the local machine.
+            remote_path: Destination path on the target host.
+            permissions: Optional octal permissions (e.g. 0o644) to set
+                on the destination file.
+        """
+        ...
+
+    def get_file(
+        self,
+        remote_path: str | Path,
+        local_path: str | Path,
+    ) -> None:
+        """Transfer a file from the target host to the local machine.
+
+        Args:
+            remote_path: Path to the file on the target host.
+            local_path: Destination path on the local machine.
+        """
+        ...
+
+    def close(self) -> None: ...
+
+
+def _require_list(cmd: object, method: str) -> None:
+    """Raise TypeError if *cmd* is a str instead of list[str].
+
+    shlex.quote iterates a str character-by-character, producing a broken
+    (though not injectable) command.  Catching this early prevents subtle bugs.
+    """
+    if isinstance(cmd, str):
+        raise TypeError(
+            f"{method} requires cmd as list[str], got str. "
+            f"Use shlex.split() or pass a list: {cmd!r}"
+        )
+
+
+def is_remote(executor: Executor | None) -> bool:
+    """Return True if *executor* dispatches commands to a remote host.
+
+    Returns False for ``None`` (no executor) or a :class:`LocalExecutor`.
+    """
+    if executor is None:
+        return False
+    return not isinstance(executor, LocalExecutor)
+
+
+class LocalExecutor:
+    """Execute commands on the local machine via subprocess.
+
+    File transfers operate directly on the local filesystem.
+    """
+
+    def run(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        timeout: int | None = None,
+        check: bool = False,
+        input: str | None = None,
+        sensitive_args: set[str] | None = None,
+    ) -> Result:
+        _require_list(cmd, "LocalExecutor.run")
+        full_cmd = ["sudo", "--"] + cmd if sudo else cmd
+        safe_cmd = _redact_cmd(full_cmd, sensitive_args)
+        logger.debug("local: %s", " ".join(shlex.quote(c) for c in safe_cmd))
+        try:
+            kwargs: dict = dict(
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            if input is not None:
+                kwargs["input"] = input
+            proc = subprocess.run(full_cmd, **kwargs)
+        except subprocess.TimeoutExpired as exc:
+            return Result(
+                command=" ".join(shlex.quote(c) for c in safe_cmd),
+                returncode=124,
+                stdout=exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or ""),
+                stderr=exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or ""),
+            )
+        result = Result(
+            command=" ".join(shlex.quote(c) for c in safe_cmd),
+            returncode=proc.returncode,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+        )
+        if check:
+            result.check()
+        return result
+
+    def run_stream(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        timeout: int | None = None,
+        sensitive_args: set[str] | None = None,
+    ) -> int:
+        _require_list(cmd, "LocalExecutor.run_stream")
+        full_cmd = ["sudo", "--"] + cmd if sudo else cmd
+        safe_cmd = _redact_cmd(full_cmd, sensitive_args)
+        logger.debug("local stream: %s", " ".join(shlex.quote(c) for c in safe_cmd))
+        try:
+            proc = subprocess.run(full_cmd, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            return 124
+        return proc.returncode
+
+    def run_interactive(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        sensitive_args: set[str] | None = None,
+    ) -> int:
+        _require_list(cmd, "LocalExecutor.run_interactive")
+        full_cmd = ["sudo", "--"] + cmd if sudo else cmd
+        safe_cmd = _redact_cmd(full_cmd, sensitive_args)
+        logger.debug("local interactive: %s", " ".join(shlex.quote(c) for c in safe_cmd))
+        try:
+            proc = subprocess.run(full_cmd)
+            return proc.returncode
+        except KeyboardInterrupt:
+            return 130
+
+    def put_file(
+        self,
+        local_path: str | Path,
+        remote_path: str | Path,
+        *,
+        permissions: int | None = None,
+    ) -> None:
+        src = Path(local_path)
+        dst = Path(remote_path)
+        logger.debug("local put_file: %s -> %s", src, dst)
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_bytes(src.read_bytes())
+        if permissions is not None:
+            dst.chmod(permissions)
+
+    def get_file(
+        self,
+        remote_path: str | Path,
+        local_path: str | Path,
+    ) -> None:
+        src = Path(remote_path)
+        dst = Path(local_path)
+        logger.debug("local get_file: %s -> %s", src, dst)
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_bytes(src.read_bytes())
+
+    def close(self) -> None:
+        pass
+
+
+class SSHExecutor:
+    """Execute commands on a remote host over an SSH connection.
+
+    Requires paramiko. Import is deferred so the module can be loaded
+    without paramiko installed — only construction raises ImportError.
+    """
+
+    def __init__(self, client: object) -> None:
+        try:
+            import paramiko
+        except ImportError:
+            raise ImportError(
+                "paramiko is required for SSH execution. "
+                "Install it with: pip install ots-shared[ssh]"
+            ) from None
+        if not isinstance(client, paramiko.SSHClient):
+            raise TypeError(f"Expected paramiko.SSHClient, got {type(client).__name__}")
+        self._client = client
+
+    # Sentinel to distinguish "caller did not pass timeout" from "caller passed None".
+    _UNSET = object()
+
+    def run(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        timeout: int | None | object = _UNSET,
+        check: bool = False,
+        input: str | None = None,
+        sensitive_args: set[str] | None = None,
+    ) -> Result:
+        _require_list(cmd, "SSHExecutor.run")
+
+        # Apply default timeout when caller does not specify one.
+        # Pass timeout=None explicitly to disable the timeout.
+        effective_timeout: int | None
+        if timeout is self._UNSET:
+            effective_timeout = SSH_DEFAULT_TIMEOUT
+        else:
+            effective_timeout = timeout  # type: ignore[assignment]
+
+        # Security: shlex.quote every argument before joining
+        shell_cmd = " ".join(shlex.quote(c) for c in cmd)
+        safe_cmd = " ".join(shlex.quote(c) for c in _redact_cmd(cmd, sensitive_args))
+        if sudo:
+            shell_cmd = f"sudo -- {shell_cmd}"
+            safe_cmd = f"sudo -- {safe_cmd}"
+        logger.debug("ssh: %s", safe_cmd)
+        stdin_ch, stdout, stderr = self._client.exec_command(shell_cmd, timeout=effective_timeout)
+        if input is not None:
+            stdin_ch.write(input)
+            stdin_ch.channel.shutdown_write()
+        exit_code = stdout.channel.recv_exit_status()
+        result = Result(
+            command=safe_cmd,
+            returncode=exit_code,
+            stdout=stdout.read().decode("utf-8", errors="replace"),
+            stderr=stderr.read().decode("utf-8", errors="replace"),
+        )
+        if check:
+            result.check()
+        return result
+
+    def run_stream(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        timeout: int | None = None,
+        sensitive_args: set[str] | None = None,
+    ) -> int:
+        """Stream remote command output to local terminal via select loop.
+
+        When *timeout* is provided, enforces an overall deadline on the
+        streaming session. If the deadline is exceeded, the channel is
+        closed and exit code 124 (matching GNU timeout convention) is returned.
+        """
+        import time
+
+        _require_list(cmd, "SSHExecutor.run_stream")
+        shell_cmd = " ".join(shlex.quote(c) for c in cmd)
+        safe_cmd = " ".join(shlex.quote(c) for c in _redact_cmd(cmd, sensitive_args))
+        if sudo:
+            shell_cmd = f"sudo -- {shell_cmd}"
+            safe_cmd = f"sudo -- {safe_cmd}"
+        logger.debug("ssh stream: %s", safe_cmd)
+        transport = self._client.get_transport()
+        channel = transport.open_session()
+        channel.setblocking(0)
+        if timeout is not None:
+            channel.settimeout(float(timeout))
+        channel.exec_command(shell_cmd)
+
+        # Overall deadline for the select loop
+        deadline = time.monotonic() + timeout if timeout is not None else None
+
+        # Stream output until channel is closed
+        while (
+            not channel.exit_status_ready() or channel.recv_ready() or channel.recv_stderr_ready()
+        ):
+            # Check deadline
+            if deadline is not None and time.monotonic() > deadline:
+                logger.warning("ssh stream timeout after %ds: %s", timeout, safe_cmd)
+                channel.close()
+                return 124
+
+            readable, _, _ = select.select([channel], [], [], 0.1)
+            if readable:
+                if channel.recv_ready():
+                    data = channel.recv(4096)
+                    if data:
+                        sys.stdout.buffer.write(data)
+                        sys.stdout.buffer.flush()
+                if channel.recv_stderr_ready():
+                    data = channel.recv_stderr(4096)
+                    if data:
+                        sys.stderr.buffer.write(data)
+                        sys.stderr.buffer.flush()
+        # Drain any remaining data after exit
+        while channel.recv_ready():
+            data = channel.recv(4096)
+            if data:
+                sys.stdout.buffer.write(data)
+                sys.stdout.buffer.flush()
+        while channel.recv_stderr_ready():
+            data = channel.recv_stderr(4096)
+            if data:
+                sys.stderr.buffer.write(data)
+                sys.stderr.buffer.flush()
+        exit_code = channel.recv_exit_status()
+        channel.close()
+        return exit_code
+
+    def run_interactive(
+        self,
+        cmd: list[str],
+        *,
+        sudo: bool = False,
+        sensitive_args: set[str] | None = None,
+    ) -> int:
+        """Run with full PTY over SSH: bidirectional stdin/stdout, SIGWINCH.
+
+        Delegates terminal handling to :mod:`ots_shared.ssh._pty`.
+        """
+        _require_list(cmd, "SSHExecutor.run_interactive")
+        from ots_shared.ssh import _pty
+
+        shell_cmd = " ".join(shlex.quote(c) for c in cmd)
+        safe_cmd = " ".join(shlex.quote(c) for c in _redact_cmd(cmd, sensitive_args))
+        if sudo:
+            shell_cmd = f"sudo -- {shell_cmd}"
+            safe_cmd = f"sudo -- {safe_cmd}"
+        logger.debug("ssh interactive: %s", safe_cmd)
+
+        transport = self._client.get_transport()
+        channel = transport.open_session()
+
+        # Request PTY with current terminal dimensions
+        cols, rows = _pty.get_terminal_size()
+        term = os.environ.get("TERM", "xterm-256color")
+        channel.get_pty(term=term, width=cols, height=rows)
+        channel.exec_command(shell_cmd)
+        channel.setblocking(0)
+
+        try:
+            exit_code = _pty.run_pty_session(channel)
+        finally:
+            channel.close()
+        return exit_code
+
+    def put_file(
+        self,
+        local_path: str | Path,
+        remote_path: str | Path,
+        *,
+        permissions: int | None = None,
+    ) -> None:
+        src = Path(local_path)
+        dst_str = str(remote_path)
+        logger.debug("ssh put_file: %s -> %s", src, dst_str)
+        sftp = self._client.open_sftp()
+        try:
+            sftp.put(str(src), dst_str)
+            if permissions is not None:
+                sftp.chmod(dst_str, permissions)
+        finally:
+            sftp.close()
+
+    def get_file(
+        self,
+        remote_path: str | Path,
+        local_path: str | Path,
+    ) -> None:
+        src_str = str(remote_path)
+        dst = Path(local_path)
+        logger.debug("ssh get_file: %s -> %s", src_str, dst)
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        sftp = self._client.open_sftp()
+        try:
+            sftp.get(src_str, str(dst))
+        finally:
+            sftp.close()
+
+    def close(self) -> None:
+        self._client.close()

ots_shared/taxonomy.py

@@ -0,0 +1,100 @@
+"""Canonical jurisdiction and environment vocabularies for OTS infrastructure.
+
+These vocabularies are the single source of truth for taxonomy inference
+across all OTS CLI tools (otsinfra, ots-cloudinit, hcloud-manager, etc.).
+
+Jurisdictions are ISO 3166-1 alpha-2 country codes used in hostname
+segments, directory structures, and inventory records.
+
+Environments map common aliases to canonical short names, allowing
+hostname segments like "stg" or "production" to resolve consistently.
+"""
+
+KNOWN_JURISDICTIONS: frozenset[str] = frozenset(
+    {
+        "ar",
+        "at",
+        "au",
+        "be",
+        "br",
+        "ca",
+        "ch",
+        "cl",
+        "co",
+        "cz",
+        "de",
+        "dk",
+        "es",
+        "eu",
+        "fi",
+        "fr",
+        "gb",
+        "hk",
+        "hu",
+        "ie",
+        "in",
+        "it",
+        "jp",
+        "kr",
+        "mx",
+        "nl",
+        "no",
+        "nz",
+        "pe",
+        "pl",
+        "pt",
+        "ro",
+        "se",
+        "sg",
+        "tw",
+        "uk",
+        "us",
+        "za",
+    }
+)
+"""ISO 3166-1 alpha-2 country codes used as jurisdiction identifiers.
+
+Checked against hostname segments split on '-' for taxonomy inference.
+"""
+
+KNOWN_ROLES: frozenset[str] = frozenset(
+    {
+        "web",
+        "db",
+        "redis",
+        "jump",
+        "bastion",
+        "worker",
+        "monitor",
+        "proxy",
+        "mail",
+        "dns",
+    }
+)
+"""Common host roles in OTS infrastructure.
+
+Used for validation warnings in otsinfra host add/edit. Not an exhaustive
+list -- unknown roles produce a warning, not an error.
+"""
+
+KNOWN_ENVIRONMENTS: dict[str, str] = {
+    "prod": "prod",
+    "production": "prod",
+    "staging": "staging",
+    "stg": "staging",
+    "stage": "staging",
+    "dev": "dev",
+    "development": "dev",
+    "test": "test",
+    "testing": "test",
+    "qa": "qa",
+    "uat": "uat",
+    "demo": "demo",
+    "sandbox": "sandbox",
+    "lab": "lab",
+}
+"""Map of environment aliases to canonical short names.
+
+Keys are the recognized input strings (from hostnames, CLI flags, etc.).
+Values are the canonical names stored in inventory records.
+"""

ots_shared-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+ots_shared/__init__.py,sha256=edoVgdqUhKcuLgCqd5yHzGnnciTt0a3wiPJCJinYkxo,63
+ots_shared/cli.py,sha256=mtA_pEexV43Q4fg36C0oNua-Npk9-r0x0Mcs2iOu1HI,1195
+ots_shared/exit_codes.py,sha256=0pVZMECJhxgPIo9Ad3Z6B0nTSJx5gVhiX0qKKAQxDJ0,913
+ots_shared/taxonomy.py,sha256=tCWa2NIFlaERJDzD6j0PIyYBDfFcTZ5HJRW1RarV42A,2174
+ots_shared/ssh/__init__.py,sha256=7rPxMwgTrypVD5mdf3i6be6LYWoPuYPoc8YOXCN6Vvc,1196
+ots_shared/ssh/_pty.py,sha256=wfIYQTNCQkqV0MJtCDfqMefwI9wyfqRLcjHT8APwdqM,5265
+ots_shared/ssh/connection.py,sha256=pkFUnCMtz11po_cEgk9LUuN4mPQhjagYdYz4yrXSogM,5326
+ots_shared/ssh/env.py,sha256=rBpbunOam8LbBYW_0RWIPTzk8J8Hg8hPq_sDNZutrGo,5791
+ots_shared/ssh/executor.py,sha256=o7aP-kyCS53yYnrfhIWuqjmSLFpbFh71Y3zzB7uK0mg,15711
+ots_shared-0.2.0.dist-info/METADATA,sha256=4n84hXjQ2Q_tjqNHGiWyM5WGOXnUvDdpLKODW_ar6k0,1045
+ots_shared-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ots_shared-0.2.0.dist-info/RECORD,,

ots_shared-0.2.0.dist-info/WHEEL

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