@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/tools/validation/validate_skills.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+import os
+import re
+import yaml
+from pathlib import Path
+from collections import defaultdict
+
+def find_skills(base_dirs):
+    """Encuentra todas las skills en los directorios base."""
+    skills = {}
+    for base_dir in base_dirs:
+        path = Path(base_dir)
+        if not path.exists():
+            continue
+        for skill_file in path.rglob("SKILL.md"):
+            skill_name = skill_file.parent.name
+            skills[skill_name] = {
+                "path": str(skill_file),
+                "content": skill_file.read_text(encoding="utf-8", errors="ignore")
+            }
+    return skills
+
+def validate_skill_format(skills):
+    """Valida el formato de cada skill."""
+    validation_results = {}
+    for name, data in skills.items():
+        content = data["content"]
+        has_title = bool(re.search(r'^#\s+.+', content, re.MULTILINE))
+        validation_results[name] = {
+            "has_title": has_title,
+            "is_empty": len(content.strip()) == 0,
+            "path": data["path"]
+        }
+    return validation_results
+
+def find_agents(base_dirs):
+    """Encuentra las definiciones de los agentes."""
+    agents = {}
+    for base_dir in base_dirs:
+        path = Path(base_dir)
+        if not path.exists():
+            continue
+        for agent_file in path.rglob("*.md"):
+            if agent_file.name == "README.md":
+                continue
+            content = agent_file.read_text(encoding="utf-8", errors="ignore")
+            # Extraer frontmatter YAML
+            match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)', content, re.DOTALL)
+            if match:
+                try:
+                    frontmatter = yaml.safe_load(match.group(1))
+                    if isinstance(frontmatter, dict) and "name" in frontmatter:
+                        agents[frontmatter["name"]] = {
+                            "path": str(agent_file),
+                            "skills_declared": frontmatter.get("skills", []),
+                            "body": match.group(2)
+                        }
+                except yaml.YAMLError:
+                    pass
+    return agents
+
+def analyze_injection():
+    """Analiza cómo se inyectan las skills (revisando pre_tool_use.py)."""
+    hook_path = Path("gaia-ops/hooks/pre_tool_use.py")
+    if not hook_path.exists():
+        return "No se encontró gaia-ops/hooks/pre_tool_use.py"
+    
+    content = hook_path.read_text(encoding="utf-8", errors="ignore")
+    if "skills are injected natively by Claude Code" in content:
+        return "Las skills se inyectan de forma nativa por Claude Code a través del campo 'skills:' en el frontmatter del agente (según pre_tool_use.py)."
+    return "Mecanismo de inyección en pre_tool_use.py analizado, pero no se encontró la nota estándar sobre inyección nativa."
+
+def generate_report(skills, validation, agents, injection_info):
+    """Genera el reporte en formato Markdown."""
+    report = ["# Reporte de Validación de Skills\n"]
+    
+    report.append("## 1. Análisis de Inyección")
+    report.append(f"{injection_info}\n")
+    
+    report.append(f"## 2. Skills Encontradas ({len(skills)})")
+    for name, val in validation.items():
+        status = "✅ OK" if val["has_title"] and not val["is_empty"] else "❌ PROBLEMA"
+        issues = []
+        if not val["has_title"]: issues.append("Falta título (# Título)")
+        if val["is_empty"]: issues.append("Archivo vacío")
+        issue_str = f" - Detalles: {', '.join(issues)}" if issues else ""
+        report.append(f"- **{name}** ({val['path']}): {status}{issue_str}")
+    report.append("")
+    
+    # Analizar uso de skills
+    used_skills = defaultdict(list)
+    missing_skills = defaultdict(list)
+    body_mentions = defaultdict(list)
+    
+    for agent_name, agent_data in agents.items():
+        declared = agent_data["skills_declared"] or []
+        body = agent_data["body"]
+        for skill in declared:
+            if skill in skills:
+                used_skills[skill].append(agent_name)
+            else:
+                missing_skills[agent_name].append(skill)
+        
+        # Check for skills mentioned in the body but not declared
+        for skill in skills:
+            if skill not in declared and skill in body:
+                body_mentions[agent_name].append(skill)
+                
+    report.append("## 3. Uso de Skills por Agentes")
+    if not agents:
+        report.append("No se encontraron definiciones de agentes con frontmatter YAML válido.\n")
+    else:
+        for agent_name, agent_data in agents.items():
+            declared = agent_data["skills_declared"] or []
+            mentions = body_mentions[agent_name]
+            mention_str = f" (Menciona en texto sin declarar: {', '.join(mentions)})" if mentions else ""
+            report.append(f"- **{agent_name}**: {len(declared)} skills declaradas.{mention_str}")
+        report.append("")
+        
+    report.append("## 4. Gaps Identificados")
+    
+    # Skills no utilizadas
+    # Consideramos una skill como utilizada si está declarada o si se menciona explícitamente en el cuerpo
+    all_used_skills = set(used_skills.keys())
+    for mentions in body_mentions.values():
+        all_used_skills.update(mentions)
+        
+    unused_skills = set(skills.keys()) - all_used_skills
+    if unused_skills:
+        report.append("### Skills no utilizadas (Huérfanas)")
+        for skill in sorted(unused_skills):
+            report.append(f"- {skill}")
+    else:
+        report.append("### Skills no utilizadas (Huérfanas)")
+        report.append("- Ninguna. Todas las skills encontradas están asignadas a al menos un agente.")
+    report.append("")
+    
+    # Skills declaradas pero inexistentes
+    if missing_skills:
+        report.append("### Skills declaradas pero no encontradas (Faltantes)")
+        for agent, missing in missing_skills.items():
+            for m in missing:
+                report.append(f"- El agente **{agent}** declara la skill '{m}', pero no se encontró el archivo SKILL.md correspondiente.")
+    else:
+        report.append("### Skills declaradas pero no encontradas (Faltantes)")
+        report.append("- Ninguna. Todas las skills declaradas por los agentes existen.")
+    report.append("")
+    
+    # Skills mencionadas en el texto pero no inyectadas formalmente
+    report.append("### Skills mencionadas en el texto pero NO declaradas en 'skills:'")
+    if body_mentions:
+        for agent, mentions in body_mentions.items():
+            for m in mentions:
+                report.append(f"- **{agent}** menciona '{m}' en su cuerpo pero no está en la lista de inyección.")
+    else:
+        report.append("- Ninguna.")
+    report.append("")
+    
+    return "\n".join(report)
+
+def main():
+    skill_dirs = ["gaia-ops/skills", ".claude/skills", "conductor-orchestrator/skills"]
+    agent_dirs = ["gaia-ops/agents", ".claude/agents", "conductor-orchestrator/agents"]
+    
+    print("Buscando skills...")
+    skills = find_skills(skill_dirs)
+    
+    print("Validando formato...")
+    validation = validate_skill_format(skills)
+    
+    print("Buscando agentes...")
+    agents = find_agents(agent_dirs)
+    
+    print("Analizando inyección...")
+    injection_info = analyze_injection()
+    
+    print("Generando reporte...")
+    report = generate_report(skills, validation, agents, injection_info)
+    
+    report_path = Path("gaia-ops/tools/validation/skills_report.md")
+    report_path.write_text(report, encoding="utf-8")
+    print(f"Reporte generado en {report_path}")
+    
+    # Imprimir el reporte en la salida estándar para que el agente lo pueda devolver
+    print("\n" + "="*50 + "\n")
+    print(report)
+
+if __name__ == "__main__":
+    main()

package/dist/gaia-security/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "gaia-security",
+  "version": "4.7.2",
+  "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
+  "author": {
+    "name": "jaguilar87"
+  },
+  "repository": "https://github.com/metraton/gaia-ops",
+  "license": "MIT",
+  "keywords": [
+    "security",
+    "devops"
+  ],
+  "engines": {
+    "claude-code": ">=2.1.0"
+  },
+  "categories": [
+    "devops",
+    "security",
+    "orchestration"
+  ]
+}

package/dist/gaia-security/config/universal-rules.json

@@ -0,0 +1,10 @@
+{
+  "rules": {
+    "universal": [
+      {
+        "rule": "Your prompt includes a Project Context section with confirmed project knowledge. Extract relevant data from it BEFORE executing commands."
+      }
+    ],
+    "agent_specific": {}
+  }
+}

package/dist/gaia-security/hooks/adapters/__init__.py

@@ -0,0 +1,52 @@
+"""
+Adapter Layer for Gaia-Ops Hooks.
+
+Provides CLI-agnostic normalized types and the abstract HookAdapter interface.
+Business logic modules consume and produce these types; concrete adapters
+translate between these types and CLI-specific JSON protocols.
+
+Modules:
+- types: Frozen dataclasses and enums for all hook event/response data
+- base: Abstract HookAdapter interface
+"""
+
+from .types import (
+    HookEventType,
+    PermissionDecision,
+    DistributionChannel,
+    HookEvent,
+    ValidationRequest,
+    ValidationResult,
+    ToolResult,
+    AgentCompletion,
+    CompletionResult,
+    ContextResult,
+    BootstrapResult,
+    QualityResult,
+    VerificationResult,
+    HookResponse,
+)
+from .base import HookAdapter
+from .claude_code import ClaudeCodeAdapter
+from .utils import has_stdin_data, warn_if_dual_channel
+
+__all__ = [
+    "HookEventType",
+    "PermissionDecision",
+    "DistributionChannel",
+    "HookEvent",
+    "ValidationRequest",
+    "ValidationResult",
+    "ToolResult",
+    "AgentCompletion",
+    "CompletionResult",
+    "ContextResult",
+    "BootstrapResult",
+    "QualityResult",
+    "VerificationResult",
+    "HookResponse",
+    "HookAdapter",
+    "ClaudeCodeAdapter",
+    "has_stdin_data",
+    "warn_if_dual_channel",
+]

package/dist/gaia-security/hooks/adapters/base.py

@@ -0,0 +1,219 @@
+"""
+Abstract base class defining the adapter contract.
+
+Each CLI backend (Claude Code, future CLIs) provides a concrete implementation
+of HookAdapter. Business logic modules interact only with the normalized types;
+they never see raw CLI JSON.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .types import (
+    AgentCompletion,
+    BootstrapResult,
+    CompletionResult,
+    ContextResult,
+    DistributionChannel,
+    HookEvent,
+    HookResponse,
+    QualityResult,
+    ValidationResult,
+    VerificationResult,
+)
+
+
+class HookAdapter(ABC):
+    """Abstract adapter between CLI-specific JSON and normalized types.
+
+    Invariants (from adapter-interface contract):
+    1. Business logic modules NEVER see HookResponse.
+    2. The adapter NEVER modifies business logic results -- only translates format.
+    3. Adding a new hook event requires ONLY a new adapter method.
+    """
+
+    @abstractmethod
+    def parse_event(self, stdin_data: str) -> HookEvent:
+        """Parse raw stdin JSON into a normalized HookEvent.
+
+        Preconditions:
+            - stdin_data is a valid JSON string
+            - JSON contains at minimum: hook_event_name, session_id
+
+        Postconditions:
+            - Returns HookEvent with event_type set to a valid HookEventType
+            - Returns HookEvent with session_id populated
+            - payload contains the full raw event data
+
+        Raises:
+            ValueError: If JSON is invalid or event type is unknown.
+        """
+        ...
+
+    @abstractmethod
+    def format_validation_response(self, result: ValidationResult) -> HookResponse:
+        """Format a ValidationResult for CLI consumption.
+
+        Preconditions:
+            - result.allowed is a valid boolean
+            - result.reason is a non-empty string
+
+        Postconditions:
+            - HookResponse.output is a valid JSON-serializable dict
+            - HookResponse.exit_code is 0 (corrective deny) or 2 (permanent block)
+            - If result.allowed is True, output contains permissionDecision: allow
+            - If result.allowed is False, output contains permissionDecision: deny
+            - If result.modified_input is set, output contains updatedInput
+        """
+        ...
+
+    @abstractmethod
+    def format_completion_response(self, result: CompletionResult) -> HookResponse:
+        """Format a CompletionResult for CLI consumption.
+
+        Postconditions:
+            - HookResponse.output contains contract_valid, anomalies_detected
+            - HookResponse.exit_code is always 0
+        """
+        ...
+
+    @abstractmethod
+    def format_context_response(self, result: ContextResult) -> HookResponse:
+        """Format a ContextResult for CLI consumption."""
+        ...
+
+    @abstractmethod
+    def format_bootstrap_response(self, result: BootstrapResult) -> HookResponse:
+        """Format a BootstrapResult for CLI consumption.
+
+        Returns session bootstrap status for SessionStart events.
+        """
+        ...
+
+    @abstractmethod
+    def adapt_session_start(self, raw: dict) -> BootstrapResult:
+        """Parse SessionStart event and return bootstrap actions.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a SessionStart event
+
+        Postconditions:
+            - Returns BootstrapResult with should_scan and should_refresh set
+              based on session_type
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # P2 event adapters
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def adapt_stop(self, raw: dict) -> QualityResult:
+        """Parse Stop event and assess response quality.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a Stop event
+
+        Postconditions:
+            - Returns QualityResult with quality assessment
+        """
+        ...
+
+    @abstractmethod
+    def adapt_task_completed(self, raw: dict) -> VerificationResult:
+        """Parse TaskCompleted event and verify completion criteria.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a TaskCompleted event
+
+        Postconditions:
+            - Returns VerificationResult with criteria assessment
+        """
+        ...
+
+    @abstractmethod
+    def adapt_subagent_start(self, raw: dict) -> ContextResult:
+        """Parse SubagentStart event and prepare agent context.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a SubagentStart event
+
+        Postconditions:
+            - Returns ContextResult with agent-specific context
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # P2 formatters
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def format_quality_response(self, result: QualityResult) -> HookResponse:
+        """Format a QualityResult for CLI consumption."""
+        ...
+
+    @abstractmethod
+    def format_verification_response(self, result: VerificationResult) -> HookResponse:
+        """Format a VerificationResult for CLI consumption."""
+        ...
+
+    @abstractmethod
+    def detect_channel(self) -> DistributionChannel:
+        """Detect the distribution channel (NPM or PLUGIN).
+
+        Checks environment variables and filesystem layout to determine
+        how gaia-ops was installed.
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # Full hook lifecycle adapters (thin-gate pattern)
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def adapt_pre_tool_use(self, event: HookEvent) -> HookResponse:
+        """Run all pre-tool-use business logic and return a formatted response.
+
+        Orchestrates: routing (bash vs task), validation, state management,
+        context injection, approval handling, and response formatting.
+
+        Preconditions:
+            - event is a parsed HookEvent with event_type PRE_TOOL_USE
+
+        Postconditions:
+            - Returns HookResponse ready for stdout + sys.exit()
+        """
+        ...
+
+    @abstractmethod
+    def adapt_post_tool_use(self, event: HookEvent) -> HookResponse:
+        """Run all post-tool-use business logic and return a formatted response.
+
+        Orchestrates: state retrieval, duration computation, audit logging,
+        T3 grant confirmation, critical event detection, session context
+        writing, and state cleanup.
+
+        Preconditions:
+            - event is a parsed HookEvent with event_type POST_TOOL_USE
+
+        Postconditions:
+            - Returns HookResponse (always exit 0, post-hook never blocks)
+        """
+        ...
+
+    @abstractmethod
+    def adapt_subagent_stop(self, event: HookEvent) -> HookResponse:
+        """Run all subagent-stop business logic and return a formatted response.
+
+        Orchestrates: contract parsing and validation, approval cleanup,
+        context updates, workflow recording, response contract validation,
+        anomaly detection, episodic memory, and result assembly.
+
+        Preconditions:
+            - event is a parsed HookEvent with event_type SUBAGENT_STOP
+
+        Postconditions:
+            - Returns HookResponse (exit 0 for success, exit 2 for contract rejection)
+        """
+        ...

package/dist/gaia-security/hooks/adapters/channel.py

@@ -0,0 +1,17 @@
+"""
+Distribution Channel Detection for Gaia-Ops.
+
+Utility module that detects whether gaia-ops is running as a Claude Code plugin
+or via npm. Used by entry points to log coexistence warnings and by business
+logic to adapt behavior per channel.
+"""
+
+import os
+from pathlib import Path
+
+
+def is_dual_channel_active() -> bool:
+    """Check if both plugin and npm installations exist simultaneously."""
+    has_plugin = bool(os.environ.get("CLAUDE_PLUGIN_ROOT"))
+    has_npm = Path(".claude/hooks").is_symlink()
+    return has_plugin and has_npm