design-playbook 0.7.0

package/mcp/preview/i18n.py

@@ -0,0 +1,162 @@
+"""i18n for the preview adapter UI (ADR: CJK-first, en supported).
+
+Locale source: env DPB_PREVIEW_LANG (or LANG), default "zh-CN". Only zh-CN and
+en are provided; unknown locales fall back to zh-CN.
+
+CONFIRM/revise labels are locale-aware: DEFAULT_OPTIONS returns the options in
+the active locale, and CONFIRM_LABELS is the union across locales so the
+backend still recognises a confirm regardless of UI language.
+"""
+from __future__ import annotations
+import os
+
+ZH = "zh-CN"
+EN = "en"
+
+_STRINGS: dict[str, dict[str, str]] = {
+    ZH: {
+        "region_label": "预览确认",
+        "round_n": "第 {n} 轮",
+        "annotate": "批注",
+        "pill_open": "评审确认",
+        "ready": "可确认",
+        "not_ready": "写意见或批注后再确认",
+        "drawer_aria": "批注与确认",
+        "collapse": "收起",
+        "pin_toggle": "点选批注",
+        "pin_count": "已选 {n} 处",
+        "pin_on": "点选中 · 再点关闭",
+        "pin_off": "点选批注",
+        "anchor_num_pre": "锚点 ",
+        "anchor_num_post": " 的修改意见",
+        "anchor_placeholder": "这条要改什么",
+        "remove_num_pre": "移除锚点 ",
+        "pin_count_pre": "已选 ",
+        "pin_count_post": " 处",
+        # JS-side dynamic anchors (split pre/post because idx is a JS value):
+        "anchors_head": "选中批注",
+        "anchors_empty": "尚未选中元素。点上方「点选批注」后，再点页面上的元素。",
+        "field_label": "整体批注",
+        "field_hint": "请写整体意见或点选元素加批注后确认；空反馈会被拦下（ADR-0008）",
+        "field_placeholder": "对整页的总意见；页面元素的局部问题用「点选批注」",
+        "close": "关闭",
+        "terminate": "终止评审",
+        "terminate_confirm": "再点一次确认终止",
+        "terminate_desc": "终止整次预览会话（不是通过/修改）；需再点一次确认",
+        "abort_cancelled": "已取消",
+        "confirm_confirm": "再点一次确认通过",
+        "confirm_cancelled": "已取消确认",
+        "draft": "保留批注，暂不决定",
+        "draft_desc": "关闭抽屉并保留批注，不提交本轮决定",
+        "locate": "定位到该元素",
+        "locate_anchor": "定位到该元素",
+        "remove": "移除",
+        "selected_n": "已选 {n} 处",
+        "anchor_note_label": "锚点批注 ({n}):",
+        "no_text": "(无文字)",
+        "done_title": "已记录",
+        "done_body": "窗口即将自动关闭。",
+        "confirm": "确认通过",
+        "confirm_desc": "确认本轮通过并进入实现（Fill）；需有批注或整体意见",
+        "revise": "需要修改",
+        "revise_desc": "提交修改意见，进入下一轮原型",
+        "floor_failure_empty": "confirm with no substantive feedback: empty feedback and no anchor with a non-empty comment",
+        "floor_failure_selector": "anchor missing non-empty selector and comment: selector={sel!r} comment={note!r}",
+        "log_anchor_missing": "锚点 #{n} 缺 selector 或 comment",
+        "self_check_passed": "FLOOR SELF-CHECK PASSED",
+    },
+    EN: {
+        "region_label": "Preview confirm",
+        "round_n": "Round {n}",
+        "annotate": "Annotate",
+        "pill_open": "Review & confirm",
+        "ready": "Ready",
+        "not_ready": "Add notes or pin to confirm",
+        "drawer_aria": "Annotate & confirm",
+        "collapse": "Collapse",
+        "pin_toggle": "Pick to annotate",
+        "pin_count": "{n} selected",
+        "pin_on": "Picking · click again to close",
+        "pin_off": "Pick to annotate",
+        "anchor_num_pre": "Anchor ",
+        "anchor_num_post": " revision note",
+        "anchor_placeholder": "What to change here",
+        "remove_num_pre": "Remove anchor ",
+        "pin_count_pre": "",
+        "pin_count_post": " selected",
+        "anchors_head": "Selected annotations",
+        "anchors_empty": "No element selected. Click \"Pick to annotate\" above, then click an element on the page.",
+        "field_label": "Overall feedback",
+        "field_hint": "Write overall notes or pick an element to annotate before confirming; empty feedback is blocked (ADR-0008)",
+        "field_placeholder": "Overall notes for the page; for a specific element use \"Pick to annotate\"",
+        "close": "Close",
+        "terminate": "Abort preview",
+        "terminate_confirm": "Click again to abort",
+        "terminate_desc": "Stops the whole preview session (not pass/fail); click again to confirm",
+        "abort_cancelled": "Cancelled",
+        "confirm_confirm": "Click again to confirm",
+        "confirm_cancelled": "Confirm cancelled",
+        "draft": "Keep notes, decide later",
+        "draft_desc": "Close drawer and keep notes; do not submit a decision yet",
+        "locate": "Locate this element",
+        "locate_anchor": "Locate this element",
+        "anchor_aria": "Revision note for anchor \"{label}\"",
+        "remove": "Remove",
+        "selected_n": "{n} selected",
+        "anchor_note_label": "Anchor notes ({n}):",
+        "no_text": "(no text)",
+        "done_title": "Recorded",
+        "done_body": "This window will close shortly.",
+        "confirm": "Confirm",
+        "confirm_desc": "Approve this round and proceed to Fill; needs notes or annotations",
+        "revise": "Needs changes",
+        "revise_desc": "Submit revision notes and open the next prototype round",
+        "floor_failure_empty": "confirm with no substantive feedback: empty feedback and no anchor with a non-empty comment",
+        "floor_failure_selector": "anchor missing non-empty selector and comment: selector={sel!r} comment={note!r}",
+        "log_anchor_missing": "anchor #{n} missing selector or comment",
+        "self_check_passed": "FLOOR SELF-CHECK PASSED",
+    },
+}
+
+
+def lang() -> str:
+    """Active locale (zh-CN or en). Env DPB_PREVIEW_LANG, then LANG, default zh-CN."""
+    raw = os.environ.get("DPB_PREVIEW_LANG") or os.environ.get("LANG") or ZH
+    low = raw.replace("_", "-").lower()
+    if low.startswith("en"):
+        return EN
+    return ZH
+
+
+def t(key: str, **kw: object) -> str:
+    """Translate a key in the active locale, with {kw} interpolation."""
+    table = _STRINGS[lang()]
+    val = table.get(key)
+    if val is None:
+        return key
+    if kw:
+        try:
+            return val.format(**kw)
+        except (KeyError, IndexError):
+            return val
+    return val
+
+
+def default_options() -> list[str]:
+    """[confirm_label, revise_label] in the active locale."""
+    return [t("confirm"), t("revise")]
+
+
+# Union of confirm labels across ALL locales - backend must recognise a confirm
+# regardless of which locale the UI rendered in.
+CONFIRM_LABELS: set[str] = {
+    _STRINGS[ZH]["confirm"], _STRINGS[EN]["confirm"],
+    "confirm", "confirmed", "pass", "ok",
+}
+
+# Union of revise labels across ALL locales - frontend must classify a revise
+# regardless of which locale the UI rendered in.
+REVISE_LABELS: set[str] = {
+    _STRINGS[ZH]["revise"], _STRINGS[EN]["revise"],
+    "revise", "needs changes", "needs-changes",
+}

package/mcp/preview/server.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Minimal stdio MCP server: single tool ``preview_prototype``.
+
+Entry point only: tool schema + handler. JSON-RPC stdio framing lives in
+``mcp/_transport.py``; browser HTTP collection lives in ``browser.py``;
+decision authority and persistence live in ``transaction.py``. Control,
+confirm, utility, and locale details stay in their sibling modules. No
+third-party deps.
+
+Run (plugin-bundled MCP config uses ${CLAUDE_PLUGIN_ROOT}):
+  { "command": "python", "args": ["<plugin>/mcp/preview/server.py"] }
+Compatibility launcher remains at packages/design-playbook-preview/server.py.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+# Shared stdio JSON-RPC framing + single-tool dispatch live one level up in
+# mcp/_transport.py (both bundled adapters speak the same wire format and
+# run the same JSON-RPC protocol; ADR-0009).
+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
+
+TOOL_NAME = "preview_prototype"
+
+
+
+def _tool_schema() -> dict[str, Any]:
+    return {
+        "name": TOOL_NAME,
+        "description": (
+            "Show a disposable HTML prototype in a centered app window, collect "
+            "user confirm/revise feedback, and write preview confirm records."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to prototype HTML (preferred).",
+                },
+                "html": {
+                    "type": "string",
+                    "description": "Inline full-page HTML when path is absent.",
+                },
+                "summary": {
+                    "type": "string",
+                    "description": "Decision-report summary / change note.",
+                },
+                "round": {
+                    "type": "integer",
+                    "description": "Loop round number; first round = 1.",
+                },
+                "report_ref": {
+                    "type": "string",
+                    "description": "Path or version id of the decision report.",
+                },
+                "options": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Confirm/revise labels. Omit to use the adapter locale's "
+                        "defaults; known confirm/revise labels are rendered in "
+                        "the adapter locale either way."
+                    ),
+                },
+            },
+            "required": ["summary", "round", "report_ref"],
+        },
+    }
+
+
+
+def handle_preview_prototype(args: dict[str, Any]) -> dict[str, Any]:
+    path_arg = args.get("path")
+    html = args.get("html")
+    summary = args.get("summary")
+    round_n = args.get("round")
+    report_ref = args.get("report_ref")
+    options = args.get("options") or default_options()
+
+    if not isinstance(summary, str) or not summary.strip():
+        raise ValueError("summary is required")
+    if not isinstance(round_n, int) or isinstance(round_n, bool) or round_n < 1:
+        raise ValueError("round must be a positive integer")
+    if not isinstance(report_ref, str) or not report_ref.strip():
+        raise ValueError("report_ref is required")
+    if path_arg is not None and not isinstance(path_arg, str):
+        raise ValueError("path must be a string")
+    if html is not None and not isinstance(html, str):
+        raise ValueError("html must be a string")
+    if not isinstance(options, list) or not all(isinstance(o, str) for o in options):
+        raise ValueError("options must be string[]")
+
+    try:
+        return run_preview_transaction(
+            path_arg=path_arg,
+            html=html,
+            summary=summary,
+            round_n=round_n,
+            report_ref=report_ref,
+            options=options,
+            collect=browser._collect_via_browser,
+        )
+    except PreviewTransactionError as exc:
+        raise ToolError(str(exc), exc.details) from exc
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "--self-check":
+        _self_check_floor()
+    else:
+        serve_stdio(
+            "design-playbook-preview",
+            "0.1.0",
+            _tool_schema(),
+            handle_preview_prototype,
+            recover_from_malformed=False,
+        )