orche 0.1.0__tar.gz

orche-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: orche
+Version: 0.1.0
+Summary: A Python orchestrator for Docker Compose stacks
+Author: Pietro Agazzi
+Author-email: pietro.agazzi@prconsulting.eu
+Requires-Python: >=3.10,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Requires-Dist: GitPython (>=3.1.0)
+Requires-Dist: PyYAML (>=6.0)
+Requires-Dist: mypy (>=1.8.0) ; extra == "dev"
+Requires-Dist: pre-commit (>=4.0.0) ; extra == "dev"
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
+Requires-Dist: pytest-mock (>=3.14.0) ; extra == "dev"
+Requires-Dist: pytest-timeout (>=2.3.0) ; extra == "dev"
+Requires-Dist: python-dotenv (>=1.0.0)
+Requires-Dist: python-on-whales (>=0.80.0,<0.81.0)
+Requires-Dist: rich (>=13.0.0)
+Requires-Dist: ruff (>=0.2.0) ; extra == "dev"
+Requires-Dist: types-PyYAML (>=6.0) ; extra == "dev"
+Requires-Dist: types-pygments (>=2.19.0) ; extra == "dev"
+Description-Content-Type: text/markdown
+
+# Whaler
+
+[![CI](https://github.com/pietroagazzi/whaler/actions/workflows/ci.yml/badge.svg)](https://github.com/pietroagazzi/whaler/actions/workflows/ci.yml)
+
+A simple, lightweight Python orchestrator for Docker Compose stacks.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## CLI Reference
+
+The `whaler` command executes your `whaler.py` file with the specified command and services.
+
+```bash
+whaler [command] [services...]
+```
+
+### Commands
+
+- `whaler up [services]` - Start services (executes whaler.py with 'up' command)
+- `whaler build [services]` - Build services (executes whaler.py with 'build' command)
+- `whaler down [services]` - Stop services (executes whaler.py with 'down' command)
+
+### Options
+
+- `-f, --file FILE` - Path to whaler file (default: whaler.py)
+- `-v, --version` - Show version
+- `-h, --help` - Show help
+
+### Examples
+
+```bash
+# Execute whaler.py with up command
+whaler up
+
+# Build specific services
+whaler build api web
+
+# Start specific services
+whaler up postgres redis
+
+# Use custom whaler file
+whaler -f custom-whaler.py up
+```
+
+## Examples
+
+### Basic Usage
+
+```python
+from whaler import Stack
+
+stack = Stack("docker-compose.yml")
+stack.build().up()
+```
+
+### With Project Name
+
+```python
+from whaler import Stack
+
+stack = Stack(
+    compose_file="docker-compose.yml",
+    project_name="myapp",
+    project_path="/path/to/project"
+)
+
+stack.build().up(wait=True)
+```
+
+### Specific Services
+
+```python
+from whaler import Stack
+
+stack = Stack("docker-compose.yml")
+
+# Build specific services
+stack.build(["api", "web"])
+
+# Start specific services
+stack.up(["postgres", "redis"])
+```
+
+### Interactive Script
+
+```python
+from whaler import Stack, tui
+
+project_name = tui.input("Project name: ", default="myproject")
+environment = tui.input("Environment (dev/prod): ", default="dev")
+
+stack = Stack(
+    compose_file=f"docker-compose.{environment}.yml",
+    project_name=project_name
+)
+
+stack.build().up()
+```
+
+## Requirements
+
+- Python >= 3.14
+- Docker and Docker Compose installed on the system
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Type checking:
+
+```bash
+mypy whaler
+```
+
+Linting:
+
+```bash
+ruff check whaler
+```
+

orche-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Whaler
+
+[![CI](https://github.com/pietroagazzi/whaler/actions/workflows/ci.yml/badge.svg)](https://github.com/pietroagazzi/whaler/actions/workflows/ci.yml)
+
+A simple, lightweight Python orchestrator for Docker Compose stacks.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## CLI Reference
+
+The `whaler` command executes your `whaler.py` file with the specified command and services.
+
+```bash
+whaler [command] [services...]
+```
+
+### Commands
+
+- `whaler up [services]` - Start services (executes whaler.py with 'up' command)
+- `whaler build [services]` - Build services (executes whaler.py with 'build' command)
+- `whaler down [services]` - Stop services (executes whaler.py with 'down' command)
+
+### Options
+
+- `-f, --file FILE` - Path to whaler file (default: whaler.py)
+- `-v, --version` - Show version
+- `-h, --help` - Show help
+
+### Examples
+
+```bash
+# Execute whaler.py with up command
+whaler up
+
+# Build specific services
+whaler build api web
+
+# Start specific services
+whaler up postgres redis
+
+# Use custom whaler file
+whaler -f custom-whaler.py up
+```
+
+## Examples
+
+### Basic Usage
+
+```python
+from whaler import Stack
+
+stack = Stack("docker-compose.yml")
+stack.build().up()
+```
+
+### With Project Name
+
+```python
+from whaler import Stack
+
+stack = Stack(
+    compose_file="docker-compose.yml",
+    project_name="myapp",
+    project_path="/path/to/project"
+)
+
+stack.build().up(wait=True)
+```
+
+### Specific Services
+
+```python
+from whaler import Stack
+
+stack = Stack("docker-compose.yml")
+
+# Build specific services
+stack.build(["api", "web"])
+
+# Start specific services
+stack.up(["postgres", "redis"])
+```
+
+### Interactive Script
+
+```python
+from whaler import Stack, tui
+
+project_name = tui.input("Project name: ", default="myproject")
+environment = tui.input("Environment (dev/prod): ", default="dev")
+
+stack = Stack(
+    compose_file=f"docker-compose.{environment}.yml",
+    project_name=project_name
+)
+
+stack.build().up()
+```
+
+## Requirements
+
+- Python >= 3.14
+- Docker and Docker Compose installed on the system
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Type checking:
+
+```bash
+mypy whaler
+```
+
+Linting:
+
+```bash
+ruff check whaler
+```

orche-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "orche"
+version = "0.1.0"
+description = "A Python orchestrator for Docker Compose stacks"
+authors = [
+    {name = "Pietro Agazzi", email = "pietro.agazzi@prconsulting.eu"}
+]
+readme = "README.md"
+requires-python = ">=3.10,<4"
+dependencies = [
+    "python-on-whales>=0.80.0,<0.81.0",
+    "rich>=13.0.0",
+    "python-dotenv>=1.0.0",
+    "PyYAML>=6.0",
+    "GitPython>=3.1.0",
+]
+
+[project.scripts]
+whaler = "whaler.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-timeout>=2.3.0",
+    "pytest-cov>=5.0.0",
+    "pytest-mock>=3.14.0",
+    "mypy>=1.8.0",
+    "ruff>=0.2.0",
+    "types-PyYAML>=6.0",
+    "types-pygments>=2.19.0",
+    "pre-commit>=4.0.0",
+]
+
+[tool.poetry]
+packages = [{include = "whaler"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+# [tool.pytest.ini_options]
+# minversion = "8.0"
+# addopts = "-ra -q --timeout=300"
+# testpaths = [
+#     "tests",
+# ]
+# pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+files = ["whaler", "tests"]

orche-0.1.0/whaler/__init__.py

@@ -0,0 +1,8 @@
+from . import builtin
+from .logger import setup_logger
+from .stack import Stack
+from .tui import TUI, tui
+
+__all__ = ["tui", "TUI", "builtin", "setup_logger", "Stack"]
+
+__version__ = "0.1.0"

orche-0.1.0/whaler/builtin.py

@@ -0,0 +1,78 @@
+"""Built-in utility functions for stack operations."""
+
+from pathlib import Path
+from typing import Any
+
+import git
+import yaml
+
+from .tui import tui
+
+
+def ensure_directory(path: str | Path) -> Path:
+    """Ensure a directory exists, creating it if necessary.
+
+    Args:
+        path: Path to the directory
+
+    Returns:
+        The Path object of the directory
+    """
+    p = Path(path)
+    if not p.exists():
+        p.mkdir(parents=True, exist_ok=True)
+        tui.info(f"Created directory: {p}")
+    return p
+
+
+def git_clone(repo_url: str, dest: str | Path, branch: str | None = None) -> None:
+    """Clone a git repository.
+
+    Args:
+        repo_url: URL of the repository
+        dest: Destination path
+        branch: Optional specific branch/tag to checkout
+    """
+    dest_path = Path(dest)
+    if dest_path.exists() and any(dest_path.iterdir()):
+        tui.warning(
+            f"Destination {dest} already exists and is not empty. Skipping clone."
+        )
+        return
+
+    tui.info(f"Cloning {repo_url} into {dest}...")
+    try:
+        if branch:
+            git.Repo.clone_from(repo_url, dest_path, branch=branch)
+        else:
+            git.Repo.clone_from(repo_url, dest_path)
+        tui.success(f"Repository cloned to {dest}")
+    except git.exc.GitCommandError as e:
+        tui.error(f"Failed to clone repository: {e.stderr}")
+        raise
+
+
+def read_yaml(path: str | Path) -> Any:
+    """Read and parse a YAML file.
+
+    Args:
+        path: Path to the YAML file
+
+    Returns:
+        Parsed YAML content (usually dict or list)
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        yaml.YAMLError: If file is not valid YAML
+    """
+    p = Path(path)
+    if not p.exists():
+        tui.error(f"YAML file not found: {p}")
+        raise FileNotFoundError(f"File not found: {p}")
+
+    try:
+        with open(p, encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        tui.error(f"Error parsing YAML file {p}: {e}")
+        raise

orche-0.1.0/whaler/cli.py

@@ -0,0 +1,162 @@
+"""Command-line interface for Whaler."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Literal, NoReturn
+
+from dotenv import load_dotenv
+from rich.console import Console
+
+from whaler import __version__
+from whaler.logger import setup_logger
+
+CommandName = Literal["up", "build", "down", "stop"]
+
+
+def find_whaler_file() -> Path:
+    """Find whaler.py in current directory.
+
+    Returns:
+        Path to whaler.py file
+
+    Raises:
+        FileNotFoundError: If whaler.py is not found
+    """
+    whaler_file = Path.cwd() / "whaler.py"
+    if not whaler_file.exists():
+        raise FileNotFoundError(
+            f"whaler.py not found in {Path.cwd()}\n"
+            "Make sure you're in a directory with a whaler.py file."
+        )
+    return whaler_file
+
+
+def execute_whaler_file(
+    whaler_file: Path,
+    command: str,
+    services: list[str],
+    verbose: bool = False,
+) -> None:
+    """Execute whaler.py file with given command.
+
+    Args:
+        whaler_file: Path to whaler.py file
+        command: Command to execute (up, build, down, stop)
+        services: List of service names
+        verbose: Enable verbose/debug logging
+    """
+    # Load environment variables from .env file
+    load_dotenv()
+
+    # Setup logging based on verbosity
+    setup_logger(verbose=verbose)
+
+    # Add current working directory to sys.path to allow local imports
+    if os.getcwd() not in sys.path:
+        sys.path.insert(0, os.getcwd())
+
+    # Prepare sys.argv for the whaler.py script
+    # This allows the script to access command and services via sys.argv
+    original_argv = sys.argv.copy()
+    sys.argv = ["whaler.py", command] + services
+
+    try:
+        # Read and execute the whaler.py file
+        with open(whaler_file, encoding="utf-8") as f:
+            code = compile(f.read(), str(whaler_file), "exec")
+            # Execute in global namespace so imports work correctly
+            exec(code, {"__name__": "__main__", "__file__": str(whaler_file)})
+    finally:
+        # Restore original sys.argv
+        sys.argv = original_argv
+
+
+def main() -> NoReturn:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Whaler - Docker Compose Stack Orchestrator",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  whaler up              Execute whaler.py with 'up' command
+  whaler up api web      Execute whaler.py with 'up' command for specific services
+  whaler build           Execute whaler.py with 'build' command
+  whaler down            Execute whaler.py with 'down' command
+  whaler stop            Execute whaler.py with 'stop' command
+  whaler -v up           Execute with verbose/debug logging
+
+The whaler.py file in the current directory will be executed with the
+specified command and services available via sys.argv.
+        """,
+    )
+
+    parser.add_argument(
+        "command",
+        choices=["up", "build", "down", "stop"],
+        help="Command to execute (up, build, down, or stop)",
+    )
+
+    parser.add_argument(
+        "services",
+        nargs="*",
+        default=[],
+        help="Optional service names to operate on",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--file",
+        default="whaler.py",
+        help="Path to whaler file (default: whaler.py)",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose/debug logging",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"whaler {__version__}",
+    )
+
+    args = parser.parse_args()
+
+    error_console = Console(stderr=True)
+
+    # Find whaler.py file
+    try:
+        if args.file == "whaler.py":
+            whaler_file = find_whaler_file()
+        else:
+            whaler_file = Path(args.file)
+            if not whaler_file.exists():
+                error_console.print(f"[red]Error: File not found: {whaler_file}[/red]")
+                sys.exit(1)
+    except FileNotFoundError as e:
+        error_console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+    # Execute whaler.py with command
+    try:
+        execute_whaler_file(
+            whaler_file, args.command, args.services, verbose=args.verbose
+        )
+        sys.exit(0)
+    except KeyboardInterrupt:
+        error_console.print("\n[yellow]Interrupted by user[/yellow]")
+        sys.exit(130)
+    except Exception as e:
+        error_console.print(f"[red]Error executing whaler.py: {e}[/red]")
+        if args.verbose:
+            error_console.print_exception()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

orche-0.1.0/whaler/docker.py

@@ -0,0 +1,130 @@
+"""Docker abstraction layer for docker-compose operations."""
+
+import shutil
+from pathlib import Path
+
+from python_on_whales import DockerClient, DockerException
+
+from .exceptions import DockerComposeError
+
+
+class DockerComposeWrapper:
+    """Abstraction layer for docker-compose operations."""
+
+    def __init__(
+        self,
+        compose_file: Path,
+        project_name: str | None = None,
+        project_path: Path | None = None,
+    ):
+        """Initialize Docker Compose wrapper.
+
+        Args:
+            compose_file: Path to docker-compose.yml file
+            project_name: Optional project name (defaults to directory name)
+            project_path: Optional project path (defaults to compose_file directory)
+        """
+        self.compose_file = Path(compose_file)
+        self.project_name = project_name
+        self.project_path = (
+            Path(project_path) if project_path else self.compose_file.parent
+        )
+
+        if not shutil.which("docker"):
+            raise DockerComposeError(
+                "Docker executable not found. Please ensure Docker is "
+                "installed and in your PATH."
+            )
+
+        self.compose = DockerClient(
+            compose_files=[str(self.compose_file)],
+            compose_project_name=project_name,
+            compose_project_directory=str(self.project_path),
+        ).compose
+
+    def build(self, services: list[str] | None = None) -> None:
+        """Build services defined in compose file.
+
+        Args:
+            services: Optional list of specific services to build
+
+        Raises:
+            DockerComposeError: If build command fails
+        """
+        try:
+            self.compose.build(services=services)
+        except DockerException as e:
+            raise DockerComposeError(f"Build failed: {e}") from e
+        except Exception as e:
+            raise DockerComposeError(f"Unexpected error during build: {e}") from e
+
+    def up(
+        self,
+        services: list[str] | None = None,
+        detach: bool = True,
+        wait: bool = False,
+    ) -> None:
+        """Start services.
+
+        Args:
+            services: Optional list of specific services to start
+            detach: Run containers in background (default: True)
+            wait: Wait for services to be running (default: False)
+
+        Raises:
+            DockerComposeError: If up command fails
+        """
+        try:
+            self.compose.up(
+                services=services,
+                quiet=True,
+                detach=detach,
+                wait=wait,
+            )
+        except DockerException as e:
+            raise DockerComposeError(f"Failed to start services: {e}") from e
+        except Exception as e:
+            raise DockerComposeError(f"Unexpected error during up: {e}") from e
+
+    def down(
+        self,
+        services: list[str] | None = None,
+        remove_orphans: bool = True,
+        volumes: bool = False,
+    ) -> None:
+        """Stop and remove services.
+
+        Args:
+            services: Optional list of specific services to stop and remove
+            remove_orphans: Remove containers for services not in compose file
+            volumes: Remove named volumes declared in the volumes section
+
+        Raises:
+            DockerComposeError: If down command fails
+        """
+        try:
+            if services:
+                self.compose.stop(services)
+                self.compose.rm(services, stop=True, volumes=volumes)
+            else:
+                self.compose.down(remove_orphans=remove_orphans, volumes=volumes)
+        except DockerException as e:
+            raise DockerComposeError(f"Failed to stop services: {e}") from e
+        except Exception as e:
+            raise DockerComposeError(f"Unexpected error during down: {e}") from e
+
+    def stop(self, services: list[str] | None = None) -> None:
+        """Stop services without removing them.
+
+        Args:
+            services: Optional list of specific services to stop
+
+        Raises:
+            DockerComposeError: If stop command fails
+        """
+        try:
+            self.compose.stop(services=services)
+        except DockerException as e:
+            raise DockerComposeError(f"Failed to stop services: {e}") from e
+        except Exception as e:
+            raise DockerComposeError(f"Unexpected error during stop: {e}") from e

orche-0.1.0/whaler/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for the Whaler library."""
+
+
+class WhalerError(Exception):
+    """Base exception for all Whaler errors."""
+
+    pass
+
+
+class DockerComposeError(WhalerError):
+    """Raised when docker-compose command fails."""
+
+    pass

orche-0.1.0/whaler/logger.py

@@ -0,0 +1,79 @@
+"""Logging configuration for Whaler."""
+
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from typing import Literal
+
+from rich.logging import RichHandler
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+def setup_logger(
+    name: str | None = None,
+    verbose: bool = False,
+) -> logging.Logger:
+    """Setup and configure logger.
+
+    Args:
+        name: Logger name (None for root logger)
+        verbose: Whether to enable verbose logging to console
+
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)  # Capture everything at logger level
+
+    # Avoid adding handlers multiple times
+    if logger.handlers:
+        return logger
+
+    # Rotating file handler
+    # Ensure log directory exists
+    log_dir = Path.cwd() / ".whaler" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / "whaler.log"
+
+    file_handler = RotatingFileHandler(
+        log_file,
+        maxBytes=5 * 1024 * 1024,  # 5 MB
+        backupCount=3,
+        encoding="utf-8",
+    )
+    file_handler.setLevel(logging.DEBUG)
+    file_formatter = logging.Formatter(
+        "%(asctime)s | %(name)s | %(levelname)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    file_handler.setFormatter(file_formatter)
+    logger.addHandler(file_handler)
+
+    # Console handler in verbose mode
+    if verbose:
+        console_handler = RichHandler(
+            rich_tracebacks=True,
+            show_time=True,
+            show_path=False,
+            markup=True,
+        )
+        console_handler.setLevel(logging.DEBUG)
+        logger.addHandler(console_handler)
+    else:
+        # If not verbose, don't log to console at all
+        pass
+
+    return logger
+
+
+def get_logger(name: str = "whaler") -> logging.Logger:
+    """Get logger instance.
+
+    Args:
+        name: Logger name
+
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)

orche-0.1.0/whaler/stack.py

@@ -0,0 +1,231 @@
+"""Main Stack class for orchestrating Docker Compose stacks."""
+
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Generic, Literal, TypeVar
+
+from dotenv import load_dotenv
+
+from .docker import DockerComposeWrapper
+from .logger import get_logger
+
+CommandType = Literal["up", "build", "down", "stop"]
+T = TypeVar("T", bound=Callable[[], None])
+
+
+class CommandRegistry(Generic[T]):
+    """Registry for stack commands."""
+
+    def __init__(self) -> None:
+        self._commands: dict[str, Callable[[], None]] = {}
+
+    def register(self, name: str) -> Callable[[T], T]:
+        """Decorator to register a command."""
+
+        def decorator(func: T) -> T:
+            self._commands[name] = func  # type: ignore[assignment]
+            return func
+
+        return decorator
+
+    @property
+    def up(self) -> Callable[[T], T]:
+        """Decorator for the 'up' command."""
+        return self.register("up")
+
+    @property
+    def down(self) -> Callable[[T], T]:
+        """Decorator for the 'down' command."""
+        return self.register("down")
+
+    @property
+    def build(self) -> Callable[[T], T]:
+        """Decorator for the 'build' command."""
+        return self.register("build")
+
+    @property
+    def stop(self) -> Callable[[T], T]:
+        """Decorator for the 'stop' command."""
+        return self.register("stop")
+
+    def get(self, name: str) -> Callable[[], None] | None:
+        """Get a registered command handler."""
+        return self._commands.get(name)
+
+
+class Stack:
+    """Main orchestrator for Docker Compose stacks."""
+
+    def __init__(
+        self,
+        name: str | None = None,
+        path: str | Path = ".",
+        compose_file: str | Path = "docker-compose.yml",
+        load_env: bool = True,
+    ):
+        """Initialize a Docker Compose stack.
+
+        Args:
+            name: Optional project name (defaults to directory name)
+            path: Project root path (defaults to current directory)
+            compose_file: Path to docker-compose.yml file (relative to path)
+            load_env: Whether to load .env file from project path
+
+        Raises:
+            FileNotFoundError: If compose_file does not exist
+        """
+        self.project_path = Path(path).resolve()
+        self.compose_file = self.project_path / compose_file
+        self.project_name = name
+        self.logger = get_logger()
+
+        # Load .env file if it exists
+        if load_env:
+            env_file = self.project_path / ".env"
+            if env_file.exists():
+                load_dotenv(env_file)
+                self.logger.debug(f"Loaded environment from {env_file}")
+
+        if not self.compose_file.exists():
+            raise FileNotFoundError(
+                f"Docker Compose file not found: {self.compose_file}\n"
+                f"Please ensure the file exists or provide the correct path."
+            )
+
+        # Initialize Docker wrapper
+        self._docker = DockerComposeWrapper(
+            compose_file=self.compose_file,
+            project_name=self.project_name,
+            project_path=self.project_path,
+        )
+
+        # Command registry
+        self.commands: CommandRegistry[Callable[[], None]] = CommandRegistry()
+
+        # Runtime context
+        self._active_services: list[str] = []
+
+    def active(self, service: str) -> bool:
+        """Check if a service is active in the current execution context.
+
+        If no specific services were requested (empty list),
+        all services are considered active.
+        """
+        if not self._active_services:
+            return True
+        return service in self._active_services
+
+    def build(self, services: list[str] | None = None) -> "Stack":
+        """Build services in the stack.
+
+        If 'services' is not provided, uses the active services from CLI args.
+
+        Args:
+            services: Optional list of specific services to build
+
+        Returns:
+            Self for method chaining
+        """
+        target_services = services if services is not None else self._active_services
+        if target_services:
+            self.logger.info(f"Building services: {', '.join(target_services)}")
+        else:
+            self.logger.info("Building all services")
+        self._docker.build(services=target_services if target_services else None)
+        return self
+
+    def up(self, services: list[str] | None = None, wait: bool = True) -> "Stack":
+        """Start services in the stack.
+
+        If 'services' is not provided, uses the active services from CLI args.
+
+        Args:
+            services: Optional list of specific services to start
+            wait: If True, wait for services to be running
+
+        Returns:
+            Self for method chaining
+        """
+        target_services = services if services is not None else self._active_services
+        if target_services:
+            self.logger.info(f"Starting services: {', '.join(target_services)}")
+        else:
+            self.logger.info("Starting all services")
+        self._docker.up(
+            services=target_services if target_services else None, wait=wait
+        )
+        if wait:
+            self.logger.info("Services are ready")
+        return self
+
+    def down(self, services: list[str] | None = None, volumes: bool = False) -> "Stack":
+        """Stop and remove services in the stack.
+
+        Args:
+            services: Optional list of specific services to stop and remove
+            volumes: Whether to remove named volumes
+
+        Returns:
+            Self for method chaining
+        """
+        target_services = services if services is not None else self._active_services
+        if target_services:
+            self.logger.info(
+                f"Stopping and removing services: {', '.join(target_services)}"
+            )
+        else:
+            self.logger.info("Stopping and removing all services")
+
+        self._docker.down(
+            services=target_services if target_services else None, volumes=volumes
+        )
+        return self
+
+    def stop(self, services: list[str] | None = None) -> "Stack":
+        """Stop services without removing them.
+
+        Args:
+            services: Optional list of specific services to stop
+
+        Returns:
+            Self for method chaining
+        """
+        target_services = services if services is not None else self._active_services
+        if target_services:
+            self.logger.info(f"Stopping services: {', '.join(target_services)}")
+        else:
+            self.logger.info("Stopping all services")
+        self._docker.stop(services=target_services if target_services else None)
+        return self
+
+    def run(self) -> None:
+        """Parse CLI arguments and execute the requested command."""
+        if len(sys.argv) < 2:
+            self.logger.info(f"Stack: {self.project_name or 'Whaler'}")
+            self.logger.info("\nUsage: python whaler.py <command> [services...]")
+            self.logger.info("\nAvailable commands:")
+            for cmd in self.commands._commands:
+                self.logger.info(f"  - {cmd}")
+            sys.exit(1)
+
+        command_name = sys.argv[1]
+        self._active_services = sys.argv[2:]
+
+        handler = self.commands.get(command_name)
+        if not handler:
+            self.logger.error(f"Unknown command '{command_name}'")
+            self.logger.info(
+                f"Available commands: {', '.join(self.commands._commands.keys())}"
+            )
+            sys.exit(1)
+
+        try:
+            handler()
+        except KeyboardInterrupt:
+            self.logger.warning("\nInterrupted by user")
+            sys.exit(130)
+        except Exception as e:
+            self.logger.error(f"Command failed: {e}")
+            self.logger.debug("Exception details:", exc_info=True)
+            sys.exit(1)

orche-0.1.0/whaler/tui.py

@@ -0,0 +1,141 @@
+"""User interface utilities for interactive input."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+from rich.status import Status
+
+
+class TUI:
+    """Terminal User Interface for whaler CLI.
+
+    Provides colored output, prompts, and interactive input with
+    shared console instances across the application.
+    """
+
+    def __init__(
+        self,
+        console: Console | None = None,
+        error_console: Console | None = None,
+    ) -> None:
+        """Initialize TUI with consoles.
+
+        Args:
+            console: Rich Console for stdout (created if None)
+            error_console: Rich Console for stderr (created if None)
+        """
+        self._console = console or Console()
+        self._error_console = error_console or Console(stderr=True)
+
+    @property
+    def console(self) -> Console:
+        """Get the stdout console instance.
+
+        Returns:
+            Rich Console for stdout
+        """
+        return self._console
+
+    @property
+    def error_console(self) -> Console:
+        """Get the stderr console instance.
+
+        Returns:
+            Rich Console for stderr
+        """
+        return self._error_console
+
+    def status(self, message: str, spinner: str = "dots") -> Status:
+        """Create a status spinner context manager.
+
+        Args:
+            message: Message to display next to spinner
+            spinner: Name of spinner animation to use
+
+        Returns:
+            Rich Status context manager
+        """
+        return self._console.status(message, spinner=spinner)
+
+    def input(self, prompt: str = "", default: str | None = None) -> str:
+        """Interactive input function with optional default.
+
+        Args:
+            prompt: Prompt message to display
+            default: Default value if user enters nothing
+
+        Returns:
+            User input or default value
+        """
+        return cast(
+            str,
+            Prompt.ask(
+                prompt,
+                default=default,
+                show_default=True if default is not None else False,
+            ),
+        )
+
+    def confirm(self, prompt: str, default: bool = False) -> bool:
+        """Ask user for yes/no confirmation.
+
+        Args:
+            prompt: Confirmation prompt message
+            default: Default value if user presses Enter
+
+        Returns:
+            True if user confirms, False otherwise
+        """
+        return cast(bool, Confirm.ask(prompt, default=default))
+
+    def secret_input(self, prompt: str = "Password") -> str:
+        """Get secret input (password) without echoing to screen.
+
+        Args:
+            prompt: Prompt message to display
+
+        Returns:
+            User's secret input
+        """
+        return cast(str, Prompt.ask(prompt, password=True))
+
+    def info(self, message: str) -> None:
+        """Print info message with color.
+
+        Args:
+            message: Message to display
+        """
+        self._console.print(f"[cyan][>][/cyan] {message}")
+
+    def success(self, message: str) -> None:
+        """Print success message with color.
+
+        Args:
+            message: Success message to display
+        """
+        self._console.print(f"\n[green][+][/green] {message}\n")
+
+    def error(self, message: str) -> None:
+        """Print error message with color.
+
+        Args:
+            message: Error message to display
+        """
+        self._error_console.print(f"[red][X] {message}[/red]")
+
+    def warning(self, message: str) -> None:
+        """Print warning message with color.
+
+        Args:
+            message: Warning message to display
+        """
+        self._console.print(f"[yellow][!][/yellow] {message}")
+
+
+# Module-level singleton instance
+tui = TUI()
+
+__all__ = ["TUI", "tui"]