command-gate 0.2.4__py3-none-any.whl

cgate/__init__.py

@@ -0,0 +1,26 @@
+"""cgate: middleware and CLI between AI assistants and managed servers."""
+
+from __future__ import annotations
+
+try:
+    from cgate._version import __version__ as __version__
+except ImportError:
+    # _version.py is generated by hatch-vcs (for source installs) and by
+    # scripts/_ensure_version.py (for PyInstaller binaries). When neither
+    # has run yet (e.g., a bare `python -c "import cgate"` from a fresh
+    # clone), fall back to git describe so the runtime version is still
+    # meaningful instead of crashing with a hard-coded stale value.
+    import subprocess
+    from pathlib import Path
+
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--abbrev=0", "--match=v*"],
+            cwd=Path(__file__).resolve().parents[2],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        __version__ = result.stdout.strip().lstrip("v")
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+        __version__ = "0.0.0+unknown"

cgate/__main__.py

@@ -0,0 +1,8 @@
+"""Run command-gate as a Python module."""
+
+from __future__ import annotations
+
+from cgate.cli.main import main
+
+if __name__ == "__main__":
+    main()

cgate/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)
+
+__commit_id__ = commit_id = None

cgate/cli/__init__.py

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

cgate/cli/_console.py

@@ -0,0 +1,17 @@
+"""Shared console-interaction helpers for CLI commands."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+
+
+def should_pause(no_pause: bool) -> bool:  # noqa: FBT001 -- CLI flags are plain bools
+    """Pause for human review unless --no-pause or stdin is not a TTY."""
+    return not no_pause and sys.stdin.isatty()
+
+
+def wait_for_enter() -> None:
+    """Block until the user presses Enter; silently no-op on EOF (pipe/CI)."""
+    with contextlib.suppress(EOFError):
+        input("Press Enter to close...")

cgate/cli/connections.py

@@ -0,0 +1,212 @@
+"""CLI group for saved server connections."""
+
+from __future__ import annotations
+
+import sqlite3
+
+import typer
+from click import Choice
+from rich.console import Console
+from rich.table import Table
+
+from cgate.connections.auth import (
+    get_credential,
+    is_kerberos_available,
+    remove_credential,
+    store_credential,
+)
+from cgate.connections.detect import (
+    AmbiguousHostError,
+    UnknownHostError,
+    probe_host,
+)
+from cgate.connections.store import ConnectionsRepo
+from cgate.core.paths import db_path
+from cgate.db.connection import Database, init_database
+from cgate.db.types import ServerType
+
+connections_app = typer.Typer(help="Manage saved server connections.")
+console = Console()
+
+
+def _db() -> Database:
+    """Open the local SQLite database and create its schema when absent."""
+    db = Database(path=db_path())
+    init_database(db)
+    return db
+
+
+@connections_app.command("add")
+def add(alias: str, hostname: str) -> None:
+    """Detect the server type, save the connection, and collect credentials."""
+    # Pre-check alias before doing any network probe or prompting for
+    # credentials. Without this, a duplicate alias wastes the user's
+    # time on a probe plus username/password prompts before the
+    # IntegrityError surfaces. See issue #16.
+    repo = ConnectionsRepo(_db())
+    if repo.get(alias) is not None:
+        console.print(
+            f"[red]Error:[/red] A connection with alias [bold]'{alias}'[/bold] "
+            f"already exists. Use [bold]cgate connections remove {alias}[/bold] "
+            f"first, or choose a different alias."
+        )
+        raise typer.Exit(code=1) from None
+
+    probe = probe_host(hostname)
+    try:
+        server_type = probe.server_type
+    except AmbiguousHostError:
+        console.print(
+            f"[yellow]{hostname} responded to BOTH SSH and WinRM. Choose one.[/yellow]"
+        )
+        choice = typer.prompt("Protocol", type=Choice(["ssh", "winrm"]))
+        server_type = (
+            ServerType.LINUX if choice == "ssh" else ServerType.WINDOWS
+        )
+    except UnknownHostError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    try:
+        _ = repo.add(
+            alias=alias,
+            hostname=hostname,
+            server_type=server_type,
+            detection_ssh=probe.ssh,
+            detection_winrm=probe.winrm,
+        )
+    except sqlite3.IntegrityError:
+        # Race fallback: between the pre-check above and this INSERT,
+        # another process could have added the same alias. Surface the
+        # same friendly message instead of a raw traceback (issue #1).
+        console.print(
+            f"[red]Error:[/red] A connection with alias [bold]'{alias}'[/bold] "
+            f"already exists. Use [bold]cgate connections remove {alias}[/bold] "
+            f"first, or choose a different alias."
+        )
+        raise typer.Exit(code=1) from None
+    console.print(f"Saved [bold]{alias}[/bold] -> {hostname} ({server_type.value}).")
+
+    if is_kerberos_available():
+        console.print(
+            "[dim]Kerberos passthrough detected; no credentials to store.[/dim]"
+        )
+        return
+
+    username = typer.prompt("Username")
+    if server_type is ServerType.LINUX:
+        ssh_key = typer.prompt(
+            "SSH key path (blank for password auth)", default="", show_default=False
+        )
+        if ssh_key.strip():
+            store_credential(
+                alias, username=username, password=None, ssh_key=ssh_key.strip()
+            )
+            console.print(
+                f"Stored SSH-key credential for [bold]{alias}[/bold] in OS keyring."
+            )
+        else:
+            password = typer.prompt("Password", hide_input=True)
+            store_credential(
+                alias, username=username, password=password, ssh_key=None
+            )
+            console.print(
+                f"Stored password credential for [bold]{alias}[/bold] in OS keyring."
+            )
+    else:
+        password = typer.prompt("Password", hide_input=True)
+        store_credential(alias, username=username, password=password, ssh_key=None)
+        console.print(
+            f"Stored WinRM credential for [bold]{alias}[/bold] in OS keyring."
+        )
+
+
+@connections_app.command("list")
+def list_cmd() -> None:
+    """List all saved connections in a table."""
+    conns = ConnectionsRepo(_db()).list_all()
+    if not conns:
+        console.print("[dim]No connections saved.[/dim]")
+        return
+    table = Table(title="Saved connections")
+    table.add_column("Alias", style="bold")
+    table.add_column("Hostname")
+    table.add_column("Type")
+    table.add_column("SSH?", justify="center")
+    table.add_column("WinRM?", justify="center")
+    table.add_column("Created")
+    for connection in conns:
+        table.add_row(
+            connection.alias,
+            connection.hostname,
+            connection.server_type.value,
+            "Y" if connection.detection_ssh else "N",
+            "Y" if connection.detection_winrm else "N",
+            connection.created_at.isoformat(),
+        )
+    console.print(table)
+
+
+@connections_app.command("remove")
+def remove(alias: str) -> None:
+    """Remove a connection and its credential from the OS keyring."""
+    if not typer.confirm(f"Remove connection '{alias}'?"):
+        raise typer.Abort
+    repo = ConnectionsRepo(_db())
+    if repo.get(alias) is None:
+        console.print(f"[red]No connection '{alias}' found.[/red]")
+        raise typer.Exit(code=1)
+
+    # Remove the keyring credential BEFORE the DB row (issue #5). If the
+    # keyring backend is unavailable -- common on headless Linux, where
+    # keyring.errors.NoKeyringError is raised -- aborting here leaves the
+    # connection intact and reusable instead of deleting the DB row and
+    # orphaning a credential no connection can ever reference again.
+    #
+    # Three cases to distinguish:
+    # 1. No credential was ever stored (kerberos-mode adds store none,
+    #    or the keyring was down at add time, etc.). Removing the DB row
+    #    is safe -- there is nothing in the keyring to orphan.
+    # 2. A credential exists. Removal must succeed; otherwise we'd
+    #    orphan it. `remove_credential` swallows `KeyringError` (incl.
+    #    `NoKeyringError`) and returns False -- so we must check the
+    #    bool, since the `except Exception` below never sees that case.
+    # 3. We can't even read the keyring (backend unavailable). We can't
+    #    tell whether case 1 or 2 applies, so conservatively abort.
+    try:
+        existing = get_credential(alias)
+    except Exception as exc:
+        console.print(
+            f"[red]Could not read the stored credential for '{alias}' "
+            f"from the OS keyring:[/red] {exc}\n"
+            "[dim]The connection was NOT removed. Fix the keyring backend "
+            "and retry, or remove the credential manually first.[/dim]"
+        )
+        raise typer.Exit(code=1) from exc
+    if existing is not None:
+        try:
+            keyring_removed = remove_credential(alias)
+        except Exception as exc:
+            console.print(
+                f"[red]Could not remove the stored credential for '{alias}' "
+                f"from the OS keyring:[/red] {exc}\n"
+                "[dim]The connection was NOT removed. Fix the keyring backend "
+                "and retry, or remove the credential manually first.[/dim]"
+            )
+            raise typer.Exit(code=1) from exc
+        if not keyring_removed:
+            console.print(
+                f"[red]Could not remove the stored credential for '{alias}' "
+                f"from the OS keyring.[/red]\n"
+                "[dim]The keyring backend is unavailable (common on headless "
+                "Linux, where no backend is registered with the `keyring` "
+                "library); the connection was NOT removed. Fix the keyring "
+                "backend or remove the credential manually first, then retry.[/dim]"
+            )
+            raise typer.Exit(code=1) from None
+
+    removed = repo.remove(alias)
+    if not removed:
+        console.print(f"[red]No connection '{alias}' found.[/red]")
+        raise typer.Exit(code=1)
+    console.print(f"Removed [bold]{alias}[/bold].")

cgate/cli/history.py

@@ -0,0 +1,191 @@
+"""CLI commands for browsing and exporting the resolved-batch audit trail."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from enum import StrEnum
+
+# Typer resolves Annotated parameter types at runtime via
+# inspect.signature(eval_str=True); moving this into TYPE_CHECKING (as the
+# linter would otherwise suggest) makes `history export --help` raise
+# NameError: name 'Path' is not defined the moment Typer builds the command.
+from pathlib import Path  # noqa: TC003
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.console import Console
+
+from cgate.core.paths import db_path
+from cgate.db.batches import BatchesRepo
+from cgate.db.commands import CommandsRepo
+from cgate.db.connection import Database, init_database
+from cgate.db.rows import iso
+
+if TYPE_CHECKING:
+    from cgate.db.types import Batch, Command
+
+history_app = typer.Typer(help="Browse and export the resolved-batch audit trail.")
+console = Console()
+
+_CSV_FIELDNAMES: list[str] = [
+    "batch_id",
+    "batch_title",
+    "batch_description",
+    "requested_by_agent",
+    "batch_created_at",
+    "batch_resolved_at",
+    "command_id",
+    "position",
+    "server_alias",
+    "server_type",
+    "command",
+    "status",
+    "result",
+    "approved_by",
+    "reason",
+    "risk_label",
+    "command_created_at",
+    "command_resolved_at",
+]
+
+
+class ExportFormat(StrEnum):
+    """Output format for `cgate history export`."""
+
+    CSV = "csv"
+    JSON = "json"
+
+
+def _csv_row(batch: Batch, command: Command) -> dict[str, str]:
+    """Flatten one command, with its batch's context repeated, into a CSV row.
+
+    One row per command (not per batch) so a spreadsheet or `awk`/`grep`
+    over the export can filter/sort by any command-level field directly.
+    """
+    return {
+        "batch_id": batch.id,
+        "batch_title": batch.title,
+        "batch_description": batch.description or "",
+        "requested_by_agent": batch.requested_by_agent or "",
+        "batch_created_at": iso(batch.created_at),
+        "batch_resolved_at": iso(batch.resolved_at) if batch.resolved_at else "",
+        "command_id": command.id,
+        "position": str(command.position),
+        "server_alias": command.server_alias,
+        "server_type": command.server_type.value,
+        "command": command.command,
+        "status": command.status.value,
+        "result": command.result or "",
+        "approved_by": command.approved_by or "",
+        "reason": command.reason or "",
+        "risk_label": command.risk_label or "",
+        "command_created_at": iso(command.created_at),
+        "command_resolved_at": iso(command.resolved_at) if command.resolved_at else "",
+    }
+
+
+def _json_command(command: Command) -> dict[str, object]:
+    return {
+        "id": command.id,
+        "position": command.position,
+        "server_alias": command.server_alias,
+        "server_type": command.server_type.value,
+        "command": command.command,
+        "status": command.status.value,
+        "result": command.result,
+        "approved_by": command.approved_by,
+        "reason": command.reason,
+        "risk_label": command.risk_label,
+        "created_at": iso(command.created_at),
+        "resolved_at": iso(command.resolved_at) if command.resolved_at else None,
+    }
+
+
+def _json_batch(batch: Batch, commands: list[Command]) -> dict[str, object]:
+    """Nest a batch's commands under it.
+
+    The natural shape for JSON, unlike the CSV export's
+    one-row-per-command flattening.
+    """
+    return {
+        "batch_id": batch.id,
+        "title": batch.title,
+        "description": batch.description,
+        "requested_by_agent": batch.requested_by_agent,
+        "created_at": iso(batch.created_at),
+        "resolved_at": iso(batch.resolved_at) if batch.resolved_at else None,
+        "commands": [_json_command(command) for command in commands],
+    }
+
+
+def _render_csv(batches: list[Batch], commands_repo: CommandsRepo) -> str:
+    buffer = io.StringIO()
+    writer = csv.DictWriter(buffer, fieldnames=_CSV_FIELDNAMES)
+    writer.writeheader()
+    for batch in batches:
+        for command in commands_repo.list_for_batch(batch.id):
+            writer.writerow(_csv_row(batch, command))
+    return buffer.getvalue()
+
+
+def _render_json(batches: list[Batch], commands_repo: CommandsRepo) -> str:
+    payload = [_json_batch(batch, commands_repo.list_for_batch(batch.id)) for batch in batches]
+    return json.dumps(payload, indent=2)
+
+
+@history_app.command("export")
+def export_cmd(
+    *,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="File to write to. Prints to stdout when omitted.",
+        ),
+    ] = None,
+    export_format: Annotated[
+        ExportFormat,
+        typer.Option("--format", "-f", help="Output format."),
+    ] = ExportFormat.CSV,
+    limit: Annotated[
+        int | None,
+        typer.Option(
+            "--limit",
+            help=(
+                "Cap how many resolved batches to include (most recently resolved "
+                "first). Exports the full audit trail by default."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Export every resolved batch and its commands -- the full audit trail.
+
+    A human-only export: this reads the same data `cgate watch`'s History
+    screen (`h`) shows, for compliance reporting or offline analysis. Not
+    exposed to AI agents over MCP -- an agent that proposed a batch can
+    already poll its own `check_status(batch_id)` at any time, resolved or
+    not, and there's no reason to hand it a browse of everyone else's.
+    """
+    db = Database(path=db_path())
+    init_database(db)
+    batches_repo = BatchesRepo(db)
+    commands_repo = CommandsRepo(db)
+    resolved = batches_repo.list_resolved(limit=limit)
+
+    text = (
+        _render_csv(resolved, commands_repo)
+        if export_format is ExportFormat.CSV
+        else _render_json(resolved, commands_repo)
+    )
+
+    if output is None:
+        typer.echo(text)
+        return
+    _ = output.write_text(text, encoding="utf-8")
+    console.print(f"Wrote [bold]{len(resolved)}[/bold] resolved batch(es) to {output}")
+
+
+__all__ = ["history_app"]

cgate/cli/install.py

@@ -0,0 +1,182 @@
+"""Install cgate onto this machine.
+
+Copies the running binary into a per-user bin directory and registers
+that directory on PATH.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import typer
+from rich.console import Console
+
+from cgate.cli._console import should_pause, wait_for_enter
+from cgate.core.path_env import (
+    copy_binary,
+    ensure_posix_shell_path,
+    ensure_windows_user_path,
+    install_dir,
+    install_target_path,
+)
+from cgate.mcp_installer import detect_clients, register
+from cgate.update import current_binary_path
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+console = Console()
+
+
+def _current_source_and_target() -> tuple[Path, Path] | None:
+    """Return (source, target) when running from a frozen binary, else None."""
+    source = current_binary_path()
+    if source is None:
+        return None
+    return source, install_target_path()
+
+
+def _perform_install(source: Path, target: Path) -> bool:
+    """Copy the binary to ``target`` and register it on PATH.
+
+    Returns True if a fresh install actually happened, False if already
+    installed at ``target``. Raises ``typer.Exit(code=1)`` if a
+    different file already exists at the target, or if the copy/PATH
+    write itself fails -- both print their own explanation first.
+    """
+    console.print("[bold]Install:[/bold]")
+    already_at_target = source.resolve() == target.resolve()
+    if already_at_target:
+        console.print(f"  Binary: [dim]already running from {target}[/dim]")
+    elif target.exists():
+        console.print(f"  [red]{target} already exists.[/red]")
+        console.print(
+            f"  [dim]That looks like an existing cgate install. To update it, "
+            f"run `cgate update apply` from {target} instead.[/dim]"
+        )
+        raise typer.Exit(code=1)
+    else:
+        try:
+            copy_binary(source, target)
+        except OSError as exc:
+            console.print(f"  [red]Failed to copy binary to {target}:[/red] {exc}")
+            raise typer.Exit(code=1) from exc
+        console.print(f"  Binary: [green]copied to {target}[/green]")
+
+    directory = install_dir()
+    rc_path = None
+    try:
+        if sys.platform == "win32":
+            path_status = ensure_windows_user_path(directory)
+        else:
+            path_status, rc_path = ensure_posix_shell_path(directory)
+    except OSError as exc:
+        console.print(f"  [red]Failed to update PATH:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    if path_status == "already_present":
+        console.print(f"  PATH: [dim]{directory} already on PATH[/dim]")
+    else:
+        console.print(f"  PATH: [green]added {directory}[/green]")
+        if sys.platform == "win32":
+            console.print(
+                "  [dim]Open a new terminal for `cgate` to be found on PATH "
+                "(already-open shells won't pick this up).[/dim]"
+            )
+        else:
+            console.print(
+                f"  [dim]Run `source {rc_path}` or open a new terminal for "
+                "`cgate` to be found on PATH.[/dim]"
+            )
+
+    return not already_at_target
+
+
+def _auto_register_mcp_clients(target: Path) -> None:
+    """Register every detected IA client with no confirmation prompts.
+
+    Used only by the zero-argument first-run flow, where the user has
+    already opted into full automation by not typing anything else.
+    Registers against ``target`` directly (``mcp serve``), not
+    ``current_binary_command()``'s ``sys.executable`` resolution, which
+    at this point in the process still resolves to the pre-copy source
+    binary, not the just-installed one.
+    """
+    clients = detect_clients()
+    if not clients:
+        console.print(
+            "\n[dim]No IA clients detected yet -- run `cgate mcp install` "
+            "later once you have one.[/dim]"
+        )
+        return
+    console.print(f"\nRegistering with {len(clients)} detected IA client(s)...")
+    command, args = str(target), ["mcp", "serve"]
+    for client in clients:
+        try:
+            register(client, command, args)
+        except OSError as exc:
+            console.print(f"  [red]Failed to register {client.label}:[/red] {exc}")
+            continue
+        console.print(f"  [green]Registered {client.label}.[/green]")
+
+
+def install_cmd() -> None:
+    """Copy this binary into ~/bin (Windows) or ~/.local/bin (macOS/Linux) and add it to PATH.
+
+    Safe to run repeatedly: already installed at the target, and already
+    on PATH, are both detected and reported rather than redone.
+    """
+    result = _current_source_and_target()
+    if result is None:
+        console.print(
+            "[yellow]Not running from a packaged binary; nothing to install.[/yellow]\n"
+            "[dim]`cgate install` only applies to the downloaded release "
+            "binary, not a source checkout.[/dim]"
+        )
+        return
+
+    source, target = result
+    _perform_install(source, target)
+    console.print("\nNext: run [bold]cgate mcp install[/bold] to register with your AI clients.")
+
+
+def maybe_auto_install(*, unattended: bool = False) -> bool:
+    """Run automatically when cgate is invoked with no arguments at all.
+
+    A binary just downloaded and double-clicked (or run bare from a
+    terminal) is a frozen binary not yet at the install target -- in
+    that case, do the full first-run setup (install + MCP client
+    registration) with no confirmation prompts, since the whole point
+    of this path is "just run the exe, nothing else." Returns True if
+    it did this (the caller should not also print help); False when
+    there was nothing to auto-install (dev mode, or already properly
+    installed), in which case the caller falls through to normal help.
+
+    ``unattended`` skips the "Press Enter to close" pause at the end
+    (there are no prompts to skip either way -- this path never has
+    any) so a scripted/silent deployment (``cgate-windows-amd64.exe
+    --unattended``) runs start to finish and exits on its own, instead
+    of waiting on a keypress nobody is there to send.
+    """
+    result = _current_source_and_target()
+    if result is None:
+        return False
+    source, target = result
+    if source.resolve() == target.resolve():
+        return False  # already installed -- bare `cgate` should just show help
+
+    console.print("[bold]First run detected -- setting up cgate automatically.[/bold]\n")
+    _perform_install(source, target)
+    _auto_register_mcp_clients(target)
+
+    console.print(
+        "\n[bold]Almost done -- two things only your terminal/AI client can do:[/bold]\n"
+        "  1. Open a new terminal (already-open ones won't see the PATH change).\n"
+        "  2. Restart your AI client (Claude Code / opencode / Cursor) to load "
+        "the new MCP server."
+    )
+    if should_pause(no_pause=unattended):
+        console.print()
+        wait_for_enter()
+    return True