kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/cli/commands/ops/list_sessions.py

@@ -0,0 +1,252 @@
+"""List all sessions."""
+
+from __future__ import annotations
+
+import json as json_lib
+import logging
+from typing import Any
+
+from rich.table import Table
+
+from kstlib.cli.common import console
+from kstlib.config import get_config
+from kstlib.ops import (
+    ContainerRunner,
+    SessionStatus,
+    TmuxRunner,
+)
+from kstlib.ops.exceptions import BackendNotFoundError
+from kstlib.ops.models import BackendType, SessionState
+from kstlib.ops.validators import (
+    validate_command,
+    validate_env,
+    validate_image_name,
+    validate_ports,
+    validate_session_name,
+    validate_volumes,
+)
+
+from .common import (
+    BACKEND_OPTION,
+    JSON_OPTION,
+)
+
+log = logging.getLogger(__name__)
+
+# Maximum number of config sessions to prevent DoS via large config
+_MAX_CONFIG_SESSIONS = 50
+
+_VALID_BACKENDS = {"tmux", "container"}
+
+_STATE_STYLES: dict[str, str] = {
+    "running": "green",
+    "defined": "dim",
+    "exited": "yellow",
+    "stopped": "yellow",
+    "unknown": "red",
+}
+
+
+def _load_config_sessions() -> dict[str, dict[str, Any]]:
+    """Load session definitions from kstlib configuration.
+
+    Reads ``ops.sessions`` from the config file and validates
+    each entry with deep defense checks.
+
+    Returns:
+        Validated session configs keyed by session name.
+    """
+    config = get_config()
+    ops_config: dict[str, Any] = config.get("ops", {})  # type: ignore[no-untyped-call]
+    raw_sessions: Any = ops_config.get("sessions", {})
+
+    # Deep defense: sessions must be a dict
+    if not isinstance(raw_sessions, dict):
+        log.warning("ops.sessions is not a dict, ignoring config sessions")
+        return {}
+
+    # Deep defense: limit number of sessions
+    if len(raw_sessions) > _MAX_CONFIG_SESSIONS:
+        log.warning(
+            "ops.sessions has %d entries (max %d), truncating",
+            len(raw_sessions),
+            _MAX_CONFIG_SESSIONS,
+        )
+        # Take only first N entries
+        raw_sessions = dict(list(raw_sessions.items())[:_MAX_CONFIG_SESSIONS])
+
+    validated: dict[str, dict[str, Any]] = {}
+    for name, data in raw_sessions.items():
+        if not isinstance(data, dict):
+            log.warning("Session '%s' config is not a dict, skipping", name)
+            continue
+
+        try:
+            _validate_config_session(name, data)
+        except ValueError as exc:
+            log.warning("Invalid config session '%s': %s", name, exc)
+            continue
+
+        validated[name] = data
+
+    return validated
+
+
+def _validate_config_session(name: str, data: dict[str, Any]) -> None:
+    """Validate a single config session entry.
+
+    Args:
+        name: Session name (YAML key).
+        data: Session configuration dict.
+
+    Raises:
+        ValueError: If any field is invalid.
+    """
+    validate_session_name(name)
+
+    backend = data.get("backend", "tmux")
+    if backend not in _VALID_BACKENDS:
+        raise ValueError(f"Invalid backend '{backend}'")
+
+    image = data.get("image")
+    if image is not None:
+        validate_image_name(image)
+
+    command = data.get("command")
+    if command is not None:
+        validate_command(command)
+
+    env = data.get("env")
+    if env is not None:
+        if not isinstance(env, dict):
+            raise ValueError("env must be a dict")
+        validate_env(env)
+
+    volumes = data.get("volumes")
+    if volumes is not None:
+        if not isinstance(volumes, list):
+            raise ValueError("volumes must be a list")
+        validate_volumes(volumes)
+
+    ports = data.get("ports")
+    if ports is not None:
+        if not isinstance(ports, list):
+            raise ValueError("ports must be a list")
+        validate_ports(ports)
+
+
+def _collect_sessions(backend: str | None) -> list[SessionStatus]:
+    """Collect sessions from runtime backends and config definitions.
+
+    Merges runtime sessions with config-defined sessions. Config sessions
+    that are not currently running appear with state DEFINED.
+
+    Args:
+        backend: Backend to query, or None for all.
+
+    Returns:
+        List of SessionStatus from queried backends plus config-defined sessions.
+    """
+    sessions: list[SessionStatus] = []
+
+    # Collect from tmux
+    if backend is None or backend == "tmux":
+        try:
+            tmux = TmuxRunner()
+            sessions.extend(tmux.list_sessions())
+        except BackendNotFoundError:
+            pass
+
+    # Collect from container
+    if backend is None or backend == "container":
+        try:
+            container = ContainerRunner()
+            sessions.extend(container.list_sessions())
+        except BackendNotFoundError:
+            pass
+
+    # Merge config-defined sessions
+    runtime_names: set[str] = {s.name for s in sessions}
+    config_sessions = _load_config_sessions()
+
+    for name, data in config_sessions.items():
+        if name in runtime_names:
+            continue
+
+        session_backend = data.get("backend", "tmux")
+
+        # Apply backend filter to config sessions too
+        if backend is not None and session_backend != backend:
+            continue
+
+        backend_type = BackendType(session_backend)
+        sessions.append(
+            SessionStatus(
+                name=name,
+                state=SessionState.DEFINED,
+                backend=backend_type,
+                image=data.get("image"),
+            ),
+        )
+
+    return sessions
+
+
+def list_sessions(
+    backend: str | None = BACKEND_OPTION,
+    json: bool = JSON_OPTION,
+) -> None:
+    """List all sessions.
+
+    Shows all tmux sessions and containers managed by the ops module,
+    plus config-defined sessions that have not been started yet.
+    Can be filtered by backend type.
+
+    Examples:
+        kstlib ops list
+        kstlib ops list --backend tmux
+        kstlib ops list --backend container --json
+    """
+    sessions = _collect_sessions(backend)
+
+    if json:
+        # JSON output
+        data = [
+            {
+                "name": s.name,
+                "state": s.state.value,
+                "backend": s.backend.value,
+                "pid": s.pid,
+                "image": s.image,
+            }
+            for s in sessions
+        ]
+        console.print(json_lib.dumps(data, indent=2))
+        return
+
+    if not sessions:
+        console.print("[dim]No sessions found.[/]")
+        return
+
+    # Rich table output
+    table = Table(title="Sessions")
+    table.add_column("Name", style="cyan")
+    table.add_column("State", style="white")
+    table.add_column("Backend", style="blue")
+    table.add_column("PID", style="dim")
+    table.add_column("Image", style="dim")
+
+    for session in sessions:
+        state_style = _STATE_STYLES.get(session.state.value, "yellow")
+        table.add_row(
+            session.name,
+            f"[{state_style}]{session.state.value}[/]",
+            session.backend.value,
+            str(session.pid) if session.pid else "-",
+            session.image or "-",
+        )
+
+    console.print(table)
+
+
+__all__ = ["list_sessions"]

kstlib/cli/commands/ops/logs.py

@@ -0,0 +1,49 @@
+"""Show session logs."""
+
+from __future__ import annotations
+
+from kstlib.cli.common import console, exit_error
+from kstlib.ops.exceptions import OpsError, SessionNotFoundError
+
+from .common import (
+    BACKEND_OPTION,
+    LINES_OPTION,
+    SESSION_ARGUMENT,
+    get_session_manager,
+)
+
+
+def logs(
+    name: str = SESSION_ARGUMENT,
+    backend: str | None = BACKEND_OPTION,
+    lines: int = LINES_OPTION,
+) -> None:
+    """Show logs from a session.
+
+    Retrieves and displays recent output from a tmux session or container.
+    ANSI color codes are preserved in the output.
+
+    Examples:
+        kstlib ops logs dev
+        kstlib ops logs prod --lines 50
+    """
+    try:
+        manager = get_session_manager(name, backend=backend)
+
+        if not manager.exists():
+            exit_error(f"Session '{name}' not found.")
+
+        log_content = manager.logs(lines=lines)
+
+        if log_content.strip():
+            console.print(log_content, markup=False)
+        else:
+            console.print(f"[dim]No logs available for session '{name}'.[/]")
+
+    except SessionNotFoundError:
+        exit_error(f"Session '{name}' not found.")
+    except OpsError as e:
+        exit_error(str(e))
+
+
+__all__ = ["logs"]

kstlib/cli/commands/ops/start.py

@@ -0,0 +1,98 @@
+"""Start a session."""
+
+from __future__ import annotations
+
+from kstlib.cli.common import (
+    CommandResult,
+    CommandStatus,
+    emit_result,
+    exit_error,
+)
+from kstlib.ops.exceptions import OpsError, SessionExistsError
+
+from .common import (
+    BACKEND_OPTION,
+    COMMAND_OPTION,
+    ENV_OPTION,
+    IMAGE_OPTION,
+    PORT_OPTION,
+    QUIET_OPTION,
+    SESSION_ARGUMENT,
+    VOLUME_OPTION,
+    WORKDIR_OPTION,
+    get_session_manager,
+)
+
+
+def start(  # noqa: PLR0913
+    name: str = SESSION_ARGUMENT,
+    backend: str | None = BACKEND_OPTION,
+    command: str | None = COMMAND_OPTION,
+    image: str | None = IMAGE_OPTION,
+    quiet: bool = QUIET_OPTION,
+    working_dir: str | None = WORKDIR_OPTION,
+    env: list[str] | None = ENV_OPTION,
+    volume: list[str] | None = VOLUME_OPTION,
+    port: list[str] | None = PORT_OPTION,
+) -> None:
+    """Start a new session.
+
+    Creates and starts a new tmux session or container with the specified
+    configuration. If the session is defined in kstlib.conf.yml, those
+    settings will be used as defaults.
+
+    Examples:
+        kstlib ops start dev --backend tmux --command "python app.py"
+        kstlib ops start prod --backend container --image app:latest
+        kstlib ops start astro  # Uses config from kstlib.conf.yml
+    """
+    # Parse environment variables
+    env_dict: dict[str, str] = {}
+    if env:
+        for item in env:
+            if "=" in item:
+                key, value = item.split("=", 1)
+                env_dict[key] = value
+            else:
+                exit_error(f"Invalid environment variable format: {item}")
+
+    try:
+        manager = get_session_manager(
+            name,
+            backend=backend,
+            image=image,
+            command=command,
+        )
+
+        # Build kwargs for start
+        kwargs: dict[str, str | list[str] | dict[str, str] | None] = {}
+        if working_dir:
+            kwargs["working_dir"] = working_dir
+        if env_dict:
+            kwargs["env"] = env_dict
+        if volume:
+            kwargs["volumes"] = list(volume)
+        if port:
+            kwargs["ports"] = list(port)
+
+        status = manager.start(command, **kwargs)
+
+        result = CommandResult(
+            status=CommandStatus.OK,
+            message=f"Session '{name}' started ({status.backend.value} backend).",
+            payload={
+                "name": status.name,
+                "state": status.state.value,
+                "backend": status.backend.value,
+                "pid": status.pid,
+            },
+        )
+        emit_result(result, quiet)
+
+    except SessionExistsError:
+        exit_error(f"Session '{name}' already exists. Use 'kstlib ops stop {name}' first.")
+    except OpsError as e:
+        exit_error(str(e))
+
+
+__all__ = ["start"]

kstlib/cli/commands/ops/status.py

@@ -0,0 +1,138 @@
+"""Show session status."""
+
+from __future__ import annotations
+
+import json as json_lib
+
+from rich.table import Table
+
+from kstlib.cli.common import console, exit_error
+from kstlib.ops import SessionManager
+from kstlib.ops.exceptions import OpsError, SessionNotFoundError
+from kstlib.ops.models import SessionState, SessionStatus
+from kstlib.utils.formatting import format_timestamp
+
+from .common import (
+    BACKEND_OPTION,
+    JSON_OPTION,
+    QUIET_OPTION,
+    SESSION_ARGUMENT,
+    get_session_manager,
+)
+
+
+def _config_fallback_status(name: str) -> SessionStatus | None:
+    """Try to build a DEFINED status from config for a non-running session.
+
+    Args:
+        name: Session name to look up in config.
+
+    Returns:
+        SessionStatus with DEFINED state, or None if not in config.
+    """
+    try:
+        manager = SessionManager.from_config(name)
+    except OpsError:
+        return None
+
+    return SessionStatus(
+        name=name,
+        state=SessionState.DEFINED,
+        backend=manager.config.backend,
+        image=manager.config.image,
+    )
+
+
+def _format_created_at(created_at: str | None) -> str | None:
+    """Format created_at value for display.
+
+    Args:
+        created_at: Raw created_at value (epoch string or ISO format).
+
+    Returns:
+        Formatted datetime string, or None if no value.
+    """
+    if not created_at:
+        return None
+    try:
+        float(created_at)
+        return format_timestamp(created_at)
+    except ValueError:
+        # Already formatted (ISO from Docker), keep as-is
+        return created_at
+
+
+def status(
+    name: str = SESSION_ARGUMENT,
+    backend: str | None = BACKEND_OPTION,
+    quiet: bool = QUIET_OPTION,
+    json: bool = JSON_OPTION,
+) -> None:
+    """Show status of a session.
+
+    Displays detailed information about a session including its state,
+    PID, backend type, and other relevant details.
+
+    Examples:
+        kstlib ops status dev
+        kstlib ops status prod --json
+    """
+    try:
+        manager = get_session_manager(name, backend=backend)
+
+        if not manager.exists():
+            # Try config fallback for defined-but-not-started sessions
+            session_status = _config_fallback_status(name)
+            if session_status is None:
+                exit_error(f"Session '{name}' not found.")
+        else:
+            session_status = manager.status()
+
+        if json:
+            # JSON output
+            data = {
+                "name": session_status.name,
+                "state": session_status.state.value,
+                "backend": session_status.backend.value,
+                "pid": session_status.pid,
+                "created_at": session_status.created_at,
+                "window_count": session_status.window_count,
+                "image": session_status.image,
+                "exit_code": session_status.exit_code,
+            }
+            console.print(json_lib.dumps(data, indent=2))
+            return
+
+        if quiet:
+            console.print(f"{name}: {session_status.state.value}")
+            return
+
+        # Rich table output
+        table = Table(title=f"Session: {name}")
+        table.add_column("Property", style="cyan")
+        table.add_column("Value", style="white")
+
+        table.add_row("State", session_status.state.value)
+        table.add_row("Backend", session_status.backend.value)
+
+        # Add optional fields as rows (reduces branching complexity)
+        optional_rows = [
+            ("PID", str(session_status.pid) if session_status.pid else None),
+            ("Created", _format_created_at(session_status.created_at)),
+            ("Windows", str(session_status.window_count) if session_status.window_count > 0 else None),
+            ("Image", session_status.image),
+            ("Exit Code", str(session_status.exit_code) if session_status.exit_code is not None else None),
+        ]
+        for label, value in optional_rows:
+            if value:
+                table.add_row(label, value)
+
+        console.print(table)
+
+    except SessionNotFoundError:
+        exit_error(f"Session '{name}' not found.")
+    except OpsError as e:
+        exit_error(str(e))
+
+
+__all__ = ["status"]

kstlib/cli/commands/ops/stop.py

@@ -0,0 +1,60 @@
+"""Stop a session."""
+
+from __future__ import annotations
+
+from kstlib.cli.common import (
+    CommandResult,
+    CommandStatus,
+    emit_result,
+    exit_error,
+)
+from kstlib.ops.exceptions import OpsError, SessionNotFoundError
+
+from .common import (
+    BACKEND_OPTION,
+    FORCE_OPTION,
+    QUIET_OPTION,
+    SESSION_ARGUMENT,
+    TIMEOUT_OPTION,
+    get_session_manager,
+)
+
+
+def stop(
+    name: str = SESSION_ARGUMENT,
+    backend: str | None = BACKEND_OPTION,
+    quiet: bool = QUIET_OPTION,
+    force: bool = FORCE_OPTION,
+    timeout: int = TIMEOUT_OPTION,
+) -> None:
+    """Stop a running session.
+
+    Stops a tmux session or container. By default, attempts a graceful
+    shutdown first, then forces termination if the timeout is exceeded.
+
+    Examples:
+        kstlib ops stop dev
+        kstlib ops stop prod --force
+        kstlib ops stop bot --timeout 30
+    """
+    try:
+        manager = get_session_manager(name, backend=backend)
+
+        if not manager.exists():
+            exit_error(f"Session '{name}' not found.")
+
+        manager.stop(graceful=not force, timeout=timeout)
+
+        result = CommandResult(
+            status=CommandStatus.OK,
+            message=f"Session '{name}' stopped.",
+        )
+        emit_result(result, quiet)
+
+    except SessionNotFoundError:
+        exit_error(f"Session '{name}' not found.")
+    except OpsError as e:
+        exit_error(str(e))
+
+
+__all__ = ["stop"]

kstlib/cli/commands/rapi/__init__.py

@@ -0,0 +1,60 @@
+"""CLI commands for REST API client (rapi)."""
+
+from __future__ import annotations
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from .call import call
+from .list import list_endpoints
+from .show import show_endpoint
+
+# Known subcommands that should not be treated as endpoints
+_SUBCOMMANDS = {"list", "call", "show", "--help", "-h", "help"}
+
+
+class RapiGroup(TyperGroup):
+    """Custom Typer Group that treats unknown commands as endpoint calls."""
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        """Override command resolution to treat unknown commands as endpoints."""
+        # Try normal resolution first
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            # If command not found and looks like an endpoint, redirect to call
+            if args and args[0] not in _SUBCOMMANDS and "." in args[0]:
+                # Treat as implicit call: prepend "call" to args
+                return super().resolve_command(ctx, ["call", *args])
+            raise
+
+
+rapi_app = typer.Typer(
+    help="Config-driven REST API client.",
+    cls=RapiGroup,
+)
+
+# Register explicit commands
+rapi_app.command(name="list")(list_endpoints)
+rapi_app.command(name="show")(show_endpoint)
+# Keep "call" for explicit usage (shown in help)
+rapi_app.command(name="call", hidden=False)(call)
+
+
+def register_cli(app: typer.Typer) -> None:
+    """Register the rapi sub-commands on the root Typer app."""
+    app.add_typer(rapi_app, name="rapi")
+
+
+__all__ = [
+    "call",
+    "list_endpoints",
+    "rapi_app",
+    "register_cli",
+    "show_endpoint",
+]