orch-cli 0.1.0__py3-none-any.whl

orch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

orch/cli.py

@@ -0,0 +1,384 @@
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+import typer
+import psutil
+from rich.console import Console
+from rich.table import Table
+from rich.live import Live
+from rich.markup import escape
+
+from orch.config import load_config, find_config
+from orch.manager import ProcessManager, LOG_COLORS
+from orch.state import StateManager
+
+app = typer.Typer(
+    name="orch",
+    help="Orch: Herramienta CLI de orquestación de procesos de desarrollo local y venvs",
+    no_args_is_help=True
+)
+
+console = Console()
+
+def get_manager(config_path: Optional[Path]) -> ProcessManager:
+    """Helper to resolve config and return a ProcessManager instance."""
+    try:
+        cfg = load_config(config_path)
+        return ProcessManager(cfg, console)
+    except FileNotFoundError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1)
+    except ValueError as e:
+        console.print(f"[bold red]Config Error:[/bold red] {e}")
+        raise typer.Exit(code=1)
+
+@app.command()
+def up(
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Ejecuta todos los servicios en primer plano (foreground), mostrando logs unificados."""
+    manager = get_manager(config)
+    manager.run_foreground()
+
+@app.command()
+def start(
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Inicia todos los servicios en segundo plano (detached) y guarda sus PIDs."""
+    manager = get_manager(config)
+    success = manager.run_background()
+    if not success:
+        raise typer.Exit(code=1)
+
+@app.command()
+def stop(
+    service: Optional[str] = typer.Argument(
+        None, help="Nombre del servicio específico a detener (ej. backend). Si se omite, detiene todos."
+    ),
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Detiene los servicios en ejecución en segundo plano."""
+    manager = get_manager(config)
+    if service:
+        manager.stop_service(service)
+    else:
+        manager.stop_all()
+
+@app.command()
+def restart(
+    service: Optional[str] = typer.Argument(
+        None, help="Nombre del servicio específico a reiniciar. Si se omite, reinicia todos."
+    ),
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Reinicia servicios activos en segundo plano."""
+    manager = get_manager(config)
+    active = manager.state_manager.get_active_services()
+
+    # Determine services to restart
+    to_restart = []
+    if service:
+        if service not in manager.config.services:
+            console.print(f"[bold red]Error:[/bold red] Service '{service}' is not defined in config.")
+            raise typer.Exit(code=1)
+        to_restart.append(service)
+    else:
+        to_restart = list(manager.config.services.keys())
+
+    for name in to_restart:
+        # Stop if running
+        if name in active:
+            manager.stop_service(name)
+            # Short sleep to let process release ports
+            time.sleep(0.5)
+
+        # Start again
+        # Temporarily adapt run_background to start a single service
+        # Let's do it inline to avoid modifying ProcessManager API
+        service_config = manager.config.services[name]
+        env = manager._prepare_env(service_config)
+        log_path = manager.state_manager.get_log_path(name)
+
+        with open(log_path, "a", encoding="utf-8") as log_file:
+            log_file.write(f"\n--- Service restarted at {time.strftime('%Y-%m-%d %H:%M:%S')} ---\n")
+            log_file.flush()
+
+        log_f = open(log_path, "a", encoding="utf-8")
+        console.print(f"Starting [bold cyan]{name}[/bold cyan]...")
+        try:
+            import subprocess
+            kwargs = {
+                "shell": True,
+                "cwd": str(service_config.path),
+                "env": env,
+                "stdout": log_f,
+                "stderr": subprocess.STDOUT,
+                "stdin": subprocess.DEVNULL,
+            }
+            if sys.platform == "win32":
+                # CREATE_NEW_CONSOLE (0x10) | CREATE_NO_WINDOW (0x08000000) | CREATE_BREAKAWAY_FROM_JOB (0x01000000)
+                kwargs["creationflags"] = 0x00000010 | 0x08000000 | 0x01000000
+            else:
+                kwargs["start_new_session"] = True
+
+            proc = subprocess.Popen(service_config.command, **kwargs)
+            ps_proc = psutil.Process(proc.pid)
+            create_time = ps_proc.create_time()
+
+            manager.state_manager.update_service(name, proc.pid, service_config.command, create_time)
+            console.print(f"  * [bold green]{name}[/bold green] restarted with PID {proc.pid}")
+        except Exception as e:
+            console.print(f"  x [bold red]{name}[/bold red] failed to start: {e}")
+        finally:
+            log_f.close()
+
+def format_uptime(seconds: float) -> str:
+    """Format seconds into hh:mm:ss."""
+    h = int(seconds // 3600)
+    m = int((seconds % 3600) // 60)
+    s = int(seconds % 60)
+    return f"{h:02d}:{m:02d}:{s:02d}"
+
+@app.command()
+def status(
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Muestra el estado de los servicios en segundo plano y su consumo de recursos."""
+    manager = get_manager(config)
+    # This updates stale services in state.json to CRASHED
+    active = manager.state_manager.get_active_services()
+    state = manager.state_manager.load_state()
+    services_state = state.get("services", {})
+
+    table = Table(title=f"Project: {manager.config.project_name} (Services Status)")
+    table.add_column("Service", style="cyan", no_wrap=True)
+    table.add_column("Status", justify="center")
+    table.add_column("PID", style="magenta", justify="center")
+    table.add_column("CPU %", justify="right")
+    table.add_column("Memory (MB)", justify="right")
+    table.add_column("Uptime", justify="center")
+
+    # In order to measure CPU percent properly on psutil, we should initialize it once,
+    # sleep briefly, and fetch again. We'll do a quick 0.1s check.
+    proc_objs = {}
+    for name, info in active.items():
+        pid = info["pid"]
+        try:
+            proc = psutil.Process(pid)
+            proc.cpu_percent(interval=None)
+            proc_objs[name] = proc
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            pass
+
+    time.sleep(0.1) # Brief sleep to get meaningful CPU readings
+
+    for name in manager.config.services.keys():
+        svc_state = services_state.get(name, {})
+        status_val = svc_state.get("status", "STOPPED")
+
+        if name in active and name in proc_objs:
+            proc = proc_objs[name]
+            try:
+                cpu = proc.cpu_percent(interval=None)
+                # Sum CPU of children processes as well (common for npm/sub-shells)
+                for child in proc.children(recursive=True):
+                    try:
+                        cpu += child.cpu_percent(interval=None)
+                    except (psutil.NoSuchProcess, psutil.AccessDenied):
+                        pass
+
+                mem_bytes = proc.memory_info().rss
+                for child in proc.children(recursive=True):
+                    try:
+                        mem_bytes += child.memory_info().rss
+                    except (psutil.NoSuchProcess, psutil.AccessDenied):
+                        pass
+
+                mem_mb = mem_bytes / (1024 * 1024)
+                uptime = time.time() - proc.create_time()
+
+                table.add_row(
+                    name,
+                    "[bold green]RUNNING[/bold green]",
+                    str(proc.pid),
+                    f"{cpu:.1f}%",
+                    f"{mem_mb:.1f} MB",
+                    format_uptime(uptime)
+                )
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                table.add_row(name, "[bold red]CRASHED[/bold red]", str(svc_state.get("pid", "-")), "0.0%", "0.0 MB", "00:00:00")
+        elif status_val == "CRASHED":
+            table.add_row(
+                name,
+                "[bold red]CRASHED[/bold red]",
+                str(svc_state.get("pid", "-")),
+                "0.0%",
+                "0.0 MB",
+                "00:00:00"
+            )
+        else:
+            table.add_row(
+                name,
+                "[bold yellow]STOPPED[/bold yellow]",
+                "-",
+                "-",
+                "-",
+                "-"
+            )
+
+    console.print(table)
+
+def tail_file(filepath: Path, console: Console, prefix: str, color: str, stop_event: Any, lines_back: int = 50):
+    """Tail a single log file in a blocking thread."""
+    if not filepath.exists():
+        console.print(f"\\\\[[{color}]{prefix}[/{color}]] [yellow]Waiting for log file to be created...[/yellow]")
+        while not filepath.exists() and not stop_event.is_set():
+            time.sleep(0.5)
+
+    if stop_event.is_set():
+        return
+
+    # Read last lines_back lines
+    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+        # Simple tail implementation
+        content = f.readlines()
+        last_lines = content[-lines_back:]
+        for line in last_lines:
+            clean_line = line.rstrip(chr(10)).rstrip(chr(13))
+            console.print(f"\\\\[[{color}]{prefix}[/{color}]] {escape(clean_line)}")
+
+        # Seek to end and tail
+        f.seek(0, os.SEEK_END)
+        while not stop_event.is_set():
+            line = f.readline()
+            if line:
+                clean_line = line.rstrip(chr(10)).rstrip(chr(13))
+                console.print(f"\\\\[[{color}]{prefix}[/{color}]] {escape(clean_line)}")
+            else:
+                time.sleep(0.1)
+
+@app.command()
+def logs(
+    service: Optional[str] = typer.Argument(
+        None, help="Nombre del servicio específico a consultar. Si se omite, muestra de todos."
+    ),
+    follow: bool = typer.Option(
+        False, "--follow", "-f", help="Seguir los logs en tiempo real (tail -f)"
+    ),
+    lines: int = typer.Option(
+        50, "--lines", "-n", help="Número de líneas del historial a mostrar"
+    ),
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Muestra y sigue los logs de los servicios en segundo plano."""
+    manager = get_manager(config)
+    active = manager.state_manager.get_active_services()
+
+    services_to_show = []
+    if service:
+        if service not in manager.config.services:
+            console.print(f"[bold red]Error:[/bold red] Service '{service}' is not defined in config.")
+            raise typer.Exit(code=1)
+        services_to_show.append(service)
+    else:
+        services_to_show = list(manager.config.services.keys())
+
+    if not follow:
+        # Just display the last N lines
+        for name in services_to_show:
+            log_path = manager.state_manager.get_log_path(name)
+            console.print(f"\n--- [bold cyan]Logs for {name}[/bold cyan] ({log_path.name}) ---")
+            if not log_path.exists():
+                console.print("[yellow]No logs recorded yet.[/yellow]")
+                continue
+            with open(log_path, "r", encoding="utf-8", errors="replace") as f:
+                lines_list = f.readlines()
+                for line in lines_list[-lines:]:
+                    print(line.rstrip("\r\n"))
+    else:
+        # Multi-file follow
+        import threading
+        stop_event = threading.Event()
+        threads = []
+
+        console.print("[bold green]Following logs in real-time. Press Ctrl+C to stop...[/bold green]\n")
+        try:
+            for idx, name in enumerate(services_to_show):
+                color = LOG_COLORS[idx % len(LOG_COLORS)]
+                log_path = manager.state_manager.get_log_path(name)
+                t = threading.Thread(
+                    target=tail_file,
+                    args=(log_path, console, name, color, stop_event, lines),
+                    daemon=True
+                )
+                t.start()
+                threads.append(t)
+
+            # Wait loop until interrupted
+            while True:
+                time.sleep(0.5)
+        except KeyboardInterrupt:
+            console.print("\n[bold yellow]Stopping log follower...[/bold yellow]")
+        finally:
+            stop_event.set()
+            for t in threads:
+                t.join(timeout=1.0)
+
+@app.command()
+def clean(
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Ruta al archivo orch.yml / project.yml"
+    )
+):
+    """Detiene los servicios activos, vacía los logs y limpia el archivo de estado."""
+    manager = get_manager(config)
+    
+    # 1. Stop background services if running
+    active = manager.state_manager.get_active_services()
+    if active:
+        console.print("[bold yellow]Deteniendo servicios activos antes de limpiar...[/bold yellow]")
+        manager.stop_all()
+        # Sleep briefly to ensure process cleanup
+        time.sleep(1.0)
+        
+    # 2. Clean logs
+    logs_dir = manager.state_manager.logs_dir
+    if logs_dir.exists():
+        console.print("[bold blue]Limpiando archivos de logs...[/bold blue]")
+        for log_file in logs_dir.glob("*.log"):
+            try:
+                # Open in write-mode and close to truncate to 0 bytes
+                with open(log_file, "w", encoding="utf-8") as f:
+                    pass
+                console.print(f"  * Log {log_file.name} vaciado.")
+            except Exception as e:
+                console.print(f"  x No se pudo vaciar {log_file.name}: {e}")
+                
+    # 3. Clean state file
+    state_file = manager.state_manager.state_file
+    if state_file.exists():
+        console.print("[bold blue]Reseteando archivo de estado...[/bold blue]")
+        try:
+            manager.state_manager.save_state({"services": {}})
+            console.print("  * Estado reseteado.")
+        except Exception as e:
+            console.print(f"  x No se pudo resetear el estado: {e}")
+            
+    console.print("[bold green]Limpieza completada con éxito.[/bold green]")
+
+if __name__ == "__main__":
+    app()

orch/config.py

@@ -0,0 +1,84 @@
+import os
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+import yaml
+
+class ServiceConfig:
+    def __init__(self, name: str, data: Dict[str, Any], base_dir: Path):
+        self.name = name
+        self.path = base_dir / Path(data.get("path", "."))
+        self.command = data.get("command")
+        self.env = data.get("env", {})
+        self.restart = data.get("restart", "no") # 'no', 'always', 'on-failure'
+
+        if not self.command:
+            raise ValueError(f"Service '{name}' must have a 'command' specified.")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": str(self.path),
+            "command": self.command,
+            "env": self.env,
+            "restart": self.restart,
+        }
+
+class ProjectConfig:
+    def __init__(self, filepath: Path):
+        self.filepath = filepath.resolve()
+        self.base_dir = self.filepath.parent
+        
+        with open(self.filepath, "r", encoding="utf-8") as f:
+            try:
+                self.data = yaml.safe_load(f) or {}
+            except yaml.YAMLError as e:
+                raise ValueError(f"Invalid YAML file: {e}")
+
+        self.project_name = self.data.get("project")
+        if not self.project_name:
+            raise ValueError("Config must specify a 'project' name.")
+
+        # Parse global environment config
+        env_data = self.data.get("env", {})
+        self.env_type = env_data.get("type")
+        self.env_path = None
+        if env_data.get("path"):
+            self.env_path = (self.base_dir / Path(env_data["path"])).resolve()
+        self.global_vars = env_data.get("variables", {})
+
+        # Parse services
+        services_data = self.data.get("services", {})
+        if not services_data:
+            raise ValueError("Config must define at least one service.")
+            
+        self.services: Dict[str, ServiceConfig] = {}
+        for name, svc_data in services_data.items():
+            self.services[name] = ServiceConfig(name, svc_data, self.base_dir)
+
+def find_config(search_path: Optional[Path] = None) -> Path:
+    """
+    Search for a default configuration file starting from search_path and walking up.
+    """
+    candidates = ["orch.yml", "orch.yaml", "project.yml", "project.yaml"]
+    current = Path(search_path or os.getcwd()).resolve()
+
+    # Search upwards
+    for parent in [current] + list(current.parents):
+        for candidate in candidates:
+            path = parent / candidate
+            if path.exists() and path.is_file():
+                return path
+
+    raise FileNotFoundError(
+        "Could not find orch.yml, orch.yaml, project.yml, or project.yaml in this directory or any parent directories."
+    )
+
+def load_config(filepath: Optional[Path] = None) -> ProjectConfig:
+    if filepath is None:
+        filepath = find_config()
+    else:
+        filepath = Path(filepath).resolve()
+        if not filepath.exists():
+            raise FileNotFoundError(f"Configuration file not found: {filepath}")
+    
+    return ProjectConfig(filepath)

orch/manager.py

@@ -0,0 +1,273 @@
+import os
+import sys
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+import psutil
+from rich.console import Console
+from rich.markup import escape
+
+from orch.config import ProjectConfig, ServiceConfig
+from orch.state import StateManager
+
+# Colors for service logs
+LOG_COLORS = ["cyan", "magenta", "green", "yellow", "blue", "bright_red", "bright_green", "bright_yellow", "bright_blue", "bright_magenta", "bright_cyan"]
+
+class ProcessManager:
+    def __init__(self, config: ProjectConfig, console: Console):
+        self.config = config
+        self.console = console
+        self.state_manager = StateManager(config.base_dir)
+        self.active_processes: Dict[str, subprocess.Popen] = {}
+        self._threads: List[threading.Thread] = []
+        self._stop_event = threading.Event()
+
+    def _prepare_env(self, service: ServiceConfig) -> Dict[str, str]:
+        """Merge system env, global env variables, service env variables and inject venv if active."""
+        env = os.environ.copy()
+
+        # Inject global variables
+        for k, v in self.config.global_vars.items():
+            env[k] = str(v)
+
+        # Inject service-specific variables
+        for k, v in service.env.items():
+            env[k] = str(v)
+
+        # Inject virtual environment if configured
+        if self.config.env_type == "venv" and self.config.env_path:
+            venv_path = self.config.env_path
+            
+            # Determine path to venv binary/scripts directory
+            if sys.platform == "win32":
+                bin_dir = venv_path / "Scripts"
+            else:
+                bin_dir = venv_path / "bin"
+
+            if bin_dir.exists():
+                # Prepend venv's bin to PATH
+                env["PATH"] = f"{bin_dir}{os.pathsep}{env.get('PATH', '')}"
+                env["VIRTUAL_ENV"] = str(venv_path)
+                # Remove PYTHONHOME if set to prevent issues with virtual envs
+                env.pop("PYTHONHOME", None)
+            else:
+                self.console.print(f"[yellow]Warning: Virtualenv path '{venv_path}' is configured, but '{bin_dir}' was not found.[/yellow]")
+
+        return env
+
+    def _read_stream(self, name: str, stream: Any, color: str):
+        """Read line by line from stream and print to console with colored prefix."""
+        while not self._stop_event.is_set():
+            line = stream.readline()
+            if not line:
+                break
+            # Decode and strip line breaks
+            decoded = line.rstrip("\r\n")
+            self.console.print(f"\\[[{color}]{name}[/{color}]] {escape(decoded)}")
+
+    def run_foreground(self):
+        """Run all services in foreground mode, multiplexing logs to stdout."""
+        self.console.print(f"[bold green]Starting project '{self.config.project_name}' in foreground mode...[/bold green]")
+        self.console.print("Press [bold red]Ctrl+C[/bold red] to stop all services.\n")
+
+        # Check if services are already running in background
+        active_background = self.state_manager.get_active_services()
+        if active_background:
+            self.console.print("[yellow]Warning: Some services are already running in the background. Running in foreground might cause port conflicts.[/yellow]")
+
+        services = list(self.config.services.values())
+        
+        try:
+            for idx, service in enumerate(services):
+                color = LOG_COLORS[idx % len(LOG_COLORS)]
+                env = self._prepare_env(service)
+
+                self.console.print(f"[bold blue]Starting service '{service.name}'...[/bold blue]")
+                
+                # On Windows, using shell=True allows running npm/python command strings naturally
+                # We merge stderr into stdout for combined streaming
+                proc = subprocess.Popen(
+                    service.command,
+                    shell=True,
+                    cwd=str(service.path),
+                    env=env,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    bufsize=1 # Line buffered
+                )
+
+                self.active_processes[service.name] = proc
+
+                # Start a thread to read output
+                t = threading.Thread(
+                    target=self._read_stream,
+                    args=(service.name, proc.stdout, color),
+                    daemon=True
+                )
+                t.start()
+                self._threads.append(t)
+
+            # Wait loop to monitor processes
+            while self.active_processes:
+                dead_services = []
+                for name, proc in list(self.active_processes.items()):
+                    ret = proc.poll()
+                    if ret is not None:
+                        self.console.print(f"[bold red][{name}] Process exited with code {ret}[/bold red]")
+                        dead_services.append(name)
+                
+                for name in dead_services:
+                    del self.active_processes[name]
+                
+                time.sleep(0.5)
+
+        except KeyboardInterrupt:
+            self.console.print("\n[bold yellow]Stopping all services...[/bold yellow]")
+        finally:
+            self.stop_all(foreground=True)
+
+    def run_background(self) -> bool:
+        """Start all services in detached background mode, writing logs to files."""
+        self.state_manager.ensure_dirs()
+        active = self.state_manager.get_active_services()
+        
+        success = True
+        for name, service in self.config.services.items():
+            if name in active:
+                self.console.print(f"[yellow]Service '{name}' is already running (PID: {active[name]['pid']}). Skipping...[/yellow]")
+                continue
+
+            env = self._prepare_env(service)
+            log_path = self.state_manager.get_log_path(name)
+            
+            # Open log file in append mode, write run header
+            with open(log_path, "a", encoding="utf-8") as log_file:
+                log_file.write(f"\n--- Service started at {time.strftime('%Y-%m-%d %H:%M:%S')} ---\n")
+                log_file.flush()
+
+            # Open log file for sub-process stdout/stderr redirection
+            # We open in write mode (to append, we pass file handles)
+            log_f = open(log_path, "a", encoding="utf-8")
+
+            self.console.print(f"Starting [bold cyan]{name}[/bold cyan]...")
+            try:
+                # We need to spawn process detached so it survives parent exiting
+                # On Windows, we can use CREATE_NEW_PROCESS_GROUP
+                # On Unix, we can use start_new_session=True (or preexec_fn=os.setsid)
+                # stdout and stderr go directly to log file, stdin is DEVNULL
+                kwargs = {
+                    "shell": True,
+                    "cwd": str(service.path),
+                    "env": env,
+                    "stdout": log_f,
+                    "stderr": subprocess.STDOUT,
+                    "stdin": subprocess.DEVNULL,
+                }
+                
+                if sys.platform == "win32":
+                    # CREATE_NEW_PROCESS_GROUP (0x200) | CREATE_BREAKAWAY_FROM_JOB (0x01000000)
+                    kwargs["creationflags"] = 0x00000200 | 0x01000000
+                else:
+                    kwargs["start_new_session"] = True
+
+                proc = subprocess.Popen(service.command, **kwargs)
+                
+                # Fetch create_time using psutil to prevent PID recycle issue
+                ps_proc = psutil.Process(proc.pid)
+                create_time = ps_proc.create_time()
+
+                self.state_manager.update_service(name, proc.pid, service.command, create_time)
+                self.console.print(f"  * [bold green]{name}[/bold green] started with PID {proc.pid}")
+            except Exception as e:
+                self.console.print(f"  x [bold red]{name}[/bold red] failed to start: {e}")
+                success = False
+            finally:
+                log_f.close()
+
+        return success
+
+    def stop_all(self, foreground: bool = False):
+        """Stop all processes. If foreground, stops active_processes. If background, reads state file."""
+        self._stop_event.set()
+        
+        if foreground:
+            for name, proc in list(self.active_processes.items()):
+                self.console.print(f"Stopping [bold yellow]{name}[/bold yellow] (PID {proc.pid})...")
+                self.kill_process_tree(proc.pid)
+            self.active_processes.clear()
+        else:
+            state = self.state_manager.load_state()
+            services = state.get("services", {})
+            
+            stopped_any = False
+            for name, info in services.items():
+                if info.get("status") == "STOPPED":
+                    continue
+                
+                pid = info.get("pid")
+                if pid:
+                    self.console.print(f"Stopping [bold yellow]{name}[/bold yellow] (PID {pid})...")
+                    self.kill_process_tree(pid)
+                else:
+                    self.console.print(f"Clearing stale state for [bold yellow]{name}[/bold yellow]...")
+                
+                self.state_manager.remove_service(name)
+                stopped_any = True
+            
+            if stopped_any:
+                self.console.print("[bold green]All services stopped/cleared.[/bold green]")
+            else:
+                self.console.print("[yellow]No active or crashed services found to stop.[/yellow]")
+
+    def stop_service(self, name: str):
+        """Stop a specific background service."""
+        state = self.state_manager.load_state()
+        services = state.get("services", {})
+        if name not in services or services[name].get("status") == "STOPPED":
+            self.console.print(f"[yellow]Service '{name}' is not running in the background.[/yellow]")
+            return
+
+        info = services[name]
+        pid = info.get("pid")
+        if pid:
+            self.console.print(f"Stopping [bold yellow]{name}[/bold yellow] (PID {pid})...")
+            self.kill_process_tree(pid)
+        
+        self.state_manager.remove_service(name)
+        self.console.print(f"[bold green]Service '{name}' stopped.[/bold green]")
+
+    def kill_process_tree(self, pid: int):
+        """Recursively terminate parent PID and all its child processes."""
+        try:
+            parent = psutil.Process(pid)
+            children = parent.children(recursive=True)
+            
+            # Send terminate signal to children first
+            for child in children:
+                try:
+                    child.terminate()
+                except psutil.NoSuchProcess:
+                    pass
+            
+            # Terminate parent
+            parent.terminate()
+
+            # Wait up to 2 seconds for clean termination
+            gone, alive = psutil.wait_procs(children + [parent], timeout=2.0)
+            
+            # Force kill survivors
+            for survivor in alive:
+                try:
+                    self.console.print(f"  [red]Force killing survivor process PID {survivor.pid}[/red]")
+                    survivor.kill()
+                except psutil.NoSuchProcess:
+                    pass
+        except psutil.NoSuchProcess:
+            pass
+        except Exception as e:
+            self.console.print(f"[red]Error killing process tree for PID {pid}: {e}[/red]")

orch/state.py

@@ -0,0 +1,115 @@
+import json
+import os
+import time
+from pathlib import Path
+from typing import Dict, Any, Optional
+import psutil
+
+class StateManager:
+    def __init__(self, base_dir: Path):
+        self.base_dir = base_dir.resolve()
+        self.orch_dir = self.base_dir / ".orch"
+        self.state_file = self.orch_dir / "state.json"
+        self.logs_dir = self.orch_dir / "logs"
+
+    def ensure_dirs(self):
+        """Ensure .orch and .orch/logs directories exist."""
+        self.orch_dir.mkdir(parents=True, exist_ok=True)
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+
+    def load_state(self) -> Dict[str, Any]:
+        """Load state JSON, returning empty dict if not existing or invalid."""
+        if not self.state_file.exists():
+            return {"services": {}}
+        try:
+            with open(self.state_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return {"services": {}}
+
+    def save_state(self, state: Dict[str, Any]):
+        """Save state dict to state.json."""
+        self.ensure_dirs()
+        with open(self.state_file, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2)
+
+    def update_service(self, name: str, pid: int, command: str, create_time: float):
+        """Update or insert a running service entry."""
+        state = self.load_state()
+        state["services"][name] = {
+            "pid": pid,
+            "command": command,
+            "started_at": time.time(),
+            "create_time": create_time,
+            "log_file": str(self.get_log_path(name)),
+            "status": "RUNNING",
+        }
+        self.save_state(state)
+
+    def remove_service(self, name: str):
+        """Mark a service entry as STOPPED cleanly."""
+        state = self.load_state()
+        if name in state["services"]:
+            state["services"][name]["status"] = "STOPPED"
+            state["services"][name]["pid"] = None
+            state["services"][name]["create_time"] = None
+        else:
+            state["services"][name] = {
+                "pid": None,
+                "command": "",
+                "started_at": None,
+                "create_time": None,
+                "log_file": str(self.get_log_path(name)),
+                "status": "STOPPED",
+            }
+        self.save_state(state)
+
+    def get_log_path(self, name: str) -> Path:
+        """Get the absolute path to a service's log file."""
+        self.ensure_dirs()
+        return (self.logs_dir / f"{name}.log").resolve()
+
+    def get_active_services(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Verify PIDs against OS processes. Returns active services only.
+        Updates stale entries to 'CRASHED' in the state file.
+        """
+        state = self.load_state()
+        services = state.get("services", {})
+        active = {}
+        changed = False
+
+        for name, info in list(services.items()):
+            if info.get("status") == "STOPPED":
+                continue
+
+            pid = info.get("pid")
+            saved_create_time = info.get("create_time")
+
+            is_alive = False
+            if pid and psutil.pid_exists(pid):
+                try:
+                    proc = psutil.Process(pid)
+                    # Check if create_time matches within a reasonable delta
+                    proc_create_time = proc.create_time()
+                    if saved_create_time and abs(proc_create_time - saved_create_time) < 1.5:
+                        if proc.is_running() and proc.status() != psutil.STATUS_ZOMBIE:
+                            is_alive = True
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+
+            if is_alive:
+                active[name] = info
+                if info.get("status") != "RUNNING":
+                    info["status"] = "RUNNING"
+                    changed = True
+            else:
+                # Process is dead, but was not stopped cleanly -> CRASHED
+                if info.get("status") != "CRASHED":
+                    info["status"] = "CRASHED"
+                    changed = True
+
+        if changed:
+            self.save_state(state)
+
+        return active

orch_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: orch-cli
+Version: 0.1.0
+Summary: A local development process orchestrator and venv-aware runner
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer[all]>=0.9.0
+Description-Content-Type: text/markdown
+
+# Orch - Local Service Orchestrator
+
+[![PyPI version](https://img.shields.io/pypi/v/orch-cli.svg)](https://pypi.org/project/orch-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/EASYLIFECODE/orch/workflows/CI/badge.svg)](https://github.com/EASYLIFECODE/orch/actions)
+
+**Orch** is a lightweight, **daemon-less** command-line interface (CLI) tool designed to simplify local development of client-server or multi-service architectures. 
+
+It runs your scripts, servers, frontends, and workers concurrently, manages their Python virtual environments (`venv`) transparently, monitors their resources, and multiplexes their logs—**without** the overhead of Docker or background daemon processes.
+
+---
+
+## Key Features
+
+- 🔌 **Daemon-less Architecture**: No persistent background services needed. State is safely tracked locally in `.orch/state.json`.
+- 🐍 **Automatic venv Detection**: Injects your project's Python virtual environment (`venv`) to the process execution path automatically—no manual activation scripts required.
+- 🎨 **Unified Multiplexed Logs**: Streams output from all services into a single terminal window with distinct, customizable color prefixes, protecting ANSI markup.
+- 🌙 **Background Execution**: Spawn services in detached modes, persisting output to individual log files.
+- 📊 **Resource Monitoring**: Track CPU, Memory consumption, and uptime per service with a single command.
+- 🛡️ **Clean Process Tree Teardown**: Intercepts shutdown signals and recursively kills child processes (e.g. Node sub-processes, shell scripts) cleanly, avoiding orphaned processes.
+- 🛡️ **PID Recycle Protection**: Safeguards against re-using recycled PIDs by validating the OS process creation time before killing or reporting status.
+
+---
+
+## Installation
+
+### Stable Release (via PyPI)
+
+```bash
+pip install orch-cli
+```
+
+### From Source (Development Mode)
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/EASYLIFECODE/orch.git
+   cd orch
+   ```
+
+2. Install in editable development mode:
+   ```bash
+   pip install -e .
+   ```
+
+---
+
+## Configuration (`orch.yml`)
+
+Configure your services in an `orch.yml` or `project.yml` file in the root of your project:
+
+```yaml
+# orch.yml
+project: my-awesome-app
+
+# Global environment configuration
+env:
+  type: venv               # Type of virtual environment
+  path: ./venv            # Path to the virtualenv folder
+  variables:
+    GLOBAL_VAR: "shared-value"
+    DATABASE_URL: "sqlite:///local.db"
+
+services:
+  backend:
+    path: ./backend        # Working directory for this service
+    command: python app.py  # Automatically runs using the configured global venv
+    env:
+      PORT: "8000"
+
+  frontend:
+    path: ./frontend
+    command: npm run dev
+    env:
+      VITE_API_URL: "http://localhost:8000"
+
+  worker:
+    path: ./worker
+    command: python worker.py
+```
+
+---
+
+## CLI Usage
+
+### 1. Run in Foreground (Interactive Mode)
+
+Launches all services concurrently, streaming their colored logs into the active console. Pressing `Ctrl+C` cleanly shuts down all services.
+
+```bash
+orch up
+```
+
+### 2. Run in Background (Detached Mode)
+
+Launches all services in the background and saves their state.
+
+```bash
+orch start
+```
+
+### 3. Check Service Status & Resource Usage
+
+Displays an elegant table showing running status, PID, CPU, Memory usage (recursive of all child processes), and uptime.
+
+```bash
+orch status
+```
+
+*Example Output:*
+```text
+           Project: my-awesome-app (Services Status)
+┌──────────┬─────────┬───────┬───────┬─────────────┬──────────┐
+│ Service  │ Status  │  PID  │ CPU % │ Memory (MB) │  Uptime  │
+├──────────┼─────────┼───────┼───────┼─────────────┼──────────┤
+│ backend  │ RUNNING │ 12452 │  0.2% │     45.4 MB │ 00:12:30 │
+│ frontend │ RUNNING │ 12459 │  0.0% │     82.1 MB │ 00:12:30 │
+│ worker   │ RUNNING │ 12461 │  1.5% │     32.7 MB │ 00:12:28 │
+└──────────┴─────────┴───────┴───────┴─────────────┴──────────┘
+```
+
+### 4. Consult and Tail Logs
+
+Tail log files of services running in the background.
+
+```bash
+# Follow logs of all services
+orch logs -f
+
+# Follow logs of a specific service
+orch logs backend -f
+
+# Read last 100 lines without following
+orch logs frontend --lines 100
+```
+
+### 5. Restart Services
+
+Restarts all or specific services running in the background.
+
+```bash
+# Restart all
+orch restart
+
+# Restart only backend
+orch restart backend
+```
+
+### 6. Stop Services
+
+Stops services running in the background and cleans up state.
+
+```bash
+# Stop all services
+orch stop
+
+# Stop a specific service
+orch stop backend
+```
+
+### 7. Clean State & Logs
+
+Terminates background services, clears log files (`.orch/logs/*.log`) to 0 bytes, and resets the state file.
+
+```bash
+orch clean
+```
+
+---
+
+## Technical Architecture
+
+Orch is built using **Python 3.8+**, **Typer** for the CLI framework, **Rich** for visual output rendering, and **psutil** for platform-independent process controls.
+
+```text
+                     [ CLI Command: orch ]
+                              │
+                    [ Load Configuration ]
+                              │
+                    [ Validate YAML Schema ]
+                              │
+                    [ Process Execution ]
+                              │
+         ┌────────────────────┴────────────────────┐
+  [ Foreground Mode ]                       [ Background Mode ]
+  (Multiplex to Terminal)                   (Write to Log Files)
+         │                                         │
+  ├── Thread 1 (stdout)                     ├── .orch/logs/backend.log
+  ├── Thread 2 (stdout)                     ├── .orch/logs/frontend.log
+  └── SIGINT cleanup                        └── Keep PIDs in .orch/state.json
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

orch_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+orch/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+orch/cli.py,sha256=G9w4j7Owo-Ic9FzY2uMKhezeyvMO8CDwoQB0TpdYJVY,14334
+orch/config.py,sha256=zPgYT4MCpwgf-0P97nCFPl7Um7Hf7Gabma7DLdpJcps,3057
+orch/manager.py,sha256=r_TMuWRKGBmU3s7KZQct9WfvYInW_CIePPrtbcS8W6o,11569
+orch/state.py,sha256=G_qoZBUOva5BQj9FQggyHxFWzn_V6RDn6c2pxSlYKGw,4191
+orch_cli-0.1.0.dist-info/METADATA,sha256=oBXP3TgIhxsDxASaMhx5yQ-GqCEJSnpeKZLT64rPrZE,6808
+orch_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+orch_cli-0.1.0.dist-info/entry_points.txt,sha256=EpMKCtXt47wWaG7uM1m8pdYOLyeJtgLQPUSzH_NwBjY,38
+orch_cli-0.1.0.dist-info/licenses/LICENSE,sha256=Vno9RhyRE70OW8p_3mHDMutHBEbQBAzMQtOBxhkC3JE,1100
+orch_cli-0.1.0.dist-info/RECORD,,

orch_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

orch_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orch = orch.cli:app

orch_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EASYLIFECODE / Anthony Mosquera (4m12-code)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.