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

modao_prd_cli/modao_prd/schemas/document-2.0.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "document-2.0.json",
+  "title": "Modao PRD document",
+  "type": "object",
+  "required": ["schema_version", "source", "facts", "derived", "evidence", "coverage", "warnings", "stats"],
+  "properties": {
+    "schema_version": {"const": "2.0"},
+    "source": {"type": "object"},
+    "facts": {"type": "object", "required": ["screens", "states", "blocks", "tables", "assets", "observed_interactions", "visual_regions"]},
+    "derived": {"type": "object", "required": ["requirements", "declared_interactions", "layout_relations"]},
+    "evidence": {"type": "array"},
+    "coverage": {"type": "object"},
+    "capture": {"type": "object"},
+    "network": {"type": "array"},
+    "stats": {"type": "object"},
+    "document": {"type": "object"},
+    "warnings": {"type": "array", "items": {"type": "string"}}
+  },
+  "additionalProperties": true
+}

modao_prd_cli/modao_prd/schemas/document-2.1.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "document-2.1.json",
+  "title": "Modao PRD Agent document",
+  "description": "Compact Agent-facing projection. Detailed DOM/layout evidence is referenced from the evidence bundle.",
+  "type": "object",
+  "required": ["schema_version", "source", "facts", "derived", "evidence", "coverage", "warnings", "stats"],
+  "properties": {
+    "schema_version": {"const": "2.1"},
+    "source": {"type": "object"},
+    "capture": {"type": "object"},
+    "facts": {
+      "type": "object",
+      "required": ["screens", "states", "blocks", "tables", "assets", "observed_interactions", "visual_regions"]
+    },
+    "derived": {
+      "type": "object",
+      "required": ["requirements", "declared_interactions"]
+    },
+    "evidence": {"type": "array"},
+    "network": {"type": "array"},
+    "coverage": {"type": "object"},
+    "document": {
+      "type": "object",
+      "required": ["title", "type", "sections"]
+    },
+    "warnings": {"type": "array", "items": {"type": "string"}},
+    "stats": {"type": "object"}
+  },
+  "additionalProperties": false
+}

modao_prd_cli/modao_prd/schemas/manifest-1.0.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "manifest-1.0.json",
+  "title": "Evidence manifest",
+  "type": "object",
+  "required": ["schema_version", "generated_by", "files"],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "generated_by": {"type": "string", "minLength": 1},
+    "total_size": {"type": "integer", "minimum": 0},
+    "files": {"type": "array", "items": {"$ref": "#/$defs/file"}},
+    "metadata": {"type": "object"}
+  },
+  "$defs": {
+    "file": {
+      "type": "object",
+      "required": ["path", "sha256", "size", "media_type"],
+      "properties": {
+        "path": {"type": "string", "minLength": 1},
+        "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "size": {"type": "integer", "minimum": 0},
+        "media_type": {"type": "string", "minLength": 1}
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}

modao_prd_cli/modao_prd/tests/__init__.py

@@ -0,0 +1 @@
+

modao_prd_cli/modao_prd/tests/fixtures/modao_sample.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html>
+  <body>
+    <main id="screens">
+      <section class="mb-screen" data-title="方舟远征">
+        <div class="widget tree-node wRichText"><div class="text">方舟纪元</div></div>
+        <div class="widget tree-node wRichText"><div class="text">活动时间：7月2日10点-7月8日24点</div></div>
+        <div class="widget tree-node wRichText"><div class="text">点击选中奖池，用户可同时选择1-3奖池。选择低于1个时toast：最少选择1个奖池~。</div></div>
+        <button>远航1次</button>
+        <table>
+          <tr><th>礼物名称</th><th>抽1次需要消耗的道具</th><th>获得概率</th></tr>
+          <tr><td>礼物名称（100钻）</td><td>1</td><td>10%</td></tr>
+          <tr><td>礼物名称（500钻）</td><td>2</td><td>5%</td></tr>
+        </table>
+        <img src="https://cdn.example.test/gift.png" alt="礼物图" />
+      </section>
+    </main>
+  </body>
+</html>
+

modao_prd_cli/modao_prd/tests/test_browser.py

@@ -0,0 +1,54 @@
+import pytest
+
+from modao_prd_cli.modao_prd.browser import (
+    default_output_root,
+    ensure_default_output_ignored,
+    find_project_root,
+    validate_share_url,
+)
+from modao_prd_cli.modao_prd.errors import ModaoPrdError
+
+
+def test_validate_share_url_extracts_project_id():
+    result = validate_share_url("https://modao.cc/proto/k1dsCPMlterfdx9cPa11KY/sharing?view_mode=inspect")
+    assert result.project_id == "k1dsCPMlterfdx9cPa11KY"
+    assert result.host == "modao.cc"
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "http://modao.cc/proto/demo/sharing",
+        "https://example.com/proto/demo/sharing",
+        "https://modao.cc/proto/demo/design",
+        "https://user:pass@modao.cc/proto/demo/sharing",
+        "https://modao.cc:8443/proto/demo/sharing",
+    ],
+)
+def test_validate_share_url_rejects_unsafe_or_unsupported_urls(url):
+    with pytest.raises(ModaoPrdError):
+        validate_share_url(url)
+
+
+def test_default_output_uses_nearest_git_project_root(tmp_path):
+    project = tmp_path / "project"
+    nested = project / "packages" / "web"
+    nested.mkdir(parents=True)
+    (project / ".git").mkdir()
+
+    assert find_project_root(nested) == project
+    assert default_output_root(nested) == project / ".modao-prd"
+
+
+def test_default_output_falls_back_to_current_directory(tmp_path):
+    assert find_project_root(tmp_path) == tmp_path
+    assert default_output_root(tmp_path) == tmp_path / ".modao-prd"
+
+
+def test_default_output_gitignore_entry_is_idempotent(tmp_path):
+    ignore_file = tmp_path / ".gitignore"
+    ignore_file.write_text("dist/", encoding="utf-8")
+
+    assert ensure_default_output_ignored(tmp_path) is True
+    assert ensure_default_output_ignored(tmp_path) is False
+    assert ignore_file.read_text(encoding="utf-8") == "dist/\n/.modao-prd/\n"

modao_prd_cli/modao_prd/tests/test_classifier.py

@@ -0,0 +1,32 @@
+from modao_prd_cli.modao_prd.classifier import classify_blocks
+
+
+def test_classifier_extracts_validation_interaction_and_feedback():
+    requirements, interactions, warnings = classify_blocks(
+        [
+            {
+                "id": "block-001",
+                "type": "text",
+                "text": "点击选中奖池，选择低于1个时toast：最少选择1个奖池~。",
+            }
+        ]
+    )
+    assert requirements[0]["type"] == "validation"
+    assert requirements[0]["feedback"] == "最少选择1个奖池~"
+    assert interactions[0]["trigger"].startswith("点击")
+    assert warnings == []
+
+
+def test_classifier_marks_probability_and_external_reference_for_review():
+    requirements, _interactions, warnings = classify_blocks(
+        [
+            {
+                "id": "block-001",
+                "type": "text",
+                "text": "获得概率10%，具体配置见谷歌文档。",
+            }
+        ]
+    )
+    assert requirements[0]["type"] == "probability"
+    assert any("概率" in warning for warning in warnings)
+    assert any("外部文档" in warning for warning in warnings)

modao_prd_cli/modao_prd/tests/test_cli.py

@@ -0,0 +1,88 @@
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from modao_prd_cli.modao_prd.cli import cli
+from modao_prd_cli.modao_prd.extractor import extract_from_html
+
+
+def _raw_page():
+    return {
+        "requested_url": "https://modao.cc/proto/cli_test/sharing",
+        "final_url": "https://modao.cc/proto/cli_test/sharing",
+        "project_id": "cli_test",
+        "title": "CLI 测试页",
+        "body_text_length": 120,
+        "screens": [{"index": 0, "title": "首页"}],
+        "records": [
+            {
+                "kind": "text",
+                "text": "活动时间：7月2日",
+                "screen_index": 0,
+                "tag": "div",
+                "selector": ".wRichText",
+                "dom_order": 0,
+            }
+        ],
+    }
+
+
+def test_help_and_doctor_json():
+    runner = CliRunner()
+    help_result = runner.invoke(cli, ["--help"])
+    assert help_result.exit_code == 0
+    assert "inspect" in help_result.output
+    with patch("modao_prd_cli.modao_prd.cli.doctor", return_value={"ready": True}):
+        result = runner.invoke(cli, ["doctor", "--json"])
+    assert result.exit_code == 0
+    assert json.loads(result.output)["ready"] is True
+
+
+def test_inspect_json_uses_capture_backend():
+    runner = CliRunner()
+    with patch("modao_prd_cli.modao_prd.cli.capture_page", return_value=_raw_page()):
+        result = runner.invoke(cli, ["inspect", _raw_page()["requested_url"], "--json"])
+    assert result.exit_code == 0
+    payload = json.loads(result.output)
+    assert payload["title"] == "CLI 测试页"
+    assert payload["screens"] == 1
+
+
+def test_export_json_writes_project_directory(tmp_path):
+    runner = CliRunner()
+    with patch("modao_prd_cli.modao_prd.cli.capture_page", return_value=_raw_page()):
+        result = runner.invoke(
+            cli,
+            ["export", _raw_page()["requested_url"], "--format", "json", "--output", str(tmp_path), "--json"],
+        )
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    output_file = tmp_path / "cli_test" / "document.json"
+    assert output_file.is_file()
+    assert payload["files"]["json"] == str(output_file)
+
+
+def test_export_defaults_to_hidden_project_directory_and_updates_gitignore(tmp_path, monkeypatch):
+    runner = CliRunner()
+    monkeypatch.chdir(tmp_path)
+    with patch("modao_prd_cli.modao_prd.cli.capture_page", return_value=_raw_page()):
+        result = runner.invoke(
+            cli,
+            ["export", _raw_page()["requested_url"], "--format", "json", "--json"],
+        )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    output_file = (Path.cwd() / ".modao-prd" / "cli_test" / "document.json").resolve()
+    assert output_file.is_file()
+    assert payload["files"]["json"] == str(output_file)
+    assert Path(".gitignore").read_text(encoding="utf-8") == "/.modao-prd/\n"
+
+
+def test_invalid_url_is_json_error():
+    runner = CliRunner()
+    result = runner.invoke(cli, ["inspect", "https://example.com/proto/a/sharing", "--json"])
+    assert result.exit_code == 1
+    assert json.loads(result.output)["error"]["type"] == "unsupported_url"

modao_prd_cli/modao_prd/tests/test_extractor.py

@@ -0,0 +1,57 @@
+import json
+from pathlib import Path
+
+from modao_prd_cli.modao_prd.extractor import build_document, extract_from_html
+
+
+FIXTURE = Path(__file__).parent / "fixtures" / "modao_sample.html"
+
+
+def test_fixture_extracts_blocks_tables_and_assets():
+    document = extract_from_html(
+        FIXTURE.read_text(encoding="utf-8"),
+        title="方舟纪元",
+        url="https://modao.cc/proto/demo_123/sharing?view_mode=inspect",
+    )
+
+    assert document["schema_version"] == "2.1"
+    assert document["facts"]["blocks"]
+    assert document["derived"]["requirements"]
+    assert "layout_relations" not in document["derived"]
+    assert "blocks" not in document["document"]
+    assert "requirements" not in document
+    assert document["source"]["project_id"] == "demo_123"
+    assert document["facts"]["screens"][0]["title"] == "方舟远征"
+    assert any(block["text"] == "方舟纪元" for block in document["facts"]["blocks"])
+    assert len(document["facts"]["tables"]) == 1
+    assert document["facts"]["tables"][0]["rows"][0]["获得概率"] == "10%"
+    assert document["facts"]["assets"][0]["src"].endswith("gift.png")
+
+
+def test_agent_document_does_not_repeat_state_evidence_on_every_node():
+    raw = {
+        "title": "大页面",
+        "requested_url": "https://modao.cc/proto/demo/sharing",
+        "final_url": "https://modao.cc/proto/demo/sharing",
+        "project_id": "demo",
+        "screens": [{"index": 0, "title": "首页"}],
+        "records": [
+            {"kind": "text", "text": "说明", "screen_index": 0, "dom_order": 0},
+            {"kind": "button", "text": "继续", "screen_index": 0, "dom_order": 1},
+        ],
+        "evidence": [
+            {"id": "evidence-001", "kind": "asset", "state_id": "state-001", "path": "evidence/assets/a.png"},
+            {"id": "evidence-002", "kind": "dom", "state_id": "state-001", "path": "evidence/state-001.dom.json"},
+            {"id": "evidence-003", "kind": "screen_screenshot", "state_id": "state-001", "path": "evidence/state-001.screen-001.png"},
+        ],
+    }
+    document = build_document(raw)
+    assert document["facts"]["blocks"][0]["evidence_ids"] == ["evidence-002", "evidence-003"]
+    assert document["facts"]["blocks"][1]["evidence_ids"] == ["evidence-002", "evidence-003"]
+    assert document["facts"]["screens"][0]["evidence_ids"] == ["evidence-002", "evidence-003"]
+    assert len(json.dumps(document, ensure_ascii=False)) < 12000
+
+
+def test_ndjson_like_payload_is_json_safe():
+    document = extract_from_html(FIXTURE.read_text(encoding="utf-8"))
+    assert json.dumps(document, ensure_ascii=False)

modao_prd_cli/modao_prd/tests/test_full_e2e.py

@@ -0,0 +1,23 @@
+import json
+import os
+
+import pytest
+
+from modao_prd_cli.modao_prd.browser import capture_page
+from modao_prd_cli.modao_prd.extractor import build_document
+
+
+SAMPLE_URL = "https://modao.cc/proto/k1dsCPMlterfdx9cPa11KY/sharing?view_mode=inspect"
+
+
+@pytest.mark.live
+@pytest.mark.skipif(os.environ.get("MODAO_PRD_LIVE_E2E") != "1", reason="set MODAO_PRD_LIVE_E2E=1 to access Modao")
+def test_live_modao_share_is_extractable():
+    document = build_document(capture_page(SAMPLE_URL, timeout_seconds=45))
+    assert document["source"]["title"] == "7月活动-方舟纪元"
+    assert document["stats"]["body_text_length"] > 1000
+    assert document["stats"]["text_block_count"] > 0
+    assert document["stats"]["table_count"] >= 1
+    assert document["stats"]["interaction_count"] > 0
+    assert document["stats"]["requirement_count"] > 0
+    assert json.dumps(document, ensure_ascii=False)

modao_prd_cli/modao_prd/tests/test_writers.py

@@ -0,0 +1,79 @@
+import json
+
+import pytest
+
+from modao_prd_cli.modao_prd.extractor import extract_from_html
+from modao_prd_cli.modao_prd.writers import render_markdown, render_ndjson, write_outputs
+
+
+def _document():
+    return extract_from_html(
+        '<section class="mb-screen" data-title="页面一"><div class="widget tree-node wRichText">点击按钮</div></section>',
+        title="测试文档",
+        url="https://modao.cc/proto/writer_test/sharing",
+    )
+
+
+def test_renderers_produce_expected_formats():
+    document = _document()
+    markdown = render_markdown(document)
+    ndjson = render_ndjson(document)
+    assert "# 测试文档" in markdown
+    assert "## 抓取摘要" in markdown
+    assert "#### 交互说明" in markdown
+    assert markdown.count("点击按钮") == 1
+    assert "## 独立规则" not in markdown
+    assert all(json.loads(line)["type"] for line in ndjson.splitlines())
+
+
+def test_markdown_gives_tables_a_contextual_title():
+    document = extract_from_html(
+        """
+        <section class="mb-screen" data-title="页面一">
+          <table>
+            <tr><th>礼物</th><th>概率</th></tr>
+            <tr><td>礼物 A</td><td>10%</td></tr>
+          </table>
+        </section>
+        """,
+        title="测试文档",
+        url="https://modao.cc/proto/writer_table/sharing",
+    )
+    markdown = render_markdown(document)
+    assert "#### 表格" in markdown
+    assert "##### 页面一 - 表格 1" in markdown
+    assert "#### 未命名表格" not in markdown
+
+
+def test_write_outputs_refuses_existing_files_without_force(tmp_path):
+    document = _document()
+    first = write_outputs(document, tmp_path, "all")
+    assert set(first["files"]) == {"json", "markdown", "ndjson"}
+    with pytest.raises(FileExistsError):
+        write_outputs(document, tmp_path, "all")
+    second = write_outputs(document, tmp_path, "all", force=True)
+    assert second["overwrote"] is True
+
+
+def test_write_outputs_with_evidence_preserves_output_and_manifest_contract(tmp_path):
+    document = _document()
+    output_root = tmp_path / "output"
+    output_dir = output_root / "writer_test"
+    from modao_prd_cli.modao_prd.evidence import EvidenceBundleWriter
+
+    output_dir.mkdir(parents=True)
+    writer = EvidenceBundleWriter(output_dir)
+    result = write_outputs(document, output_root, "all", evidence_writer=writer)
+
+    assert set(result["files"]) == {"json", "markdown", "ndjson"}
+    assert result["format"] == "all"
+    assert result["manifest"] == str(output_dir / "manifest.json")
+    assert result["coverage"] == str(output_dir / "coverage.json")
+
+    manifest = json.loads((output_dir / "manifest.json").read_text())
+    paths = {item["path"] for item in manifest["files"]}
+    assert {"document.json", "document.md", "document.ndjson", "coverage.json"} <= paths
+    assert "evidence/network/index.ndjson" not in paths
+    assert manifest["metadata"]["project_id"] == "writer_test"
+    assert manifest["metadata"]["document"] == "document.json"
+    assert manifest["metadata"]["format"] == "all"