cc-visual-walkthrough 0.2.0__py3-none-any.whl

cc_visual_walkthrough/__init__.py

@@ -0,0 +1,22 @@
+"""cc-visual-walkthrough: spec-driven Playwright walkthroughs for Claude Code.
+
+Records and captures browser tours of a live web app into shareable HTML +
+Markdown reports (screenshots, per-group video, non-fatal regression
+assertions). The supported workflow is through the Claude Code plugin
+(slug: ccwalk); the `ccwalk` CLI can be driven by hand, but that path is
+unsupported -- you are on your own.
+"""
+
+from .specs import Assertion, AssertionResult, Step, StepResult, load_spec, validate_steps
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Assertion",
+    "AssertionResult",
+    "Step",
+    "StepResult",
+    "load_spec",
+    "validate_steps",
+    "__version__",
+]

cc_visual_walkthrough/actions.py

@@ -0,0 +1,241 @@
+"""Action registry: the verbs a spec's action dicts can use.
+
+Every action takes the live ``Runner`` (``rt``), the current ``Step``, and
+its own kwargs, and returns an info dict merged into the step's log
+(``screenshot`` / ``progress_screenshots`` keys are collected into the
+report). The registry is a plain dict, so app-specific actions can be
+added from a custom module -- see ``load_custom_actions``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from .specs import Step
+
+
+def _url_for(rt, path: str) -> str:
+    if path.startswith("http://") or path.startswith("https://"):
+        return path
+    if not path.startswith("/"):
+        path = "/" + path
+    return rt.base_url + path
+
+
+def act_goto(rt, step: Step, url: str, apply_auth: bool = True, **_) -> dict:
+    """Navigate. On the first goto of a fresh browser context this also
+    establishes auth per the config (form login / localStorage injection);
+    cookie and header auth are applied at context creation instead."""
+    if apply_auth:
+        rt.ensure_pre_goto_auth()
+    rt.page.goto(_url_for(rt, url), wait_until="domcontentloaded")
+    if apply_auth:
+        rt.ensure_post_goto_auth()
+    return {}
+
+
+def act_reload(rt, step: Step, **_) -> dict:
+    rt.page.reload(wait_until="domcontentloaded")
+    return {}
+
+
+def act_click(rt, step: Step, selector: str, timeout_ms: int = 10000, **_) -> dict:
+    rt.page.click(selector, timeout=timeout_ms)
+    return {}
+
+
+def act_fill(rt, step: Step, selector: str, value: str, **_) -> dict:
+    rt.page.fill(selector, value)
+    return {}
+
+
+def act_press(rt, step: Step, selector: str, key: str, **_) -> dict:
+    rt.page.press(selector, key)
+    return {}
+
+
+def act_hover(rt, step: Step, selector: str, **_) -> dict:
+    rt.page.hover(selector)
+    return {}
+
+
+def act_select_option(
+    rt, step: Step, selector: str, value: str | None = None, label: str | None = None, **_
+) -> dict:
+    if label is not None:
+        rt.page.select_option(selector, label=label)
+    else:
+        rt.page.select_option(selector, value=value)
+    return {}
+
+
+def act_upload_file(rt, step: Step, selector: str, path: str, **_) -> dict:
+    rt.page.set_input_files(selector, path)
+    return {}
+
+
+def act_wait_for(
+    rt, step: Step, selector: str, state: str = "visible", timeout_ms: int = 15000, **_
+) -> dict:
+    rt.page.wait_for_selector(selector, state=state, timeout=timeout_ms)
+    return {}
+
+
+def act_wait_ms(rt, step: Step, ms: int, **_) -> dict:
+    rt.page.wait_for_timeout(ms)
+    return {}
+
+
+def act_set_viewport(rt, step: Step, width: int, height: int, **_) -> dict:
+    rt.page.set_viewport_size({"width": width, "height": height})
+    return {}
+
+
+def act_screenshot(rt, step: Step, suffix: str = "", **_) -> dict:
+    path = rt.screenshot(step, suffix=suffix)
+    return {"screenshot": path}
+
+
+def act_scroll_into_view(rt, step: Step, selector: str, **_) -> dict:
+    rt.page.locator(selector).first.scroll_into_view_if_needed()
+    return {}
+
+
+def act_login_form(rt, step: Step, **_) -> dict:
+    """Perform the configured form login explicitly (useful as a group's
+    opening step when the login flow itself should appear in the tour)."""
+    rt.perform_form_login()
+    return {"logged_in": True}
+
+
+def act_override_session(rt, step: Step, logical_name: str = "default", **_) -> dict:
+    sid = rt.override_session_id(logical_name)
+    return {"session_id": sid}
+
+
+def act_wait_for_condition(
+    rt,
+    step: Step,
+    js: str,
+    timeout_ms: int = 90000,
+    capture_progress: bool = False,
+    poll_interval_ms: int = 2500,
+    progress_selector: str = "",
+    settle_ms: int = 400,
+    **_,
+) -> dict:
+    """Poll ``js`` (a no-arg JS function body evaluated via
+    ``() => (expr)``; return truthy when the wait should END) until it
+    holds or ``timeout_ms`` elapses. While waiting, if
+    ``progress_selector`` is visible and ``capture_progress`` is set, a
+    progress screenshot is taken every ``poll_interval_ms`` -- this is how
+    long async operations (spinners, progress labels, streaming
+    responses) get their wait-state captured in the report.
+
+    The internal poll granularity is finer (300ms) than
+    ``poll_interval_ms`` (which only paces progress screenshots), so a
+    near-instant completion is still detected promptly -- a lesson
+    inherited from the predecessor system, where gating on a
+    spinner-visible->hidden transition spun for the full timeout on
+    fast replies (see DESIGN.md).
+    """
+    shots: list[str] = []
+    deadline = time.monotonic() + (timeout_ms / 1000.0)
+    saw_progress = False
+    met = False
+    last_shot_at = 0.0
+    check_interval_ms = min(300, poll_interval_ms) if poll_interval_ms else 300
+    expr = f"() => ({js})"
+    while time.monotonic() < deadline:
+        if progress_selector and rt.page.is_visible(progress_selector):
+            saw_progress = True
+            now = time.monotonic()
+            if capture_progress and (now - last_shot_at) * 1000 >= poll_interval_ms:
+                shots.append(rt.screenshot(step, suffix=f"wait_{len(shots)}"))
+                last_shot_at = now
+        if rt.page.evaluate(expr):
+            met = True
+            break
+        rt.page.wait_for_timeout(check_interval_ms)
+    if not met and rt.page.evaluate(expr):
+        met = True  # condition became true exactly at the deadline
+    if not met:
+        # A timed-out evidence wait must be VISIBLE: the runner turns this
+        # into a failed pseudo-assertion (step status warn), never a
+        # silent PASS.
+        return {
+            "progress_screenshots": shots,
+            "saw_progress": saw_progress,
+            "timed_out": True,
+            "timeout_detail": f"wait_for_condition {js!r} not met within {timeout_ms}ms",
+        }
+    if settle_ms:
+        rt.page.wait_for_timeout(settle_ms)
+    return {"progress_screenshots": shots, "saw_progress": saw_progress}
+
+
+def act_mock_route(rt, step: Step, url_pattern: str, json_body: Any, status: int = 200, **_) -> dict:
+    """Intercept a network request with a canned JSON response (e.g. to
+    stop a wizard auto-skipping itself on an already-configured backend).
+    Registered on the page, so it survives a subsequent goto/reload."""
+    body = json.dumps(json_body)
+
+    def handler(route):
+        route.fulfill(status=status, content_type="application/json", body=body)
+
+    rt.page.route(url_pattern, handler)
+    return {}
+
+
+ACTIONS: dict[str, Callable[..., dict]] = {
+    "goto": act_goto,
+    "reload": act_reload,
+    "click": act_click,
+    "fill": act_fill,
+    "press": act_press,
+    "hover": act_hover,
+    "select_option": act_select_option,
+    "upload_file": act_upload_file,
+    "wait_for": act_wait_for,
+    "wait_ms": act_wait_ms,
+    "set_viewport": act_set_viewport,
+    "screenshot": act_screenshot,
+    "scroll_into_view": act_scroll_into_view,
+    "login_form": act_login_form,
+    "override_session": act_override_session,
+    "wait_for_condition": act_wait_for_condition,
+    "mock_route": act_mock_route,
+}
+
+
+def run_action(rt, step: Step, action_dict: dict[str, Any]) -> dict:
+    kwargs = {k: v for k, v in action_dict.items() if k != "action"}
+    name = action_dict["action"]
+    fn = ACTIONS.get(name)
+    if fn is None:
+        raise ValueError(f"Unknown action {name!r} (known: {sorted(ACTIONS)})")
+    return fn(rt, step, **kwargs)
+
+
+def load_custom_actions(module_path: str | Path) -> list[str]:
+    """Import a custom-actions module by file path and let it register
+    into ACTIONS. The module must expose ``register(actions: dict)``.
+    Returns the action names it added."""
+    path = Path(module_path)
+    if not path.exists():
+        raise ValueError(f"custom_actions module not found: {module_path}")
+    spec = importlib.util.spec_from_file_location(f"ccwalk_custom_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"Cannot import custom_actions module: {module_path}")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    register = getattr(mod, "register", None)
+    if not callable(register):
+        raise ValueError(f"{module_path} must define register(actions: dict)")
+    before = set(ACTIONS)
+    register(ACTIONS)
+    return sorted(set(ACTIONS) - before)

cc_visual_walkthrough/browser.py

@@ -0,0 +1,38 @@
+"""Browser launch with a system-chromium fallback.
+
+Some boxes cannot run `playwright install-deps` (no root), but already
+have a shared-libs-satisfied system chromium. Try the Playwright-managed
+browser first, then each known system path."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_FALLBACK_CHROMIUM_PATHS = [
+    "/usr/bin/chromium-browser",
+    "/usr/bin/chromium",
+    "/snap/bin/chromium",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+]
+
+
+def launch_browser(playwright, headless: bool = True):
+    last_error: Exception | None = None
+    try:
+        return playwright.chromium.launch(headless=headless)
+    except Exception as e:  # noqa: BLE001 -- any launch failure triggers fallback
+        last_error = e
+    for candidate in _FALLBACK_CHROMIUM_PATHS:
+        if not Path(candidate).exists():
+            continue
+        try:
+            return playwright.chromium.launch(headless=headless, executable_path=candidate)
+        except Exception as e:  # noqa: BLE001
+            last_error = e
+    raise RuntimeError(
+        "Could not launch any chromium (playwright-managed or system fallback). "
+        f"Last error: {last_error}. Run `ccwalk install-browsers` to install "
+        "Playwright's chromium (if that fails on missing shared libraries, "
+        "install libnspr4/libnss3 system packages)."
+    )

cc_visual_walkthrough/cli.py

@@ -0,0 +1,388 @@
+"""ccwalk CLI: init / run / doctor / report.
+
+The supported workflow is through the Claude Code plugin (/ccwalk:setup
+writes the config and spec, /ccwalk:run runs and triages). Driving this
+CLI by hand works but is unsupported.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from .actions import load_custom_actions
+from .config import CONFIG_FILENAME, Config, load_config
+from .helpers import AppProcess, app_ready, git_head, parse_viewports
+from .reporters import results_from_run_meta, transcode_videos_mp4, write_report
+from .runner import run_capture_only, run_walkthrough
+from .specs import load_spec
+
+_CONFIG_TEMPLATE = """\
+# ccwalk.yaml -- cc-visual-walkthrough configuration.
+# Generated by `ccwalk init`; the /ccwalk:setup Claude Code skill fills
+# this in properly for your app. Full schema: see the config module docs.
+version: 1
+app:
+  name: "My App"
+  base_url: "http://localhost:8000"
+  # start_command: "npm run dev"
+  ready_check: { path: "/", timeout_s: 60 }
+auth:
+  method: none        # none | form | localstorage | cookie | header
+capture:
+  video: true
+  default_viewport: { width: 1440, height: 900 }
+report:
+  out_dir: "reports/walkthrough"
+  keep_runs: 10
+specs_dir: "walkthrough/specs"
+default_spec: "example_tour"
+"""
+
+_EXAMPLE_SPEC = '''\
+"""Example walkthrough spec -- replace with your app's tour.
+
+Rules the validator enforces:
+- steps of a group must be consecutive in STEPS
+- a group's first step must begin with a goto (fresh contexts start blank)
+"""
+
+from cc_visual_walkthrough import Assertion, Step
+
+STEPS = [
+    Step(
+        name="homepage",
+        description="Load the homepage and check the main heading renders",
+        group="smoke",
+        actions=[
+            {"action": "goto", "url": "/"},
+            {"action": "wait_for", "selector": "h1"},
+        ],
+        assertions=[Assertion(selector="h1", description="main heading visible")],
+    ),
+]
+'''
+
+
+def _resolve_spec(cfg: Config, spec_arg: str | None) -> str:
+    """Resolution order: an explicit path (slash or .py) passes through;
+    otherwise try {specs_dir}/{name}.py on disk FIRST -- so a spec named
+    'tour.v2' finds tour.v2.py instead of misrouting into a dotted-module
+    import -- and only fall back to treating a dotted name as a module."""
+    spec = spec_arg or cfg.default_spec
+    if "/" in spec or "\\" in spec or spec.endswith(".py"):
+        return spec
+    candidate = Path(cfg.specs_dir) / f"{spec}.py"
+    if candidate.exists() or "." not in spec:
+        return str(candidate)
+    return spec  # dotted module path
+
+
+def _prune_runs(out_root: Path, keep: int) -> None:
+    if keep <= 0 or not out_root.is_dir():
+        return
+    runs = sorted([p for p in out_root.iterdir() if p.is_dir()], key=lambda p: p.name)
+    for old in runs[:-keep]:
+        shutil.rmtree(old, ignore_errors=True)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    cfg_path = root / CONFIG_FILENAME
+    if cfg_path.exists() and not args.force:
+        print(f"{CONFIG_FILENAME} already exists (use --force to overwrite)")
+        return 1
+    cfg_path.write_text(_CONFIG_TEMPLATE)
+    specs_dir = root / "walkthrough" / "specs"
+    specs_dir.mkdir(parents=True, exist_ok=True)
+    example = specs_dir / "example_tour.py"
+    if not example.exists() or args.force:
+        example.write_text(_EXAMPLE_SPEC)
+    state_dir = root / ".ccwalk"
+    state_dir.mkdir(exist_ok=True)
+    (state_dir / ".gitignore").write_text("*\n")
+    print(f"Wrote {CONFIG_FILENAME}, {example.relative_to(root)}, and .ccwalk/")
+    print("Next: run /ccwalk:setup in Claude Code to tailor the tour to this app.")
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    cfg = load_config(args.config)
+    if args.base_url:
+        cfg.app.base_url = args.base_url.rstrip("/")
+    if cfg.custom_actions:
+        added = load_custom_actions(cfg.custom_actions)
+        if added:
+            print(f"Custom actions loaded: {', '.join(added)}")
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    out_root = Path(cfg.report.out_dir)
+    out_dir = Path(args.out_dir) if args.out_dir else out_root / timestamp
+
+    app_proc = None
+    if args.start_app:
+        if not cfg.app.start_command:
+            print("--start-app given but app.start_command is not configured", file=sys.stderr)
+            return 2
+        app_proc = AppProcess(
+            cfg.app.start_command,
+            cfg.app.base_url,
+            cfg.app.ready_check.path,
+            cfg.app.ready_check.timeout_s,
+        )
+        app_proc.__enter__()
+
+    try:
+        health = app_ready(cfg.app.base_url, cfg.app.ready_check.path)
+        if not health.get("reachable") and not args.force:
+            print(
+                f"App not reachable at {cfg.app.base_url}{cfg.app.ready_check.path} "
+                f"({health.get('error')}). Start it first, use --start-app, or --force "
+                "to run anyway.",
+                file=sys.stderr,
+            )
+            return 2
+        # Preflight passed -- only now claim a run directory, so a dead app
+        # doesn't litter reports/ with empty timestamp dirs.
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        run_meta = {
+            "timestamp": timestamp,
+            "git_head": git_head(),
+            "base_url": cfg.app.base_url,
+            "app_health": health,
+            "app_name": cfg.app.name,
+            "tool_version": __version__,
+        }
+
+        if args.capture_only:
+            run_meta["spec"] = f"--capture-only {args.capture_only}"
+            viewports = parse_viewports(args.viewports)
+            results = run_capture_only(
+                args.capture_only, viewports, cfg, out_dir, headed=args.headed
+            )
+        else:
+            spec_ref = _resolve_spec(cfg, args.spec)
+            run_meta["spec"] = spec_ref
+            from .actions import ACTIONS
+
+            steps = load_spec(spec_ref, known_actions=set(ACTIONS))
+            results = run_walkthrough(
+                steps, cfg, out_dir,
+                headed=args.headed,
+                record_video=cfg.capture.video and not args.no_video,
+            )
+    finally:
+        if app_proc:
+            app_proc.__exit__(None, None, None)
+
+    if args.mp4:
+        for w in transcode_videos_mp4(out_dir, results):
+            print(f"warning: {w}", file=sys.stderr)
+
+    embed = args.embed or cfg.report.embed
+    if embed:
+        total_media = sum(
+            (out_dir / p).stat().st_size
+            for r in results
+            for p in [*r.screenshots, *( [r.video_path] if r.video_path else [] )]
+            if (out_dir / p).exists()
+        )
+        if total_media > 20 * 1024 * 1024:
+            print(
+                f"warning: --embed with {total_media / 1e6:.0f}MB of media makes a very "
+                "large HTML file; files over 25MB stay linked",
+                file=sys.stderr,
+            )
+    report_path = write_report(run_meta, results, out_dir, embed=embed)
+    if not args.out_dir:
+        _prune_runs(out_root, cfg.report.keep_runs)
+
+    n_pass = sum(1 for r in results if r.status == "pass")
+    n_warn = sum(1 for r in results if r.status == "warn")
+    n_fail = sum(1 for r in results if r.status == "fail")
+    n_blocked = sum(1 for r in results if r.status == "blocked")
+    print(f"\nReport: {Path(report_path).resolve()}")
+    summary = f"Steps: {len(results)}  PASS={n_pass}  WARN={n_warn}  FAIL={n_fail}"
+    if n_blocked:
+        summary += f"  BLOCKED={n_blocked}"
+    print(summary)
+    for r in results:
+        line = f"  [{r.status.upper():7s}] {r.step.name} ({r.duration_ms:.0f}ms)"
+        if r.error:
+            line += f" -- {r.error}"
+        print(line)
+    return 0 if n_fail == 0 else 1
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    from .doctor import run_doctor
+
+    cfg = load_config(args.config)
+    if args.base_url:
+        cfg.app.base_url = args.base_url.rstrip("/")
+    return run_doctor(
+        cfg, args.url, args.find, headed=args.headed, no_auth=args.no_auth
+    )
+
+
+def cmd_install_browsers(args: argparse.Namespace) -> int:
+    """Install Playwright's chromium via THIS interpreter -- works the
+    same for pip, uv tool, and pipx installs, where a bare `playwright`
+    command may not be on PATH."""
+    import subprocess
+
+    extra = args.args or ["chromium"]
+    proc = subprocess.run([sys.executable, "-m", "playwright", "install", *extra])
+    if proc.returncode == 0:
+        # playwright is silent when browsers are already present; say so
+        print(f"ccwalk: {' '.join(extra)} ready (installed or already present)")
+    else:
+        print("ccwalk: browser install FAILED - see output above", file=sys.stderr)
+    return proc.returncode
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    from . import serve as serve_mod
+
+    cfg = load_config(args.config)
+    root = cfg.source_path.parent if cfg.source_path else Path.cwd()
+    out_root = Path(cfg.report.out_dir)
+    if not out_root.is_absolute():
+        out_root = root / out_root
+    if args.action == "stop":
+        return serve_mod.stop(root)
+    if args.action == "status":
+        return serve_mod.status(root, out_root)
+    return serve_mod.start(
+        root, out_root, cfg.app.name,
+        port=args.port, bind=args.bind, daemon=args.daemon,
+        config_path=str(cfg.source_path) if cfg.source_path else None,
+    )
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    import json
+
+    run_dir = Path(args.run_dir)
+    meta_path = run_dir / "run_meta.json"
+    if not meta_path.exists():
+        print(f"No run_meta.json in {run_dir}", file=sys.stderr)
+        return 2
+    run_meta = json.loads(meta_path.read_text())
+    results = results_from_run_meta(run_meta)
+    if args.mp4:
+        for w in transcode_videos_mp4(run_dir, results):
+            print(f"warning: {w}", file=sys.stderr)
+    path = write_report(
+        run_meta, results, run_dir, embed=args.embed,
+        in_place=getattr(args, "in_place", False),
+    )
+    print(f"Re-rendered: {path}" + (" (embedded media)" if args.embed else ""))
+    return 0
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ccwalk",
+        description="cc-visual-walkthrough: records and captures spec-driven browser tours "
+        "into shareable HTML reports. Supported via the Claude Code plugin (/ccwalk:setup).",
+    )
+    p.add_argument("--version", action="version", version=f"ccwalk {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="Scaffold ccwalk.yaml + an example spec")
+    p_init.add_argument("--force", action="store_true")
+    p_init.set_defaults(func=cmd_init)
+
+    p_run = sub.add_parser("run", help="Run a walkthrough (or --capture-only) and write the report")
+    p_run.add_argument("--spec", default=None, help="Spec name in specs_dir, module path, or .py file")
+    p_run.add_argument("--config", default=None, help=f"Path to {CONFIG_FILENAME}")
+    p_run.add_argument("--base-url", default=None)
+    p_run.add_argument("--out-dir", default=None)
+    p_run.add_argument("--headed", action="store_true", help="Show the browser window")
+    p_run.add_argument("--no-video", action="store_true", help="Skip video recording")
+    p_run.add_argument("--embed", action="store_true", help="Base64-embed media into one HTML file")
+    p_run.add_argument("--mp4", action="store_true", help="Transcode videos to H.264 (needs ffmpeg)")
+    p_run.add_argument("--start-app", action="store_true", help="Launch app.start_command for the run")
+    p_run.add_argument("--force", action="store_true", help="Run even if the ready check fails")
+    p_run.add_argument("--capture-only", default=None, metavar="URL_OR_PATH",
+                       help="Design mode: screenshot one page across --viewports")
+    p_run.add_argument("--viewports", default="390,768,1440")
+    p_run.set_defaults(func=cmd_run)
+
+    p_doc = sub.add_parser("doctor", help="Print stable-selector candidates for a page")
+    p_doc.add_argument("url", help="Path or URL to inspect")
+    p_doc.add_argument("--find", default=None, help="Text to locate on the page")
+    p_doc.add_argument("--config", default=None)
+    p_doc.add_argument("--base-url", default=None)
+    p_doc.add_argument("--headed", action="store_true")
+    p_doc.add_argument(
+        "--no-auth", dest="no_auth", action="store_true",
+        help="inspect without applying configured auth (the configured "
+        "login page is always exempt automatically)",
+    )
+    p_doc.set_defaults(func=cmd_doctor)
+
+    p_rep = sub.add_parser("report", help="Re-render report.html/.md from a run's run_meta.json")
+    p_rep.add_argument("run_dir")
+    p_rep.add_argument(
+        "--embed", action="store_true",
+        help="also write a self-contained report_embedded.html next to report.html",
+    )
+    p_rep.add_argument(
+        "--in-place", dest="in_place", action="store_true",
+        help="with --embed: overwrite report.html instead of writing a sibling",
+    )
+    p_rep.add_argument("--mp4", action="store_true")
+    p_rep.set_defaults(func=cmd_report)
+
+    p_srv = sub.add_parser(
+        "serve",
+        help="Serve the report directory with a runs index at / "
+        "(localhost, Cache-Control: no-store)",
+        description="Serve reports over HTTP with a generated runs index at /. "
+        "Binds 127.0.0.1 by default; exposing wider (--bind 0.0.0.0) is an "
+        "explicit choice - reports contain your app's screenshots. Safari "
+        "cannot play the .webm videos from this server (no Range support); "
+        "use --mp4 runs plus a range-capable server for Safari viewers.",
+    )
+    p_srv.add_argument(
+        "action", nargs="?", default="start", choices=["start", "stop", "status"],
+        help="start (default; restarts any running server), stop, or status",
+    )
+    p_srv.add_argument("--port", type=int, default=8378,
+                       help="port to bind (default 8378; 0 = pick a free one)")
+    p_srv.add_argument("--bind", default="127.0.0.1")
+    p_srv.add_argument("--daemon", action="store_true",
+                       help="run in the background (manage with serve stop/status)")
+    p_srv.add_argument("--config", default=None)
+    p_srv.set_defaults(func=cmd_serve)
+
+    p_ib = sub.add_parser(
+        "install-browsers",
+        help="Install Playwright's chromium for this interpreter (pip/uv tool/pipx safe)",
+    )
+    p_ib.add_argument("args", nargs="*", help="Extra args for `playwright install` (default: chromium)")
+    p_ib.set_defaults(func=cmd_install_browsers)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_arg_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (ValueError, RuntimeError) as e:
+        # Config errors, spec errors, and browser-launch failures arrive
+        # here as clean one-liners (with their own remediation hints)
+        # instead of raw tracebacks.
+        print(f"ccwalk: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())