Developing With Streamlit

#!/usr/bin/env python3
"""Discover the Streamlit package's bundled agent-skills SKILL.md.

Usage:
    python scripts/discover.py [--project-dir PATH]

When --project-dir is given, the script resolves `.venv`, `../.venv`,
`Pipfile`, `poetry.lock`, `pdm.lock`, and `uv.lock` relative to that path (so
its checks land on the user's project rather than on the script's installed
location).

Exit codes:
    0 - success; prints the absolute path to the bundled SKILL.md on stdout.
    1 - Streamlit is not installed in the detected interpreter.
    2 - Streamlit is installed but predates bundled skills (no .agents/skills/).
    3 - no usable Python interpreter was found.
    4 - .agents/skills/ exists but the expected developing-with-streamlit/SKILL.md
        is missing from the documented sub-path (likely upstream restructured).
        The agent should read the listed available skills directly.
    5 - invalid script argument.

On non-zero exit, a human-readable "ERROR:" block is printed on stderr.
"""
from __future__ import annotations

import argparse
import os
import shutil
import subprocess
import sys
from pathlib import Path
from typing import List, Optional, Tuple


def find_venv_python(venv_root: Path) -> Optional[Path]:
    """Return the venv's Python executable, cross-platform.

    POSIX venvs put it at bin/python; Windows venvs put it at Scripts/python.exe.
    """
    for candidate in (
        venv_root / "bin" / "python",
        venv_root / "Scripts" / "python.exe",
    ):
        if candidate.is_file():
            return candidate
    return None


def find_git_root(start: Path) -> Optional[Path]:
    """Walk up from `start` looking for a `.git` directory or file.

    Returns the directory containing `.git` (the repo root), or None if no
    git repository is found above `start`. Handles the worktree case where
    `.git` is a file pointing at the real repo dir.
    """
    for ancestor in [start, *start.parents]:
        if (ancestor / ".git").exists():
            return ancestor
    return None


def detect_interpreter(project_dir: Path) -> Optional[Tuple[List[str], str]]:
    """Pick the right Python interpreter, in documented priority order.

    Returns ``(cmd, tag)`` where ``cmd`` is the command for ``subprocess.run``
    and ``tag`` identifies which detection branch fired (``virtual-env``,
    ``venv-local``, ``venv-parent``, ``venv-git-root``, ``conda``, ``pipenv``,
    ``poetry``, ``pdm``, ``uv``, or ``system``). The tag lets callers give
    targeted install advice on exit 1 instead of a buffet of unrelated
    package-manager commands.
    """
    venv = os.environ.get("VIRTUAL_ENV")
    if venv:
        py = find_venv_python(Path(venv))
        if py:
            return [str(py)], "virtual-env"

    py = find_venv_python(project_dir / ".venv")
    if py:
        return [str(py)], "venv-local"

    py = find_venv_python(project_dir.parent / ".venv")
    if py:
        return [str(py)], "venv-parent"

    # Walk up to the git repo root and look for a `.venv` there. Helpful for
    # monorepos where the project's venv lives at repo root but the agent's
    # cwd / --project-dir points deep into a subdirectory.
    git_root = find_git_root(project_dir)
    if (
        git_root is not None
        and git_root != project_dir
        and git_root != project_dir.parent
    ):
        py = find_venv_python(git_root / ".venv")
        if py:
            return [str(py)], "venv-git-root"

    conda = os.environ.get("CONDA_PREFIX")
    if conda:
        py = find_venv_python(Path(conda))
        if py:
            return [str(py)], "conda"

    if shutil.which("pipenv") and (project_dir / "Pipfile").is_file():
        return ["pipenv", "run", "python"], "pipenv"

    if shutil.which("poetry") and (project_dir / "poetry.lock").is_file():
        return ["poetry", "run", "python"], "poetry"

    if shutil.which("pdm") and (project_dir / "pdm.lock").is_file():
        return ["pdm", "run", "python"], "pdm"

    if sh