design-playbook 0.12.0 → 0.13.0

package/design_playbook.py

@@ -0,0 +1,20 @@
+"""Namespace alias: absolute ``design_playbook.*`` imports inside this plugin.
+
+The plugin directory is ``design-playbook`` (hyphen), so Python's import
+system cannot load it under the identifier ``design_playbook`` — FileFinder
+matches directory names literally. This module aliases the package root onto
+``design_playbook.__path__`` so that, once the one bootstrap (ADR-0022) puts
+the package root on ``sys.path``, absolute imports such as
+``design_playbook.mcp.preview.integrity`` and
+``design_playbook.scripts.stages`` resolve to the real ``mcp/`` and
+``scripts/`` trees below.
+
+The alias also keeps the import seam namespaced: a bare ``mcp.*`` import
+would collide with the PyPI ``mcp`` SDK when the host has it installed.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+__path__ = [str(Path(__file__).resolve().parent)]
+__all__: list[str] = []

package/mcp/evidence/capture_contract.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""Capture contract v1 rules, owned by the bundled Evidence runtime.
+
+ADR-0018 enforcement site 1: this module is the single owner of the v1
+contract surface — the write-side parse/normalize authority, the read-side
+full-shape snapshot validator, and the contract-fields JSON Schema fragment
+the provider tool schema composes. The provider (server.py) keeps only
+Runtime Object fields, path/overwrite boundaries, and Playwright I/O; G6
+(scripts/validate_run.py) validates bound manifest request snapshots through
+``validate_capture_snapshot`` instead of hand-written partial checks.
+
+Named ``capture_contract.py`` to avoid collision with
+``scripts/contract_v1.py`` (the persistent contract, ADR-0017).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+CAPTURE_SCHEMA_VERSION = 1
+COLOR_SCHEMES = frozenset({"light", "dark", "no-preference"})
+MIN_VIEWPORT_DPR = 0.1
+RECAPTURE_HINT = "recapture with capture contract schemaVersion=1"
+FREEZE_DEFAULTS = {
+    "enabled": True,
+    "waitFonts": True,
+    "networkIdle": False,
+}
+
+
+@dataclass(frozen=True)
+class CaptureFact:
+    """One host-neutral capture-contract violation (empty facts = valid)."""
+
+    code: str
+    detail: str
+    expected: str = ""
+    actual: str = ""
+
+
+def _is_schema_version(value: object) -> bool:
+    return type(value) is int and value == CAPTURE_SCHEMA_VERSION
+
+
+def _bad_viewport(viewport: dict[str, Any]) -> str | None:
+    """First malformed viewport field, or None when the shape is valid.
+
+    Mirrors the parser's field rules exactly so the read side and write side
+    cannot disagree on what a valid viewport is.
+    """
+    width = viewport.get("width")
+    height = viewport.get("height")
+    dpr = viewport.get("devicePixelRatio")
+    scheme = viewport.get("colorScheme")
+    if type(width) is not int or width < 1:
+        return "viewport.width must be a positive integer"
+    if type(height) is not int or height < 1:
+        return "viewport.height must be a positive integer"
+    if (
+        type(dpr) not in (int, float)
+        or not math.isfinite(dpr)
+        or dpr < MIN_VIEWPORT_DPR
+    ):
+        return (
+            "viewport.devicePixelRatio must be a number greater than or equal "
+            f"to {MIN_VIEWPORT_DPR}"
+        )
+    if not isinstance(scheme, str) or scheme not in COLOR_SCHEMES:
+        return (
+            f"viewport.colorScheme must be one of {sorted(COLOR_SCHEMES)}; "
+            f"got {scheme!r}"
+        )
+    return None
+
+
+def _bad_freeze(freeze: dict[str, Any]) -> str | None:
+    """First malformed freeze field, or None when the shape is valid."""
+    for key in FREEZE_DEFAULTS:
+        if not isinstance(freeze.get(key), bool):
+            return f"freeze.{key} must be a boolean"
+    return None
+
+
+def parse_capture_contract(args: dict[str, Any]) -> dict[str, Any]:
+    """Validate capture contract v1 fields and return a normalized request.
+
+    Write authority (ADR-0018): raises ValueError with a recapture instruction
+    for missing/unknown versions or an incomplete viewport. Pure — no browser
+    side effects. The normalized output is what the provider echoes into the
+    manifest request snapshot, so real snapshots always carry freeze defaults.
+    """
+    if "schemaVersion" not in args:
+        raise ValueError(
+            f"capture contract schemaVersion is required; {RECAPTURE_HINT}"
+        )
+    version = args.get("schemaVersion")
+    if not _is_schema_version(version):
+        raise ValueError(
+            f"unsupported capture schemaVersion {version!r}; {RECAPTURE_HINT}"
+        )
+    viewport = args.get("viewport")
+    if not isinstance(viewport, dict):
+        raise ValueError(
+            f"viewport object is required for schemaVersion=1; {RECAPTURE_HINT}"
+        )
+    bad_viewport = _bad_viewport(viewport)
+    if bad_viewport is not None:
+        raise ValueError(bad_viewport)
+    width = viewport["width"]
+    height = viewport["height"]
+    dpr = viewport["devicePixelRatio"]
+    scheme = viewport["colorScheme"]
+
+    freeze_raw = args.get("freeze")
+    if freeze_raw is None:
+        freeze_raw = {}
+    if not isinstance(freeze_raw, dict):
+        raise ValueError("freeze must be an object when provided")
+    freeze = {
+        key: freeze_raw.get(key, FREEZE_DEFAULTS[key])
+        for key in FREEZE_DEFAULTS
+    }
+    bad_freeze = _bad_freeze(freeze)
+    if bad_freeze is not None:
+        raise ValueError(bad_freeze)
+
+    return {
+        "schemaVersion": CAPTURE_SCHEMA_VERSION,
+        "viewport": {
+            "width": width,
+            "height": height,
+            "devicePixelRatio": float(dpr),
+            "colorScheme": scheme,
+        },
+        "freeze": freeze,
+    }
+
+
+def validate_capture_snapshot(snapshot: object) -> list[CaptureFact]:
+    """Read authority: full-shape validation of a bound manifest snapshot.
+
+    Host-neutral — never raises, returns facts (empty list = valid). Strict on
+    the v1 full shape: schemaVersion=1, a complete typed viewport, and a
+    complete boolean freeze. The parser normalizes defaults at capture time;
+    the read side requires the recorded snapshot to be self-contained so the
+    manifest alone can reproduce the capture (ADR-0018). Malformed viewport
+    shape or missing freeze therefore fail closed (sanctioned correction; was
+    lax in the old hand-written G6 checks). Unknown extra keys are tolerated
+    (host-neutral forward compatibility).
+    """
+    if not isinstance(snapshot, dict):
+        return [CaptureFact(
+            "missing_schema_version",
+            "no request snapshot on the bound entry",
+            expected="schemaVersion=1 with viewport and freeze",
+            actual=("None" if snapshot is None else type(snapshot).__name__),
+        )]
+    version = snapshot.get("schemaVersion")
+    if not _is_schema_version(version):
+        return [CaptureFact(
+            ("missing_schema_version" if version is None
+             else "unsupported_schema_version"),
+            ("missing schemaVersion" if version is None
+             else f"unsupported schemaVersion {version!r}"),
+            expected="schemaVersion=1",
+            actual=repr(version),
+        )]
+    viewport = snapshot.get("viewport")
+    if not isinstance(viewport, dict):
+        return [CaptureFact(
+            "missing_viewport",
+            "viewport object is required for schemaVersion=1",
+            expected="viewport width/height/devicePixelRatio/colorScheme",
+            actual=type(viewport).__name__ if viewport is not None else "missing",
+        )]
+    bad_viewport = _bad_viewport(viewport)
+    if bad_viewport is not None:
+        return [CaptureFact(
+            "bad_viewport_shape",
+            bad_viewport,
+            expected="viewport width/height/devicePixelRatio/colorScheme",
+            actual=bad_viewport,
+        )]
+    freeze = snapshot.get("freeze")
+    if not isinstance(freeze, dict):
+        return [CaptureFact(
+            "missing_freeze",
+            "freeze snapshot is required on the bound entry",
+            expected="freeze enabled/waitFonts/networkIdle booleans",
+            actual=type(freeze).__name__ if freeze is not None else "missing",
+        )]
+    bad_freeze = _bad_freeze(freeze)
+    if bad_freeze is not None:
+        return [CaptureFact(
+            "bad_freeze_shape",
+            bad_freeze,
+            expected="freeze enabled/waitFonts/networkIdle booleans",
+            actual=bad_freeze,
+        )]
+    return []
+
+
+def capture_contract_schema_fragment() -> dict[str, Any]:
+    """JSON Schema fragment for the contract fields (schemaVersion/viewport/freeze).
+
+    The provider composes this into its tool schema alongside its Runtime
+    Object fields. const/enum/required/default all come from the same module
+    constants the parser uses, so the schema and the parser cannot drift.
+    """
+    return {
+        "properties": {
+            "schemaVersion": {
+                "type": "integer",
+                "description": "Capture contract version. Only 1 is supported.",
+                "const": CAPTURE_SCHEMA_VERSION,
+            },
+            "viewport": {
+                "type": "object",
+                "description": (
+                    "Required capture viewport. Provider does not invent "
+                    "desktop defaults."
+                ),
+                "properties": {
+                    "width": {"type": "integer", "minimum": 1},
+                    "height": {"type": "integer", "minimum": 1},
+                    "devicePixelRatio": {
+                        "type": "number",
+                        "minimum": MIN_VIEWPORT_DPR,
+                    },
+                    "colorScheme": {
+                        "type": "string",
+                        "enum": sorted(COLOR_SCHEMES),
+                    },
+                },
+                "required": [
+                    "width",
+                    "height",
+                    "devicePixelRatio",
+                    "colorScheme",
+                ],
+                "additionalProperties": False,
+            },
+            "freeze": {
+                "type": "object",
+                "description": (
+                    "Deterministic freeze controls. Defaults: "
+                    "enabled=true, waitFonts=true, networkIdle=false."
+                ),
+                "properties": {
+                    "enabled": {
+                        "type": "boolean",
+                        "default": FREEZE_DEFAULTS["enabled"],
+                    },
+                    "waitFonts": {
+                        "type": "boolean",
+                        "default": FREEZE_DEFAULTS["waitFonts"],
+                    },
+                    "networkIdle": {
+                        "type": "boolean",
+                        "default": FREEZE_DEFAULTS["networkIdle"],
+                    },
+                },
+                "additionalProperties": False,
+            },
+        },
+        "required": ["schemaVersion", "viewport"],
+    }