test-drive-skill 0.1.0__tar.gz

test_drive_skill-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deyna256
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

test_drive_skill-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: test-drive-skill
+Version: 0.1.0
+Summary: Helpers for the Test Drive agent skill
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/deyna256/test-drive
+Project-URL: Issues, https://github.com/deyna256/test-drive/issues
+Description-Content-Type: text/markdown
+
+# test-drive-skill
+
+The Python helpers for [Test Drive](https://github.com/deyna256/test-drive), an agent skill for
+testing web user journeys and creating reports with recordings. The `test-drive` command checks
+scenario file structure, selects or sets up `agent-browser`, and renders HTML reports.
+
+The package requires Python 3.10 or newer and has no third-party Python runtime dependencies.
+Browser testing also requires `agent-browser` and Chrome or Chromium. Recording WebM video requires
+FFmpeg with the `libvpx` encoder. Install the agent skill separately; see the
+[project README](https://github.com/deyna256/test-drive#readme) for setup and usage.

test_drive_skill-0.1.0/README.md

@@ -0,0 +1,10 @@
+# test-drive-skill
+
+The Python helpers for [Test Drive](https://github.com/deyna256/test-drive), an agent skill for
+testing web user journeys and creating reports with recordings. The `test-drive` command checks
+scenario file structure, selects or sets up `agent-browser`, and renders HTML reports.
+
+The package requires Python 3.10 or newer and has no third-party Python runtime dependencies.
+Browser testing also requires `agent-browser` and Chrome or Chromium. Recording WebM video requires
+FFmpeg with the `libvpx` encoder. Install the agent skill separately; see the
+[project README](https://github.com/deyna256/test-drive#readme) for setup and usage.

test_drive_skill-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "test-drive-skill"
+version = "0.1.0"
+description = "Helpers for the Test Drive agent skill"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/deyna256/test-drive"
+Issues = "https://github.com/deyna256/test-drive/issues"
+
+[project.scripts]
+test-drive = "test_drive.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.16.10",
+    "ty>=0.0.84",
+]
+
+[tool.uv.build-backend]
+module-name = "test_drive"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "C4",
+    "UP",
+    "SIM",
+    "RUF",
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/test_drive/report.py" = ["RUF001"]
+"**/tests/**" = ["RUF001"]

test_drive_skill-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "test-drive-skill"
+version = "0.1.0"
+description = "Helpers for the Test Drive agent skill"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/deyna256/test-drive"
+Issues = "https://github.com/deyna256/test-drive/issues"
+
+[project.scripts]
+test-drive = "test_drive.cli:main"
+
+[dependency-groups]
+dev = ["ruff>=0.16.10", "ty>=0.0.84"]
+
+[tool.uv.build-backend]
+module-name = "test_drive"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM", "RUF"]
+# The formatter cannot wrap every HTML, URL, or multilingual fixture string.
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# Russian labels and multilingual scenarios legitimately contain non-Latin characters.
+"**/test_drive/report.py" = ["RUF001"]
+"**/tests/**" = ["RUF001"]

test_drive_skill-0.1.0/src/test_drive/__init__.py

@@ -0,0 +1 @@
+"""Runtime helpers for the Test Drive agent skill."""

test_drive_skill-0.1.0/src/test_drive/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

test_drive_skill-0.1.0/src/test_drive/agent_browser.py

@@ -0,0 +1,69 @@
+"""Find the browser CLI version used by Test Drive."""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def runtime_directory() -> Path:
+    return Path(
+        os.environ.get("TEST_DRIVE_RUNTIME_DIR") or Path.home() / ".test-drive" / "agent-browser"
+    ).expanduser()
+
+
+def runtime_browser(directory: Path) -> Path:
+    return (
+        directory
+        / "node_modules"
+        / ".bin"
+        / ("agent-browser.cmd" if os.name == "nt" else "agent-browser")
+    )
+
+
+def main() -> int:
+    argparse.ArgumentParser(description="Find a compatible agent-browser CLI").parse_args()
+    managed = runtime_browser(runtime_directory())
+    browser = os.environ.get("TEST_DRIVE_AGENT_BROWSER") or (
+        str(managed) if managed.is_file() else shutil.which("agent-browser")
+    )
+    if not browser:
+        print(
+            "agent-browser >=0.40.0 was not found; set TEST_DRIVE_AGENT_BROWSER to its executable path.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        path = Path(browser).expanduser().resolve(strict=True)
+        result = subprocess.run(
+            [str(path), "--version"],
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=10,
+            check=False,
+        )
+    except (OSError, RuntimeError, subprocess.TimeoutExpired) as exc:
+        print(f"Cannot run agent-browser at {browser}: {exc}", file=sys.stderr)
+        return 1
+
+    version = result.stdout.strip()
+    match = re.fullmatch(
+        r"agent-browser (0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z.-]+)?", version
+    )
+    if result.returncode != 0 or not match or tuple(map(int, match.groups())) < (0, 40, 0):
+        print(
+            f"Test Drive requires a stable agent-browser >=0.40.0; {path} reported {version or 'no version'}.",
+            file=sys.stderr,
+        )
+        return 1
+    print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

test_drive_skill-0.1.0/src/test_drive/agent_browser_setup.py

@@ -0,0 +1,127 @@
+"""Set up the browser CLI without changing a global installation."""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from .agent_browser import runtime_browser, runtime_directory
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Set up Test Drive's browser CLI")
+    parser.add_argument("--directory", type=Path, default=runtime_directory())
+    args = parser.parse_args()
+    existing = subprocess.run(
+        [sys.executable, str(Path(__file__).with_name("agent_browser.py"))],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if existing.returncode == 0:
+        print(f"Using agent-browser: {existing.stdout.strip()}")
+        return 0
+    if os.environ.get("TEST_DRIVE_AGENT_BROWSER"):
+        print(existing.stderr.strip(), file=sys.stderr)
+        return 1
+
+    target = args.directory.expanduser().resolve()
+    if target.exists():
+        if runtime_browser(target).is_file():
+            env = os.environ.copy()
+            env["TEST_DRIVE_AGENT_BROWSER"] = str(runtime_browser(target))
+            found = subprocess.run(
+                [sys.executable, str(Path(__file__).with_name("agent_browser.py"))],
+                env=env,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if found.returncode == 0:
+                print(f"Using agent-browser: {found.stdout.strip()}")
+                return 0
+        print(
+            f"Runtime directory already exists: {target}. Choose another directory; it was not changed.",
+            file=sys.stderr,
+        )
+        return 1
+    npm, node = shutil.which("npm"), shutil.which("node")
+    if not npm or not node:
+        print("Node.js 24+ and npm are required to install agent-browser.", file=sys.stderr)
+        return 1
+    npm_command = [npm]
+    if os.name == "nt" and Path(npm).suffix.lower() in (".cmd", ".bat"):
+        npm_cli = Path(npm).parent / "node_modules" / "npm" / "bin" / "npm-cli.js"
+        if not npm_cli.is_file():
+            print("Could not locate npm-cli.js for a safe local installation.", file=sys.stderr)
+            return 1
+        npm_command = [node, str(npm_cli)]
+    try:
+        node_version = subprocess.run(
+            [node, "--version"], capture_output=True, text=True, timeout=10, check=False
+        )
+        match = re.fullmatch(r"v(\d+)\.\d+\.\d+", node_version.stdout.strip())
+        if node_version.returncode or not match or int(match.group(1)) < 24:
+            print("Node.js 24+ is required to install agent-browser.", file=sys.stderr)
+            return 1
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(prefix=".test-drive-", dir=target.parent) as directory:
+            stage = Path(directory)
+            installed = subprocess.run(
+                [
+                    *npm_command,
+                    "install",
+                    "--prefix",
+                    str(stage),
+                    "--no-global",
+                    "--no-save",
+                    "--no-package-lock",
+                    "--ignore-scripts",
+                    "agent-browser@0.40.0",
+                ],
+                cwd=stage,
+                capture_output=True,
+                text=True,
+                timeout=300,
+                check=False,
+            )
+            if installed.returncode:
+                error = re.search(
+                    r"(?m)^npm (?:error|ERR!) code ([A-Z][A-Z0-9_]+)\s*$", installed.stderr
+                )
+                code = f", {error.group(1)}" if error else ""
+                print(
+                    f"npm installation failed (exit {installed.returncode}{code}); check npm and network settings.",
+                    file=sys.stderr,
+                )
+                return 1
+            env = os.environ.copy()
+            env["TEST_DRIVE_AGENT_BROWSER"] = str(runtime_browser(stage))
+            verified = subprocess.run(
+                [sys.executable, str(Path(__file__).with_name("agent_browser.py"))],
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=15,
+                check=False,
+            )
+            if verified.returncode:
+                print(
+                    "The installed agent-browser could not be verified for this platform.",
+                    file=sys.stderr,
+                )
+                return 1
+            stage.rename(target)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        print(f"Could not set up agent-browser: {exc}", file=sys.stderr)
+        return 1
+    print(f"Installed agent-browser: {runtime_browser(target)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

test_drive_skill-0.1.0/src/test_drive/assets/report.html

@@ -0,0 +1,141 @@
+<!doctype html>
+<html lang="$language" dir="$direction">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>$page_title — Test Drive</title>
+  <style>
+    :root { color-scheme: light; --ink:#18263a; --muted:#53667e; --line:#dce4ef; --accent:#295ec1; --paper:#fff; --background:#f3f6fa; }
+    * { box-sizing:border-box; }
+    body { margin:0; background:var(--background); color:var(--ink); font:15px/1.5 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; }
+    a { color:var(--accent); text-decoration-thickness:1px; text-underline-offset:3px; }
+    button { font:inherit; }
+    button:focus-visible, a:focus-visible, video:focus-visible { outline:3px solid #5c8cfc; outline-offset:3px; }
+    .topbar { background:#172a44; color:#fff; padding:14px clamp(18px,4vw,56px); display:flex; align-items:center; gap:11px; }
+    .mark { display:grid; place-items:center; width:32px; height:32px; border-radius:9px; background:#295ec1; font-size:13px; font-weight:800; letter-spacing:.02em; }
+    .brand { font-weight:750; letter-spacing:.01em; }
+    .brand-note { margin-inline-start:auto; color:#bdcbe0; font-size:12px; }
+    .shell { max-width:1500px; margin:auto; padding:30px clamp(18px,4vw,56px) 48px; }
+    .eyebrow { color:#46678d; font-size:11px; font-weight:800; letter-spacing:.12em; text-transform:uppercase; margin:0 0 6px; }
+    h1 { font-size:clamp(25px,3vw,34px); letter-spacing:-.03em; line-height:1.15; margin:0 0 8px; }
+    .metadata { display:flex; gap:8px 18px; flex-wrap:wrap; color:var(--muted); font-size:13px; overflow-wrap:anywhere; }
+    .context { margin-top:15px; color:var(--muted); font-size:13px; }
+    .context p { margin:5px 0; white-space:pre-wrap; overflow-wrap:anywhere; }
+    .context strong { color:var(--ink); }
+    .summary { display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:10px; margin:24px 0; }
+    .stat { background:var(--paper); border:1px solid var(--line); border-radius:10px; padding:12px 14px; min-width:0; }
+    .stat-number { font-size:23px; font-weight:750; line-height:1; font-variant-numeric:tabular-nums; }
+    .stat-label { color:var(--muted); font-size:12px; margin-top:5px; }
+    .workspace { display:grid; grid-template-columns:minmax(215px,275px) minmax(0,1fr); align-items:start; gap:16px; }
+    .sidebar, .panel { background:var(--paper); border:1px solid var(--line); border-radius:12px; }
+    .sidebar { position:sticky; top:16px; overflow:hidden; }
+    .sidebar-heading { padding:15px 16px 12px; border-bottom:1px solid var(--line); display:flex; justify-content:space-between; font-weight:750; }
+    .sidebar-heading span { color:var(--muted); font-weight:500; }
+    .scenario-nav { display:flex; flex-direction:column; gap:3px; padding:7px; max-height:calc(100vh - 180px); overflow:auto; }
+    .scenario-link { display:grid; grid-template-columns:27px minmax(0,1fr); gap:8px; padding:10px 9px; color:var(--ink); text-decoration:none; border-radius:8px; min-height:52px; }
+    .scenario-link:hover { background:#f2f6fd; }
+    .scenario-link[aria-current="true"] { background:#eaf1ff; color:#1e4b9e; }
+    .scenario-number { font:12px/1.5 ui-monospace,SFMono-Regular,Consolas,monospace; color:#52657e; padding-top:1px; }
+    .scenario-name { font-weight:700; overflow-wrap:anywhere; }
+    .scenario-status { display:block; font-size:12px; font-weight:500; margin-top:2px; }
+    .passed { color:#207248; } .failed { color:#a6322d; } .blocked { color:#8a5e12; } .not_run { color:#5f6c7d; }
+    .panel { padding:clamp(18px,2.6vw,30px); min-width:0; }
+    .panel[hidden] { display:none; }
+    .panel-heading { display:flex; justify-content:space-between; gap:12px; align-items:flex-start; }
+    h2 { font-size:clamp(20px,2vw,26px); line-height:1.25; letter-spacing:-.02em; margin:0 0 5px; overflow-wrap:anywhere; }
+    h3 { font-size:15px; margin:0 0 10px; }
+    .source { color:var(--muted); font-size:12px; margin:0; overflow-wrap:anywhere; }
+    .badge { padding:5px 9px; border-radius:99px; font-size:12px; font-weight:750; white-space:nowrap; }
+    .badge.passed { background:#eaf7ee; } .badge.failed { background:#fff0ee; } .badge.blocked { background:#fff5e2; } .badge.not_run { background:#eff2f6; }
+    .outcomes { display:grid; grid-template-columns:1fr 1fr; gap:10px; margin:22px 0; }
+    .outcome { background:#f5f8fc; border:1px solid #edf1f6; border-radius:9px; padding:13px 14px; min-width:0; }
+    .outcome-label { font-size:11px; font-weight:750; color:#526985; letter-spacing:.035em; margin-bottom:5px; }
+    .outcome p, .reason, .step-detail { margin:0; white-space:pre-wrap; overflow-wrap:anywhere; }
+    .reason { padding:11px 13px; margin:16px 0 18px; border-inline-start:3px solid #d9a344; background:#fffbf3; font-size:13px; }
+    .section { margin-top:24px; }
+    .criteria { list-style:none; margin:0; padding:0; display:grid; gap:10px; }
+    .criterion { padding:13px 14px; border:1px solid var(--line); border-radius:9px; background:#f9fbfd; }
+    .criterion-heading { display:flex; justify-content:space-between; align-items:flex-start; gap:12px; font-weight:700; }
+    .criterion-heading > span:first-child { white-space:pre-wrap; overflow-wrap:anywhere; }
+    .criterion-detail { margin:8px 0 0; white-space:pre-wrap; overflow-wrap:anywhere; color:var(--muted); font-size:13px; }
+    .criterion-detail strong { color:var(--ink); }
+    .criterion-evidence { display:flex; align-items:center; gap:12px; font-size:13px; }
+    .criterion-evidence:not(:empty) { margin-top:8px; }
+    .video-wrap { background:#101925; border-radius:9px; overflow:hidden; }
+    video { display:block; width:100%; max-height:560px; background:#101925; }
+    .asset-link { display:inline-block; font-size:13px; margin-top:8px; }
+    .missing { background:#f4f6f9; color:#66778b; border:1px dashed #cbd5e2; border-radius:9px; padding:16px; font-size:13px; }
+    .steps { list-style:none; margin:0; padding:0; padding-inline-start:10px; border-inline-start:2px solid #e3e9f2; }
+    .step { position:relative; padding:0 0 16px; padding-inline-start:16px; }
+    .step:last-child { padding-bottom:0; }
+    .step:before { content:""; position:absolute; inset-inline-start:-6px; top:7px; width:10px; height:10px; background:#fff; border:2px solid #7898c5; border-radius:50%; }
+    .step-title { display:flex; gap:8px; align-items:baseline; flex-wrap:wrap; font-weight:650; }
+    .seek { border:0; padding:6px 8px; min-width:48px; min-height:36px; background:#edf3ff; color:#2359b6; border-radius:5px; font:12px/1.5 ui-monospace,SFMono-Regular,Consolas,monospace; cursor:pointer; }
+    .seek:hover { background:#dce9ff; }
+    .seek:disabled { color:#7d8794; background:#eff1f4; cursor:not-allowed; }
+    .step-detail { color:var(--muted); font-size:13px; margin-top:4px; }
+    .step-status { font-size:12px; font-weight:600; }
+    .evidence { display:block; max-width:100%; max-height:460px; border:1px solid var(--line); border-radius:9px; }
+    details { margin-top:18px; border-top:1px solid var(--line); padding-top:14px; }
+    summary { cursor:pointer; color:#375b91; font-weight:650; }
+    details ol { padding-left:22px; }
+    details li { padding:3px 0; white-space:pre-wrap; overflow-wrap:anywhere; }
+    .empty { background:var(--paper); border:1px solid var(--line); border-radius:12px; padding:25px; color:var(--muted); }
+    .footnote { color:var(--muted); font-size:12px; margin:24px 0 0; }
+    @media (max-width:760px) { .summary { grid-template-columns:repeat(2,minmax(0,1fr)); } .workspace { grid-template-columns:1fr; } .sidebar { position:static; } .scenario-nav { max-height:none; } .brand-note { display:none; } .seek { min-width:48px; min-height:44px; } }
+    @media (max-width:480px) { .outcomes { grid-template-columns:1fr; } .panel-heading { flex-direction:column; } }
+  </style>
+</head>
+<body data-seek-outside="$seek_outside">
+  <header class="topbar"><span class="mark" aria-hidden="true">TD</span><span class="brand">Test Drive</span><span class="brand-note">$brand_note</span></header>
+  <main class="shell">
+    <p class="eyebrow">$report_label</p>
+    <h1>$site_name</h1>
+    <div class="metadata">$metadata</div>
+    $context
+    <section class="summary" aria-label="$summary_aria">$summary</section>
+    $content
+    <p class="footnote">$footnote</p>
+  </main>
+  <script>
+    const panels = Array.from(document.querySelectorAll('.panel[id]'));
+    const links = Array.from(document.querySelectorAll('.scenario-link'));
+    function showScenario(id) {
+      if (!panels.some(panel => panel.id === id)) return;
+      panels.forEach(panel => {
+        if (panel.id !== id) panel.querySelectorAll('video').forEach(video => video.pause());
+        panel.hidden = panel.id !== id;
+      });
+      links.forEach(link => {
+        if (link.hash === '#' + id) link.setAttribute('aria-current', 'true');
+        else link.removeAttribute('aria-current');
+      });
+    }
+    if (panels.length) {
+      const initial = document.querySelector('.scenario-link[data-default]');
+      const navigate = () => {
+        const id = location.hash.slice(1);
+        showScenario(panels.some(panel => panel.id === id) ? id : initial.hash.slice(1));
+      };
+      navigate();
+      window.addEventListener('hashchange', navigate);
+    }
+    document.querySelectorAll('.seek').forEach(button => button.addEventListener('click', () => {
+      const video = button.closest('.panel').querySelector('video');
+      const time = Number(button.dataset.time);
+      if (!video) return;
+      const seek = () => {
+        if (Number.isFinite(video.duration) && time > video.duration) {
+          button.disabled = true;
+          button.title = document.body.dataset.seekOutside;
+          return;
+        }
+        video.currentTime = time;
+        video.play().catch(() => {});
+      };
+      if (video.readyState < 1) video.addEventListener('loadedmetadata', seek, { once:true });
+      else seek();
+    }));
+  </script>
+</body>
+</html>

test_drive_skill-0.1.0/src/test_drive/cli.py

@@ -0,0 +1,31 @@
+"""Command-line entry point for the skill's runtime helpers."""
+
+import argparse
+import json
+import sys
+from importlib import metadata
+
+from . import agent_browser, agent_browser_setup, report, scenarios
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="test-drive", description="Test Drive skill helpers")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"test-drive-skill {metadata.version('test-drive-skill')}",
+    )
+    commands = {
+        "agent-browser-path": agent_browser.main,
+        "setup-agent-browser": agent_browser_setup.main,
+        "check-scenarios": scenarios.main,
+        "render-report": report.main,
+    }
+    parser.add_argument("command", choices=(*commands, "report-labels"))
+    args = parser.parse_args(sys.argv[1:2])
+    if args.command == "report-labels":
+        argparse.ArgumentParser(prog="test-drive report-labels").parse_args(sys.argv[2:])
+        print(json.dumps(report.LABELS, ensure_ascii=False, indent=2))
+        return 0
+    sys.argv = [f"test-drive {args.command}", *sys.argv[2:]]
+    return commands[args.command]()

test_drive_skill-0.1.0/src/test_drive/report.py

@@ -0,0 +1,549 @@
+"""Build a portable HTML report from a run's JSON and local evidence files."""
+
+import argparse
+import html
+import json
+import math
+import re
+import subprocess
+import sys
+import tempfile
+from collections import Counter
+from pathlib import Path
+from string import Template
+from urllib.parse import quote, urlsplit
+
+STATUSES = {
+    "passed": ("Passed", "Passed"),
+    "failed": ("Failed", "Failed"),
+    "blocked": ("Blocked", "Blocked"),
+    "not_run": ("Not run", "Not run"),
+}
+LABELS = {
+    "brand_note": "Test report",
+    "report": "Test run",
+    "summary": "Run summary",
+    "scenarios": "Scenarios",
+    "video": "Recording",
+    "video_label": "Scenario recording",
+    "video_unsupported": "Your browser does not support video.",
+    "video_open": "Open recording",
+    "video_missing": "Recording unavailable",
+    "video_invalid": "The recording could not be decoded",
+    "video_unverified": "The recording could not be verified with ffmpeg",
+    "expected": "Expected",
+    "actual": "Actual",
+    "not_specified": "Not specified",
+    "not_recorded": "Not recorded",
+    "criteria": "Acceptance criteria",
+    "observed": "Observed",
+    "reason": "Reason",
+    "evidence": "Screenshot",
+    "steps": "Steps",
+    "steps_missing": "Steps not recorded",
+    "screenshot": "Result screenshot",
+    "screenshot_alt": "Scenario result screenshot",
+    "screenshot_missing": "Screenshot unavailable",
+    "reproduction": "How to reproduce",
+    "scope": "Scope",
+    "assumptions": "Assumptions",
+    "limitations": "Limitations",
+    "empty": "No scenarios recorded. The test did not run.",
+    "footnote": "The report and available artifacts are stored in the same folder.",
+    "seek": "Go approximately to",
+    "seek_outside": "The timestamp is outside the recording",
+}
+for status, (single, plural) in STATUSES.items():
+    LABELS[status] = single
+    LABELS[f"{status}_count"] = plural
+# Older runs could specify Russian without storing translated labels.
+LEGACY_RU_LABELS = {
+    "brand_note": "Отчёт о проверке",
+    "report": "Отчёт о прогоне",
+    "summary": "Итоги прогона",
+    "scenarios": "Сценарии",
+    "video": "Запись прогона",
+    "video_label": "Запись сценария",
+    "video_unsupported": "Ваш браузер не поддерживает видео.",
+    "video_open": "Открыть запись",
+    "video_missing": "Запись недоступна",
+    "video_invalid": "Не удалось декодировать запись",
+    "video_unverified": "Не удалось проверить запись с помощью ffmpeg",
+    "expected": "Ожидалось",
+    "actual": "Получилось",
+    "not_specified": "Не указано",
+    "not_recorded": "Не зафиксировано",
+    "criteria": "Критерии приёмки",
+    "observed": "Наблюдалось",
+    "reason": "Причина",
+    "evidence": "Снимок",
+    "steps": "Шаги",
+    "steps_missing": "Шаги не записаны",
+    "screenshot": "Снимок результата",
+    "screenshot_alt": "Снимок результата сценария",
+    "screenshot_missing": "Снимок недоступен",
+    "reproduction": "Как воспроизвести",
+    "scope": "Что проверяли",
+    "assumptions": "Допущения",
+    "limitations": "Ограничения",
+    "empty": "Сценарии не записаны. Проверка не выполнена.",
+    "footnote": "Отчёт и доступные материалы хранятся в одной папке.",
+    "seek": "Перейти примерно к",
+    "seek_outside": "Время шага за пределами записи",
+    "passed": "Пройден",
+    "passed_count": "Пройдено",
+    "failed": "Ошибка",
+    "failed_count": "Ошибок",
+    "blocked": "Не удалось проверить",
+    "blocked_count": "Не удалось проверить",
+    "not_run": "Не запускался",
+    "not_run_count": "Не запускалось",
+}
+TEMPLATE = Path(__file__).resolve().parent / "assets" / "report.html"
+
+
+def text(value: object) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def valid_time(value: object) -> bool:
+    try:
+        return (
+            not isinstance(value, bool)
+            and isinstance(value, (int, float))
+            and math.isfinite(value)
+            and value >= 0
+        )
+    except OverflowError:
+        return False
+
+
+def asset_url(root: Path, value: object) -> str | None:
+    if not isinstance(value, str) or not value or Path(value).is_absolute():
+        return None
+    try:
+        file = (root / value).resolve()
+        if not file.is_relative_to(root) or not file.is_file() or file.stat().st_size == 0:
+            return None
+        return quote(file.relative_to(root).as_posix(), safe="/")
+    except (OSError, RuntimeError, ValueError):
+        return None
+
+
+def recording_url(root: Path, value: object) -> tuple[str | None, str | None]:
+    url = asset_url(root, value)
+    if not url or not isinstance(value, str):
+        return None, None
+    try:
+        with (root / value).open("rb") as recording:
+            for protocol, address in (("fd", "fd:"), ("pipe", "pipe:0")):
+                recording.seek(0)
+                result = subprocess.run(
+                    [
+                        "ffmpeg",
+                        "-v",
+                        "error",
+                        "-xerror",
+                        "-nostdin",
+                        "-protocol_whitelist",
+                        protocol,
+                        "-i",
+                        address,
+                        "-map",
+                        "0:v:0",
+                        "-progress",
+                        "pipe:1",
+                        "-f",
+                        "null",
+                        "-",
+                    ],
+                    stdin=recording,
+                    capture_output=True,
+                    text=True,
+                    errors="replace",
+                    timeout=30,
+                    check=False,
+                )
+                if protocol != "fd" or "Protocol not found" not in result.stderr:
+                    break
+    except (OSError, subprocess.TimeoutExpired):
+        return None, "video_unverified"
+    if result.returncode or not re.search(r"^frame=\s*[1-9]\d*\s*$", result.stdout, re.MULTILINE):
+        return None, "video_invalid"
+    return url, None
+
+
+def validate_time(item: dict, started: int | float | None, number: int) -> None:
+    at = item.get("at")
+    recorded = item.get("recorded_at")
+    if (at is not None and not valid_time(at)) or (
+        recorded is not None and not valid_time(recorded)
+    ):
+        raise ValueError(f"Scenario {number} has an invalid step or criterion time")
+    if recorded is not None and (at is not None or started is None or recorded < started):
+        raise ValueError(f"Scenario {number} time does not match the recording start")
+
+
+def criteria_status(criteria: list[dict]) -> str:
+    statuses = {item["status"] for item in criteria}
+    if "failed" in statuses:
+        return "failed"
+    if statuses == {"passed"}:
+        return "passed"
+    if statuses == {"not_run"}:
+        return "not_run"
+    return "blocked"
+
+
+def validate(run: object) -> None:
+    if not isinstance(run, dict) or not isinstance(run.get("site"), dict):
+        raise ValueError("A site object with a name is required")
+    if not isinstance(run["site"].get("name"), str) or not run["site"]["name"].strip():
+        raise ValueError("site.name is required")
+    if run["site"].get("url") is not None and not isinstance(run["site"]["url"], str):
+        raise ValueError("site.url must be a string")
+    if run["site"].get("url"):
+        try:
+            url = urlsplit(run["site"]["url"])
+        except ValueError:
+            raise ValueError(
+                "site.url must be a valid address without credentials, query, or fragment"
+            ) from None
+        if url.username is not None or url.password is not None or url.query or url.fragment:
+            raise ValueError("site.url must omit credentials, query, and fragment")
+    values = [run]
+    while values:
+        value = values.pop()
+        if isinstance(value, dict):
+            values.extend(value.values())
+        elif isinstance(value, list):
+            values.extend(value)
+        elif isinstance(value, str):
+            for match in re.finditer(r"\b(?:https?|file)://[^\s<>\"`]+", value, re.IGNORECASE):
+                try:
+                    url = urlsplit(match.group())
+                    unsafe = (
+                        url.username is not None
+                        or url.password is not None
+                        or url.query
+                        or url.fragment
+                    )
+                except ValueError:
+                    unsafe = True
+                if unsafe:
+                    raise ValueError("Saved URLs must omit credentials, query, and fragment")
+    for field in ("started_at", "duration", "scope", "assumptions", "limitations"):
+        if run.get(field) is not None and not isinstance(run[field], str):
+            raise ValueError(f"{field} must be a string")
+    language = run.get("language", "en")
+    if not isinstance(language, str) or not re.fullmatch(
+        r"[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*", language
+    ):
+        raise ValueError("language must be a language code, such as en or en-US")
+    if run.get("direction", "ltr") not in ("ltr", "rtl"):
+        raise ValueError("direction must be ltr or rtl")
+    labels = run.get("labels", {})
+    if not isinstance(labels, dict) or any(
+        key not in LABELS or not isinstance(value, str) or not value.strip()
+        for key, value in labels.items()
+    ):
+        raise ValueError("labels must contain known keys with non-empty strings")
+    if language.split("-", 1)[0].lower() not in ("en", "ru") and labels.keys() != LABELS.keys():
+        raise ValueError("Provide translations for all labels when using another language")
+    if not isinstance(run.get("scenarios"), list):
+        raise ValueError("A scenarios list is required")
+    for number, scenario in enumerate(run["scenarios"], 1):
+        if (
+            not isinstance(scenario, dict)
+            or not isinstance(scenario.get("name"), str)
+            or not scenario["name"].strip()
+        ):
+            raise ValueError(f"Scenario {number} has no name")
+        if not isinstance(scenario.get("status"), str) or scenario["status"] not in STATUSES:
+            raise ValueError(f"Scenario {number} has an unknown status")
+        for field in (
+            "source",
+            "expected",
+            "actual",
+            "reason",
+            "video",
+            "video_reason",
+            "screenshot",
+        ):
+            if scenario.get(field) is not None and not isinstance(scenario[field], str):
+                raise ValueError(f"Scenario {number} field {field} must be a string")
+        if not isinstance(scenario.get("steps", []), list) or not isinstance(
+            scenario.get("reproduction", []), list
+        ):
+            raise ValueError(f"Scenario {number} steps and reproduction must be lists")
+        if any(
+            not isinstance(item, str) or not item.strip()
+            for item in scenario.get("reproduction", [])
+        ):
+            raise ValueError(f"Scenario {number} reproduction steps must be non-empty strings")
+        started = scenario.get("video_started_at")
+        if started is not None and not valid_time(started):
+            raise ValueError(f"Scenario {number} has an invalid recording start time")
+        criteria = scenario.get("criteria")
+        if criteria is not None:
+            if not isinstance(criteria, list):
+                raise ValueError(f"Scenario {number} criteria must be a list")
+            for item in criteria:
+                if (
+                    not isinstance(item, dict)
+                    or not isinstance(item.get("expected"), str)
+                    or not item["expected"].strip()
+                ):
+                    raise ValueError(
+                        f"Scenario {number} has a criterion without an expected result"
+                    )
+                if not isinstance(item.get("status"), str) or item["status"] not in STATUSES:
+                    raise ValueError(f"Scenario {number} has a criterion with an unknown status")
+                for field in ("actual", "reason", "screenshot"):
+                    if item.get(field) is not None and not isinstance(item[field], str):
+                        raise ValueError(
+                            f"Scenario {number} criterion field {field} must be a string"
+                        )
+                required = "actual" if item["status"] in ("passed", "failed") else "reason"
+                if not (item.get(required) or "").strip():
+                    raise ValueError(f"Scenario {number} criterion requires {required}")
+                validate_time(item, started, number)
+            if criteria and criteria_status(criteria) != scenario["status"]:
+                raise ValueError(f"Scenario {number} status does not match its criteria")
+            if not criteria and scenario["status"] in ("passed", "failed"):
+                raise ValueError(f"Scenario {number} has no acceptance criteria")
+        if not criteria:
+            if scenario["status"] in ("passed", "failed"):
+                if (
+                    not (scenario.get("expected") or "").strip()
+                    or not (scenario.get("actual") or "").strip()
+                ):
+                    raise ValueError(f"Scenario {number} requires expected and actual")
+            elif not (scenario.get("reason") or "").strip():
+                raise ValueError(f"Scenario {number} requires reason")
+        for step in scenario.get("steps", []):
+            if (
+                not isinstance(step, dict)
+                or not isinstance(step.get("name"), str)
+                or not step["name"].strip()
+            ):
+                raise ValueError(f"Scenario {number} has a step without a name")
+            if step.get("status") is not None and (
+                not isinstance(step["status"], str) or step["status"] not in STATUSES
+            ):
+                raise ValueError(f"Scenario {number} has a step with an unknown status")
+            if step.get("detail") is not None and not isinstance(step["detail"], str):
+                raise ValueError(f"Scenario {number} step detail must be a string")
+            validate_time(step, started, number)
+
+
+def time_button(item: dict, has_video: bool, started: int | float | None, labels: dict) -> str:
+    at = item.get("at")
+    if at is None and item.get("recorded_at") is not None:
+        at = item["recorded_at"] - started
+    if at is not None and has_video:
+        minutes, seconds = divmod(int(at), 60)
+        clock = f"{minutes}:{seconds:02d}"
+        return f'<button class="seek" type="button" data-time="{at:.3f}" aria-label="{text(labels["seek"])} {clock}">{clock}</button>'
+    return ""
+
+
+def step_markup(step: dict, has_video: bool, started: int | float | None, labels: dict) -> str:
+    time = time_button(step, has_video, started, labels)
+    status = step.get("status")
+    label = f'<span class="step-status {status}">{text(labels[status])}</span>' if status else ""
+    detail = f'<p class="step-detail">{text(step["detail"])}</p>' if step.get("detail") else ""
+    return f'<li class="step"><div class="step-title">{time}<span>{text(step["name"])}</span>{label}</div>{detail}</li>'
+
+
+def criterion_markup(
+    root: Path, item: dict, has_video: bool, started: int | float | None, labels: dict
+) -> str:
+    status = item["status"]
+    field = "actual" if status in ("passed", "failed") else "reason"
+    field_label = labels["observed"] if field == "actual" else labels["reason"]
+    evidence = asset_url(root, item.get("screenshot"))
+    evidence_link = f'<a href="{text(evidence)}">{text(labels["evidence"])}</a>' if evidence else ""
+    time = time_button(item, has_video, started, labels)
+    return (
+        f'<li class="criterion"><div class="criterion-heading"><span>{text(item["expected"])}</span>'
+        f'<span class="badge {status}">{text(labels[status])}</span></div>'
+        f'<p class="criterion-detail"><strong>{text(field_label)}:</strong> {text(item[field])}</p>'
+        f'<div class="criterion-evidence">{time}{evidence_link}</div></li>'
+    )
+
+
+def scenario_panel(root: Path, scenario: dict, number: int, labels: dict) -> str:
+    status = scenario["status"]
+    source = ""
+    if scenario.get("source"):
+        source_url = asset_url(root, scenario["source"])
+        source_label = text(scenario["source"])
+        source = (
+            f'<p class="source"><a href="{text(source_url)}">{source_label}</a></p>'
+            if source_url
+            else f'<p class="source">{source_label}</p>'
+        )
+    expected = text(scenario.get("expected") or labels["not_specified"])
+    actual = text(scenario.get("actual") or labels["not_recorded"])
+    reason = f'<p class="reason">{text(scenario["reason"])}</p>' if scenario.get("reason") else ""
+    video, video_error = recording_url(root, scenario.get("video"))
+    if video:
+        video_block = (
+            f'<div class="video-wrap"><video controls preload="metadata" src="{text(video)}" '
+            f'aria-label="{text(labels["video_label"])}: {text(scenario["name"])}" aria-describedby="scenario-{number}-steps">'
+            f'{text(labels["video_unsupported"])}</video></div><a class="asset-link" href="{text(video)}">{text(labels["video_open"])}</a>'
+        )
+    else:
+        reasons = [labels[video_error]] if video_error else []
+        if scenario.get("video_reason"):
+            reasons.append(scenario["video_reason"])
+        explanation = f": {text('; '.join(reasons))}" if reasons else ""
+        video_block = f'<div class="missing">{text(labels["video_missing"])}{explanation}</div>'
+    steps = "".join(
+        step_markup(step, bool(video), scenario.get("video_started_at"), labels)
+        for step in scenario.get("steps", [])
+    )
+    steps_block = (
+        f'<ol class="steps">{steps}</ol>'
+        if steps
+        else f'<div class="missing">{text(labels["steps_missing"])}</div>'
+    )
+    criteria = scenario.get("criteria") or []
+    if criteria:
+        entries = "".join(
+            criterion_markup(root, item, bool(video), scenario.get("video_started_at"), labels)
+            for item in criteria
+        )
+        outcomes = f'<section class="section"><h3>{text(labels["criteria"])}</h3><ol class="criteria">{entries}</ol></section>'
+    else:
+        outcomes = (
+            f'<div class="outcomes"><div class="outcome"><div class="outcome-label">{text(labels["expected"])}</div><p>{expected}</p></div>'
+            f'<div class="outcome"><div class="outcome-label">{text(labels["actual"])}</div><p>{actual}</p></div></div>'
+        )
+    screenshot = asset_url(root, scenario.get("screenshot"))
+    if screenshot:
+        screenshot_block = (
+            f'<section class="section"><h3>{text(labels["screenshot"])}</h3><a href="{text(screenshot)}">'
+            f'<img class="evidence" src="{text(screenshot)}" alt="{text(labels["screenshot_alt"])}" loading="lazy"></a></section>'
+        )
+    elif scenario.get("screenshot"):
+        screenshot_block = f'<section class="section"><h3>{text(labels["screenshot"])}</h3><div class="missing">{text(labels["screenshot_missing"])}</div></section>'
+    else:
+        screenshot_block = ""
+    reproduction = scenario.get("reproduction", [])
+    reproduction_block = (
+        (
+            f"<details><summary>{text(labels['reproduction'])}</summary><ol>"
+            + "".join(f"<li>{text(item)}</li>" for item in reproduction)
+            + "</ol></details>"
+        )
+        if reproduction
+        else ""
+    )
+    return (
+        f'<section class="panel" id="scenario-{number}"><div class="panel-heading"><div>'
+        f'<h2>{text(scenario["name"])}</h2>{source}</div><span class="badge {status}">{text(labels[status])}</span></div>'
+        f'<section class="section"><h3>{text(labels["video"])}</h3>{video_block}</section>'
+        f"{outcomes}{reason}"
+        f'<section class="section" id="scenario-{number}-steps"><h3>{text(labels["steps"])}</h3>{steps_block}</section>{screenshot_block}{reproduction_block}</section>'
+    )
+
+
+def render(run: dict, root: Path) -> str:
+    validate(run)
+    language = run.get("language", "en")
+    defaults = LEGACY_RU_LABELS if language.split("-", 1)[0].lower() == "ru" else LABELS
+    labels = defaults | run.get("labels", {})
+    scenarios = run["scenarios"]
+    counts = Counter(scenario["status"] for scenario in scenarios)
+    summary = "".join(
+        f'<div class="stat"><div class="stat-number {status}">{counts[status]}</div>'
+        f'<div class="stat-label">{text(labels[f"{status}_count"])}</div></div>'
+        for status in STATUSES
+    )
+    metadata = "".join(
+        f"<span>{text(value)}</span>"
+        for value in (run["site"].get("url"), run.get("started_at"), run.get("duration"))
+        if value
+    )
+    context = "".join(
+        f"<p><strong>{text(labels[field])}:</strong> {text(run[field])}</p>"
+        for field in ("scope", "assumptions", "limitations")
+        if run.get(field)
+    )
+    context = f'<div class="context">{context}</div>' if context else ""
+    if scenarios:
+        default = next(
+            (i for i, scenario in enumerate(scenarios, 1) if scenario["status"] == "failed"), 1
+        )
+        links = "".join(
+            f'<a class="scenario-link" href="#scenario-{i}"{(" data-default" if i == default else "")}>'
+            f'<span class="scenario-number">{i:02d}</span><span class="scenario-name">{text(scenario["name"])}'
+            f'<span class="scenario-status {scenario["status"]}">{text(labels[scenario["status"]])}</span></span></a>'
+            for i, scenario in enumerate(scenarios, 1)
+        )
+        panels = "".join(
+            scenario_panel(root, scenario, i, labels) for i, scenario in enumerate(scenarios, 1)
+        )
+        content = (
+            f'<div class="workspace"><aside class="sidebar"><div class="sidebar-heading">{text(labels["scenarios"])}'
+            f'<span>{len(scenarios)}</span></div><nav class="scenario-nav" aria-label="{text(labels["scenarios"])}">{links}</nav></aside>'
+            f"<div>{panels}</div></div>"
+        )
+    else:
+        content = f'<div class="empty">{text(labels["empty"])}</div>'
+    return Template(TEMPLATE.read_text(encoding="utf-8")).substitute(
+        page_title=text(run["site"]["name"]),
+        site_name=text(run["site"]["name"]),
+        metadata=metadata,
+        context=context,
+        summary=summary,
+        content=content,
+        language=text(language),
+        brand_note=text(labels["brand_note"]),
+        direction=text(run.get("direction", "ltr")),
+        report_label=text(labels["report"]),
+        summary_aria=text(labels["summary"]),
+        footnote=text(labels["footnote"]),
+        seek_outside=text(labels["seek_outside"]),
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create a Test Drive report from a run")
+    parser.add_argument("run", type=Path, help="path to run.json inside the report directory")
+    args = parser.parse_args()
+    temporary = None
+    try:
+        run_file = args.run.resolve(strict=True)
+        output = run_file.parent / "report.html"
+        if output == run_file:
+            raise ValueError("Input file must not be named report.html")
+        run = json.loads(run_file.read_text(encoding="utf-8"))
+        report = render(run, run_file.parent)
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=output.parent,
+            prefix=".report-",
+            suffix=".tmp",
+            delete=False,
+        ) as file:
+            temporary = Path(file.name)
+            file.write(report)
+        temporary.replace(output)
+    except (OSError, ValueError, KeyError) as error:
+        if temporary is not None:
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                print("Could not remove the temporary report file.", file=sys.stderr)
+        print(f"Could not create report: {error}", file=sys.stderr)
+        return 2
+    print(f"Report: {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

test_drive_skill-0.1.0/src/test_drive/scenarios.py

@@ -0,0 +1,110 @@
+"""Check a site's index and Markdown scenarios without exposing their contents."""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def inspect(path: Path) -> dict:
+    result = {"path": str(path), "name": "", "errors": []}
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError) as error:
+        result["errors"].append(f"Could not read file: {error}")
+        return result
+
+    fence = None
+    has_content = False
+    skip_underline = False
+    for index, line in enumerate(lines):
+        if skip_underline:
+            skip_underline = False
+            continue
+        marker = re.match(r"^\s{0,3}(`{3,}|~{3,})(.*)$", line)
+        if marker:
+            chars, tail = marker.groups()
+            if fence is None:
+                fence = (chars[0], len(chars))
+            elif chars[0] == fence[0] and len(chars) >= fence[1] and not tail.strip():
+                fence = None
+            continue
+        atx = re.match(r"^\s{0,3}#\s+(.+?)\s*#*\s*$", line) if fence is None else None
+        setext = (
+            fence is None
+            and not atx
+            and index + 1 < len(lines)
+            and line.strip()
+            and re.match(r"^ {0,3}\S", line)
+            and not re.match(r"^ {0,3}(?:[>#+*`~]|-\s|\d+[.)]\s)", line)
+            and re.fullmatch(r" {0,3}=+[ \t]*", lines[index + 1])
+        )
+        if atx or setext:
+            if result["name"]:
+                result["errors"].append("File has multiple top-level headings")
+            else:
+                result["name"] = atx.group(1) if atx else line.strip()
+            skip_underline = bool(setext)
+        elif (
+            result["name"]
+            and fence is None
+            and line.strip()
+            and not re.match(r"^\s{0,3}#{1,6}\s", line)
+        ):
+            has_content = True
+
+    if not result["name"]:
+        result["errors"].append("Site or scenario title is missing")
+    elif not has_content:
+        result["errors"].append("File has no content outside headings and code examples")
+    return result
+
+
+def check(path: Path) -> dict:
+    if path.is_dir():
+        directory = path
+        scenarios = sorted(file for file in directory.glob("*.md") if file.name != "index.md")
+    elif path.is_file() and path.name == "index.md":
+        return check(path.parent)
+    elif path.is_file() and path.suffix == ".md":
+        directory = path.parent
+        scenarios = [path]
+    else:
+        return {
+            "validation": "structure_only",
+            "site": {
+                "path": str(path),
+                "name": "",
+                "errors": ["Folder or Markdown file not found"],
+            },
+            "scenarios": [],
+        }
+
+    site = inspect(directory / "index.md")
+    cases = [inspect(file) for file in scenarios]
+    if not cases:
+        site["errors"].append("Folder has no scenario files")
+    return {"validation": "structure_only", "site": site, "scenarios": cases}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Check file structure; the agent checks meaning and acceptance criteria"
+    )
+    parser.add_argument("path", type=Path, help="site folder or individual scenario file")
+    args = parser.parse_args()
+    result = check(args.path)
+    output = json.dumps(result, ensure_ascii=False, indent=2)
+    try:
+        output.encode(sys.stdout.encoding or "utf-8")
+    except UnicodeEncodeError:
+        output = json.dumps(result, ensure_ascii=True, indent=2)
+    print(output)
+    return (
+        2 if result["site"]["errors"] or any(case["errors"] for case in result["scenarios"]) else 0
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())