#!/usr/bin/env python3
"""Shared utilities for Settled Reach asset/connector scripts.

Provides `ensure_venv`, used by the asset connectors (audio_connector,
audio_batch, image_connector, trellis_connector) to re-exec into the project
.venv before their third-party imports. The former settledreach.db connection
helpers were removed when the ticket/decision tooling was retired (pql migration
Phase 6); planning now lives in pql (`.pql/`).
"""

import os
import sys
from pathlib import Path

# ---------------------------------------------------------------------------
# Paths
# ---------------------------------------------------------------------------

SCRIPT_DIR = Path(__file__).resolve().parent
WORKTREE_ROOT = (SCRIPT_DIR / ".." / "..").resolve()


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def ensure_venv() -> None:
    """Re-exec into the project .venv Python if not already running there.

    Call this at the top of any script that uses third-party packages,
    before those imports.

    Usage::

        from common import ensure_venv
        ensure_venv()
        import numpy as np  # third-party import follows
    """
    venv_python = WORKTREE_ROOT / ".venv" / "bin" / "python"

    # Already running inside the venv — nothing to do.
    if Path(sys.executable).resolve() == venv_python.resolve():
        return

    # .venv not set up yet — fail with a helpful message.
    if not venv_python.exists():
        print(
            "error: .venv not found — run `make setup-venv` first.",
            file=sys.stderr,
        )
        sys.exit(1)

    # Re-exec into the venv Python, preserving all arguments.
    os.execv(str(venv_python), [str(venv_python)] + sys.argv)