"""Overlay path generation and on-disk directory bootstrap.

All new overlays (any type) get `path = str(overlay_id)`. The directory is
created with `exist_ok=False` so a stray folder from a prior failed delete
surfaces loudly instead of silently shadowing fresh content. Combined with
SQLite AUTOINCREMENT on `overlays.id`, that catches DB/disk drift.
"""
from __future__ import annotations

import os

from l4d2host.paths import get_left4me_root, validate_overlay_ref

from l4d2web.models import Overlay


def generate_overlay_path(overlay_id: int) -> str:
    """Return the canonical relative path for an overlay row.

    Validates the result through l4d2host's overlay-ref guard. Pure numeric IDs
    always pass — this is just a belt-and-suspenders check that surfaces
    immediately if someone changes the scheme.
    """
    candidate = str(overlay_id)
    return validate_overlay_ref(candidate)


def create_overlay_directory(overlay: Overlay) -> None:
    """Create `LEFT4ME_ROOT/overlays/{overlay.path}/` with `exist_ok=False`.

    Raises `FileExistsError` if the directory already exists, surfacing the
    rare DB/disk-drift state where a stray directory matches a fresh ID.
    """
    target = get_left4me_root() / "overlays" / overlay.path
    os.makedirs(target, exist_ok=False)