prettyplay 0.0.2__py3-none-any.whl

prettyplay/cache/store.py

@@ -0,0 +1,276 @@
+"""Repository store of cached steps: deterministic addressing, atomic best-effort writes."""
+
+import ast
+import contextlib
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from ..config import Config
+from ..reporting import StepReporter
+from .models import CachedStep, StepIdentity
+
+#: Header constants of a cache file: metadata first, then the step code.
+_HEADER_FIELDS = ("STEP_TEXT", "CACHE_KEY", "STEP_TYPE", "CREATED_AT")
+
+#: Line marking the start of the step code tail; the surrounding newlines keep
+#: the match out of the header (repr escapes newlines, so a raw newline inside
+#: the header literals is impossible) and out of the loaded code.
+_CODE_SENTINEL = "\n# --- step code ---\n"
+
+#: Legacy marker of the step code tail: files written before the sentinel carry
+#: the code starting at ``def step(`` (the old prompt forbade top-level imports).
+_STEP_MARKER = "\ndef step("
+
+#: Replace attempts and backoff for a busy target (Windows keeps the file open).
+_REPLACE_ATTEMPTS = 3
+_REPLACE_BACKOFF_SECONDS = 0.1
+
+
+class StepCache:
+    """The repository store of cache steps: addressing, atomic writes and the read-only mode.
+
+    Attributes:
+        _root: the cache root from the settings (absolute after ``load_config``).
+        _subdir: the optional subdirectory; part of the address, so steps of
+            different subdirectories never collide.
+        _reporter: the visibility point for the cache events.
+        _writable: the lazily probed writability flag; ``None`` until first use.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        path: str | None = None,
+        reporter: StepReporter | None = None,
+    ) -> None:
+        """Keep the settings, the optional subdirectory and the reporter.
+
+        Args:
+            config: project settings; the ``cache_root`` setting is the cache root.
+            path: the optional subdirectory inside the cache; ``None`` — shared root.
+            reporter: the visibility point — cache events go through it; a
+                missing reporter falls back to the hook-less default reporter,
+                so construction and saves never crash on it.
+
+        Raises:
+            ValueError: ``path`` is absolute or escapes the cache root.
+        """
+        self._root = Path(config.cache_root)
+        self._subdir = self._validated_subdir(path)
+        self._reporter = reporter if reporter is not None else StepReporter(hooks=[])
+        self._writable: bool | None = None
+
+    @property
+    def root(self) -> str:
+        """Return the effective cache root."""
+        return str(self._root)
+
+    @property
+    def writable(self) -> bool:
+        """Return whether the cache directory accepts writes.
+
+        Returns:
+            Whether writes are accepted — probed lazily once: the target
+            directory is created, ``os.access`` checked; any ``OSError``
+            counts as read-only.
+        """
+        if self._writable is None:
+            try:
+                target_dir = self._target_dir()
+                target_dir.mkdir(parents=True, exist_ok=True)
+                self._writable = os.access(target_dir, os.W_OK)
+            except OSError:
+                self._writable = False
+
+        return self._writable
+
+    def load(self, identity: StepIdentity) -> CachedStep | None:
+        """Load the cached step by address; any structural damage is a miss, not a failure.
+
+        Args:
+            identity: the address of the step.
+
+        Returns:
+            The cached step, or ``None`` when the file is missing, damaged, or
+            its metadata does not match the address.
+        """
+        target = self._target_dir() / identity.filename
+        if not target.exists():
+            return None
+
+        try:
+            text = target.read_text(encoding="utf-8")
+            fields = _parse_header(text)
+
+            sentinel = text.find(_CODE_SENTINEL)
+            if sentinel != -1:
+                code = text[sentinel + len(_CODE_SENTINEL) :]
+            else:
+                marker = text.find(_STEP_MARKER)  # a file written before the sentinel
+                if marker == -1:
+                    raise KeyError("def step(")
+                code = text[marker + 1 :]
+
+            if fields["CACHE_KEY"] != identity.cache_key or fields["STEP_TYPE"] != identity.step_type:
+                return None
+            if fields["STEP_TEXT"] != identity.normalized_text:
+                return None
+
+            return CachedStep(identity=identity, code=code, created_at=fields["CREATED_AT"])
+        except (ValueError, SyntaxError, KeyError, IndexError, OSError):
+            return None  # cache corruption never cripples the run
+
+    def save(self, step: CachedStep) -> bool:
+        """Store the step atomically, best-effort: no write error ever fails the run.
+
+        Args:
+            step: the working step to store.
+
+        Returns:
+            Whether the step was stored: ``True`` — the atomic replace
+            landed; ``False`` — the write was skipped (a read-only cache or
+            a busy target; the ``on_cache_skipped`` event carries the
+            reason).
+        """
+        if not self.writable:
+            self._emit_skipped(step, "read-only cache")
+            return False
+
+        body = _serialize(step)
+        try:
+            handle, tmp_name = tempfile.mkstemp(dir=self._target_dir(), prefix=".tmp-", suffix=".py")
+        except OSError:
+            self._emit_skipped(step, "cache target busy")
+            return False
+
+        try:
+            with os.fdopen(handle, "w", encoding="utf-8") as tmp_file:
+                tmp_file.write(body)
+                tmp_file.flush()
+                os.fsync(tmp_file.fileno())
+        except (OSError, ValueError):  # ValueError: unencodable text (e.g. surrogates)
+            _remove_quietly(tmp_name)
+            self._emit_skipped(step, "cache target busy")
+            return False
+
+        for _ in range(_REPLACE_ATTEMPTS):
+            try:
+                os.replace(tmp_name, self._target_dir() / step.identity.filename)
+                break
+            except PermissionError:
+                time.sleep(_REPLACE_BACKOFF_SECONDS)  # Windows: target busy
+            except (OSError, ValueError):  # ValueError: unencodable address (e.g. surrogates)
+                _remove_quietly(tmp_name)
+                self._emit_skipped(step, "cache target busy")
+                return False
+        else:
+            _remove_quietly(tmp_name)
+            self._emit_skipped(step, "cache target busy")
+            return False
+
+        self._reporter.emit(
+            "on_cache_saved",
+            {"step_text": step.identity.normalized_text, "filename": step.identity.filename},
+        )
+        return True
+
+    def _target_dir(self) -> Path:
+        """Return the directory holding the steps of this address."""
+        return self._root / self._subdir if self._subdir else self._root
+
+    @staticmethod
+    def _validated_subdir(path: str | None) -> Path | None:
+        """Return the subdirectory path, rejecting addresses outside the cache root.
+
+        Args:
+            path: the integrator-supplied subdirectory; ``None`` — shared root.
+
+        Returns:
+            The validated relative subdirectory, or ``None`` for the shared root.
+
+        Raises:
+            ValueError: the path is absolute or resolves outside the cache root.
+        """
+        if path is None or path == "":
+            return None
+
+        subdir = Path(path)
+
+        if subdir.is_absolute():
+            raise ValueError(f"cache path must be a subdirectory, got absolute {path!r}")
+        if ".." in subdir.parts:
+            raise ValueError(f"cache path must stay inside the cache root, got {path!r}")
+
+        return subdir
+
+    def _emit_skipped(self, step: CachedStep, reason: str) -> None:
+        """Report a skipped write through the visibility point."""
+        self._reporter.emit(
+            "on_cache_skipped",
+            {"step_text": step.identity.normalized_text, "reason": reason},
+        )
+
+
+def _parse_header(text: str) -> dict[str, str]:
+    """Parse the header constants of a cache file into a field map.
+
+    Args:
+        text: the whole cache file text.
+
+    Returns:
+        The map of the header constants found in the module.
+
+    Raises:
+        SyntaxError: the file is not a parseable Python module.
+        ValueError: a header value is not a literal.
+        KeyError: any of the header constants is missing.
+    """
+    module = ast.parse(text)
+
+    fields: dict[str, str] = {}
+    for node in module.body:
+        if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+            continue
+
+        target = node.targets[0]
+
+        if isinstance(target, ast.Name) and target.id in _HEADER_FIELDS:
+            fields[target.id] = ast.literal_eval(node.value)
+
+    missing = [name for name in _HEADER_FIELDS if name not in fields]
+
+    if missing:
+        raise KeyError(", ".join(missing))
+
+    return fields
+
+
+def _serialize(step: CachedStep) -> str:
+    """Serialize a step into the module text: metadata literals, the sentinel line, the code.
+
+    Args:
+        step: the step to serialize.
+
+    Returns:
+        The text of a valid Python module carrying the step: the sentinel
+        line marks where the code tail starts, so ``load`` restores the code
+        verbatim — top-level imports included.
+    """
+    header = "".join(
+        f"{name} = {value!r}\n"
+        for name, value in (
+            ("STEP_TEXT", step.identity.normalized_text),
+            ("CACHE_KEY", step.identity.cache_key),
+            ("STEP_TYPE", step.identity.step_type),
+            ("CREATED_AT", step.created_at),
+        )
+    )
+    return header + _CODE_SENTINEL + step.code + "\n"
+
+
+def _remove_quietly(path: str) -> None:
+    """Remove a temporary file, ignoring a failure: the write is already skipped."""
+    with contextlib.suppress(OSError):
+        Path(path).unlink()

prettyplay/cache/text.py

@@ -0,0 +1,36 @@
+"""Normalization of step sentences for cache identity and addressing."""
+
+import re
+import unicodedata
+
+#: Pattern of any whitespace run, collapsed to a single space by :func:`normalize_step_text`.
+_WHITESPACE_RUN = re.compile(r"\s+")
+
+#: Jinja template markers — any occurrence switches the sentence to verbatim addressing.
+_TEMPLATE_MARKERS = ("{{", "{%", "{#")
+
+
+def normalize_step_text(text: str) -> str:
+    """Normalize a step sentence for identity and addressing — template-aware.
+
+    Args:
+        text: the raw step sentence as written by the engineer.
+
+    Returns:
+        The normalized sentence. A template sentence (containing ``{{``,
+        ``{%`` or ``{#``) keeps its source verbatim except NFC normalization
+        and trimming — Jinja names are case-sensitive and whitespace inside
+        expressions is significant. An ordinary sentence keeps the
+        equivalence pipeline: NFC, trimmed, whitespace runs collapsed,
+        casefolded.
+    """
+    normalized = unicodedata.normalize("NFC", text)
+
+    normalized = normalized.strip()
+
+    if any(marker in normalized for marker in _TEMPLATE_MARKERS):
+        return normalized
+
+    normalized = _WHITESPACE_RUN.sub(" ", normalized)
+
+    return normalized.casefold()

prettyplay/config/.usages/configuration.md

@@ -0,0 +1,246 @@
+# Project configuration
+
+Domain: prettyplay settings. Audience: integrators configuring a test project and CI.
+
+The immutable part of the settings lives in the [tool.prettyplay] section of pyproject.toml. Load it once per test; a test can additionally override specific values programmatically through PrettyConfig.
+
+```toml
+[tool.prettyplay]
+provider = "openai"
+model = "gpt-5"
+generation_model = ""      # optional: empty -> model
+classification_model = ""  # optional: empty -> model
+base_url = ""
+cache_root = ""            # empty -> <cwd>/.prettyplay/cache/
+generation_attempts = 3
+healing_attempts = 2
+llm_request_attempts = 3  # total sends per LLM request; 1 disables request retries
+send_screenshots = false
+strict = false             # replay-only mode; default false
+polling_timeout = 6.0      # None (default) — polling off; 0 — explicit disable; >0 — settle window seconds
+polling_delay = 0.5        # pause between re-executions, seconds
+interactive = false        # opt-in steering REPL; default false
+generation_prompt = ""     # user instructions for generation requests; empty -> no block
+generation_approve = true  # the instruction compliance gate before caching; false -> never runs (the old behavior)
+classification_prompt = "" # user instructions for classification requests; empty -> no block
+
+[tool.prettyplay.browser]
+name = "chromium"          # chromium | firefox | webkit | chrome | msedge
+screen = ""                # "" | WxH | fullscreen | Playwright device name
+headless = true            # false — run with a visible window
+endpoint = ""              # ws endpoint of a remote browser; empty -> local launch
+accept_dialogs = false     # true — accept (else dismiss) dialogs no in-step capture claims, at the run-unit tail
+speed = 100            # pace of the run: 0–100 %, 100 — full speed (default)
+```
+
+## Environment overrides
+
+Every setting has an override for CI — env variable PRETTYPLAY_<SETTING> in upper case; the browser group keeps flat env names:
+
+| Setting | Env override |
+|---|---|
+| provider | PRETTYPLAY_PROVIDER |
+| browser.name | PRETTYPLAY_BROWSER_NAME |
+| browser.screen | PRETTYPLAY_BROWSER_SCREEN |
+| browser.headless | PRETTYPLAY_BROWSER_HEADLESS |
+| browser.endpoint | PRETTYPLAY_BROWSER_ENDPOINT |
+| browser.accept_dialogs | PRETTYPLAY_BROWSER_ACCEPT_DIALOGS |
+| browser.speed | PRETTYPLAY_BROWSER_SPEED |
+| model | PRETTYPLAY_MODEL |
+| generation_model | PRETTYPLAY_GENERATION_MODEL |
+| classification_model | PRETTYPLAY_CLASSIFICATION_MODEL |
+| base_url | PRETTYPLAY_BASE_URL |
+| cache_root | PRETTYPLAY_CACHE_ROOT |
+| generation_attempts | PRETTYPLAY_GENERATION_ATTEMPTS |
+| healing_attempts | PRETTYPLAY_HEALING_ATTEMPTS |
+| llm_request_attempts | PRETTYPLAY_LLM_REQUEST_ATTEMPTS |
+| send_screenshots | PRETTYPLAY_SEND_SCREENSHOTS |
+| strict | PRETTYPLAY_STRICT |
+| polling_timeout | PRETTYPLAY_POLLING_TIMEOUT |
+| polling_delay | PRETTYPLAY_POLLING_DELAY |
+| interactive | PRETTYPLAY_INTERACTIVE |
+| generation_prompt | PRETTYPLAY_GENERATION_PROMPT |
+| generation_approve | PRETTYPLAY_GENERATION_APPROVE |
+| classification_prompt | PRETTYPLAY_CLASSIFICATION_PROMPT |
+
+## Old flat keys are gone — hard break
+
+`browser`, `headless` and `browser_endpoint` at the [tool.prettyplay] level no longer exist (pre-1.0 break). A config carrying them fails loudly at load: the error names each old key and its new home — `browser` → `[tool.prettyplay.browser] name`, `headless` → `[tool.prettyplay.browser] headless`, `browser_endpoint` → `[tool.prettyplay.browser] endpoint`. The removed legacy env name `PRETTYPLAY_BROWSER` is rejected the same way — the error names `PRETTYPLAY_BROWSER_NAME` as its new home. Migrate both the file keys and the env name before upgrading.
+
+## Per-test overrides — layered merge
+
+PrettyConfig is the public name of the full settings model. A config passed to the test object carries only the explicitly set values; everything else resolves from pyproject+env:
+
+```python
+from prettyplay import PrettyPlay, PrettyConfig, BrowserConfig
+
+test = PrettyPlay(
+    cache_key="login-flow",
+    config=PrettyConfig(
+        strict=True,
+        polling_timeout=8.0,
+        interactive=True,
+        browser=BrowserConfig(screen="fullscreen", headless=False),
+    ),
+)
+```
+
+- An explicitly set field wins over pyproject+env; a field left at its default falls back to the file layer
+- The merge reaches inside the nested group: explicitly set fields of a passed BrowserConfig win over the file layer; untouched group defaults never overwrite file values
+- `strict` and `interactive` participate when passed explicitly — an explicit False overrides the file value too
+- `polling_timeout` passed as None is indistinguishable from unset — disable polling for one test with `0.0`
+- File values you did not touch survive: base_url and model set only in pyproject.toml keep working when a config is passed
+- One model — one place of validation: file and programmatic values validate identically
+
+## Settle polling
+
+`polling_timeout` is the total settle horizon of one step execution — the window starts with the first execution of
+the step's code (cached or candidate); the step code's own auto-waits count inside it. A transient failure of a pollable
+kind with time remaining re-executes the same code after `polling_delay` until success or window end — no LLM budget
+is consumed, attempts are visible as settle_retry log records. Locator ambiguity and Python-level errors of the step
+code never poll. Polling is opt-in: the default `None` (and `0`) keeps it off; polling applies in strict replay too —
+re-executing cached code is execution, not generation.
+
+## Request retries of the LLM port
+
+`llm_request_attempts` (default 3, env PRETTYPLAY_LLM_REQUEST_ATTEMPTS, per-test override) caps
+the physical sends of one LLM request — generation, failure classification, group diagnosis and
+the compliance verdict alike: the initial request included, retries of transient provider
+failures (connection, timeout, 408/429, 5xx) happen inside the request with fixed delays and
+never consume generation or healing budgets.
+
+```python
+from prettyplay import PrettyConfig, PrettyPlay
+
+test = PrettyPlay(
+    cache_key="flaky-ci",
+    config=PrettyConfig(llm_request_attempts=5),  # tolerate a longer provider outage
+)
+```
+
+- `1` disables request retries — fully the old single-send behavior
+- a value below `1` fails loudly at configuration load — never a silent ignore
+- the retry delays are fixed policy (1–10 s with jitter and the Retry-After rule) — not
+  configurable; only the attempt count is
+
+## Pace
+
+`speed` of the browser group (a percentage, 0–100 inclusive, default 100) controls how fast the
+browser executes the run: 100 — full speed, exactly the default behavior; lower values slow the
+run down linearly — 0 is the slowest supported pace. It is an ordinary layered setting — file,
+env (PRETTYPLAY_BROWSER_SPEED), per-test override:
+
+```python
+from prettyplay import BrowserConfig, PrettyConfig, PrettyPlay
+
+test = PrettyPlay(
+    cache_key="demo",
+    config=PrettyConfig(browser=BrowserConfig(speed=40)),
+)
+```
+
+- One value per test, fixed for the whole run — it applies at browser start in every launch mode
+  (local headed, local headless, remote connect); replays and strict runs take it identically
+- An out-of-range or malformed value fails at configuration load — the error names the setting,
+  the received value and the allowed range; never a silent ignore
+
+## Interactive steering
+
+`interactive` (default false, env PRETTYPLAY_INTERACTIVE, per-test override) enables the steering REPL: when a step
+terminally fails with IncurableStepError on a non-strict run, a terminal dialog opens showing the step, the failed
+code, the error and the verdict; each engineer message drives one regeneration executed against the live page. Opt-in
+by design — an accidentally enabled REPL must never hang CI. This is the steering dialog of a stuck step; it is
+unrelated to interactive hosts (IPython, Jupyter) — see the library lifecycle docs. The REPL never opens on
+product_defect, in strict replay, or when the LLM is unavailable; quit/EOF/SIGINT/unreadable stdin raises the
+original terminal failure.
+
+## The instruction compliance gate
+
+The user instructions of `generation_prompt` are binding for generated step code: every
+successfully executed candidate passes an independent compliance check before it is
+cached. The gate is the default; switch it off consciously when the extra LLM call per
+successful generation matters more than the enforcement.
+
+```toml
+[tool.prettyplay]
+generation_prompt = "Prefer id attributes for locating elements"
+generation_approve = true   # default; false -> the gate never runs (the old behavior)
+```
+
+Env override (booleans: true/false/1/0, case-insensitive; anything else fails loudly):
+
+```bash
+export PRETTYPLAY_GENERATION_APPROVE=false
+```
+
+Per-test override — an explicit False wins over the file layer:
+
+```python
+config = PrettyConfig(generation_approve=False)
+scenario = PrettyPlay(cache_key="smoke", config=config)
+```
+
+Notes for the engineer:
+- while the gate is on, every successful generation costs one extra LLM call (the verdict
+  request) through the effective classification model
+- a `high` finding fails the attempt and the retry carries the violation text — loud
+  errors instead of silent ignoring
+- changing `generation_prompt` does not invalidate cached steps: the step address stays
+  instruction-free, so purge the cache manually after changing instructions — replayed
+  cached code is never re-gated
+- the gate never runs when `generation_prompt` is empty, regardless of the switch
+
+## Browsers
+
+The browser matrix: chromium, firefox, webkit (Playwright-bundled engines) plus chrome and msedge — channels that launch the locally installed browser through the chromium engine. A channel requires the real browser installed on the machine; a missing browser fails loudly with an actionable message.
+
+## Screen modes
+
+The `screen` field of the browser group is the single size setting:
+
+| Value | Meaning |
+|---|---|
+| "" | Playwright default — the current behavior |
+| 1280x720 | fixed viewport WxH — pinned in every launch mode |
+| fullscreen | the viewport follows the window on a local headed launch — the chromium-family engines (chromium, chrome, msedge) start maximized via `--start-maximized`; firefox and webkit keep the plain window; a fixed 1920x1080 viewport under headless and remote connects (no window exists there) |
+| iPhone 13 | a Playwright device name — mobile emulation via the full descriptor: viewport, user agent, touch, is_mobile, device scale factor |
+
+- WxH and device descriptors apply in every launch mode: local headed, local headless, remote connect
+- An unknown device name fails loudly with an actionable message suggesting close device names; device names resolve against the devices registry of the running Playwright — the package never hard-codes a device list
+- A WxH-shaped value with non-positive numbers fails validation at load; any other string passes through as a device name
+
+## Dialogs
+
+`accept_dialogs` of the browser group controls how the resolver of last resort settles unclaimed dialogs:
+
+- `true` — every dialog that no in-step stock dialog capture claims is accepted
+- `false` (default) — unclaimed dialogs are dismissed (the Playwright default outcome)
+- The resolution runs at the tail of the driver-thread run unit, not at the moment the dialog fires: a dialog unclaimed by the step blocks the page until the unit ends, which can fail the remainder of the step
+- A dialog claimed by a step's in-step stock capture is accepted or dismissed by the step itself — the setting does not apply to captured dialogs
+
+## Strict mode
+
+`strict = true` (env PRETTYPLAY_STRICT, per-test override) switches the run to replay-only: cached code executes honestly and nothing is ever (re)generated. A cache miss fails as an incurable step; a failed cached step is at most classified — never regenerated. Settle polling applies to cached code (re-execution, not generation). Classification is the only LLM call strict mode makes; without LLM access the failure raises immediately by step type.
+
+## Remote execution
+
+A non-empty browser.endpoint switches the test to connecting over the Playwright ws endpoint — a Playwright Server or a hosted browser grid. The endpoint is an address, not a secret: it is valid in the config file; CI rotation goes through the env override. An empty endpoint keeps the local launch; headless does not apply to a connect — window visibility is controlled by the endpoint server.
+
+## Rules
+
+- LLM API keys are never stored in the config file — secrets come only from environment variables: OPENAI_API_KEY for openai, ANTHROPIC_API_KEY for anthropic
+- Invalid configuration fails loudly: ConfigurationError names the setting, the received value and the allowed values; the raw pydantic error stays chained for debugging
+- The provider set: openai, anthropic; the browser name set: chromium, firefox, webkit, chrome, msedge
+- A non-empty browser.endpoint must be a valid ws/wss URL
+- The cache root default: <cwd>/.prettyplay/cache/ — anchored at the working directory of the run, wherever the pyproject.toml was found
+- polling_timeout is None or non-negative; polling_delay is non-negative — violations fail loudly at load
+- generation_prompt reaches generation and regeneration requests only; classification_prompt reaches classification requests only — neither ever invalidates the cache
+
+## Loading
+
+```python
+from prettyplay.config import load_config
+
+config = load_config(pyproject_path=None)  # locates pyproject.toml upwards from the current directory
+print(config.browser.name, config.polling_timeout, config.interactive)
+```

prettyplay/config/__init__.py

@@ -0,0 +1,6 @@
+"""Facade of the prettyplay.config cell: validated project settings."""
+
+from .loader import ConfigurationError, load_config
+from .models import BrowserConfig, Config, PrettyConfig
+
+__all__ = ["BrowserConfig", "Config", "ConfigurationError", "PrettyConfig", "load_config"]