Fix cached docs artifact upload paths

docs/scripts/merge_published_site.py

@@ -144,21 +144,31 @@ def _download_version_wget(site_base_url: str, version: str, dest: Path) -> None
         print(f"wget failed for {url} (exit {result.returncode})", file=sys.stderr)
         return
 
-    # wget may create dest.parent/<version>/ or nest extra path segments — normalize
+    # wget may create dest.parent/<version>/ or preserve extra URL path
+    # segments such as dest.parent/EmbodiChain/<version>/; normalize that.
     if not dest.is_dir():
-        candidates = list(dest.parent.glob(f"*/{version}"))
-        if len(candidates) == 1 and candidates[0].is_dir():
-            candidates[0].rename(dest)
-        else:
-            nested = dest.parent / version
-            if nested.is_dir() and nested != dest:
-                nested.rename(dest)
+        candidates = [
+            candidate
+            for candidate in dest.parent.rglob(version)
+            if candidate.is_dir() and candidate != dest
+        ]
+        candidates.sort(key=lambda candidate: len(candidate.parts))
+        for candidate in candidates:
+            if (candidate / "index.html").is_file():
+                candidate.rename(dest)
+                break
 
     if dest.is_dir():
         changes = normalize_artifact_paths(dest)
         if changes:
             print(f"Normalized {len(changes)} artifact path(s) in {version}.")
 
+    for directory in sorted(
+        dest.parent.rglob("*"), key=lambda item: len(item.parts), reverse=True
+    ):
+        if directory.is_dir() and not any(directory.iterdir()):
+            directory.rmdir()
+
 
 def merge_published_site(
     build_dir: Path,
@@ -181,6 +191,11 @@ def merge_published_site(
     build_dir = build_dir.resolve()
     build_dir.mkdir(parents=True, exist_ok=True)
     skip = skip_versions or frozenset()
+    initial_changes = normalize_artifact_paths(build_dir)
+    if initial_changes:
+        print(
+            f"Normalized {len(initial_changes)} existing artifact path(s) in build tree."
+        )
 
     manifest = load_versions_manifest(
         site_base_url=site_base_url,
@@ -219,6 +234,10 @@ def merge_published_site(
                 file=sys.stderr,
             )
 
+    final_changes = normalize_artifact_paths(build_dir)
+    if final_changes:
+        print(f"Normalized {len(final_changes)} artifact path(s) in build tree.")
+
     return merged
 
 

tests/docs/conftest.py

@@ -38,3 +38,4 @@ def _load_merge_module():
 load_versions_manifest = _merge.load_versions_manifest
 merge_published_site = _merge.merge_published_site
 normalize_artifact_paths = _merge.normalize_artifact_paths
+download_version_wget = _merge._download_version_wget

tests/docs/test_merge_published_site.py

@@ -20,11 +20,13 @@
 
 import json
 import shutil
+import subprocess
 from pathlib import Path
 
 import pytest
 
 from .conftest import (
+    download_version_wget,
     load_versions_manifest,
     merge_published_site,
     normalize_artifact_paths,
@@ -115,6 +117,26 @@ def test_merge_does_not_overwrite_existing_version(
     )
 
 
+def test_merge_normalizes_existing_cached_version(
+    build_dir: Path, published_site: Path
+) -> None:
+    """Cached version dirs must be cleaned even when merge skips them."""
+    static_dir = build_dir / "v0.2.0" / "_static"
+    static_dir.mkdir(parents=True)
+    query_file = static_dir / "clipboard.min.js?v=a7894cd8"
+    query_file.write_text("cached", encoding="utf-8")
+
+    merged = merge_published_site(
+        build_dir,
+        published_root=published_site,
+        skip_versions=frozenset({"main"}),
+    )
+
+    assert merged == ["v0.1.0"]
+    assert not query_file.exists()
+    assert (static_dir / "clipboard.min.js").read_text(encoding="utf-8") == "cached"
+
+
 def test_merge_skip_version_for_fresh_tag_build(
     build_dir: Path, published_site: Path
 ) -> None:
@@ -189,3 +211,30 @@ def test_normalize_artifact_paths_removes_duplicate_query_file(tmp_path: Path) -
     assert changes == [(query_file, None)]
     assert safe_file.read_text(encoding="utf-8") == "existing"
     assert not query_file.exists()
+
+
+def test_download_version_wget_promotes_repo_prefixed_output(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """GitHub Pages URLs may make wget create build/html/EmbodiChain/vX.Y.Z."""
+    build_dir = tmp_path / "build" / "html"
+    dest = build_dir / "v0.2.2"
+
+    def fake_run(*args: object, **kwargs: object) -> subprocess.CompletedProcess[str]:
+        static_dir = build_dir / "EmbodiChain" / "v0.2.2" / "_static"
+        static_dir.mkdir(parents=True)
+        (static_dir.parent / "index.html").write_text("nested", encoding="utf-8")
+        (static_dir / "clipboard.min.js?v=a7894cd8").write_text(
+            "copy", encoding="utf-8"
+        )
+        return subprocess.CompletedProcess(args=[], returncode=0)
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+
+    download_version_wget("https://dexforce.github.io/EmbodiChain", "v0.2.2", dest)
+
+    assert (dest / "index.html").read_text(encoding="utf-8") == "nested"
+    assert (dest / "_static" / "clipboard.min.js").read_text(encoding="utf-8") == (
+        "copy"
+    )
+    assert not (build_dir / "EmbodiChain").exists()