@jaguilar87/gaia-ops 4.4.0 → 4.7.2

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

@@ -0,0 +1,266 @@
+"""
+Health Check / Verification Functions for gaia-scan
+
+Provides post-install verification checks to confirm that the
+gaia-ops installation is healthy. Used after fresh install (Mode 1)
+and after rescan+sync (Mode 2).
+
+Functions:
+- run_verification: run all checks, return summary
+- check_symlinks: verify symlinks exist and are valid
+- check_claude_md: legacy check (CLAUDE.md no longer generated)
+- check_settings_json: verify valid JSON
+- check_project_context: verify exists and has sections
+- check_python: verify python3 available
+- check_hooks: verify pre_tool_use.py exists
+"""
+
+import json
+import logging
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CheckResult:
+    """Result of a single health check.
+
+    Attributes:
+        name: Check name for display.
+        ok: Whether the check passed.
+        detail: Human-readable detail string.
+        fix: Optional fix suggestion if check failed.
+    """
+    name: str
+    ok: bool
+    detail: str = ""
+    fix: Optional[str] = None
+
+
+def check_symlinks(project_root: Path) -> CheckResult:
+    """Verify that all expected symlinks exist in .claude/.
+
+    Checks for: agents, tools, hooks, commands, templates, config,
+    speckit, skills, CHANGELOG.md (9 total).
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        CheckResult with count of valid symlinks.
+    """
+    names = [
+        "agents", "tools", "hooks", "commands",
+        "templates", "config", "speckit", "skills",
+        "CHANGELOG.md",
+    ]
+    valid = 0
+    for name in names:
+        link_path = project_root / ".claude" / name
+        if link_path.exists() or link_path.is_symlink():
+            valid += 1
+
+    return CheckResult(
+        name="Symlinks",
+        ok=valid == len(names),
+        detail=f"{valid}/{len(names)} valid",
+        fix="Run gaia-scan to recreate symlinks" if valid < len(names) else None,
+    )
+
+
+def check_claude_md(project_root: Path) -> CheckResult:
+    """Check for CLAUDE.md presence. No longer required -- identity injected by hook.
+
+    Kept for backward compatibility with callers that expect this check.
+    """
+    path = project_root / "CLAUDE.md"
+    if path.is_file():
+        return CheckResult(
+            name="CLAUDE.md",
+            ok=True,
+            detail="Present (legacy -- identity now injected by hook)",
+        )
+    return CheckResult(
+        name="CLAUDE.md",
+        ok=True,
+        detail="Not present (identity injected by UserPromptSubmit hook)",
+    )
+
+
+def check_settings_json(project_root: Path) -> CheckResult:
+    """Verify that .claude/settings.json exists and is valid JSON.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        CheckResult.
+    """
+    path = project_root / ".claude" / "settings.json"
+    if not path.is_file():
+        return CheckResult(
+            name="settings.json",
+            ok=False,
+            detail="Missing",
+            fix="Run gaia-scan",
+        )
+
+    try:
+        json.loads(path.read_text())
+        return CheckResult(name="settings.json", ok=True, detail="Valid JSON")
+    except (json.JSONDecodeError, OSError):
+        return CheckResult(
+            name="settings.json",
+            ok=False,
+            detail="Invalid JSON",
+            fix="Delete and run gaia-scan",
+        )
+
+
+def check_project_context(project_root: Path) -> CheckResult:
+    """Verify that project-context.json exists and has sections.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        CheckResult with section count.
+    """
+    path = project_root / ".claude" / "project-context" / "project-context.json"
+    if not path.is_file():
+        return CheckResult(
+            name="project-context",
+            ok=False,
+            detail="Missing",
+            fix="Run gaia-scan",
+        )
+
+    try:
+        data = json.loads(path.read_text())
+        sections = len(data.get("sections", {}))
+        return CheckResult(
+            name="project-context",
+            ok=sections >= 3,
+            detail=f"{sections} sections",
+            fix="Run gaia-scan to regenerate" if sections < 3 else None,
+        )
+    except (json.JSONDecodeError, OSError):
+        return CheckResult(
+            name="project-context",
+            ok=False,
+            detail="Invalid JSON",
+            fix="Run gaia-scan to regenerate",
+        )
+
+
+def check_python() -> CheckResult:
+    """Verify that python3 is available.
+
+    Returns:
+        CheckResult with Python version.
+    """
+    try:
+        result = subprocess.run(
+            ["python3", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            version = result.stdout.strip()
+            return CheckResult(name="Python", ok=True, detail=version)
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+
+    return CheckResult(
+        name="Python",
+        ok=False,
+        detail="Not found",
+        fix="Install Python 3.9+",
+    )
+
+
+def check_hooks(project_root: Path) -> CheckResult:
+    """Verify that pre_tool_use.py hook exists.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        CheckResult.
+    """
+    hook_path = project_root / ".claude" / "hooks" / "pre_tool_use.py"
+    if hook_path.exists():
+        return CheckResult(name="Hooks", ok=True, detail="pre_tool_use.py found")
+
+    return CheckResult(
+        name="Hooks",
+        ok=False,
+        detail="pre_tool_use.py missing",
+        fix="Run gaia-scan to recreate symlinks",
+    )
+
+
+def run_verification(project_root: Path) -> List[CheckResult]:
+    """Run all post-install verification checks.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        List of CheckResult objects (all checks always run).
+    """
+    checks = [
+        check_symlinks(project_root),
+        check_claude_md(project_root),
+        check_settings_json(project_root),
+        check_project_context(project_root),
+        check_python(),
+        check_hooks(project_root),
+    ]
+    return checks
+
+
+def print_verification(results: List[CheckResult]) -> bool:
+    """Print verification results in a human-readable format.
+
+    Args:
+        results: List of CheckResult objects.
+
+    Returns:
+        True if all checks passed.
+    """
+    supports_color = hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+
+    def _green(t: str) -> str:
+        return f"\033[32m{t}\033[0m" if supports_color else t
+
+    def _yellow(t: str) -> str:
+        return f"\033[33m{t}\033[0m" if supports_color else t
+
+    def _red(t: str) -> str:
+        return f"\033[31m{t}\033[0m" if supports_color else t
+
+    def _gray(t: str) -> str:
+        return f"\033[90m{t}\033[0m" if supports_color else t
+
+    print("\n  Verifying installation...\n", file=sys.stderr)
+
+    all_passed = True
+    for r in results:
+        padded = r.name.ljust(18)
+        if r.ok:
+            print(_green(f"    ✓ {padded} {r.detail}"), file=sys.stderr)
+        else:
+            print(_yellow(f"    ⚠ {padded} {r.detail}"), file=sys.stderr)
+            if r.fix:
+                print(_gray(f"      Fix: {r.fix}"), file=sys.stderr)
+            all_passed = False
+
+    print("", file=sys.stderr)
+    return all_passed

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

@@ -0,0 +1,118 @@
+"""
+Filtered os.walk utility for scan performance.
+
+Replaces pathlib.rglob with a single filtered os.walk pass that prunes
+expensive directories (node_modules, .git, .terraform, etc.) before descending.
+"""
+
+import os
+from pathlib import Path
+from typing import FrozenSet, Iterator, Sequence
+
+# Directories to skip during scanning -- shared across all scanners
+SKIP_DIRS: FrozenSet[str] = frozenset({
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".terraform",
+    ".terragrunt-cache",
+    "vendor",
+    "dist",
+    "build",
+    ".venv",
+    "venv",
+    ".cache",
+    ".npm",
+    ".next",
+    ".nuxt",
+    "target",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".tox",
+})
+
+
+def walk_project(root: Path, extensions: Sequence[str]) -> Iterator[Path]:
+    """Walk project tree yielding files matching given extensions.
+
+    Prunes SKIP_DIRS and hidden directories (starting with '.') to avoid
+    descending into expensive subtrees like node_modules or .terraform.
+
+    Much faster than pathlib.rglob on large monorepos because rglob
+    traverses every directory before filtering.
+
+    Args:
+        root: Absolute path to start walking from.
+        extensions: Sequence of file extensions to match (e.g., [".tf", ".hcl"]).
+
+    Yields:
+        Path objects for matching files.
+    """
+    root_str = str(root)
+    ext_set = set(extensions)
+
+    for dirpath, dirnames, filenames in os.walk(root_str):
+        # Prune in-place to prevent os.walk from descending
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in SKIP_DIRS and not d.startswith(".")
+        ]
+
+        for f in filenames:
+            # Check extension by finding the last dot
+            dot_idx = f.rfind(".")
+            if dot_idx >= 0 and f[dot_idx:] in ext_set:
+                yield Path(dirpath) / f
+
+
+def walk_project_prefix(root: Path, prefixes: Sequence[str]) -> Iterator[Path]:
+    """Walk project tree yielding files whose names start with given prefixes.
+
+    Useful for patterns like 'Dockerfile.*' where the prefix is 'Dockerfile.'.
+
+    Args:
+        root: Absolute path to start walking from.
+        prefixes: Sequence of filename prefixes to match.
+
+    Yields:
+        Path objects for matching files.
+    """
+    root_str = str(root)
+
+    for dirpath, dirnames, filenames in os.walk(root_str):
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in SKIP_DIRS and not d.startswith(".")
+        ]
+
+        for f in filenames:
+            if any(f.startswith(p) for p in prefixes):
+                yield Path(dirpath) / f
+
+
+def walk_project_named(root: Path, filenames: Sequence[str]) -> Iterator[Path]:
+    """Walk project tree yielding files matching exact filenames.
+
+    Same pruning as walk_project but matches on exact filename rather than
+    extension. Useful for files like 'Dockerfile', 'Chart.yaml', etc.
+
+    Args:
+        root: Absolute path to start walking from.
+        filenames: Sequence of exact filenames to match.
+
+    Yields:
+        Path objects for matching files.
+    """
+    root_str = str(root)
+    name_set = set(filenames)
+
+    for dirpath, dirnames, fnames in os.walk(root_str):
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in SKIP_DIRS and not d.startswith(".")
+        ]
+
+        for f in fnames:
+            if f in name_set:
+                yield Path(dirpath) / f

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

@@ -0,0 +1,85 @@
+"""
+Workspace Type Detection
+
+Detects whether the scan root is a single-repo, monorepo, or multi-repo workspace.
+Called by the orchestrator before individual scanners run, and importable by scanners
+that need workspace-aware behavior.
+
+Detection logic:
+  - If root has .git -> single-repo or monorepo (determined by stack scanner)
+  - If root has NO .git but 2+ immediate subdirectories have .git -> multi-repo-workspace
+  - Otherwise -> single-repo (default)
+"""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Directories to always skip during workspace scanning
+_SKIP_DIRS = frozenset({
+    "node_modules", "__pycache__", ".tox", ".venv",
+    "venv", "dist", "build", ".next", ".nuxt", "target",
+    ".pytest_cache", ".mypy_cache", ".ruff_cache", "vendor",
+    ".terraform", ".terragrunt-cache",
+})
+
+
+@dataclass(frozen=True)
+class WorkspaceInfo:
+    """Result of workspace type detection.
+
+    Attributes:
+        workspace_type: One of 'single-repo', 'monorepo', 'multi-repo-workspace'.
+        repo_dirs: For multi-repo, list of subdirectory Paths that contain .git.
+                   Empty for single-repo/monorepo.
+    """
+
+    workspace_type: str = "single-repo"
+    repo_dirs: List[Path] = field(default_factory=list)
+
+    @property
+    def is_multi_repo(self) -> bool:
+        return self.workspace_type == "multi-repo-workspace"
+
+
+def detect_workspace_type(root: Path) -> WorkspaceInfo:
+    """Detect the workspace type for the given root directory.
+
+    Args:
+        root: Absolute path to the project root directory.
+
+    Returns:
+        WorkspaceInfo with the detected workspace type and repo directories.
+    """
+    # If root itself has .git, it's a normal repo (single or monorepo)
+    if (root / ".git").is_dir():
+        return WorkspaceInfo(workspace_type="single-repo")
+
+    # Check immediate subdirectories for .git
+    git_subdirs: List[Path] = []
+    try:
+        for entry in sorted(root.iterdir()):
+            if not entry.is_dir():
+                continue
+            if entry.name.startswith(".") or entry.name in _SKIP_DIRS:
+                continue
+            if (entry / ".git").is_dir():
+                git_subdirs.append(entry)
+    except (PermissionError, OSError) as exc:
+        logger.debug("Failed to scan subdirectories of %s: %s", root, exc)
+
+    if len(git_subdirs) >= 2:
+        logger.info(
+            "Multi-repo workspace detected: %d repos in %s",
+            len(git_subdirs),
+            root,
+        )
+        return WorkspaceInfo(
+            workspace_type="multi-repo-workspace",
+            repo_dirs=git_subdirs,
+        )
+
+    return WorkspaceInfo(workspace_type="single-repo")