justfile

# Copyright (c) typedef int GmbH, Germany, 2025. All rights reserved.

# -----------------------------------------------------------------------------
# -- just global configuration
# -----------------------------------------------------------------------------

set unstable := true
set positional-arguments := true
set script-interpreter := ['uv', 'run', '--script']

# uv env vars (see: https://docs.astral.sh/uv/reference/environment/)

# Project base directory
PROJECT_DIR := justfile_directory()

# Tell uv to use project-local cache directory
export UV_CACHE_DIR := './.uv-cache'

# Use this common single directory for all uv venvs
VENV_DIR := './.venvs'

# Define supported Python environments
ENVS := 'cpy314 cpy313 cpy312 cpy311 pypy311'

# Package version files, kept in sync (CalVer YY.M.PATCH[.devN], PEP 440).
PY_VERSION_FILE := 'src/zlmdb/_version.py'
TOML_VERSION_FILE := 'pyproject.toml'

# Default recipe: show project header and list all recipes
default:
    #!/usr/bin/env bash
    set -e
    VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*= *"\(.*\)"/\1/')
    GIT_REV=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
    echo ""
    echo "==============================================================================="
    echo "                                   zLMDB                                       "
    echo ""
    echo "          Object-relational in-memory database layer based on LMDB            "
    echo ""
    echo "   Python Package:         zlmdb                                              "
    echo "   Python Package Version: ${VERSION}                                         "
    echo "   Git Version:            ${GIT_REV}                                         "
    echo "   Protocol Specification: https://wamp-proto.org/                            "
    echo "   Documentation:          https://zlmdb.readthedocs.io                       "
    echo "   Package Releases:       https://pypi.org/project/zlmdb/                    "
    echo "   Nightly/Dev Releases:   https://github.com/crossbario/zlmdb/releases       "
    echo "   Source Code:            https://github.com/crossbario/zlmdb                "
    echo "   Copyright:              typedef int GmbH (Germany/EU)                      "
    echo "   License:                MIT License                                        "
    echo ""
    echo "       >>>   Created by The WAMP/Autobahn/Crossbar.io OSS Project   <<<       "
    echo "==============================================================================="
    echo ""
    just --list
    echo ""

# Internal helper to map Python version short name to full uv version
_get-spec short_name:
    #!/usr/bin/env bash
    set -e
    case {{short_name}} in
        cpy314)  echo "cpython-3.14";;
        cpy314t) echo "cpython-3.14t";; # CPython 3.14 free-threaded (no-GIL); reserved for #124 Part 2
        cpy313)  echo "cpython-3.13";;
        cpy312)  echo "cpython-3.12";;
        cpy311)  echo "cpython-3.11";;
        pypy311) echo "pypy-3.11";;
        *)       echo "Unknown environment: {{short_name}}" >&2; exit 1;;
    esac

# Assert the venv interpreter's ABI (GIL vs free-threaded) matches the env name, so a wheel
# is never published with the wrong ABI tag -- e.g. a free-threaded cp314t wheel in the GIL
# cp314 slot, which shipped on aarch64 in 26.6.1 when an older uv resolved `cpython-3.14` to
# the free-threaded interpreter (zlmdb #124 / autobahn #1875). The wheel ABI tag is fixed by
# the building interpreter, so checking the interpreter catches the mismatch at build time.
_check-venv-abi venv:
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    case "${VENV_NAME}" in
        pypy*)  echo "==> ABI check skipped for '${VENV_NAME}' (PyPy)"; exit 0 ;;
        *t)     EXPECT_FT=1 ;;   # e.g. cpy314t -> free-threaded (no-GIL)
        *)      EXPECT_FT=0 ;;   # e.g. cpy314  -> GIL
    esac
    ACTUAL_FT=$(${VENV_PYTHON} -c "import sysconfig; print(1 if sysconfig.get_config_var('Py_GIL_DISABLED') else 0)")
    if [ "${ACTUAL_FT}" != "${EXPECT_FT}" ]; then
        echo "ERROR: interpreter ABI mismatch for '${VENV_NAME}': Py_GIL_DISABLED=${ACTUAL_FT}, expected free-threaded=${EXPECT_FT}." >&2
        echo "       Building would emit a wrong-ABI wheel (e.g. cp314t in the cp314 slot). Aborting." >&2
        exit 1
    fi
    echo "==> ABI check OK: '${VENV_NAME}' interpreter free-threaded=${ACTUAL_FT} (expected ${EXPECT_FT})"

# Internal helper that calculates and prints the system-matching venv name
_get-system-venv-name:
    #!/usr/bin/env bash
    set -e
    SYSTEM_VERSION=$(/usr/bin/python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    ENV_NAME="cpy$(echo ${SYSTEM_VERSION} | tr -d '.')"
    if ! echo "{{ ENVS }}" | grep -q -w "${ENV_NAME}"; then
        echo "Error: System Python (${SYSTEM_VERSION}) maps to '${ENV_NAME}', which is not a supported environment." >&2
        exit 1
    fi
    echo "${ENV_NAME}"

# Helper recipe to get the python executable path for a venv
_get-venv-python venv="":
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{PROJECT_DIR}}/.venvs/${VENV_NAME}"
    if [[ "$OS" == "Windows_NT" ]]; then
        echo "${VENV_PATH}/Scripts/python.exe"
    else
        echo "${VENV_PATH}/bin/python3"
    fi

# -----------------------------------------------------------------------------
# -- General/global helper recipes
# -----------------------------------------------------------------------------

# Setup bash tab completion for the current user (to activate: `source ~/.config/bash_completion`).
setup-completion:
    #!/usr/bin/env bash
    set -e
    COMPLETION_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/bash_completion"
    MARKER="# --- Just completion ---"
    echo "==> Setting up bash tab completion for 'just'..."
    if [ -f "${COMPLETION_FILE}" ] && grep -q "${MARKER}" "${COMPLETION_FILE}"; then
        echo "--> 'just' completion is already configured."
        exit 0
    fi
    echo "--> Configuration not found. Adding it now..."
    mkdir -p "$(dirname "${COMPLETION_FILE}")"
    echo "" >> "${COMPLETION_FILE}"
    echo "${MARKER}" >> "${COMPLETION_FILE}"
    just --completions bash >> "${COMPLETION_FILE}"
    echo "--> Successfully added completion logic to ${COMPLETION_FILE}."
    echo ""
    echo "==> Setup complete. Please restart your shell or run:"
    echo "    source \"${COMPLETION_FILE}\""

# Remove ALL generated files, including venvs, caches, and build artifacts
distclean: clean-build clean-pyc clean-test
    #!/usr/bin/env bash
    set -e
    echo "==> Performing a deep clean (distclean)..."
    echo "--> Removing venvs, cache, and build/dist directories..."
    rm -rf {{UV_CACHE_DIR}} {{VENV_DIR}} build/ dist/ .pytest_cache/ .ruff_cache/ .ty/
    rm -rf docs/_build/
    echo "--> Searching for and removing nested Python caches..."
    find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
    echo "--> Searching for and removing compiled Python files..."
    find . -type f -name "*.pyc" -delete 2>/dev/null || true
    find . -type f -name "*.pyo" -delete 2>/dev/null || true
    echo "--> Searching for and removing setuptools egg-info directories..."
    find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
    echo "--> Removing CFFI build artifacts..."
    rm -f src/zlmdb/_lmdb_vendor/_lmdb_cffi.c src/zlmdb/_lmdb_vendor/_lmdb_cffi.o src/zlmdb/_lmdb_vendor/_lmdb_cffi*.so src/zlmdb/_lmdb_vendor/_lmdb_cffi*.pyd
    echo "==> Distclean complete. The project is now pristine."

# -----------------------------------------------------------------------------
# -- Python virtual environments
# -----------------------------------------------------------------------------

# List all Python virtual environments
list-all:
    #!/usr/bin/env bash
    set -e
    echo ""
    echo "Available CPython run-times:"
    echo "============================"
    echo ""
    uv python list --all-platforms cpython
    echo ""
    echo "Available PyPy run-times:"
    echo "========================="
    echo ""
    uv python list --all-platforms pypy
    echo ""
    echo "Mapped Python run-time shortname => full version:"
    echo "================================================="
    echo ""
    for env in {{ENVS}}; do
        spec=$(just --quiet _get-spec "$env")
        echo "  - $env => $spec"
    done
    echo ""
    echo "Create a Python venv using: just create <shortname>"

# Create a single Python virtual environment (usage: `just create cpy314` or `just create`)
create venv="":
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        echo "==> No venv name specified. Auto-detecting from system Python..."
        VENV_NAME=$(just --quiet _get-system-venv-name)
        echo "==> Defaulting to venv: '${VENV_NAME}'"
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    if [ ! -d "${VENV_PATH}" ]; then
        PYTHON_SPEC=$(just --quiet _get-spec "${VENV_NAME}")
        # For a GIL env, drop free-threaded CPython dirs (…t/bin, e.g. cp314t) that
        # manylinux images pre-install on PATH ahead of the GIL build, so uv does not
        # resolve e.g. cpy314 to a free-threaded cp314t interpreter (#124). The dedicated
        # cpy314t env is used to build free-threaded wheels. No-op off manylinux.
        CREATE_PATH="${PATH}"
        if [[ "${VENV_NAME}" != *t ]]; then
            CREATE_PATH="$(printf '%s' "${PATH}" | tr ':' '\n' | grep -vE '/opt/python/[^/]*t/bin$' | paste -sd: -)"
        fi
        echo "==> Creating Python virtual environment '${VENV_NAME}' using ${PYTHON_SPEC}..."
        mkdir -p "{{ VENV_DIR }}"
        PATH="${CREATE_PATH}" uv venv --seed --python "${PYTHON_SPEC}" "${VENV_PATH}"
        echo "==> Successfully created venv '${VENV_NAME}'."
    else
        echo "==> Python virtual environment '${VENV_NAME}' already exists."
    fi
    ${VENV_PYTHON} -V
    ${VENV_PYTHON} -m pip -V
    echo "==> Activate with: source ${VENV_PATH}/bin/activate"

# Create all Python virtual environments
create-all:
    #!/usr/bin/env bash
    for venv in {{ENVS}}; do
        just create ${venv}
    done

# Get the version of a single virtual environment's Python
version venv="":
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    if [ -d "{{ VENV_DIR }}/${VENV_NAME}" ]; then
        echo "==> Python virtual environment '${VENV_NAME}' exists:"
        "{{VENV_DIR}}/${VENV_NAME}/bin/python" -V
    else
        echo "==> Python virtual environment '${VENV_NAME}' does not exist."
    fi

# Get versions of all Python virtual environments
version-all:
    #!/usr/bin/env bash
    for venv in {{ENVS}}; do
        just version ${venv}
    done

# -----------------------------------------------------------------------------
# -- Package version management (CalVer YY.M.PATCH[.devN], PEP 440)
# -----------------------------------------------------------------------------
# Replicated from crossbar's version-management recipes to align the WAMP
# projects. Deviation: this repo does not track uv.lock, so (unlike crossbar)
# bump-next does not refresh or commit a lockfile.

# Display the current package version from both version files
file-version:
    @echo "Python file: $(grep '__version__' {{PY_VERSION_FILE}} | cut -d ' ' -f 3)"
    @echo "TOML file:   $(grep '^version =' {{TOML_VERSION_FILE}} | cut -d ' ' -f 3)"

# Prepare for a stable release: strip the .devN suffix from the version files
prep-release:
    @echo "Cleaning version for stable release..."
    sed -i 's/\.dev[0-9]*//' {{PY_VERSION_FILE}}
    sed -i 's/\.dev[0-9]*//' {{TOML_VERSION_FILE}}
    @just file-version
    @echo ''
    @echo 'Now (maintainer, on the dev PC only -- tags are never created by AI):'
    @echo '   1. Commit:    git add . && git commit -m "version bump for stable release"'
    @echo '   2. Tag:       git tag -a v<VERSION> -m "tagged stable release"'
    @echo '   3. Push tag:  git push upstream v<VERSION>'
    @echo '   4. Next dev:  just bump-next <NEXT-VERSION>.dev1'
    @echo ''

# Auto-bump to the next dev version for the current month (CalVer: YY.M.1.dev1)
bump-dev:
    #!/usr/bin/env bash
    set -e
    NEXT="$(date +%-y).$(date +%-m).1.dev1"
    echo "Auto-computed next dev version: ${NEXT}"
    just bump-next "${NEXT}"

# Set a specific next version (e.g. `just bump-next 26.7.2.dev1`)
bump-next next_version:
    @echo "Bumping version to {{next_version}}..."
    sed -i 's/__version__ = .*/__version__ = "{{next_version}}"/' {{PY_VERSION_FILE}}
    sed -i 's/^version = .*/version = "{{next_version}}"/' {{TOML_VERSION_FILE}}
    git add {{PY_VERSION_FILE}} {{TOML_VERSION_FILE}}
    git commit -m "chore: bump version to {{next_version}}"
    @echo "Branch is now at {{next_version}} and ready for development."

# -----------------------------------------------------------------------------
# -- Installation
# -----------------------------------------------------------------------------

# Install zlmdb with runtime dependencies
install venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Installing zlmdb in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pip install .

# Install zlmdb in development (editable) mode
install-dev venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Installing zlmdb in editable mode in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pip install -e .

    # Prepare LMDB sources for editable installs (build hooks don't run for -e)
    if [ ! -d "build/lmdb-src" ]; then
        echo "==> Preparing LMDB sources for editable install..."
        ${VENV_PYTHON} build_lmdb.py
    fi

# Install with locally editable WAMP packages for cross-repo development (usage: `just install-dev-local cpy312`)
install-dev-local venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")

    echo "==> Installing WAMP packages in editable mode from local repos..."
    echo "==> Looking for sibling repos (../txaio, ../autobahn-python)..."

    # Install local WAMP packages in editable mode
    # txaio - no extras needed
    if [ -d "../txaio" ]; then
        echo "  ✓ Installing txaio from ../txaio"
        ${VENV_PYTHON} -m pip install -e "../txaio"
    else
        echo "  ⚠ Warning: ../txaio not found, skipping"
    fi

    # autobahn-python - install with twisted extra
    if [ -d "../autobahn-python" ]; then
        echo "  ✓ Installing autobahn-python with [twisted] from ../autobahn-python"
        ${VENV_PYTHON} -m pip install -e "../autobahn-python[twisted]"
    else
        echo "  ⚠ Warning: ../autobahn-python not found, skipping"
    fi

    echo "==> Installing zlmdb in editable mode with [dev] extras..."
    ${VENV_PYTHON} -m pip install -e .[dev] --upgrade --upgrade-strategy only-if-needed

    # Prepare LMDB sources for editable installs
    if [ ! -d "build/lmdb-src" ]; then
        echo "==> Preparing LMDB sources for editable install..."
        ${VENV_PYTHON} build_lmdb.py
    fi

# Install all environments
install-all:
    #!/usr/bin/env bash
    for venv in {{ENVS}}; do
        just install ${venv}
    done

# Meta-recipe to run `install-dev` on all environments
install-dev-all:
    #!/usr/bin/env bash
    for venv in {{ENVS}}; do
        just install-dev ${venv}
    done

# Upgrade dependencies in a single environment (usage: `just upgrade cpy314`)
upgrade venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Upgrading dependencies in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pip install --upgrade pip
    ${VENV_PYTHON} -m pip install --upgrade -e .[dev]
    echo "==> Dependencies upgraded in ${VENV_NAME}."

# Meta-recipe to run `upgrade` on all environments
upgrade-all:
    #!/usr/bin/env bash
    set -e
    for venv in {{ENVS}}; do
        just upgrade ${venv}
    done

# Install development tools (ruff, mypy, sphinx, etc.)
install-tools venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Installing development tools in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pip install -e .[dev]

# Meta-recipe to run `install-tools` on all environments
install-tools-all:
    #!/usr/bin/env bash
    set -e
    for venv in {{ENVS}}; do
        just install-tools ${venv}
    done

# Install minimal build tools for building wheels
install-build-tools venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Installing minimal build tools in ${VENV_NAME}..."
    # setuptools is required by CFFI's extension build / ffi.verify() on Python >= 3.12
    ${VENV_PYTHON} -m pip install build wheel cffi setuptools auditwheel

# -----------------------------------------------------------------------------
# -- Testing
# -----------------------------------------------------------------------------

# Test namespace isolation (verify lmdb import behavior)
test-import venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Testing namespace isolation in ${VENV_NAME}..."
    echo ""

    # Test 1: 'import lmdb' should FAIL
    echo "Test 1: Verifying 'import lmdb' raises ModuleNotFoundError..."
    if ${VENV_PYTHON} -c "import lmdb" 2>/dev/null; then
        echo "  ❌ FAIL: 'import lmdb' succeeded (should have failed)"
        exit 1
    else
        echo "  ✓ PASS: 'import lmdb' correctly raises ModuleNotFoundError"
    fi
    echo ""

    # Test 2: 'import zlmdb.lmdb as lmdb' should SUCCEED
    echo "Test 2: Verifying 'import zlmdb.lmdb as lmdb' works..."
    if ${VENV_PYTHON} -c "import zlmdb.lmdb as lmdb; print('  Version:', lmdb.version())" 2>&1; then
        echo "  ✓ PASS: 'import zlmdb.lmdb as lmdb' works"
    else
        echo "  ❌ FAIL: 'import zlmdb.lmdb as lmdb' failed"
        exit 1
    fi
    echo ""

    # Test 3: 'from zlmdb import lmdb' should SUCCEED
    echo "Test 3: Verifying 'from zlmdb import lmdb' works..."
    if ${VENV_PYTHON} -c "from zlmdb import lmdb; print('  Version:', lmdb.version())" 2>&1; then
        echo "  ✓ PASS: 'from zlmdb import lmdb' works"
    else
        echo "  ❌ FAIL: 'from zlmdb import lmdb' failed"
        exit 1
    fi
    echo ""

    # Test 4: Check version attributes
    echo "Test 4: Verifying version attributes..."
    ${VENV_PYTHON} -c "import zlmdb; print('  zlmdb.__version__:', zlmdb.__version__)"

    # LMDB 0.9.33 Release (2024/05/21)
    #
    #   - Development happens on mdb.master (version 0.9.70).
    #   - Releases are backported/committed to mdb.RE/0.9.
    #   - Tagging happens on mdb.RE/0.9.
    #
    # Thus we want to track the tip of the mdb.RE/0.9 branch.
    #
    # See:
    #   - https://github.com/LMDB/lmdb/blob/mdb.RE/0.9/libraries/liblmdb/CHANGES
    #   - https://github.com/LMDB/lmdb/blob/mdb.master/libraries/liblmdb/lmdb.h
    #   - https://github.com/LMDB/lmdb/commit/3a29a24777c82a0165de813ae696a5068b5add30
    #
    # MDB_VERSION_MAJOR   0     // Library major version
    # MDB_VERSION_MINOR   9     // Library minor version
    # MDB_VERSION_PATCH   33    // Library patch version

    # Test 4b: Verify zlmdb.lmdb does NOT have __version__
    echo ""
    echo "Test 4b: Verifying zlmdb.lmdb has NO __version__ (only zlmdb has version)..."
    if ${VENV_PYTHON} -c "import zlmdb.lmdb as lmdb; lmdb.__version__" 2>/dev/null; then
        echo "  ❌ FAIL: zlmdb.lmdb.__version__ exists (should not exist)"
        exit 1
    else
        echo "  ✓ PASS: zlmdb.lmdb has no __version__ attribute (correct)"
    fi
    echo ""

    echo "Test 5: Verifying zlmdb.lmdb.version()..."
    ${VENV_PYTHON} -c "import zlmdb; print(f'  zlmdb.lmdb.version(): {zlmdb.lmdb.version()}')"
    echo ""

    # For a production or stable project (like zlmdb), the recommended approach is to strictly
    # use and track the Latest Named Tag, not Development:
    #
    # cd deps/flatbuffers && git checkout $(git describe --tags --abbrev=0) && git describe --tags

    echo "Test 6: Verifying zlmdb.flatbuffers.__version__..."
    ${VENV_PYTHON} -c "import zlmdb; print(f'  zlmdb.flatbuffers.__version__: {zlmdb.flatbuffers.__version__}')"
    echo ""

    echo "Test 7: Verifying zlmdb.flatbuffers._git_version__..."
    ${VENV_PYTHON} -c "import zlmdb; print(f'  zlmdb.flatbuffers.__git_version__: {zlmdb.flatbuffers.__git_version__}')"
    echo ""

    echo "Test 8: Verifying zlmdb.flatbuffers.version()..."
    ${VENV_PYTHON} -c "import zlmdb; print(f'  zlmdb.flatbuffers.version(): {zlmdb.flatbuffers.version()}')"
    echo ""

    echo "========================================================================"
    echo "✅ ALL NAMESPACE ISOLATION TESTS PASSED"
    echo "========================================================================"

# Test flatbuffers reflection imports (verifies vendored reflection module works)
# This is the test that cfxdb, wamp-xbr, and crossbar depend on - they use Schema.GetRootAs()
# to load .bfbs files for dynamic FlatBuffers access.
# See: https://github.com/crossbario/zlmdb/issues/102
test-reflection venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Testing flatbuffers reflection imports in ${VENV_NAME}..."
    echo ""

    # Run the reflection test script
    ${VENV_PYTHON} "{{ PROJECT_DIR }}/scripts/test_reflection.py"

    echo ""
    echo "========================================================================"
    echo "✅ ALL REFLECTION IMPORT TESTS PASSED"
    echo "========================================================================"

# Test bundled flatc compiler (verifies flatc binary is bundled and works)
test-bundled-flatc venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Testing bundled flatc compiler in ${VENV_NAME}..."
    echo ""

    # Test 1: flatc console script works
    echo "Test 1: Verifying 'flatc --version' works via console script..."
    FLATC_VERSION=$("${VENV_PATH}/bin/flatc" --version 2>&1)
    if [ $? -eq 0 ]; then
        echo "  ✓ PASS: flatc console script works"
        echo "  Version: ${FLATC_VERSION}"
    else
        echo "  ❌ FAIL: flatc console script failed"
        exit 1
    fi
    echo ""

    # Test 2: Python API get_flatc_path() works
    echo "Test 2: Verifying zlmdb._flatc.get_flatc_path() works..."
    FLATC_PATH=$(${VENV_PYTHON} -c "from zlmdb._flatc import get_flatc_path; print(get_flatc_path())")
    if [ -x "${FLATC_PATH}" ]; then
        echo "  ✓ PASS: get_flatc_path() returns executable path"
        echo "  Path: ${FLATC_PATH}"
    else
        echo "  ❌ FAIL: get_flatc_path() returned non-executable: ${FLATC_PATH}"
        exit 1
    fi
    echo ""

    # Test 3: Python API run_flatc() works
    echo "Test 3: Verifying zlmdb._flatc.run_flatc() works..."
    RET=$(${VENV_PYTHON} -c "from zlmdb._flatc import run_flatc; exit(run_flatc(['--version']))")
    if [ $? -eq 0 ]; then
        echo "  ✓ PASS: run_flatc(['--version']) works"
    else
        echo "  ❌ FAIL: run_flatc() failed"
        exit 1
    fi
    echo ""

    # Test 4: reflection.fbs is accessible
    echo "Test 4: Verifying reflection.fbs is accessible at runtime..."
    FBS_PATH=$(${VENV_PYTHON} -c 'import zlmdb.flatbuffers; from pathlib import Path; p = Path(zlmdb.flatbuffers.__file__).parent / "reflection.fbs"; print(p) if p.exists() else exit(1)')
    if [ $? -eq 0 ]; then
        FBS_SIZE=$(stat -c%s "${FBS_PATH}" 2>/dev/null || stat -f%z "${FBS_PATH}")
        echo "  ✓ PASS: reflection.fbs found at ${FBS_PATH}"
        echo "  Size: ${FBS_SIZE} bytes"
    else
        echo "  ❌ FAIL: reflection.fbs not found"
        exit 1
    fi
    echo ""

    # Test 5: reflection.bfbs is accessible
    echo "Test 5: Verifying reflection.bfbs is accessible at runtime..."
    BFBS_PATH=$(${VENV_PYTHON} -c 'import zlmdb.flatbuffers; from pathlib import Path; p = Path(zlmdb.flatbuffers.__file__).parent / "reflection.bfbs"; print(p) if p.exists() else exit(1)')
    if [ $? -eq 0 ]; then
        BFBS_SIZE=$(stat -c%s "${BFBS_PATH}" 2>/dev/null || stat -f%z "${BFBS_PATH}")
        echo "  ✓ PASS: reflection.bfbs found at ${BFBS_PATH}"
        echo "  Size: ${BFBS_SIZE} bytes"
    else
        echo "  ❌ FAIL: reflection.bfbs not found"
        exit 1
    fi
    echo ""

    echo "========================================================================"
    echo "✅ ALL BUNDLED FLATC TESTS PASSED"
    echo "========================================================================"

# -----------------------------------------------------------------------------
# -- Artifact Verification (smoke tests for built wheels and sdist)
# -----------------------------------------------------------------------------

# Run smoke tests on an installed zlmdb package (verifies LMDB + FlatBuffers work)
# This is used by test-wheel-install and test-sdist-install after installation
test-smoke venv="":
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"

    echo "Running smoke tests with Python: $(${VENV_PYTHON} --version)"
    echo "Venv: ${VENV_PATH}"
    echo ""

    # Run the smoke test Python script
    ${VENV_PYTHON} "{{ PROJECT_DIR }}/scripts/smoke_test.py"

# Test installing and verifying a built wheel (used in CI for artifact verification)
# Usage: just test-wheel-install /path/to/zlmdb-*.whl
test-wheel-install wheel_path:
    #!/usr/bin/env bash
    set -e
    WHEEL_PATH="{{ wheel_path }}"

    if [ ! -f "${WHEEL_PATH}" ]; then
        echo "ERROR: Wheel file not found: ${WHEEL_PATH}"
        exit 1
    fi

    WHEEL_NAME=$(basename "${WHEEL_PATH}")
    echo "========================================================================"
    echo "  WHEEL INSTALL TEST"
    echo "========================================================================"
    echo ""
    echo "Wheel: ${WHEEL_NAME}"
    echo ""

    # Create ephemeral venv name based on wheel
    EPHEMERAL_VENV="smoke-wheel-$$"
    EPHEMERAL_PATH="{{ VENV_DIR }}/${EPHEMERAL_VENV}"

    # Extract Python version from wheel filename
    # Wheel format: {name}-{version}-{python tag}-{abi tag}-{platform tag}.whl
    # Python tag examples: cp312, cp311, pp311, py3
    PYTAG=$(echo "${WHEEL_NAME}" | sed -n 's/.*-\(cp[0-9]*\|pp[0-9]*\|py[0-9]*\)-.*/\1/p')

    if [[ "${PYTAG}" =~ ^cp([0-9])([0-9]+)$ ]]; then
        # CPython wheel (e.g., cp312 -> 3.12)
        MAJOR="${BASH_REMATCH[1]}"
        MINOR="${BASH_REMATCH[2]}"
        PYTHON_SPEC="cpython-${MAJOR}.${MINOR}"
        echo "Detected CPython ${MAJOR}.${MINOR} wheel"
    elif [[ "${PYTAG}" =~ ^pp([0-9])([0-9]+)$ ]]; then
        # PyPy wheel (e.g., pp311 -> pypy-3.11)
        MAJOR="${BASH_REMATCH[1]}"
        MINOR="${BASH_REMATCH[2]}"
        PYTHON_SPEC="pypy-${MAJOR}.${MINOR}"
        echo "Detected PyPy ${MAJOR}.${MINOR} wheel"
    elif [[ "${PYTAG}" =~ ^py([0-9])$ ]]; then
        # Pure Python wheel (e.g., py3) - use system Python
        SYSTEM_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
        PYTHON_SPEC="cpython-${SYSTEM_VERSION}"
        echo "Pure Python wheel, using system Python ${SYSTEM_VERSION}"
    else
        # Fallback to system Python
        SYSTEM_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
        PYTHON_SPEC="cpython-${SYSTEM_VERSION}"
        echo "Could not detect Python version from wheel, using system Python ${SYSTEM_VERSION}"
    fi

    echo "Creating ephemeral venv with ${PYTHON_SPEC}..."

    mkdir -p "{{ VENV_DIR }}"
    uv venv --seed --python "${PYTHON_SPEC}" "${EPHEMERAL_PATH}"

    EPHEMERAL_PYTHON="${EPHEMERAL_PATH}/bin/python3"

    # Install the wheel
    echo ""
    echo "Installing wheel..."
    ${EPHEMERAL_PYTHON} -m pip install "${WHEEL_PATH}"

    # Run smoke tests
    echo ""
    VENV_DIR="{{ VENV_DIR }}" just test-smoke "${EPHEMERAL_VENV}"

    # Cleanup
    echo ""
    echo "Cleaning up ephemeral venv..."
    rm -rf "${EPHEMERAL_PATH}"

    echo ""
    echo "========================================================================"
    echo "✅ WHEEL INSTALL TEST PASSED: ${WHEEL_NAME}"
    echo "========================================================================"

# Test installing and verifying a source distribution (used in CI for artifact verification)
# Usage: just test-sdist-install /path/to/zlmdb-*.tar.gz
test-sdist-install sdist_path:
    #!/usr/bin/env bash
    set -e
    SDIST_PATH="{{ sdist_path }}"

    if [ ! -f "${SDIST_PATH}" ]; then
        echo "ERROR: Source distribution not found: ${SDIST_PATH}"
        exit 1
    fi

    SDIST_NAME=$(basename "${SDIST_PATH}")
    echo "========================================================================"
    echo "  SOURCE DISTRIBUTION INSTALL TEST"
    echo "========================================================================"
    echo ""
    echo "Source dist: ${SDIST_NAME}"
    echo ""

    # Check if cmake is available (required for full functionality)
    if command -v cmake >/dev/null 2>&1; then
        echo "cmake: $(cmake --version | head -1)"
    else
        echo "WARNING: cmake not found - flatc binary will not be built"
        echo "         Install cmake for full functionality"
    fi
    echo ""

    # Create ephemeral venv name
    EPHEMERAL_VENV="smoke-sdist-$$"
    EPHEMERAL_PATH="{{ VENV_DIR }}/${EPHEMERAL_VENV}"

    echo "Creating ephemeral venv: ${EPHEMERAL_VENV}..."

    # Detect system Python version and create venv
    SYSTEM_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
    ENV_NAME="cpy$(echo ${SYSTEM_VERSION} | tr -d '.')"
    PYTHON_SPEC="cpython-${SYSTEM_VERSION}"

    mkdir -p "{{ VENV_DIR }}"
    uv venv --seed --python "${PYTHON_SPEC}" "${EPHEMERAL_PATH}"

    EPHEMERAL_PYTHON="${EPHEMERAL_PATH}/bin/python3"

    # Install build dependencies (required for --no-build-isolation)
    # CFFI is needed for LMDB extension, hatchling for the build system
    # Use --no-cache-dir consistently to ensure fresh installs
    echo ""
    echo "Installing build dependencies..."
    ${EPHEMERAL_PYTHON} -m pip install --no-cache-dir cffi setuptools wheel hatchling

    # Install from source distribution (this will compile LMDB CFFI extension)
    # Use --no-build-isolation to allow access to system cmake for building flatc
    # Use --no-cache-dir to disable HTTP download cache
    # Use --no-binary zlmdb to force building from source (disable wheel cache)
    # Note: flatc may not build if cmake is missing or grpc submodule isn't present
    echo ""
    echo "Installing from source distribution (includes CFFI compilation)..."
    ${EPHEMERAL_PYTHON} -m pip install --no-build-isolation --no-cache-dir --no-binary zlmdb "${SDIST_PATH}"

    # Run smoke tests
    echo ""
    VENV_DIR="{{ VENV_DIR }}" just test-smoke "${EPHEMERAL_VENV}"

    # Cleanup
    echo ""
    echo "Cleaning up ephemeral venv..."
    rm -rf "${EPHEMERAL_PATH}"

    echo ""
    echo "========================================================================"
    echo "✅ SOURCE DISTRIBUTION INSTALL TEST PASSED: ${SDIST_NAME}"
    echo "========================================================================"

# Test all LMDB examples
test-examples-lmdb venv="": (test-examples-lmdb-addressbook venv) (test-examples-lmdb-dirtybench-gdbm venv) (test-examples-lmdb-dirtybench venv) (test-examples-lmdb-nastybench venv) (test-examples-lmdb-parabench venv)

# Test example LMDB address book
test-examples-lmdb-addressbook venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo ""
    echo "==> Testing in ${VENV_NAME} ..."
    echo ""
    ${VENV_PYTHON} examples/lmdb/address-book.py

# Test example LMDB dirtybench-gdbm
test-examples-lmdb-dirtybench-gdbm venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo ""
    echo "==> Testing in ${VENV_NAME} ..."
    echo ""
    ${VENV_PYTHON} examples/lmdb/dirtybench-gdbm.py

# Test example LMDB dirtybench (comprehensive benchmark, takes ~3-5 minutes)
test-examples-lmdb-dirtybench venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo ""
    echo "==> Testing in ${VENV_NAME} ..."
    echo ""
    # This benchmark takes ~3 minutes on fast hardware, allow 5 minutes for CI
    timeout 300 ${VENV_PYTHON} examples/lmdb/dirtybench.py

# Test example LMDB nastybench
test-examples-lmdb-nastybench venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo ""
    echo "==> Testing in ${VENV_NAME} ..."
    echo ""
    timeout 60 ${VENV_PYTHON} examples/lmdb/nastybench.py

# Test example LMDB parabench (parallel benchmark, generates 4M keys then runs benchmark)
test-examples-lmdb-parabench venv="": (install venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo ""
    echo "==> Testing in ${VENV_NAME} ..."
    echo ""
    # Run with 2 processes for 10 seconds
    # Key generation takes ~15-20 seconds, benchmark runs for 10 seconds
    # Allow 90 seconds total for CI
    timeout 90 ${VENV_PYTHON} examples/lmdb/parabench.py 2 10

# Run test suite for ORM.
test-orm venv="": (install-tools venv) (install-dev venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running test suite in ${VENV_NAME}..."
    QUICK=1 ${VENV_PYTHON} -m pytest --log-cli-level=INFO -v src/zlmdb/tests/orm/

# Run LMDB low-level API tests
test-lmdb venv="": (install-tools venv) (install-dev venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running LMDB tests in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pytest -v src/zlmdb/tests/lmdb/

# Run the test suite (both zlmdb/tests and tests directories)
test venv="": (install-tools venv) (install-dev venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running test suite in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pytest -v src/zlmdb/tests/

# Run tests in all environments
test-all:
    #!/usr/bin/env bash
    for venv in {{ENVS}}; do
        just test ${venv}
    done

# -----------------------------------------------------------------------------
# -- Building
# -----------------------------------------------------------------------------

# Build wheel package
build venv="": (install-build-tools venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"

    # Fail fast if the interpreter ABI doesn't match the env (zlmdb #124 / autobahn #1875):
    # prevents publishing e.g. a free-threaded cp314t wheel in the GIL cp314 slot.
    just _check-venv-abi "${VENV_NAME}"

    echo "==> Building wheel package with ${VENV_NAME}..."
    mkdir -p dist/

    # Build the wheel
    ${VENV_PYTHON} -m build --wheel

    # Convert linux wheels to manylinux format using auditwheel
    if [ -x "${VENV_PATH}/bin/auditwheel" ]; then
        for wheel in dist/*-linux_*.whl; do
            if [ -f "$wheel" ]; then
                echo "==> Converting $(basename $wheel) to manylinux format..."
                "${VENV_PATH}/bin/auditwheel" show "$wheel"
                "${VENV_PATH}/bin/auditwheel" repair "$wheel" -w dist/
                # Remove the original linux wheel after successful repair
                rm "$wheel"
            fi
        done
    else
        echo "WARNING: auditwheel not available, skipping manylinux conversion"
    fi

    ls -lh dist/

# Build source distribution
build-sourcedist venv="": (install-build-tools venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Building source distribution with ${VENV_NAME}..."

    # CRITICAL: Initialize all submodules recursively BEFORE building sdist
    # Hatchling uses `git ls-files` to determine what goes into the sdist,
    # and nested submodules (like deps/flatbuffers/grpc/) must be initialized
    # for their files to be visible to git and thus included in the sdist.
    echo "==> Initializing git submodules (recursive)..."
    git submodule update --init --recursive

    mkdir -p dist/
    ${VENV_PYTHON} -m build --sdist
    ls -lh dist/

# Build wheels for all environments
build-all:
    #!/usr/bin/env bash
    set -e
    for venv in {{ENVS}}; do
        just build ${venv}
    done
    if [ -d dist/ ]; then
        ls -lh dist/
    else
        echo "WARNING: dist/ directory not found"
        mkdir -p dist/
    fi

# Verify wheels using auditwheel and other checks
verify-wheels venv="": (install-tools venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{PROJECT_DIR}}/.venvs/${VENV_NAME}"
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")

    echo "==> Verifying built wheels using ${VENV_NAME}..."
    echo ""

    WHEEL_COUNT=$(ls "{{PROJECT_DIR}}/dist/"*.whl 2>/dev/null | wc -l)
    if [ "$WHEEL_COUNT" -eq 0 ]; then
        echo "ERROR: No wheels found in {{PROJECT_DIR}}/dist/"
        exit 1
    fi

    echo "Found $WHEEL_COUNT wheel(s) in dist/"
    echo ""

    # Run twine check on all packages first
    echo "========================================================================"
    echo "Running twine check (package metadata validation)"
    echo "========================================================================"
    "${VENV_PATH}/bin/twine" check "{{PROJECT_DIR}}/dist/"*
    echo ""

    PURE_PYTHON_WHEELS=0
    BINARY_WHEELS=0
    FAILURES=0

    for wheel in "{{PROJECT_DIR}}/dist/"*.whl; do
        WHEEL_NAME=$(basename "$wheel")
        echo "========================================================================"
        echo "Checking: $WHEEL_NAME"
        echo "========================================================================"

        # Check if it's a pure Python wheel (should NOT be!)
        if [[ "$WHEEL_NAME" == *"-py3-none-any.whl" ]] || [[ "$WHEEL_NAME" == *"-py2.py3-none-any.whl" ]]; then
            echo "❌ FAIL: Pure Python wheel detected (should be binary!)"
            echo "   This wheel does not contain compiled extensions"
            ((++PURE_PYTHON_WHEELS))
            ((++FAILURES))
            echo ""
            continue
        fi

        # Check if it's a platform-specific wheel
        if [[ "$WHEEL_NAME" == *"-linux_"* ]] || [[ "$WHEEL_NAME" == *"-macosx_"* ]] || [[ "$WHEEL_NAME" == *"-win_"* ]]; then
            PLATFORM=$(echo "$WHEEL_NAME" | grep -oE '(linux|macosx|win)[_-][a-z0-9_]+' | head -1)
            echo "✓ Platform-specific wheel: $PLATFORM"
            ((++BINARY_WHEELS))
        else
            echo "⚠ WARNING: Unexpected wheel naming format"
        fi

        # Check wheel contents for CFFI extension
        echo ""
        echo "Checking for CFFI extension (.so file):"
        if ${VENV_PYTHON} -m zipfile -l "$wheel" | grep -q "_lmdb_cffi.*\.so"; then
            SO_FILE=$(${VENV_PYTHON} -m zipfile -l "$wheel" | grep "_lmdb_cffi.*\.so" | awk '{print $1}')
            SO_SIZE=$(${VENV_PYTHON} -m zipfile -l "$wheel" | grep "_lmdb_cffi.*\.so" | awk '{print $NF}')
            echo "  ✓ Found: $SO_FILE ($(numfmt --to=iec-i --suffix=B $SO_SIZE 2>/dev/null || echo "$SO_SIZE bytes"))"
        else
            echo "  ❌ FAIL: No CFFI extension found in wheel"
            ((++FAILURES))
        fi

        # Run auditwheel check (only for Linux wheels)
        if [[ "$WHEEL_NAME" == *"-linux_"* ]]; then
            echo ""
            echo "Running auditwheel check:"
            if "${VENV_PATH}/bin/auditwheel" show "$wheel" 2>&1; then
                echo "  ✓ auditwheel check passed"
            else
                echo "  ❌ FAIL: auditwheel check failed"
                ((++FAILURES))
            fi
        fi

        echo ""
    done

    echo "========================================================================"
    echo "Summary"
    echo "========================================================================"
    echo "Total wheels: $WHEEL_COUNT"
    echo "Binary wheels: $BINARY_WHEELS"
    echo "Pure Python wheels: $PURE_PYTHON_WHEELS (should be 0)"
    echo "Failures: $FAILURES"
    echo ""

    if [ $FAILURES -gt 0 ]; then
        echo "❌ VERIFICATION FAILED"
        exit 1
    elif [ $PURE_PYTHON_WHEELS -gt 0 ]; then
        echo "❌ VERIFICATION FAILED: Pure Python wheels detected"
        exit 1
    else
        echo "✅ ALL WHEELS VERIFIED SUCCESSFULLY"
    fi

# -----------------------------------------------------------------------------
# -- Documentation
# -----------------------------------------------------------------------------

# Install documentation dependencies
install-docs venv="": (create venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        echo "==> No venv name specified. Auto-detecting from system Python..."
        VENV_NAME=$(just --quiet _get-system-venv-name)
        echo "==> Defaulting to venv: '${VENV_NAME}'"
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Installing documentation tools in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pip install -e .[docs]

# Sync images (logo and favicon) from autobahn-python (Autobahn subarea source)
sync-images:
    #!/usr/bin/env bash
    set -e

    SOURCEDIR="{{ PROJECT_DIR }}/../autobahn-python/docs/_static"
    TARGETDIR="{{ PROJECT_DIR }}/docs/_static"
    IMGDIR="${TARGETDIR}/img"

    echo "==> Syncing images from autobahn-python..."
    mkdir -p "${IMGDIR}"

    # Copy optimized logo SVG
    if [ -f "${SOURCEDIR}/img/autobahn_logo_blue.svg" ]; then
        cp "${SOURCEDIR}/img/autobahn_logo_blue.svg" "${IMGDIR}/"
        echo "  Copied: autobahn_logo_blue.svg"
    else
        echo "  Warning: autobahn_logo_blue.svg not found in autobahn-python"
        echo "  Run 'just optimize-images' in autobahn-python first"
    fi

    # Copy favicon
    if [ -f "${SOURCEDIR}/favicon.ico" ]; then
        cp "${SOURCEDIR}/favicon.ico" "${TARGETDIR}/"
        echo "  Copied: favicon.ico"
    else
        echo "  Warning: favicon.ico not found in autobahn-python"
        echo "  Run 'just optimize-images' in autobahn-python first"
    fi

    echo "==> Image sync complete."

# Build HTML documentation using Sphinx
docs venv="": (install-docs venv) (sync-images)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    echo "==> Building documentation with ${VENV_NAME}..."
    "${VENV_PATH}/bin/sphinx-build" -b html docs/ docs/_build/html

# View built documentation
docs-view venv="": (docs venv)
    echo "==> Opening documentation in browser..."
    xdg-open docs/_build/html/index.html 2>/dev/null || open docs/_build/html/index.html 2>/dev/null || echo "Please open docs/_build/html/index.html manually"

# Integrate downloaded GitHub release artifacts into docs build
# Usage: just docs-integrate-github-release [release_tag]
# If no tag specified, finds the most recently downloaded artifacts
docs-integrate-github-release release_tag="":
    #!/usr/bin/env bash
    set -e

    RELEASE_TAG="{{ release_tag }}"

    # Check that docs have been built first
    if [ ! -d "docs/_build/html" ]; then
        echo "❌ ERROR: Documentation not built yet"
        echo ""
        echo "Please build documentation first using:"
        echo "  just docs"
        echo ""
        echo "Then integrate artifacts with:"
        echo "  just docs-integrate-github-release"
        echo ""
        exit 1
    fi

    # If no tag specified, find the most recently downloaded artifacts
    if [ -z "${RELEASE_TAG}" ]; then
        echo "==> No release tag specified. Finding latest downloaded artifacts..."
        LATEST_DIR=$(find /tmp/release-artifacts -maxdepth 1 -type d -printf "%T@ %p\n" 2>/dev/null \
          | sort -rn \
          | head -1 \
          | cut -d' ' -f2-)

        if [ -z "${LATEST_DIR}" ] || [ "${LATEST_DIR}" = "/tmp/release-artifacts" ]; then
            echo "❌ ERROR: No downloaded release artifacts found in /tmp/release-artifacts/"
            echo ""
            echo "Please download artifacts first using:"
            echo "  just download-github-release"
            echo ""
            exit 1
        fi

        RELEASE_TAG=$(basename "${LATEST_DIR}")
        echo "✅ Found latest downloaded artifacts: ${RELEASE_TAG}"
    fi

    DOWNLOAD_DIR="/tmp/release-artifacts/${RELEASE_TAG}"

    if [ ! -d "${DOWNLOAD_DIR}" ]; then
        echo "❌ ERROR: Release artifacts not found at: ${DOWNLOAD_DIR}"
        echo ""
        echo "Please download artifacts first using:"
        echo "  just download-github-release ${RELEASE_TAG}"
        echo ""
        exit 1
    fi

    echo "==> Integrating GitHub release artifacts into built documentation..."
    echo "    Release: ${RELEASE_TAG}"
    echo "    Source: ${DOWNLOAD_DIR}"
    echo "    Target: docs/_build/html/_static/"
    echo ""

    # Create target directories in the BUILT docs
    echo "==> Creating target directories in docs/_build/html/_static/..."
    mkdir -p docs/_build/html/_static/flatbuffers
    mkdir -p docs/_build/html/_static/release

    # Copy FlatBuffers schemas (source .fbs files)
    echo "==> Copying FlatBuffers source schemas (.fbs)..."
    if [ -d "${DOWNLOAD_DIR}/flatbuffers" ]; then
        FBS_COUNT=$(find "${DOWNLOAD_DIR}/flatbuffers" -name "*.fbs" -type f 2>/dev/null | wc -l)
        if [ "${FBS_COUNT}" -gt 0 ]; then
            cp "${DOWNLOAD_DIR}/flatbuffers"/*.fbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
            echo "✅ Copied ${FBS_COUNT} .fbs files to docs/_build/html/_static/flatbuffers/"
        else
            echo "⚠️  No .fbs files found in ${DOWNLOAD_DIR}/flatbuffers"
        fi
    else
        FBS_COUNT=$(find "${DOWNLOAD_DIR}" -maxdepth 1 -name "*.fbs" -type f 2>/dev/null | wc -l)
        if [ "${FBS_COUNT}" -gt 0 ]; then
            cp "${DOWNLOAD_DIR}"/*.fbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
            echo "✅ Copied ${FBS_COUNT} .fbs files to docs/_build/html/_static/flatbuffers/"
        else
            echo "⚠️  No .fbs files found in ${DOWNLOAD_DIR}"
        fi
    fi

    # Copy FlatBuffers binary schemas (.bfbs files)
    echo "==> Copying FlatBuffers binary schemas (.bfbs)..."
    if [ -d "${DOWNLOAD_DIR}/gen/schema" ]; then
        BFBS_COUNT=$(find "${DOWNLOAD_DIR}/gen/schema" -name "*.bfbs" -type f 2>/dev/null | wc -l)
        if [ "${BFBS_COUNT}" -gt 0 ]; then
            cp "${DOWNLOAD_DIR}/gen/schema"/*.bfbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
            echo "✅ Copied ${BFBS_COUNT} .bfbs files to docs/_build/html/_static/flatbuffers/"
        else
            echo "⚠️  No .bfbs files found in ${DOWNLOAD_DIR}/gen/schema"
        fi
    elif [ -d "${DOWNLOAD_DIR}/flatbuffers" ]; then
        BFBS_COUNT=$(find "${DOWNLOAD_DIR}/flatbuffers" -name "*.bfbs" -type f 2>/dev/null | wc -l)
        if [ "${BFBS_COUNT}" -gt 0 ]; then
            cp "${DOWNLOAD_DIR}/flatbuffers"/*.bfbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
            echo "✅ Copied ${BFBS_COUNT} .bfbs files to docs/_build/html/_static/flatbuffers/"
        else
            echo "⚠️  No .bfbs files found in ${DOWNLOAD_DIR}/flatbuffers"
        fi
    else
        BFBS_COUNT=$(find "${DOWNLOAD_DIR}" -maxdepth 1 -name "*.bfbs" -type f 2>/dev/null | wc -l)
        if [ "${BFBS_COUNT}" -gt 0 ]; then
            cp "${DOWNLOAD_DIR}"/*.bfbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
            echo "✅ Copied ${BFBS_COUNT} .bfbs files to docs/_build/html/_static/flatbuffers/"
        else
            echo "⚠️  No .bfbs files found in ${DOWNLOAD_DIR}"
        fi
    fi

    # Copy chain-of-custody files (checksums, validation, build info)
    echo "==> Copying chain-of-custody files..."
    for custody_file in CHECKSUMS.sha256 VALIDATION.txt build-info.txt; do
        if [ -f "${DOWNLOAD_DIR}/${custody_file}" ]; then
            cp "${DOWNLOAD_DIR}/${custody_file}" docs/_build/html/_static/release/
            echo "✅ Copied ${custody_file} to docs/_build/html/_static/release/"
        fi
    done

    echo ""
    echo "════════════════════════════════════════════════════════════"
    echo "✅ GitHub release artifacts integrated into built documentation"
    echo "════════════════════════════════════════════════════════════"
    echo ""
    echo "Integrated artifacts from: ${RELEASE_TAG}"
    echo "Target location: docs/_build/html/_static/"
    echo ""
    echo "Contents integrated:"
    echo "  - FlatBuffers schemas: docs/_build/html/_static/flatbuffers/"
    echo "  - Chain-of-custody:    docs/_build/html/_static/release/"
    echo ""
    echo "Next steps:"
    echo "  1. View documentation: just docs-view"
    echo ""

# Clean generated documentation
docs-clean:
    echo "==> Cleaning documentation build artifacts..."
    rm -rf docs/_build

# Run spelling check on documentation
docs-spelling venv="": (install-docs venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        echo "==> No venv name specified. Auto-detecting from system Python..."
        VENV_NAME=$(just --quiet _get-system-venv-name)
        echo "==> Defaulting to venv: '${VENV_NAME}'"
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    TMPBUILDDIR="./.build"
    mkdir -p "${TMPBUILDDIR}"
    echo "==> Running spell check on documentation..."
    "${VENV_PATH}/bin/sphinx-build" -b spelling -d "${TMPBUILDDIR}/docs/doctrees" docs "${TMPBUILDDIR}/docs/spelling"

# -----------------------------------------------------------------------------
# -- Cleaning (granular targets from Makefile)
# -----------------------------------------------------------------------------

# Clean Python bytecode files
clean-pyc:
    echo "==> Removing Python bytecode files..."
    find . -name '*.pyc' -delete
    find . -name '*.pyo' -delete
    find . -name '*~' -delete
    find . -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true

# Clean build artifacts
clean-build:
    echo "==> Removing build artifacts..."
    rm -rf build/ dist/ .eggs/
    find . -name '*.egg-info' -exec rm -rf {} + 2>/dev/null || true
    find . -name '*.egg' -delete 2>/dev/null || true
    echo "==> Removing CFFI build artifacts..."
    rm -f src/zlmdb/_lmdb_vendor/_lmdb_cffi.c src/zlmdb/_lmdb_vendor/_lmdb_cffi.o src/zlmdb/_lmdb_vendor/_lmdb_cffi*.so src/zlmdb/_lmdb_vendor/_lmdb_cffi*.pyd

# Clean test and coverage artifacts
clean-test:
    echo "==> Removing test and coverage artifacts..."
    rm -rf .coverage .coverage.* htmlcov/ .pytest_cache/ .ty/ .ruff_cache/
    rm -rf .test* 2>/dev/null || true

# -----------------------------------------------------------------------------
# -- Testing (expanded from Makefile)
# -----------------------------------------------------------------------------

# Internal helper to ensure LMDB sources are built before running tests
_prepare-lmdb-sources venv="":
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")

    # Ensure LMDB sources are built (required for CFFI compilation at import time)
    # This is especially important for editable installs where build hooks may not run
    if [ ! -d "build/lmdb-src" ]; then
        echo "==> Preparing LMDB sources..."
        ${VENV_PYTHON} build_lmdb.py
    fi

# Run quick tests with pytest
test-quick venv="": (install-tools venv) (install-dev venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running quick tests with pytest in ${VENV_NAME}..."
    # Explicitly specify test directories to avoid pytest searching .uv-cache/, .venvs/, etc.
    ${VENV_PYTHON} -m pytest -v tests/ src/zlmdb/tests/

# Run single test file
test-single venv="": (install-tools venv) (install-dev venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    clear
    echo "==> Running test_basic.py in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pytest -v -s src/zlmdb/tests/test_basic.py

# Run pmap tests
test-pmaps venv="": (install-tools venv) (install-dev venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    clear
    echo "==> Running test_pmaps.py in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pytest -v -s src/zlmdb/tests/test_pmaps.py

# Run index tests
test-indexes venv="": (install-tools venv) (install-dev venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    clear
    echo "==> Running test_pmap_indexes.py in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pytest -v -s src/zlmdb/tests/test_pmap_indexes.py

# Run select tests
test-select venv="": (install-tools venv) (install-dev venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    clear
    echo "==> Running test_select.py in ${VENV_NAME}..."
    ${VENV_PYTHON} -m pytest -v -s src/zlmdb/tests/test_select.py

# Run zdb etcd tests
test-zdb-etcd venv="": (install-tools venv) (install venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running test_zdb_etcd.py in ${VENV_NAME}..."
    ${VENV_PYTHON} tests/zdb/test_zdb_etcd.py

# Run zdb dataframe tests
test-zdb-df venv="": (install-tools venv) (install venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running test_zdb_df.py in ${VENV_NAME}..."
    ${VENV_PYTHON} tests/zdb/test_zdb_df.py

# Run zdb dynamic tests
test-zdb-dyn venv="": (install-tools venv) (install venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running test_zdb_dyn.py in ${VENV_NAME}..."
    ${VENV_PYTHON} tests/zdb/test_zdb_dyn.py

# Run zdb flatbuffers tests
test-zdb-fbs venv="": (install-tools venv) (install venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Running test_zdb_fbs.py in ${VENV_NAME}..."
    ${VENV_PYTHON} tests/zdb/test_zdb_fbs.py

# Run all zdb tests
test-zdb venv="": (test-zdb-etcd venv) (test-zdb-df venv) (test-zdb-dyn venv) (test-zdb-fbs venv)

# Generate code coverage report
check-coverage venv="": (install-tools venv) (install-dev venv) (_prepare-lmdb-sources venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
    echo "==> Generating coverage report in ${VENV_NAME}..."
    ${VENV_PYTHON} -m coverage run --source src/zlmdb --omit="src/zlmdb/flatbuffers/reflection/*,src/zlmdb/tests/*,src/zlmdb/_flatbuffers_vendor/*,src/zlmdb/_lmdb_vendor/*" -m pytest -v -s src/zlmdb
    ${VENV_PYTHON} -m coverage report -m
    ${VENV_PYTHON} -m coverage html
    echo "==> Opening coverage report..."
    xdg-open htmlcov/index.html 2>/dev/null || open htmlcov/index.html 2>/dev/null || echo "Please open htmlcov/index.html manually"

# Alias for check-coverage (backward compatibility)
coverage venv="": (check-coverage venv)

# -----------------------------------------------------------------------------
# -- Code Quality
# -----------------------------------------------------------------------------

# Auto-format code with Ruff (modifies files in-place!)
fix-format venv="": (install-tools venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    echo "==> Auto-formatting code with ${VENV_NAME}..."

    # 1. Run the FORMATTER first. This will handle line lengths, quotes, etc.
    "${VENV_PATH}/bin/ruff" format --exclude ./tests ./src/zlmdb

    # 2. Run the LINTER'S FIXER second. This will handle things like
    #    removing unused imports, sorting __all__, etc.
    "${VENV_PATH}/bin/ruff" check --fix --exclude ./tests ./src/zlmdb
    echo "--> Formatting complete."

# Alias for fix-format (backward compatibility)
autoformat venv="": (fix-format venv)

# Check code formatting with Ruff (dry run)
check-format venv="": (install-tools venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    echo "==> Checking code formatting with ${VENV_NAME}..."
    "${VENV_PATH}/bin/ruff" check --exclude ./deps/flatbuffers .

# Run static type checking with ty (Astral's Rust-based type checker)
# FIXME: Many type errors need to be fixed. For now, we ignore most rules
# to get CI passing. Create follow-up issue to address type errors.
check-typing venv="": (install-tools venv) (install-dev venv)
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        VENV_NAME=$(just --quiet _get-system-venv-name)
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
    echo "==> Running static type checks with ${VENV_NAME}..."
    # Only check core zlmdb package, exclude tests and vendored packages
    "${VENV_PATH}/bin/ty" check \
        --python "${VENV_PATH}/bin/python" \
        --ignore unresolved-import \
        --ignore unresolved-attribute \
        --ignore unresolved-reference \
        --ignore unresolved-global \
        --ignore possibly-missing-attribute \
        --ignore possibly-missing-import \
        --ignore call-non-callable \
        --ignore invalid-assignment \
        --ignore invalid-argument-type \
        --ignore invalid-return-type \
        --ignore invalid-method-override \
        --ignore invalid-type-form \
        --ignore invalid-declaration \
        --ignore unsupported-operator \
        --ignore too-many-positional-arguments \
        --ignore unknown-argument \
        --ignore missing-argument \
        --ignore not-subscriptable \
        --ignore not-iterable \
        --ignore no-matching-overload \
        --ignore conflicting-declarations \
        --ignore deprecated \
        --ignore unused-type-ignore-comment \
        --ignore possibly-missing-submodule \
        src/zlmdb/

# Run all checks in single environment (usage: `just check cpy314`)
check venv="": (check-format venv) (check-typing venv)

# -----------------------------------------------------------------------------
# -- Publishing
# -----------------------------------------------------------------------------

# Build both source distribution and wheel
dist venv="": clean-build (build venv) (build-sourcedist venv)
    #!/usr/bin/env bash
    echo "==> Listing distribution files..."
    ls -lh dist/
    echo ""
    echo "==> Contents of wheel:"
    unzip -l dist/zlmdb-*-py*.whl || echo "Wheel not found"

# Publish package to PyPI and Read the Docs (meta-recipe)
publish venv="" tag="": (publish-pypi venv tag) (publish-rtd tag)
    #!/usr/bin/env bash
    set -e
    TAG="{{ tag }}"
    if [ -z "${TAG}" ]; then
        TAG=$(git describe --tags --abbrev=0)
    fi
    echo ""
    echo "════════════════════════════════════════════════════════════"
    echo "✅ Successfully published version ${TAG}"
    echo "════════════════════════════════════════════════════════════"
    echo ""
    echo "📦 PyPI: https://pypi.org/project/zlmdb/${TAG#v}/"
    echo "📚 RTD:  https://zlmdb.readthedocs.io/en/${TAG}/"
    echo ""

# Download GitHub release artifacts (usage: `just download-github-release` for nightly, or `just download-github-release stable`)
# Downloads wheels, sdist, FlatBuffers schemas, and verifies checksums
# This is the unified download recipe for both docs integration and release notes generation
download-github-release release_type="nightly":
    #!/usr/bin/env bash
    set -euo pipefail

    RELEASE_TYPE="{{ release_type }}"
    REPO="crossbario/zlmdb"

    echo ""
    echo "════════════════════════════════════════════════════════════"
    echo "  Downloading GitHub Release Artifacts"
    echo "════════════════════════════════════════════════════════════"
    echo ""
    echo "Release type: ${RELEASE_TYPE}"
    echo ""

    # Check if gh is available and authenticated
    if ! command -v gh &> /dev/null; then
        echo "❌ ERROR: GitHub CLI (gh) is not installed"
        echo "   Install: https://cli.github.com/"
        exit 1
    fi

    if ! gh auth status &> /dev/null; then
        echo "❌ ERROR: GitHub CLI is not authenticated"
        echo "   Run: gh auth login"
        exit 1
    fi

    # Determine which release tag to download
    case "${RELEASE_TYPE}" in
        nightly)
            echo "==> Looking for nightly release..."
            RELEASE_TAG=$(gh release list --repo "${REPO}" --limit 20 | grep -E "^master-" | head -1 | awk '{print $1}') || true
            if [ -z "${RELEASE_TAG}" ]; then
                echo "❌ ERROR: No nightly (master-*) release found"
                echo "Available releases:"
                gh release list --repo "${REPO}" --limit 10
                exit 1
            fi
            ;;
        stable)
            echo "==> Looking for stable release..."
            RELEASE_TAG=$(gh release list --repo "${REPO}" --limit 20 | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+" | head -1 | awk '{print $1}') || true
            if [ -z "${RELEASE_TAG}" ]; then
                echo "❌ ERROR: No stable (v*) release found"
                echo "Available releases:"
                gh release list --repo "${REPO}" --limit 10
                exit 1
            fi
            ;;
        *)
            # Assume it's a specific tag name
            RELEASE_TAG="${RELEASE_TYPE}"
            ;;
    esac

    echo "✅ Found release: ${RELEASE_TAG}"
    echo ""

    # Destination directory - compatible with generate-release-notes
    DEST_DIR="/tmp/release-artifacts/${RELEASE_TAG}"

    # Create/clean destination directory
    if [ -d "${DEST_DIR}" ]; then
        echo "==> Cleaning existing directory: ${DEST_DIR}"
        rm -rf "${DEST_DIR}"
    fi
    mkdir -p "${DEST_DIR}"

    # Download all release assets
    echo "==> Downloading all release assets to: ${DEST_DIR}"
    echo ""
    cd "${DEST_DIR}"

    gh release download "${RELEASE_TAG}" \
        --repo "${REPO}" \
        --pattern "*" \
        --clobber

    echo ""
    echo "==> Downloaded assets:"
    ls -la

    # Count different types of files
    WHEEL_COUNT=$(ls -1 *.whl 2>/dev/null | wc -l || echo "0")
    TARBALL_COUNT=$(ls -1 *.tar.gz 2>/dev/null | wc -l || echo "0")
    CHECKSUM_COUNT=$(ls -1 *CHECKSUMS* 2>/dev/null | wc -l || echo "0")

    echo ""
    echo "==> Asset summary:"
    echo "    Wheels:     ${WHEEL_COUNT}"
    echo "    Tarballs:   ${TARBALL_COUNT}"
    echo "    Checksums:  ${CHECKSUM_COUNT}"

    # Verify checksums if available
    if [ -f "CHECKSUMS.sha256" ]; then
        echo ""
        echo "==> Verifying checksums..."
        VERIFIED=0
        FAILED=0
        while IFS= read -r line; do
            [ -z "$line" ] && continue
            FILE_PATH=$(echo "$line" | sed -E 's/^SHA2?-?256\(([^)]+)\)=.*/\1/')
            EXPECTED_CHECKSUM=$(echo "$line" | awk -F'= ' '{print $2}')
            FILE_PATH="${FILE_PATH#./}"
            if [ -f "$FILE_PATH" ]; then
                ACTUAL_CHECKSUM=$(openssl sha256 "$FILE_PATH" | awk '{print $2}')
                if [ "$ACTUAL_CHECKSUM" = "$EXPECTED_CHECKSUM" ]; then
                    VERIFIED=$((VERIFIED + 1))
                else
                    echo "    ❌ MISMATCH: $FILE_PATH"
                    FAILED=$((FAILED + 1))
                fi
            fi
        done < CHECKSUMS.sha256
        if [ $FAILED -gt 0 ]; then
            echo "    ERROR: ${FAILED} file(s) failed verification!"
            exit 1
        else
            echo "    ✅ ${VERIFIED} file(s) verified successfully"
        fi
    fi

    # Extract FlatBuffers schema tarball if present
    if ls flatbuffers-schema*.tar.gz 1> /dev/null 2>&1; then
        echo ""
        echo "==> Extracting FlatBuffers schemas..."
        mkdir -p flatbuffers
        tar -xzf flatbuffers-schema*.tar.gz -C flatbuffers --strip-components=1 2>/dev/null || tar -xzf flatbuffers-schema*.tar.gz -C flatbuffers
        FBS_COUNT=$(find flatbuffers -name "*.fbs" -type f 2>/dev/null | wc -l)
        BFBS_COUNT=$(find flatbuffers -name "*.bfbs" -type f 2>/dev/null | wc -l)
        echo "    ✅ Extracted ${FBS_COUNT} .fbs files, ${BFBS_COUNT} .bfbs files"
    fi

    echo ""
    echo "════════════════════════════════════════════════════════════"
    echo "✅ Download Complete"
    echo "════════════════════════════════════════════════════════════"
    echo ""
    echo "Artifacts location: ${DEST_DIR}"
    echo ""
    echo "Next steps:"
    echo "  1. Build docs:            just docs"
    echo "  2. Integrate artifacts:   just docs-integrate-github-release ${RELEASE_TAG}"
    echo "  3. Generate release notes: just generate-release-notes <version> ${RELEASE_TAG}"
    echo ""

# Download release artifacts from GitHub and publish to PyPI
publish-pypi venv="" tag="":
    #!/usr/bin/env bash
    set -e
    VENV_NAME="{{ venv }}"
    if [ -z "${VENV_NAME}" ]; then
        echo "==> No venv name specified. Auto-detecting from system Python..."
        VENV_NAME=$(just --quiet _get-system-venv-name)
        echo "==> Defaulting to venv: '${VENV_NAME}'"
    fi
    VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"

    # Determine which tag to use
    TAG="{{ tag }}"
    if [ -z "${TAG}" ]; then
        echo "==> No tag specified. Using latest git tag..."
        TAG=$(git describe --tags --abbrev=0)
        echo "==> Using tag: ${TAG}"
    fi

    # Verify tag looks like a version tag
    if [[ ! "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
        echo "❌ Error: Tag '${TAG}' doesn't look like a version tag (expected format: vX.Y.Z)"
        exit 1
    fi

    # Create temp directory for downloads
    TEMP_DIR=$(mktemp -d)
    echo "==> Downloading release artifacts from GitHub release ${TAG}..."
    echo "    Temp directory: ${TEMP_DIR}"

    # Download all release assets
    gh release download "${TAG}" --repo crossbario/zlmdb --dir "${TEMP_DIR}"

    echo ""
    echo "==> Downloaded files:"
    ls -lh "${TEMP_DIR}"
    echo ""

    # Count wheels and source distributions
    WHEEL_COUNT=$(find "${TEMP_DIR}" -name "*.whl" | wc -l)
    SDIST_COUNT=$(find "${TEMP_DIR}" -name "*.tar.gz" | wc -l)

    echo "Found ${WHEEL_COUNT} wheel(s) and ${SDIST_COUNT} source distribution(s)"

    if [ "${WHEEL_COUNT}" -eq 0 ] || [ "${SDIST_COUNT}" -eq 0 ]; then
        echo "❌ Error: Expected at least 1 wheel and 1 source distribution"
        echo "    Wheels found: ${WHEEL_COUNT}"
        echo "    Source dist found: ${SDIST_COUNT}"
        rm -rf "${TEMP_DIR}"
        exit 1
    fi

    # Ensure twine is installed
    if [ ! -f "${VENV_PATH}/bin/twine" ]; then
        echo "==> Installing twine in ${VENV_NAME}..."
        "${VENV_PATH}/bin/pip" install twine
    fi

    echo "==> Publishing to PyPI using twine..."
    # Use explicit patterns to avoid uploading metadata files (build-info.txt, CHECKSUMS.sha256, etc.)
    "${VENV_PATH}/bin/twine" upload "${TEMP_DIR}"/*.whl "${TEMP_DIR}"/*.tar.gz

    # Cleanup
    rm -rf "${TEMP_DIR}"
    echo "✅ Successfully published ${TAG} to PyPI"

# Trigger Read the Docs build for a specific tag
publish-rtd tag="":
    #!/usr/bin/env bash
    set -e

    # Determine which tag to use
    TAG="{{ tag }}"
    if [ -z "${TAG}" ]; then
        echo "==> No tag specified. Using latest git tag..."
        TAG=$(git describe --tags --abbrev=0)
        echo "==> Using tag: ${TAG}"
    fi

    # Verify tag looks like a version tag
    if [[ ! "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
        echo "❌ Error: Tag '${TAG}' doesn't look like a version tag (expected format: vX.Y.Z)"
        exit 1
    fi

    # Check if RTD_TOKEN is set
    if [ -z "${RTD_TOKEN}" ]; then
        echo "❌ Error: RTD_TOKEN environment variable is not set"
        echo ""
        echo "To trigger RTD builds, you need to:"
        echo "1. Get an API token from https://readthedocs.org/accounts/tokens/"
        echo "2. Export it: export RTD_TOKEN=your_token_here"
        echo ""
        exit 1
    fi

    echo "==> Triggering Read the Docs build for ${TAG}..."
    echo ""

    # Trigger build via RTD API
    # See: https://docs.readthedocs.io/en/stable/api/v3.html#post--api-v3-projects-(string-project_slug)-versions-(string-version_slug)-builds-
    RTD_PROJECT="zlmdb"
    RTD_API_URL="https://readthedocs.org/api/v3/projects/${RTD_PROJECT}/versions/${TAG}/builds/"

    echo "==> Calling RTD API..."
    echo "    Project: ${RTD_PROJECT}"
    echo "    Version: ${TAG}"
    echo "    URL: ${RTD_API_URL}"
    echo ""

    # Trigger the build
    HTTP_CODE=$(curl -X POST \
        -H "Authorization: Token ${RTD_TOKEN}" \
        -w "%{http_code}" \
        -s -o /tmp/rtd_response.json \
        "${RTD_API_URL}")

    echo "==> API Response (HTTP ${HTTP_CODE}):"
    cat /tmp/rtd_response.json | python3 -m json.tool 2>/dev/null || cat /tmp/rtd_response.json
    echo ""

    if [ "${HTTP_CODE}" = "202" ] || [ "${HTTP_CODE}" = "201" ]; then
        echo "✅ Read the Docs build triggered successfully!"
        echo ""
        echo "Check build status at:"
        echo "  https://readthedocs.org/projects/${RTD_PROJECT}/builds/"
        echo ""
        echo "Documentation will be available at:"
        echo "  https://${RTD_PROJECT}.readthedocs.io/en/${TAG}/"
        echo "  https://${RTD_PROJECT}.readthedocs.io/en/stable/ (if marked as stable)"
        echo ""
    else
        echo "❌ Error: Failed to trigger RTD build (HTTP ${HTTP_CODE})"
        echo ""
        echo "Common issues:"
        echo "- Invalid RTD_TOKEN"
        echo "- Version/tag doesn't exist in RTD project"
        echo "- Network/API connectivity problems"
        echo ""
        exit 1
    fi

    rm -f /tmp/rtd_response.json

# -----------------------------------------------------------------------------
# -- Utilities
# -----------------------------------------------------------------------------

# Bump vendored flatbuffers to latest release tag
bump-flatbuffers:
    #!/usr/bin/env bash
    set -e
    echo "==> Fetching latest tags from upstream..."
    cd deps/flatbuffers && git fetch --tags
    LATEST_TAG=$(cd deps/flatbuffers && git describe --tags --abbrev=0 $(git rev-list --tags --max-count=1))
    echo "==> Latest release tag: ${LATEST_TAG}"
    cd deps/flatbuffers && git checkout "${LATEST_TAG}"
    echo "==> Submodule now at: $(cd deps/flatbuffers && git describe --tags --always)"
    echo ""
    echo "Next steps:"
    echo "  1. just update-flatbuffers"
    echo "  2. git add deps/flatbuffers src/zlmdb/flatbuffers"
    echo "  3. git commit -m 'Bump vendored flatbuffers to ${LATEST_TAG}'"

# Update vendored flatbuffers runtime from deps/flatbuffers submodule
update-flatbuffers:
    echo "==> Updating vendored flatbuffers from submodule..."
    rm -rf ./src/zlmdb/flatbuffers
    cp -R deps/flatbuffers/python/flatbuffers ./src/zlmdb/flatbuffers
    echo "✓ Flatbuffers vendor updated in src/zlmdb/flatbuffers"

# Generate flatbuffers reflection: the binary schema (reflection.bfbs) AND the
# Python wrappers (reflection/*.py), using a host flatc built from the vendored
# deps/flatbuffers (version-matched, self-contained -- no system flatc needed).
#
# reflection.bfbs is committed (source-of-truth) and shipped in the sdist+wheel,
# so the package build never has to execute flatc. This is what makes
# cross-compilation (e.g. Buildroot/aarch64) work -- see issue #107. Run this on
# the host whenever deps/flatbuffers is bumped, then commit the results.
generate-flatbuffers-reflection: && fix-flatbuffers-reflection-imports
    #!/usr/bin/env bash
    set -e
    FBS_DIR="deps/flatbuffers"
    BUILD_DIR="${FBS_DIR}/build"
    FLATC="${BUILD_DIR}/flatc"
    OUT_DIR="src/zlmdb/flatbuffers"
    REFLECTION_FBS="${FBS_DIR}/reflection/reflection.fbs"

    if [ ! -f "${REFLECTION_FBS}" ]; then
        echo "ERROR: ${REFLECTION_FBS} not found (init the deps/flatbuffers submodule?)"
        exit 1
    fi

    # Build a host flatc from the vendored flatbuffers if we don't have one yet.
    # (Delete deps/flatbuffers/build to force a rebuild after a submodule bump.)
    if [ ! -x "${FLATC}" ]; then
        echo "==> Building host flatc from ${FBS_DIR}..."
        mkdir -p "${BUILD_DIR}"
        ( cd "${BUILD_DIR}" && \
          cmake .. -DCMAKE_BUILD_TYPE=Release \
                   -DFLATBUFFERS_BUILD_TESTS=OFF \
                   -DFLATBUFFERS_BUILD_FLATLIB=OFF \
                   -DFLATBUFFERS_BUILD_FLATHASH=OFF \
                   -DFLATBUFFERS_BUILD_GRPCTEST=OFF \
                   -DFLATBUFFERS_BUILD_SHAREDLIB=OFF >/dev/null && \
          cmake --build . --config Release --target flatc >/dev/null )
    fi
    echo "==> Using flatc: $(${FLATC} --version)"

    # 1) Binary reflection schema (committed; shipped as package data).
    echo "==> Generating reflection.bfbs..."
    "${FLATC}" --binary --schema --bfbs-comments --bfbs-builtins -o "${OUT_DIR}" "${REFLECTION_FBS}"

    # 2) Python reflection wrappers.
    echo "==> Generating reflection Python code..."
    "${FLATC}" --python -o "${OUT_DIR}" "${REFLECTION_FBS}"

    echo "✓ Flatbuffers reflection generated (reflection.bfbs + reflection/*.py)"

# Fix absolute imports in generated flatbuffers reflection code
# The flatc compiler generates absolute imports like 'from reflection.Type import Type'
# but when vendored inside zlmdb, these must be relative imports 'from .Type import Type'
# See: https://github.com/crossbario/zlmdb/issues/102
fix-flatbuffers-reflection-imports:
    #!/usr/bin/env bash
    set -e
    REFLECTION_DIR="src/zlmdb/flatbuffers/reflection"

    if [ ! -d "${REFLECTION_DIR}" ]; then
        echo "ERROR: Reflection directory not found at ${REFLECTION_DIR}"
        exit 1
    fi

    echo "==> Fixing absolute imports in flatbuffers reflection code..."

    # Count files that need fixing
    FILES_WITH_ABSOLUTE=$(grep -l "from reflection\." "${REFLECTION_DIR}"/*.py 2>/dev/null | wc -l)

    if [ "${FILES_WITH_ABSOLUTE}" -eq 0 ]; then
        echo "✓ No absolute imports found (already fixed or not present)"
        exit 0
    fi

    echo "   Found ${FILES_WITH_ABSOLUTE} files with absolute imports"

    # Fix all occurrences of 'from reflection.X import' to 'from .X import'
    for pyfile in "${REFLECTION_DIR}"/*.py; do
        if grep -q "from reflection\." "$pyfile" 2>/dev/null; then
            sed -i 's/from reflection\./from ./g' "$pyfile"
            echo "   Fixed: $(basename $pyfile)"
        fi
    done

    # Verify fix
    REMAINING=$(grep -l "from reflection\." "${REFLECTION_DIR}"/*.py 2>/dev/null | wc -l)
    if [ "${REMAINING}" -gt 0 ]; then
        echo "ERROR: ${REMAINING} files still have absolute imports!"
        exit 1
    fi

    echo "✓ Flatbuffers reflection imports fixed (absolute -> relative)"

# Fix copyright headers (typedef int GmbH)
fix-copyright:
    echo "==> Fixing copyright headers..."
    find . -type f -exec sed -i 's/Copyright (c) Crossbar.io Technologies GmbH/Copyright (c) typedef int GmbH/g' {} \;
    echo "✓ Copyright headers updated"


# -----------------------------------------------------------------------------
# -- Release workflow recipes
# -----------------------------------------------------------------------------

# Generate changelog entry from git history for a given version
prepare-changelog version:
    .cicd/scripts/prepare-changelog.sh "{{ version }}" "crossbario/zlmdb"

# Generate release notes entry from downloaded artifacts
# Usage: just generate-release-notes 25.12.1 master-202512092131
# Requires: artifacts downloaded via `just download-github-release`
generate-release-notes version release_name:
    .cicd/scripts/generate-release-notes.sh "{{ version }}" "{{ release_name }}" "crossbario/zlmdb"

# Validate release is ready: checks changelog, releases, version
draft-release version:
    #!/usr/bin/env bash
    set -e
    VERSION="{{ version }}"

    echo ""
    echo "=========================================="
    echo " Validating release ${VERSION}"
    echo "=========================================="
    echo ""

    ERRORS=0

    # Check pyproject.toml version
    PYPROJECT_VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*= *"\(.*\)"/\1/')
    if [ "${PYPROJECT_VERSION}" = "${VERSION}" ]; then
        echo "✅ pyproject.toml version matches: ${VERSION}"
    else
        echo "❌ pyproject.toml version mismatch: ${PYPROJECT_VERSION} != ${VERSION}"
        ERRORS=$((ERRORS + 1))
    fi

    # Check changelog entry
    if grep -q "^${VERSION}$" docs/changelog.rst; then
        echo "✅ Changelog entry exists for ${VERSION}"
    else
        echo "❌ Changelog entry missing for ${VERSION}"
        ERRORS=$((ERRORS + 1))
    fi

    # Check releases entry
    if grep -q "^${VERSION}$" docs/releases.rst; then
        echo "✅ Releases entry exists for ${VERSION}"
    else
        echo "❌ Releases entry missing for ${VERSION}"
        ERRORS=$((ERRORS + 1))
    fi

    echo ""
    if [ ${ERRORS} -gt 0 ]; then
        echo "=========================================="
        echo " ❌ Validation failed with ${ERRORS} error(s)"
        echo "=========================================="
        exit 1
    else
        echo "=========================================="
        echo " ✅ All checks passed for ${VERSION}"
        echo "=========================================="
    fi

# Full release preparation: validate + test + build docs
prepare-release version venv="":
    #!/usr/bin/env bash
    set -e
    VERSION="{{ version }}"
    VENV="{{ venv }}"

    echo ""
    echo "=========================================="
    echo " Preparing release ${VERSION}"
    echo "=========================================="
    echo ""

    # Run draft-release validation first
    just draft-release "${VERSION}"

    echo ""
    echo "==> Running tests..."
    if [ -n "${VENV}" ]; then
        just test "${VENV}"
    else
        just test
    fi

    echo ""
    echo "==> Building documentation..."
    just docs

    echo ""
    echo "=========================================="
    echo " ✅ Release ${VERSION} is ready"
    echo "=========================================="
    echo ""
    echo "Next steps:"
    echo "  1. git add docs/changelog.rst docs/releases.rst pyproject.toml"
    echo "  2. git commit -m \"Release ${VERSION}\""
    echo "  3. git tag v${VERSION}"
    echo "  4. git push && git push --tags"
    echo ""