local-dev-composer 0.1.0__py3-none-any.whl

ldc/__init__.py

@@ -0,0 +1,3 @@
+"""local-dev-composer (ldc) — orchestrate local microservice environments."""
+
+__version__ = "0.1.0"

ldc/__main__.py

@@ -0,0 +1,5 @@
+"""Enables  python -m ldc  invocation."""
+from ldc.cli import main
+
+if __name__ == "__main__":
+    main()

ldc/adapters/config/yaml_reader.py

@@ -0,0 +1,172 @@
+"""
+Adapter: reads a composer.yml file and produces a WorkspaceConfig.
+
+YAML schema is deliberately flat and human-friendly; this adapter maps it
+to the rich domain model.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+
+from ldc.domain.exceptions import ConfigValidationError
+from ldc.domain.models import (
+    Group,
+    HealthCheckConfig,
+    HealthCheckType,
+    InstallConfig,
+    Prerequisites,
+    Runtime,
+    Service,
+    StartConfig,
+    WorkspaceConfig,
+)
+from ldc.ports.config_reader import IConfigReader
+
+
+class YamlConfigReader(IConfigReader):
+
+    def read(self, path: Path) -> WorkspaceConfig:
+        if not path.exists():
+            raise ConfigValidationError(f"Config file not found: {path}")
+
+        with path.open("r", encoding="utf-8") as fh:
+            raw = yaml.safe_load(fh)
+
+        if not isinstance(raw, dict):
+            raise ConfigValidationError("composer.yml must be a YAML mapping")
+
+        workspace_raw = raw.get("workspace", {})
+        root = workspace_raw.get("root", "./services")
+        log_dir = workspace_raw.get("log_dir", "./logs")
+
+        services_raw: Dict[str, Any] = raw.get("services", {})
+        groups_raw: Dict[str, Any] = raw.get("groups", {})
+
+        services = {
+            name: self._parse_service(name, svc_raw)
+            for name, svc_raw in services_raw.items()
+        }
+
+        groups = {
+            name: self._parse_group(name, grp_raw)
+            for name, grp_raw in groups_raw.items()
+        }
+
+        return WorkspaceConfig(
+            root=root,
+            log_dir=log_dir,
+            services=services,
+            groups=groups,
+        )
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _parse_service(self, name: str, raw: Dict[str, Any]) -> Service:
+        runtime_str = raw.get("runtime", "custom")
+        try:
+            runtime = Runtime(runtime_str.lower())
+        except ValueError:
+            raise ConfigValidationError(
+                f"Service '{name}': unknown runtime '{runtime_str}'. "
+                f"Valid values: {[r.value for r in Runtime]}"
+            )
+
+        return Service(
+            name=name,
+            runtime=runtime,
+            depends_on=raw.get("depends_on", []),
+            repo=raw.get("repo"),
+            branch=raw.get("branch", "main"),
+            dir=raw.get("dir"),
+            env=raw.get("env", {}),
+            env_files=self._parse_env_files(raw),
+            requires=self._parse_prerequisites(raw.get("requires")),
+            install=self._parse_install(raw.get("install")),
+            start=self._parse_start(raw.get("start")),
+            health_check=self._parse_health_check(name, raw.get("health_check")),
+            labels=raw.get("labels", {}),
+            description=raw.get("description", ""),
+        )
+
+    def _parse_env_files(self, raw: Dict[str, Any]) -> list:
+        if "env_files" in raw:
+            value = raw["env_files"]
+            return [value] if isinstance(value, str) else list(value)
+        if "env_file" in raw:
+            value = raw["env_file"]
+            return [value] if value else []
+        return []
+
+    def _parse_prerequisites(self, raw: Optional[Dict]) -> Optional[Prerequisites]:
+        if not raw:
+            return None
+        return Prerequisites(
+            java=raw.get("java"),
+            python=raw.get("python"),
+            node=raw.get("node"),
+            dotnet=raw.get("dotnet"),
+            commands=raw.get("commands", []),
+            env_vars=raw.get("env_vars", []),
+            folders=raw.get("folders", []),
+            files=raw.get("files", []),
+            ports_free=raw.get("ports_free", []),
+        )
+
+    def _parse_install(self, raw: Optional[Any]) -> Optional[InstallConfig]:
+        if not raw:
+            return None
+        if isinstance(raw, str):
+            return InstallConfig(command=raw)
+        return InstallConfig(
+            command=raw["command"],
+            working_dir=raw.get("working_dir", "."),
+        )
+
+    def _parse_start(self, raw: Optional[Any]) -> Optional[StartConfig]:
+        if not raw:
+            return None
+        if isinstance(raw, str):
+            return StartConfig(command=raw)
+        return StartConfig(
+            command=raw["command"],
+            args=raw.get("args", []),
+            working_dir=raw.get("working_dir", "."),
+        )
+
+    def _parse_health_check(
+        self, service_name: str, raw: Optional[Dict]
+    ) -> Optional[HealthCheckConfig]:
+        if not raw:
+            return None
+
+        type_str = raw.get("type", "process")
+        try:
+            hc_type = HealthCheckType(type_str.lower())
+        except ValueError:
+            raise ConfigValidationError(
+                f"Service '{service_name}': unknown health_check type '{type_str}'"
+            )
+
+        return HealthCheckConfig(
+            type=hc_type,
+            url=raw.get("url"),
+            host=raw.get("host", "localhost"),
+            port=raw.get("port"),
+            command=raw.get("command"),
+            expected_output=raw.get("expected_output"),
+            interval_seconds=raw.get("interval", 5),
+            timeout_seconds=raw.get("timeout", 60),
+            retries=raw.get("retries", 12),
+        )
+
+    def _parse_group(self, name: str, raw: Dict[str, Any]) -> Group:
+        return Group(
+            name=name,
+            description=raw.get("description", ""),
+            services=raw.get("services", []),
+        )

ldc/adapters/git/subprocess_client.py

@@ -0,0 +1,64 @@
+"""
+Adapter: git operations via the system git binary (via subprocess).
+Works on Windows with Git for Windows / GitBash.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from ldc.ports.git_client import IGitClient
+
+
+class SubprocessGitClient(IGitClient):
+
+    def clone(self, repo_url: str, dest: Path, branch: str = "main") -> None:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        self._run(
+            ["git", "clone", "--branch", branch, "--depth", "1", repo_url, dest.name],
+            cwd=str(dest.parent),
+        )
+
+    def pull(self, repo_dir: Path, branch: str = "main") -> None:
+        self._run(["git", "fetch", "origin"], cwd=str(repo_dir))
+        self._run(
+            ["git", "checkout", branch], cwd=str(repo_dir)
+        )
+        self._run(
+            ["git", "pull", "origin", branch, "--ff-only"],
+            cwd=str(repo_dir),
+        )
+
+    def is_cloned(self, dest: Path) -> bool:
+        git_dir = dest / ".git"
+        return git_dir.exists()
+
+    def current_branch(self, repo_dir: Path) -> str:
+        result = self._run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=str(repo_dir),
+            capture=True,
+        )
+        return result.stdout.strip()
+
+    # ------------------------------------------------------------------
+
+    def _run(
+        self,
+        cmd: list,
+        cwd: str,
+        capture: bool = False,
+    ) -> subprocess.CompletedProcess:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=capture,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            stderr = result.stderr.strip() if capture else ""
+            raise RuntimeError(
+                f"git command failed (exit {result.returncode}): {' '.join(cmd)}\n{stderr}"
+            )
+        return result

ldc/adapters/health/command_checker.py

@@ -0,0 +1,41 @@
+"""Adapter: health check via arbitrary command exit code / output."""
+from __future__ import annotations
+
+import subprocess
+import time
+
+from ldc.domain.models import HealthCheckConfig, HealthCheckType
+from ldc.ports.health_checker import IHealthChecker
+
+
+class CommandHealthChecker(IHealthChecker):
+
+    def supports(self, config: HealthCheckConfig) -> bool:
+        return config.type == HealthCheckType.COMMAND
+
+    def check(self, config: HealthCheckConfig) -> bool:
+        if not config.command:
+            return False
+        try:
+            result = subprocess.run(
+                config.command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode != 0:
+                return False
+            if config.expected_output:
+                return config.expected_output in (result.stdout + result.stderr)
+            return True
+        except Exception:
+            return False
+
+    def wait_healthy(self, config: HealthCheckConfig) -> bool:
+        deadline = time.monotonic() + config.timeout_seconds
+        while time.monotonic() < deadline:
+            if self.check(config):
+                return True
+            time.sleep(config.interval_seconds)
+        return False

ldc/adapters/health/composite_checker.py

@@ -0,0 +1,39 @@
+"""
+Adapter: dispatches health checks to the appropriate concrete checker
+based on HealthCheckConfig.type.
+"""
+from __future__ import annotations
+
+import time
+from typing import List
+
+from ldc.domain.models import HealthCheckConfig
+from ldc.ports.health_checker import IHealthChecker
+
+
+class CompositeHealthChecker(IHealthChecker):
+    """Routes to the first registered checker that supports the config type."""
+
+    def __init__(self, checkers: List[IHealthChecker]) -> None:
+        self._checkers = checkers
+
+    def supports(self, config: HealthCheckConfig) -> bool:
+        return any(c.supports(config) for c in self._checkers)
+
+    def check(self, config: HealthCheckConfig) -> bool:
+        checker = self._find(config)
+        if checker is None:
+            return False
+        return checker.check(config)
+
+    def wait_healthy(self, config: HealthCheckConfig) -> bool:
+        checker = self._find(config)
+        if checker is None:
+            return False
+        return checker.wait_healthy(config)
+
+    def _find(self, config: HealthCheckConfig) -> "IHealthChecker | None":
+        for c in self._checkers:
+            if c.supports(config):
+                return c
+        return None

ldc/adapters/health/http_checker.py

@@ -0,0 +1,31 @@
+"""Adapter: HTTP/HTTPS health check."""
+from __future__ import annotations
+
+import time
+import urllib.request
+import urllib.error
+
+from ldc.domain.models import HealthCheckConfig, HealthCheckType
+from ldc.ports.health_checker import IHealthChecker
+
+
+class HttpHealthChecker(IHealthChecker):
+
+    def supports(self, config: HealthCheckConfig) -> bool:
+        return config.type == HealthCheckType.HTTP
+
+    def check(self, config: HealthCheckConfig) -> bool:
+        try:
+            req = urllib.request.Request(config.url)
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                return 200 <= resp.status < 400
+        except Exception:
+            return False
+
+    def wait_healthy(self, config: HealthCheckConfig) -> bool:
+        deadline = time.monotonic() + config.timeout_seconds
+        while time.monotonic() < deadline:
+            if self.check(config):
+                return True
+            time.sleep(config.interval_seconds)
+        return False

ldc/adapters/health/process_checker.py

@@ -0,0 +1,28 @@
+"""Adapter: health check that simply verifies the process is alive."""
+from __future__ import annotations
+
+import time
+
+import psutil
+
+from ldc.domain.models import HealthCheckConfig, HealthCheckType
+from ldc.ports.health_checker import IHealthChecker
+
+
+class ProcessHealthChecker(IHealthChecker):
+
+    def __init__(self, pid_provider) -> None:
+        # pid_provider: callable(service_name) -> Optional[int]
+        self._pid_provider = pid_provider
+
+    def supports(self, config: HealthCheckConfig) -> bool:
+        return config.type == HealthCheckType.PROCESS
+
+    def check(self, config: HealthCheckConfig) -> bool:
+        # For PROCESS type we just need any live process — the caller supplies PID
+        # via the provider; config carries no PID directly.
+        # This checker is used as a fallback by the orchestrator passing PID explicitly.
+        return True  # orchestrator checks is_alive() directly for PROCESS type
+
+    def wait_healthy(self, config: HealthCheckConfig) -> bool:
+        return True

ldc/adapters/health/tcp_checker.py

@@ -0,0 +1,33 @@
+"""Adapter: TCP port health check."""
+from __future__ import annotations
+
+import socket
+import time
+
+from ldc.domain.models import HealthCheckConfig, HealthCheckType
+from ldc.ports.health_checker import IHealthChecker
+
+
+class TcpHealthChecker(IHealthChecker):
+
+    def supports(self, config: HealthCheckConfig) -> bool:
+        return config.type == HealthCheckType.TCP
+
+    def check(self, config: HealthCheckConfig) -> bool:
+        host = config.host or "localhost"
+        port = config.port
+        if not port:
+            return False
+        try:
+            with socket.create_connection((host, port), timeout=3):
+                return True
+        except (OSError, socket.timeout):
+            return False
+
+    def wait_healthy(self, config: HealthCheckConfig) -> bool:
+        deadline = time.monotonic() + config.timeout_seconds
+        while time.monotonic() < deadline:
+            if self.check(config):
+                return True
+            time.sleep(config.interval_seconds)
+        return False

ldc/adapters/prerequisites/system_checker.py

@@ -0,0 +1,256 @@
+"""
+Adapter: checks host prerequisites (runtimes, commands, env vars, folders, files, ports).
+
+Every check produces a CheckResult with a human-readable fix_hint so the
+user always knows exactly what to do when something is missing.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import socket
+import subprocess
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from ldc.domain.models import CheckResult, Prerequisites, PrerequisiteReport
+from ldc.ports.prerequisite_checker import IPrerequisiteChecker
+
+
+class SystemPrerequisiteChecker(IPrerequisiteChecker):
+
+    def check(self, service_name: str, prereqs: Prerequisites) -> PrerequisiteReport:
+        results: List[CheckResult] = []
+
+        if prereqs.java:
+            results.append(self._check_runtime("java", prereqs.java))
+        if prereqs.python:
+            results.append(self._check_runtime("python", prereqs.python))
+        if prereqs.node:
+            results.append(self._check_runtime("node", prereqs.node))
+        if prereqs.dotnet:
+            results.append(self._check_runtime("dotnet", prereqs.dotnet))
+
+        for cmd in prereqs.commands:
+            results.append(self._check_command(cmd))
+
+        for var in prereqs.env_vars:
+            results.append(self._check_env_var(var))
+
+        for folder in prereqs.folders:
+            results.append(self._check_folder(folder))
+
+        for filepath in prereqs.files:
+            results.append(self._check_file(filepath))
+
+        for port in prereqs.ports_free:
+            results.append(self._check_port_free(port))
+
+        return PrerequisiteReport(service_name=service_name, checks=results)
+
+    def auto_fix(self, service_name: str, prereqs: Prerequisites) -> PrerequisiteReport:
+        """Only auto-fixable action: create missing folders."""
+        for folder in prereqs.folders:
+            try:
+                Path(folder).mkdir(parents=True, exist_ok=True)
+            except Exception:
+                pass
+        return self.check(service_name, prereqs)
+
+    # ------------------------------------------------------------------
+    # Individual checks
+    # ------------------------------------------------------------------
+
+    def _check_runtime(self, runtime: str, constraint: str) -> CheckResult:
+        binary_map = {
+            "java": ("java", "-version"),
+            "python": ("python", "--version"),
+            "node": ("node", "--version"),
+            "dotnet": ("dotnet", "--version"),
+        }
+        binary, flag = binary_map[runtime]
+        installed_ver = self._get_version(binary, flag)
+
+        if installed_ver is None:
+            return CheckResult(
+                name=f"{runtime} runtime",
+                passed=False,
+                message=f"'{binary}' not found on PATH",
+                fix_hint=self._runtime_install_hint(runtime),
+            )
+
+        satisfied, reason = self._version_satisfies(installed_ver, constraint)
+        return CheckResult(
+            name=f"{runtime} runtime",
+            passed=satisfied,
+            message=f"{runtime} {installed_ver} — required: {constraint}",
+            fix_hint=None if satisfied else self._runtime_install_hint(runtime),
+        )
+
+    def _check_command(self, cmd: str) -> CheckResult:
+        found = shutil.which(cmd) is not None
+        return CheckResult(
+            name=f"command '{cmd}'",
+            passed=found,
+            message=f"'{cmd}' {'found on PATH' if found else 'NOT found on PATH'}",
+            fix_hint=(
+                None
+                if found
+                else f"Install '{cmd}' and ensure it is on your PATH. "
+                     f"On Windows you can check: where {cmd}"
+            ),
+        )
+
+    def _check_env_var(self, var: str) -> CheckResult:
+        value = os.environ.get(var)
+        present = value is not None and value.strip() != ""
+        return CheckResult(
+            name=f"env var '{var}'",
+            passed=present,
+            message=f"${var} {'is set' if present else 'is NOT set'}",
+            fix_hint=(
+                None
+                if present
+                else f"Set the environment variable: setx {var} \"<value>\" "
+                     f"(system-wide) or add it to your .env file"
+            ),
+        )
+
+    def _check_folder(self, folder: str) -> CheckResult:
+        path = Path(folder)
+        exists = path.exists() and path.is_dir()
+        return CheckResult(
+            name=f"folder '{folder}'",
+            passed=exists,
+            message=f"'{folder}' {'exists' if exists else 'does NOT exist'}",
+            fix_hint=(
+                None
+                if exists
+                else f"Create the folder: mkdir -p \"{folder}\"  "
+                     f"(or run: ldc check --fix to auto-create)"
+            ),
+        )
+
+    def _check_file(self, filepath: str) -> CheckResult:
+        path = Path(filepath)
+        exists = path.exists() and path.is_file()
+        return CheckResult(
+            name=f"file '{filepath}'",
+            passed=exists,
+            message=f"'{filepath}' {'exists' if exists else 'does NOT exist'}",
+            fix_hint=(
+                None
+                if exists
+                else f"Create or copy the required file to: {filepath}"
+            ),
+        )
+
+    def _check_port_free(self, port: int) -> CheckResult:
+        in_use = self._is_port_in_use(port)
+        return CheckResult(
+            name=f"port {port} free",
+            passed=not in_use,
+            message=f"Port {port} is {'in use' if in_use else 'free'}",
+            fix_hint=(
+                None
+                if not in_use
+                else f"Port {port} is occupied. Find the process: "
+                     f"netstat -ano | findstr :{port}  "
+                     f"then terminate it or change the service port."
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # Version utilities
+    # ------------------------------------------------------------------
+
+    def _get_version(self, binary: str, flag: str) -> Optional[str]:
+        try:
+            result = subprocess.run(
+                [binary, flag],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            # java -version prints to stderr; others to stdout
+            output = (result.stdout + result.stderr).strip()
+            return self._extract_version(output)
+        except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+            return None
+
+    _VERSION_RE = re.compile(r"(\d+)(?:\.(\d+))?(?:\.(\d+))?")
+
+    def _extract_version(self, text: str) -> Optional[str]:
+        m = self._VERSION_RE.search(text)
+        if not m:
+            return None
+        parts = [m.group(i) or "0" for i in (1, 2, 3)]
+        return ".".join(parts)
+
+    def _version_satisfies(
+        self, installed: str, constraint: str
+    ) -> Tuple[bool, str]:
+        """Evaluate simple constraints like '>=17', '>11', '==3.9'."""
+        m = re.match(r"^(>=|>|<=|<|==)(\d+(?:\.\d+)?(?:\.\d+)?)$", constraint.strip())
+        if not m:
+            return True, "unparseable constraint — skipped"
+
+        op, required_str = m.group(1), m.group(2)
+        inst_tuple = self._ver_tuple(installed)
+        req_tuple = self._ver_tuple(required_str)
+
+        ops = {
+            ">=": inst_tuple >= req_tuple,
+            ">": inst_tuple > req_tuple,
+            "<=": inst_tuple <= req_tuple,
+            "<": inst_tuple < req_tuple,
+            "==": inst_tuple == req_tuple,
+        }
+        satisfied = ops[op]
+        return satisfied, f"{installed} {op} {required_str}"
+
+    @staticmethod
+    def _ver_tuple(ver: str) -> tuple:
+        parts = ver.split(".")
+        result = []
+        for p in parts[:3]:
+            try:
+                result.append(int(p))
+            except ValueError:
+                result.append(0)
+        while len(result) < 3:
+            result.append(0)
+        return tuple(result)
+
+    @staticmethod
+    def _is_port_in_use(port: int) -> bool:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", port))
+                return False
+            except OSError:
+                return True
+
+    @staticmethod
+    def _runtime_install_hint(runtime: str) -> str:
+        hints = {
+            "java": (
+                "Install JDK and add JAVA_HOME to system env vars. "
+                "Download from: https://adoptium.net  "
+                "Then: setx JAVA_HOME \"C:\\Program Files\\Eclipse Adoptium\\jdk-XX\""
+            ),
+            "python": (
+                "Install Python from https://python.org/downloads "
+                "and ensure 'Add Python to PATH' is checked during setup."
+            ),
+            "node": (
+                "Install Node.js from https://nodejs.org "
+                "and ensure the installer adds it to PATH."
+            ),
+            "dotnet": (
+                "Install .NET SDK from https://dotnet.microsoft.com/download "
+                "and restart your terminal."
+            ),
+        }
+        return hints.get(runtime, f"Install '{runtime}' and add it to PATH.")