justfile

# Alchemist — Justfile
# https://github.com/casey/just
#
# Install: cargo install just  |  brew install just  |  pacman -S just

set shell := ["bash", "-euo", "pipefail", "-c"]
set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]

# ─────────────────────────────────────────
# Variables
# ─────────────────────────────────────────

VERSION := if os_family() == "windows" {
  `(Get-Content VERSION -Raw).Trim()`
} else {
  `tr -d '[:space:]' < VERSION`
}

# ─────────────────────────────────────────
# Default — list all recipes
# ─────────────────────────────────────────

[private]
default:
    @just --list

# ─────────────────────────────────────────
# DEVELOPMENT
# ─────────────────────────────────────────

# Install repo dependencies needed for local development
install:
    @just {{ if os_family() == "windows" { "install-w" } else { "install-u" } }}

[private]
install-u:
    @command -v cargo >/dev/null || { echo "error: cargo is required"; exit 1; }
    @command -v bun >/dev/null || { echo "error: bun is required"; exit 1; }
    @if [ "$(uname -s)" = "Darwin" ] && ! command -v swift >/dev/null; then \
        echo "warning: swift is not installed; native/mac recipes will not run"; \
    fi
    @if ! command -v dotnet >/dev/null; then \
        echo "warning: dotnet (.NET 9 SDK) is not installed; Jellyfin plugin recipes will not run"; \
        echo "  macOS: brew install --cask dotnet-sdk"; \
        echo "  Linux: https://learn.microsoft.com/dotnet/core/install/linux"; \
    fi
    @echo "── Rust dependencies ──"
    cargo fetch --locked
    @echo "── Web dependencies ──"
    cd web && bun install --frozen-lockfile
    @echo "── E2E dependencies ──"
    cd web-e2e && bun install --frozen-lockfile && bunx playwright install chromium
    @if ! command -v ffmpeg >/dev/null; then \
        echo "warning: ffmpeg is not installed; media integration tests will not run"; \
    fi
    @echo "Repo ready for development."
    @echo "Next: just dev"

install-w:
    @powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\\scripts\\install_dev_windows.ps1

# Build frontend assets, then start the backend server
dev:
    @just {{ if os_family() == "windows" { "dev-w" } else { "dev-u" } }}

[private]
dev-u: web-build
    @just run

dev-w:
    @powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\\scripts\\dev_windows.ps1

# Start the backend only
run:
    cargo run

# Start the backend with release profile and frontend build
perform:
    cd web && bun run build
    cargo run --release

# Start frontend dev server only
web:
    cd web && bun install --frozen-lockfile && bun run dev

# Validate the authoritative documentation source
docs:
    python3 scripts/check_docs.py
    @echo "Preview the generated site from the Dead Signal Works website repository."

# ─────────────────────────────────────────
# BUILD
# ─────────────────────────────────────────

# Full production build — frontend first, then Rust
build:
    @echo "Building frontend..."
    cd web && bun install --frozen-lockfile && bun run build
    @echo "Building Rust binary..."
    cargo build --release
    @echo "Building native macOS client when available..."
    @if [ "$(uname -s)" = "Darwin" ] && command -v swift >/dev/null; then \
        just mac-build; \
    else \
        echo "Skipping native macOS client build (requires macOS + Swift)."; \
    fi
    @echo "Done → target/release/alchemist"

# Build frontend assets only
web-build:
    cd web && bun install --frozen-lockfile && bun run build

# Build Rust only (assumes web/dist already exists)
rust-build:
    cargo build --release

# ─────────────────────────────────────────
# NATIVE MAC CLIENT
# ─────────────────────────────────────────

# Build the native macOS SwiftUI prototype
mac-build:
    cd native/mac && swift build

# Run native macOS Swift tests
mac-test:
    cd native/mac && swift run AlchemistMacChecks

# Check native macOS Swift package
mac-check:
    cd native/mac && swift run AlchemistMacChecks && swift build

# Stage the Rust daemon for bundled native macOS development
mac-stage-daemon: web-build rust-build
    mkdir -p native/mac/.artifacts
    cp target/release/alchemist native/mac/.artifacts/alchemistd
    chmod +x native/mac/.artifacts/alchemistd
    @echo "Staged native/mac/.artifacts/alchemistd"

# Run the native macOS app against whatever API URL is configured in-app
mac-run:
    cd native/mac && swift run AlchemistMac

# Build/stage the Rust daemon, then run the native macOS app in bundled mode
mac-run-bundled: mac-stage-daemon
    cd native/mac && ALCHEMIST_DAEMON_PATH="$(pwd)/.artifacts/alchemistd" swift run AlchemistMac

# Build the whole project plus the staged native daemon
mac-build-full: build mac-stage-daemon

# ─────────────────────────────────────────
# JELLYFIN PLUGIN
# ─────────────────────────────────────────

# Build the Jellyfin plugin (requires .NET 9 SDK)
jellyfin-build:
    dotnet build integrations/jellyfin/Alchemist.Jellyfin/Alchemist.Jellyfin.csproj

# Run Jellyfin plugin tests
jellyfin-test:
    dotnet test integrations/jellyfin/Alchemist.Jellyfin.Tests/Alchemist.Jellyfin.Tests.csproj

# Build + test the Jellyfin plugin
jellyfin-check: jellyfin-build jellyfin-test

# Build the Jellyfin plugin release zip and checksum assets
jellyfin-package: jellyfin-check
    python3 scripts/package_jellyfin_plugin.py --output-dir dist/jellyfin

# ─────────────────────────────────────────
# CHECKS — mirrors CI exactly
# ─────────────────────────────────────────

# Run all checks (fmt + clippy + typecheck + frontend build)
check:
    @just {{ if os_family() == "windows" { "check-w" } else { "check-u" } }}

[private]
check-u:
    @echo "── Rust format ──"
    cargo fmt --all -- --check
    @echo "── Rust clippy ──"
    cargo clippy --all-targets --all-features -- -D warnings -D clippy::unwrap_used -D clippy::expect_used
    @echo "── Rust check ──"
    cargo check --all-targets
    @echo "── API contract ──"
    python3 scripts/check_api_contract.py
    @echo "── Docker runtime contract ──"
    python3 scripts/check_docker_runtime_contract.py
    @echo "── Frontend typecheck ──"
    cd web && bun install --frozen-lockfile && bun run typecheck && echo "── Frontend build ──" && bun run build
    @if [ "$(uname -s)" = "Darwin" ] && command -v swift >/dev/null; then \
        echo "── Native macOS check ──"; \
        just mac-check; \
    else \
        echo "── Native macOS check skipped (requires macOS + Swift) ──"; \
    fi
    @echo "All checks passed ✓"

check-w:
    @powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\\scripts\\check_windows.ps1

# Rust checks only (faster)
check-rust:
    cargo fmt --all -- --check
    cargo clippy --all-targets --all-features -- -D warnings -D clippy::unwrap_used -D clippy::expect_used
    cargo check --all-targets

# Frontend checks only
check-web:
    cd web && bun install --frozen-lockfile && bun run typecheck && bun run build
    cd web-e2e && bun install --frozen-lockfile && bun run test

# Validate v1 API route coverage against the OpenAPI contract
api-contract:
    python3 scripts/check_api_contract.py

# ─────────────────────────────────────────
# TESTS
# ─────────────────────────────────────────

# Run all Rust tests
test:
    cargo test

# Run Rust tests with output shown
test-verbose:
    cargo test -- --nocapture

# Run a specific test by name (e.g. just test-filter stream_rules)
test-filter FILTER:
    cargo test {{FILTER}} -- --nocapture

# Run frontend e2e reliability tests
test-e2e:
    cd web-e2e && bun install --frozen-lockfile && bun run test:reliability

# Run all e2e tests headed (for debugging)
test-e2e-headed:
    cd web-e2e && bun install --frozen-lockfile && bun run test:headed

# Run all e2e tests with Playwright UI
test-e2e-ui:
    cd web-e2e && bun install --frozen-lockfile && bun run test:ui

# ─────────────────────────────────────────
# DATABASE
# ─────────────────────────────────────────

# Wipe the dev database (essential for re-testing the setup wizard)
db-reset:
    @DB="${ALCHEMIST_DB_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/alchemist/alchemist.db}"; \
        echo "Deleting $DB"; \
        rm -f "$DB" "$DB-wal" "$DB-shm"; \
        echo "Done — next run will re-apply migrations."

# Wipe dev database AND config (full clean slate, triggers setup wizard)
db-reset-all:
    @DB="${ALCHEMIST_DB_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/alchemist/alchemist.db}"; \
        CFG="${ALCHEMIST_CONFIG_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/alchemist/config.toml}"; \
        echo "Deleting $DB and $CFG"; \
        rm -f "$DB" "$DB-wal" "$DB-shm" "$CFG"; \
        echo "Done — setup wizard will run on next launch."

# Open the dev database in sqlite3
db-shell:
    @sqlite3 "${ALCHEMIST_DB_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/alchemist/alchemist.db}"

# Show applied migrations
db-migrations:
    @sqlite3 "${ALCHEMIST_DB_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/alchemist/alchemist.db}" \
        "SELECT version, description, installed_on FROM _sqlx_migrations ORDER BY installed_on;"

# ─────────────────────────────────────────
# DOCKER
# ─────────────────────────────────────────

# Build the Docker image locally
docker-build:
    docker build -t alchemist:dev .

# Build multi-arch image (requires buildx; add --push to push to registry)
docker-build-multi:
    docker buildx build --platform linux/amd64,linux/arm64 -t alchemist:dev .

# Validate runtime-image GPU tooling without doing a full app build.
# Override with ALCHEMIST_DOCKER_TEST_PLATFORM, ALCHEMIST_DOCKER_TEST_TARGETARCH,
# or ALCHEMIST_DOCKER_TEST_RENDER_GID when needed.
docker-runtime-contract:
    python3 scripts/check_docker_runtime_contract.py
    @IMAGE="alchemist:runtime-contract-local"; \
        PLATFORM="${ALCHEMIST_DOCKER_TEST_PLATFORM:-linux/amd64}"; \
        TARGETARCH="${ALCHEMIST_DOCKER_TEST_TARGETARCH:-amd64}"; \
        TEST_GID="${ALCHEMIST_DOCKER_TEST_RENDER_GID:-105}"; \
        TMPDIR="$(mktemp -d)"; \
        cleanup() { \
            rm -rf "$TMPDIR"; \
            docker rmi "$IMAGE" >/dev/null 2>&1 || true; \
        }; \
        trap cleanup EXIT; \
        docker version >/dev/null; \
        cp Dockerfile.runtime "$TMPDIR/Dockerfile"; \
        cp entrypoint.sh "$TMPDIR/entrypoint.sh"; \
        printf '%s\n' '#!/bin/sh' 'echo alchemist-placeholder "$@"' > "$TMPDIR/alchemist"; \
        chmod +x "$TMPDIR/alchemist"; \
        docker build --platform "$PLATFORM" --build-arg TARGETARCH="$TARGETARCH" -t "$IMAGE" "$TMPDIR"; \
        docker run --rm --platform "$PLATFORM" --entrypoint sh "$IMAGE" -c '\
            set -eu; \
            command -v vainfo; \
            command -v setpriv; \
            ffmpeg -hide_banner -encoders | grep -E "h264_vaapi|hevc_vaapi"; \
            ffmpeg -hide_banner -encoders | grep -E "h264_qsv|hevc_qsv"; \
            ffmpeg -hide_banner -encoders | grep -E "h264_nvenc|hevc_nvenc"; \
        '; \
        docker run --rm --platform "$PLATFORM" --group-add "$TEST_GID" -e PUID=1000 -e PGID=1000 --entrypoint /app/entrypoint.sh "$IMAGE" id \
            | grep -E "uid=1000.*gid=1000.*groups=.*${TEST_GID}"; \
        echo "Docker runtime contract smoke OK."

# Run Alchemist in Docker for local testing
docker-run:
    mkdir -p dev-config dev-data
    docker run --rm \
        -p 3000:3000 \
        -v "$(pwd)/dev-config:/app/config" \
        -v "$(pwd)/dev-data:/app/data" \
        -e ALCHEMIST_CONFIG_PATH=/app/config/config.toml \
        -e ALCHEMIST_DB_PATH=/app/data/alchemist.db \
        -e ALCHEMIST_CONFIG_MUTABLE=true \
        -e RUST_LOG=info \
        alchemist:dev

# Start the Docker Compose stack
docker-up:
    docker compose up -d

# Stop the Docker Compose stack
docker-down:
    docker compose down

# Tail Docker Compose logs
docker-logs:
    docker compose logs -f

# ─────────────────────────────────────────
# VERSIONING & RELEASE
# ─────────────────────────────────────────

# Bump version across repo version files only (e.g. just bump 0.3.0 or just bump 0.3.0-rc.1)
bump NEW_VERSION:
    @echo "Bumping to {{NEW_VERSION}}..."
    bash scripts/bump_version.sh {{NEW_VERSION}}

[private]
release-verify:
    @echo "── Rust format ──"
    cargo fmt --all -- --check
    @echo "── Rust clippy ──"
    cargo clippy --locked --all-targets --all-features -- -D warnings -D clippy::unwrap_used -D clippy::expect_used
    @echo "── Rust check ──"
    cargo check --locked --all-targets --all-features
    @echo "── Rust tests ──"
    cargo test --locked --all-targets -- --test-threads=4
    @echo "── Rust audit ──"
    cargo audit
    @echo "── Actionlint ──"
    actionlint .github/workflows/*.yml
    @echo "── API contract ──"
    python3 scripts/check_api_contract.py
    @echo "── Docker runtime contract ──"
    python3 scripts/check_docker_runtime_contract.py
    @echo "── Web verify ──"
    cd web && bun install --frozen-lockfile && bun run verify && python3 ../scripts/run_bun_audit.py .
    @echo "── Docs verify ──"
    python3 scripts/check_docs.py
    @echo "── E2E backend build ──"
    rm -rf target/debug/incremental
    CARGO_INCREMENTAL=0 cargo build --locked --no-default-features
    @echo "── E2E reliability ──"
    @E2E_PORT=""; \
        for port in $(seq 4173 4273); do \
            if ! lsof -nPiTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then \
                E2E_PORT="$port"; \
                break; \
            fi; \
        done; \
        if [ -z "$E2E_PORT" ]; then \
            echo "error: no free web-e2e port found in 4173-4273" >&2; \
            exit 1; \
        fi; \
        echo "Using web-e2e port ${E2E_PORT}"; \
        cd web-e2e && bun install --frozen-lockfile && ALCHEMIST_E2E_PORT="${E2E_PORT}" bun run test:reliability
    @echo "── Jellyfin plugin ──"
    @if command -v dotnet >/dev/null; then \
        just jellyfin-check; \
    else \
        echo "skipped (dotnet not installed)"; \
    fi

# Checkpoint dirty local work with confirmation, then bump, validate, commit, tag, and push
# (blocks behind/diverged remote state; e.g. just update 0.3.0-rc.1 or just update v0.3.0-rc.1)
update NEW_VERSION:
    @RAW_VERSION="{{NEW_VERSION}}"; \
    NEW_VERSION="${RAW_VERSION#v}"; \
    CURRENT_VERSION="{{VERSION}}"; \
    TAG="v${NEW_VERSION}"; \
    BRANCH="$(git branch --show-current)"; \
    if [ -z "${NEW_VERSION}" ]; then \
        echo "error: version must not be empty" >&2; \
        exit 1; \
    fi; \
    if [ "${NEW_VERSION}" = "${CURRENT_VERSION}" ]; then \
        echo "error: version ${NEW_VERSION} is already current" >&2; \
        exit 1; \
    fi; \
    if [ -z "${BRANCH}" ]; then \
        echo "error: detached HEAD is not supported for just update" >&2; \
        exit 1; \
    fi; \
    if ! git remote get-url origin >/dev/null 2>&1; then \
        echo "error: origin remote does not exist" >&2; \
        exit 1; \
    fi; \
    if [ -n "$(git status --porcelain)" ]; then \
        echo "── Local changes detected ──"; \
        git status --short; \
        if [ ! -r /dev/tty ]; then \
            echo "error: interactive confirmation requires a TTY" >&2; \
            exit 1; \
        fi; \
        printf "Checkpoint current local changes before release? [y/N] " > /dev/tty; \
        read -r RESPONSE < /dev/tty; \
        case "${RESPONSE}" in \
            [Yy]|[Yy][Ee][Ss]) \
                git add -A; \
                git commit -m "chore: checkpoint before release ${TAG}"; \
                ;; \
            *) \
                echo "error: aborted because local changes were not checkpointed" >&2; \
                exit 1; \
                ;; \
        esac; \
    fi; \
    git fetch --quiet --prune --tags origin; \
    if git show-ref --verify --quiet "refs/remotes/origin/${BRANCH}"; then \
        LOCAL_HEAD="$(git rev-parse HEAD)"; \
        REMOTE_HEAD="$(git rev-parse "refs/remotes/origin/${BRANCH}")"; \
        BASE_HEAD="$(git merge-base HEAD "refs/remotes/origin/${BRANCH}")"; \
        if [ "${LOCAL_HEAD}" != "${REMOTE_HEAD}" ]; then \
            if [ "${BASE_HEAD}" = "${LOCAL_HEAD}" ]; then \
                echo "error: branch ${BRANCH} is behind origin/${BRANCH}; pull before running just update" >&2; \
                exit 1; \
            fi; \
            if [ "${BASE_HEAD}" != "${REMOTE_HEAD}" ]; then \
                echo "error: branch ${BRANCH} has diverged from origin/${BRANCH}; reconcile it before running just update" >&2; \
                exit 1; \
            fi; \
        fi; \
    fi; \
    if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null 2>&1; then \
        echo "error: local tag ${TAG} already exists" >&2; \
        exit 1; \
    fi; \
    if git ls-remote --exit-code --tags origin "refs/tags/${TAG}" >/dev/null 2>&1; then \
        echo "error: remote tag ${TAG} already exists on origin" >&2; \
        exit 1; \
    fi; \
    echo "── Bump version to ${NEW_VERSION} ──"; \
    bash scripts/bump_version.sh "${NEW_VERSION}"; \
    just release-verify; \
    PACKAGE_FILES=(); \
    while IFS= read -r line; do [ -n "$line" ] && PACKAGE_FILES+=("$line"); done < <(git ls-files -- 'package.json' '*/package.json'); \
    CHANGED_TRACKED=(); \
    while IFS= read -r line; do [ -n "$line" ] && CHANGED_TRACKED+=("$line"); done < <(git diff --name-only --); \
    if [ "${#CHANGED_TRACKED[@]}" -eq 0 ]; then \
        echo "error: bump completed but no tracked files changed" >&2; \
        exit 1; \
    fi; \
    for file in "${CHANGED_TRACKED[@]}"; do \
        case "${file}" in \
            VERSION|Cargo.toml|Cargo.lock|CHANGELOG.md|docs/content/changelog.md|package.json|*/package.json) ;; \
            *) \
                echo "error: unexpected tracked change after validation: ${file}" >&2; \
                exit 1; \
                ;; \
        esac; \
    done; \
    git add -- VERSION Cargo.toml Cargo.lock CHANGELOG.md docs/content/changelog.md; \
    if [ "${#PACKAGE_FILES[@]}" -gt 0 ]; then \
        git add -- "${PACKAGE_FILES[@]}"; \
    fi; \
    if git diff --cached --quiet; then \
        echo "error: no version files were staged for commit" >&2; \
        exit 1; \
    fi; \
    echo "── Commit release ──"; \
    git commit -m "chore: release ${TAG}"; \
    echo "── Tag release ──"; \
    git tag -a "${TAG}" -m "${TAG}"; \
    echo "── Push branch ──"; \
    git push origin "${BRANCH}"; \
    echo "── Push tag ──"; \
    git push origin "refs/tags/${TAG}"

# Show current version
version:
    @echo "{{VERSION}}"

# Open CHANGELOG.md
changelog:
    ${EDITOR:-vi} CHANGELOG.md

# Print a pre-filled changelog entry header for pasting
changelog-entry:
    @printf '\n## [{{VERSION}}] - %s\n\n### Added\n- \n\n### Changed\n- \n\n### Fixed\n- \n\n' \
        "$(date +%Y-%m-%d)"

# Run all checks and tests, then print release steps
release-check:
    @echo "── Release checklist for v{{VERSION}} ──"
    @just release-verify
    @echo ""
    @echo "✓ All checks passed. Next steps:"
    @echo "  1. Update CHANGELOG.md and docs/content/changelog.md"
    @echo "  2. Complete the manual checklist in RELEASING.md"
    @echo "  3. Commit and merge the release-prep changes"
    @echo "  4. Tag v{{VERSION}} on the exact merged commit when ready"

# ─────────────────────────────────────────
# UTILITIES
# ─────────────────────────────────────────

# Format all Rust code
fmt:
    cargo fmt --all

# Clean all build and generated artifacts
clean:
    cargo clean
    @if [ -f whytho/Cargo.toml ]; then \
        cargo clean --manifest-path whytho/Cargo.toml; \
    fi
    rm -rf \
        dist \
        native/mac/.artifacts \
        native/mac/.build \
        web/.astro \
        web/dist \
        web/node_modules \
        web-e2e/.runtime \
        web-e2e/node_modules \
        web-e2e/test-results \
        web.zip
    rm -rf \
        integrations/jellyfin/Alchemist.Jellyfin/bin \
        integrations/jellyfin/Alchemist.Jellyfin/obj \
        integrations/jellyfin/Alchemist.Jellyfin.Tests/bin \
        integrations/jellyfin/Alchemist.Jellyfin.Tests/obj \
        integrations/jellyfin/Alchemist.Jellyfin.Tests/TestResults
    @if [ -d whytho ]; then \
        find whytho -type d -name target -prune -exec rm -rf {} +; \
    fi

# Count lines of source code
loc:
    @echo "── Rust ──"
    @count=0; \
        if [ -d src ]; then \
            count=$(find src -type f -name "*.rs" -exec cat {} + | wc -l | tr -d '[:space:]'); \
        fi; \
        printf "%8s total\n" "$count"
    @echo "── Frontend ──"
    @count=0; \
        if [ -d web/src ]; then \
            count=$(find web/src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.astro" \) -exec cat {} + | wc -l | tr -d '[:space:]'); \
        fi; \
        printf "%8s total\n" "$count"
    @echo "── Tests ──"
    @count=0; \
        paths=(); \
        [ -d tests ] && paths+=(tests); \
        [ -d web-e2e/tests ] && paths+=(web-e2e/tests); \
        if [ ${#paths[@]} -gt 0 ]; then \
            count=$(find "${paths[@]}" -type f \( -name "*.rs" -o -name "*.ts" \) -exec cat {} + | wc -l | tr -d '[:space:]'); \
        fi; \
        printf "%8s total\n" "$count"

# Show all environment variables Alchemist respects
env-help:
    @echo "ALCHEMIST_CONFIG_PATH    Config file path"
    @echo "                         Linux/macOS default: ~/.config/alchemist/config.toml"
    @echo "                         Windows default:     %APPDATA%\\Alchemist\\config.toml"
    @echo "ALCHEMIST_CONFIG         Alias for ALCHEMIST_CONFIG_PATH"
    @echo "ALCHEMIST_DB_PATH        SQLite database path"
    @echo "                         Linux/macOS default: ~/.config/alchemist/alchemist.db"
    @echo "                         Windows default:     %APPDATA%\\Alchemist\\alchemist.db"
    @echo "ALCHEMIST_DATA_DIR       Override data directory for the DB file"
    @echo "ALCHEMIST_CONFIG_MUTABLE Allow runtime config writes (default: true)"
    @echo "XDG_CONFIG_HOME          Respected on Linux/macOS if set"
    @echo "RUST_LOG                 Log level (e.g. info, debug, alchemist=trace)"