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

kstlib/cli/commands/auth/whoami.py

@@ -0,0 +1,106 @@
+"""Show user info from OIDC userinfo endpoint."""
+
+# pylint: disable=too-many-locals,too-many-branches
+# Justification: OIDC userinfo renderer with 3 output modes (raw/quiet/verbose) and
+# claim mapping for 12 standard OIDC claims. Variables are mostly display labels and
+# formatted values - extracting helpers would fragment the linear rendering logic.
+
+from __future__ import annotations
+
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from kstlib.cli.common import console, exit_error
+from kstlib.utils.formatting import format_timestamp
+from kstlib.utils.serialization import to_json
+
+from .common import PROVIDER_ARGUMENT, QUIET_OPTION, get_provider, resolve_provider_name
+
+
+def whoami(
+    provider: str | None = PROVIDER_ARGUMENT,
+    quiet: bool = QUIET_OPTION,
+    raw: bool = typer.Option(
+        False,
+        "--raw",
+        help="Output raw JSON response.",
+    ),
+) -> None:
+    """Show user info from the OIDC userinfo endpoint.
+
+    Only works with OIDC providers that expose a userinfo endpoint.
+    """
+    provider_name = resolve_provider_name(provider)
+    auth_provider = get_provider(provider_name)
+
+    # Check if authenticated
+    token = auth_provider.get_token(auto_refresh=True)
+    if token is None:
+        exit_error(f"Not authenticated with {provider_name}.\nRun 'kstlib auth login {provider_name}' first.")
+
+    # Check if provider supports userinfo (OIDC)
+    if not hasattr(auth_provider, "get_userinfo"):
+        exit_error(
+            f"Provider '{provider_name}' does not support userinfo.\nUserinfo is only available for OIDC providers."
+        )
+
+    try:
+        userinfo = auth_provider.get_userinfo()
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        exit_error(f"Failed to fetch userinfo: {e}")
+
+    if raw:
+        print(to_json(userinfo))
+        return
+
+    if quiet:
+        # Show just the essential info
+        name = userinfo.get("name") or userinfo.get("preferred_username") or userinfo.get("sub", "unknown")
+        email = userinfo.get("email", "")
+        if email:
+            console.print(f"{name} <{email}>")
+        else:
+            console.print(name)
+        return
+
+    # Verbose output
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    # Standard OIDC claims in preferred order
+    claim_labels = {
+        "sub": "Subject",
+        "name": "Name",
+        "preferred_username": "Username",
+        "email": "Email",
+        "email_verified": "Email Verified",
+        "given_name": "Given Name",
+        "family_name": "Family Name",
+        "nickname": "Nickname",
+        "picture": "Picture",
+        "locale": "Locale",
+        "zoneinfo": "Timezone",
+        "updated_at": "Updated At",
+    }
+
+    # Show known claims first
+    for claim, label in claim_labels.items():
+        if claim in userinfo:
+            value = userinfo[claim]
+            if isinstance(value, bool):
+                value = "[green]Yes[/]" if value else "[red]No[/]"
+            elif claim == "updated_at" and isinstance(value, int):
+                value = format_timestamp(value)
+            table.add_row(label, str(value))
+
+    # Show any additional claims
+    for claim, value in userinfo.items():
+        if claim not in claim_labels:
+            table.add_row(claim, str(value))
+
+    console.print(Panel(table, title=f"User Info ({provider_name})", style="cyan"))
+
+
+__all__ = ["whoami"]

kstlib/cli/commands/config.py

@@ -0,0 +1,89 @@
+"""CLI commands for configuration management."""
+
+from __future__ import annotations
+
+import pathlib
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+
+from kstlib.cli.common import console
+from kstlib.config.export import (
+    ConfigExportError,
+    ConfigExportOptions,
+    export_configuration,
+)
+
+config_app = typer.Typer(help="Configuration utilities.")
+
+
+@config_app.command("export", help="Export the default configuration file.")
+def export_command(
+    section: Annotated[
+        str | None,
+        typer.Option(
+            "--section",
+            help="Optional dotted path selecting a subtree (e.g. utilities.secure_delete).",
+        ),
+    ] = None,
+    out: Annotated[
+        pathlib.Path | None,
+        typer.Option(
+            "--out",
+            help=(
+                "Destination file or directory. Defaults to ./kstlib.conf.yml when omitted. "
+                "When a directory is provided, the default filename is used."
+            ),
+        ),
+    ] = None,
+    stdout: Annotated[
+        bool,
+        typer.Option(
+            "--stdout",
+            help="Write configuration to stdout instead of a file.",
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Overwrite destination if it already exists.",
+        ),
+    ] = False,
+) -> None:
+    """Export default configuration to a file or stdout."""
+    resolved_out = out.expanduser() if isinstance(out, pathlib.Path) else out
+    options = ConfigExportOptions(section=section, out_path=resolved_out, stdout=stdout, force=force)
+
+    try:
+        result = export_configuration(options)
+    except ConfigExportError as exc:
+        console.print(f"[bold red]{exc}[/bold red]")
+        raise typer.Exit(code=1) from exc
+
+    if stdout:
+        if result.content is None:
+            console.print("[bold red]Export failed: empty content.[/bold red]")
+            raise typer.Exit(code=1)
+        console.print(result.content)
+        return
+
+    if result.destination is None:
+        console.print("[bold red]Export failed: missing destination file.[/bold red]")
+        raise typer.Exit(code=1)
+    console.print(
+        Panel.fit(
+            f"Configuration exported to [bold]{result.destination}[/bold]",
+            title="kstlib config export",
+            border_style="green",
+        )
+    )
+
+
+def register_cli(app: typer.Typer) -> None:
+    """Register configuration subcommands on the main CLI application."""
+    app.add_typer(config_app, name="config")
+
+
+__all__ = ["config_app", "register_cli"]

kstlib/cli/commands/ops/__init__.py

@@ -0,0 +1,39 @@
+"""CLI commands for session management (tmux/container)."""
+
+from __future__ import annotations
+
+import typer
+
+from .attach import attach
+from .list_sessions import list_sessions
+from .logs import logs
+from .start import start
+from .status import status
+from .stop import stop
+
+ops_app = typer.Typer(help="Manage sessions (tmux/container).")
+
+# Register commands on the ops_app
+ops_app.command()(start)
+ops_app.command()(stop)
+ops_app.command()(attach)
+ops_app.command()(status)
+ops_app.command()(logs)
+ops_app.command(name="list")(list_sessions)
+
+
+def register_cli(app: typer.Typer) -> None:
+    """Register the ops sub-commands on the root Typer app."""
+    app.add_typer(ops_app, name="ops")
+
+
+__all__ = [
+    "attach",
+    "list_sessions",
+    "logs",
+    "ops_app",
+    "register_cli",
+    "start",
+    "status",
+    "stop",
+]

kstlib/cli/commands/ops/attach.py

@@ -0,0 +1,49 @@
+"""Attach to a session."""
+
+from __future__ import annotations
+
+from kstlib.cli.common import exit_error
+from kstlib.ops.exceptions import OpsError, SessionNotFoundError
+
+from .common import (
+    BACKEND_OPTION,
+    SESSION_ARGUMENT,
+    get_session_manager,
+)
+
+
+def attach(
+    name: str = SESSION_ARGUMENT,
+    backend: str | None = BACKEND_OPTION,
+) -> None:
+    """Attach to a running session.
+
+    Attaches the current terminal to a tmux session or container.
+    This command replaces the current process.
+
+    For tmux: Use Ctrl+B D to detach.
+    For container: Use Ctrl+P Ctrl+Q to detach.
+
+    Examples:
+        kstlib ops attach dev
+        kstlib ops attach prod --backend container
+    """
+    try:
+        manager = get_session_manager(name, backend=backend)
+
+        if not manager.exists():
+            exit_error(f"Session '{name}' not found.")
+
+        if not manager.is_running():
+            exit_error(f"Session '{name}' is not running.")
+
+        # This replaces the current process and does not return
+        manager.attach()
+
+    except SessionNotFoundError:
+        exit_error(f"Session '{name}' not found.")
+    except OpsError as e:
+        exit_error(str(e))
+
+
+__all__ = ["attach"]

kstlib/cli/commands/ops/common.py

@@ -0,0 +1,269 @@
+"""Shared options and utilities for ops CLI commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from kstlib.cli.common import CommandResult, CommandStatus, exit_error
+from kstlib.ops import SessionManager
+from kstlib.ops.exceptions import OpsError, SessionAmbiguousError
+from kstlib.ops.manager import auto_detect_backend
+
+# ============================================================================
+# Shared Arguments and Options
+# ============================================================================
+
+
+SESSION_ARGUMENT = typer.Argument(
+    ...,
+    help="Session name.",
+    metavar="NAME",
+)
+
+BACKEND_OPTION = typer.Option(
+    None,
+    "--backend",
+    "-b",
+    help="Backend type (tmux or container). If not specified, uses config default.",
+)
+
+IMAGE_OPTION = typer.Option(
+    None,
+    "--image",
+    "-i",
+    help="Container image (container backend only).",
+)
+
+COMMAND_OPTION = typer.Option(
+    None,
+    "--command",
+    "-c",
+    help="Command to run in the session.",
+)
+
+QUIET_OPTION = typer.Option(
+    False,
+    "--quiet",
+    "-q",
+    help="Minimal output.",
+)
+
+JSON_OPTION = typer.Option(
+    False,
+    "--json",
+    help="Output in JSON format.",
+)
+
+WORKDIR_OPTION = typer.Option(
+    None,
+    "--workdir",
+    "-w",
+    help="Working directory for the session.",
+)
+
+ENV_OPTION = typer.Option(
+    None,
+    "--env",
+    "-e",
+    help="Environment variable (KEY=VALUE). Can be repeated.",
+)
+
+VOLUME_OPTION = typer.Option(
+    None,
+    "--volume",
+    "-v",
+    help="Volume mount (host:container). Can be repeated.",
+)
+
+PORT_OPTION = typer.Option(
+    None,
+    "--port",
+    "-p",
+    help="Port mapping (host:container). Can be repeated.",
+)
+
+FORCE_OPTION = typer.Option(
+    False,
+    "--force",
+    "-f",
+    help="Force stop without graceful shutdown.",
+)
+
+TIMEOUT_OPTION = typer.Option(
+    10,
+    "--timeout",
+    "-t",
+    help="Seconds to wait for graceful shutdown.",
+)
+
+LINES_OPTION = typer.Option(
+    100,
+    "--lines",
+    "-n",
+    help="Number of lines to show.",
+)
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def _rebuild_with_overrides(
+    name: str,
+    manager: SessionManager,
+    *,
+    backend: str | None,
+    image: str | None,
+    command: str | None,
+) -> SessionManager:
+    """Rebuild a config-loaded SessionManager with CLI overrides.
+
+    Args:
+        name: Session name.
+        manager: Original config-loaded manager.
+        backend: CLI backend override (or None).
+        image: CLI image override (or None).
+        command: CLI command override (or None).
+
+    Returns:
+        New SessionManager with overrides applied.
+    """
+    cfg = manager.config
+    kwargs: dict[str, Any] = {
+        "backend": backend or cfg.backend.value,
+        "command": command or cfg.command,
+        "working_dir": cfg.working_dir,
+        "env": cfg.env,
+        "image": image or cfg.image,
+        "volumes": list(cfg.volumes),
+        "ports": list(cfg.ports),
+        "runtime": cfg.runtime,
+        "log_volume": cfg.log_volume,
+    }
+    return SessionManager(name, **kwargs)
+
+
+def _try_from_config(
+    name: str,
+    *,
+    backend: str | None,
+    image: str | None,
+    command: str | None,
+) -> SessionManager | None:
+    """Try to load a SessionManager from config, with CLI overrides.
+
+    Args:
+        name: Session name.
+        backend: CLI backend override (or None).
+        image: CLI image override (or None).
+        command: CLI command override (or None).
+
+    Returns:
+        SessionManager if found in config, None otherwise.
+    """
+    try:
+        manager = SessionManager.from_config(name)
+    except OpsError:
+        return None
+    if backend or image or command:
+        return _rebuild_with_overrides(
+            name,
+            manager,
+            backend=backend,
+            image=image,
+            command=command,
+        )
+    return manager
+
+
+def get_session_manager(
+    name: str,
+    *,
+    backend: str | None = None,
+    image: str | None = None,
+    command: str | None = None,
+    from_config: bool = True,
+) -> SessionManager:
+    """Get or create a SessionManager.
+
+    Tries to load session configuration from kstlib.conf.yml first,
+    then applies CLI arguments as overrides. Falls back to auto-detection
+    or explicit options if the session is not defined in config.
+
+    Args:
+        name: Session name.
+        backend: Override backend type.
+        image: Container image (for container backend).
+        command: Command to run.
+        from_config: If True, try to load from config first.
+
+    Returns:
+        SessionManager instance.
+
+    Raises:
+        typer.Exit: On configuration error or ambiguous session.
+    """
+    try:
+        # Try to load from config first (CLI args override config values)
+        if from_config:
+            manager = _try_from_config(name, backend=backend, image=image, command=command)
+            if manager is not None:
+                return manager
+
+        # Auto-detect backend if not specified
+        if backend is None:
+            detected = auto_detect_backend(name)
+            if detected is not None:
+                backend = detected.value
+
+        # Create with explicit options
+        kwargs: dict[str, Any] = {}
+        if backend:
+            kwargs["backend"] = backend
+        if image:
+            kwargs["image"] = image
+        if command:
+            kwargs["command"] = command
+
+        return SessionManager(name, **kwargs)
+    except SessionAmbiguousError as e:
+        exit_error(str(e))
+    except OpsError as e:
+        exit_error(str(e))
+
+
+def handle_ops_error(e: OpsError) -> CommandResult:
+    """Convert an OpsError to a CommandResult.
+
+    Args:
+        e: The OpsError exception.
+
+    Returns:
+        CommandResult with error status.
+    """
+    return CommandResult(
+        status=CommandStatus.ERROR,
+        message=str(e),
+    )
+
+
+__all__ = [
+    "BACKEND_OPTION",
+    "COMMAND_OPTION",
+    "ENV_OPTION",
+    "FORCE_OPTION",
+    "IMAGE_OPTION",
+    "JSON_OPTION",
+    "LINES_OPTION",
+    "PORT_OPTION",
+    "QUIET_OPTION",
+    "SESSION_ARGUMENT",
+    "TIMEOUT_OPTION",
+    "VOLUME_OPTION",
+    "WORKDIR_OPTION",
+    "get_session_manager",
+    "handle_ops_error",
+]