modao-prd-cli 0.1.0__py3-none-any.whl

modao_prd_cli/__init__.py

@@ -0,0 +1 @@
+"""Python package for the modao-prd-cli tool."""

modao_prd_cli/modao_prd/__init__.py

@@ -0,0 +1,4 @@
+"""Public Modao prototype extraction CLI."""
+
+__version__ = "0.1.0"
+

modao_prd_cli/modao_prd/__main__.py

@@ -0,0 +1,7 @@
+"""Run modao-prd-cli with ``python -m modao_prd_cli.modao_prd``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

modao_prd_cli/modao_prd/browser.py

@@ -0,0 +1,578 @@
+"""Secure Playwright backend for public Modao prototype shares."""
+
+from __future__ import annotations
+
+import importlib.util
+import platform
+import re
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from . import __version__
+from .capture_evidence import capture_state_evidence, make_response_handler, merge_evidence
+from .errors import ModaoPrdError
+from .evidence import EvidenceBundleWriter
+
+
+ALLOWED_HOSTS = {"modao.cc", "www.modao.cc"}
+SHARE_PATH_RE = re.compile(r"^/proto/(?P<project_id>[A-Za-z0-9_-]+)/sharing/?$")
+READY_SELECTORS = [".mb-screen", "#screens", ".wRichText"]
+CHROME_PATHS = (
+    Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+    Path("/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
+)
+
+
+@dataclass(frozen=True)
+class ShareURL:
+    """Validated public Modao share URL facts."""
+
+    url: str
+    project_id: str
+    host: str
+
+
+def validate_share_url(url: str) -> ShareURL:
+    """Validate a URL and prevent this CLI from becoming a generic fetcher."""
+
+    candidate = (url or "").strip()
+    if not candidate:
+        raise ModaoPrdError("invalid_url", "墨刀分享链接不能为空")
+    try:
+        parsed = urlsplit(candidate)
+        port = parsed.port
+    except ValueError as exc:
+        raise ModaoPrdError("invalid_url", f"无法解析 URL：{exc}", url=candidate) from exc
+
+    if parsed.scheme.lower() != "https":
+        raise ModaoPrdError("invalid_url", "只允许使用 HTTPS 墨刀分享链接", url=candidate)
+    if parsed.username or parsed.password or port is not None:
+        raise ModaoPrdError(
+            "invalid_url",
+            "链接不能包含用户名、密码或自定义端口",
+            url=candidate,
+        )
+
+    host = (parsed.hostname or "").lower().rstrip(".")
+    if host not in ALLOWED_HOSTS:
+        raise ModaoPrdError(
+            "unsupported_url",
+            "仅支持 modao.cc 的公开分享链接",
+            url=candidate,
+            diagnostics={"allowed_hosts": sorted(ALLOWED_HOSTS)},
+        )
+
+    match = SHARE_PATH_RE.fullmatch(parsed.path)
+    if not match:
+        raise ModaoPrdError(
+            "unsupported_url",
+            "链接路径必须符合 /proto/<project-id>/sharing",
+            url=candidate,
+        )
+    return ShareURL(url=candidate, project_id=match.group("project_id"), host=host)
+
+
+def find_project_root(start: str | Path | None = None) -> Path:
+    """Return the nearest Git project root, falling back to the working directory."""
+
+    current = Path(start or Path.cwd()).expanduser().resolve()
+    if current.is_file():
+        current = current.parent
+    for candidate in (current, *current.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return current
+
+
+def default_output_root(start: str | Path | None = None) -> Path:
+    return find_project_root(start) / ".modao-prd"
+
+
+def ensure_default_output_ignored(project_root: str | Path) -> bool:
+    """Idempotently ignore the default generated-output directory."""
+
+    root = Path(project_root).expanduser().resolve()
+    ignore_file = root / ".gitignore"
+    entry = "/.modao-prd/"
+    try:
+        existing = ignore_file.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        existing = ""
+    if any(line.strip() in {entry, ".modao-prd/", ".modao-prd"} for line in existing.splitlines()):
+        return False
+    prefix = "" if not existing or existing.endswith(("\n", "\r")) else "\n"
+    with ignore_file.open("a", encoding="utf-8") as target:
+        target.write(f"{prefix}{entry}\n")
+    return True
+
+
+def doctor() -> dict[str, Any]:
+    """Return local runtime readiness without opening a browser."""
+
+    playwright_available = importlib.util.find_spec("playwright") is not None
+    channels: list[str] = []
+    if CHROME_PATHS[0].is_file():
+        channels.append("chrome")
+    if CHROME_PATHS[1].is_file():
+        channels.append("msedge")
+
+    bundled_path: str | None = None
+    if playwright_available:
+        # Keep doctor side-effect free: inspecting Playwright's sync runtime can
+        # leave an async driver task behind on some Python/macOS combinations.
+        # The common cache locations are enough for a readiness diagnostic.
+        cache_roots = [
+            Path.home() / "Library" / "Caches" / "ms-playwright",
+            Path.home() / ".cache" / "ms-playwright",
+        ]
+        executable_names = {
+            "Google Chrome for Testing",
+            "chrome",
+            "chromium",
+            "chromium.exe",
+        }
+        for cache_root in cache_roots:
+            if not cache_root.is_dir():
+                continue
+            for candidate in cache_root.rglob("*"):
+                if candidate.is_file() and candidate.name in executable_names:
+                    bundled_path = str(candidate)
+                    channels.append("chromium")
+                    break
+            if bundled_path:
+                break
+        for executable in ("chromium", "chromium-browser", "google-chrome"):
+            if shutil.which(executable):
+                channels.append("chromium")
+                bundled_path = bundled_path or shutil.which(executable)
+                break
+
+    channels = list(dict.fromkeys(channels))
+    return {
+        "version": __version__,
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "playwright_available": playwright_available,
+        "browser_available": bool(channels),
+        "browser_channels": channels,
+        "bundled_chromium_path": bundled_path,
+        "default_output_root": str(default_output_root()),
+        "ready": playwright_available and bool(channels),
+        "install_hint": None
+        if playwright_available and channels
+        else "python3 -m pip install -e . && python3 -m playwright install chromium",
+    }
+
+
+def capture_page(
+    url: str,
+    *,
+    headed: bool = False,
+    timeout_seconds: int = 30,
+    evidence_writer: EvidenceBundleWriter | None = None,
+    evidence_mode: str = "none",
+    explore: str = "none",
+    max_states: int = 50,
+    max_depth: int = 3,
+    max_actions: int = 200,
+    max_duration_seconds: int = 120,
+    max_item: int = 10 * 1024 * 1024,
+    max_total: int = 200 * 1024 * 1024,
+) -> dict[str, Any]:
+    """Render a public share in an ephemeral browser and collect facts/evidence."""
+
+    share = validate_share_url(url)
+    if importlib.util.find_spec("playwright") is None:
+        raise ModaoPrdError(
+            "playwright_missing",
+            "缺少 Playwright；请先安装项目依赖",
+            url=url,
+            diagnostics={"install_hint": "python3 -m pip install -e ."},
+        )
+
+    try:
+        from playwright.sync_api import Error as PlaywrightError
+        from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:  # pragma: no cover - guarded above
+        raise ModaoPrdError("playwright_missing", str(exc), url=url) from exc
+
+    timeout_ms = max(1, timeout_seconds) * 1000
+    browser = None
+    launch_errors: list[str] = []
+    try:
+        with sync_playwright() as runtime:
+            launch_options = (
+                ("chrome", {"channel": "chrome"}),
+                ("chromium", {}),
+            )
+            for label, extra in launch_options:
+                try:
+                    browser = runtime.chromium.launch(headless=not headed, **extra)
+                    break
+                except PlaywrightError as exc:
+                    launch_errors.append(f"{label}: {_short_error(exc)}")
+
+            if browser is None:
+                raise ModaoPrdError(
+                    "browser_unavailable",
+                    "无法启动 Chrome 或 Playwright Chromium",
+                    url=url,
+                    diagnostics={
+                        "attempts": launch_errors,
+                        "install_hint": "python3 -m playwright install chromium",
+                    },
+                )
+
+            context = browser.new_context(
+                viewport={"width": 1440, "height": 1000},
+                locale="zh-CN",
+            )
+            page = context.new_page()
+            page.set_default_timeout(timeout_ms)
+            warnings: list[str] = []
+            evidence: list[dict[str, Any]] = []
+            network_records: list[dict[str, Any]] = []
+            response_handler = make_response_handler(
+                writer=evidence_writer,
+                requested_url=share.url,
+                state_id="state-001",
+                evidence=evidence,
+                network_records=network_records,
+                warnings=warnings,
+                max_item=max_item,
+                max_total=max_total,
+                evidence_mode=evidence_mode,
+            )
+            if evidence_mode != "none":
+                context.on("response", response_handler)
+            try:
+                page.goto(url, wait_until="domcontentloaded", timeout=timeout_ms)
+                page.wait_for_function(
+                    """() => {
+                        const ready = document.querySelector('.mb-screen, #screens, .wRichText');
+                        const length = document.body?.innerText?.trim().length || 0;
+                        return Boolean(ready) || length >= 200;
+                    }""",
+                    timeout=timeout_ms,
+                )
+                page.wait_for_timeout(750)
+                _expand_scrollable_content(page, timeout_ms)
+            except PlaywrightTimeoutError as exc:
+                diagnostics = _page_diagnostics(page)
+                diagnostics["expected_selectors"] = READY_SELECTORS
+                raise ModaoPrdError(
+                    "page_timeout",
+                    f"墨刀页面在 {timeout_seconds} 秒内未完成渲染",
+                    url=url,
+                    diagnostics=diagnostics,
+                ) from exc
+            except PlaywrightError as exc:
+                raise ModaoPrdError(
+                    "page_not_rendered",
+                    "墨刀页面无法加载",
+                    url=url,
+                    diagnostics={"detail": _short_error(exc)},
+                ) from exc
+
+            diagnostics = _page_diagnostics(page)
+            try:
+                validate_share_url(page.url)
+            except ModaoPrdError as exc:
+                raise ModaoPrdError(
+                    "page_access_denied",
+                    "墨刀分享页跳转到了不受支持的地址",
+                    url=url,
+                    diagnostics={"final_url": page.url, "detail": exc.message},
+                ) from exc
+            body_text = page.locator("body").inner_text().strip()
+            lowered = body_text.lower()
+            if any(marker in lowered for marker in ("无访问权限", "access denied", "请登录后访问")):
+                raise ModaoPrdError(
+                    "page_access_denied",
+                    "该页面不是可直接读取的公开分享页",
+                    url=url,
+                    diagnostics=diagnostics,
+                )
+            if diagnostics["body_text_length"] < 20:
+                raise ModaoPrdError(
+                    "empty_document",
+                    "页面已打开，但没有发现可提取的原型内容",
+                    url=url,
+                    diagnostics=diagnostics,
+                )
+
+            try:
+                captured = page.evaluate(_DOM_EXTRACTION_SCRIPT)
+            except PlaywrightError as exc:
+                raise ModaoPrdError(
+                    "parse_error",
+                    "读取墨刀 DOM 时失败",
+                    url=url,
+                    diagnostics={"detail": _short_error(exc), **diagnostics},
+                ) from exc
+
+            state_evidence, dom_snapshot, evidence_stats = capture_state_evidence(
+                page,
+                context,
+                writer=evidence_writer if evidence_mode != "none" else None,
+                state_id="state-001",
+                requested_url=share.url,
+                evidence_mode=evidence_mode,
+                max_item=max_item,
+                max_total=max_total,
+                warnings=warnings,
+                network_records=network_records,
+                evidence_id_offset=len(evidence),
+            )
+            # A response callback may have added network evidence before the
+            # rendered-state artifacts. Keep one stable evidence list in the
+            # raw capture and let the document builder attach these IDs.
+            merge_evidence(evidence, state_evidence)
+            captured.update(
+                {
+                    "requested_url": share.url,
+                    "project_id": share.project_id,
+                    "final_url": page.url,
+                    "title": page.title().strip() or share.project_id,
+                    "body_text_length": len(body_text),
+                    "state_id": "state-001",
+                    "states": [
+                        {
+                            "id": "state-001",
+                            "url": page.url,
+                            "depth": 0,
+                            "action_count": 0,
+                            "evidence_ids": [item["id"] for item in evidence],
+                            "dom": dom_snapshot,
+                            "evidence_stats": evidence_stats,
+                        }
+                    ],
+                    "evidence": evidence,
+                    "network": network_records,
+                    "warnings": warnings,
+                    "coverage": {
+                        "state_count": 1,
+                        "explored": explore == "safe",
+                        "max_states": max_states,
+                        "max_depth": max_depth,
+                        "max_actions": max_actions,
+                        "max_duration_seconds": max_duration_seconds,
+                    },
+                    "capture": {
+                        "evidence": evidence_mode,
+                        "explore": explore,
+                        "timeout_seconds": timeout_seconds,
+                        "max_states": max_states,
+                        "max_depth": max_depth,
+                        "max_actions": max_actions,
+                        "max_duration_seconds": max_duration_seconds,
+                        "max_item": max_item,
+                        "max_total": max_total,
+                    },
+                }
+            )
+            if explore == "safe" and max_states > 1 and max_actions > 0:
+                try:
+                    context.remove_listener("response", response_handler)
+                except Exception:
+                    pass
+                from .explorer import explore_safe
+
+                explore_safe(
+                    page,
+                    context,
+                    requested_url=share.url,
+                    timeout_ms=timeout_ms,
+                    max_states=max_states,
+                    max_depth=max_depth,
+                    max_actions=max_actions,
+                    max_duration_seconds=max_duration_seconds,
+                    evidence_mode=evidence_mode,
+                    evidence_writer=evidence_writer,
+                    max_item=max_item,
+                    max_total=max_total,
+                    raw=captured,
+                )
+            context.close()
+            browser.close()
+            browser = None
+            return captured
+    finally:
+        # The sync_playwright context owns cleanup on exceptional paths. Do
+        # not call browser.close() here after the runtime has stopped.
+        browser = None
+
+
+def _page_diagnostics(page: Any) -> dict[str, Any]:
+    try:
+        text_length = len(page.locator("body").inner_text().strip())
+    except Exception:
+        text_length = 0
+    try:
+        title = page.title()
+    except Exception:
+        title = ""
+    return {
+        "title": title,
+        "final_url": getattr(page, "url", ""),
+        "body_text_length": text_length,
+    }
+
+
+def _short_error(exc: Exception, limit: int = 500) -> str:
+    text = " ".join(str(exc).split())
+    return text[:limit] + ("…" if len(text) > limit else "")
+
+
+def _expand_scrollable_content(page: Any, timeout_ms: int) -> None:
+    """Reveal bounded lazy content without treating network-idle as readiness."""
+
+    try:
+        page.evaluate(
+            """() => {
+              const scrollables = [document.scrollingElement, ...Array.from(document.querySelectorAll('*'))]
+                .filter(element => element && element.scrollHeight > element.clientHeight + 8 &&
+                  ['auto', 'scroll'].includes(getComputedStyle(element).overflowY));
+              for (const element of scrollables.slice(0, 80)) element.scrollTop = element.scrollHeight;
+              window.scrollTo(0, document.scrollingElement?.scrollHeight || document.body.scrollHeight);
+            }"""
+        )
+        page.wait_for_timeout(min(350, timeout_ms))
+        page.evaluate("() => window.scrollTo(0, 0)")
+    except Exception:
+        # A page may contain a detached or cross-origin scroll container; the
+        # rendered DOM and screenshot still remain useful evidence.
+        return
+
+
+_DOM_EXTRACTION_SCRIPT = r"""
+() => {
+  const root = document.querySelector('#screens') || document.querySelector('.mb-screen') || document.body;
+  const screenNodes = Array.from(root.querySelectorAll('.mb-screen'));
+  if (root.matches && root.matches('.mb-screen')) screenNodes.unshift(root);
+  const uniqueScreens = Array.from(new Set(screenNodes));
+  if (!uniqueScreens.length) uniqueScreens.push(root);
+
+  const normalize = value => (value || '')
+    .replace(/\u00a0/g, ' ')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\s*\n\s*/g, '\n')
+    .trim();
+  const screenIndex = element => {
+    const screen = element.closest?.('.mb-screen');
+    const index = screen ? uniqueScreens.indexOf(screen) : 0;
+    return index >= 0 ? index : 0;
+  };
+  const rectOf = element => {
+    const rect = element.getBoundingClientRect();
+    return {
+      x: Math.round(rect.x), y: Math.round(rect.y),
+      width: Math.round(rect.width), height: Math.round(rect.height)
+    };
+  };
+  const semanticSelector = element => {
+    if (element.matches('table')) return 'table';
+    if (element.matches('img')) return 'img';
+    if (element.matches('button')) return 'button';
+    if (element.matches('.widget.tree-node.wButton')) return '.widget.tree-node.wButton';
+    if (element.matches('.widget.tree-node.wRichText')) return '.widget.tree-node.wRichText';
+    return element.tagName.toLowerCase();
+  };
+
+  const screens = uniqueScreens.map((screen, index) => {
+    const localTitle = screen.querySelector('.canvas-title')?.textContent;
+    const globalTitles = Array.from(document.querySelectorAll('.canvas-title'));
+    const fallback = globalTitles[index]?.textContent;
+    return {
+      index,
+      source_id: screen.id || null,
+      title: normalize(localTitle || fallback) || `页面 ${index + 1}`,
+      bounds: rectOf(screen)
+    };
+  });
+
+  const candidates = [];
+  const add = (element, kind, extra = {}) => {
+    if (!root.contains(element) || element.offsetParent === null) return;
+    candidates.push({
+      element,
+      kind,
+      screen_index: screenIndex(element),
+      tag: element.tagName.toLowerCase(),
+      selector: semanticSelector(element),
+      bounds: rectOf(element),
+      ...extra
+    });
+  };
+
+  root.querySelectorAll('.widget.tree-node.wRichText').forEach(element => {
+    if (element.closest('table') || element.closest('.widget.tree-node.wButton')) return;
+    const text = normalize(element.innerText || element.textContent);
+    if (text) add(element, 'text', {text});
+  });
+  root.querySelectorAll('table').forEach(element => {
+    const matrix = Array.from(element.rows).map(row =>
+      Array.from(row.cells).map(cell => normalize(cell.innerText || cell.textContent))
+    ).filter(row => row.some(Boolean));
+    const table = {
+      rows: Array.from(element.rows).map((row, rowIndex) => ({
+        index: rowIndex,
+        cells: Array.from(row.cells).map((cell, columnIndex) => ({
+          row_index: rowIndex,
+          column_index: columnIndex,
+          tag: cell.tagName.toLowerCase(),
+          text: normalize(cell.innerText || cell.textContent),
+          rowspan: cell.rowSpan || 1,
+          colspan: cell.colSpan || 1,
+          bounds: rectOf(cell)
+        }))
+      }))
+    };
+    if (matrix.length) add(element, 'table', {matrix, table, text: matrix.map(row => row.join(' | ')).join('\n')});
+  });
+  root.querySelectorAll('button, .widget.tree-node.wButton').forEach(element => {
+    if (element.closest('table')) return;
+    const nested = element.parentElement?.closest('.widget.tree-node.wButton');
+    if (nested) return;
+    const text = normalize(element.innerText || element.textContent || element.getAttribute('aria-label'));
+    if (text) add(element, 'button', {text});
+  });
+  root.querySelectorAll('img').forEach(element => {
+    const rawSrc = element.currentSrc || element.src || '';
+    add(element, 'image', {
+      text: normalize(element.alt) || 'image',
+      alt: normalize(element.alt),
+      src: rawSrc.startsWith('data:') ? null : rawSrc.slice(0, 4096),
+      embedded: rawSrc.startsWith('data:'),
+      natural_width: element.naturalWidth || 0,
+      natural_height: element.naturalHeight || 0
+    });
+  });
+
+  candidates.sort((left, right) => {
+    if (left.element === right.element) return 0;
+    const relation = left.element.compareDocumentPosition(right.element);
+    if (relation & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+    if (relation & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+    return 0;
+  });
+
+  return {
+    screens,
+    records: candidates.map(({element, ...record}, index) => ({...record, dom_order: index})),
+    browser_stats: {
+      screen_count: screens.length,
+      record_count: candidates.length,
+      text_node_count: root.querySelectorAll('.widget.tree-node.wRichText').length,
+      table_count: root.querySelectorAll('table').length,
+      image_count: root.querySelectorAll('img').length,
+      control_count: root.querySelectorAll('button, .widget.tree-node.wButton').length
+    }
+  };
+}
+"""