cc.shellback-kit 0.3.0__tar.gz

cc_shellback_kit-0.3.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: cc.shellback-kit
+Version: 0.3.0
+Summary: Add your description here
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: capsulecore-logger==0.3.0
+Requires-Dist: gitchangelog>=3.0.4
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: pytest-timeout>=2.4.0
+Requires-Dist: ruff>=0.15.6
+
+# CapsuleCore shellback
+
+Shellback is a robust, architecturally-agnostic Python library designed to bridge terminal environments (Bash, CMD, PowerShell) with Python scripts. It provides a clean, decoupled abstraction layer to execute system commands while maintaining persistent session state and cross-platform compatibility.
+
+Built with Hexagonal Architecture (Ports and Adapters) principles, Shellback ensures that your domain logic remains independent of the specific shell or operating system being used.
+
+## Usage
+
+```python
+from cc_shellback_kit.capsule import Bash
+from cc_shellback_kit.core import Command, SessionContext
+from cc_shellback_kit.observers import ConsoleLogObserver
+
+# 1. Configuramos el observador para ver la actividad en consola
+observer = ConsoleLogObserver()
+
+# 2. Iniciamos la Shell usando el manejador de contexto (with)
+with Bash(observer=observer) as shell:
+    
+    # --- EJECUCIÓN DE COMANDOS EXTERNOS ---
+    # Creamos un comando simple: 'ls -la'
+    cmd_list = Command("ls").add_args("-la")
+    result = shell.run(cmd_list)
+    
+    if result.is_success():
+        print(f"Archivos encontrados:\n{result.standard_output}")
+
+    # --- MANEJO DE ESTADO (VIRTUAL BUILT-INS) ---
+    # Cambiamos de directorio (esto afecta al SessionContext, no solo al proceso)
+    shell.run(Command("cd").add_args("/tmp"))
+    
+    # Verificamos el cambio ejecutando un 'pwd'
+    shell.run(Command("pwd"))
+
+    # --- VARIABLES DE ENTORNO ---
+    # Exportamos una variable que persistirá durante este bloque 'with'
+    shell.run(Command("export").add_args("APP_STAGE=development", "DEBUG=true"))
+```
+
+

cc_shellback_kit-0.3.0/README.md

@@ -0,0 +1,40 @@
+# CapsuleCore shellback
+
+Shellback is a robust, architecturally-agnostic Python library designed to bridge terminal environments (Bash, CMD, PowerShell) with Python scripts. It provides a clean, decoupled abstraction layer to execute system commands while maintaining persistent session state and cross-platform compatibility.
+
+Built with Hexagonal Architecture (Ports and Adapters) principles, Shellback ensures that your domain logic remains independent of the specific shell or operating system being used.
+
+## Usage
+
+```python
+from cc_shellback_kit.capsule import Bash
+from cc_shellback_kit.core import Command, SessionContext
+from cc_shellback_kit.observers import ConsoleLogObserver
+
+# 1. Configuramos el observador para ver la actividad en consola
+observer = ConsoleLogObserver()
+
+# 2. Iniciamos la Shell usando el manejador de contexto (with)
+with Bash(observer=observer) as shell:
+    
+    # --- EJECUCIÓN DE COMANDOS EXTERNOS ---
+    # Creamos un comando simple: 'ls -la'
+    cmd_list = Command("ls").add_args("-la")
+    result = shell.run(cmd_list)
+    
+    if result.is_success():
+        print(f"Archivos encontrados:\n{result.standard_output}")
+
+    # --- MANEJO DE ESTADO (VIRTUAL BUILT-INS) ---
+    # Cambiamos de directorio (esto afecta al SessionContext, no solo al proceso)
+    shell.run(Command("cd").add_args("/tmp"))
+    
+    # Verificamos el cambio ejecutando un 'pwd'
+    shell.run(Command("pwd"))
+
+    # --- VARIABLES DE ENTORNO ---
+    # Exportamos una variable que persistirá durante este bloque 'with'
+    shell.run(Command("export").add_args("APP_STAGE=development", "DEBUG=true"))
+```
+
+

cc_shellback_kit-0.3.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "cc.shellback-kit"
+version = "0.3.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "capsulecore-logger==0.3.0",
+    "gitchangelog>=3.0.4",
+    "pytest>=9.0.2",
+    "pytest-timeout>=2.4.0",
+    "ruff>=0.15.6",
+]

cc_shellback_kit-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cc_shellback_kit-0.3.0/src/cc.shellback_kit.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: cc.shellback-kit
+Version: 0.3.0
+Summary: Add your description here
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: capsulecore-logger==0.3.0
+Requires-Dist: gitchangelog>=3.0.4
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: pytest-timeout>=2.4.0
+Requires-Dist: ruff>=0.15.6
+
+# CapsuleCore shellback
+
+Shellback is a robust, architecturally-agnostic Python library designed to bridge terminal environments (Bash, CMD, PowerShell) with Python scripts. It provides a clean, decoupled abstraction layer to execute system commands while maintaining persistent session state and cross-platform compatibility.
+
+Built with Hexagonal Architecture (Ports and Adapters) principles, Shellback ensures that your domain logic remains independent of the specific shell or operating system being used.
+
+## Usage
+
+```python
+from cc_shellback_kit.capsule import Bash
+from cc_shellback_kit.core import Command, SessionContext
+from cc_shellback_kit.observers import ConsoleLogObserver
+
+# 1. Configuramos el observador para ver la actividad en consola
+observer = ConsoleLogObserver()
+
+# 2. Iniciamos la Shell usando el manejador de contexto (with)
+with Bash(observer=observer) as shell:
+    
+    # --- EJECUCIÓN DE COMANDOS EXTERNOS ---
+    # Creamos un comando simple: 'ls -la'
+    cmd_list = Command("ls").add_args("-la")
+    result = shell.run(cmd_list)
+    
+    if result.is_success():
+        print(f"Archivos encontrados:\n{result.standard_output}")
+
+    # --- MANEJO DE ESTADO (VIRTUAL BUILT-INS) ---
+    # Cambiamos de directorio (esto afecta al SessionContext, no solo al proceso)
+    shell.run(Command("cd").add_args("/tmp"))
+    
+    # Verificamos el cambio ejecutando un 'pwd'
+    shell.run(Command("pwd"))
+
+    # --- VARIABLES DE ENTORNO ---
+    # Exportamos una variable que persistirá durante este bloque 'with'
+    shell.run(Command("export").add_args("APP_STAGE=development", "DEBUG=true"))
+```
+
+

cc_shellback_kit-0.3.0/src/cc.shellback_kit.egg-info/SOURCES.txt

@@ -0,0 +1,41 @@
+README.md
+pyproject.toml
+src/cc.shellback_kit.egg-info/PKG-INFO
+src/cc.shellback_kit.egg-info/SOURCES.txt
+src/cc.shellback_kit.egg-info/dependency_links.txt
+src/cc.shellback_kit.egg-info/requires.txt
+src/cc.shellback_kit.egg-info/top_level.txt
+src/cc_shellback_kit/__init__.py
+src/cc_shellback_kit/capsule/Bash.py
+src/cc_shellback_kit/capsule/ConsoleLogObserver.py
+src/cc_shellback_kit/capsule/FileLogObserver.py
+src/cc_shellback_kit/capsule/JSONFileObserver.py
+src/cc_shellback_kit/capsule/MultiObserver.py
+src/cc_shellback_kit/capsule/SilentObserver.py
+src/cc_shellback_kit/capsule/__init__.py
+src/cc_shellback_kit/core/ArgumentBuilder.py
+src/cc_shellback_kit/core/Command.py
+src/cc_shellback_kit/core/CommandResult.py
+src/cc_shellback_kit/core/SessionContext.py
+src/cc_shellback_kit/core/Shell.py
+src/cc_shellback_kit/core/ShellObserver.py
+src/cc_shellback_kit/core/__init__.py
+tests/test_ArgumentBuilder.py
+tests/test_Bash.py
+tests/test_Command.py
+tests/test_CommandResult.py
+tests/test_ConsoleLogObserver.py
+tests/test_FileLogObserver.py
+tests/test_JSONFileObserver.py
+tests/test_MultiObserver.py
+tests/test_SessionContext.py
+tests/test_ShellObserver.py
+tests/test_Shell_handle_cd.py
+tests/test_Shell_handle_export.py
+tests/test_Shell_notify_error.py
+tests/test_Shell_parse_env_vars.py
+tests/test_Shell_resolve_path.py
+tests/test_Shell_run.py
+tests/test_Shell_run_external.py
+tests/test_Shell_validate_executable.py
+tests/test_SilentObserver.py

cc_shellback_kit-0.3.0/src/cc.shellback_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cc_shellback_kit-0.3.0/src/cc.shellback_kit.egg-info/requires.txt

@@ -0,0 +1,5 @@
+capsulecore-logger==0.3.0
+gitchangelog>=3.0.4
+pytest>=9.0.2
+pytest-timeout>=2.4.0
+ruff>=0.15.6

cc_shellback_kit-0.3.0/src/cc.shellback_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+cc_shellback_kit

cc_shellback_kit-0.3.0/src/cc_shellback_kit/__init__.py

@@ -0,0 +1,34 @@
+from .capsule import (
+    Bash,
+    ConsoleLogObserver,
+    FileLogObserver,
+    SilentObserver,
+    JSONFileObserver,
+    MultiObserver,
+)
+from .core import (
+    Shell,
+    ArgumentBuilder,
+    Command,
+    SessionContext,
+    CommandResult,
+    CommandNotFoundError,
+    ShellObserver,
+)
+
+
+__all__ = [
+    "ArgumentBuilder",
+    "Command",
+    "Bash",
+    "Shell",
+    "SessionContext",
+    "CommandResult",
+    "JSONFileObserver",
+    "CommandNotFoundError",
+    "ShellObserver",
+    "ConsoleLogObserver",
+    "FileLogObserver",
+    "SilentObserver",
+    "MultiObserver",
+]

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/Bash.py

@@ -0,0 +1,8 @@
+from ..core import Shell
+
+
+class Bash(Shell):
+    def _format_command(self, executable: str, args: list[str]) -> list[str]:
+        # Ya no concatenamos [executable] + args aquí.
+        # Solo devolvemos los args tal cual, la Shell base hará el resto.
+        return args

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/ConsoleLogObserver.py

@@ -0,0 +1,16 @@
+from ..core import CommandResult, ShellObserver
+
+
+class ConsoleLogObserver(ShellObserver):
+    """Muestra en consola lo que está pasando en tiempo real."""
+
+    def on_command_start(self, executable, final_args):
+        print(f"🛠️  Ejecutando: {' '.join(final_args)}")
+
+    def on_command_result(self, result: CommandResult):
+        if result.is_success():
+            print(f"✅ OK ({result.execution_time:.3f}s)")
+        else:
+            print(f"❌ FALLO (Código: {result.return_code})")
+            if result.standard_error:
+                print(f"   Error: {result.standard_error.strip()}")

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/FileLogObserver.py

@@ -0,0 +1,49 @@
+import logging
+from pathlib import Path
+from ..core import ShellObserver, CommandResult
+
+
+class FileLogObserver(ShellObserver):
+    """Guarda toda la actividad de la Shell en un archivo físico."""
+
+    def __init__(self, log_path: str = "shell_activity.log"):
+            self.log_path = Path(log_path)
+
+            self.logger = logging.getLogger("ShellFileLogger")
+            self.logger.setLevel(logging.INFO)
+            self.logger.propagate = False  # Evita que los logs salgan por consola en los tests
+
+            if self.logger.handlers:
+                for h in self.logger.handlers[:]:
+                    h.close()
+                    self.logger.removeHandler(h)
+
+            # Ahora creamos el nuevo handler con la ruta correcta
+            handler = logging.FileHandler(self.log_path, encoding="utf-8")
+            formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
+            handler.setFormatter(formatter) 
+            self.logger.addHandler(handler)
+
+    def on_session_start(self, shell_name: str):
+        self.logger.info(f"=== INICIO DE SESIÓN: {shell_name} ===")
+
+    def on_session_end(self, shell_name: str, error: Exception = None):
+        if error:
+            self.logger.error(f"=== FIN DE SESIÓN CON ERROR: {error} ===")
+        else:
+            self.logger.info("=== FIN DE SESIÓN EXITOSO ===")
+
+    def on_command_start(self, executable: str, final_args: list[str]):
+        cmd_str = " ".join(final_args)
+        self.logger.info(f"EJECUTANDO: {cmd_str}")
+
+    def on_command_result(self, result: CommandResult):
+        status = "SUCCESS" if result.is_success() else f"FAILED({result.return_code})"
+        self.logger.info(
+            f"RESULTADO: {status} | "
+            f"DURACIÓN: {result.execution_time:.4f}s | "
+            f"STDOUT: {result.standard_output.strip()[:100]}..."
+        )
+
+    def on_error(self, message: str, error: Exception = None):
+        self.logger.error(f"ERROR DEL SISTEMA: {message} | Detalle: {error}")

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/JSONFileObserver.py

@@ -0,0 +1,63 @@
+import json
+import time
+from pathlib import Path
+from typing import Any, List, Optional, Dict
+from ..core import ShellObserver, CommandResult
+
+class JSONFileObserver(ShellObserver):
+    """
+    Registra toda la actividad de la Shell en un archivo JSON.
+    Ideal para auditoría técnica y análisis de datos posterior.
+    """
+
+    def __init__(self, log_path: str = "shell_audit.json"):
+        self.log_path = Path(log_path)
+        # Inicializamos el archivo si no existe
+        if not self.log_path.exists():
+            self._write_logs([])
+
+    def _read_logs(self) -> List[Dict[str, Any]]:
+        try:
+            with open(self.log_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return []
+
+    def _write_logs(self, logs: List[Dict[str, Any]]):
+        with open(self.log_path, "w", encoding="utf-8") as f:
+            json.dump(logs, f, indent=4, ensure_ascii=False)
+
+    def _append_entry(self, entry: Dict[str, Any]):
+        logs = self._read_logs()
+        logs.append(entry)
+        self._write_logs(logs)
+
+    def on_command_result(self, result: CommandResult):
+        entry = {
+            "timestamp": time.time(),
+            "event": "command_executed",
+            "command": result.command_sent,
+            "success": result.is_success(),
+            "exit_code": result.return_code,
+            "duration": round(result.execution_time, 4),
+            "stdout_len": len(result.standard_output),
+            "stderr": result.standard_error.strip() if result.standard_error else None
+        }
+        self._append_entry(entry)
+
+    def on_context_change(self, key: str, value: Any):
+        entry = {
+            "timestamp": time.time(),
+            "event": "context_mutation",
+            "change": {key: str(value)}
+        }
+        self._append_entry(entry)
+
+    def on_error(self, message: str, error: Optional[Exception] = None):
+        entry = {
+            "timestamp": time.time(),
+            "event": "internal_error",
+            "message": message,
+            "exception": str(error) if error else None
+        }
+        self._append_entry(entry)

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/MultiObserver.py

@@ -0,0 +1,39 @@
+from typing import List, Any
+from ..core import ShellObserver, CommandResult
+
+
+class MultiObserver(ShellObserver):
+    """
+    Patrón Composite: Permite registrar múltiples observadores y
+    notificar a todos ellos de cada evento de la Shell.
+    """
+
+    def __init__(self, observers: List[ShellObserver] = None):
+        self.observers = observers or []
+
+    def add_observer(self, observer: ShellObserver):
+        self.observers.append(observer)
+
+    def on_session_start(self, shell_name: str):
+        for o in self.observers:
+            o.on_session_start(shell_name)
+
+    def on_session_end(self, shell_name: str, error: Exception = None):
+        for o in self.observers:
+            o.on_session_end(shell_name, error)
+
+    def on_context_change(self, key: str, value: Any):
+        for o in self.observers:
+            o.on_context_change(key, value)
+
+    def on_command_start(self, executable: str, final_args: List[str]):
+        for o in self.observers:
+            o.on_command_start(executable, final_args)
+
+    def on_command_result(self, result: CommandResult):
+        for o in self.observers:
+            o.on_command_result(result)
+
+    def on_error(self, message: str, error: Exception = None):
+        for o in self.observers:
+            o.on_error(message, error)

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/SilentObserver.py

@@ -0,0 +1,7 @@
+from ..core import ShellObserver
+
+
+class SilentObserver(ShellObserver):
+    """No hace nada. Ideal para scripts de producción donde no quieres ruido."""
+
+    pass

cc_shellback_kit-0.3.0/src/cc_shellback_kit/capsule/__init__.py

@@ -0,0 +1,16 @@
+from .Bash import Bash
+from .ConsoleLogObserver import ConsoleLogObserver
+from .FileLogObserver import FileLogObserver
+from .MultiObserver import MultiObserver
+from .JSONFileObserver import JSONFileObserver
+from .SilentObserver import SilentObserver
+
+
+__all__ = [
+    "Bash",
+    "ConsoleLogObserver",
+    "FileLogObserver",
+    "JSONFileObserver",
+    "MultiObserver",
+    "SilentObserver",
+]

cc_shellback_kit-0.3.0/src/cc_shellback_kit/core/ArgumentBuilder.py

@@ -0,0 +1,30 @@
+from typing import Any, List
+
+class ArgumentBuilder:
+    """Garantiza la consistencia de los argumentos para el Sistema Operativo."""
+
+    def __init__(self, style: str = "unix"):
+        self._args: List[str] = []
+        self.style = style
+
+    def add_arg(self, value: Any) -> "ArgumentBuilder":
+        """Aplana listas/tuplas y convierte todo a string, ignorando vacíos."""
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                self.add_arg(item)
+        elif value is not None:
+            val_str = str(value).strip()
+            if val_str:
+                self._args.append(val_str)
+        return self
+
+    def add_flag(self, name: str, value: Any = None) -> "ArgumentBuilder":
+        prefix = "--" if self.style == "unix" else "/"
+        clean_name = name.strip().replace(" ", "_")
+        self.add_arg(f"{prefix}{clean_name}")
+        if value is not None:
+            self.add_arg(value)
+        return self
+
+    def build(self) -> List[str]:
+        return self._args

cc_shellback_kit-0.3.0/src/cc_shellback_kit/core/Command.py

@@ -0,0 +1,22 @@
+from .ArgumentBuilder import ArgumentBuilder
+
+class Command:
+    """Representa un comando ejecutable con sus argumentos."""
+
+    def __init__(self, executable: str):
+        self.executable = executable
+        self.builder = ArgumentBuilder()
+
+    def add_args(self, *args) -> "Command":
+        """
+        Añade argumentos posicionales. 
+        Soporta elementos sueltos o listas gracias al nuevo builder.
+        """
+        for arg in args:
+            self.builder.add_arg(arg)
+        return self
+
+    @property
+    def args(self) -> list[str]:
+        """Obtiene la lista de argumentos construida y validada."""
+        return self.builder.build()

cc_shellback_kit-0.3.0/src/cc_shellback_kit/core/CommandResult.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+import json
+from typing import Any
+
+
+@dataclass
+class CommandResult:
+    """Encapsulates the output of an executed command."""
+
+    standard_output: str = ""
+    standard_error: str = ""
+    return_code: int = 0
+    execution_time: float = 0.0
+    command_sent: list[str] = field(default_factory=list)
+
+    def is_success(self) -> bool:
+        """Returns True if the command executed successfully."""
+        return self.return_code == 0
+
+    def json(self) -> Any:
+        """Parses the standard output as JSON."""
+        return json.loads(self.standard_output)
+
+    def __or__(self, next_command: Any) -> str:
+        """Enables pipe syntax."""
+        return self.standard_output

cc_shellback_kit-0.3.0/src/cc_shellback_kit/core/SessionContext.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict
+
+
+@dataclass(frozen=True)
+class SessionContext:
+    """Maintains persistent state across Shell executions."""
+
+    cwd: Path = field(default_factory=Path.cwd)
+    env: Dict[str, str] = field(default_factory=dict)
+    encoding: str = "utf-8"