misterdev 0.2.0__py3-none-any.whl

misterdev/core/verification/web_verify.py

@@ -0,0 +1,408 @@
+"""Optional headless-browser web verification gate.
+
+A passing build/test suite proves units behave, but not that the assembled web
+artifact actually renders, is free of console errors, meets accessibility
+baselines, or looks like its approved screenshot. This gate drives a real
+headless browser (Playwright, sync API), optionally starting a dev server first,
+loads a URL, runs a list of declarative ``checks`` against the live page, and
+captures a screenshot as REAL evidence (never an LLM self-report).
+
+It mirrors :mod:`misterdev.core.execution.runtime`: strictly opt-in (off
+unless ``runtime.web`` is configured), best-effort, and run in a daemon worker
+thread with a hard timeout so a hung browser or server can NEVER block the build.
+Absent config, a missing Playwright/browser dependency, or a timeout is a SKIP
+(no opinion), not a failure; only a check that genuinely fails (missing element,
+missing text, a console error, an accessibility violation, or a screenshot diff
+beyond threshold) is a RED.
+
+``checks`` is a list of strings drawn from:
+  - ``dom:<selector>``       element matching the CSS selector must be present
+  - ``text:<substring>``     the substring must appear in the page text
+  - ``no-console-errors``    no ``console.error`` / page error may fire
+  - ``axe``                  inject axe-core; fail on any accessibility violation
+  - ``screenshot``           capture and pixel-diff against a stored baseline;
+                             with no baseline, the current shot is seeded and the
+                             check is treated as seeded (SKIP-like), not RED.
+"""
+
+import subprocess
+import time
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from misterdev.core.execution.bounded import run_bounded
+from misterdev.core.execution.outcomes import (
+    GREEN,
+    RED,
+    SKIP,
+    GateOutcome,
+)
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+# Outcome constants. SKIP means "no opinion" (no config, missing dependency, or
+# timeout) and must never be treated as a pass/fail signal by callers.
+# Filename of the captured evidence screenshot, written under ``baseline_dir``
+# (or a temp dir) so a human can inspect what the gate actually saw.
+_EVIDENCE_NAME = "web_verify_evidence.png"
+_BASELINE_NAME = "web_verify_baseline.png"
+
+# Default fraction of differing bytes above which a screenshot check fails. Kept
+# generous: this is a coarse regression tripwire, not a precise visual diff.
+_DEFAULT_SCREENSHOT_THRESHOLD = 0.02
+
+
+class WebResult(GateOutcome):
+    """Outcome of a web verification run. ``status`` is SKIP/GREEN/RED;
+    ``evidence`` is the path to the captured screenshot (or ""); ``checks`` is
+    the per-check outcome list; ``reason`` explains a SKIP/RED."""
+
+    def __init__(
+        self,
+        status: str,
+        evidence: str = "",
+        checks: Optional[List[Tuple[str, str]]] = None,
+        reason: str = "",
+    ):
+        super().__init__(status, reason)
+        self.evidence = evidence
+        self.checks = checks or []
+
+    def __repr__(self) -> str:
+        return f"WebResult(status={self.status!r}, reason={self.reason!r})"
+
+
+def run_web_gate(
+    project_root: Path,
+    web_config: Optional[dict],
+    runner=None,
+) -> WebResult:
+    """Run the web gate described by ``web_config``.
+
+    ``web_config`` keys:
+      - ``url`` (required): the page to load (http(s):// or file://).
+      - ``serve`` (optional): command to start a dev server before loading.
+      - ``ready`` (optional): substring of the server's stdout that signals
+        readiness; without it we just wait briefly for the port.
+      - ``checks`` (optional): list of check strings (see module docstring).
+      - ``baseline_dir`` (optional): where baseline/evidence images live;
+        defaults to ``<project_root>/.orchestrator``.
+      - ``threshold`` (optional): screenshot diff fraction (default 0.02).
+      - ``timeout`` (optional, default 60): hard ceiling for the whole run.
+
+    Returns a :class:`WebResult`. SKIP when there is no config / no ``url``
+    (feature off), when Playwright or its browser is unavailable, or when the
+    hard timeout fires (never blocks). ``runner`` is accepted for symmetry with
+    the gate seam; the browser runs on the host where the dev server's ports
+    live, so it is unused today.
+    """
+    if not web_config or not web_config.get("url"):
+        return WebResult(SKIP, reason="no runtime.web config")
+
+    timeout = float(web_config.get("timeout", 60))
+
+    def _work() -> WebResult:
+        try:
+            return _verify(project_root, web_config, timeout)
+        except Exception as e:  # any browser/server/IO failure is non-fatal
+            logger.debug(f"Web verify gate unavailable: {e}")
+            return WebResult(SKIP, reason=f"error: {e}")
+
+    # A small margin over the inner timeout so a clean inner teardown is
+    # preferred, but the outer bound still guarantees we return.
+    return run_bounded(
+        _work, timeout + 5, WebResult(SKIP, reason="timed out"), "Web verify gate"
+    )
+
+
+def _playwright_sync():
+    """Import Playwright's sync API, or return None if it is unavailable.
+
+    Kept in a dedicated function so it can be monkeypatched in tests and so an
+    absent dependency degrades to SKIP instead of raising.
+    """
+    try:
+        from playwright.sync_api import sync_playwright
+
+        return sync_playwright
+    except Exception as e:  # not installed / broken install -> skip
+        logger.debug(f"Playwright unavailable: {e}")
+        return None
+
+
+def _verify(project_root: Path, web_config: dict, timeout: float) -> WebResult:
+    """Optionally start a server, drive the browser, run checks, tear down."""
+    sync_playwright = _playwright_sync()
+    if sync_playwright is None:
+        return WebResult(SKIP, reason="playwright not installed")
+
+    url = web_config["url"]
+    serve = web_config.get("serve")
+    ready = web_config.get("ready")
+    checks = list(web_config.get("checks") or [])
+    threshold = float(web_config.get("threshold", _DEFAULT_SCREENSHOT_THRESHOLD))
+    baseline_dir = Path(
+        web_config.get("baseline_dir") or (project_root / ".orchestrator")
+    )
+    deadline = time.monotonic() + timeout
+
+    proc = None
+    try:
+        if serve:
+            proc = _start_server(project_root, serve, ready, deadline)
+        return _drive_browser(
+            sync_playwright, url, checks, baseline_dir, threshold, deadline
+        )
+    finally:
+        _terminate(proc)
+
+
+def _start_server(
+    project_root: Path, serve: str, ready: Optional[str], deadline: float
+) -> subprocess.Popen:
+    """Launch the dev server and wait until it signals readiness (or briefly)."""
+    proc = subprocess.Popen(
+        serve,
+        shell=True,
+        cwd=str(project_root),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    if ready:
+        captured: List[str] = []
+        while time.monotonic() < deadline:
+            if "".join(captured).find(ready) != -1:
+                break
+            if proc.poll() is not None:
+                break
+            if proc.stdout is not None:
+                line = proc.stdout.readline()
+                if line:
+                    captured.append(line)
+    else:
+        # No readiness signal: give the server a brief moment to bind its port.
+        time.sleep(min(2.0, max(0.0, deadline - time.monotonic())))
+    return proc
+
+
+def _drive_browser(
+    sync_playwright,
+    url: str,
+    checks: List[str],
+    baseline_dir: Path,
+    threshold: float,
+    deadline: float,
+) -> WebResult:
+    """Load ``url`` headless, run ``checks``, always capture a screenshot."""
+    nav_timeout_ms = max(1, int((deadline - time.monotonic()) * 1000))
+    console_errors: List[str] = []
+    results: List[Tuple[str, str]] = []
+    failures: List[str] = []
+
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch(headless=True)
+        try:
+            page = browser.new_page()
+            page.on("console", lambda msg: _record_console(msg, console_errors))
+            page.on("pageerror", lambda err: console_errors.append(str(err)))
+            page.goto(url, timeout=nav_timeout_ms)
+
+            evidence = _capture_evidence(page, baseline_dir)
+
+            for check in checks:
+                ok, detail = _run_check(
+                    page, check, console_errors, baseline_dir, threshold
+                )
+                results.append((check, detail))
+                if ok is False:
+                    failures.append(f"{check}: {detail}")
+        finally:
+            browser.close()
+
+    if failures:
+        return WebResult(
+            RED, evidence=evidence, checks=results, reason="; ".join(failures)
+        )
+    return WebResult(GREEN, evidence=evidence, checks=results)
+
+
+def _record_console(msg, sink: List[str]) -> None:
+    """Append console.error messages to ``sink`` (best-effort across versions)."""
+    try:
+        msg_type = msg.type if isinstance(msg.type, str) else msg.type()
+    except Exception:
+        msg_type = getattr(msg, "type", "")
+    if msg_type == "error":
+        try:
+            sink.append(msg.text if isinstance(msg.text, str) else msg.text())
+        except Exception:
+            sink.append("console error")
+
+
+def _capture_evidence(page, baseline_dir: Path) -> str:
+    """Write a full-page screenshot under ``baseline_dir`` and return its path."""
+    try:
+        baseline_dir.mkdir(parents=True, exist_ok=True)
+        path = baseline_dir / _EVIDENCE_NAME
+        page.screenshot(path=str(path), full_page=True)
+        return str(path)
+    except Exception as e:
+        logger.debug(f"Could not capture web evidence screenshot: {e}")
+        return ""
+
+
+def _run_check(
+    page,
+    check: str,
+    console_errors: List[str],
+    baseline_dir: Path,
+    threshold: float,
+) -> Tuple[Optional[bool], str]:
+    """Evaluate a single check string. Returns ``(ok, detail)`` where ``ok`` is
+    True/False, or None for a seeded screenshot (treated as non-failing)."""
+    if check.startswith("dom:"):
+        selector = check[len("dom:") :]
+        try:
+            present = page.query_selector(selector) is not None
+        except Exception as e:
+            return False, f"selector error: {e}"
+        return (present, "present" if present else "element not found")
+
+    if check.startswith("text:"):
+        needle = check[len("text:") :]
+        # Match against the rendered, visible body text so a substring that only
+        # occurs inside a tag name or attribute value does not count as present.
+        # Fall back to the raw HTML only if the rendered text can't be read.
+        try:
+            content = page.inner_text("body")
+        except Exception:
+            try:
+                content = page.content()
+            except Exception as e:
+                return False, f"content error: {e}"
+        found = needle in content
+        return (found, "found" if found else "substring not found")
+
+    if check == "no-console-errors":
+        if console_errors:
+            return False, f"{len(console_errors)} console error(s): {console_errors[0]}"
+        return True, "none"
+
+    if check == "axe":
+        return _run_axe(page)
+
+    if check == "screenshot":
+        return _run_screenshot_diff(page, baseline_dir, threshold)
+
+    return False, "unknown check"
+
+
+def _run_axe(page) -> Tuple[bool, str]:
+    """Inject axe-core and run it; fail on any accessibility violation."""
+    try:
+        page.add_script_tag(
+            url="https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js"
+        )
+        result = page.evaluate(
+            "async () => { const r = await axe.run(); "
+            "return r.violations.map(v => v.id); }"
+        )
+    except Exception as e:
+        # axe-core could not be loaded/run (offline, CSP). No opinion -> pass the
+        # individual check rather than failing the build on infrastructure.
+        logger.debug(f"axe-core unavailable: {e}")
+        return True, "axe unavailable (skipped)"
+    violations = list(result or [])
+    if violations:
+        return False, f"{len(violations)} violation(s): {', '.join(violations[:5])}"
+    return True, "no violations"
+
+
+def _run_screenshot_diff(
+    page, baseline_dir: Path, threshold: float
+) -> Tuple[Optional[bool], str]:
+    """Pixel-diff the current screenshot against a stored baseline.
+
+    With no baseline, seed it and return None (seeded, not a failure). Otherwise
+    fail when the differing fraction exceeds ``threshold``.
+    """
+    try:
+        baseline_dir.mkdir(parents=True, exist_ok=True)
+        baseline = baseline_dir / _BASELINE_NAME
+        current_bytes = page.screenshot(full_page=True)
+        if not baseline.exists():
+            baseline.write_bytes(current_bytes)
+            return None, "baseline seeded"
+        baseline_bytes = baseline.read_bytes()
+        diff = _image_diff_fraction(baseline_bytes, current_bytes)
+        if diff > threshold:
+            return False, f"diff {diff:.3f} > threshold {threshold:.3f}"
+        return True, f"diff {diff:.3f} <= threshold {threshold:.3f}"
+    except Exception as e:
+        logger.debug(f"Screenshot diff unavailable: {e}")
+        return True, "screenshot diff unavailable (skipped)"
+
+
+def _image_diff_fraction(a: bytes, b: bytes) -> float:
+    """Fraction of differing pixels between two PNG byte strings.
+
+    Prefers a per-pixel comparison via Pillow (size-normalized). Falls back to a
+    byte-level comparison when Pillow is absent, so the check degrades rather
+    than crashing.
+    """
+    try:
+        import io
+
+        from PIL import Image
+
+        img_a = Image.open(io.BytesIO(a)).convert("RGB")
+        img_b = Image.open(io.BytesIO(b)).convert("RGB")
+        if img_a.size != img_b.size:
+            img_b = img_b.resize(img_a.size)
+        px_a = img_a.load()
+        px_b = img_b.load()
+        width, height = img_a.size
+        if width == 0 or height == 0:
+            return 0.0
+        differing = 0
+        for y in range(height):
+            for x in range(width):
+                if px_a[x, y] != px_b[x, y]:
+                    differing += 1
+        return differing / float(width * height)
+    except Exception as e:
+        logger.debug(f"Pillow diff unavailable, byte-comparing: {e}")
+        return _byte_diff_fraction(a, b)
+
+
+def _byte_diff_fraction(a: bytes, b: bytes) -> float:
+    """Fraction of differing bytes between two byte strings (length-normalized)."""
+    if not a and not b:
+        return 0.0
+    longer = max(len(a), len(b))
+    if longer == 0:
+        return 0.0
+    shorter = min(len(a), len(b))
+    differing = abs(len(a) - len(b))
+    for i in range(shorter):
+        if a[i] != b[i]:
+            differing += 1
+    return differing / float(longer)
+
+
+def _terminate(proc: Optional[subprocess.Popen]) -> None:
+    """Best-effort teardown of the dev server: terminate, then kill if needed."""
+    if proc is None or proc.poll() is not None:
+        return
+    try:
+        proc.terminate()
+        proc.wait(timeout=3)
+    except (subprocess.TimeoutExpired, OSError):
+        try:
+            proc.kill()
+            proc.wait(timeout=3)
+        except (subprocess.TimeoutExpired, OSError):
+            logger.debug("Web dev server did not exit after kill.")

misterdev/environments/base_env.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class BaseEnvironmentManager(ABC):
+    def __init__(self, config: dict, project_path: str | Path):
+        self.config = config
+        self.project_path = Path(project_path)
+
+    @abstractmethod
+    def setup(self) -> bool:
+        """Sets up the environment."""
+        pass
+
+    @abstractmethod
+    def activate_command(self) -> str:
+        """Returns the command snippet to activate the environment."""
+        pass

misterdev/environments/container_env.py

@@ -0,0 +1,87 @@
+"""Container-backed build environment (opt-in).
+
+Selected by ``environment.type: docker`` (or ``container``). Provides a
+:class:`~misterdev.core.execution.container.ContainerEngine` configured for
+the project so gate commands run inside a pinned image. Strictly best-effort:
+if no OCI engine is reachable, :meth:`engine` returns ``None`` and the caller
+runs gates locally exactly as before — the environment never blocks a build.
+
+The image comes from ``environment.image`` when set, otherwise auto-detected
+from the project ``language``. ``environment.engine`` may pin a preferred engine
+(podman/docker/nerdctl/colima); by default detection prefers rootless-first.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from misterdev.core.execution.container import (
+    ContainerEngine,
+    detect_engine,
+    image_for_language,
+)
+from misterdev.environments.base_env import BaseEnvironmentManager
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class ContainerEnvironmentManager(BaseEnvironmentManager):
+    def __init__(
+        self,
+        config: dict,
+        project_path: str | Path,
+        language: str = "",
+        network: Optional[str] = None,
+    ):
+        super().__init__(config, project_path)
+        self.language = language or config.get("language", "")
+        self.image = config.get("image") or image_for_language(self.language)
+        self.preferred_engine = config.get("engine")
+        self.mount_path = config.get("mount_path", "/workspace")
+        # Container egress control from governance.network ("none" disables the
+        # container network). None leaves the engine default unchanged.
+        self.network = network
+        # Optional resource caps for the throwaway container; unset -> no flag.
+        self.memory = config.get("memory")
+        self.cpus = config.get("cpus")
+        self.pids_limit = config.get("pids_limit")
+        # Optional sandbox hardening; unset -> no flag (off path unchanged).
+        self.cap_drop = config.get("cap_drop")
+        self.security_opt = config.get("security_opt")
+        self._engine: Optional[ContainerEngine] = None
+
+    def setup(self) -> bool:
+        """Detect a usable OCI engine. Returns True when one is available, False
+        otherwise (caller falls back to local execution). Never raises."""
+        engine_name = detect_engine(self.preferred_engine)
+        if engine_name is None:
+            logger.info(
+                "No container engine available; gate commands will run locally."
+            )
+            self._engine = None
+            return False
+        logger.info(
+            f"Using container engine '{engine_name}' with image '{self.image}'."
+        )
+        self._engine = ContainerEngine(
+            engine_name,
+            self.image,
+            self.project_path,
+            self.mount_path,
+            network=self.network,
+            memory=self.memory,
+            cpus=self.cpus,
+            pids_limit=self.pids_limit,
+            cap_drop=self.cap_drop,
+            security_opt=self.security_opt,
+        )
+        return True
+
+    def engine(self) -> Optional[ContainerEngine]:
+        """The detected engine (after :meth:`setup`), or ``None`` if none."""
+        return self._engine
+
+    def activate_command(self) -> str:
+        """No host-side activation: the image is the toolchain. The empty prefix
+        means local fallback commands run unmodified."""
+        return ""

misterdev/environments/venv_env.py

@@ -0,0 +1,42 @@
+import subprocess
+from pathlib import Path
+
+from misterdev.environments.base_env import BaseEnvironmentManager
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class VenvEnvironmentManager(BaseEnvironmentManager):
+    def __init__(self, config: dict, project_path: str | Path):
+        super().__init__(config, project_path)
+        self.root_dir = self.config.get("root_dir", ".venv")
+        self.venv_path = self.project_path / self.root_dir
+
+    def setup(self) -> bool:
+        """Sets up the venv if it doesn't exist."""
+        if self.venv_path.exists():
+            logger.info(f"Venv already exists at {self.venv_path}")
+            return True
+
+        logger.info(f"Setting up venv at {self.venv_path}")
+        setup_commands = self.config.get(
+            "setup_commands", [f"python -m venv {self.root_dir}"]
+        )
+
+        for cmd_template in setup_commands:
+            command = cmd_template.format(root_dir=self.root_dir)
+            logger.info(f"Running env setup command: {command}")
+            try:
+                subprocess.run(command, shell=True, cwd=self.project_path, check=True)
+            except subprocess.CalledProcessError as e:
+                logger.error(f"Failed to setup environment: {e}")
+                return False
+        return True
+
+    def activate_command(self) -> str:
+        """Returns the activation command."""
+        activate_script = self.config.get(
+            "activate_script", "source {root_dir}/bin/activate"
+        )
+        return activate_script.format(root_dir=self.root_dir)