@jaguilar87/gaia 5.0.0-rc.2

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"

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

@@ -0,0 +1,212 @@
+"""
+Section-Aware Context Combining Logic
+
+Merges scanner results with existing project-context.json following the
+merge rules from contracts/merge-behavior.md:
+
+  Rule 1: Scanner-owned sections -> full replace
+  Rule 2: Agent-enriched sections -> never touch
+  Rule 3: Mixed sections -> selective update at sub-key level
+  Rule 4: Unknown/user-custom sections -> preserve
+  Rule 5: Metadata -> always update
+
+Note: Backward-compatible sections (project_details, application_architecture,
+development_standards) were removed in v3. Consumers read v2 scanner sections
+directly (project_identity, stack, git, environment, infrastructure).
+
+Special handling for sub-section level ownership: the `environment` section
+is jointly owned by the `tools` scanner (tools, tool_preferences) and the
+`environment` scanner (os, runtimes, env_files). Each scanner replaces only
+its owned sub-keys without clobbering the other scanner's sub-keys.
+
+Contract: specs/002-gaia-scan/contracts/merge-behavior.md
+"""
+
+import copy
+import logging
+from typing import Any, Dict, Optional, Set
+
+from tools.context.deep_merge import deep_merge
+
+logger = logging.getLogger(__name__)
+
+# Sections fully owned by scanners -- replaced entirely on each scan (Rule 1)
+# Top-level sections only; sub-key ownership handled separately
+SCANNER_OWNED_TOP_LEVEL: Dict[str, str] = {
+    "project_identity": "stack",
+    "stack": "stack",
+    "git": "git",
+    "infrastructure": "infrastructure",
+    "orchestration": "orchestration",
+    # "environment" is NOT listed here because it has sub-key ownership
+}
+
+# Sub-key ownership within the `environment` section (Rule 4 / sub-section)
+# Maps environment sub-key -> owning scanner name
+ENVIRONMENT_SUBKEY_OWNERS: Dict[str, str] = {
+    "tools": "tools",
+    "tool_preferences": "tools",
+    "os": "environment",
+    "runtimes": "environment",
+    "env_files": "environment",
+}
+
+# Agent-enriched sections -- never modified by scanners (Rule 2)
+AGENT_ENRICHED_SECTIONS: frozenset = frozenset([
+    "operational_guidelines",
+    "cluster_details",
+    "infrastructure_topology",
+    "monitoring_observability",
+    "architecture_overview",
+    "gcp_services",
+    "workload_identity",
+])
+
+# Mixed sections with partial scanner ownership (Rule 3)
+# Maps section_name -> set of scanner-owned field names
+MIXED_SECTION_SCANNER_FIELDS: Dict[str, Set[str]] = {
+    "terraform_infrastructure": {"layout"},
+    "gitops_configuration": {"repository"},
+    "application_services": {"base_path", "services"},
+}
+
+
+def merge_context(
+    existing: Dict[str, Any],
+    scan_sections: Dict[str, Any],
+    section_owners: Dict[str, str],
+) -> Dict[str, Any]:
+    """Merge scanner results with existing project-context sections.
+
+    Applies the merge rules from contracts/merge-behavior.md to produce
+    the final merged sections dict.
+
+    Args:
+        existing: Current sections from project-context.json (may be empty).
+        scan_sections: Combined sections from all scanners.
+        section_owners: Mapping of section/sub-section name to scanner name,
+                        from ScannerRegistry.get_section_owners().
+
+    Returns:
+        Merged sections dict ready to be written to project-context.json.
+        The merge is deterministic: same inputs always produce the same output.
+    """
+    result = copy.deepcopy(existing)
+
+    # --- Rule 1: Scanner-owned top-level sections -> full replace ---
+    for section_name in SCANNER_OWNED_TOP_LEVEL:
+        if section_name in scan_sections:
+            result[section_name] = copy.deepcopy(scan_sections[section_name])
+
+    # --- Sub-section level ownership for `environment` ---
+    # Both the `tools` scanner and `environment` scanner contribute sub-keys
+    # to the `environment` section. Each scanner's sub-keys replace their owned
+    # portion without clobbering the other scanner's sub-keys.
+    _merge_environment_section(result, scan_sections)
+
+    # --- Rule 2: Agent-enriched sections -> never touch ---
+    # These are already in `result` from the deepcopy of `existing`.
+    # We explicitly do NOT overwrite them, even if a scanner accidentally
+    # produced data for one of these section names.
+    # (No action needed -- they are preserved by the deepcopy.)
+
+    # --- Rule 3: Mixed sections -> selective update ---
+    for section_name, scanner_fields in MIXED_SECTION_SCANNER_FIELDS.items():
+        if section_name in scan_sections:
+            scan_data = scan_sections[section_name]
+            if section_name not in result:
+                result[section_name] = {}
+            # Only update scanner-owned fields; preserve agent fields
+            for field_name in scanner_fields:
+                if field_name in scan_data:
+                    result[section_name][field_name] = copy.deepcopy(
+                        scan_data[field_name]
+                    )
+
+    # --- Rule 5: Unknown/user-custom sections -> preserve ---
+    # Any section in `existing` that is not scanner-owned, not agent-enriched,
+    # not backward-compat, and not mixed is a user-custom section.
+    # These are already preserved by the initial deepcopy of `existing`.
+    # We do NOT add new unknown sections from scan_sections.
+
+    return result
+
+
+def _merge_environment_section(
+    result: Dict[str, Any],
+    scan_sections: Dict[str, Any],
+) -> None:
+    """Merge the `environment` section with sub-key level ownership.
+
+    Two scanners contribute to the `environment` section:
+    - `tools` scanner owns: tools, tool_preferences
+    - `environment` scanner owns: os, runtimes, env_files
+
+    Each scanner's sub-keys replace their owned portion; the other scanner's
+    sub-keys are preserved. The `_source` field gets a combined tag.
+
+    Args:
+        result: The result dict being built (mutated in place).
+        scan_sections: Combined sections from all scanners.
+    """
+    if "environment" not in scan_sections:
+        return
+
+    scan_env = scan_sections["environment"]
+
+    if "environment" not in result:
+        result["environment"] = {}
+
+    env = result["environment"]
+
+    # Replace each sub-key based on ownership
+    for subkey in ENVIRONMENT_SUBKEY_OWNERS:
+        if subkey in scan_env:
+            env[subkey] = copy.deepcopy(scan_env[subkey])
+
+    # Set combined _source tag
+    env["_source"] = "scanner:environment+tools"
+
+
+def collect_scanner_sections(
+    scanner_results: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Collect and combine sections from all scanner results.
+
+    Handles the environment section specially: both `tools` and `environment`
+    scanners produce sub-keys under `environment`, so their outputs are
+    combined into a single `environment` section.
+
+    Args:
+        scanner_results: Mapping of scanner_name -> ScanResult (must have
+                         a `sections` attribute that is a dict).
+
+    Returns:
+        Combined sections dict from all scanners.
+    """
+    combined: Dict[str, Any] = {}
+    environment_parts: Dict[str, Any] = {}
+
+    for _scanner_name, scan_result in scanner_results.items():
+        sections = scan_result.sections if hasattr(scan_result, "sections") else {}
+
+        for section_name, section_data in sections.items():
+            if section_name == "environment":
+                # Merge environment sub-keys from both scanners
+                if isinstance(section_data, dict):
+                    for key, value in section_data.items():
+                        if key != "_source":
+                            environment_parts[key] = value
+            else:
+                # Non-environment sections: direct assignment (last scanner wins,
+                # but each section should have exactly one owner)
+                combined[section_name] = section_data
+
+    # Reassemble environment section if we got any parts
+    if environment_parts:
+        combined["environment"] = {
+            "_source": "scanner:environment+tools",
+            **environment_parts,
+        }
+
+    return combined