opensandbox-cli 0.1.0__py3-none-any.whl

opensandbox_cli/config.py

@@ -0,0 +1,160 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""CLI configuration loading and management.
+
+Priority (highest to lowest):
+  1. CLI flags
+  2. Environment variables
+  3. Config file (~/.opensandbox/config.toml)
+  4. SDK defaults
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ModuleNotFoundError:  # pragma: no cover
+        tomllib = None  # type: ignore[assignment]
+
+
+DEFAULT_CONFIG_DIR = Path.home() / ".opensandbox"
+DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_DIR / "config.toml"
+
+DEFAULT_CONFIG_TEMPLATE = """\
+# OpenSandbox CLI configuration
+# Priority: CLI flags > environment variables > this file > SDK defaults
+
+[connection]
+# api_key = "your-api-key"
+# domain = "localhost:8080"
+# protocol = "http"
+# request_timeout = 30
+# use_server_proxy = false
+
+[output]
+# color = true
+
+[defaults]
+# image = "python:3.11"
+# timeout = "10m"  # or "none" for manual cleanup mode
+"""
+
+
+def load_config_file(config_path: Path | None = None) -> dict[str, Any]:
+    """Load and parse the TOML config file.
+
+    Returns an empty dict if the file doesn't exist or tomllib is unavailable.
+    """
+    path = config_path or DEFAULT_CONFIG_PATH
+    if not path.exists():
+        return {}
+    if tomllib is None:
+        return {}
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def resolve_config(
+    *,
+    cli_api_key: str | None = None,
+    cli_domain: str | None = None,
+    cli_protocol: str | None = None,
+    cli_timeout: int | None = None,
+    cli_use_server_proxy: bool | None = None,
+    config_path: Path | None = None,
+) -> dict[str, Any]:
+    """Merge config from all sources and return a flat dict.
+
+    Keys returned:
+      - api_key, domain, protocol, request_timeout (int seconds), use_server_proxy (bool)
+      - default_image, default_timeout (str like "10m")
+    """
+    file_cfg = load_config_file(config_path)
+    conn = file_cfg.get("connection", {})
+    output_cfg = file_cfg.get("output", {})
+    defaults = file_cfg.get("defaults", {})
+
+    return {
+        "api_key": cli_api_key
+        or os.getenv("OPEN_SANDBOX_API_KEY")
+        or conn.get("api_key"),
+        "domain": cli_domain
+        or os.getenv("OPEN_SANDBOX_DOMAIN")
+        or conn.get("domain"),
+        "protocol": cli_protocol
+        or os.getenv("OPEN_SANDBOX_PROTOCOL")
+        or conn.get("protocol")
+        or "http",
+        "request_timeout": cli_timeout
+        or _int_or_none(os.getenv("OPEN_SANDBOX_REQUEST_TIMEOUT"))
+        or conn.get("request_timeout")
+        or 30,
+        "use_server_proxy": _coalesce(
+            cli_use_server_proxy,
+            _bool_or_none(os.getenv("OPEN_SANDBOX_USE_SERVER_PROXY")),
+            conn.get("use_server_proxy"),
+            False,
+        ),
+        "color": output_cfg.get("color", True),
+        "default_image": defaults.get("image"),
+        "default_timeout": defaults.get("timeout"),
+    }
+
+
+def init_config_file(config_path: Path | None = None, *, force: bool = False) -> Path:
+    """Create a default config file. Returns the path written."""
+    path = config_path or DEFAULT_CONFIG_PATH
+    if path.exists() and not force:
+        raise FileExistsError(
+            f"Config file already exists at {path}. Use --force to overwrite."
+        )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(DEFAULT_CONFIG_TEMPLATE)
+    return path
+
+
+def _int_or_none(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _bool_or_none(value: str | None) -> bool | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if normalized in ("1", "true", "yes", "on"):
+        return True
+    if normalized in ("0", "false", "no", "off"):
+        return False
+    return None
+
+
+def _coalesce(*values: Any) -> Any:
+    for value in values:
+        if value is not None:
+            return value
+    return None

opensandbox_cli/main.py

@@ -0,0 +1,138 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Root Click group with global options."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from opensandbox_cli import __version__
+from opensandbox_cli.client import ClientContext
+from opensandbox_cli.commands.command import command_group
+from opensandbox_cli.commands.config_cmd import config_group
+from opensandbox_cli.commands.devops import devops_group
+from opensandbox_cli.commands.egress import egress_group
+from opensandbox_cli.commands.file import file_group
+from opensandbox_cli.commands.sandbox import sandbox_group
+from opensandbox_cli.commands.skills import skills_group
+from opensandbox_cli.config import resolve_config
+
+# ---------------------------------------------------------------------------
+# Banner
+# ---------------------------------------------------------------------------
+
+BANNER = r"""[bold cyan]
+   ____                   _____                 _ _
+  / __ \                 / ____|               | | |
+ | |  | |_ __   ___ _ _| (___   __ _ _ __   __| | |__   _____  __
+ | |  | | '_ \ / _ \ '_ \___ \ / _` | '_ \ / _` | '_ \ / _ \ \/ /
+ | |__| | |_) |  __/ | | |___) | (_| | | | | (_| | |_) | (_) >  <
+  \____/| .__/ \___|_| |_|____/ \__,_|_| |_|\__,_|_.__/ \___/_/\_\
+        | |
+        |_|[/]  [dim]v{version}[/]
+"""
+
+
+class BannerGroup(click.Group):
+    """Custom Click group that shows a banner before help text."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        console = Console(stderr=False)
+        console.print(BANNER.format(version=__version__))
+        super().format_help(ctx, formatter)
+
+
+@click.group(cls=BannerGroup, context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("--api-key", envvar="OPEN_SANDBOX_API_KEY", default=None, help="API key for authentication.")
+@click.option("--domain", envvar="OPEN_SANDBOX_DOMAIN", default=None, help="API server domain (e.g. localhost:8080).")
+@click.option("--protocol", type=click.Choice(["http", "https"]), default=None, help="Protocol (http/https).")
+@click.option("--request-timeout", type=int, default=None, help="Request timeout in seconds.")
+@click.option(
+    "--use-server-proxy/--no-use-server-proxy",
+    default=None,
+    help="Route execd and endpoint traffic through the sandbox server proxy.",
+)
+@click.option("--config", "config_path", type=click.Path(exists=False, path_type=Path), default=None, help="Config file path.")
+@click.option("-v", "--verbose", is_flag=True, default=False, help="Enable verbose/debug output.")
+@click.option("--no-color", is_flag=True, default=False, help="Disable colored output.")
+@click.version_option(version=__version__, prog_name="opensandbox")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    api_key: str | None,
+    domain: str | None,
+    protocol: str | None,
+    request_timeout: int | None,
+    use_server_proxy: bool | None,
+    config_path: Path | None,
+    verbose: bool,
+    no_color: bool,
+) -> None:
+    """OpenSandbox CLI — manage sandboxes from your terminal."""
+    if verbose:
+        import logging
+
+        logging.basicConfig(level=logging.DEBUG)
+
+    cli_overrides = {
+        "api_key": api_key,
+        "domain": domain,
+        "protocol": protocol,
+        "request_timeout": request_timeout,
+        "use_server_proxy": use_server_proxy,
+    }
+
+    if ctx.invoked_subcommand == "config":
+        resolved = {
+            "api_key": api_key,
+            "domain": domain,
+            "protocol": protocol or "http",
+            "request_timeout": request_timeout or 30,
+            "use_server_proxy": use_server_proxy if use_server_proxy is not None else False,
+            "color": True,
+            "default_image": None,
+            "default_timeout": None,
+        }
+    else:
+        resolved = resolve_config(
+            cli_api_key=api_key,
+            cli_domain=domain,
+            cli_protocol=protocol,
+            cli_timeout=request_timeout,
+            cli_use_server_proxy=use_server_proxy,
+            config_path=config_path,
+        )
+    resolved["color"] = not no_color and resolved.get("color", True)
+
+    effective_config_path = config_path or Path.home() / ".opensandbox" / "config.toml"
+    ctx.obj = ClientContext(
+        resolved_config=resolved,
+        config_path=effective_config_path,
+        cli_overrides=cli_overrides,
+    )
+    ctx.call_on_close(lambda: ctx.obj.close())
+
+
+# Register sub-command groups
+cli.add_command(sandbox_group)
+cli.add_command(command_group)
+cli.add_command(file_group)
+cli.add_command(egress_group)
+cli.add_command(config_group)
+cli.add_command(devops_group)
+cli.add_command(skills_group)

opensandbox_cli/output.py

@@ -0,0 +1,363 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Output formatting: table (rich), JSON, YAML."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Generator, Sequence
+from contextlib import contextmanager
+from typing import Any
+
+import click
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None  # type: ignore[assignment]
+
+from pydantic import BaseModel
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.status import Status
+from rich.table import Table
+from rich.text import Text
+
+# ---------------------------------------------------------------------------
+# Status badge styling  (sandbox state → color + icon)
+# ---------------------------------------------------------------------------
+
+_STATUS_STYLES: dict[str, tuple[str, str]] = {
+    # state → (rich style, icon)
+    "running": ("bold green", "●"),
+    "ready": ("bold green", "●"),
+    "healthy": ("bold green", "●"),
+    "pending": ("bold yellow", "◐"),
+    "creating": ("bold yellow", "◐"),
+    "starting": ("bold yellow", "◐"),
+    "paused": ("bold blue", "⏸"),
+    "stopped": ("dim", "○"),
+    "terminated": ("dim", "○"),
+    "killed": ("dim", "○"),
+    "error": ("bold red", "✗"),
+    "failed": ("bold red", "✗"),
+    "unhealthy": ("bold red", "✗"),
+    "created": ("bold cyan", "✦"),
+}
+
+# Columns that contain status-like values
+_STATUS_COLUMNS = {"status", "state", "healthy"}
+
+# Columns that should be rendered in a dimmer style (long IDs, timestamps)
+_DIM_COLUMNS = {"created_at", "expires_at", "modified_at", "updated_at"}
+
+# Columns that are primary identifiers
+_ID_COLUMNS = {"id", "sandbox_id", "execution_id", "context_id"}
+
+
+def _style_value(col: str, value: str) -> Text:
+    """Apply contextual styling to a cell value."""
+    lower = value.lower()
+
+    if col in _STATUS_COLUMNS:
+        style, icon = _STATUS_STYLES.get(lower, ("", ""))
+        if style:
+            return Text(f"{icon} {value}", style=style)
+
+    if col in _DIM_COLUMNS:
+        return Text(value, style="dim")
+
+    if col in _ID_COLUMNS:
+        return Text(value, style="bold cyan")
+
+    return Text(value)
+
+
+class OutputFormatter:
+    """Renders data in table / json / yaml format."""
+
+    def __init__(self, fmt: str = "table", *, color: bool = True) -> None:
+        self.fmt = fmt
+        self.color = color
+        self.console = Console(
+            stderr=False, no_color=not color, force_terminal=None
+        )
+        self._err_console = Console(
+            stderr=True, no_color=not color, force_terminal=None
+        )
+
+    # ------------------------------------------------------------------
+    # Status messages with icons
+    # ------------------------------------------------------------------
+
+    def success(self, msg: str) -> None:
+        """Print a success message with ✅ icon."""
+        if self.fmt == "json":
+            self._print_json({"status": "ok", "message": msg})
+            return
+        if self.fmt == "yaml":
+            self._print_yaml({"status": "ok", "message": msg})
+            return
+        if self.color:
+            self.console.print(f"  [bold green]✅ {msg}[/]")
+        else:
+            click.echo(f"OK: {msg}")
+
+    def info(self, msg: str) -> None:
+        """Print an info message with ℹ️  icon."""
+        if self.fmt == "json":
+            self._print_json({"status": "info", "message": msg})
+            return
+        if self.fmt == "yaml":
+            self._print_yaml({"status": "info", "message": msg})
+            return
+        if self.color:
+            self.console.print(f"  [bold blue]ℹ️  {msg}[/]")
+        else:
+            click.echo(f"INFO: {msg}")
+
+    def warning(self, msg: str) -> None:
+        """Print a warning message with ⚠️  icon."""
+        if self.fmt == "json":
+            self._print_json({"status": "warning", "message": msg})
+            return
+        if self.fmt == "yaml":
+            self._print_yaml({"status": "warning", "message": msg})
+            return
+        if self.color:
+            self._err_console.print(f"  [bold yellow]⚠️  {msg}[/]")
+        else:
+            click.echo(f"WARN: {msg}", err=True)
+
+    def error(self, msg: str) -> None:
+        """Print an error message with ❌ icon."""
+        if self.fmt == "json":
+            self._print_json({"status": "error", "message": msg})
+            return
+        if self.fmt == "yaml":
+            self._print_yaml({"status": "error", "message": msg})
+            return
+        if self.color:
+            self._err_console.print(f"  [bold red]❌ {msg}[/]")
+        else:
+            click.echo(f"ERROR: {msg}", err=True)
+
+    def error_panel(self, msg: str, title: str = "Error") -> None:
+        """Print an error with a bold header and message."""
+        if self.color:
+            self._err_console.print()
+            self._err_console.print(f"  [bold red]{title}[/]")
+            self._err_console.print(f"  [dim]{'─' * (len(title) + 2)}[/]")
+            for line in msg.splitlines():
+                self._err_console.print(f"  {line}")
+            self._err_console.print()
+        else:
+            click.echo(f"ERROR [{title}]: {msg}", err=True)
+
+    # ------------------------------------------------------------------
+    # Spinner for long-running operations
+    # ------------------------------------------------------------------
+
+    @contextmanager
+    def spinner(self, msg: str) -> Generator[Status, None, None]:
+        """Context manager that shows a spinner while work is in progress."""
+        if self.color and self.fmt == "table":
+            with self._err_console.status(f"[bold cyan]⏳ {msg}[/]", spinner="dots") as status:
+                yield status
+        else:
+            # No spinner in non-color or non-table mode
+            yield None  # type: ignore[arg-type]
+
+    # ------------------------------------------------------------------
+    # Panel output
+    # ------------------------------------------------------------------
+
+    def panel(self, content: str, *, title: str | None = None, style: str = "cyan") -> None:
+        """Print content inside a styled panel."""
+        if self.color:
+            self.console.print(Panel(
+                content,
+                title=title,
+                title_align="left",
+                border_style=style,
+                box=box.ROUNDED,
+                padding=(0, 1),
+            ))
+        else:
+            if title:
+                click.echo(f"--- {title} ---")
+            click.echo(content)
+
+    def success_panel(self, data: dict[str, Any], *, title: str = "Success") -> None:
+        """Print a success result with a header and indented key-value pairs."""
+        if self.fmt != "table":
+            if self.fmt == "json":
+                self._print_json(data)
+            elif self.fmt == "yaml":
+                self._print_yaml(data)
+            return
+
+        if self.color:
+            self.console.print()
+            self.console.print(f"  [bold green]✓ {title}[/]")
+            self.console.print(f"  [dim]{'─' * (len(title) + 2)}[/]")
+            for k, v in data.items():
+                self.console.print(f"  [bold]{k}:[/] [cyan]{v}[/]")
+            self.console.print()
+        else:
+            click.echo(f"--- {title} ---")
+            for k, v in data.items():
+                click.echo(f"  {k}: {v}")
+
+    # ------------------------------------------------------------------
+    # Public helpers
+    # ------------------------------------------------------------------
+
+    def print_model(self, model: BaseModel, title: str | None = None) -> None:
+        """Print a single Pydantic model as key-value panel or JSON/YAML."""
+        data = _model_to_dict(model)
+        if self.fmt == "json":
+            self._print_json(data)
+        elif self.fmt == "yaml":
+            self._print_yaml(data)
+        else:
+            self._print_kv_table(data, title=title)
+
+    def print_models(
+        self,
+        models: Sequence[BaseModel],
+        columns: list[str],
+        *,
+        title: str | None = None,
+    ) -> None:
+        """Print a list of Pydantic models as a table or JSON/YAML."""
+        rows = [_model_to_dict(m) for m in models]
+        if self.fmt == "json":
+            self._print_json(rows)
+        elif self.fmt == "yaml":
+            self._print_yaml(rows)
+        else:
+            self._print_table(rows, columns, title=title)
+
+    def print_rows(
+        self,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        *,
+        title: str | None = None,
+    ) -> None:
+        """Print pre-processed rows (list of dicts) as a table or JSON/YAML."""
+        if self.fmt == "json":
+            self._print_json(rows)
+        elif self.fmt == "yaml":
+            self._print_yaml(rows)
+        else:
+            self._print_table(rows, columns, title=title)
+
+    def print_dict(self, data: dict[str, Any], title: str | None = None) -> None:
+        """Print a flat dict."""
+        if self.fmt == "json":
+            self._print_json(data)
+        elif self.fmt == "yaml":
+            self._print_yaml(data)
+        else:
+            self._print_kv_table(data, title=title)
+
+    def print_text(self, text: str) -> None:
+        """Print raw text (ignores format)."""
+        click.echo(text)
+
+    # ------------------------------------------------------------------
+    # Internal renderers
+    # ------------------------------------------------------------------
+
+    def _print_json(self, data: Any) -> None:
+        if self.color:
+            self.console.print_json(json.dumps(data, default=str))
+        else:
+            click.echo(json.dumps(data, indent=2, default=str))
+
+    def _print_yaml(self, data: Any) -> None:
+        if yaml is None:
+            click.secho(
+                "PyYAML is not installed. Use --output json instead.", fg="red", err=True
+            )
+            sys.exit(1)
+        click.echo(yaml.dump(data, default_flow_style=False, allow_unicode=True).rstrip())
+
+    def _print_kv_table(self, data: dict[str, Any], *, title: str | None = None) -> None:
+        table = Table(
+            title=title,
+            show_header=True,
+            header_style="bold magenta",
+            title_style="bold cyan",
+            box=box.ROUNDED,
+            border_style="bright_black",
+            padding=(0, 1),
+            show_lines=True,
+        )
+        table.add_column("Key", style="bold cyan", no_wrap=True)
+        table.add_column("Value")
+        for k, v in data.items():
+            val_text = _style_value(k, str(v)) if v is not None else Text("-", style="dim")
+            table.add_row(str(k), val_text)
+        self.console.print(table)
+
+    def _print_table(
+        self,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        *,
+        title: str | None = None,
+    ) -> None:
+        table = Table(
+            title=title,
+            show_header=True,
+            header_style="bold magenta",
+            title_style="bold cyan",
+            box=box.ROUNDED,
+            border_style="bright_black",
+            padding=(0, 1),
+            row_styles=["", "dim"],
+        )
+        for col in columns:
+            style = ""
+            if col in _ID_COLUMNS:
+                style = "bold cyan"
+            elif col in _DIM_COLUMNS:
+                style = "dim"
+            table.add_column(col.upper(), style=style, no_wrap=(col in _ID_COLUMNS))
+
+        for row in rows:
+            cells: list[Text | str] = []
+            for col in columns:
+                val = str(row.get(col, "-"))
+                if col in _STATUS_COLUMNS:
+                    cells.append(_style_value(col, val))
+                else:
+                    cells.append(val)
+            table.add_row(*cells)
+        self.console.print(table)
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+
+def _model_to_dict(model: BaseModel) -> dict[str, Any]:
+    return model.model_dump(mode="json")

opensandbox_cli/py.typed

@@ -0,0 +1 @@
+