ui-design-workbench-cli 0.5.0__py3-none-any.whl

uidw_mcp.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Optional local stdio MCP facade over the deterministic UIDW CLI core."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import uidw
+from native_render_registry import native_render_status
+from scoped_context import apply_patch_file, build_scoped_context
+
+
+SERVER_INSTRUCTIONS = (
+    "Start with ui_project, then call ui_scope for one screen or a small finding set. "
+    "If ui_project returns setupRequired, ask the user only for low, medium, or high, then call "
+    "ui_configure with that choice before continuing. "
+    "Do not request or embed the complete UI IR when bounded context is sufficient. "
+    "Use ui_prepare_job for review, proposal, or implementation handoffs. Review and proposal work "
+    "must preserve immutable baseline UI and return sparse ui-ir.patch.json operations; application "
+    "source changes require an explicit implementation request. Use ui_build_preview for projection "
+    "checks only; do not infer UI/UX findings unless the user explicitly requests a review. "
+    "For Android or Apple visual accuracy, call ui_native_status and never describe source projection as a native render. "
+    "Native builds, simulators, and captures are explicit-only operations."
+)
+
+
+def _root(value: str | None, default: Path) -> Path:
+    path = Path(value).expanduser().resolve() if value else default.resolve()
+    if not path.is_dir():
+        raise ValueError(f"Repository directory does not exist: {path}")
+    return path
+
+
+def _ir(root: Path, value: str | None) -> tuple[Path, dict[str, Any]]:
+    return uidw.load_ir_argument(uidw.state_paths(root), Path(value).expanduser() if value else None)
+
+
+def project_summary(repo: str | None, default_repo: Path) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    initialization, paths, config = uidw.ensure_initialized(root)
+    ir = uidw.load_project_ir(paths) or {}
+    configuration = uidw.configuration_context(config)
+    setup_required = bool(configuration.get("setupRequired"))
+    return {
+        "status": initialization.get("status"),
+        "cache": initialization.get("initialization", {}).get("status"),
+        "repoRoot": str(root),
+        "uiIrFile": str(paths["ir"]),
+        "contextFile": str(paths["context"]),
+        "screens": [{"id": item.get("id"), "name": item.get("name"), "platform": item.get("platform")} for item in ir.get("screens", [])],
+        "findingCount": len(ir.get("review", {}).get("audit", {}).get("findings", [])),
+        "setupRequired": setup_required,
+        "detailLevel": configuration.get("detailLevel"),
+        "detailChoices": ["low", "medium", "high"] if setup_required else [],
+        "questionsForUser": configuration.get("questionsForUser", []),
+        "uiModeEnabled": bool(config.get(uidw.UI_MODE_KEY, {}).get("enabled")),
+        "next": (
+            "Ask the user to choose low, medium, or high, then call ui_configure."
+            if setup_required
+            else "Use ui_scope for one screen or a small finding set; do not read the full IR."
+        ),
+    }
+
+
+def scoped_payload(
+    repo: str | None,
+    default_repo: Path,
+    ui_ir_file: str | None,
+    screen_ids: list[str],
+    finding_ids: list[str],
+    max_tokens: int,
+) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    ir_path, ir = _ir(root, ui_ir_file)
+    return build_scoped_context(
+        ir,
+        screen_ids=screen_ids,
+        finding_ids=finding_ids,
+        token_budget=max_tokens,
+        ui_ir_file=str(ir_path),
+    )
+
+
+def compact_workbench_result(result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        key: result.get(key)
+        for key in ("version", "status", "previewFile", "url", "workflow", "initialization")
+        if result.get(key) is not None
+    }
+
+
+def configure_detail(repo: str | None, default_repo: Path, detail: str) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    normalized = detail.strip().lower()
+    if normalized not in {"low", "medium", "high"}:
+        return {
+            "status": "blocked",
+            "error": "detail must be low, medium, or high",
+            "detailChoices": ["low", "medium", "high"],
+        }
+    result = uidw.configure_project(root, "set", "detail", normalized)
+    configuration = result.get("configuration", {})
+    return {
+        "status": result.get("status"),
+        "repoRoot": result.get("repoRoot"),
+        "setupRequired": bool(configuration.get("setupRequired")),
+        "detailLevel": configuration.get("detailLevel"),
+        "mockData": configuration.get(uidw.MOCK_DATA_KEY),
+        "contextFile": result.get("contextFile"),
+        "next": "Use ui_scope, then ui_build_preview when the requested screens are ready.",
+    }
+
+
+def build_preview(
+    repo: str | None,
+    default_repo: Path,
+    ui_ir_file: str | None,
+    output_dir: str | None,
+    level: str,
+) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    paths = uidw.state_paths(root)
+    configuration = uidw.configuration_context(uidw.load_config(paths["config"]))
+    if configuration.get("setupRequired"):
+        return {
+            "status": "needs-setup",
+            "setupRequired": True,
+            "detailChoices": ["low", "medium", "high"],
+            "questionsForUser": configuration.get("questionsForUser", []),
+            "next": "Ask the user to choose low, medium, or high, then call ui_configure.",
+        }
+
+    ir_path, _ = _ir(root, ui_ir_file)
+    destination = Path(output_dir).expanduser().resolve() if output_dir else ir_path.parent / "workbench"
+    cached_ir = paths["ir"].resolve()
+    allow_draft = ir_path.resolve() == cached_ir
+    try:
+        result = uidw.build_workbench(
+            root,
+            ir_path,
+            destination,
+            level,
+            allow_draft,
+            "generic",
+            False,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+    except (RuntimeError, ValueError, OSError) as exc:
+        return {
+            "status": "blocked",
+            "error": str(exc),
+            "uiIrFile": str(ir_path),
+            "next": "Resolve the reported IR or fidelity problem, then call ui_build_preview again.",
+        }
+    return compact_workbench_result(result)
+
+
+def create_server(default_repo: Path, name: str = "UI Design Workbench") -> Any:
+    try:
+        from mcp.server import MCPServer
+    except ImportError as exc:
+        raise RuntimeError(
+            "MCP support is optional. Install it with `pip install \"ui-design-workbench-cli[mcp]\"` "
+            "or `pip install \"mcp>=2,<3\"`. The regular uidw CLI does not require it."
+        ) from exc
+
+    server = MCPServer(
+        name,
+        version=uidw.CLI_VERSION,
+        instructions=SERVER_INSTRUCTIONS,
+    )
+
+    @server.tool()
+    def ui_project(repo: str = "") -> dict[str, Any]:
+        """Get a compact cached UI catalog and the next bounded action."""
+        return project_summary(repo or None, default_repo)
+
+    @server.tool()
+    def ui_configure(detail: str, repo: str = "") -> dict[str, Any]:
+        """Set the required low, medium, or high preview detail after the user chooses it."""
+        return configure_detail(repo or None, default_repo, detail)
+
+    @server.tool()
+    def ui_scope(
+        screen_ids: list[str],
+        finding_ids: list[str],
+        repo: str = "",
+        ui_ir_file: str = "",
+        max_tokens: int = 4000,
+    ) -> dict[str, Any]:
+        """Read complete UI evidence only for named screens/findings."""
+        return scoped_payload(repo or None, default_repo, ui_ir_file or None, screen_ids, finding_ids, max_tokens)
+
+    @server.tool()
+    def ui_prepare_job(
+        kind: str,
+        finding_ids: list[str],
+        repo: str = "",
+        ui_ir_file: str = "",
+        output_file: str = "",
+        scope: str = "current",
+        direct: bool = False,
+    ) -> dict[str, Any]:
+        """Prepare a portable bounded job plus context and ui-ir.patch.json."""
+        root = _root(repo or None, default_repo)
+        ir_path, ir = _ir(root, ui_ir_file or None)
+        if kind not in {"expert", "proposal", "implementation"}:
+            raise ValueError("kind must be expert, proposal, or implementation")
+        output = Path(output_file).expanduser().resolve() if output_file else ir_path.parent / f"ui-agent-job-{kind}.json"
+        return uidw.prepare_agent_job(root, ir_path, ir, kind, output, identifiers=finding_ids, scope=scope, direct=direct)
+
+    @server.tool()
+    def ui_apply_patch(
+        patch_file: str,
+        repo: str = "",
+        ui_ir_file: str = "",
+        output_file: str = "",
+    ) -> dict[str, Any]:
+        """Validate and apply sparse review/proposal operations without touching baseline UI."""
+        root = _root(repo or None, default_repo)
+        ir_path, _ = _ir(root, ui_ir_file or None)
+        output = Path(output_file).expanduser().resolve() if output_file else ir_path.with_name("ui-ir.patched.json")
+        return apply_patch_file(ir_path, Path(patch_file).expanduser(), output)
+
+    @server.tool()
+    def ui_build_preview(
+        repo: str = "",
+        ui_ir_file: str = "",
+        output_dir: str = "",
+        level: str = "quick",
+    ) -> dict[str, Any]:
+        """Render and projection-check the HTML workbench; never auto-review UX."""
+        return build_preview(repo or None, default_repo, ui_ir_file or None, output_dir or None, level)
+
+    @server.tool()
+    def ui_native_status(repo: str = "", platform: str = "all") -> dict[str, Any]:
+        """Discover native Android/Apple render providers without executing builds or simulators."""
+        if platform not in {"all", "android", "apple"}:
+            raise ValueError("platform must be all, android, or apple")
+        root = _root(repo or None, default_repo)
+        return native_render_status(root, uidw.state_paths(root)["native"], platform)
+
+    @server.tool()
+    def ui_fidelity(identifier: str, repo: str = "", ui_ir_file: str = "") -> dict[str, Any]:
+        """Explain one node/evidence id without returning the complete IR."""
+        root = _root(repo or None, default_repo)
+        _, ir = _ir(root, ui_ir_file or None)
+        return uidw.fidelity_command(ir, "explain", identifier, None, "json")
+
+    return server
+
+
+def run_server(default_repo: Path, name: str = "UI Design Workbench") -> None:
+    create_server(default_repo, name).run()
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Local stdio MCP server for UI Design Workbench")
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    parser.add_argument("--name", default="UI Design Workbench")
+    return parser.parse_args(argv)
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        run_server(args.repo.resolve(), args.name)
+    except (RuntimeError, ValueError, OSError) as exc:
+        print(f"uidw mcp: {exc}", file=sys.stderr)
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

validate_platform_profiles.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Validate platform-profile selection and node standard references in UI IR."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from quality_common import framework_adapters, node_screen_map, platform_family, profile_catalog, read_json, target_families, write_json
+
+
+def validate_profiles(ir: dict[str, Any]) -> dict[str, Any]:
+    catalog = profile_catalog()
+    profiles = catalog.get("profiles", {})
+    adapters = catalog.get("frameworkAdapters", {})
+    families = target_families(ir)
+    selected = ir.get("design", {}).get("standardProfiles", {})
+    issues: list[dict[str, Any]] = []
+    resolved: dict[str, Any] = {}
+
+    if not families:
+        supported = ", ".join(sorted({str(item.get("family")) for item in profiles.values() if isinstance(item, dict) and item.get("family")}))
+        issues.append({"code": "target-platform-missing", "severity": "error", "message": f"design.targetPlatforms must resolve to a supported family: {supported}."})
+
+    for adapter_id in sorted(framework_adapters(ir)):
+        adapter = adapters[adapter_id]
+        if adapter.get("requiresExplicitTarget") and not ir.get("design", {}).get("targetPlatforms"):
+            issues.append({"code": "framework-target-ambiguous", "severity": "error", "adapter": adapter_id, "message": f"{adapter_id} requires explicit design.targetPlatforms."})
+
+    for family in sorted(families):
+        selection = selected.get(family)
+        if not isinstance(selection, dict):
+            issues.append({"code": "profile-missing", "severity": "error", "family": family, "message": f"Missing design.standardProfiles.{family}."})
+            continue
+        profile_id = selection.get("id")
+        if profile_id == "project":
+            if not selection.get("reason"):
+                issues.append({"code": "project-profile-unreasoned", "severity": "error", "family": family, "message": "A project profile needs a reason and evidence."})
+            else:
+                resolved[family] = {**selection, "family": family, "standardRefPrefixes": ["project."]}
+            continue
+        profile = profiles.get(profile_id)
+        if not profile or profile.get("family") != family:
+            issues.append({"code": "profile-invalid", "severity": "error", "family": family, "profile": profile_id, "message": f"Profile {profile_id!r} does not belong to {family}."})
+            continue
+        resolved[family] = {**profile, "id": profile_id, "source": selection.get("source")}
+
+    decisions = {item.get("id") for item in ir.get("design", {}).get("decisions", []) if isinstance(item, dict)}
+    screen_families = {str(screen.get("id")): platform_family(screen.get("platform")) for screen in ir.get("screens", [])}
+    node_screens = node_screen_map(ir)
+    for node_id, node in ir.get("nodes", {}).items():
+        if node.get("type") == "spacer" or node.get("decisionId") in decisions:
+            continue
+        shared = str(node.get("standardRef", ""))
+        per_platform = node.get("standardRefs", {}) if isinstance(node.get("standardRefs"), dict) else {}
+        node_families = {screen_families.get(screen_id) for screen_id in node_screens.get(str(node_id), set())}
+        node_families.discard(None)
+        node_families = node_families or families
+        for family in sorted(node_families):
+            profile = resolved.get(family)
+            if not profile:
+                continue
+            ref = str(per_platform.get(family, shared))
+            prefixes = tuple(profile.get("standardRefPrefixes", []))
+            if not ref.startswith(prefixes):
+                issues.append({"code": "standard-ref-mismatch", "severity": "error", "family": family, "node": node_id, "ref": ref or None, "allowedPrefixes": list(prefixes), "message": f"Node {node_id} lacks a {family} standard reference or decision."})
+
+    return {
+        "version": 1,
+        "status": "blocked" if any(item["severity"] == "error" for item in issues) else "pass",
+        "targetFamilies": sorted(families),
+        "frameworkAdapters": sorted(framework_adapters(ir)),
+        "resolvedProfiles": resolved,
+        "issues": issues,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("ir", help="Path to ui-ir.json")
+    parser.add_argument("--output", required=True, help="Path for platform-profile-report.json")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero when the report is blocked")
+    args = parser.parse_args()
+    report = validate_profiles(read_json(args.ir))
+    write_json(args.output, report)
+    print(Path(args.output).resolve())
+    return 2 if args.strict and report["status"] != "pass" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())