lcloud-cli 0.1.0__py3-none-any.whl

lambda_cloud/cli/state.py

@@ -0,0 +1,66 @@
+"""Runtime state shared by all commands (built once per invocation)."""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+import typer
+from rich.console import RenderableType
+
+from ..api import LambdaCloudClient
+from ..core.config import resolve_api_key
+from .ui.console import OutputFormat, emit, failure
+
+
+class State:
+    """Holds global CLI options and lazily builds the API client."""
+
+    def __init__(self, api_key: str | None, output: OutputFormat, verbose: bool) -> None:
+        self.api_key = api_key
+        self.output = output
+        self.verbose = verbose
+        self.history: dict[str, Any] = {}
+        self._client: LambdaCloudClient | None = None
+
+    @property
+    def client(self) -> LambdaCloudClient:
+        """API client, created on first use (so --help works without a key)."""
+        if self._client is None:
+            self._client = LambdaCloudClient(resolve_api_key(self.api_key))
+        return self._client
+
+    def close(self) -> None:
+        """Release any resource allocated lazily (HTTP connections)."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+class CommandBase:
+    """Per-command helper wrapping the global :class:`State`.
+
+    Attributes:
+        state: The global state built in the root callback.
+        command: Name of the invoked command.
+        output: The resolved output format.
+    """
+
+    def __init__(self, ctx: typer.Context, *, needs_client: bool = True) -> None:
+        state: State = ctx.obj
+        if needs_client:
+            _ = state.client  # resolve early → clear failure on missing key
+        self.state = state
+        self.command = ctx.info_name or ""
+        self.output = state.output
+
+    @property
+    def client(self) -> LambdaCloudClient:
+        return self.state.client
+
+    def emit(self, data: Any, renderable: RenderableType | None = None) -> None:
+        """Print ``data`` according to the configured output format."""
+        emit(data, self.output, renderable)
+
+    def failure(self, action: str, message: str) -> NoReturn:
+        """Report a failed action and exit."""
+        failure(action, message)

lambda_cloud/cli/ui/__init__.py

@@ -0,0 +1,13 @@
+"""User interface layer: console, formatters, tables, history."""
+
+from .console import OutputFormat, confirm_or_exit, console, emit, err_console, failure, success
+
+__all__ = [
+    "OutputFormat",
+    "console",
+    "confirm_or_exit",
+    "emit",
+    "err_console",
+    "failure",
+    "success",
+]

lambda_cloud/cli/ui/console.py

@@ -0,0 +1,94 @@
+"""Console output helpers: rich tables for humans, JSON for scripts."""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any, NoReturn
+
+import typer
+from pydantic import BaseModel
+from rich.console import Console, RenderableType
+
+from ...core.errors import APIError, LambdaCloudError
+
+console = Console()
+err_console = Console(stderr=True, style="bold red")
+
+
+class OutputFormat(str, Enum):
+    TABLE = "table"
+    JSON = "json"
+
+
+def _normalize(data: Any) -> Any:
+    """Convert pydantic models and containers to plain JSON-able data."""
+    if isinstance(data, BaseModel):
+        return data.model_dump(mode="json")
+    if isinstance(data, list):
+        return [_normalize(item) for item in data]
+    if isinstance(data, dict):
+        return {key: _normalize(value) for key, value in data.items()}
+    return data
+
+
+def emit(
+    data: Any,
+    output_format: OutputFormat,
+    renderable: RenderableType | None = None,
+) -> None:
+    """Print ``data`` as JSON, or print ``renderable`` in table mode."""
+    if output_format is OutputFormat.JSON:
+        console.print(
+            json.dumps(_normalize(data), indent=2, ensure_ascii=False),
+            highlight=False,
+            soft_wrap=True,
+        )
+    elif renderable is not None:
+        console.print(renderable)
+
+
+def success(message: str) -> None:
+    console.print(f"[green]✓[/green] {message}")
+
+
+def info(message: str) -> None:
+    console.print(message)
+
+
+def warn(message: str) -> None:
+    console.print(f"[yellow]![/yellow] {message}")
+
+
+def failure(header: str, message: str) -> NoReturn:
+    """Print a failed action's details and exit with a non-zero code."""
+    err_console.print(f"Action failed: {header}")
+    err_console.print(f"Error: {message}")
+    raise typer.Exit(code=1)
+
+
+def confirm_or_exit(message: str, assume_yes: bool) -> None:
+    """Ask for confirmation; abort the command when declined."""
+    if assume_yes:
+        return
+    if not typer.confirm(message):
+        console.print("Aborted.")
+        raise typer.Exit(code=0)
+
+
+def exit_with_error(exc: Exception) -> NoReturn:
+    """Render an error nicely on stderr and exit with a non-zero code."""
+    if isinstance(exc, APIError):
+        err_console.print(f"Error: {exc.message} [dim]({exc.code}, HTTP {exc.status_code})[/dim]")
+        if exc.suggestion:
+            err_console.print(f"Suggestion: {exc.suggestion}", style="yellow")
+        if exc.status_code == 401:
+            err_console.print(
+                "Hint: check your API key with `lambda-cloud login`.",
+                style="dim",
+            )
+    elif isinstance(exc, LambdaCloudError):
+        err_console.print(f"Error: {exc}")
+    else:  # unexpected bug: keep the message but stay polite
+        err_console.print(f"Unexpected error: {exc}")
+    raise typer.Exit(code=1)

lambda_cloud/cli/ui/history.py

@@ -0,0 +1,62 @@
+"""Lightweight result history stored under the config directory.
+
+Best-effort: history write failures never break a command.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from ...core.config import config_dir
+
+_HISTORY_FILE = "history.json"
+_MAX_ENTRIES = 25
+
+
+def _history_path():
+    return config_dir() / _HISTORY_FILE
+
+
+def _default_entry(kind: str, data: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "recorded_at": datetime.now(timezone.utc).isoformat(),
+        "kind": kind,
+        "data": data,
+        "result_preview": str(data)[:80],
+    }
+
+
+def record_result(kind: str, data: dict[str, Any]) -> None:
+    """Append a result entry to the local history file (best-effort)."""
+    path = _history_path()
+    try:
+        history = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else []
+    except (OSError, ValueError):
+        history = []
+    history.append(_default_entry(kind, data))
+    history = history[-_MAX_ENTRIES:]
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(history, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+
+def last_result(kind: str) -> dict[str, Any] | None:
+    """Return the most recent recorded result for ``kind``, if any."""
+    path = _history_path()
+    if not path.is_file():
+        return None
+    try:
+        history = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    for entry in reversed(history):
+        if entry.get("kind") == kind:
+            return entry
+    return None

lambda_cloud/cli/ui/tables.py

@@ -0,0 +1,258 @@
+"""Rich table renderers for every API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from rich.table import Table
+
+from ...mngr.models import (
+    AuditEvent,
+    Filesystem,
+    FirewallRule,
+    FirewallRuleset,
+    Image,
+    Instance,
+    InstanceStatus,
+    InstanceTypeOffer,
+    Region,
+    SSHKey,
+)
+
+_STATUS_STYLES = {
+    InstanceStatus.ACTIVE: "green",
+    InstanceStatus.BOOTING: "cyan",
+    InstanceStatus.UNHEALTHY: "yellow",
+    InstanceStatus.TERMINATING: "magenta",
+    InstanceStatus.TERMINATED: "red",
+    InstanceStatus.PREEMPTED: "red",
+}
+
+
+def _styled_status(status: InstanceStatus) -> str:
+    style = _STATUS_STYLES.get(status, "default")
+    return f"[{style}]{status.value}[/{style}]"
+
+
+def _short(value: str | None, length: int = 40) -> str:
+    if not value:
+        return "-"
+    return value if len(value) <= length else value[: length - 1] + "…"
+
+
+def _fmt_dt(value: datetime | str | None) -> str:
+    if value is None:
+        return "-"
+    if isinstance(value, str):
+        return value[:19].replace("T", " ")
+    return value.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _fmt_bytes(value: int | None) -> str:
+    if value is None:
+        return "-"
+    size = float(value)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if size < 1024 or unit == "TiB":
+            return f"{size:.1f} {unit}" if unit != "B" else f"{int(size)} B"
+        size /= 1024
+    return "-"
+
+
+def instance_detail_table(instance: Instance) -> Table:
+    """Key/value detail view for a single instance."""
+    table = Table(title=f"Instance {instance.id}", show_header=False)
+    table.add_column("FIELD", style="bold cyan")
+    table.add_column("VALUE")
+
+    rows: list[tuple[str, str]] = [
+        ("ID", instance.id),
+        ("Name", instance.name or "-"),
+        ("Status", _styled_status(instance.status)),
+        ("Type", instance.instance_type.name if instance.instance_type else "-"),
+        ("Region", instance.region.name if instance.region else "-"),
+        ("IP", instance.ip or "-"),
+        ("Private IP", instance.private_ip or "-"),
+        ("Hostname", instance.hostname or "-"),
+        ("SSH keys", ", ".join(instance.ssh_key_names) or "-"),
+        ("Filesystems", ", ".join(instance.file_system_names) or "-"),
+        ("Jupyter", instance.jupyter_url or "-"),
+        (
+            "Tags",
+            ", ".join(f"{tag.key}={tag.value}" for tag in instance.tags or []) or "-",
+        ),
+    ]
+    if instance.instance_type:
+        rows.append(
+            ("Price/hour", f"${instance.instance_type.price_per_hour:.2f}"),
+        )
+    for field, value in rows:
+        table.add_row(field, value)
+    return table
+
+
+def instances_table(instances: list[Instance]) -> Table:
+    table = Table(title="Instances")
+    table.add_column("ID", style="cyan")
+    table.add_column("NAME")
+    table.add_column("TYPE")
+    table.add_column("REGION")
+    table.add_column("STATUS")
+    table.add_column("IP")
+    table.add_column("PRICE/H", justify="right")
+    for instance in instances:
+        price = f"${instance.instance_type.price_per_hour:.2f}" if instance.instance_type else "-"
+        table.add_row(
+            instance.id,
+            instance.name or "-",
+            instance.instance_type.name if instance.instance_type else "-",
+            instance.region.name if instance.region else "-",
+            _styled_status(instance.status),
+            instance.ip or "-",
+            price,
+        )
+    return table
+
+
+def instance_types_table(offers: list[InstanceTypeOffer]) -> Table:
+    table = Table(title="Instance types")
+    table.add_column("NAME", style="cyan")
+    table.add_column("DESCRIPTION")
+    table.add_column("GPUS", justify="right")
+    table.add_column("VCPUS", justify="right")
+    table.add_column("MEM (GiB)", justify="right")
+    table.add_column("STORAGE (GiB)", justify="right")
+    table.add_column("PRICE/H", justify="right")
+    table.add_column("REGIONS AVAILABLE")
+    for offer in offers:
+        instance_type = offer.instance_type
+        regions = ", ".join(r.name for r in offer.regions_with_capacity_available) or "-"
+        table.add_row(
+            instance_type.name,
+            _short(instance_type.description, 32),
+            str(instance_type.specs.gpus),
+            str(instance_type.specs.vcpus),
+            str(instance_type.specs.memory_gib),
+            str(instance_type.specs.storage_gib),
+            f"${instance_type.price_per_hour:.2f}",
+            regions,
+        )
+    return table
+
+
+def ssh_keys_table(keys: list[SSHKey]) -> Table:
+    table = Table(title="SSH keys")
+    table.add_column("ID", style="cyan")
+    table.add_column("NAME")
+    table.add_column("PUBLIC KEY")
+    for key in keys:
+        table.add_row(key.id, key.name, _short(key.public_key, 60))
+    return table
+
+
+def filesystems_table(filesystems: list[Filesystem]) -> Table:
+    table = Table(title="Filesystems")
+    table.add_column("ID", style="cyan")
+    table.add_column("NAME")
+    table.add_column("REGION")
+    table.add_column("MOUNT POINT")
+    table.add_column("USED", justify="right")
+    table.add_column("IN USE")
+    table.add_column("CREATED")
+    for filesystem in filesystems:
+        table.add_row(
+            filesystem.id,
+            filesystem.name,
+            filesystem.region.name if filesystem.region else "-",
+            filesystem.mount_point,
+            _fmt_bytes(filesystem.bytes_used),
+            "yes" if filesystem.is_in_use else "no",
+            _fmt_dt(filesystem.created),
+        )
+    return table
+
+
+def images_table(images: list[Image]) -> Table:
+    table = Table(title="Images")
+    table.add_column("ID", style="cyan")
+    table.add_column("NAME")
+    table.add_column("FAMILY")
+    table.add_column("VERSION")
+    table.add_column("ARCH")
+    table.add_column("REGION")
+    table.add_column("UPDATED")
+    for image in images:
+        table.add_row(
+            image.id,
+            _short(image.name, 40),
+            image.family,
+            image.version,
+            image.architecture,
+            image.region.name if image.region else "-",
+            _fmt_dt(image.updated_time),
+        )
+    return table
+
+
+def regions_table(regions: list[Region]) -> Table:
+    table = Table(title="Regions")
+    table.add_column("NAME", style="cyan")
+    table.add_column("DESCRIPTION")
+    for region in regions:
+        table.add_row(region.name, region.description)
+    return table
+
+
+def firewall_rules_table(rules: list[FirewallRule]) -> Table:
+    table = Table()
+    table.add_column("PROTOCOL", style="cyan")
+    table.add_column("PORTS")
+    table.add_column("SOURCE")
+    table.add_column("DESCRIPTION")
+    for rule in rules:
+        table.add_row(
+            rule.protocol.value, rule.ports_display, rule.source_network, rule.description
+        )
+    return table
+
+
+def rulesets_table(rulesets: list[FirewallRuleset]) -> Table:
+    table = Table(title="Firewall rulesets")
+    table.add_column("ID", style="cyan")
+    table.add_column("NAME")
+    table.add_column("REGION")
+    table.add_column("RULES", justify="right")
+    table.add_column("INSTANCES", justify="right")
+    table.add_column("CREATED")
+    for ruleset in rulesets:
+        table.add_row(
+            ruleset.id,
+            ruleset.name,
+            ruleset.region.name if ruleset.region else "-",
+            str(len(ruleset.rules)),
+            str(len(ruleset.instance_ids)),
+            _fmt_dt(ruleset.created),
+        )
+    return table
+
+
+def audit_events_table(events: list[AuditEvent]) -> Table:
+    table = Table(title="Audit events")
+    table.add_column("TIME")
+    table.add_column("ACTION", style="cyan")
+    table.add_column("RESOURCE")
+    table.add_column("ACTOR")
+    table.add_column("SURFACE")
+    table.add_column("RESULT")
+    for event in events:
+        result = event.result.status if event.result else "-"
+        styled = f"[green]{result}[/green]" if result == "success" else result
+        table.add_row(
+            _fmt_dt(event.event_time),
+            event.action,
+            event.resource_name,
+            event.actor_email or event.actor_display_name or "-",
+            event.surface or "-",
+            styled,
+        )
+    return table

lambda_cloud/core/__init__.py

@@ -0,0 +1 @@
+"""Core foundation: shared configuration, error types, standards."""

lambda_cloud/core/config.py

@@ -0,0 +1,125 @@
+"""Local configuration and API key resolution.
+
+Resolution order for the API key:
+
+1. ``--api-key`` command-line flag
+2. ``LAMBDA_API_KEY`` environment variable
+3. Config file written by ``lambda-cloud login``
+
+The config directory is ``$LAMBDA_CLOUD_CONFIG_DIR`` if set, otherwise
+``$XDG_CONFIG_HOME/lambda-cloud`` (defaulting to ``~/.config/lambda-cloud``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ConfigError
+
+API_KEY_ENV_VAR = "LAMBDA_API_KEY"
+CONFIG_DIR_ENV_VAR = "LAMBDA_CLOUD_CONFIG_DIR"
+_CONFIG_FILE_NAME = "config.json"
+
+
+@dataclass(frozen=True)
+class StoredConfig:
+    """Content of the on-disk config file."""
+
+    api_key: str
+
+
+def config_dir() -> Path:
+    """Return the directory where lambda-cloud stores its configuration."""
+    override = os.environ.get(CONFIG_DIR_ENV_VAR)
+    if override:
+        return Path(override).expanduser()
+    xdg_home = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_home).expanduser() if xdg_home else Path.home() / ".config"
+    return base / "lambda-cloud"
+
+
+def config_path() -> Path:
+    """Return the path of the config file."""
+    return config_dir() / _CONFIG_FILE_NAME
+
+
+def load_stored_config() -> StoredConfig | None:
+    """Load the config file, returning ``None`` if it does not exist."""
+    path = config_path()
+    if not path.is_file():
+        return None
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as exc:
+        raise ConfigError(f"Invalid config file {path}: {exc}") from exc
+    api_key = raw.get("api_key")
+    if not api_key:
+        raise ConfigError(f"Config file {path} does not contain an API key.")
+    return StoredConfig(api_key=api_key)
+
+
+def write_secret_file(path: Path, content: str) -> None:
+    """Write ``content`` to ``path`` with owner-only permissions (0600)."""
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(content)
+
+
+def save_api_key(api_key: str) -> Path:
+    """Persist the API key with owner-only permissions (0600)."""
+    directory = config_dir()
+    directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+    path = config_path()
+    write_secret_file(path, json.dumps({"api_key": api_key}) + "\n")
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    return path
+
+
+def delete_stored_config() -> bool:
+    """Delete the config file. Returns ``True`` if a file was removed."""
+    path = config_path()
+    if path.is_file():
+        path.unlink()
+        return True
+    return False
+
+
+def resolve_api_key(flag_value: str | None = None) -> str:
+    """Resolve the API key from flag, environment, then config file."""
+    if flag_value:
+        return flag_value
+    env_value = os.environ.get(API_KEY_ENV_VAR)
+    if env_value:
+        return env_value
+    stored = load_stored_config()
+    if stored:
+        return stored.api_key
+    raise ConfigError(
+        "No API key configured. Run `lambda-cloud login`, "
+        f"set the {API_KEY_ENV_VAR} environment variable, "
+        "or pass --api-key."
+    )
+
+
+def mask_api_key(api_key: str) -> str:
+    """Return a masked representation of an API key, safe to display."""
+    if len(api_key) <= 8:
+        return "…"
+    return f"{api_key[:8]}…"
+
+
+def describe_api_key_source(flag_value: str | None = None) -> tuple[str, str] | None:
+    """Return ``(source, api_key)`` describing where the key comes from."""
+    if flag_value:
+        return "--api-key flag", flag_value
+    env_value = os.environ.get(API_KEY_ENV_VAR)
+    if env_value:
+        return f"{API_KEY_ENV_VAR} environment variable", env_value
+    stored = load_stored_config()
+    if stored:
+        return str(config_path()), stored.api_key
+    return None

lambda_cloud/core/errors.py

@@ -0,0 +1,58 @@
+"""Exceptions raised by lambda-cloud."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class LambdaCloudError(Exception):
+    """Base class for all lambda-cloud errors."""
+
+
+class ConfigError(LambdaCloudError):
+    """Local configuration is missing or invalid."""
+
+
+class APIError(LambdaCloudError):
+    """The Lambda Cloud API returned an error response.
+
+    Attributes:
+        status_code: HTTP status code of the response.
+        code: Machine-readable error code returned by the API
+            (e.g. ``global/invalid-api-key``).
+        message: Human-readable explanation returned by the API.
+        suggestion: Optional hint returned by the API on how to fix the error.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        suggestion: str | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.suggestion = suggestion
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> APIError:
+        """Build an :class:`APIError` from a failed API response."""
+        try:
+            payload = response.json()
+        except ValueError:
+            return cls(
+                response.status_code,
+                "http/unexpected-response",
+                f"HTTP {response.status_code}: non-JSON response body",
+            )
+
+        error = payload.get("error") or {}
+        return cls(
+            status_code=response.status_code,
+            code=error.get("code", "unknown"),
+            message=error.get("message", response.text or "Unknown error"),
+            suggestion=error.get("suggestion"),
+        )

lambda_cloud/mngr/__init__.py

@@ -0,0 +1,5 @@
+"""Manager layer: resource models and state helpers."""
+
+from . import models
+
+__all__ = ["models"]