design-playbook 0.8.0 → 0.9.0

package/mcp/preview/browser.py

@@ -12,6 +12,7 @@ import html
 import json
 import os
 import re
+import secrets
 import shutil
 import subprocess
 import sys
@@ -23,14 +24,68 @@ from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qs
 
-from confirm import (
-    _DecisionSession,
-    _generate_decision_token,
-    prototype_html_digest,
-)
 from control import _build_control
 from i18n import lang, t
-from util import _log
+from util import _log, prototype_html_digest
+
+
+def _generate_decision_token() -> str:
+    """One-time URL-safe decision token (G5 trust boundary).
+
+    Proves a POST to /decide originated from the trusted parent control bar
+    (which renders the hidden field) rather than from prototype scripts running
+    inside the sandboxed iframe, which cannot read the parent DOM. Bound to a
+    single preview round via :class:`_DecisionSession`.
+    """
+    return secrets.token_urlsafe(32)
+
+
+class _DecisionSession:
+    """First-decision-wins token lock for a single preview round (G5).
+
+    ``validate`` returns ``True`` only for the first POST whose token matches
+    (constant-time) AND whose round matches. Every other POST — missing token,
+    reused token, mismatched round, or wrong token — is rejected so the caller
+    can fail the decision closed. The session grants at most one valid decision.
+    """
+
+    def __init__(self, round_n: int, token: str) -> None:
+        self.round_n = round_n
+        self._token = token
+        self._locked = False
+        self._lock = threading.Lock()
+        self.last_rejection: str = ""
+
+    @property
+    def locked(self) -> bool:
+        return self._locked
+
+    def validate(self, posted_round: int, posted_token: str | None) -> bool:
+        # LOW-1 (secure-ship-0.4.4): the check-then-set on ``_locked`` must
+        # be atomic. ThreadingHTTPServer handles each POST on its own
+        # thread, so two concurrent valid-token POSTs could both pass the
+        # ``if self._locked`` check and each consume the session. Hold the
+        # lock for the whole decision so first-decision-wins holds under
+        # real concurrency; the lock is uncontended in the single-POST
+        # happy path, so the cost is a no-op acquire/release.
+        with self._lock:
+            if not posted_token:
+                self.last_rejection = "missing"
+                return False
+            if posted_round != self.round_n:
+                self.last_rejection = "round_mismatch"
+                return False
+            if self._locked:
+                # First valid decision already consumed the session; every
+                # later POST (even with the correct token) is a replay.
+                self.last_rejection = "reuse"
+                return False
+            if not secrets.compare_digest(posted_token, self._token):
+                self.last_rejection = "invalid_token"
+                return False
+            self._locked = True
+            self.last_rejection = ""
+            return True
 
 
 def _screen_size() -> tuple[int, int]:

package/mcp/preview/server.py

@@ -24,9 +24,12 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from _transport import ToolError, serve_stdio  # noqa: E402
 
 import browser
-from confirm import _self_check_floor
 from i18n import default_options
-from transaction import PreviewTransactionError, run_preview_transaction
+from transaction import (
+    PreviewTransactionError,
+    _self_check_floor,
+    run_preview_transaction,
+)
 
 TOOL_NAME = "preview_prototype"
 

package/mcp/preview/test_browser_control.py

@@ -33,11 +33,11 @@ from urllib.parse import urlencode
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import browser  # noqa: E402
 import control as preview_control  # noqa: E402
-from confirm import (  # noqa: E402
+from browser import (  # noqa: E402
     _DecisionSession,
     _generate_decision_token,
-    prototype_html_digest,
 )
+from util import prototype_html_digest  # noqa: E402
 
 
 # --------------------------------------------------------------------------- #

package/mcp/preview/transaction.py

@@ -17,20 +17,97 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Callable, Iterator
 
-from confirm import (
-    _check_feedback_floor,
-    _ensure_prototype,
-    _preview_dir_for,
-    prototype_html_digest,
-)
 from control import _format_feedback
 from i18n import CONFIRM_LABELS
-from util import _now_iso
+from util import _now_iso, prototype_html_digest
 
 BrowserCollector = Callable[[Path, str, list[str], int], dict[str, Any]]
 ENTRY_SCHEMA_VERSION = 1
 
 
+def _preview_dir_for(path: Path | None) -> Path:
+    if path is not None:
+        return path.parent
+    scratch = Path.cwd() / ".scratch" / "preview-adapter" / "preview"
+    scratch.mkdir(parents=True, exist_ok=True)
+    return scratch
+
+
+def _ensure_prototype(path_arg: str | None, html: str | None, round_n: int,
+                      preview_dir: Path) -> Path:
+    if path_arg:
+        p = Path(path_arg)
+        if not p.is_file():
+            raise ValueError(f"prototype path does not exist: {path_arg}")
+        return p
+    if not html:
+        raise ValueError("path or html is required")
+    preview_dir.mkdir(parents=True, exist_ok=True)
+    target = preview_dir / f"round-{round_n}.html"
+    target.write_text(html, encoding="utf-8")
+    return target
+
+
+def _check_feedback_floor(feedback: str,
+                          anchors: list[dict[str, Any]]) -> tuple[bool, str]:
+    """ADR-0008 preview feedback floor (structural, machine-checkable).
+
+    Passes when:
+    - (non-empty feedback OR >=1 anchor present) as trigger, AND
+    - every present anchor (if any) has non-empty selector AND non-empty comment.
+
+    Deliberately structural, no minimum length: short CJK feedback like
+    "太挤了" is substantive; semantic junk (ADR-0008's "安师大" case) is
+    ui-evaluator's job (G6), not the floor's.
+    Returns (floor_pass, floor_failure_reason).
+    """
+    feedback = (feedback or "").strip()
+    trigger = bool(feedback) or bool(anchors)
+    if not trigger:
+        return False, "confirm with no substantive feedback: empty feedback and no anchor"
+    if anchors:
+        for a in anchors:
+            if not isinstance(a, dict):
+                return False, "anchor is not an object"
+            sel = str(a.get("selector") or "").strip()
+            note = str(a.get("comment") or "").strip()
+            if not sel or not note:
+                return False, (
+                    "anchor missing non-empty selector and comment: "
+                    f"selector={sel!r} comment={note!r}")
+    return True, ""
+
+
+def _self_check_floor() -> None:
+    """ADR-0008 floor branch logic self-check (ponytail: one runnable check)."""
+    cases = [
+        ("empty + no anchors", "", [], False),
+        ("whitespace-only feedback", "   \n  ", [], False),
+        ("short feedback passes (structural floor)", "ok", [], True),
+        ("short CJK feedback passes ('太挤了' is substantive)", "太挤了", [], True),
+        ("'安师大' passes floor; semantic junk is G6's job (ADR-0008)", "安师大", [], True),
+        ("longer feedback passes", "fix it", [], True),
+        ("anchor with comment", "", [{"selector": "h2", "comment": "x"}], True),
+        ("anchor no comment (0015 garbage)", "",
+         [{"selector": "h2", "comment": ""}], False),
+        ("anchor empty selector", "",
+         [{"selector": "", "comment": "x"}], False),
+        ("non-dict anchor", "", ["not-a-dict"], False),
+        ("feedback + incomplete anchor still fails", "ok",
+         [{"selector": "h2", "comment": ""}], False),
+        ("two anchors one incomplete fails", "",
+         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": ""}], False),
+        ("two anchors both complete passes", "",
+         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": "y"}], True),
+        ("short feedback + good anchor passes", "hi",
+         [{"selector": "h2", "comment": "x"}], True),
+    ]
+    for label, fb, anc, want in cases:
+        got, _ = _check_feedback_floor(fb, anc)
+        assert got == want, f"{label}: want {want}, got {got}"
+    print("FLOOR SELF-CHECK PASSED")
+
+
 class PreviewTransactionError(ValueError):
     """Recoverable transaction failure with actionable artifact context."""
 

package/mcp/preview/util.py

@@ -1,10 +1,11 @@
-"""Shared leaf helpers for the preview adapter (logging, timestamps).
+"""Shared leaf helpers for the preview adapter (logging, timestamps, digest).
 
-Sibling to i18n.py; imported by server.py, browser.py, confirm.py.
+Sibling to i18n.py; imported by server.py, browser.py, transaction.py.
 No third-party deps.
 """
 from __future__ import annotations
 
+import hashlib
 import sys
 from datetime import datetime, timezone
 
@@ -13,6 +14,21 @@ def _log(msg: str) -> None:
     print(msg, file=sys.stderr, flush=True)
 
 
+def prototype_html_digest(raw: bytes) -> str:
+    """SHA-256 of prototype bytes with newlines normalized to LF.
+
+    Windows ``core.autocrlf`` rewrites working-tree bytes on checkout; a raw
+    digest then disagrees between the machine that wrote the confirm record
+    and a Linux CI runner validating the same git blob. Line-ending noise is
+    not a prototype content change for G5 integrity (issue 02 / T01).
+
+    Must stay in lockstep with ``scripts/_preview_integrity.prototype_html_digest``.
+    """
+    return hashlib.sha256(
+        raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+    ).hexdigest()
+
+
 
 def _now_iso() -> str:
     return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-playbook",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Design I/O for coding agents: controllable UI generation via declarations (spec/domain/craft/design/components/template) and contracts (skill/evaluator). Use for product UI—console, dashboard, agent-ops, CJK-first apps.",
   "keywords": [
     "pi-package",

package/mcp/preview/confirm.py

@@ -1,183 +0,0 @@
-"""ADR-0008 floor logic, G5 trust token, and prototype target resolution.
-
-Sibling module split from server.py; behavior unchanged. Holds the
-feedback-floor check, the G5 one-time decision token + first-decision-wins
-session, the prototype html digest primitive, and the ``--self-check``
-floor cases.
-"""
-from __future__ import annotations
-
-import hashlib
-import secrets
-import sys
-import threading
-from pathlib import Path
-from typing import Any
-
-
-def prototype_html_digest(raw: bytes) -> str:
-    """SHA-256 of prototype bytes with newlines normalized to LF.
-
-    Windows ``core.autocrlf`` rewrites working-tree bytes on checkout; a raw
-    digest then disagrees between the machine that wrote the confirm record
-    and a Linux CI runner validating the same git blob. Line-ending noise is
-    not a prototype content change for G5 integrity (issue 02 / T01).
-
-    Must stay in lockstep with ``scripts/_preview_integrity.prototype_html_digest``.
-    """
-    return hashlib.sha256(
-        raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
-    ).hexdigest()
-
-
-def _preview_dir_for(path: Path | None) -> Path:
-    if path is not None:
-        return path.parent
-    scratch = Path.cwd() / ".scratch" / "preview-adapter" / "preview"
-    scratch.mkdir(parents=True, exist_ok=True)
-    return scratch
-
-
-
-def _ensure_prototype(path_arg: str | None, html: str | None, round_n: int,
-                      preview_dir: Path) -> Path:
-    if path_arg:
-        p = Path(path_arg)
-        if not p.is_file():
-            raise ValueError(f"prototype path does not exist: {path_arg}")
-        return p
-    if not html:
-        raise ValueError("path or html is required")
-    preview_dir.mkdir(parents=True, exist_ok=True)
-    target = preview_dir / f"round-{round_n}.html"
-    target.write_text(html, encoding="utf-8")
-    return target
-
-
-def _check_feedback_floor(feedback: str,
-                          anchors: list[dict[str, Any]]) -> tuple[bool, str]:
-    """ADR-0008 preview feedback floor (structural, machine-checkable).
-
-    Passes when:
-    - (non-empty feedback OR >=1 anchor present) as trigger, AND
-    - every present anchor (if any) has non-empty selector AND non-empty comment.
-
-    Deliberately structural, no minimum length: short CJK feedback like
-    "太挤了" is substantive; semantic junk (ADR-0008's "安师大" case) is
-    ui-evaluator's job (G6), not the floor's.
-    Returns (floor_pass, floor_failure_reason).
-    """
-    feedback = (feedback or "").strip()
-    trigger = bool(feedback) or bool(anchors)
-    if not trigger:
-        return False, "confirm with no substantive feedback: empty feedback and no anchor"
-    if anchors:
-        for a in anchors:
-            if not isinstance(a, dict):
-                return False, "anchor is not an object"
-            sel = str(a.get("selector") or "").strip()
-            note = str(a.get("comment") or "").strip()
-            if not sel or not note:
-                return False, (
-                    "anchor missing non-empty selector and comment: "
-                    f"selector={sel!r} comment={note!r}")
-    return True, ""
-
-
-
-def _generate_decision_token() -> str:
-    """One-time URL-safe decision token (G5 trust boundary).
-
-    Proves a POST to /decide originated from the trusted parent control bar
-    (which renders the hidden field) rather than from prototype scripts running
-    inside the sandboxed iframe, which cannot read the parent DOM. Bound to a
-    single preview round via :class:`_DecisionSession`.
-    """
-    return secrets.token_urlsafe(32)
-
-
-class _DecisionSession:
-    """First-decision-wins token lock for a single preview round (G5).
-
-    ``validate`` returns ``True`` only for the first POST whose token matches
-    (constant-time) AND whose round matches. Every other POST — missing token,
-    reused token, mismatched round, or wrong token — is rejected so the caller
-    can fail the decision closed. The session grants at most one valid decision.
-    """
-
-    def __init__(self, round_n: int, token: str) -> None:
-        self.round_n = round_n
-        self._token = token
-        self._locked = False
-        self._lock = threading.Lock()
-        self.last_rejection: str = ""
-
-    @property
-    def locked(self) -> bool:
-        return self._locked
-
-    def validate(self, posted_round: int, posted_token: str | None) -> bool:
-        # LOW-1 (secure-ship-0.4.4): the check-then-set on ``_locked`` must
-        # be atomic. ThreadingHTTPServer handles each POST on its own
-        # thread, so two concurrent valid-token POSTs could both pass the
-        # ``if self._locked`` check and each consume the session. Hold the
-        # lock for the whole decision so first-decision-wins holds under
-        # real concurrency; the lock is uncontended in the single-POST
-        # happy path, so the cost is a no-op acquire/release.
-        with self._lock:
-            if not posted_token:
-                self.last_rejection = "missing"
-                return False
-            if posted_round != self.round_n:
-                self.last_rejection = "round_mismatch"
-                return False
-            if self._locked:
-                # First valid decision already consumed the session; every
-                # later POST (even with the correct token) is a replay.
-                self.last_rejection = "reuse"
-                return False
-            if not secrets.compare_digest(posted_token, self._token):
-                self.last_rejection = "invalid_token"
-                return False
-            self._locked = True
-            self.last_rejection = ""
-            return True
-
-
-def _self_check_floor() -> None:
-    """ADR-0008 floor branch logic self-check (ponytail: one runnable check)."""
-    cases = [
-        ("empty + no anchors", "", [], False),
-        ("whitespace-only feedback", "   \n  ", [], False),
-        ("short feedback passes (structural floor)", "ok", [], True),
-        ("short CJK feedback passes ('太挤了' is substantive)", "太挤了", [], True),
-        ("'安师大' passes floor; semantic junk is G6's job (ADR-0008)", "安师大", [], True),
-        ("longer feedback passes", "fix it", [], True),
-        ("anchor with comment", "", [{"selector": "h2", "comment": "x"}], True),
-        ("anchor no comment (0015 garbage)", "",
-         [{"selector": "h2", "comment": ""}], False),
-        ("anchor empty selector", "",
-         [{"selector": "", "comment": "x"}], False),
-        ("non-dict anchor", "", ["not-a-dict"], False),
-        ("feedback + incomplete anchor still fails", "ok",
-         [{"selector": "h2", "comment": ""}], False),
-        ("two anchors one incomplete fails", "",
-         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": ""}], False),
-        ("two anchors both complete passes", "",
-         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": "y"}], True),
-        ("short feedback + good anchor passes", "hi",
-         [{"selector": "h2", "comment": "x"}], True),
-    ]
-    for label, fb, anc, want in cases:
-        got, _ = _check_feedback_floor(fb, anc)
-        assert got == want, f"{label}: want {want}, got {got}"
-    print("FLOOR SELF-CHECK PASSED")
-
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1 and sys.argv[1] == "--self-check":
-        _self_check_floor()
-    else:
-        raise SystemExit(
-            "usage: confirm.py --self-check (the MCP server entry is server.py)")
-