sync update from LAN repo (source dhk-1 @ 3b1ec5b4)

This commit is contained in:
gozeros committed 2026-11-05 10:56:34 +08:00
1 parent da6521b6cb
commit 264e2200d6
995 files changed
+148105 -13399

No files matched your search

@@ -0,0 +1,11 @@
#!/usr/bin/env python3
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "_shared"))
import render_white_house_page as renderer
from fast_patch_page import run
if __name__ == "__main__":
sys.exit(run(renderer, output_stem="white-house-page"))
@@ -0,0 +1,574 @@
#!/usr/bin/env python3
"""Validate White House page data and render the bundled template."""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
from typing import Any
from urllib.parse import urlparse
SKILL_DIR = Path(__file__).resolve().parents[1]
ASSETS_DIR = SKILL_DIR / "assets"
DEFAULT_DATA_PATH = ASSETS_DIR / "default-data.json"
TEMPLATE_PATH = ASSETS_DIR / "white-house-template.html"
RUNTIME_PATH = ASSETS_DIR / "white-house-runtime.js"
MODULES = (
"site",
"navigation",
"hero",
"notice",
"updates",
"priorities",
"administration",
"calendar",
"participation",
"footer",
)
UPDATE_VISUALS = {"hall", "mobility", "science", "statement", "action"}
PARTICIPATION_VISUALS = {"visit", "letter", "service"}
FORBIDDEN_TEXT = ("<script", "<iframe", "javascript:", "http://", "https://")
REMOTE_MEDIA_TYPES = {"image", "video", "webpage"}
MEDIA_URL_KEYS = {"mediaUrl", "posterUrl", "pageUrl"}
TECHNICAL_TEXT_KEYS = {"id", "href", "visual", "theme", "language", "day", "countdownValue", "type", "mediaUrl", "posterUrl", "pageUrl"}
class DataValidationError(ValueError):
"""Raised when JSON does not satisfy the fixed page contract."""
def _read_json(path: Path) -> dict[str, Any]:
try:
value = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise DataValidationError(f"input file does not exist: {path}") from exc
except json.JSONDecodeError as exc:
raise DataValidationError(
f"invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}"
) from exc
if not isinstance(value, dict):
raise DataValidationError("top-level JSON value must be an object")
return value
def _mapping(value: Any, path: str, errors: list[str]) -> dict[str, Any]:
if not isinstance(value, dict):
errors.append(f"{path} must be an object")
return {}
return value
def _array(
value: Any,
path: str,
errors: list[str],
*,
minimum: int,
maximum: int,
) -> list[Any]:
if not isinstance(value, list):
errors.append(f"{path} must be an array")
return []
if len(value) < minimum:
errors.append(f"{path} must contain at least {minimum} item(s)")
if len(value) > maximum:
errors.append(f"{path} must contain at most {maximum} item(s)")
return value
def _required_string(value: Any, path: str, errors: list[str]) -> None:
if not isinstance(value, str) or not value.strip():
errors.append(f"{path} must be a non-empty string")
def _href(value: Any, path: str, errors: list[str]) -> None:
_required_string(value, path, errors)
if isinstance(value, str) and not value.startswith("#"):
errors.append(f"{path} must be an in-page anchor beginning with #")
def _unique_id(item: dict[str, Any], path: str, seen: set[str], errors: list[str]) -> None:
item_id = item.get("id")
_required_string(item_id, f"{path}.id", errors)
if isinstance(item_id, str):
if item_id in seen:
errors.append(f"{path}.id duplicates {item_id!r}")
seen.add(item_id)
def _links(
value: Any,
path: str,
errors: list[str],
*,
minimum: int,
maximum: int,
) -> list[Any]:
items = _array(value, path, errors, minimum=minimum, maximum=maximum)
for index, raw in enumerate(items):
item = _mapping(raw, f"{path}[{index}]", errors)
_required_string(item.get("label"), f"{path}[{index}].label", errors)
_href(item.get("href"), f"{path}[{index}].href", errors)
return items
def _validate_no_remote_or_markup(value: Any, path: str, errors: list[str]) -> None:
if isinstance(value, dict):
for key, item in value.items():
if key in MEDIA_URL_KEYS:
continue
_validate_no_remote_or_markup(item, f"{path}.{key}", errors)
elif isinstance(value, list):
for index, item in enumerate(value):
_validate_no_remote_or_markup(item, f"{path}[{index}]", errors)
elif isinstance(value, str):
lowered = value.lower()
if any(token in lowered for token in FORBIDDEN_TEXT):
errors.append(f"{path} must not contain HTML, script, iframe, or remote URLs")
def _remote_url(value: Any, path: str, errors: list[str], *, required: bool = False, data_prefix: str = "") -> None:
if value in (None, "") and not required:
return
if not isinstance(value, str) or not value.strip():
errors.append(f"{path} must be a non-empty URL")
return
candidate = value.strip()
if data_prefix and candidate.lower().startswith(data_prefix):
return
parsed = urlparse(candidate)
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
errors.append(f"{path} must use an http(s) URL")
def _validate_remote_media_tree(value: Any, path: str, errors: list[str]) -> None:
if isinstance(value, list):
for index, item in enumerate(value):
_validate_remote_media_tree(item, f"{path}[{index}]", errors)
return
if not isinstance(value, dict):
return
media = value.get("media")
if isinstance(media, dict) and "type" in media:
media_path = f"{path}.media"
media_data = _mapping(media, media_path, errors)
media_type = media_data.get("type")
if media_type not in REMOTE_MEDIA_TYPES:
errors.append(f"{media_path}.type must be one of: {', '.join(sorted(REMOTE_MEDIA_TYPES))}")
elif media_type in {"image", "video"}:
_remote_url(media_data.get("mediaUrl"), f"{media_path}.mediaUrl", errors, required=True, data_prefix=f"data:{media_type}/")
if media_type == "video":
_remote_url(media_data.get("posterUrl"), f"{media_path}.posterUrl", errors, data_prefix="data:image/")
if media_type == "webpage":
_remote_url(media_data.get("pageUrl"), f"{media_path}.pageUrl", errors, required=True)
_remote_url(media_data.get("mediaUrl"), f"{media_path}.mediaUrl", errors, data_prefix="data:image/")
if "embed" in media_data and not isinstance(media_data.get("embed"), bool):
errors.append(f"{media_path}.embed must be a boolean")
elif media_type in {"image", "video"}:
_remote_url(media_data.get("pageUrl"), f"{media_path}.pageUrl", errors)
for key, item in value.items():
if key != "media":
_validate_remote_media_tree(item, f"{path}.{key}", errors)
def _validate_chinese_reader_copy(
value: Any,
path: str,
errors: list[str],
*,
key: str | None = None,
) -> None:
if isinstance(value, dict):
for child_key, item in value.items():
_validate_chinese_reader_copy(
item,
f"{path}.{child_key}",
errors,
key=child_key,
)
elif isinstance(value, list):
for index, item in enumerate(value):
_validate_chinese_reader_copy(item, f"{path}[{index}]", errors, key=key)
elif (
isinstance(value, str)
and key not in TECHNICAL_TEXT_KEYS
and not (key and key.lower().endswith(("id", "href", "url")))
):
if not any("\u3400" <= character <= "\u9fff" for character in value):
errors.append(f"{path} must use Simplified Chinese reader-facing copy")
def validate_document(data: dict[str, Any]) -> dict[str, int]:
errors: list[str] = []
missing = [name for name in MODULES if name not in data]
extra = [name for name in data if name not in MODULES]
if missing:
errors.append("missing top-level module(s): " + ", ".join(missing))
if extra:
errors.append("unknown top-level module(s): " + ", ".join(extra))
site = _mapping(data.get("site"), "site", errors)
for key in (
"brandName",
"officeName",
"pageTitle",
"description",
"language",
"skipLabel",
):
_required_string(site.get(key), f"site.{key}", errors)
if site.get("language") != "zh-CN":
errors.append("site.language must be zh-CN")
if site.get("theme") not in {"light", "dark", "auto"}:
errors.append("site.theme must be light, dark, or auto")
navigation = _mapping(data.get("navigation"), "navigation", errors)
for key in ("menuLabel", "searchLabel", "themeLightLabel", "themeDarkLabel"):
_required_string(navigation.get(key), f"navigation.{key}", errors)
left_links = _links(
navigation.get("leftLinks"),
"navigation.leftLinks",
errors,
minimum=1,
maximum=5,
)
right_links = _links(
navigation.get("rightLinks"),
"navigation.rightLinks",
errors,
minimum=1,
maximum=5,
)
menu = _mapping(navigation.get("menu"), "navigation.menu", errors)
for key in ("eyebrow", "title", "text", "ctaLabel"):
_required_string(menu.get(key), f"navigation.menu.{key}", errors)
_href(menu.get("ctaHref"), "navigation.menu.ctaHref", errors)
menu_columns = _array(
menu.get("columns"),
"navigation.menu.columns",
errors,
minimum=1,
maximum=4,
)
seen_menu: set[str] = set()
menu_links = 0
for index, raw in enumerate(menu_columns):
item_path = f"navigation.menu.columns[{index}]"
item = _mapping(raw, item_path, errors)
_unique_id(item, item_path, seen_menu, errors)
_required_string(item.get("title"), f"{item_path}.title", errors)
menu_links += len(
_links(
item.get("links"),
f"{item_path}.links",
errors,
minimum=1,
maximum=8,
)
)
search = _mapping(navigation.get("search"), "navigation.search", errors)
for key in ("title", "placeholder", "emptyMessage", "resultPrefix"):
_required_string(search.get(key), f"navigation.search.{key}", errors)
hero = _mapping(data.get("hero"), "hero", errors)
if hero.get("visual") != "executive-house":
errors.append("hero.visual must be executive-house")
for key in (
"kicker",
"title",
"subtitle",
"summary",
"liveActionLabel",
"scrollLabel",
):
_required_string(hero.get(key), f"hero.{key}", errors)
primary = _mapping(hero.get("primaryAction"), "hero.primaryAction", errors)
_required_string(primary.get("label"), "hero.primaryAction.label", errors)
_href(primary.get("href"), "hero.primaryAction.href", errors)
brief = _mapping(hero.get("brief"), "hero.brief", errors)
for key in ("label", "time", "title", "summary"):
_required_string(brief.get(key), f"hero.brief.{key}", errors)
live_modal = _mapping(hero.get("liveModal"), "hero.liveModal", errors)
for key in (
"title",
"streamTitle",
"streamSubtitle",
"location",
"captionsOn",
"captionsOff",
):
_required_string(live_modal.get(key), f"hero.liveModal.{key}", errors)
notice = _mapping(data.get("notice"), "notice", errors)
for key in ("label", "text", "date"):
_required_string(notice.get(key), f"notice.{key}", errors)
_href(notice.get("href"), "notice.href", errors)
updates = _mapping(data.get("updates"), "updates", errors)
for key in ("eyebrow", "title", "summary"):
_required_string(updates.get(key), f"updates.{key}", errors)
update_items = _array(
updates.get("items"), "updates.items", errors, minimum=1, maximum=8
)
seen_updates: set[str] = set()
for index, raw in enumerate(update_items):
item_path = f"updates.items[{index}]"
item = _mapping(raw, item_path, errors)
_unique_id(item, item_path, seen_updates, errors)
for key in ("type", "title", "summary", "date"):
_required_string(item.get(key), f"{item_path}.{key}", errors)
if item.get("visual") not in UPDATE_VISUALS:
errors.append(f"{item_path}.visual must be one of {sorted(UPDATE_VISUALS)}")
priorities = _mapping(data.get("priorities"), "priorities", errors)
for key in ("eyebrow", "title", "summary", "agendaLabel"):
_required_string(priorities.get(key), f"priorities.{key}", errors)
_href(priorities.get("agendaHref"), "priorities.agendaHref", errors)
priority_items = _array(
priorities.get("items"),
"priorities.items",
errors,
minimum=1,
maximum=6,
)
seen_priorities: set[str] = set()
for index, raw in enumerate(priority_items):
item_path = f"priorities.items[{index}]"
item = _mapping(raw, item_path, errors)
_unique_id(item, item_path, seen_priorities, errors)
for key in ("title", "summary", "detail"):
_required_string(item.get(key), f"{item_path}.{key}", errors)
administration = _mapping(data.get("administration"), "administration", errors)
if administration.get("visual") != "portrait":
errors.append("administration.visual must be portrait")
for key in ("eyebrow", "title", "quote", "description", "signature"):
_required_string(administration.get(key), f"administration.{key}", errors)
admin_links = _links(
administration.get("links"),
"administration.links",
errors,
minimum=1,
maximum=6,
)
calendar = _mapping(data.get("calendar"), "calendar", errors)
for key in (
"eyebrow",
"title",
"countdownValue",
"countdownLabel",
"panelEyebrow",
"panelTitle",
"panelText",
):
_required_string(calendar.get(key), f"calendar.{key}", errors)
months = _array(
calendar.get("months"), "calendar.months", errors, minimum=1, maximum=6
)
seen_months: set[str] = set()
event_count = 0
for month_index, raw_month in enumerate(months):
month_path = f"calendar.months[{month_index}]"
month = _mapping(raw_month, month_path, errors)
_unique_id(month, month_path, seen_months, errors)
_required_string(month.get("label"), f"{month_path}.label", errors)
events = _array(
month.get("events"),
f"{month_path}.events",
errors,
minimum=1,
maximum=8,
)
event_count += len(events)
seen_events: set[str] = set()
for event_index, raw_event in enumerate(events):
event_path = f"{month_path}.events[{event_index}]"
event = _mapping(raw_event, event_path, errors)
_unique_id(event, event_path, seen_events, errors)
for key in ("day", "month", "title", "summary", "tag"):
_required_string(event.get(key), f"{event_path}.{key}", errors)
participation = _mapping(data.get("participation"), "participation", errors)
for key in ("eyebrow", "title", "summary"):
_required_string(participation.get(key), f"participation.{key}", errors)
cards = _array(
participation.get("cards"),
"participation.cards",
errors,
minimum=1,
maximum=6,
)
seen_cards: set[str] = set()
for index, raw in enumerate(cards):
item_path = f"participation.cards[{index}]"
item = _mapping(raw, item_path, errors)
_unique_id(item, item_path, seen_cards, errors)
for key in ("kicker", "title", "summary", "actionLabel"):
_required_string(item.get(key), f"{item_path}.{key}", errors)
_href(item.get("actionHref"), f"{item_path}.actionHref", errors)
if item.get("visual") not in PARTICIPATION_VISUALS:
errors.append(
f"{item_path}.visual must be one of {sorted(PARTICIPATION_VISUALS)}"
)
newsletter = _mapping(
participation.get("newsletter"), "participation.newsletter", errors
)
for key in ("title", "text", "placeholder", "button", "successPrefix"):
_required_string(newsletter.get(key), f"participation.newsletter.{key}", errors)
footer = _mapping(data.get("footer"), "footer", errors)
_required_string(footer.get("description"), "footer.description", errors)
footer_columns = _array(
footer.get("columns"), "footer.columns", errors, minimum=1, maximum=4
)
seen_footer: set[str] = set()
footer_links = 0
for index, raw in enumerate(footer_columns):
item_path = f"footer.columns[{index}]"
item = _mapping(raw, item_path, errors)
_unique_id(item, item_path, seen_footer, errors)
_required_string(item.get("title"), f"{item_path}.title", errors)
footer_links += len(
_links(
item.get("links"),
f"{item_path}.links",
errors,
minimum=1,
maximum=8,
)
)
_required_string(footer.get("copyright"), "footer.copyright", errors)
_required_string(footer.get("legal"), "footer.legal", errors)
_validate_remote_media_tree(data, "$", errors)
_validate_no_remote_or_markup(data, "$", errors)
_validate_chinese_reader_copy(data, "$", errors)
if errors:
raise DataValidationError("\n".join(f"- {error}" for error in errors))
return {
"header_links": len(left_links) + len(right_links),
"menu_columns": len(menu_columns),
"menu_links": menu_links,
"updates": len(update_items),
"priorities": len(priority_items),
"administration_links": len(admin_links),
"months": len(months),
"events": event_count,
"participation_cards": len(cards),
"footer_columns": len(footer_columns),
"footer_links": footer_links,
}
def render_document(data: dict[str, Any], template: str, runtime: str) -> str:
validate_document(data)
data_text = json.dumps(data, ensure_ascii=False, separators=(",", ":"))
data_text = data_text.replace("</script", "<\\/script")
if template.count("__WHITE_HOUSE_PAGE_DATA__") != 1:
raise DataValidationError(
"template must contain one __WHITE_HOUSE_PAGE_DATA__ marker"
)
if template.count("__WHITE_HOUSE_PAGE_RUNTIME__") != 1:
raise DataValidationError(
"template must contain one __WHITE_HOUSE_PAGE_RUNTIME__ marker"
)
rendered = template.replace("__WHITE_HOUSE_PAGE_DATA__", data_text).replace(
"__WHITE_HOUSE_PAGE_RUNTIME__", runtime
)
if "__WHITE_HOUSE_PAGE_" in rendered:
raise DataValidationError("unresolved template marker remains in rendered HTML")
return rendered
def _write_new(path: Path, content: str) -> None:
if path.exists():
raise DataValidationError(
f"refusing to overwrite existing file: {path}; choose a new path"
)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8", newline="\n")
def _emit(payload: dict[str, Any]) -> None:
print(json.dumps(payload, ensure_ascii=False))
def _command_init(output: Path) -> dict[str, Any]:
data = _read_json(DEFAULT_DATA_PATH)
counts = validate_document(data)
_write_new(output, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
return {
"status": "ok",
"action": "init",
"output": str(output),
"modules": list(MODULES),
"counts": counts,
}
def _command_validate(input_path: Path) -> dict[str, Any]:
counts = validate_document(_read_json(input_path))
return {
"status": "ok",
"action": "validate",
"input": str(input_path),
"modules": list(MODULES),
"counts": counts,
}
def _command_render(input_path: Path, output: Path) -> dict[str, Any]:
data = _read_json(input_path)
counts = validate_document(data)
template = TEMPLATE_PATH.read_text(encoding="utf-8")
runtime = RUNTIME_PATH.read_text(encoding="utf-8")
_write_new(output, render_document(data, template, runtime))
return {
"status": "ok",
"action": "render",
"input": str(input_path),
"output": str(output),
"modules": list(MODULES),
"counts": counts,
}
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="Initialize, validate, and render White House-style portal JSON."
)
subparsers = parser.add_subparsers(dest="command", required=True)
init_parser = subparsers.add_parser("init", help="write a fresh default JSON file")
init_parser.add_argument("--output", required=True, type=Path)
validate_parser = subparsers.add_parser("validate", help="validate a JSON file")
validate_parser.add_argument("--input", required=True, type=Path)
render_parser = subparsers.add_parser(
"render", help="render validated JSON into the fixed HTML template"
)
render_parser.add_argument("--input", required=True, type=Path)
render_parser.add_argument("--output", required=True, type=Path)
return parser
def main(argv: list[str] | None = None) -> int:
parser = _build_parser()
args = parser.parse_args(argv)
try:
if args.command == "init":
payload = _command_init(args.output)
elif args.command == "validate":
payload = _command_validate(args.input)
else:
payload = _command_render(args.input, args.output)
_emit(payload)
return 0
except (DataValidationError, OSError) as exc:
_emit({"status": "error", "action": args.command, "message": str(exc)})
return 1
if __name__ == "__main__":
sys.exit(main())