test: cover sync_from_registry, build_site and --fix; gate sibling-clone test

Adds fixture-based tests for sync_from_registry (marker replacement,
backslash content, script-tag escaping, --check drift, LF output) and
smoke tests that render a cursor-plugin and an mcp-server site through
build_site.py with escaping checks.

--fix helpers now insert a missing standards-version signal (frontmatter
key or comment marker) instead of failing, matching the documented
"missing or malformed" behavior, and are covered end to end through
_apply_fixes_live. Drops the unused _FRONTMATTER_RE.

The registry-vs-sibling-manifest test now runs only with
DTD_SIBLING_REPOS=1, so a stale local clone no longer fails the suite.

Closes #124

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

Author: TMHSDigital

scripts/add_comment_marker.py

@@ -3,8 +3,9 @@
 Usage: python add_comment_marker.py <file_path> <new_version>
 
 Finds a line matching ``<!-- standards-version: X.Y.Z -->`` (anywhere in the
-file, though convention is the first line) and replaces the version.  Exits 0
-on success, 1 if the marker is absent.
+file, though convention is the first line) and replaces the version. When
+no marker exists one is inserted as the first line. Exits 0 on success, 1 if
+the file cannot be read.
 """
 from __future__ import annotations
 
@@ -16,11 +17,14 @@
 _MARKER_RE = re.compile(r"<!--\s*standards-version\s*:\s*[^\s>]+\s*-->")
 
 
-def _update(text: str, new_version: str) -> str | None:
-    """Return updated text, or None if no marker is found."""
+def _update(text: str, new_version: str) -> str:
+    """Return *text* with the marker set to *new_version*, inserting the
+    marker as the first line when it is absent."""
     new_marker = f"<!-- standards-version: {new_version} -->"
-    updated, count = _MARKER_RE.subn(new_marker, text, count=1)
-    return updated if count else None
+    updated, count = _MARKER_RE.subn(lambda _m: new_marker, text, count=1)
+    if count:
+        return updated
+    return new_marker + "\n" + text
 
 
 def main(argv: list[str]) -> int:
@@ -38,10 +42,6 @@ def main(argv: list[str]) -> int:
         return 1
 
     updated = _update(text, new_version)
-    if updated is None:
-        print(f"error: standards-version marker not found in {path}", file=sys.stderr)
-        return 1
-
     path.write_text(updated, encoding="utf-8", newline="\n")
     print(f"updated {path}")
     return 0

scripts/add_frontmatter.py

@@ -3,8 +3,10 @@
 Usage: python add_frontmatter.py <file_path> <new_version>
 
 Finds the ``standards-version:`` key inside the leading ``---`` block and
-replaces its value.  Exits 0 on success, 1 if the marker is absent or the
-file cannot be parsed.
+replaces its value. When the key is missing it is inserted as the first key
+of the existing frontmatter block, and when the file has no frontmatter at
+all a minimal block is prepended. Exits 0 on success, 1 if the file cannot
+be read.
 """
 from __future__ import annotations
 
@@ -13,28 +15,26 @@
 from pathlib import Path
 
 
-_FRONTMATTER_RE = re.compile(r"\Astandardsversion:", re.I)  # loose sentinel
-
-
-def _update(text: str, new_version: str) -> str | None:
-    """Return updated text, or None if the standards-version key is absent."""
+def _update(text: str, new_version: str) -> str:
+    """Return *text* with ``standards-version`` set to *new_version*."""
     lines = text.splitlines(keepends=True)
-    in_block = False
-    for i, line in enumerate(lines):
-        stripped = line.lstrip()
-        if i == 0 and stripped.rstrip() == "---":
-            in_block = True
-            continue
-        if in_block and stripped.rstrip() in ("---", "..."):
-            break
-        if in_block and re.match(r"^standards-version\s*:", stripped):
-            lines[i] = re.sub(
-                r"(standards-version\s*:\s*).*",
-                rf"\g<1>{new_version}",
-                line,
-            )
-            return "".join(lines)
-    return None
+    has_block = bool(lines) and lines[0].strip() == "---"
+    if has_block:
+        for i, line in enumerate(lines[1:], start=1):
+            stripped = line.lstrip()
+            if stripped.rstrip() in ("---", "..."):
+                break
+            if re.match(r"^standards-version\s*:", stripped):
+                lines[i] = re.sub(
+                    r"(standards-version\s*:\s*).*",
+                    lambda m: m.group(1) + new_version,
+                    line,
+                )
+                return "".join(lines)
+        # Block exists but lacks the key: insert it as the first key.
+        lines.insert(1, f"standards-version: {new_version}\n")
+        return "".join(lines)
+    return f"---\nstandards-version: {new_version}\n---\n" + text
 
 
 def main(argv: list[str]) -> int:
@@ -52,10 +52,6 @@ def main(argv: list[str]) -> int:
         return 1
 
     updated = _update(text, new_version)
-    if updated is None:
-        print(f"error: standards-version not found in frontmatter of {path}", file=sys.stderr)
-        return 1
-
     path.write_text(updated, encoding="utf-8", newline="\n")
     print(f"updated {path}")
     return 0

tests/test_build_site.py

@@ -0,0 +1,105 @@
+"""Smoke tests for site-template/build_site.py: a minimal cursor-plugin
+repo and a minimal mcp-server repo must both render, and repo-supplied text
+must be HTML-escaped."""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+BUILD_SITE = REPO_ROOT / "site-template" / "build_site.py"
+
+pytest.importorskip("jinja2")
+
+HOSTILE = '<script>alert(1)</script> & "quotes"'
+
+
+def _site(**extra) -> str:
+    """Minimal site.json matching what the scaffold emits."""
+    site = {
+        "accent": "#7c3aed",
+        "accentLight": "#a78bfa",
+        "heroGradientFrom": "#0d1117",
+        "heroGradientTo": "#161b22",
+        "links": {"github": "https://github.com/TMHSDigital/Sample"},
+        "installSteps": ["Install it"],
+    }
+    site.update(extra)
+    return json.dumps(site)
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _build(repo: Path, out: Path) -> str:
+    result = subprocess.run(
+        [sys.executable, str(BUILD_SITE), "--repo-root", str(repo), "--out", str(out)],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+    return (out / "index.html").read_text(encoding="utf-8")
+
+
+def test_cursor_plugin_site_renders_and_escapes(tmp_path: Path):
+    repo = tmp_path / "plugin"
+    _write(repo / "site.json", _site(title="Sample Plugin", description=HOSTILE))
+    _write(
+        repo / ".cursor-plugin" / "plugin.json",
+        json.dumps({
+            "name": "sample-plugin",
+            "displayName": "Sample Plugin",
+            "description": HOSTILE,
+            "version": "1.2.3",
+            "repository": "https://github.com/TMHSDigital/Sample-Plugin",
+            "license": "CC-BY-NC-ND-4.0",
+        }),
+    )
+    _write(
+        repo / "skills" / "first-skill" / "SKILL.md",
+        "---\nname: first-skill\ndescription: Does the first thing\n---\n# First\n",
+    )
+    _write(repo / "rules" / "style.mdc", "---\ndescription: Style rule\n---\nBody\n")
+    _write(
+        repo / "mcp-tools.json",
+        json.dumps([{"name": "sample_tool", "description": HOSTILE, "category": "General"}]),
+    )
+    _write(
+        repo / "CHANGELOG.md",
+        "# Changelog\n\n## [Unreleased]\n\n## [1.2.3] - 2026-01-01\n\n### Fixed\n\n- A fix\n",
+    )
+
+    html = _build(repo, tmp_path / "out")
+    assert "Sample Plugin" in html
+    assert "Does the first thing" in html
+    assert "sample_tool" in html
+    assert "1.2.3" in html
+    assert "<script>alert(1)</script>" not in html
+    assert "&lt;script&gt;" in html
+
+
+def test_mcp_server_site_renders_from_package_json(tmp_path: Path):
+    repo = tmp_path / "server"
+    _write(repo / "site.json", _site(description="A sample server"))
+    _write(
+        repo / "package.json",
+        json.dumps({
+            "name": "@tmhs/sample-mcp",
+            "version": "0.4.0",
+            "description": "A sample server",
+            "repository": {"url": "git+https://github.com/TMHSDigital/sample-mcp.git"},
+            "license": "CC-BY-NC-ND-4.0",
+        }),
+    )
+    _write(repo / "mcp-tools.json", json.dumps([{"name": "do_thing", "description": "x"}]))
+
+    html = _build(repo, tmp_path / "out")
+    assert "Sample MCP" in html
+    assert "do_thing" in html
+    assert "0.4.0" in html

tests/test_fix_scripts.py

@@ -0,0 +1,104 @@
+"""Tests for the --fix helpers (add_frontmatter.py, add_comment_marker.py)
+and the drift-check path that invokes them."""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+from scripts.drift_check import cli
+from scripts.drift_check.semver import parse_version
+from scripts.drift_check.types import Finding, RepoConfig, RepoSnapshot
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+
+
+def _load(name: str):
+    spec = importlib.util.spec_from_file_location(name, SCRIPTS_DIR / f"{name}.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+fm = _load("add_frontmatter")
+cm = _load("add_comment_marker")
+
+
+# ------------------------------- frontmatter --------------------------------
+
+
+def test_frontmatter_replaces_existing_value():
+    text = "---\nname: x\nstandards-version: 1.0.0\n---\nbody\n"
+    assert fm._update(text, "1.10.1") == "---\nname: x\nstandards-version: 1.10.1\n---\nbody\n"
+
+
+def test_frontmatter_inserts_key_into_existing_block():
+    text = "---\nname: x\n---\nbody\n"
+    assert fm._update(text, "1.10.1") == "---\nstandards-version: 1.10.1\nname: x\n---\nbody\n"
+
+
+def test_frontmatter_prepends_block_when_absent():
+    text = "# Title\n"
+    assert fm._update(text, "1.10.1") == "---\nstandards-version: 1.10.1\n---\n# Title\n"
+
+
+def test_frontmatter_ignores_key_outside_block():
+    text = "---\nname: x\n---\nstandards-version: 0.0.1\n"
+    out = fm._update(text, "2.0.0")
+    assert out.startswith("---\nstandards-version: 2.0.0\nname: x\n---\n")
+    assert out.endswith("standards-version: 0.0.1\n")
+
+
+def test_frontmatter_main_writes_file(tmp_path: Path):
+    path = tmp_path / "SKILL.md"
+    path.write_text("---\nname: x\n---\n", encoding="utf-8")
+    assert fm.main(["add_frontmatter.py", str(path), "1.2.3"]) == 0
+    assert "standards-version: 1.2.3" in path.read_text(encoding="utf-8")
+
+
+# ------------------------------- comment marker -----------------------------
+
+
+def test_marker_replaces_existing():
+    text = "<!-- standards-version: 1.0.0 -->\n# Agents\n"
+    assert cm._update(text, "1.10.1") == "<!-- standards-version: 1.10.1 -->\n# Agents\n"
+
+
+def test_marker_inserted_when_missing():
+    assert cm._update("# Agents\n", "1.10.1") == "<!-- standards-version: 1.10.1 -->\n# Agents\n"
+
+
+def test_marker_main_on_missing_file_fails(tmp_path: Path):
+    assert cm.main(["add_comment_marker.py", str(tmp_path / "nope.md"), "1.0.0"]) == 1
+
+
+# ------------------------------- --fix wiring -------------------------------
+
+
+def test_apply_fixes_live_inserts_missing_signal(tmp_path: Path):
+    repo = tmp_path / "repo"
+    (repo / "skills" / "a").mkdir(parents=True)
+    skill = repo / "skills" / "a" / "SKILL.md"
+    skill.write_text("---\nname: a\n---\nbody\n", encoding="utf-8")
+    agents = repo / "AGENTS.md"
+    agents.write_text("# Agents\n", encoding="utf-8")
+
+    meta = parse_version("1.10.1")
+    snap = RepoSnapshot(
+        slug="repo",
+        repo_type="cursor-plugin",
+        files={},
+        meta_version=meta,
+        meta_commit="sha",
+        config=RepoConfig(slug="repo", repo_type="cursor-plugin"),
+    )
+    findings = [
+        Finding(repo="repo", file=Path("skills/a/SKILL.md"), check="version-signal",
+                severity="error", message="missing standards-version"),
+        Finding(repo="repo", file=Path("AGENTS.md"), check="version-signal",
+                severity="error", message="missing standards-version"),
+    ]
+    touched = cli._apply_fixes_live([snap], [repo], findings, SCRIPTS_DIR, meta)
+    assert touched == 2
+    assert "standards-version: 1.10.1" in skill.read_text(encoding="utf-8")
+    assert agents.read_text(encoding="utf-8").startswith("<!-- standards-version: 1.10.1 -->")

tests/test_registry_manifest_counts.py

@@ -11,6 +11,7 @@
 """
 
 import json
+import os
 from pathlib import Path
 
 import pytest
@@ -30,6 +31,13 @@ def _sibling_checkout(repo_field: str) -> Path | None:
     return candidate if candidate.is_dir() else None
 
 
+@pytest.mark.skipif(
+    os.environ.get("DTD_SIBLING_REPOS") != "1",
+    reason=(
+        "set DTD_SIBLING_REPOS=1 to compare against sibling tool checkouts; "
+        "off by default so a stale local clone cannot fail the suite"
+    ),
+)
 def test_registry_mcptools_matches_local_manifests():
     mismatches = []
     checked = []
@@ -57,7 +65,10 @@ def test_registry_mcptools_matches_local_manifests():
             "validation runs CI-side where repos can be cloned"
         )
 
-    assert not mismatches, "registry mcpTools != manifest length: " + ", ".join(
+    assert not mismatches, (
+        "registry mcpTools != manifest length (run `git pull` in each sibling "
+        "checkout first; a stale clone reports false drift): "
+    ) + ", ".join(
         f"{slug}: registry={declared} manifest={actual}"
         for slug, declared, actual in mismatches
     )