command-gate 0.2.4__py3-none-any.whl

cgate/connections/detect.py

@@ -0,0 +1,78 @@
+"""TCP probe to detect whether a remote host is Windows (WinRM) or Linux (SSH).
+
+Pure logic, no DB access, no keyring. Tests can mock socket.create_connection.
+"""
+from __future__ import annotations
+
+import socket
+from dataclasses import dataclass
+
+from cgate.db.types import ServerType
+
+SSH_PORT = 22
+WINRM_HTTP_PORT = 5985
+WINRM_HTTPS_PORT = 5986
+DEFAULT_PROBE_TIMEOUT = 2.0
+
+
+class AmbiguousHostError(Exception):
+    """Host responded to BOTH SSH and WinRM; user must choose."""
+
+
+class UnknownHostError(Exception):
+    """Host did not respond to either SSH or WinRM."""
+
+
+def _probe(hostname: str, port: int, timeout: float) -> bool:
+    """Try TCP connect and report whether the port is open within the timeout."""
+    try:
+        with socket.create_connection((hostname, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+@dataclass(frozen=True, slots=True)
+class DetectionProbe:
+    """Result of probing a host for SSH and WinRM."""
+
+    hostname: str
+    ssh: bool
+    winrm: bool
+
+    @property
+    def server_type(self) -> ServerType:
+        """Resolve the result or raise when the host is ambiguous or unknown."""
+        if self.ssh and self.winrm:
+            message = " ".join(
+                (
+                    f"{self.hostname} responded to both SSH (22) and WinRM",
+                    "(5985/5986). Specify which to use.",
+                )
+            )
+            raise AmbiguousHostError(message)
+        if self.ssh:
+            return ServerType.LINUX
+        if self.winrm:
+            return ServerType.WINDOWS
+        message = " ".join(
+            (
+                f"{self.hostname} did not respond to SSH (22) or WinRM",
+                "(5985/5986).",
+            )
+        )
+        raise UnknownHostError(message)
+
+
+def probe_host(
+    hostname: str, *, timeout: float = DEFAULT_PROBE_TIMEOUT
+) -> DetectionProbe:
+    """Probe the host for SSH and WinRM and return both binary signals."""
+    ssh = _probe(hostname, SSH_PORT, timeout)
+    winrm_https = _probe(hostname, WINRM_HTTPS_PORT, timeout)
+    winrm_http = _probe(hostname, WINRM_HTTP_PORT, timeout)
+    return DetectionProbe(
+        hostname=hostname,
+        ssh=ssh,
+        winrm=winrm_https or winrm_http,
+    )

cgate/connections/store.py

@@ -0,0 +1,88 @@
+"""Persistence for saved connection aliases — parallels detect.py and auth.py."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from cgate.db.connection import Database, connect
+from cgate.db.rows import iso, row_to_connection
+from cgate.db.types import Connection, ServerType
+
+
+class ConnectionsRepo:
+    """Saved connection CRUD keyed by a user-defined alias."""
+
+    _db: Database  # class-level annotation required by strict mode
+
+    def __init__(self, db: Database) -> None:
+        """Store the database handle for subsequent operations."""
+        self._db = db
+
+    def add(
+        self,
+        *,
+        alias: str,
+        hostname: str,
+        server_type: ServerType,
+        detection_ssh: bool,
+        detection_winrm: bool,
+    ) -> Connection:
+        """Save a connection with its detection signals and current UTC timestamp."""
+        now = datetime.now(UTC)
+        with connect(self._db) as conn:
+            _ = conn.execute(
+                """
+                INSERT INTO connections (alias, hostname, server_type,
+                    detection_ssh, detection_winrm, created_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    alias,
+                    hostname,
+                    server_type.value,
+                    detection_ssh,
+                    detection_winrm,
+                    iso(now),
+                ),
+            )
+        return Connection(
+            alias=alias,
+            hostname=hostname,
+            server_type=server_type,
+            detection_ssh=detection_ssh,
+            detection_winrm=detection_winrm,
+            created_at=now,
+        )
+
+    def get(self, alias: str) -> Connection | None:
+        """Fetch a connection by alias, or None if it is absent."""
+        with connect(self._db) as conn:
+            row = conn.execute(
+                """
+                SELECT alias, hostname, server_type, detection_ssh, detection_winrm,
+                    created_at
+                FROM connections WHERE alias = ?
+                """,
+                (alias,),
+            ).fetchone()
+        return row_to_connection(row) if row is not None else None
+
+    def list_all(self) -> list[Connection]:
+        """Return every saved connection ordered by alias."""
+        with connect(self._db) as conn:
+            rows = conn.execute(
+                """
+                SELECT alias, hostname, server_type, detection_ssh, detection_winrm,
+                    created_at
+                FROM connections ORDER BY alias ASC
+                """
+            ).fetchall()
+        return [row_to_connection(row) for row in rows]
+
+    def remove(self, alias: str) -> bool:
+        """Delete a connection and report whether a row was removed."""
+        with connect(self._db) as conn:
+            cursor = conn.execute(
+                "DELETE FROM connections WHERE alias = ?",
+                (alias,),
+            )
+        return cursor.rowcount > 0

cgate/core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cgate/core/path_env.py

@@ -0,0 +1,218 @@
+r"""Per-user install directory and PATH registration mechanics.
+
+Pure logic, no typer/rich -- testable without CliRunner. On Windows, every
+registry call goes through the module-level ``winreg`` name (never a
+function-local ``import winreg``) specifically so tests can replace it
+with a fake and never touch the real ``HKEY_CURRENT_USER\Environment``
+key on the machine running the test suite.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Final
+
+try:
+    import winreg
+except ImportError:  # non-Windows -- module must still import cleanly
+    winreg = None  # type: ignore[assignment]
+
+_ENV_SUBKEY: Final = "Environment"
+_PATH_VALUE_NAME: Final = "Path"
+_MARKER: Final = "# Added by cgate install"
+
+# WM_SETTINGCHANGE broadcast constants (winuser.h).
+_HWND_BROADCAST: Final = 0xFFFF
+_WM_SETTINGCHANGE: Final = 0x001A
+_SMTO_ABORTIFHUNG: Final = 0x0002
+_BROADCAST_TIMEOUT_MS: Final = 5000
+
+
+def install_dir() -> Path:
+    r"""Per-user directory ``cgate install`` copies the binary into.
+
+    Windows: ``%USERPROFILE%\bin`` (already the directory named in
+    TECHNICAL.md's manual instructions). macOS/Linux: ``~/.local/bin``.
+    No admin/sudo path exists or is planned -- user-level only.
+    """
+    if sys.platform == "win32":
+        return Path.home() / "bin"
+    return Path.home() / ".local" / "bin"
+
+
+def install_target_path() -> Path:
+    """Where the installed binary itself should live.
+
+    A fixed filename ("cgate.exe" / "cgate"), not whatever the source
+    file happens to be named (e.g. ``cgate-windows-amd64.exe`` as
+    downloaded), so `cgate` on PATH resolves regardless of the download's
+    original name.
+    """
+    name = "cgate.exe" if sys.platform == "win32" else "cgate"
+    return install_dir() / name
+
+
+def copy_binary(source: Path, target: Path) -> None:
+    """Copy ``source`` to ``target``, preserving the executable bit.
+
+    Uses ``shutil.copy2`` -- NOT ``copyfile``, which does not preserve
+    permission bits and would silently produce a non-executable copy on
+    macOS/Linux.
+    """
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+# ---- Windows: HKCU\Environment\Path ----------------------------------
+
+
+def ensure_windows_user_path(directory: Path) -> str:
+    r"""Ensure ``directory`` is present in ``HKCU\Environment\Path``.
+
+    Returns ``"already_present"`` or ``"added"``. Raises ``OSError`` on a
+    genuine registry failure. Windows-only -- the function has no hive
+    parameter, so it is structurally impossible for it to target
+    anything but ``HKEY_CURRENT_USER``; ``HKEY_LOCAL_MACHINE`` (which
+    would require admin rights) is never referenced anywhere in this
+    module.
+    """
+    assert winreg is not None, "ensure_windows_user_path must only be called on win32"
+    target = str(directory)
+
+    # CreateKeyEx (not OpenKey) so a brand-new user profile where the
+    # Environment key itself doesn't exist yet still works -- it opens or
+    # creates atomically instead of needing a separate existence check.
+    with winreg.CreateKeyEx(
+        winreg.HKEY_CURRENT_USER, _ENV_SUBKEY, 0, winreg.KEY_READ | winreg.KEY_WRITE
+    ) as key:
+        try:
+            current_value, value_type = winreg.QueryValueEx(key, _PATH_VALUE_NAME)
+        except FileNotFoundError:
+            # Rare but real: brand-new profile, Path value never created.
+            # REG_EXPAND_SZ is the type Windows itself uses for a
+            # freshly-created user Path value.
+            current_value, value_type = "", winreg.REG_EXPAND_SZ
+
+        if _path_dir_present(current_value, target):
+            return "already_present"
+
+        new_value = f"{current_value};{target}" if current_value else target
+        # value_type is exactly what was read above (or the default) --
+        # never assumed, never upgraded. We only ever append a
+        # fully-resolved literal directory (no "%...%" tokens of our
+        # own), so appending into a REG_EXPAND_SZ value is always safe.
+        winreg.SetValueEx(key, _PATH_VALUE_NAME, 0, value_type, new_value)
+
+    _broadcast_environment_change()
+    return "added"
+
+
+def _path_dir_present(current_value: str, target: str) -> bool:
+    """Case-insensitive, ``;``-split, ``%VAR%``-tolerant membership check.
+
+    Deliberately does not call ``Path.resolve()`` (which touches the
+    filesystem and requires the path to exist) -- pure string
+    normalization, so it works identically whether or not the directory
+    exists yet.
+    """
+    target_norm = os.path.normcase(os.path.normpath(target))
+    for raw_entry in current_value.split(";"):
+        entry = raw_entry.strip()
+        if not entry:
+            continue
+        expanded = os.path.expandvars(entry)  # handles %USERPROFILE%\bin etc.
+        if os.path.normcase(os.path.normpath(expanded)) == target_norm:
+            return True
+    return False
+
+
+def _broadcast_environment_change() -> None:
+    """Best-effort WM_SETTINGCHANGE broadcast.
+
+    Lets newly-launched processes pick up the PATH change without a full
+    logoff (already-open shells still won't see it). Must never be
+    fatal -- wrapped broadly and always swallowed.
+
+    ``argtypes``/``restype`` are declared explicitly and are NOT
+    optional: without them ctypes defaults every argument to 32-bit
+    ``c_int`` on a 64-bit process, corrupting the HWND, the lParam
+    string pointer, and the output pointer -- silent memory corruption,
+    not just "might not work". The output parameter is ``DWORD_PTR``
+    (pointer-sized, 8 bytes on 64-bit Windows), so it uses ``c_size_t``,
+    not ``c_ulong`` (which stays 32-bit under Windows' LLP64 model and
+    would be undersized for the write).
+    """
+    if sys.platform != "win32":
+        return
+    try:
+        user32 = ctypes.windll.user32  # type: ignore[attr-defined]
+        send = user32.SendMessageTimeoutW
+        send.argtypes = [
+            ctypes.c_void_p,  # HWND
+            ctypes.c_uint,  # UINT Msg
+            ctypes.c_void_p,  # WPARAM
+            ctypes.c_wchar_p,  # LPARAM ("Environment")
+            ctypes.c_uint,  # UINT fuFlags
+            ctypes.c_uint,  # UINT uTimeout
+            ctypes.POINTER(ctypes.c_size_t),  # PDWORD_PTR lpdwResult
+        ]
+        send.restype = ctypes.c_ssize_t  # LRESULT
+        result = ctypes.c_size_t()
+        send(
+            ctypes.c_void_p(_HWND_BROADCAST),
+            _WM_SETTINGCHANGE,
+            None,
+            "Environment",
+            _SMTO_ABORTIFHUNG,
+            _BROADCAST_TIMEOUT_MS,
+            ctypes.byref(result),
+        )
+    except (OSError, AttributeError, TypeError):
+        pass
+
+
+# ---- POSIX: shell rc file ---------------------------------------------
+
+
+def detect_shell_rc() -> Path:
+    """Best-effort ``$SHELL``-based rc file detection.
+
+    A heuristic, not a guarantee: ``$SHELL`` reflects the login shell,
+    not necessarily whatever shell actually launched ``cgate install``,
+    and classic macOS bash setups that source ``.bash_profile`` instead
+    of ``.bashrc`` won't be picked up. Falls back to ``~/.profile`` (a
+    portable POSIX default) for anything unrecognized.
+    """
+    name = Path(os.environ.get("SHELL", "")).name
+    home = Path.home()
+    if name == "zsh":
+        return home / ".zshrc"
+    if name == "fish":
+        return home / ".config" / "fish" / "config.fish"
+    if name == "bash":
+        return home / ".bashrc"
+    return home / ".profile"
+
+
+def ensure_posix_shell_path(directory: Path, rc_path: Path | None = None) -> tuple[str, Path]:
+    """Ensure ``directory`` is exported on PATH via a shell rc file.
+
+    Idempotent via ``_MARKER``. ``rc_path`` is injectable so tests never
+    touch a real home-directory dotfile. Returns ``(status, rc_path)``
+    where status is ``"already_present"`` or ``"added"``. Cannot affect
+    the currently-running parent shell -- the caller must tell the user
+    to restart their terminal or ``source`` the file.
+    """
+    rc_path = rc_path if rc_path is not None else detect_shell_rc()
+    existing = rc_path.read_text(encoding="utf-8") if rc_path.exists() else ""
+    if _MARKER in existing:
+        return "already_present", rc_path
+    rc_path.parent.mkdir(parents=True, exist_ok=True)
+    block = f'\n{_MARKER}\nexport PATH="{directory}:$PATH"\n'
+    with rc_path.open("a", encoding="utf-8") as f:
+        f.write(block)
+    return "added", rc_path

cgate/core/paths.py

@@ -0,0 +1,35 @@
+"""Per-user storage paths for command-gate."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def data_dir() -> Path:
+    """Return the OS-appropriate per-user data directory for command-gate."""
+    app = "command-gate"
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
+        if base is None:
+            base = str(Path.home() / "AppData" / "Local")
+        return Path(base) / app
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / app
+    base = os.environ.get("XDG_DATA_HOME")
+    if base:
+        return Path(base) / app
+    return Path.home() / ".local" / "share" / app
+
+
+def db_path() -> Path:
+    """Return the path to the SQLite database.
+
+    Overridable via the CGATE_DB_PATH environment variable (used by tests
+    and by operators who want to point at an alternate location).
+    """
+    override = os.environ.get("CGATE_DB_PATH")
+    if override:
+        return Path(override)
+    return data_dir() / "cgate.db"

cgate/core/update_log.py

@@ -0,0 +1,36 @@
+"""Best-effort append-only logging for background update/uninstall operations.
+
+Lives in ``cgate.core`` (not ``cgate.cli``) because it's shared by the
+interactive CLI and the non-interactive ``cgate.helper`` binary, which must
+not import anything from ``cgate.cli`` (typer/rich/mcp/paramiko/pywinrm).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import cgate.core.paths
+
+_LOG_FILENAME = "update.log"
+
+
+def append_log(message: str) -> None:
+    """Append a timestamped line to ``<data_dir>/update.log``. Never raises.
+
+    Best-effort: any failure (permission denied, missing dir, encoding
+    errors) is silently swallowed. Logging must never crash the caller --
+    in particular, the helper process that runs after the main cgate
+    process has exited has no other way to surface failure.
+
+    Uses ``cgate.core.paths.data_dir`` (attribute lookup at call time)
+    rather than a module-level import so tests can monkeypatch the data
+    directory location.
+    """
+    try:
+        log_path = cgate.core.paths.data_dir() / _LOG_FILENAME
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now(UTC).isoformat(timespec="seconds")
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(f"[{timestamp}] {message}\n")
+    except Exception:
+        pass

cgate/db/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cgate/db/batches.py

@@ -0,0 +1,111 @@
+"""BatchesRepo: CRUD + FIFO queue queries for the `batches` table."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from cgate.db.connection import Database, connect
+from cgate.db.rows import iso, row_to_batch
+from cgate.db.types import Batch, BatchId
+
+
+class BatchesRepo:
+    """Batch CRUD + queue queries (FIFO pending list, mark resolved)."""
+
+    _db: Database  # class-level annotation required by strict mode
+
+    def __init__(self, db: Database) -> None:
+        """Store the database handle for subsequent operations."""
+        self._db = db
+
+    def create(
+        self,
+        *,
+        title: str,
+        description: str | None,
+        requested_by_agent: str | None,
+    ) -> Batch:
+        """Create a new batch with a fresh UUID and the current UTC timestamp."""
+        batch_id = BatchId(str(uuid4()))
+        now = datetime.now(UTC)
+        with connect(self._db) as conn:
+            _ = conn.execute(
+                """
+                INSERT INTO batches
+                    (id, title, description, requested_by_agent, created_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (batch_id, title, description, requested_by_agent, iso(now)),
+            )
+        return Batch(
+            id=batch_id,
+            title=title,
+            description=description,
+            requested_by_agent=requested_by_agent,
+            created_at=now,
+            resolved_at=None,
+        )
+
+    def get(self, batch_id: BatchId) -> Batch | None:
+        """Fetch a batch by its ID, or None if not found."""
+        with connect(self._db) as conn:
+            row = conn.execute(
+                """
+                SELECT id, title, description, requested_by_agent, created_at, resolved_at
+                FROM batches WHERE id = ?
+                """,
+                (batch_id,),
+            ).fetchone()
+        return row_to_batch(row) if row is not None else None
+
+    def list_pending(self) -> list[Batch]:
+        """Return pending batches (resolved_at IS NULL), oldest first (FIFO)."""
+        with connect(self._db) as conn:
+            rows = conn.execute(
+                """
+                SELECT id, title, description, requested_by_agent, created_at, resolved_at
+                FROM batches
+                WHERE resolved_at IS NULL
+                ORDER BY created_at ASC, id ASC
+                """
+            ).fetchall()
+        return [row_to_batch(r) for r in rows]
+
+    def list_resolved(self, *, limit: int | None = 50) -> list[Batch]:
+        """Return resolved batches, most recently resolved first.
+
+        The live queue drops a batch the instant it resolves (`list_pending`
+        filters it out), so this is the only way to look back at anything
+        that already went through -- approved, rejected, or auto-executed.
+
+        ``limit=None`` returns every resolved batch (SQLite's own
+        ``LIMIT -1`` means "unlimited") -- used by ``cgate history export``,
+        where the whole audit trail is the point, unlike the History
+        screen's bounded browse list.
+        """
+        with connect(self._db) as conn:
+            rows = conn.execute(
+                """
+                SELECT id, title, description, requested_by_agent, created_at, resolved_at
+                FROM batches
+                WHERE resolved_at IS NOT NULL
+                ORDER BY resolved_at DESC
+                LIMIT ?
+                """,
+                (limit if limit is not None else -1,),
+            ).fetchall()
+        return [row_to_batch(r) for r in rows]
+
+    def mark_resolved(
+        self, batch_id: BatchId, *, resolved_at: datetime | None = None
+    ) -> None:
+        """Stamp resolved_at; no-op if the batch is already resolved."""
+        when = resolved_at if resolved_at is not None else datetime.now(UTC)
+        with connect(self._db) as conn:
+            _ = conn.execute(
+                """
+                UPDATE batches SET resolved_at = ?
+                WHERE id = ? AND resolved_at IS NULL
+                """,
+                (iso(when), batch_id),
+            )