@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/tools/persist_transcript_analysis.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Retroactive transcript analysis: analyze .output files and persist metrics.
+
+Reads all .output transcript files from a session's tasks directory,
+runs analyze() and compute_compliance_score() from transcript_analyzer,
+and appends non-empty results as JSON lines to the episodic-memory metrics file.
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Ensure the hooks package is importable
+PLUGIN_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PLUGIN_ROOT))
+
+from hooks.modules.agents.transcript_analyzer import analyze, compute_compliance_score
+
+SESSION_ID = "5da6ec0a-5471-4af9-b301-794748b21f62"
+TASKS_DIR = Path(
+    f"/tmp/claude-1000/-home-jaguilar-aaxis-qxo/{SESSION_ID}/tasks"
+)
+METRICS_FILE = Path(
+    "/home/jaguilar/aaxis/qxo/.claude/project-context"
+    "/workflow-episodic-memory/metrics.jsonl"
+)
+
+
+def main() -> None:
+    if not TASKS_DIR.exists():
+        print(f"Tasks directory not found: {TASKS_DIR}")
+        sys.exit(1)
+
+    output_files = sorted(TASKS_DIR.glob("*.output"))
+    if not output_files:
+        print("No .output files found.")
+        sys.exit(0)
+
+    METRICS_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    persisted = 0
+
+    with open(METRICS_FILE, "a") as f:
+        for output_path in output_files:
+            task_id = output_path.stem  # filename without .output
+
+            analysis = analyze(str(output_path))
+
+            if analysis.api_call_count == 0:
+                continue
+
+            score = compute_compliance_score(analysis, True, False, 0.5)
+
+            timestamp = analysis.first_timestamp or datetime.now(
+                timezone.utc
+            ).isoformat()
+
+            entry = {
+                "timestamp": timestamp,
+                "session_id": SESSION_ID,
+                "task_id": task_id,
+                "agent": "retroactive-analysis",
+                "source": "transcript_analyzer_retroactive",
+                "input_tokens": analysis.input_tokens,
+                "cache_creation_tokens": analysis.cache_creation_tokens,
+                "cache_read_tokens": analysis.cache_read_tokens,
+                "output_tokens": analysis.output_tokens,
+                "duration_ms": analysis.duration_ms,
+                "tool_call_count": analysis.tool_call_count,
+                "skills_injected": analysis.skills_injected,
+                "model_used": analysis.model,
+                "compliance_score": score.total,
+                "compliance_grade": score.grade,
+                "api_call_count": analysis.api_call_count,
+            }
+
+            f.write(json.dumps(entry, separators=(",", ":")) + "\n")
+            persisted += 1
+
+    print(f"Persisted {persisted} entries to {METRICS_FILE}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/gaia-ops/tools/review/__init__.py

@@ -0,0 +1 @@
+# Review tools for pending update management

package/dist/gaia-ops/tools/review/review_engine.py

@@ -0,0 +1,157 @@
+"""Review engine for managing pending context update suggestions.
+
+This module provides the review logic for pending update suggestions,
+including listing, approving, rejecting, and viewing statistics of
+updates discovered by agents.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Import PendingUpdateStore from the context module
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from context.pending_updates import PendingUpdateStore
+
+
+def review_pending(
+    action: str,
+    update_id: Optional[str] = None,
+    context_path: Optional[Path] = None,
+    store: Optional["PendingUpdateStore"] = None
+) -> dict:
+    """Execute a review action on pending updates.
+
+    Args:
+        action: One of "list", "approve", "reject", "stats"
+        update_id: Required for approve/reject actions
+        context_path: Optional path to project-context.json (for apply)
+        store: Optional PendingUpdateStore instance (for testing)
+
+    Returns:
+        dict: Action-specific results
+
+    Raises:
+        ValueError: If action is invalid or required parameters are missing
+    """
+    valid_actions = {"list", "approve", "reject", "stats"}
+
+    if action not in valid_actions:
+        raise ValueError(
+            f"Invalid action: {action}. Must be one of: {', '.join(sorted(valid_actions))}"
+        )
+
+    # Validate update_id requirement for approve/reject
+    if action in {"approve", "reject"} and not update_id:
+        raise ValueError(f"update_id is required for {action} action")
+
+    # Use provided store or create default
+    if store is None:
+        store = PendingUpdateStore()
+    
+    # Execute action
+    if action == "list":
+        updates = store.list_pending()
+        # Convert dataclass instances to dicts for JSON serialization
+        updates_dict = [
+            {
+                "update_id": u.update_id,
+                "category": u.category,
+                "target_section": u.target_section,
+                "summary": u.summary,
+                "confidence": u.confidence,
+                "source_agent": u.source_agent,
+                "status": u.status,
+                "created_at": u.created_at,
+                "seen_count": u.seen_count,
+            }
+            for u in updates
+        ]
+        return {
+            "action": "list",
+            "updates": updates_dict,
+            "count": len(updates_dict)
+        }
+    
+    elif action == "approve":
+        # Approve the update
+        store.approve(update_id)
+        
+        # Apply the update to project-context.json
+        result = store.apply(update_id, context_path)
+        
+        return {
+            "action": "approve",
+            "update_id": update_id,
+            "applied": result.get("success", False),
+            "result": result
+        }
+    
+    elif action == "reject":
+        store.reject(update_id)
+        return {
+            "action": "reject",
+            "update_id": update_id,
+            "success": True
+        }
+    
+    elif action == "stats":
+        statistics = store.get_statistics()
+        return {
+            "action": "stats",
+            "statistics": statistics
+        }
+
+
+def main():
+    """CLI entry point for review operations."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(
+        description="Review pending context updates"
+    )
+    parser.add_argument(
+        "action",
+        choices=["list", "approve", "reject", "stats"],
+        help="Action to perform"
+    )
+    parser.add_argument(
+        "--update-id",
+        help="Update ID (required for approve/reject)"
+    )
+    parser.add_argument(
+        "--context-path",
+        help="Path to project-context.json"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON (default behavior)"
+    )
+    
+    args = parser.parse_args()
+    
+    try:
+        # Execute review action
+        result = review_pending(
+            args.action,
+            args.update_id,
+            Path(args.context_path) if args.context_path else None
+        )
+        
+        # Output result as JSON
+        print(json.dumps(result, indent=2))
+        
+    except Exception as e:
+        # Output error as JSON
+        error_result = {
+            "error": str(e),
+            "action": args.action
+        }
+        print(json.dumps(error_result, indent=2))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/dist/gaia-ops/tools/scan/__init__.py

@@ -0,0 +1,35 @@
+"""
+Scan Module: Modular project scanner for gaia-ops
+
+This module provides a pluggable scanner system that detects project stack,
+infrastructure, git configuration, tools, orchestration, and environment.
+Each scanner is a pure function (filesystem path -> JSON sections) that runs
+independently and in parallel. The system produces an agnostic project-context.json
+schema that works for any project type.
+
+Main components:
+- BaseScanner: Abstract base class for scanner modules
+- ScannerRegistry: Auto-discovery registry for scanner modules
+- ScanOrchestrator: Parallel scanner execution and result aggregation
+- ScanConfig: Scanner configuration and tool definitions
+"""
+
+import json as _json
+from pathlib import Path as _Path
+
+
+def _read_version() -> str:
+    """Read version from package.json (single source of truth)."""
+    try:
+        pkg_path = _Path(__file__).resolve().parent.parent.parent / "package.json"
+        with open(pkg_path) as f:
+            return _json.load(f)["version"]
+    except Exception:
+        return "unknown"
+
+
+__version__ = _read_version()
+
+__all__ = [
+    "__version__",
+]

package/dist/gaia-ops/tools/scan/config.py

@@ -0,0 +1,247 @@
+"""
+Scanner Configuration Module
+
+Provides ScanConfig for scanner orchestration settings, ToolCategory enum,
+ToolDefinition dataclass, and the default tool definitions list.
+
+Staleness threshold is overridable via GAIA_SCAN_STALENESS_HOURS env var.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional
+
+
+class ToolCategory(Enum):
+    """Tool categories for classification during environment scanning."""
+
+    KUBERNETES = "kubernetes"
+    CLOUD = "cloud"
+    IAC = "iac"
+    CONTAINER = "container"
+    FILE_VIEWER = "file_viewer"
+    FILE_SEARCH = "file_search"
+    GIT = "git"
+    LANGUAGE_RUNTIME = "language_runtime"
+    BUILD = "build"
+    UTILITY = "utility"
+    AI_ASSISTANT = "ai_assistant"
+
+
+@dataclass
+class ToolDefinition:
+    """Definition of a tool to scan for during environment detection.
+
+    Attributes:
+        name: Binary name (e.g., 'kubectl').
+        category: Tool category enum value.
+        version_flag: Flag to get version (default: '--version').
+        version_regex: Regex to extract version from output (None = first line).
+        preference_key: If this tool is a preferred alternative, the preference key.
+        preference_priority: Higher = more preferred (e.g., bat=10, cat=1).
+        extended: If True, only scanned with --full flag (low-value tools).
+    """
+
+    name: str
+    category: ToolCategory
+    version_flag: str = "--version"
+    version_regex: Optional[str] = None
+    preference_key: Optional[str] = None
+    preference_priority: int = 0
+    extended: bool = False
+
+
+@dataclass
+class ScanConfig:
+    """Configuration for the scan orchestrator.
+
+    Attributes:
+        project_root: Absolute path to the project root directory.
+        scanners: List of scanner names to run (empty = all).
+        timeout_per_scanner: Timeout in seconds per scanner (default 10).
+        parallel: Whether to run scanners in parallel (default True).
+        verbose: Print detailed output (default False).
+        output_path: Path to write project-context.json (None = default location).
+        staleness_hours: Hours before a scan is considered stale (default 24).
+    """
+
+    project_root: Path = field(default_factory=lambda: Path.cwd())
+    scanners: List[str] = field(default_factory=list)
+    timeout_per_scanner: int = 10
+    parallel: bool = True
+    verbose: bool = False
+    output_path: Optional[Path] = None
+    staleness_hours: int = 24
+
+    def __post_init__(self) -> None:
+        """Apply environment variable overrides after init."""
+        env_staleness = os.environ.get("GAIA_SCAN_STALENESS_HOURS")
+        if env_staleness is not None:
+            try:
+                self.staleness_hours = int(env_staleness)
+            except ValueError:
+                pass  # Keep default if env var is not a valid integer
+
+
+# Default tool definitions per data-model.md section 5.3
+TOOL_DEFINITIONS: List[ToolDefinition] = [
+    # Kubernetes
+    ToolDefinition(
+        name="kubectl",
+        category=ToolCategory.KUBERNETES,
+        version_flag="version --client",
+        version_regex=r"Client Version:\s*(.+)",
+    ),
+    ToolDefinition(
+        name="helm",
+        category=ToolCategory.KUBERNETES,
+        version_flag="version --short",
+    ),
+    ToolDefinition(name="kustomize", category=ToolCategory.KUBERNETES, extended=True),
+    ToolDefinition(name="k9s", category=ToolCategory.KUBERNETES, extended=True),
+    ToolDefinition(
+        name="stern",
+        category=ToolCategory.KUBERNETES,
+        preference_key="log_viewer",
+        preference_priority=10,
+        extended=True,
+    ),
+    ToolDefinition(name="kubens", category=ToolCategory.KUBERNETES, extended=True),
+    ToolDefinition(name="kubectx", category=ToolCategory.KUBERNETES, extended=True),
+    # Cloud
+    ToolDefinition(name="gcloud", category=ToolCategory.CLOUD),
+    ToolDefinition(name="aws", category=ToolCategory.CLOUD),
+    ToolDefinition(name="az", category=ToolCategory.CLOUD, extended=True),
+    # IaC
+    ToolDefinition(name="terraform", category=ToolCategory.IAC),
+    ToolDefinition(name="terragrunt", category=ToolCategory.IAC),
+    ToolDefinition(name="pulumi", category=ToolCategory.IAC, extended=True),
+    # Container
+    ToolDefinition(
+        name="docker",
+        category=ToolCategory.CONTAINER,
+        preference_key="container_runtime",
+        preference_priority=10,
+    ),
+    ToolDefinition(
+        name="podman",
+        category=ToolCategory.CONTAINER,
+        preference_key="container_runtime",
+        preference_priority=5,
+        extended=True,
+    ),
+    ToolDefinition(
+        name="nerdctl",
+        category=ToolCategory.CONTAINER,
+        preference_key="container_runtime",
+        preference_priority=3,
+        extended=True,
+    ),
+    # File viewing
+    ToolDefinition(
+        name="bat",
+        category=ToolCategory.FILE_VIEWER,
+        preference_key="file_viewer",
+        preference_priority=10,
+        extended=True,
+    ),
+    # File search
+    ToolDefinition(
+        name="fd",
+        category=ToolCategory.FILE_SEARCH,
+        preference_key="file_search",
+        preference_priority=10,
+        extended=True,
+    ),
+    ToolDefinition(
+        name="rg",
+        category=ToolCategory.FILE_SEARCH,
+        preference_key="content_search",
+        preference_priority=10,
+        extended=True,
+    ),
+    ToolDefinition(name="fzf", category=ToolCategory.FILE_SEARCH, extended=True),
+    # Git
+    ToolDefinition(
+        name="gh",
+        category=ToolCategory.GIT,
+        preference_key="git_cli",
+        preference_priority=10,
+    ),
+    ToolDefinition(
+        name="glab",
+        category=ToolCategory.GIT,
+        preference_key="git_cli",
+        preference_priority=10,
+    ),
+    ToolDefinition(name="git", category=ToolCategory.GIT),
+    # Language runtimes
+    ToolDefinition(name="python3", category=ToolCategory.LANGUAGE_RUNTIME),
+    ToolDefinition(name="node", category=ToolCategory.LANGUAGE_RUNTIME),
+    ToolDefinition(name="go", category=ToolCategory.LANGUAGE_RUNTIME),
+    ToolDefinition(name="cargo", category=ToolCategory.LANGUAGE_RUNTIME, extended=True),
+    ToolDefinition(name="rustc", category=ToolCategory.LANGUAGE_RUNTIME, extended=True),
+    ToolDefinition(name="java", category=ToolCategory.LANGUAGE_RUNTIME, extended=True),
+    ToolDefinition(name="ruby", category=ToolCategory.LANGUAGE_RUNTIME, extended=True),
+    ToolDefinition(name="php", category=ToolCategory.LANGUAGE_RUNTIME, extended=True),
+    # Build tools
+    ToolDefinition(name="make", category=ToolCategory.BUILD),
+    ToolDefinition(name="npm", category=ToolCategory.BUILD),
+    ToolDefinition(name="pnpm", category=ToolCategory.BUILD),
+    ToolDefinition(name="yarn", category=ToolCategory.BUILD),
+    ToolDefinition(name="pip", category=ToolCategory.BUILD),
+    ToolDefinition(name="poetry", category=ToolCategory.BUILD, extended=True),
+    ToolDefinition(name="gradle", category=ToolCategory.BUILD, extended=True),
+    ToolDefinition(
+        name="maven", category=ToolCategory.BUILD, version_flag="-version",
+        extended=True,
+    ),
+    # Utilities
+    ToolDefinition(name="jq", category=ToolCategory.UTILITY),
+    ToolDefinition(name="yq", category=ToolCategory.UTILITY),
+    ToolDefinition(name="curl", category=ToolCategory.UTILITY, extended=True),
+    ToolDefinition(name="wget", category=ToolCategory.UTILITY, extended=True),
+    # AI assistants
+    ToolDefinition(name="claude", category=ToolCategory.AI_ASSISTANT),
+]
+
+
+def load_scan_config(project_root: Path) -> ScanConfig:
+    """Load scan configuration from project-context.json if it exists.
+
+    Reads metadata.scan_config from the project context file. Falls back
+    to defaults if the file does not exist or the section is missing.
+
+    Args:
+        project_root: Absolute path to the project root directory.
+
+    Returns:
+        ScanConfig with values from file or defaults.
+    """
+    context_path = project_root / ".claude" / "project-context" / "project-context.json"
+
+    config = ScanConfig(project_root=project_root)
+
+    if context_path.is_file():
+        try:
+            with open(context_path, "r") as f:
+                data = json.load(f)
+
+            scan_config = data.get("metadata", {}).get("scan_config", {})
+
+            if "staleness_hours" in scan_config:
+                config.staleness_hours = int(scan_config["staleness_hours"])
+
+        except (json.JSONDecodeError, ValueError, OSError):
+            pass  # Use defaults on any error
+
+    return config
+
+
+DEFAULT_SCAN_CONFIG = ScanConfig()
+
+# Path to the context-contracts.json file (relative to the gaia-ops-plugin root)
+CONTRACT_CONFIG_PATH = Path(__file__).parent.parent.parent / "config" / "context-contracts.json"