steppy-dev 0.3.0__py3-none-any.whl

steppy/config.py

@@ -0,0 +1,231 @@
+"""Configuration loader for Steppy."""
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from pydantic import ValidationError
+
+from .models import SteppyConfig
+
+
+class ConfigError(Exception):
+    """Raised when configuration is invalid."""
+
+    pass
+
+
+# ${VAR} or ${VAR:-default}. Only ASCII env-var names; the optional ``:-default``
+# supplies a fallback used when the variable is unset.
+_ENV_REF = re.compile(r"\$\{([A-Za-z_]\w*)(?::-([^}]*))?\}")
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge override into base. Override values win.
+
+    NOTE: intentionally mirrored by ``_deep_merge`` in the rendered
+    ``templates/conftest.py.j2`` (and its bundled copy) — that copy is
+    standalone runtime code in each generated project and cannot import from
+    here. Keep the two in sync if the merge semantics ever change.
+    """
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def _interpolate_env(obj: Any, _warnings: Optional[list] = None) -> Any:
+    """Recursively substitute ``${VAR}`` / ``${VAR:-default}`` in every string leaf.
+
+    Resolution per reference: use the env var if set; else the ``:-default`` if
+    that form was used; else leave the literal ``${...}`` in place and record a
+    warning. Keeps secrets out of committed config — put ``${STEPPY_PW}`` in
+    ``config.yaml`` and the real value in the environment.
+    """
+    if isinstance(obj, dict):
+        return {k: _interpolate_env(v, _warnings) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_interpolate_env(v, _warnings) for v in obj]
+    if isinstance(obj, str):
+
+        def _sub(m: "re.Match") -> str:
+            name, default = m.group(1), m.group(2)
+            if name in os.environ:
+                return os.environ[name]
+            if default is not None:
+                return default
+            if _warnings is not None:
+                _warnings.append(
+                    f"environment variable ${{{name}}} referenced in config is not "
+                    f"set; leaving the literal '{m.group(0)}' in place"
+                )
+            return m.group(0)
+
+        return _ENV_REF.sub(_sub, obj)
+    return obj
+
+
+def _check_credential_hygiene(raw_config: dict, _warnings: list) -> None:
+    """Warn when credentials are committed as inline plaintext in config.yaml.
+
+    Runs on the base (pre-interpolation) config: a username/password that is a
+    non-empty literal (not a ``${VAR}`` reference) means a real secret is sitting
+    in a file that is typically committed. The gitignored ``credentials.yaml``
+    overlay or ``${ENV_VAR}`` references are the safe alternatives.
+    """
+    apps = raw_config.get("apps")
+    if not isinstance(apps, dict):
+        return
+    for role, app in apps.items():
+        if not isinstance(app, dict):
+            continue
+        creds = app.get("auth", {}).get("credentials") if isinstance(app.get("auth"), dict) else None
+        if not isinstance(creds, dict):
+            continue
+        for field in ("username", "password", "totp_secret"):
+            value = creds.get(field)
+            if isinstance(value, str) and value and not _ENV_REF.search(value):
+                _warnings.append(
+                    f"app '{role}' has a plaintext {field} in config.yaml. Prefer a "
+                    f"${{ENV_VAR}} reference or the gitignored credentials.yaml overlay "
+                    f"(see SECURITY.md)."
+                )
+
+    _check_tts_key_hygiene(raw_config, _warnings)
+
+
+def _check_tts_key_hygiene(raw_config: dict, _warnings: list) -> None:
+    """Same rule for the video narration provider's API key.
+
+    A cloud TTS key is a billable credential — a committed one is someone else's
+    invoice, not just an access risk.
+    """
+    video = raw_config.get("video")
+    tts = video.get("tts") if isinstance(video, dict) else None
+    if not isinstance(tts, dict):
+        return
+    value = tts.get("api_key")
+    if isinstance(value, str) and value and not _ENV_REF.search(value):
+        _warnings.append(
+            "video.tts.api_key is a plaintext value in config.yaml. Prefer a "
+            "${ENV_VAR} reference or the gitignored credentials.yaml overlay "
+            "(see SECURITY.md) — a cloud TTS key is billable."
+        )
+
+
+def _check_deprecated_output_keys(raw_config: dict, _warnings: list) -> None:
+    """Warn on ``output.reports_dir``, which is accepted but does nothing.
+
+    Kept parseable rather than removed so an existing ``config.yaml`` still
+    loads (``SteppyConfig`` forbids extras), but a key that silently does
+    nothing is precisely the failure FLAWS §4.6 was about — so it says so once
+    per load. ``steppy update --check`` reports the same thing, CI-ably.
+    """
+    output = raw_config.get("output")
+    if isinstance(output, dict) and output.get("reports_dir") is not None:
+        _warnings.append(
+            "output.reports_dir is deprecated and ignored — nothing writes output/reports. "
+            "Playwright traces and videos go to output/traces and output/videos; JUnit and HTML "
+            "reports take their paths from report.junit_xml / report.html. Remove the key."
+        )
+
+
+def _emit_warnings(warnings: list) -> None:
+    """Print collected config warnings to stderr (config.py has no console)."""
+    for w in warnings:
+        print(f"WARNING: {w}", file=sys.stderr)
+
+
+def _load_credentials(config_path: Path) -> Optional[dict]:
+    """Load credentials.yaml from the same directory as config_path, if it exists."""
+    credentials_path = config_path.parent / "credentials.yaml"
+    if not credentials_path.exists():
+        return None
+
+    try:
+        with open(credentials_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Failed to parse YAML in {credentials_path}:\n  {e}")
+    except Exception as e:
+        raise ConfigError(f"Failed to read credentials file: {e}")
+
+    return data if data else None
+
+
+def load_config(config_path: Optional[Path] = None) -> SteppyConfig:
+    """
+    Load and validate the Steppy configuration from config.yaml.
+
+    Args:
+        config_path: Path to config.yaml. If None, looks for config.yaml in current directory.
+
+    Returns:
+        Validated SteppyConfig instance.
+
+    Raises:
+        ConfigError: If config file doesn't exist or is invalid.
+    """
+    if config_path is None:
+        config_path = Path.cwd() / "config.yaml"
+
+    if not config_path.exists():
+        error_msg = f"Configuration file not found: {config_path}\n"
+        error_msg += "\nHint: Create a config.yaml file with your application settings."
+        error_msg += "\n      See STEPPY-REFERENCE.md or the README configuration section."
+        raise ConfigError(error_msg)
+
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            raw_config = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        error_msg = f"Failed to parse YAML in {config_path}:\n"
+        error_msg += f"  {e}\n"
+        error_msg += "\nHint: Check for syntax errors (indentation, quotes, colons)"
+        raise ConfigError(error_msg)
+    except Exception as e:
+        raise ConfigError(f"Failed to read config file: {e}")
+
+    if raw_config is None:
+        error_msg = f"Configuration file is empty: {config_path}\n"
+        error_msg += "\nHint: Add your application configuration to config.yaml"
+        raise ConfigError(error_msg)
+
+    warnings: list = []
+    # Flag plaintext secrets in the committed config *before* they get overlaid
+    # or interpolated (so we only warn about what's literally in config.yaml).
+    _check_credential_hygiene(raw_config, warnings)
+    _check_deprecated_output_keys(raw_config, warnings)
+
+    # Merge credentials from separate file if it exists
+    credentials = _load_credentials(config_path)
+    if credentials:
+        raw_config = _deep_merge(raw_config, credentials)
+
+    # Resolve ${VAR} / ${VAR:-default} references against the environment.
+    raw_config = _interpolate_env(raw_config, warnings)
+
+    _emit_warnings(warnings)
+
+    try:
+        config = SteppyConfig(**raw_config)
+    except ValidationError as e:
+        error_msg = f"Configuration validation failed in {config_path}:\n\n"
+
+        # Extract and format validation errors more clearly
+        for error in e.errors():
+            field = " -> ".join(str(x) for x in error["loc"])
+            msg = error["msg"]
+            error_msg += f"  Field '{field}': {msg}\n"
+
+        error_msg += "\nHint: Check that all required fields are present and have correct types."
+        error_msg += "\n      See STEPPY-REFERENCE.md or the README configuration section."
+        raise ConfigError(error_msg)
+
+    return config

steppy/config_schema.py

@@ -0,0 +1,87 @@
+"""JSON Schema generation for ``config.yaml`` (FLAWS §7.2).
+
+``SteppyConfig`` uses Pydantic ``extra = "forbid"`` everywhere, so any typo in
+``config.yaml`` is a hard failure with no autocomplete. Pydantic hands us the
+antidote for free: dump ``SteppyConfig.model_json_schema()`` to a committed
+``steppy-config.schema.json`` and reference it from the top of ``config.yaml``
+with a ``# yaml-language-server: $schema=...`` line — the VS Code YAML extension
+then provides autocomplete + inline typo squiggles, flipping ``extra="forbid"``
+from hostile to helpful.
+
+This module is the single source of truth for that schema, consumed by both
+``steppy init`` (which writes the schema into a fresh project) and the drift
+guard test (``tests/test_config_schema.py``), so the committed file can never
+silently fall out of sync with the model.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .models import SteppyConfig
+
+# Bumped only when we intentionally change the emitted schema shape (e.g. adopt
+# a newer JSON Schema dialect). Consumers should not care about this value; it
+# exists so a regeneration is an explicit, reviewable diff.
+SCHEMA_TITLE = "Steppy configuration (config.yaml)"
+
+#: Numeric constraint keywords whose value pydantic may emit as ``0`` or ``0.0``
+#: depending on its version. JSON Schema treats the two as the same number.
+_NUMERIC_KEYWORDS = frozenset({"minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"})
+
+
+def _canonicalise(node):
+    """Strip the parts of pydantic's output that vary by pydantic version.
+
+    The committed schema is an *artifact*, and the guard test asserts it matches
+    the models byte for byte — which only means anything if the bytes are a
+    function of the models. They were not: ``pydantic>=2.0.0`` is unbounded, and
+    two things it emits differently across 2.x releases leaked straight into the
+    file, so the guard failed on a machine whose pydantic simply differed from
+    the one that last regenerated it. Neither difference carries meaning:
+
+    * ``additionalProperties: true`` on an open ``dict`` field — ``true`` is the
+      JSON Schema default, so emitting it and omitting it say the same thing.
+    * ``exclusiveMinimum: 0.0`` vs ``0`` — the same number, differently typed.
+
+    Normalising both here makes the artifact reproducible, which is the property
+    a committed generated file needs. Add a rule when a future pydantic
+    introduces another purely-cosmetic difference; do NOT reach for it to paper
+    over a real schema change.
+    """
+    if isinstance(node, dict):
+        out = {}
+        for key, value in node.items():
+            if key == "additionalProperties" and value is True:
+                continue
+            if key in _NUMERIC_KEYWORDS and isinstance(value, float) and value.is_integer():
+                out[key] = int(value)
+                continue
+            out[key] = _canonicalise(value)
+        return out
+    if isinstance(node, list):
+        return [_canonicalise(item) for item in node]
+    return node
+
+
+def generate_config_schema() -> dict:
+    """Return the JSON Schema for ``config.yaml`` as a plain dict.
+
+    Deterministic: same model in ⇒ same bytes out (see :func:`schema_json`), so
+    the drift guard can assert byte-equality against the committed file.
+    """
+    schema = _canonicalise(SteppyConfig.model_json_schema())
+    # A stable, self-describing title so the generated file reads well and the
+    # editor shows something meaningful on hover at the root.
+    schema["title"] = SCHEMA_TITLE
+    return schema
+
+
+def schema_json() -> str:
+    """Return the canonical serialized form written to disk / compared in tests.
+
+    ``sort_keys=True`` + 2-space indent + trailing newline, over a
+    :func:`_canonicalise`-d schema, so the output depends on the models and not
+    on which pydantic 2.x happens to be installed.
+    """
+    return json.dumps(generate_config_schema(), indent=2, sort_keys=True) + "\n"

steppy/contracts/__init__.py

@@ -0,0 +1,54 @@
+"""Versioned wire contracts Steppy shares with anything that consumes its runs.
+
+These are *not* internal types. They are the published shape of what leaves a
+Steppy run — today the results bundle, later the job API — and a consumer at a
+different version of Steppy has to be able to read them. That inverts one house
+rule and is worth stating plainly: every model here is ``extra="allow"``,
+whereas ``models.py`` is ``extra="forbid"``. The config models protect a
+hand-written file, where a typo must fail loudly. These protect a wire format,
+where the requirement is the reverse — a newer producer's extra field must
+survive an older consumer, not crash it.
+
+Compatibility rules, enforced in code rather than by convention:
+
+1. **Additive fields are always allowed**, and unknown ones are preserved.
+2. **Unknown enum-ish values are data, not errors** — an artifact ``kind`` this
+   version has never heard of is stored opaquely rather than failing ingestion.
+3. **A consumer accepts version N and N−1**, expressed as an explicit tuple so
+   a test and an error message can both read it.
+4. **Absent keys default** — inherited from the screenshot sidecars, whose
+   ``device_scale_factor`` is the worked example (absent means 1).
+
+Two contracts live here: ``bundle`` (``manifest.json`` — what a run *produced*)
+and ``report`` (``report.json`` — what a run *means*). Only ``bundle`` is
+re-exported below, because both modules define ``accepts`` and ``schema_json``
+and flattening them would collide; import ``steppy.contracts.report`` directly.
+"""
+
+from .bundle import (
+    ACCEPTED_BUNDLE_VERSIONS,
+    BUNDLE_SCHEMA_VERSION,
+    BundleCoverage,
+    BundleFile,
+    BundleGit,
+    BundleManifest,
+    BundleRun,
+    BundleSpec,
+    BundleTest,
+    accepts,
+    parse_manifest,
+)
+
+__all__ = [
+    "ACCEPTED_BUNDLE_VERSIONS",
+    "BUNDLE_SCHEMA_VERSION",
+    "BundleCoverage",
+    "BundleFile",
+    "BundleGit",
+    "BundleManifest",
+    "BundleRun",
+    "BundleSpec",
+    "BundleTest",
+    "accepts",
+    "parse_manifest",
+]

steppy/contracts/bundle.py

@@ -0,0 +1,215 @@
+"""Results-bundle manifest — contract v1.
+
+A bundle is a ``.tar.zst`` (or ``.tar.gz``) of a subset of a run's ``output/``
+tree **exactly as steppy writes it** — no path rewriting, so an unpacked bundle
+feeds ``steppy guide`` and ``steppy build`` unchanged, and a laptop, a CI runner
+and a remote agent produce identical structures by construction — plus three
+generated members at the archive root::
+
+    manifest.json                 this contract
+    junit.xml                     merged pytest --junitxml (belt and braces)
+    events/
+      <scenario>__<locale>-<layout>.jsonl
+    output/
+      screenshots/<scenario>/[<locale>/][<layout>/]step-NN[-<frame>].png
+      screenshots/.../step-NN[-<frame>].json      sidecars: viewport, DSF, bbox
+      screenshots/_failures/...
+      coverage/raw/<run_id>/<scenario>/<fixture>__<locale-layout>.json
+      coverage/raw/<run_id>/_maps/<sha256>.json.gz
+      failures/<slug>/pytest.log
+      guides/...                                  optional
+
+Producer: ``steppy bundle create``. See :mod:`steppy.contracts` for the
+compatibility rules and why these models are ``extra="allow"``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Bump only on a breaking change. Additive fields never require it.
+BUNDLE_SCHEMA_VERSION = 1
+
+#: What a consumer at this version will read. The N and N−1 rule expressed as
+#: data, so the error message and the test read the same tuple.
+ACCEPTED_BUNDLE_VERSIONS: tuple[int, ...] = (1,)
+
+
+class _Wire(BaseModel):
+    """Base for every wire model: unknown fields are kept, never rejected."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class BundleGit(_Wire):
+    """Where the run's code came from. Every field optional — a laptop run
+    outside a repository has none of it, and that is not an error."""
+
+    sha: Optional[str] = None
+    branch: Optional[str] = None
+    pr: Optional[int] = None
+
+
+class BundleSpec(_Wire):
+    """What the run was asked to do — the ``steppy run`` flags, resolved.
+
+    Recorded by the run itself rather than reconstructed by the bundler: they
+    are separate processes, and re-deriving this from flags a user retypes
+    drifts silently.
+    """
+
+    guide: bool = False
+    no_guide: bool = False
+    no_asserts: bool = False
+    screenshots: bool = False
+    coverage: bool = False
+    locales: list[str] = Field(default_factory=list)
+    layouts: list[str] = Field(default_factory=list)
+    workers: int = 1
+    tag: Optional[Any] = None
+    scenario: Optional[str] = None
+
+
+class BundleRun(_Wire):
+    """Run identity and provenance."""
+
+    run_id: str
+    created_at: str
+    steppy_version: str
+    executor: str = "local"
+    git: BundleGit = Field(default_factory=BundleGit)
+    spec: BundleSpec = Field(default_factory=BundleSpec)
+
+
+class BundleTest(_Wire):
+    """One test result — one (scenario, locale, layout) parametrization.
+
+    ``outcome`` uses the ``STEPPY-EVT`` vocabulary: ``passed|failed|skipped|
+    error`` from a worker, plus ``interrupted`` and ``worker_died``, which a
+    coordinator synthesises for tests that were still in flight. Deliberately
+    a plain ``str`` rather than an enum — rule 2 in :mod:`steppy.contracts`.
+    """
+
+    #: Required, not optional: a Steppy test belongs to a scenario by
+    #: construction. Producers that lack one on a given path derive it from the
+    #: node id's module name (``test_<slug>.py``) rather than emitting null —
+    #: an older consumer types this as a plain ``str`` and rejects the whole
+    #: manifest otherwise.
+    scenario: str
+    nodeid: str
+    outcome: str
+    duration_ms: Optional[int] = None
+    locale: Optional[str] = None
+    layout: Optional[str] = None
+    fail_tail_b64: Optional[str] = None
+    #: 1-based index of the step that was in flight when the test died — the
+    #: scenario's own step number, so it survives steps skipped by ``only-in:``
+    #: or ``layouts:``. Recorded by the env-gated ``STEPPY_STEP_EVENTS`` emitter
+    #: that ``steppy run --bundle`` turns on.
+    #:
+    #: ``None`` is a real answer, not just "unknown": a passing test has no
+    #: failed step, and a test that died in fixture teardown closed every step
+    #: it ran. A producer that was not recording step events also reports
+    #: ``None``, so a consumer that needs to tell the two apart should look for
+    #: ``step-start`` records in ``events/``.
+    failed_step: Optional[int] = None
+
+
+class BundleFile(_Wire):
+    """One archived file, content-addressed.
+
+    ``sha256`` is what makes uploads cheap: with locales × layouts × device
+    scale factors, unchanged screenshots dominate a bundle, so a consumer can
+    ask only for digests it does not already hold.
+    """
+
+    path: str
+    kind: str
+    sha256: str
+    size: int
+    scenario: Optional[str] = None
+    locale: Optional[str] = None
+    layout: Optional[str] = None
+    step: Optional[int] = None
+    #: Multi-frame captures (a tall ``fill-form``) emit ``step-NN-a``, ``-b``, …
+    frame: Optional[str] = None
+
+
+class BundleCoverage(_Wire):
+    """Pointer to the coverage records carried in this bundle.
+
+    ``run_id`` may legitimately differ from ``run.run_id``: a bundle created
+    with an explicit ``--run-id`` names itself after the identity its consumer
+    assigned, while the records on disk keep whatever the run recorded them
+    under.
+    """
+
+    run_id: Optional[str] = None
+    records: int = 0
+
+
+class BundleManifest(_Wire):
+    """The contract."""
+
+    steppy_bundle: int = Field(description="Contract version; see ACCEPTED_BUNDLE_VERSIONS.")
+    run: BundleRun
+    tests: list[BundleTest] = Field(default_factory=list)
+    files: list[BundleFile] = Field(default_factory=list)
+    coverage: Optional[BundleCoverage] = None
+    #: True **only** when a file that belonged in the bundle was dropped to fit
+    #: a size budget. Not set for content the user excluded by flag, and not for
+    #: content that was never produced. The distinction is what lets a consumer
+    #: tell "step 7 never ran" from "we dropped step 7's screenshot".
+    truncated: bool = False
+    #: Human-readable notes from the producer (dropped files, degraded sources).
+    warnings: list[str] = Field(default_factory=list)
+
+    def digests(self) -> set[str]:
+        return {f.sha256 for f in self.files}
+
+    def files_by_kind(self, kind: str) -> list[BundleFile]:
+        return [f for f in self.files if f.kind == kind]
+
+
+SCHEMA_TITLE = "Steppy results bundle manifest"
+
+
+def generate_bundle_schema() -> dict:
+    """JSON Schema for ``manifest.json``, for consumers that are not Python.
+
+    Mirrors :mod:`steppy.config_schema`: generated from the model, committed to
+    the repo, and byte-compared by a drift guard so the published contract can
+    never fall out of sync with what the producer emits.
+    """
+    schema = BundleManifest.model_json_schema()
+    schema["title"] = SCHEMA_TITLE
+    schema["x-steppy-bundle-version"] = BUNDLE_SCHEMA_VERSION
+    schema["x-steppy-bundle-accepted"] = list(ACCEPTED_BUNDLE_VERSIONS)
+    return schema
+
+
+def schema_json() -> str:
+    """The canonical serialized form written to disk and compared in tests."""
+    import json
+
+    return json.dumps(generate_bundle_schema(), indent=2, sort_keys=True) + "\n"
+
+
+def accepts(version: int) -> bool:
+    return version in ACCEPTED_BUNDLE_VERSIONS
+
+
+def parse_manifest(payload: dict[str, Any]) -> BundleManifest:
+    """Validate a ``manifest.json`` payload, with actionable version errors."""
+    version = payload.get("steppy_bundle")
+    if not isinstance(version, int):
+        raise ValueError("manifest.json is missing the integer 'steppy_bundle' contract version")
+    if not accepts(version):
+        supported = ", ".join(f"v{v}" for v in sorted(ACCEPTED_BUNDLE_VERSIONS, reverse=True))
+        raise ValueError(
+            f"bundle contract v{version} is not accepted by this version of steppy (supports {supported}). "
+            "Upgrade the steppy that is reading this bundle, or re-create it with the steppy that wrote it."
+        )
+    return BundleManifest.model_validate(payload)