kernhell 0.1.0__py3-none-any.whl

kernhell/cache/schemas.py

@@ -0,0 +1,42 @@
+"""Schemas for the Semantic Vector Cache."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from kernhell.core.models import SelectorStrategy
+
+
+class CacheEntry(BaseModel):
+    """A verified selector healing record stored in semantic memory."""
+
+    id: str  # Hash of selector + context
+    broken_selector: str
+    new_selector: str
+    strategy: SelectorStrategy = SelectorStrategy.CSS_FALLBACK
+    confidence: float = Field(ge=0.0, le=1.0)
+    context_snippet: str = ""
+    page_url: str = ""
+    test_file: str = ""
+    verified: bool = True
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    hit_count: int = 0
+
+
+class CacheStats(BaseModel):
+    """Aggregate statistics for the semantic vector cache."""
+
+    total_entries: int = 0
+    hits: int = 0
+    misses: int = 0
+
+    @property
+    def hit_ratio(self) -> float:
+        total = self.hits + self.misses
+        if total == 0:
+            return 0.0
+        return round((self.hits / total) * 100, 1)

kernhell/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package — Typer commands and Rich UI helpers."""

kernhell/cli/app.py

@@ -0,0 +1,62 @@
+"""Main CLI application entrypoint for KernHell."""
+
+import sys
+
+if sys.platform == "win32":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+import typer
+from rich.console import Console
+
+from kernhell import __app_name__, __version__
+from kernhell.cli.commands.cache import cache_app
+from kernhell.cli.commands.config import config_app
+from kernhell.cli.commands.dashboard import dashboard_command
+from kernhell.cli.commands.heal import heal_command
+from kernhell.cli.commands.scan import scan_command
+
+console = Console(stderr=True)
+
+app = typer.Typer(
+    name=__app_name__,
+    help="KernHell — AI-Powered Autonomous Self-Healing Testing Engine.\n\n"
+         "'The Heart of Your System Where Innovation Meets Precision'",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+# Register core commands
+app.command(name="scan", help="Scan a test file to detect broken selectors and capture DOM snapshots.")(scan_command)
+app.command(name="heal", help="Autonomously heal broken Playwright selectors in a test file.")(heal_command)
+app.command(name="dashboard", help="Launch the KernHell Mission Control Dashboard and REST API.")(dashboard_command)
+app.command(name="ui", help="Alias for 'dashboard' command.")(dashboard_command)
+app.add_typer(cache_app, name="cache")
+app.add_typer(config_app, name="config")
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        console.print(f"[bold red]KernHell[/bold red] version [cyan]{__version__}[/cyan]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show KernHell version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """KernHell CLI entrypoint callback."""
+    pass
+
+
+if __name__ == "__main__":
+    app()

kernhell/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands package."""

kernhell/cli/commands/cache.py

@@ -0,0 +1,96 @@
+"""CLI commands for managing the Semantic Vector Cache: `kernhell cache <subcommand>`."""
+
+from __future__ import annotations
+
+from typing import Optional
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich import box
+
+from kernhell.cache.cache_manager import CacheManager
+from kernhell.core.config import load_config
+from kernhell.utils.logger import setup_logging
+
+console = Console(stderr=True)
+
+cache_app = typer.Typer(
+    name="cache",
+    help="Inspect, query, and manage KernHell's Semantic Vector Cache.",
+    no_args_is_help=True,
+)
+
+
+@cache_app.command(name="list", help="List all verified healed selector mappings in cache.")
+def list_cache(
+    config_path: Optional[Path] = typer.Option(None, "--config", "-c"),
+) -> None:
+    cfg = load_config(config_path)
+    setup_logging(level=cfg.logging.level)
+    mgr = CacheManager(cfg)
+
+    entries = mgr.list_entries()
+    if not entries:
+        console.print("[yellow]Semantic Cache is currently empty. Run `kernhell heal` to populate.[/yellow]")
+        return
+
+    table = Table(title="🧠 KernHell Semantic Memory Cache", box=box.ROUNDED)
+    table.add_column("Original Selector", style="red")
+    table.add_column("Healed Selector", style="bold green")
+    table.add_column("Strategy", style="cyan")
+    table.add_column("Confidence", justify="right")
+    table.add_column("Hits", justify="right")
+
+    for e in entries:
+        table.add_row(
+            e.broken_selector,
+            e.new_selector,
+            e.strategy.value,
+            f"{int(e.confidence * 100)}%",
+            str(e.hit_count),
+        )
+
+    console.print(table)
+
+
+@cache_app.command(name="stats", help="Show cache hit/miss metrics and efficiency ratio.")
+def stats_cache(
+    config_path: Optional[Path] = typer.Option(None, "--config", "-c"),
+) -> None:
+    cfg = load_config(config_path)
+    setup_logging(level=cfg.logging.level)
+    mgr = CacheManager(cfg)
+
+    stats = mgr.get_stats()
+    table = Table(title="📊 Semantic Memory Metrics", box=box.ROUNDED)
+    table.add_column("Metric", style="bold")
+    table.add_column("Value", justify="right")
+
+    table.add_row("Total Entries", str(stats.total_entries))
+    table.add_row("Cache Hits", f"[bold green]{stats.hits}[/bold green]")
+    table.add_row("Cache Misses", str(stats.misses))
+    table.add_row("Hit Efficiency", f"[bold cyan]{stats.hit_ratio}%[/bold cyan]")
+    table.add_row("Storage Path", str(mgr.storage_dir))
+
+    console.print(table)
+
+
+@cache_app.command(name="clear", help="Purge all entries from the semantic cache.")
+def clear_cache(
+    config_path: Optional[Path] = typer.Option(None, "--config", "-c"),
+    force: bool = typer.Option(False, "--force", "-f", help="Bypass confirmation prompt."),
+) -> None:
+    cfg = load_config(config_path)
+    setup_logging(level=cfg.logging.level)
+    mgr = CacheManager(cfg)
+
+    if not force:
+        confirm = typer.confirm("Are you sure you want to purge the semantic vector cache?")
+        if not confirm:
+            console.print("[dim]Operation cancelled.[/dim]")
+            return
+
+    count = mgr.clear()
+    console.print(f"[bold green]✔ Successfully cleared {count} entries from semantic cache.[/bold green]")

kernhell/cli/commands/config.py

@@ -0,0 +1,111 @@
+"""CLI commands for configuration inspection and setup: `kernhell config <subcommand>`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from kernhell.core.config import KernHellConfig, load_config
+from kernhell.utils.logger import setup_logging
+
+console = Console(stderr=True)
+
+config_app = typer.Typer(
+    name="config",
+    help="View and configure KernHell engine parameters.",
+    no_args_is_help=True,
+)
+
+
+@config_app.command(name="show", help="Display active configuration settings and source paths.")
+def show_config(
+    config_path: Optional[Path] = typer.Option(None, "--config", "-c"),
+) -> None:
+    cfg = load_config(config_path)
+    setup_logging(level=cfg.logging.level)
+
+    table = Table(title="⚙️ KernHell Active Configuration", box=box.ROUNDED)
+    table.add_column("Section", style="bold cyan")
+    table.add_column("Setting", style="yellow")
+    table.add_column("Value")
+
+    # LLM
+    table.add_row("LLM", "Provider", cfg.llm.provider)
+    table.add_row("LLM", "Model", cfg.llm.model)
+    table.add_row("LLM", "API Key", "******" if cfg.llm.api_key else "[dim](not set, using local heuristic)[/dim]")
+    table.add_row("LLM", "Temperature", str(cfg.llm.temperature))
+
+    # Healing
+    table.add_row("Healing", "Confidence Threshold", f"{int(cfg.healing.confidence_threshold * 100)}%")
+    table.add_row("Healing", "Max Heals / File", str(cfg.healing.max_heals_per_file))
+    table.add_row("Healing", "Dry Run Default", str(cfg.healing.dry_run))
+
+    # Cache
+    table.add_row("Cache", "Enabled", str(cfg.cache.enabled))
+    table.add_row("Cache", "Similarity Threshold", f"{int(cfg.cache.similarity_threshold * 100)}%")
+    table.add_row("Cache", "Cache Directory", cfg.cache.cache_dir)
+    table.add_row("Cache", "Embedding Model", cfg.cache.embedding_model)
+
+    # Scanner
+    table.add_row("Scanner", "Browser", cfg.scanner.browser)
+    table.add_row("Scanner", "Timeout (ms)", str(cfg.scanner.timeout_ms))
+    table.add_row("Scanner", "Capture Screenshot", str(cfg.scanner.capture_screenshot))
+
+    console.print(table)
+
+
+@config_app.command(name="init", help="Interactive setup wizard to initialize .kernhellrc.toml.")
+def init_config(
+    target_path: Path = typer.Option(Path(".kernhellrc.toml"), "--path", "-p", help="Target config file path."),
+) -> None:
+    console.print("[bold red]KernHell Engine Configuration Wizard[/bold red]\n")
+
+    provider = typer.prompt("Select LLM Provider (groq, openai, anthropic, ollama)", default="groq")
+    model = typer.prompt(
+        "Default Model Name",
+        default="llama-3.3-70b-versatile" if provider == "groq" else "gpt-4o",
+    )
+    api_key = typer.prompt("LLM API Key (press Enter to skip for local/env)", default="", hide_input=True)
+    confidence = typer.prompt("Confidence Threshold for auto-healing (0.0 to 1.0)", default=0.85, type=float)
+    browser = typer.prompt("Playwright Browser (chromium, firefox, webkit)", default="chromium")
+
+    toml_content = f"""# KernHell Configuration File
+# Generated via `kernhell config init`
+
+[llm]
+provider = "{provider}"
+model = "{model}"
+{"api_key = \"" + api_key + "\"" if api_key else "# api_key = \"\""}
+temperature = 0.1
+max_tokens = 2048
+
+[healing]
+confidence_threshold = {confidence}
+max_heals_per_file = 5
+dry_run = false
+auto_commit = false
+
+[cache]
+enabled = true
+similarity_threshold = 0.92
+cache_dir = "~/.kernhell/cache"
+embedding_model = "all-MiniLM-L6-v2"
+
+[scanner]
+timeout_ms = 5000
+capture_screenshot = true
+browser = "{browser}"
+headless = true
+
+[logging]
+level = "INFO"
+json_output = false
+"""
+
+    target_path.write_text(toml_content.strip() + "\n", encoding="utf-8")
+    console.print(f"\n[bold green]✔ Configuration successfully written to {target_path.resolve()}[/bold green]")

kernhell/cli/commands/dashboard.py

@@ -0,0 +1,55 @@
+"""CLI command: `kernhell dashboard` (or `kernhell ui`).
+
+Launches the local KernHell Mission Control Dashboard and API service.
+"""
+
+from __future__ import annotations
+
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import typer
+import uvicorn
+from rich.console import Console
+from rich.panel import Panel
+
+from kernhell.api.server import create_app
+from kernhell.cli.ui import print_banner
+from kernhell.core.config import load_config
+from kernhell.utils.logger import setup_logging
+
+console = Console(stderr=True)
+
+
+def dashboard_command(
+    host: str = typer.Option("127.0.0.1", "--host", "-h", help="Bind host address."),
+    port: int = typer.Option(8000, "--port", "-p", help="Bind port number."),
+    no_open: bool = typer.Option(False, "--no-open", help="Do not automatically open browser."),
+    config_path: Optional[Path] = typer.Option(None, "--config", "-c"),
+) -> None:
+    """Launch the KernHell Mission Control Dashboard and REST API service."""
+    cfg = load_config(config_path)
+    setup_logging(level=cfg.logging.level)
+
+    print_banner()
+
+    url = f"http://{host}:{port}"
+    web_url = "http://localhost:3000"
+
+    panel_content = (
+        f"[bold cyan]Mission Control API:[/bold cyan] [underline]{url}[/underline]\n"
+        f"[bold cyan]Swagger API Docs:[/bold cyan]    [underline]{url}/docs[/underline]\n"
+        f"[bold cyan]Web Dashboard UI:[/bold cyan]    [underline]{web_url}[/underline]\n\n"
+        f"[dim]Press Ctrl+C to terminate the dashboard server.[/dim]"
+    )
+    console.print(Panel(panel_content, title="🚀 Mission Control Active", border_style="cyan"))
+
+    if not no_open:
+        try:
+            webbrowser.open(f"{url}/docs")
+        except Exception:
+            pass
+
+    app = create_app(cfg)
+    uvicorn.run(app, host=host, port=port, log_level="warning")

kernhell/cli/commands/heal.py

@@ -0,0 +1,141 @@
+"""CLI command: `kernhell heal <test_file_or_directory>`.
+
+Executes tests, intercepts selector failures, and runs the self-healing engine.
+Supports single-file healing and directory-wide batch healing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from kernhell.cli.ui import (
+    print_banner,
+    print_failure_context,
+    print_pruning_stats,
+)
+from kernhell.core.config import load_config
+from kernhell.core.exceptions import (
+    NoFailuresDetectedError,
+    PlaywrightNotInstalledError,
+    ScannerError,
+    TestFileNotFoundError,
+)
+from kernhell.core.models import HealingReport
+from kernhell.core.orchestrator import HealingOrchestrator
+from kernhell.reporter.reporter import HealingReporter
+from kernhell.utils.file_utils import read_file
+from kernhell.utils.logger import setup_logging
+
+console = Console(stderr=True)
+
+
+def heal_command(
+    target: Path = typer.Argument(
+        ...,
+        help="Path to a Playwright test file or directory of test files to heal.",
+        exists=False,
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview healed selectors without mutating test files on disk.",
+    ),
+    output_format: str = typer.Option(
+        "text",
+        "--output",
+        "-o",
+        help="Output format: 'text' (Rich terminal) or 'json' (machine-parseable for CI).",
+    ),
+    output_file: Optional[Path] = typer.Option(
+        None,
+        "--output-file",
+        help="Optional path to save JSON healing report.",
+    ),
+    config_path: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to custom .kernhellrc.toml file.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable detailed debug logs.",
+    ),
+    json_log: bool = typer.Option(
+        False,
+        "--json-log",
+        help="Output structured logs in JSON format.",
+    ),
+) -> None:
+    """Autonomously detect and heal broken Playwright selectors."""
+    cfg = load_config(config_path)
+    log_level = "DEBUG" if verbose else cfg.logging.level
+    setup_logging(level=log_level, json_output=json_log or cfg.logging.json_output)
+
+    if output_format != "json":
+        print_banner()
+
+    if not target.exists():
+        console.print(f"[bold red]Error:[/bold red] Target path not found: {target}")
+        raise typer.Exit(code=1)
+
+    # Discover test files (single file vs batch directory mode)
+    if target.is_dir():
+        test_files = sorted(target.rglob("test_*.py"))
+        if not test_files:
+            console.print(f"[yellow]No 'test_*.py' files found in {target}[/yellow]")
+            raise typer.Exit(code=0)
+    else:
+        test_files = [target]
+
+    orchestrator = HealingOrchestrator(cfg)
+    reports: list[HealingReport] = []
+
+    for test_file in test_files:
+        original_code = read_file(test_file) if test_file.is_file() else ""
+
+        with console.status(f"[bold cyan]Scanning & healing [white]{test_file.name}[/white]..."):
+            try:
+                report = orchestrator.heal(test_file, dry_run=dry_run)
+                reports.append(report)
+            except NoFailuresDetectedError as exc:
+                if output_format != "json":
+                    console.print(f"[bold green]✔[/bold green] {test_file.name}: {exc}")
+                continue
+            except (PlaywrightNotInstalledError, ScannerError, TestFileNotFoundError) as exc:
+                console.print(f"[bold red]Failed on {test_file.name}:[/bold red] {exc}")
+                continue
+
+        if output_format != "json" and report.results:
+            for i, result in enumerate(report.results, start=1):
+                print_failure_context(result.failure, index=i)
+                if result.pruned_dom:
+                    print_pruning_stats(result.pruned_dom)
+                console.print()
+
+            # Render surgical AST diff if file was patched
+            if not dry_run and original_code and test_file.is_file():
+                patched_code = read_file(test_file)
+                if patched_code != original_code:
+                    HealingReporter.render_diff(
+                        old_code=original_code,
+                        new_code=patched_code,
+                        filename=test_file.name,
+                    )
+
+            HealingReporter.print_summary(report)
+
+    # JSON export handling
+    if output_format == "json" or output_file is not None:
+        combined_json = [json_str for report in reports for json_str in [HealingReporter.export_json(report)]]
+        payload = f"[\n{', '.join(combined_json)}\n]"
+        if output_file:
+            output_file.write_text(payload, encoding="utf-8")
+        if output_format == "json":
+            typer.echo(payload)

kernhell/cli/commands/scan.py

@@ -0,0 +1,87 @@
+"""CLI command: `kernhell scan <test_file>`.
+
+Detects broken selectors and captures DOM snapshots without modifying test files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from kernhell.cli.ui import (
+    print_banner,
+    print_failure_context,
+    print_pruning_stats,
+    print_scan_summary,
+)
+from kernhell.core.config import load_config
+from kernhell.core.exceptions import (
+    NoFailuresDetectedError,
+    PlaywrightNotInstalledError,
+    ScannerError,
+    TestFileNotFoundError,
+)
+from kernhell.core.orchestrator import HealingOrchestrator
+from kernhell.utils.logger import setup_logging
+
+console = Console(stderr=True)
+
+
+def scan_command(
+    test_file: Path = typer.Argument(
+        ...,
+        help="Path to the Playwright test file to scan for broken selectors.",
+        exists=False,
+    ),
+    config_path: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to custom .kernhellrc.toml file.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable detailed debug logs.",
+    ),
+    json_log: bool = typer.Option(
+        False,
+        "--json-log",
+        help="Output structured logs in JSON format.",
+    ),
+) -> None:
+    """Scan a Playwright test file, intercepting selector failures and capturing DOM."""
+    cfg = load_config(config_path)
+    log_level = "DEBUG" if verbose else cfg.logging.level
+    setup_logging(level=log_level, json_output=json_log or cfg.logging.json_output)
+
+    print_banner()
+
+    if not test_file.exists():
+        console.print(f"[bold red]Error:[/bold red] Test file not found: {test_file}")
+        raise typer.Exit(code=1)
+
+    orchestrator = HealingOrchestrator(cfg)
+
+    with console.status(f"[bold cyan]Scanning [white]{test_file.name}[/white] for selector failures..."):
+        try:
+            results = orchestrator.scan(test_file)
+        except NoFailuresDetectedError as exc:
+            console.print(f"[bold green]✔[/bold green] {exc}")
+            raise typer.Exit(code=0)
+        except (PlaywrightNotInstalledError, ScannerError, TestFileNotFoundError) as exc:
+            console.print(f"[bold red]Scan Failed:[/bold red] {exc}")
+            raise typer.Exit(code=1)
+
+    failures = [f for f, _ in results]
+    print_scan_summary(failures)
+
+    for i, (failure, pruned) in enumerate(results, start=1):
+        print_failure_context(failure, index=i)
+        if pruned:
+            print_pruning_stats(pruned)
+        console.print()