titan-cli 0.7.2__tar.gz → 0.8.0__tar.gz

{titan_cli-0.7.2 → titan_cli-0.8.0}/PKG-INFO

@@ -1,24 +1,24 @@
 Metadata-Version: 2.4
 Name: titan-cli
-Version: 0.7.2
+Version: 0.8.0
 Summary: Modular development tools orchestrator - Streamline your workflows with AI integration and intuitive terminal UI
 License: MIT
 License-File: LICENSE
 Keywords: cli,workflow,orchestrator,automation,devtools,ai
 Author: MasOrange Apps Team
 Author-email: apps-management-stores@masorange.es
-Requires-Python: >=3.10,<4.0.0
+Requires-Python: >=3.11,<4.0.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 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
+Classifier: Programming Language :: Python :: 3.10
 Requires-Dist: anthropic (>=0.75.0,<0.76.0)
 Requires-Dist: google-auth (>=2.43.0,<3.0.0)
 Requires-Dist: google-genai (>=1.58.0,<2.0.0)

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/__init__.py

@@ -0,0 +1 @@
+"""Titan CLI Docker plugin."""

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/__init__.py

@@ -0,0 +1,9 @@
+# plugins/titan-plugin-docker/titan_plugin_docker/clients/__init__.py
+"""
+Docker client module
+"""
+
+from .docker_client import DockerClient
+from ..exceptions import DockerClientError
+
+__all__ = ["DockerClient", "DockerClientError"]

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/docker_client.py

@@ -0,0 +1,106 @@
+# plugins/titan-plugin-docker/titan_plugin_docker/clients/docker_client.py
+"""
+Docker Client Facade
+
+Unified API that delegates to specialized services.
+All methods return ClientResult for consistent error handling.
+"""
+from typing import Callable, Dict, List, Optional
+
+from titan_cli.core.result import ClientResult
+from titan_cli.core.plugins.models import DockerBuildTargetConfig
+
+from .network import DockerNetwork
+from .services import ComposeService, BuildService, PruneService, ContainerService
+from ..models.view import UIComposeStatus, UIBuildResult, UIDiskUsage, UIPruneEntry, UIContainer
+
+
+class DockerClient:
+    """
+    Docker client facade - delegates to specialized services.
+
+    All public methods return ClientResult[T] for consistent error handling.
+    Uses pattern matching (match/case) for result handling in operations and steps.
+
+    Also carries the project's `service_groups` and `build_targets` config
+    (set from `DockerPluginConfig` at plugin initialization), so steps can
+    resolve them via `ctx.docker.service_groups` / `ctx.docker.build_targets`.
+    """
+
+    def __init__(
+        self,
+        project_path: str = ".",
+        compose_file: str = "docker-compose.yml",
+        service_groups: Optional[Dict[str, List[str]]] = None,
+        build_targets: Optional[List[DockerBuildTargetConfig]] = None,
+    ):
+        """
+        Initialize Docker client.
+
+        Args:
+            project_path: Path to the project root (default: current directory)
+            compose_file: Path to the compose file, relative to the project root
+            service_groups: Project-configured named service groups
+            build_targets: Project-configured build targets
+        """
+        self.project_path = project_path
+        self.compose_file = compose_file
+        self.service_groups = service_groups or {}
+        self.build_targets = build_targets or []
+
+        # Initialize network layer
+        self.network = DockerNetwork(project_path=project_path)
+
+        # Initialize services
+        self.compose_service = ComposeService(self.network, compose_file)
+        self.build_service = BuildService(self.network)
+        self.prune_service = PruneService(self.network)
+        self.container_service = ContainerService(self.network)
+
+    # ===== Compose Methods =====
+
+    def compose_up(self, services: Optional[List[str]] = None, detach: bool = True) -> ClientResult[List[str]]:
+        """Start compose services (empty/None starts all services)."""
+        return self.compose_service.up(services=services, detach=detach)
+
+    def compose_down(self, services: Optional[List[str]] = None) -> ClientResult[List[str]]:
+        """Stop compose services (empty/None stops the whole project)."""
+        return self.compose_service.down(services=services)
+
+    def compose_status(self, services: Optional[List[str]] = None) -> ClientResult[UIComposeStatus]:
+        """Get compose project status (empty/None inspects all services)."""
+        return self.compose_service.status(services=services)
+
+    def list_services(self) -> ClientResult[List[str]]:
+        """List every service name defined in the compose file."""
+        return self.compose_service.list_services()
+
+    # ===== Build Methods =====
+
+    def build_target(
+        self,
+        target: DockerBuildTargetConfig,
+        on_output: Optional[Callable[[str], None]] = None,
+    ) -> ClientResult[UIBuildResult]:
+        """Build (and optionally push) a single configured image, optionally streaming build output via `on_output`."""
+        return self.build_service.build_target(target, on_output=on_output)
+
+    # ===== Prune Methods =====
+
+    def disk_usage(self) -> ClientResult[UIDiskUsage]:
+        """Get a host-wide breakdown of Docker's disk usage."""
+        return self.prune_service.disk_usage()
+
+    def prune(self, targets: List[str]) -> ClientResult[List[UIPruneEntry]]:
+        """Prune the given host-wide resource categories (see `PRUNE_COMMANDS` for valid keys)."""
+        return self.prune_service.prune(targets)
+
+    # ===== Container Methods =====
+
+    def list_containers(self) -> ClientResult[List[UIContainer]]:
+        """List every container on the host, running or stopped (not scoped to this project)."""
+        return self.container_service.list_containers()
+
+    def remove_containers(self, container_ids: List[str]) -> ClientResult[List[str]]:
+        """Remove the given (stopped) containers."""
+        return self.container_service.remove_containers(container_ids)

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/network/__init__.py

@@ -0,0 +1,4 @@
+"""Network layer for Docker plugin."""
+from .docker_network import DockerNetwork
+
+__all__ = ["DockerNetwork"]

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/network/docker_network.py

@@ -0,0 +1,201 @@
+# plugins/titan-plugin-docker/titan_plugin_docker/clients/network/docker_network.py
+"""
+Docker Network Client
+
+Low-level Docker CLI command executor.
+Handles subprocess execution and error handling.
+No model conversion - returns raw command output strings.
+"""
+import re
+import subprocess
+import shutil
+import time
+from typing import Callable, List, Optional
+
+from titan_cli.core.logging.config import get_logger
+
+from ...exceptions import DockerError, DockerClientError, DockerCommandError
+
+# ANSI escape sequences (CSI/OSC/single-char) plus stray C0 control chars.
+# Even with --progress=plain, tools invoked inside a build can emit color or
+# cursor codes; a TUI text widget renders those raw, garbling the console.
+_ANSI_RE = re.compile(r"\x1b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])")
+_CTRL_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f]")
+
+
+def _sanitize_output_line(line: str) -> str:
+    """Strip ANSI escapes and control chars so TUI widgets render plain text.
+
+    A lone carriage-return redraw (`foo\rbar`) keeps only the final state,
+    which is what the terminal would have shown.
+    """
+    line = _ANSI_RE.sub("", line)
+    if "\r" in line:
+        line = line.rsplit("\r", 1)[-1]
+    return _CTRL_RE.sub("", line)
+
+
+class DockerNetwork:
+    """
+    Docker network client using the Docker CLI (docker, docker compose, docker buildx).
+
+    Executes commands and handles errors.
+    Returns raw command output (strings) without parsing or model conversion.
+    """
+
+    def __init__(self, project_path: str = "."):
+        """
+        Initialize Docker network client.
+
+        Args:
+            project_path: Path to the project root (default: current directory)
+
+        Raises:
+            DockerClientError: If the Docker CLI is not installed
+        """
+        self.project_path = project_path
+        self._logger = get_logger(__name__)
+        self._check_docker_installed()
+
+    def _check_docker_installed(self) -> None:
+        """
+        Check if the Docker CLI is installed.
+
+        Raises:
+            DockerClientError: If docker is not found
+        """
+        if not shutil.which("docker"):
+            raise DockerClientError("Docker CLI not found. Please install Docker.")
+
+    def run_command(
+        self,
+        args: List[str],
+        check: bool = True,
+        cwd: Optional[str] = None,
+    ) -> str:
+        """
+        Run a docker CLI command and return stdout.
+
+        Args:
+            args: Full command arguments (including 'docker')
+            check: Raise exception on non-zero exit code (default: True)
+            cwd: Optional working directory (overrides project_path)
+
+        Returns:
+            Command stdout as string
+
+        Raises:
+            DockerCommandError: If the command fails
+            DockerClientError: If the docker CLI is not found
+            DockerError: If an unexpected error occurs
+        """
+        subcommand = " ".join(args[1:3]) if len(args) > 1 else "unknown"
+        start = time.time()
+
+        try:
+            result = subprocess.run(
+                args,
+                cwd=cwd or self.project_path,
+                capture_output=True,
+                text=True,
+                check=check,
+            )
+            self._logger.debug(
+                "docker_command_ok",
+                subcommand=subcommand,
+                duration=round(time.time() - start, 3),
+            )
+            return result.stdout.rstrip()
+        except subprocess.CalledProcessError as e:
+            self._logger.debug(
+                "docker_command_failed",
+                subcommand=subcommand,
+                duration=round(time.time() - start, 3),
+                exit_code=e.returncode,
+            )
+            error_msg = e.stderr.strip() if e.stderr else str(e)
+            raise DockerCommandError(f"Docker command failed: {error_msg}") from e
+        except FileNotFoundError:
+            raise DockerClientError("Docker CLI not found. Please install Docker.")
+        except Exception as e:
+            raise DockerError(f"An unexpected error occurred: {e}") from e
+
+    def stream_command(
+        self,
+        args: List[str],
+        on_line: Callable[[str], None],
+        check: bool = True,
+        cwd: Optional[str] = None,
+    ) -> str:
+        """
+        Run a docker CLI command, invoking `on_line` for each line of output
+        as it is produced (stdout and stderr merged, in the order emitted).
+
+        Long-running, chatty commands (e.g. `docker buildx build`) print their
+        progress on stderr, so both streams are merged into a single feed
+        rather than only surfacing output after the process exits.
+
+        Args:
+            args: Full command arguments (including 'docker')
+            on_line: Called with each output line (without trailing newline) as it arrives
+            check: Raise exception on non-zero exit code (default: True)
+            cwd: Optional working directory (overrides project_path)
+
+        Returns:
+            Full command output (stdout+stderr merged) as a single string
+
+        Raises:
+            DockerCommandError: If the command fails
+            DockerClientError: If the docker CLI is not found
+            DockerError: If an unexpected error occurs
+        """
+        subcommand = " ".join(args[1:3]) if len(args) > 1 else "unknown"
+        start = time.time()
+        lines: List[str] = []
+
+        try:
+            process = subprocess.Popen(
+                args,
+                cwd=cwd or self.project_path,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+            )
+            for line in process.stdout:
+                stripped = _sanitize_output_line(line.rstrip("\n"))
+                lines.append(stripped)
+                on_line(stripped)
+            process.wait()
+
+            output = "\n".join(lines)
+            if check and process.returncode != 0:
+                self._logger.debug(
+                    "docker_command_failed",
+                    subcommand=subcommand,
+                    duration=round(time.time() - start, 3),
+                    exit_code=process.returncode,
+                )
+                raise DockerCommandError(f"Docker command failed: {output}")
+
+            self._logger.debug(
+                "docker_command_ok",
+                subcommand=subcommand,
+                duration=round(time.time() - start, 3),
+            )
+            return output
+        except FileNotFoundError:
+            raise DockerClientError("Docker CLI not found. Please install Docker.")
+        except DockerCommandError:
+            raise
+        except Exception as e:
+            raise DockerError(f"An unexpected error occurred: {e}") from e
+
+    def get_project_path(self) -> str:
+        """
+        Get configured project path.
+
+        Returns:
+            Project path string
+        """
+        return self.project_path

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/services/__init__.py

@@ -0,0 +1,12 @@
+"""Services layer for Docker plugin."""
+from .compose_service import ComposeService
+from .build_service import BuildService
+from .prune_service import PruneService
+from .container_service import ContainerService
+
+__all__ = [
+    "ComposeService",
+    "BuildService",
+    "PruneService",
+    "ContainerService",
+]

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/services/build_service.py

@@ -0,0 +1,97 @@
+# plugins/titan-plugin-docker/titan_plugin_docker/clients/services/build_service.py
+"""
+Build Service
+
+Business logic for building (and optionally pushing) Docker images.
+Uses network layer to execute commands, parses to network models, maps to view models.
+"""
+from typing import Callable, Optional
+
+from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
+from titan_cli.core.plugins.models import DockerBuildTargetConfig
+
+from ..network import DockerNetwork
+from ...models.network.build_result import NetworkBuildResult
+from ...models.view.build_result import UIBuildResult
+from ...models.mappers import from_network_build_result
+from ...exceptions import DockerCommandError
+
+
+class BuildService:
+    """
+    Service for building and pushing Docker images.
+
+    Operates on a single `DockerBuildTargetConfig` at a time - the caller
+    (operations layer) decides which target(s) to build.
+    """
+
+    def __init__(self, docker_network: DockerNetwork):
+        """
+        Initialize Build service.
+
+        Args:
+            docker_network: DockerNetwork instance for command execution
+        """
+        self.docker = docker_network
+
+    @log_client_operation()
+    def build_target(
+        self,
+        target: DockerBuildTargetConfig,
+        on_output: Optional[Callable[[str], None]] = None,
+    ) -> ClientResult[UIBuildResult]:
+        """
+        Build (and optionally push) a single configured image.
+
+        Uses `docker buildx build` so a single code path covers both
+        single-platform and multi-platform builds.
+
+        Args:
+            target: Build target configuration
+            on_output: Optional callback invoked with each line of build output as it streams
+
+        Returns:
+            ClientResult[UIBuildResult]
+        """
+        try:
+            image_ref = f"{target.image}:{target.tag}"
+
+            args = [
+                "docker", "buildx", "build",
+                # Line-oriented output: without this buildx may pick its TTY
+                # renderer (ANSI cursor-movement redraws) and the streamed
+                # "lines" become raw control sequences that garble the console.
+                "--progress=plain",
+                "-t", image_ref,
+                "-f", target.dockerfile,
+            ]
+            # Omitted when unconfigured so buildx targets its native platform.
+            # Passing a platform list the host doesn't match makes buildx emulate
+            # through QEMU, so this is never guessed on the project's behalf.
+            if target.platforms:
+                args.extend(["--platform", target.platforms])
+            if target.target:
+                args.extend(["--target", target.target])
+            if target.push:
+                args.append("--push")
+            args.append(target.context)
+
+            if on_output:
+                self.docker.stream_command(args, on_line=on_output)
+            else:
+                self.docker.run_command(args)
+
+            network_result = NetworkBuildResult(
+                name=target.name,
+                image=target.image,
+                tag=target.tag,
+                platforms=target.platforms,
+                target=target.target or "",
+                pushed=target.push,
+            )
+            ui_result = from_network_build_result(network_result)
+
+            return ClientSuccess(data=ui_result, message=f"Built {image_ref}")
+        except DockerCommandError as e:
+            return ClientError(error_message=str(e), error_code="BUILD_ERROR")

titan_cli-0.8.0/plugins/titan-plugin-docker/titan_plugin_docker/clients/services/compose_service.py

@@ -0,0 +1,165 @@
+# plugins/titan-plugin-docker/titan_plugin_docker/clients/services/compose_service.py
+"""
+Compose Service
+
+Business logic for Docker Compose lifecycle operations.
+Uses network layer to execute commands, parses to network models, maps to view models.
+"""
+import json
+from typing import List, Optional
+
+from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
+
+from ..network import DockerNetwork
+from ...models.network.compose_status import NetworkComposeService, NetworkComposeStatus
+from ...models.view.compose_status import UIComposeStatus
+from ...models.mappers import from_network_compose_status
+from ...exceptions import DockerCommandError
+
+
+class ComposeService:
+    """
+    Service for Docker Compose lifecycle operations.
+
+    Operates on an arbitrary list of service names (or all services when
+    none is given). Has no notion of "profiles" or special-cased groups -
+    that resolution happens in the operations layer.
+    """
+
+    def __init__(self, docker_network: DockerNetwork, compose_file: str = "docker-compose.yml"):
+        """
+        Initialize Compose service.
+
+        Args:
+            docker_network: DockerNetwork instance for command execution
+            compose_file: Path to the compose file, relative to the project root
+        """
+        self.docker = docker_network
+        self.compose_file = compose_file
+
+    def _compose_args(self, *args: str) -> List[str]:
+        return ["docker", "compose", "-f", self.compose_file, *args]
+
+    @log_client_operation()
+    def up(self, services: Optional[List[str]] = None, detach: bool = True) -> ClientResult[List[str]]:
+        """
+        Start compose services.
+
+        Args:
+            services: Service names to start (empty/None starts all services)
+            detach: Run containers in the background (default: True)
+
+        Returns:
+            ClientResult[List[str]] with the started service names
+        """
+        try:
+            args = self._compose_args("up")
+            if detach:
+                args.append("-d")
+            args.extend(services or [])
+
+            self.docker.run_command(args)
+            return ClientSuccess(
+                data=services or [],
+                message="Started services" if services else "Started all services",
+            )
+        except DockerCommandError as e:
+            return ClientError(error_message=str(e), error_code="COMPOSE_UP_ERROR")
+
+    @log_client_operation()
+    def down(self, services: Optional[List[str]] = None) -> ClientResult[List[str]]:
+        """
+        Stop compose services.
+
+        Args:
+            services: Service names to stop (empty/None stops the whole project)
+
+        Returns:
+            ClientResult[List[str]] with the stopped service names
+        """
+        try:
+            if services:
+                # `docker compose down` doesn't accept service names; use `stop` for a subset.
+                args = self._compose_args("stop", *services)
+            else:
+                args = self._compose_args("down")
+
+            self.docker.run_command(args)
+            return ClientSuccess(
+                data=services or [],
+                message="Stopped services" if services else "Stopped project",
+            )
+        except DockerCommandError as e:
+            return ClientError(error_message=str(e), error_code="COMPOSE_DOWN_ERROR")
+
+    @log_client_operation()
+    def status(self, services: Optional[List[str]] = None) -> ClientResult[UIComposeStatus]:
+        """
+        Get compose project status.
+
+        Args:
+            services: Service names to inspect (empty/None inspects all services)
+
+        Returns:
+            ClientResult[UIComposeStatus]
+        """
+        try:
+            args = self._compose_args("ps", "--format", "json")
+            args.extend(services or [])
+
+            output = self.docker.run_command(args, check=False)
+            network_status = NetworkComposeStatus(services=self._parse_ps_output(output))
+            ui_status = from_network_compose_status(network_status)
+
+            return ClientSuccess(data=ui_status, message="Status retrieved")
+        except DockerCommandError as e:
+            return ClientError(error_message=str(e), error_code="COMPOSE_STATUS_ERROR")
+
+    @log_client_operation()
+    def list_services(self) -> ClientResult[List[str]]:
+        """
+        List every service name defined in the compose file, regardless of
+        whether it currently has a running/stopped container.
+
+        Returns:
+            ClientResult[List[str]]
+        """
+        try:
+            args = self._compose_args("config", "--services")
+            output = self.docker.run_command(args)
+            services = [line.strip() for line in output.splitlines() if line.strip()]
+            return ClientSuccess(data=services, message=f"Found {len(services)} service(s)")
+        except DockerCommandError as e:
+            return ClientError(error_message=str(e), error_code="COMPOSE_LIST_SERVICES_ERROR")
+
+    @staticmethod
+    def _parse_ps_output(output: str) -> List[NetworkComposeService]:
+        """
+        Parse `docker compose ps --format json` output.
+
+        Handles both a single JSON array (newer Compose) and newline-delimited
+        JSON objects (older Compose), since the CLI output shape has changed
+        across versions.
+        """
+        if not output.strip():
+            return []
+
+        try:
+            entries = json.loads(output)
+            if isinstance(entries, dict):
+                entries = [entries]
+        except json.JSONDecodeError:
+            entries = [json.loads(line) for line in output.splitlines() if line.strip()]
+
+        return [
+            NetworkComposeService(
+                service=entry.get("Service", ""),
+                container_name=entry.get("Name", ""),
+                image=entry.get("Image", ""),
+                state=entry.get("State", ""),
+                status=entry.get("Status", ""),
+                health=entry.get("Health", ""),
+            )
+            for entry in entries
+        ]