dev.py

#!/usr/bin/env python3
"""
Development helper script for the my-practice Django project.
"""

import glob
import inspect
import os
import re
import shutil
import subprocess
import sys
import time

CONTAINER_NAME = "my-practice-django"
COMPOSE = ["docker", "compose"]

# Python that lives outside ./app and so is invisible to the container's
# `ruff format .` (docker-compose mounts only ./app at /app). These are piped
# through the container's ruff over stdin instead — see _ruff_root_python —
# so they're held to the same pinned ruff version as the app.
#
# Their *config* has to differ in one respect, though: these files run on the
# host Python, not the container's 3.14, and the app's target-version = "py314"
# makes the formatter rewrite `except (A, B):` into 3.14's bracketless form —
# a SyntaxError on 3.13 and older, which would make ./dev.py itself unrunnable.
# The repo-root ruff.toml sets the lower target, but the container can't see it
# (only ./app is mounted), so it's passed through as an inline --config below.
ROOT_PYTHON_GLOBS = ("dev.py", "prod.py", "scripts/*.py")
ROOT_RUFF_CONFIG = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ruff.toml")


def _root_ruff_target_version():
    """Read target-version out of the repo-root ruff.toml.

    Parsed rather than duplicated so the value can't drift from the config CI
    and a native `ruff` run both use.
    """
    try:
        with open(ROOT_RUFF_CONFIG, encoding="utf-8") as fh:
            for line in fh:
                match = re.match(r'\s*target-version\s*=\s*"([^"]+)"', line)
                if match:
                    return match.group(1)
    except OSError:
        pass
    return None


def run_docker_command(args, interactive=False, **run_kwargs):
    """Run a command in the Django container.

    run_kwargs go to subprocess.run; passing `input` keeps the container's stdin
    open (-i) so it can be piped in.
    """
    flags = ["-it"] if interactive else ["-i"] if "input" in run_kwargs else []
    return subprocess.run(["docker", "exec", *flags, CONTAINER_NAME, *args], **run_kwargs)


def _root_python_files():
    """Repo-root Python files that the container can't see (see ROOT_PYTHON_GLOBS)."""
    files = []
    for pattern in ROOT_PYTHON_GLOBS:
        files.extend(sorted(glob.glob(pattern)))
    return files


def _run_ruff_stdin(ruff_args, source):
    """Run the container's ruff against source text piped over stdin.

    --stdin-filename resolves against the container's /app, so ruff discovers
    app/pyproject.toml for these files. That is right for everything except
    target-version — see ROOT_PYTHON_GLOBS — which is overridden inline.
    """
    cmd = ["python", "-m", "ruff", *ruff_args]
    target_version = _root_ruff_target_version()
    if target_version:
        cmd.extend(["--config", f"target-version='{target_version}'"])
    return run_docker_command(cmd, input=source, capture_output=True, text=True)


def _ruff_root_python(write=False, verbose=False):
    """Format-check (or rewrite) and lint the repo-root Python files.

    Returns 0 if everything is clean, 1 otherwise. In write mode the formatted
    output is written back, mirroring what `ruff format .` does inside /app.
    """
    problems = []

    for path in _root_python_files():
        with open(path, encoding="utf-8") as fh:
            source = fh.read()

        if write:
            result = _run_ruff_stdin(["format", "-", "--stdin-filename", path], source)
            if result.returncode != 0:
                problems.append(f"{path}: {result.stderr.strip()}")
            elif result.stdout != source:
                with open(path, "w", encoding="utf-8") as fh:
                    fh.write(result.stdout)
                print(f"   reformatted {path}")
        else:
            result = _run_ruff_stdin(["format", "--check", "-", "--stdin-filename", path], source)
            if result.returncode != 0:
                problems.append(f"{path}: needs formatting")

        lint = _run_ruff_stdin(["check", "--stdin-filename", path, "-"], source)
        if lint.returncode != 0:
            problems.append(f"{path}: {lint.stdout.strip() or lint.stderr.strip()}")

    if problems:
        for problem in problems:
            print(f"   {problem}" if verbose else f"   {problem.splitlines()[0]}")
        return 1
    return 0


# This and _confirm_metered_download are duplicated verbatim in prod.py. prod.py
# ships to self-hosters as a single stdlib-only file, so it cannot import a
# shared module, and the copies must stay identical —
# scripts/check_shared_helpers.py fails if they drift.
def _is_metered_connection():
    """Best-effort NetworkManager check for a metered connection (e.g. mobile hotspot).

    Returns True/False when nmcli gives a definite answer, None when it can't be
    determined (no NetworkManager, no default route, non-Linux host, ...).
    Callers should treat None as "unknown" and not block on it.
    """
    if not shutil.which("nmcli"):
        return None
    try:
        route = subprocess.run(
            ["ip", "route", "show", "default"],
            capture_output=True,
            text=True,
            timeout=3,
        )
        parts = route.stdout.split()
        device = parts[parts.index("dev") + 1] if "dev" in parts else None
        if not device:
            return None
        out = subprocess.run(
            ["nmcli", "-t", "-f", "GENERAL.METERED", "device", "show", device],
            capture_output=True,
            text=True,
            timeout=3,
        )
        value = out.stdout.strip().split(":", 1)[-1]
        return value.startswith("yes")
    except Exception:
        return None


def _confirm_metered_download(action):
    """Ask before a data-heavy operation if the active connection looks metered.

    Returns True if it's fine to proceed (not metered, unknown, or user confirmed).
    """
    if _is_metered_connection() is not True:
        return True
    print(
        f"⚠️  Active network connection is metered (e.g. mobile hotspot). {action} can pull a lot of data."
    )
    if not sys.stdin.isatty():
        print("   Not an interactive terminal — pass --yes to proceed anyway.")
        return False
    return input("   Continue anyway? [y/N] ").strip().lower() == "y"


def cmd_restart(args):
    """Restart the Django container (or do full restart with --force)"""
    # Check if --force flag is present
    if "--force" in args:
        extra_args = [a for a in args if a not in ("--force", "--build")]
        rebuild = "--build" in args
        print("Forcing full restart (compose down/up) to reload environment variables...")
        if rebuild:
            print("Rebuilding image first...")
            cmd_build(extra_args)
        cmd_stop([])
        return cmd_start(extra_args)
    else:
        print(f"Restarting {CONTAINER_NAME}...")
        cmd = ["docker", "restart", CONTAINER_NAME]
        return subprocess.run(cmd)


DROP_TEST_DB_CLONES = """
import os, re
import django
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
django.setup()
from django.db import connection
base = connection.creation._get_test_db_name()
with connection.cursor() as cursor:
    cursor.execute("SELECT datname FROM pg_database WHERE datname LIKE %s", [base + "_%"])
    for (name,) in cursor.fetchall():
        if re.fullmatch(re.escape(base) + r"_\\d+", name):
            cursor.execute("DROP DATABASE " + connection.ops.quote_name(name))
"""


def drop_parallel_test_db_clones():
    """Drop the per-worker test databases left behind by a previous parallel run.

    With --keepdb, Django migrates the main test database but reuses any
    existing worker clone (test_<name>_1, _2, ...) untouched, so after a new
    migration every worker runs against the old schema and fails with
    "relation ... does not exist". Re-cloning from the migrated template is
    a cheap CREATE DATABASE ... TEMPLATE per worker.
    """
    run_docker_command(["python", "-c", DROP_TEST_DB_CLONES])


def run_django_tests(test_args):
    """Run `manage.py test`, re-running serially if a parallel run fails.

    Django's parallel runner pickles results back to the parent, and an errored
    test whose traceback can't be pickled kills the whole run with "cannot
    pickle 'traceback' object" at the first error — so any later failures stay
    hidden. The serial re-run costs nothing on a green build and produces a
    complete report when it matters. Mirrors the fallback in ci.yml.
    """
    parallel = any(a.startswith("--parallel") for a in test_args)
    if parallel and "--keepdb" in test_args:
        drop_parallel_test_db_clones()

    result = run_docker_command(test_args)
    if result.returncode == 0 or not parallel:
        return result

    # Django accepts `--parallel`, `--parallel N` and `--parallel=N`.
    serial_args = []
    args_iter = iter(test_args)
    for arg in args_iter:
        if arg.startswith("--parallel="):
            continue
        if arg == "--parallel":
            following = next(args_iter, None)
            if following is not None and not following.isdigit():
                serial_args.append(following)
            continue
        serial_args.append(arg)

    print("\n⚠️  Parallel run failed — re-running serially for a complete report...")
    return run_docker_command(serial_args)


def cmd_test(args):
    """Run Django tests and JavaScript tests

    Speed optimizations:
    - --smart: Only run tests affected by recent file changes (pytest + testmon).
              First run builds a mapping; subsequent runs are very fast.
    - --parallel N: Run tests in N parallel workers (default: auto-detect CPUs)
    - --failfast: Stop on first failure
    - --fast: Shortcut for --parallel --failfast
    - --no-keepdb: Recreate test database (use when schema changed)
    """
    results = []

    # Check for --js-only flag
    if "--js-only" in args:
        args = [a for a in args if a != "--js-only"]
        return cmd_test_js(args)

    # The .mo files are gitignored build output, and ./app is bind-mounted over
    # the image's freshly compiled copy, so after a pull that adds msgids the
    # tests would otherwise run against a stale catalog and fail on German
    # assertions. Up-to-date catalogs are skipped, so this costs well under a second.
    run_docker_command(["python", "manage.py", "compilemessages", "-v", "0"])

    # Check for --smart flag: pytest + testmon (only run tests affected by changes)
    if "--smart" in args:
        args = [a for a in args if a != "--smart"]
        print("🎯 Smart mode: only running tests affected by recent changes...")
        print("   (First run builds the mapping — all tests execute once.)")
        pytest_args = ["python", "-m", "pytest", "--testmon", "-q"]
        if args:  # allow passing extra filters, e.g. a test path
            pytest_args.extend(args)
        return run_docker_command(pytest_args)

    # Check for --django-only flag
    django_only = "--django-only" in args
    if django_only:
        args = [a for a in args if a != "--django-only"]

    # Check for --no-keepdb flag (recreate test database)
    use_keepdb = "--no-keepdb" not in args
    if not use_keepdb:
        args = [a for a in args if a != "--no-keepdb"]

    # Check for --fast shortcut (parallel + failfast)
    fast_flags = []
    if "--fast" in args:
        args = [a for a in args if a != "--fast"]
        # Store flags to add later (after positional arguments)
        if not any(a.startswith("--parallel") for a in args):
            fast_flags.append("--parallel")
        if "--failfast" not in args:
            fast_flags.append("--failfast")

    # Note: Using --keepdb to reuse test database between runs
    # This avoids the need for cleanup and speeds up tests

    # Determine if specific Django tests were specified
    has_specific_tests = (
        args and "--all" not in args and any(not arg.startswith("--") for arg in args)
    )

    # Run Django tests
    print("🐍 Running Django tests...")
    test_args = ["python", "manage.py", "test"]
    if use_keepdb:
        test_args.append("--keepdb")
    if args and "--all" not in args:
        test_args.extend(args)
    else:
        test_args.extend(["-v", "2"])
    # Add --fast flags after positional arguments
    test_args.extend(fast_flags)

    django_result = run_django_tests(test_args)
    results.append(("Django", django_result.returncode))

    # Only run JavaScript tests if no specific Django tests were requested and not django-only
    if not has_specific_tests and not django_only:
        print("\n📊 Running JavaScript tests...")
        js_result = cmd_test_js([])
        results.append(("JavaScript", js_result.returncode))

    # Print summary
    print("\n" + "=" * 50)
    print("Test Summary:")
    print("=" * 50)
    for test_type, code in results:
        status = "✓ PASSED" if code == 0 else "✗ FAILED"
        print(f"{test_type:12} {status}")
    print("=" * 50)

    # Return non-zero if any test failed
    failed = any(code != 0 for _, code in results if code is not None)
    return subprocess.CompletedProcess(args=[], returncode=1 if failed else 0)


def cmd_test_js(args):
    """Run the Node.js JavaScript test suites (the same set CI runs)."""
    print("📊 Running Node.js-based JS Tests...")

    # Discovered, not listed. This used to be a hand-maintained list, and so
    # did the copy in .github/workflows/ci.yml — which broke the build the
    # first time a suite was deleted (global-search.test.js, P-047). Both
    # sides glob now, so adding or removing a suite needs no edit here.
    js_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "app", "static", "js")
    suites = sorted(
        os.path.basename(p)
        for pattern in ("*.test.js", "*.test.extended.js")
        for p in glob.glob(os.path.join(js_dir, pattern))
    )

    results = []
    for suite in suites:
        stem = suite.replace(".test.extended.js", " (extended)").replace(".test.js", "")
        print(f"\n--- {suite} ---")
        result = run_docker_command(["node", f"/app/static/js/{suite}"])
        results.append((f"JS {stem}", result.returncode))

    print("\n" + "=" * 50)
    print("Node.js Test Summary:")
    print("=" * 50)
    for test_type, code in results:
        status = "✓ PASSED" if code == 0 else "✗ FAILED"
        print(f"{test_type:12} {status}")
    print("=" * 50)

    failed = any(code != 0 for _, code in results)
    return subprocess.CompletedProcess(args=[], returncode=1 if failed else 0)


def cmd_manage(args):
    """Run Django management commands"""
    if not args:
        print("Usage: dev.py manage <command>")
        return subprocess.CompletedProcess(args=[], returncode=1)

    # If --odt-file points to a host path that isn't already inside the container,
    # copy it into the container's /tmp/ first and rewrite the argument.
    args = list(args)
    container_tmp_path = None
    for i, arg in enumerate(args):
        if arg == "--odt-file" and i + 1 < len(args):
            host_path = os.path.expanduser(args[i + 1])
            if not host_path.startswith("/app"):
                filename = os.path.basename(host_path)
                container_tmp_path = f"/tmp/{filename}"
                cp_cmd = ["docker", "cp", host_path, f"{CONTAINER_NAME}:{container_tmp_path}"]
                print(f"Copying {host_path} → container:{container_tmp_path}")
                result = subprocess.run(cp_cmd)
                if result.returncode != 0:
                    return result
                args[i + 1] = container_tmp_path
            break

    interactive = args[0] in ("createsuperuser", "shell") if args else False
    result = run_docker_command(["python", "manage.py"] + args, interactive=interactive)

    # Clean up the temporary file from the container.
    if container_tmp_path:
        run_docker_command(
            ["rm", "-f", container_tmp_path], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
        )

    return result


def cmd_python(args):
    """Run Python in the container"""
    if args:
        return run_docker_command(["python"] + args)
    else:
        return run_docker_command(["python"], interactive=True)


def cmd_shell(args):
    """Open Django shell or execute command with -c"""
    # Check for -c flag (execute command)
    if args and args[0] == "-c":
        if len(args) < 2:
            print("Error: -c requires a command to execute")
            print(
                'Example: ./dev.py shell -c "from my_practice.models import Client; print(Client.objects.count())"'
            )
            return subprocess.CompletedProcess(args=[], returncode=1)

        command = " ".join(args[1:])
        return run_docker_command(["python", "manage.py", "shell"], input=command.encode())
    else:
        # Interactive shell
        return run_docker_command(["python", "manage.py", "shell"], interactive=True)


def cmd_bash(args):
    """Open bash shell in container"""
    return run_docker_command(["bash"], interactive=True)


def cmd_build(args):
    """Rebuild Docker image(s) via compose build.

    Options:
        --no-cache   Force full rebuild (ignore layer cache)
        --yes        Skip the metered-connection confirmation prompt
        <service>    Build only a specific service (default: all)
    """
    skip_confirm = "--yes" in args
    args = [a for a in args if a != "--yes"]
    if not skip_confirm and not _confirm_metered_download("Rebuilding the image"):
        print("Aborted.")
        return subprocess.CompletedProcess(args=[], returncode=1)
    print("Building Docker image(s)...")
    return subprocess.run([*COMPOSE, "build", *args])


def cmd_start(args):
    """Start all containers with compose."""
    print("Starting containers with compose...")
    result = subprocess.run([*COMPOSE, "up", "-d", *args])
    if result.returncode != 0:
        return result
    # Wait for Django to finish migrating and start serving requests.
    print("Waiting for Django to be ready...", end="", flush=True)
    wait_cmd = ["docker", "inspect", "--format", "{{.State.Health.Status}}", CONTAINER_NAME]
    for _ in range(60):
        out = subprocess.run(wait_cmd, capture_output=True, text=True)
        status = out.stdout.strip()
        if status == "healthy":
            print(" ready.")
            break
        if status == "unhealthy":
            print(" unhealthy — check logs with: ./dev.py logs -f")
            break
        print(".", end="", flush=True)
        time.sleep(2)
    else:
        print(" timed out — check logs with: ./dev.py logs -f")
    return result


def cmd_stop(args):
    """Stop all containers with compose."""
    print("Stopping containers with compose...")
    return subprocess.run([*COMPOSE, "down", *args])


def cmd_logs(args):
    """Show container logs: all services, or the container named first."""
    all_services = not args or args[0].startswith("-")
    prefix = [*COMPOSE, "logs"] if all_services else ["docker", "logs"]
    tail = [] if "-f" in args or "--follow" in args else ["--tail", "100"]
    return subprocess.run([*prefix, *tail, *args])


def cmd_ps(args):
    """Show container status"""
    return subprocess.run([*COMPOSE, "ps", *args])


def cmd_migrate(args):
    """Run migrations"""
    return run_docker_command(["python", "manage.py", "migrate"] + args)


def cmd_makemigrations(args):
    """Create new migrations"""
    return run_docker_command(["python", "manage.py", "makemigrations"] + args)


def _container_running():
    """Whether the Django container is up (`docker exec` would fail otherwise)."""
    cmd = ["docker", "inspect", "--format", "{{.State.Running}}", CONTAINER_NAME]
    out = subprocess.run(cmd, capture_output=True, text=True)
    return out.returncode == 0 and out.stdout.strip() == "true"


def cmd_i18n(args):
    """Extract and compile translation strings.

    Usage:
      ./dev.py i18n                # extract + compile (default)
      ./dev.py i18n makemessages   # extract only
      ./dev.py i18n compilemessages  # compile only

    --if-running skips quietly when the container is down, for the post-merge
    and post-checkout hooks: a `git pull` shouldn't fail because Docker isn't up,
    and the container compiles the catalogs itself on start.
    """
    if "--if-running" in args:
        args = [a for a in args if a != "--if-running"]
        if not _container_running():
            print("ℹ️  Django container not running — catalogs compile on next start.")
            return subprocess.CompletedProcess(args=[], returncode=0)
    sub = args[0] if args else None
    if sub not in (None, "makemessages", "compilemessages"):
        print(f"Error: unknown i18n step '{sub}' (expected makemessages or compilemessages)")
        return subprocess.CompletedProcess(args=[], returncode=1)
    if sub in (None, "makemessages"):
        result = run_docker_command(
            ["python", "manage.py", "makemessages", "-l", "de", "-l", "en", "--no-wrap"]
        )
        if result.returncode != 0:
            return result
    if sub in (None, "compilemessages"):
        result = run_docker_command(["python", "manage.py", "compilemessages"])
    return result


def cmd_quality(args):
    """Run code quality checks (ruff format, ruff lint, Tailwind CSS build, tests)

    Options:
        --no-tests: Skip test execution
        --only-format: Run only ruff format + ruff lint
        --only-tests: Run only tests
        --verbose: Show full output (default: minimal)

    Note: vulture and mypy are skipped by default due to many false positives.
          Run them manually if needed:
            docker exec my-practice-django python -m vulture my_practice
            docker exec my-practice-django python -m mypy my_practice
    """
    results = []
    verbose = "--verbose" in args
    run_tests = "--no-tests" not in args
    only_format = "--only-format" in args
    only_tests = "--only-tests" in args

    # Determine which checks to run
    run_format = not only_tests
    run_tests = run_tests and not only_format

    print("🔍 Code Quality Checks")
    print("=" * 50)
    if not verbose:
        print("💡 Use --verbose for full output")
    print()

    # Ruff format check
    if run_format:
        print("1️⃣  Ruff format (code formatter)")
        print("-" * 30)
        cmd = ["python", "-m", "ruff", "format", ".", "--check"]
        if not verbose:
            cmd.append("--quiet")
        fmt_result = run_docker_command(cmd)
        # ./app is all the container can see; check the repo-root scripts too.
        root_result = _ruff_root_python(verbose=verbose)
        if fmt_result.returncode == 0 and root_result == 0:
            print("✅ Ruff format OK")
            results.append(("Ruff format", 0))
        else:
            print("❌ Code needs formatting")
            if not verbose:
                print("   Run: ./dev.py format")
            results.append(("Ruff format", 1))
        print()

    # Ruff linter
    if run_format:
        print("2️⃣  Ruff lint")
        print("-" * 30)
        cmd = ["python", "-m", "ruff", "check", "."]
        if not verbose:
            cmd.extend(["--quiet"])
        ruff_result = run_docker_command(cmd)
        results.append(("Ruff lint", ruff_result.returncode))
        if ruff_result.returncode == 0:
            print("✅ Ruff lint passed")
        else:
            print("❌ Ruff found issues")
            if not verbose:
                print("   Run with --verbose to see details")
        print()

        # Runs on the host Python, not in the container: that mounts just ./app,
        # and this reads dev.py and prod.py from the repo root.
        print("2️⃣ ½ Duplicated helpers (dev.py ↔ prod.py)")
        print("-" * 30)
        dup_result = subprocess.run([sys.executable, "scripts/check_shared_helpers.py"])
        results.append(("Duplicated helpers", dup_result.returncode))
        if dup_result.returncode == 0:
            print("✅ Duplicated helpers in sync")
        else:
            print("❌ Duplicated helpers have drifted")
        print()

        # Same reasoning as above, for the other pair of files that duplicate
        # content on purpose: requirements.txt and requirements-dev.txt.
        print("2️⃣ ¾ Requirements pins (requirements.txt ↔ requirements-dev.txt)")
        print("-" * 30)
        req_result = subprocess.run([sys.executable, "scripts/check_requirements_sync.py"])
        results.append(("Requirements sync", req_result.returncode))
        if req_result.returncode == 0:
            print("✅ Runtime pins in sync")
        else:
            print("❌ Runtime pins have drifted")
        print()

    # Tailwind CSS build
    if run_format:
        print("3️⃣  Tailwind CSS build")
        print("-" * 30)
        css_result = run_docker_command(["npm", "run", "build:css"])
        results.append(("Tailwind CSS", css_result.returncode))
        if css_result.returncode == 0:
            print("✅ Tailwind CSS built")
        else:
            print("❌ Tailwind CSS build failed")
        print()

    # Django tests (optional)
    if run_tests:
        print("4️⃣  Django Tests")
        print("-" * 30)

        # Note: Using --keepdb to reuse test database between runs
        cmd = ["python", "manage.py", "test", "my_practice", "--keepdb", "--parallel"]
        if not verbose:
            cmd.append("--verbosity=1")
        test_result = run_django_tests(cmd)
        results.append(("Tests", test_result.returncode))
        print()
    else:
        print("4️⃣  Django Tests")
        print("-" * 30)
        print("⏭️  Skipped (--no-tests flag)")
        print()

    # Summary
    print()
    print("=" * 50)
    print("Quality Check Summary:")
    print("=" * 50)
    for name, code in results:
        status = "✅ PASSED" if code == 0 else "❌ FAILED"
        print(f"{name:<20} {status}")
    print("=" * 50)

    if not results:
        print("⚠️  No checks were run")
        print("   Use --only-format or --only-tests")
        return subprocess.CompletedProcess(args=[], returncode=0)

    # Return overall status
    overall_status = 0 if all(code == 0 for _, code in results) else 1
    if overall_status == 0:
        print("✅ All checks passed")
    else:
        print("❌ Some checks failed")
        if not verbose:
            print("\n💡 Tip: Run with --verbose to see detailed output")
    return subprocess.CompletedProcess(args=[], returncode=overall_status)


def _print_outdated_dev_packages():
    """Print outdated host packages that appear in requirements-dev.txt."""
    import json

    dev_req = os.path.join(os.path.dirname(__file__), "app", "requirements-dev.txt")
    try:
        with open(dev_req) as f:
            # Extract bare package names, normalise to lowercase with hyphens
            dev_names = set()
            for line in f:
                line = line.strip()
                if not line or line.startswith("#"):
                    continue
                name = re.split(r"[>=<!;\[]", line)[0].strip().lower().replace("_", "-")
                if name:
                    dev_names.add(name)
    except FileNotFoundError:
        print("  (requirements-dev.txt not found)")
        return

    cmd = ["pip3", "list", "--outdated", "--format", "json"]
    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0 or not result.stdout.strip():
        print("  (could not run pip3 on host)")
        return

    try:
        packages = json.loads(result.stdout)
    except json.JSONDecodeError:
        print("  (failed to parse pip3 output)")
        return

    relevant = [p for p in packages if p["name"].lower().replace("_", "-") in dev_names]
    if relevant:
        print(f"  {'Package':<30} {'Version':<16} {'Latest':<16} Type")
        print(f"  {'-' * 30} {'-' * 16} {'-' * 16} ----")
        for p in relevant:
            print(
                f"  {p['name']:<30} {p['version']:<16} {p['latest_version']:<16} {p['latest_filetype']}"
            )
    else:
        print("  All dev packages up to date")


def cmd_review(args):
    """Periodic codebase health review (monthly/quarterly).

    Runs automated checks and prints the manual checklist.

    Options:
        --full      Quarterly mode: also runs complexity analysis (radon) and
                    lists files over the long-file threshold
        --verbose   Show full tool output instead of summaries
        --no-tests  Skip the test-coverage step (faster, no DB required)
        -h, --help  Show this help message
    """
    if "-h" in args or "--help" in args:
        print(inspect.getdoc(cmd_review))
        return subprocess.CompletedProcess(args=[], returncode=0)

    full = "--full" in args
    verbose = "--verbose" in args
    no_tests = "--no-tests" in args
    results = []

    mode = "Quarterly" if full else "Monthly"
    print(f"🔬 Codebase Health Review — {mode}")
    print("=" * 55)
    if not verbose:
        print("💡 Use --verbose for full tool output")
    print()

    # --- 1. Dead code (vulture) ---
    print("1️⃣  Dead code (vulture)")
    print("-" * 30)
    vulture_result = run_docker_command(
        ["python", "-m", "vulture", "my_practice", "--min-confidence", "80"]
    )
    results.append(("Dead code (vulture)", vulture_result.returncode))
    if vulture_result.returncode == 0:
        print("✅ No dead code found")
    else:
        print("⚠️  Potential dead code above")
    print()

    # --- 2. Unused imports / variables (ruff F401/F841) ---
    print("2️⃣  Unused imports & variables (ruff)")
    print("-" * 30)
    ruff_cmd = ["python", "-m", "ruff", "check", ".", "--select", "F401,F841"]
    if not verbose:
        ruff_cmd.append("--quiet")
    ruff_result = run_docker_command(ruff_cmd)
    results.append(("Unused symbols (ruff)", ruff_result.returncode))
    if ruff_result.returncode == 0:
        print("✅ No unused imports or variables")
    else:
        print("⚠️  Unused symbols found above")
    print()

    # --- 3. Security: known CVEs (pip-audit + npm audit) ---
    print("3️⃣  Dependency security (pip-audit + npm audit)")
    print("-" * 30)
    # Check if pip-audit is available before running
    check = run_docker_command(["python", "-c", "import pip_audit"])
    if check.returncode != 0:
        print("⏭️  pip-audit not installed — skipping Python CVE check")
        print("   Install: pip install pip-audit")
        results.append(("CVE audit (pip-audit)", None))
    else:
        audit_result = run_docker_command(
            ["python", "-m", "pip_audit", "--progress-spinner", "off"]
        )
        results.append(("CVE audit (pip-audit)", audit_result.returncode))
        if audit_result.returncode == 0:
            print("✅ No known Python CVEs")
        else:
            print("⚠️  Python vulnerabilities found above")

    npm_audit = run_docker_command(["npm", "audit", "--prefix", "/app"])
    results.append(("CVE audit (npm audit)", npm_audit.returncode))
    if npm_audit.returncode == 0:
        print("✅ No known JS CVEs")
    else:
        print("⚠️  JS vulnerabilities found above")
    print()

    # --- 4. Outdated packages ---
    print("4️⃣  Outdated packages (pip list --outdated)")
    print("-" * 30)
    print("App (container / requirements.txt):")
    run_docker_command(["pip", "list", "--outdated", "--format", "columns"])
    print("Dev tools (host / requirements-dev.txt):")
    _print_outdated_dev_packages()
    results.append(("Outdated packages", 0))  # informational only
    print()

    # --- 5. Test coverage ---
    print("5️⃣  Test coverage (coverage report)")
    print("-" * 30)
    if no_tests:
        print("⏭️  Skipped (--no-tests)")
        results.append(("Coverage", None))
    else:
        # source/omit/skip flags and the fail_under floor all live in
        # app/pyproject.toml, so a `coverage report` run by hand reports the
        # same thing this does.
        run_docker_command(
            [
                "python",
                "-m",
                "coverage",
                "run",
                "manage.py",
                "test",
                "my_practice",
                "--keepdb",
                "--verbosity=0",
            ]
        )
        cov_cmd = ["python", "-m", "coverage", "report"]
        if not verbose:
            cov_cmd.extend(["--sort=miss"])
        cov_result = run_docker_command(cov_cmd)
        results.append(("Coverage", cov_result.returncode))
        if cov_result.returncode != 0:
            print("❌ Coverage is below the floor in app/pyproject.toml")
    print()

    # --- 6. Complexity (quarterly only) ---
    if full:
        print("6️⃣  Complexity hotspots (radon cc)")
        print("-" * 30)
        check = run_docker_command(["python", "-c", "import radon"])
        if check.returncode != 0:
            print("⏭️  radon not installed in container — skipping complexity check")
            print("   Rebuild the container to install it: ./dev.py build")
            results.append(("Complexity (radon)", None))
        else:
            radon_result = run_docker_command(
                [
                    "python",
                    "-m",
                    "radon",
                    "cc",
                    "my_practice",
                    "--min",
                    "C",  # C = complex, D/E/F = very complex
                    "--show-complexity",
                    "--average",
                ]
            )
            results.append(("Complexity (radon)", radon_result.returncode))
        print()

        # --- 7. Long files (quarterly only) ---
        # Same threshold and pathspecs as the generated metrics page, so the two
        # never disagree; that page has the month-by-month trend, this is the list.
        print("7️⃣  Long files (scripts/codebase_metrics.py --largest)")
        print("-" * 30)
        long_result = subprocess.run(
            [sys.executable, "scripts/codebase_metrics.py", "--largest"],
            cwd=os.path.dirname(os.path.abspath(__file__)),
        )
        results.append(("Long files", long_result.returncode))
        print()

    # --- Summary ---
    print("=" * 55)
    print("Automated Check Summary:")
    print("=" * 55)
    for name, code in results:
        status = "⏭️  Skipped" if code is None else ("✅ OK" if code == 0 else "⚠️  Review")
        print(f"  {name:<30} {status}")
    print()

    # --- Manual checklist ---
    print("=" * 55)
    print(f"Manual Checklist — {mode}:")
    print("=" * 55)
    monthly_items = [
        "git log: repeated fixes in same area? (design smell)",
        "German comments/identifiers in touched files? (P-038)",
        "GH issues: close stale items inactive >2 months",
        "New views bypassing mixins/builders? Consolidate",
    ]
    quarterly_items = [
        "Similar blocks across views/utils? Extract a helper",
        "Django/Python/WeasyPrint/psycopg major versions?",
        "New builder/helper patterns followed by recent code?",
        "PROJECTS.md: stale WIPs → done/cancelled?",
        "docs/architecture/CODE_STRUCTURE.md still accurate?",
        "New language features that simplify existing code?",
    ]
    for item in monthly_items:
        print(f"  [ ] {item}")
    if full:
        print()
        print("  Quarterly extras:")
        for item in quarterly_items:
            print(f"  [ ] {item}")
    print()
    print(
        "See docs/guides/CODEBASE_STANDARDS.md for the full scan checklist and canonical patterns."
    )

    return subprocess.CompletedProcess(args=[], returncode=0)


def cmd_format(args):
    """Format code with ruff format (Black-compatible formatter only).

    Note: does NOT run ruff check --fix. Auto-fixing lint rules can silently
    introduce syntax regressions (e.g. UP034 stripping parens from
    `except (A, B):` → Python 2 syntax). Use `./dev.py lint` to review
    lint issues and fix them manually.
    """
    print("🎨 Formatting code with ruff...")
    result = run_docker_command(["python", "-m", "ruff", "format", "."])
    # ./app is all the container can see; format the repo-root scripts too.
    _ruff_root_python(write=True)
    return result


def cmd_lint(args):
    """Run ruff format check + ruff lint only (fast, no tests).

    Use this during development for quick feedback.
    Use ./dev.py quality to run the full suite before a release.
    """
    return cmd_quality(["--only-format"] + args)


def cmd_calendar_auth(_args):
    """Open the Google Calendar authorization URL in the default browser.

    Use this when the calendar token has expired (invalid_grant error).
    The browser handles the full OAuth2/PKCE flow and saves the new token.
    The app must be running (./dev.py start) before calling this.
    """
    url = "http://localhost:8000/calendar/authorize/"
    print(f"Opening {url} in your browser...")
    print("Complete the Google sign-in to refresh the calendar token.")
    result = subprocess.run(["xdg-open", url])
    if result.returncode != 0:
        print(f"xdg-open failed. Open this URL manually in your browser:\n  {url}")
    return result


def cmd_smoke(args):
    """Smoke-test a released GHCR image in a contained fashion (issue #202).

    Pulls ghcr.io/dholbach/my-practice:<version>, boots it against a throwaway
    postgres under an isolated compose project (my-practice-smoke), waits for
    migrations + gunicorn via the healthcheck, verifies the image reports the
    expected version and serves the login page, then tears everything down.

    Runs safely alongside the dev stack: no shared container names, volumes,
    ports, or bind mounts.

    Usage:
        ./dev.py smoke [vX.Y.Z] [--keep] [--no-pull]
        ./dev.py smoke --down

    Options:
        vX.Y.Z      Image tag to test (default: version.py of this checkout)
        --keep      Leave the stack running for manual inspection
        --no-pull   Skip the explicit pull (use a locally cached image)
        --down      Tear down a stack left running by a previous --keep run
        --yes       Skip the metered-connection confirmation prompt
    """
    import base64
    import secrets as pysecrets
    import tempfile

    keep = "--keep" in args
    no_pull = "--no-pull" in args
    down_only = "--down" in args
    skip_confirm = "--yes" in args
    positional = [a for a in args if not a.startswith("-")]

    if (
        not no_pull
        and not down_only
        and not skip_confirm
        and not _confirm_metered_download("Pulling the smoke-test image")
    ):
        print("Aborted.")
        return subprocess.CompletedProcess(args=[], returncode=1)

    repo_dir = os.path.dirname(os.path.abspath(__file__))
    if positional:
        version = positional[0]
    else:
        version_py = os.path.join(repo_dir, "app", "my_practice", "version.py")
        with open(version_py) as fh:
            version = re.search(r'VERSION\s*=\s*"([^"]+)"', fh.read()).group(1)

    project = "my-practice-smoke"
    compose_file = os.path.join(repo_dir, "docker-compose.smoke.yml")

    def compose(*extra, capture=False):
        cmd = [*COMPOSE, "-p", project, "-f", compose_file, "--env-file", env_file, *extra]
        return subprocess.run(cmd, capture_output=capture, text=capture)

    def fail(result, message):
        print(f"\n❌ {message}")
        print("── last 50 log lines ──")
        compose("logs", "--tail", "50")
        if not keep:
            compose("down", "-v", "--remove-orphans")
        result.returncode = result.returncode or 1
        return result

    # Throwaway secrets, passed via a private --env-file (never written to .env)
    tmp_dir = tempfile.mkdtemp(prefix="my-practice-smoke-")
    env_file = os.path.join(tmp_dir, "smoke.env")
    with open(env_file, "w") as fh:
        fh.write(f"SMOKE_VERSION={version}\n")
        fh.write(f"POSTGRES_PASSWORD={pysecrets.token_urlsafe(32)}\n")
        fh.write(f"DJANGO_SECRET_KEY={pysecrets.token_urlsafe(50)}\n")
        fh.write(f"FERNET_KEY={base64.urlsafe_b64encode(os.urandom(32)).decode()}\n")

    if down_only:
        print("Tearing down the smoke stack...")
        try:
            result = compose("down", "-v", "--remove-orphans")
        finally:
            os.remove(env_file)
            os.rmdir(tmp_dir)
        return result

    print(f"🔥 Smoke-testing ghcr.io/dholbach/my-practice:{version}")
    try:
        if not no_pull:
            print("── pulling image ──")
            result = compose("pull", "django")
            if result.returncode != 0:
                return fail(result, f"Could not pull image for {version}.")

        print("── booting stack (migrate + collectstatic + gunicorn) ──")
        result = compose("up", "-d", "--wait", "--quiet-pull")
        if result.returncode != 0:
            return fail(result, "Stack did not become healthy.")

        print("── verifying ──")
        result = compose(
            "exec",
            "-T",
            "django",
            "python",
            "-c",
            "from my_practice.version import VERSION; print(VERSION)",
            capture=True,
        )
        reported = result.stdout.strip()
        if result.returncode != 0 or reported != version:
            return fail(result, f"Image reports version {reported!r}, expected {version!r}.")
        print(f"  ✓ image reports {reported}")

        result = compose(
            "exec",
            "-T",
            "django",
            "curl",
            "-sf",
            "http://localhost:8000/accounts/login/",
            capture=True,
        )
        if result.returncode != 0 or "csrfmiddlewaretoken" not in result.stdout:
            return fail(result, "Login page did not render.")
        print("  ✓ login page renders (migrations ran, gunicorn serving)")

        port = compose("port", "django", "8000", capture=True).stdout.strip()
        print(f"\n✅ {version} passed the smoke test.")
        if keep:
            print(f"   Stack left running at http://{port}")
            print("   Tear down with: ./dev.py smoke --down")
        return subprocess.CompletedProcess(args=[], returncode=0)
    finally:
        if not keep:
            compose("down", "-v", "--remove-orphans", capture=True)
        try:
            os.remove(env_file)
            os.rmdir(tmp_dir)
        except OSError:
            pass


def cmd_install_hooks(_args):
    """Install the pre-commit hooks from .pre-commit-config.yaml.

    Run once after cloning. The hooks run ruff, gitleaks, the PII guard and the
    file-sync checks before each commit (host tools, no Docker needed).
    """
    repo_root = os.path.dirname(os.path.abspath(__file__))

    if shutil.which("pre-commit") is None:
        print("❌ pre-commit is not installed on the host.")
        print("   Install it, then re-run this command:")
        print("     pip install pre-commit    # or: pipx install pre-commit")
        print("   (it is pinned in app/requirements-dev.txt)")
        return subprocess.CompletedProcess(args=[], returncode=1)

    # An earlier version of this command pointed git at a committed .githooks/
    # directory. core.hooksPath overrides .git/hooks/ wholesale, so leaving it
    # set makes `pre-commit install` refuse — and, worse, silently bypasses
    # every hook below on a clone where it was set before the migration.
    existing = subprocess.run(
        ["git", "config", "--get", "core.hooksPath"],
        cwd=repo_root,
        capture_output=True,
        text=True,
    )
    if existing.returncode == 0 and existing.stdout.strip():
        print(f"ℹ️  Clearing core.hooksPath (was: {existing.stdout.strip()})")
        subprocess.run(["git", "config", "--unset", "core.hooksPath"], cwd=repo_root)

    result = subprocess.run(["pre-commit", "install"], cwd=repo_root)
    if result.returncode == 0:
        print("✅ Hooks installed — .pre-commit-config.yaml runs on every commit.")
        print("   Run them over the whole tree: pre-commit run --all-files")
        print("   To skip the hooks for one commit: git commit --no-verify")
    return result


def cmd_run(args):
    """Run a Python script in the container with Django environment loaded"""
    if not args:
        print("Error: Please specify a Python script to run")
        print("Example: ./dev.py run check_df.py")
        return subprocess.CompletedProcess(args=[], returncode=1)

    script_path = args[0]

    # Check if script exists
    if not os.path.exists(script_path):
        print(f"Error: Script not found: {script_path}")
        return subprocess.CompletedProcess(args=[], returncode=1)

    # Read script content
    with open(script_path, "r") as f:
        script_content = f.read()

    return run_docker_command(["python", "manage.py", "shell"], input=script_content.encode())


def cmd_exec(args):
    """Execute arbitrary command in container"""
    if not args:
        print("Error: Please specify a command to execute")
        print("Example: ./dev.py exec ls -la")
        return subprocess.CompletedProcess(args=[], returncode=1)

    return run_docker_command(args)


def cmd_sql(args):
    """Execute SQL query in PostgreSQL database"""
    if not args:
        print("Error: Please specify SQL query or file")
        print("Examples:")
        print('  ./dev.py sql "SELECT * FROM my_practice_client LIMIT 5"')
        print("  ./dev.py sql query.sql")
        return subprocess.CompletedProcess(args=[], returncode=1)

    query = args[0]

    # Check if it's a file
    if os.path.exists(query):
        with open(query, "r") as f:
            query = f.read()

    return run_docker_command(["psql", "-U", "my_practice", "-d", "my_practice", "-c", query])


def cmd_psql(args):
    """Open interactive PostgreSQL shell"""
    print("Opening PostgreSQL shell...")
    return run_docker_command(["psql", "-U", "my_practice", "-d", "my_practice"], interactive=True)


def cmd_backup(args):
    """Back up database + media via scripts/backup.sh (the implementation is prod.py's)."""
    script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "scripts", "backup.sh")
    return subprocess.run(["bash", script, *args])


COMMANDS = {
    "backup": cmd_backup,
    "build": cmd_build,
    "start": cmd_start,
    "stop": cmd_stop,
    "restart": cmd_restart,
    "test": cmd_test,
    "test-js": cmd_test_js,
    "manage": cmd_manage,
    "python": cmd_python,
    "shell": cmd_shell,
    "bash": cmd_bash,
    "logs": cmd_logs,
    "ps": cmd_ps,
    "migrate": cmd_migrate,
    "makemigrations": cmd_makemigrations,
    "i18n": cmd_i18n,
    "quality": cmd_quality,
    "lint": cmd_lint,
    "review": cmd_review,
    "format": cmd_format,
    "calendar-auth": cmd_calendar_auth,
    "smoke": cmd_smoke,
    "install-hooks": cmd_install_hooks,
    "run": cmd_run,
    "exec": cmd_exec,
    "sql": cmd_sql,
    "psql": cmd_psql,
}


def print_help():
    """Print usage information"""
    print("Usage: dev.py <command> [args...]")
    print("\nAvailable commands:")
    print("  start                - Start all containers (compose up -d)")
    print("  stop                 - Stop all containers (compose down)")
    print("  build [--no-cache]   - Rebuild Docker image(s)")
    print("  restart [--force]    - Restart the Django container (--force: full down/up)")
    print("  test [args]          - Run tests (default: Django + JS)")
    print("  test --js-only       - Run only JavaScript tests (Node.js)")
    print("  test --django-only   - Run only Django tests")
    print("  test-js              - Run JavaScript tests (Node.js-based)")
    print("  manage <cmd> [args]  - Run Django management commands")
    print("  python [args]        - Run Python in the container")
    print('  shell [-c "cmd"]     - Open Django shell or execute command with -c')
    print("  bash                 - Open bash shell in container")
    print("  run <script>         - Run a Python script with Django environment")
    print("  exec <cmd> [args]    - Execute arbitrary command in container")
    print("  sql <query|file>     - Execute SQL query or file")
    print("  psql                 - Open interactive PostgreSQL shell")
    print("  backup               - Back up database + media (verified, 30-day rotation)")
    print("  logs [args]          - Show container logs (default: all services, last 100 lines)")
    print("  ps                   - Show container status")
    print("  migrate [args]       - Run migrations")
    print("  makemigrations [args]- Create new migrations")
    print("  i18n [sub]           - Extract/compile translations (makemessages + compilemessages)")
    print("  lint                 - Fast lint check: ruff format + ruff check (no tests, ~seconds)")
    print("  lint --verbose       - Lint with full output")
    print("  quality              - Full pre-release check: lint + full test suite (~minutes)")
    print("  quality --no-tests   - Run quality checks without tests")
    print("  quality --only-tests - Run only tests")
    print("  quality --verbose    - Show full output from all tools")
    print("  review               - Monthly codebase health check (dead code, CVEs, coverage)")
    print("  review --full        - Quarterly review (adds complexity analysis)")
    print("  review --verbose     - Show full tool output during review")
    print("  format               - Auto-format code with ruff format")
    print(
        "  calendar-auth        - Open Google Calendar auth URL in browser (re-authorize expired token)"
    )
    print(
        "  smoke [vX.Y.Z]       - Boot a released GHCR image with a throwaway DB and verify it serves"
    )
    print("  smoke --keep         - Leave the smoke stack running for manual inspection")
    print("  smoke --down         - Tear down a smoke stack left running by --keep")
    print("  install-hooks        - Install the pre-commit hooks (run once after clone)")
    print("\nExamples:")
    print("  ./dev.py start                                # Start all containers")
    print("  ./dev.py start --build                        # Rebuild and start")
    print("  ./dev.py build                                # Rebuild image (cached)")
    print("  ./dev.py build --no-cache                     # Full rebuild (no cache)")
    print("  ./dev.py restart --force                      # Full restart (reloads .env)")
    print("  ./dev.py restart --force --build              # Rebuild + full restart")
    print("  ./dev.py stop                                 # Stop all containers")
    print("  ./dev.py stop -v                              # Stop and remove volumes")
    print("  ./dev.py ps                                   # Show container status")
    print("  ./dev.py logs -f                              # Follow all logs")
    print("  ./dev.py logs --tail 50 django                # Last 50 lines of Django")
    print("  ./dev.py test                                 # Run all tests")
    print("  ./dev.py test --django-only                   # Run only Django tests")
    print("  ./dev.py test --js-only                       # Run only JavaScript tests")
    print("  ./dev.py test-js                              # Run Node.js JS tests")
    print("  ./dev.py test my_practice.tests.test_imports # Run specific tests")
    print("  ./dev.py manage createsuperuser               # Create superuser")
    print("  ./dev.py shell                                # Open Django shell")
    print("  ./dev.py shell -c \"print('Hello')\"            # Execute command in Django shell")
    print("  ./dev.py run check_df.py                      # Run Python script with Django")
    print("  ./dev.py exec ls -la /app                     # Execute command in container")
    print('  ./dev.py sql "SELECT COUNT(*) FROM ..."       # Execute SQL query')
    print("  ./dev.py psql                                 # Open PostgreSQL shell")


def main():
    if len(sys.argv) < 2 or sys.argv[1] in ["-h", "--help", "help"]:
        print_help()
        return 0

    command = sys.argv[1]
    args = sys.argv[2:]

    if command not in COMMANDS:
        print(f"Unknown command: {command}")
        print("")
        print_help()
        return 1

    result = COMMANDS[command](args)
    return result.returncode


if __name__ == "__main__":
    sys.exit(main())