justfile

uv := require("uv")

project_dir := justfile_directory()
src_dir := project_dir / "dqlitepy"
tests_dir := project_dir / "tests"

export PY_COLORS := "1"
export PYTHONBREAKPOINT := "pdb.set_trace"
export PYTHONPATH := project_dir / "dqlitepy"

uv_run := "uv run --frozen"

[private]
default:
    @just help

# Regenerate uv.lock
[group("dev")]
lock:
    uv lock

# Create a development environment
[group("dev")]
env: lock
    uv sync --extra dev

# Upgrade uv.lock with the latest dependencies
[group("dev")]
upgrade:
    uv lock --upgrade

# Apply coding style standards to code
[group("lint")]
fmt: lock
    {{uv_run}} ruff format {{src_dir}} {{tests_dir}}
    {{uv_run}} ruff check --fix {{src_dir}} {{tests_dir}}

# Check code against coding style standards
[group("lint")]
lint: lock
    {{uv_run}} codespell {{src_dir}}
    {{uv_run}} ruff check {{src_dir}}

# Run static type checker on code
[group("lint")]
typecheck: lock
    {{uv_run}} pyright

# Build vendored raft and dqlite libraries (for local development)
[group("dev")]
build-vendor:
    bash scripts/build_vendor_libs.sh

# Build the native Go library locally (requires build-vendor to be run first)
[group("dev")]
build-lib-local: lock build-vendor
    {{uv_run}} python scripts/build_go_lib.py -v

# Build the native Go library using Docker (proper/recommended way)
[group("dev")]
build-lib:
    #!/usr/bin/env bash
    set -e
    echo "==> Building native library using Docker"
    docker build --target go-build --tag dqlitepy-lib-builder .
    docker create --name dqlitepy-lib-extract dqlitepy-lib-builder
    docker cp dqlitepy-lib-extract:/build/dqlitepy/_lib/. ./dqlitepy/_lib/
    docker rm dqlitepy-lib-extract
    echo "==> Library extracted to dqlitepy/_lib/"
    ls -lh dqlitepy/_lib/linux-amd64/

# Run unit tests with coverage (59% threshold)
# Note: Coverage is limited by untested modules (sqlalchemy=0%, client=27%)
# and upstream segfault preventing full node lifecycle testing
[group("test")]
unit: lock build-lib
    {{uv_run}} pytest {{tests_dir}} --cov={{src_dir}} --cov-report=term-missing --cov-fail-under=59

# Install Docusaurus dependencies
[group("docusaurus")]
docs-install:
    @echo "📦 Installing Docusaurus dependencies..."
    cd docusaurus && yarn install

# Start Docusaurus development server
[group("docusaurus")]
docs-dev: docs-install
    @echo "🚀 Starting Docusaurus development server..."
    cd docusaurus && yarn start

# Start Docusaurus development server on specific port
[group("docusaurus")]
docs-dev-port port="3000": docs-install
    @echo "🚀 Starting Docusaurus development server on port {{port}}..."
    cd docusaurus && yarn start --port {{port}}

# Build Docusaurus for production
[group("docusaurus")]
docs-build: docs-install
    @echo "🏗️ Generating API documentation from source..."
    {{uv_run}} python3 ./docusaurus/scripts/generate-api-docs.py
    @echo "🏗️ Building Docusaurus for production..."
    cd docusaurus && yarn build

# Generate API documentation from SDK source code
[group("docusaurus")]
docs-generate-api:
    @echo "📝 Generating API documentation from source..."
    {{uv_run}} python3 ./docusaurus/scripts/generate-api-docs.py

# Serve built Docusaurus site locally
[group("docusaurus")]
docs-serve: docs-build
    @echo "🌐 Serving built Docusaurus site..."
    cd docusaurus && yarn serve

# Clean Docusaurus build artifacts
[group("docusaurus")]
docs-clean:
    @echo "🧹 Cleaning Docusaurus build artifacts..."
    cd docusaurus && rm -rf build .docusaurus

# Show available documentation commands
[group("docusaurus")]
docs-help:
    @echo "📚 Docusaurus Commands:"
    @echo "  docs-install        - Install dependencies"
    @echo "  docs-dev            - Start development server"
    @echo "  docs-dev-port       - Start dev server on specific port"
    @echo "  docs-build          - Build for production (includes API docs generation)"
    @echo "  docs-generate-api   - Generate API docs from SDK source"
    @echo "  docs-serve          - Serve built site"
    @echo "  docs-clean          - Clean build artifacts"

# Build dqlitepy wheel using Docker
build-wheel:
    ./scripts/build_wheel_docker.sh

# Run FastAPI example cluster with Docker Compose
run-fast-api-example:
    docker compose -f examples/fast_api_example/docker-compose.yml up

# Run FastAPI example cluster in detached mode
run-fast-api-example-d:
    docker compose -f examples/fast_api_example/docker-compose.yml up -d

# Stop FastAPI example cluster
stop-fast-api-example:
    docker compose -f examples/fast_api_example/docker-compose.yml down

# Stop FastAPI example and clean volumes
clean-fast-api-example:
    docker compose -f examples/fast_api_example/docker-compose.yml down -v

# View FastAPI example logs
logs-fast-api-example:
    docker compose -f examples/fast_api_example/docker-compose.yml logs -f

# Rebuild and restart FastAPI example
rebuild-fast-api-example:
    docker compose -f examples/fast_api_example/docker-compose.yml down
    docker compose -f examples/fast_api_example/docker-compose.yml up --build