justfile

# Capsem Justfile
#
# Internal helpers:
#   _ensure-setup   checks for .dev-setup sentinel, runs doctor if missing (auto first-run)
#   _install-tools  auto-installs rust targets, components, cargo tools
#   _check-assets   verifies VM assets exist, runs build-assets if not
#   _pack-initrd    cross-compiles guest binaries + repacks initrd
#   _sign           builds host binaries + codesigns (macOS only, required for VZ)
#   _ensure-service kills any running service, launches a fresh one, waits for socket
#
# User-facing recipe chains:
#   shell            -> _check-assets + _pack-initrd + _ensure-service + TUI
#   ui               -> _ensure-setup + _pnpm-install + run-service (service + Tauri dev hot-reload)
#   run-service      -> _check-assets + _pack-initrd + _ensure-service (start daemon, idempotent)
#   exec +CMD        -> run-service (one-shot command in a fresh temp VM)
#   build-assets     -> _install-tools + _clean-stale + inline doctor (kernel + rootfs, profile-aware)
#   build-ui         -> _frontend-dist (pnpm build + cargo build -p capsem-app, in lockstep)
#   run-ui *ARGS     -> build-ui (launch ./target/debug/capsem-app)
#   smoke            -> _install-tools + _frontend-dist + _check-assets + _pack-initrd + _ensure-service
#                       (audit, doctor --fast, injection, integration, parallel pytest groups)
#   test             -> _install-tools + _clean-stale + _frontend-dist + _generate-settings
#                       + _check-assets + _pack-initrd (everything: audit, cov, cross-compile,
#                       frontend, python, injection, integration, bench, test-install)
#   benchmark        -> _ensure-setup + _check-assets + _pack-initrd + _ensure-service
#                       (standard artifact-recording performance suite)
#   bench            -> benchmark
#   test-gateway     -> (no deps; unit + mock UDS tests)
#   test-gateway-e2e -> _check-assets + _pack-initrd + _sign (real service + VMs)
#   test-install     -> _build-host (Docker e2e: build .deb, dpkg -i, pytest)
#   install          -> _pnpm-install + _stamp-version + profile-derived asset rebuild + _pack-initrd
#                       (hard clean + native package install + status capture + guest DNS/HTTPS gate)
#   cut-release      -> test + _stamp-version (commits changelog and creates a local tag)
#   release [tag]    -> (waits for CI on a pushed tag)
#
# First-time setup:
#   just doctor       (shows what's missing; `just doctor fix` auto-installs)
#   just build-assets (builds kernel + rootfs -- needs docker via Colima on macOS)
#
# Daily dev:          just shell         (service daemon + TUI, ~10s)
#                     just ui            (service + Tauri GUI with hot-reload)
#                     just exec "<cmd>"  (one-shot command in a temp VM)
# Local install:      just install       (hard clean + native package install + status/VM network gate)
# Releases:           just cut-release   (test + bump + local tag; push main/tag manually)
# Dep maintenance:    just update-deps   (cargo update + pnpm update)
#                     just update-prices (refresh genai-prices.json)
#                     just update-fixture <src> (rebuild test.db fixture)
# Debugging:          just logs, just sandbox-logs <id>, just list-sessions,
#                     just inspect-session [id], just query-session "SQL"
# Disk cleanup:       just clean         (nuke target/ + frontend build, ~100 GB)
#                     just clean all     (clean + docker prune)

binary := "target/debug/capsem"
cli_binary := "target/debug/capsem"
service_binary := "target/debug/capsem-service"
process_binary := "target/debug/capsem-process"
mcp_binary := "target/debug/capsem-mcp"
gateway_binary := "target/debug/capsem-gateway"
host_binaries := "target/debug/capsem target/debug/capsem-service target/debug/capsem-process target/debug/capsem-mcp target/debug/capsem-mcp-aggregator target/debug/capsem-mcp-builtin target/debug/capsem-gateway target/debug/capsem-tray target/debug/capsem-tui"
assets_dir := "assets"
default_asset_profile := "config/profiles/base/coding.profile.toml"
entitlements := "entitlements.plist"
host_crates := "-p capsem-service -p capsem-process -p capsem -p capsem-mcp -p capsem-mcp-aggregator -p capsem-mcp-builtin -p capsem-gateway -p capsem-tray -p capsem-tui"

# Stamp version as 1.2.{unix_timestamp} in Cargo.toml, tauri.conf.json, and pyproject.toml.
_stamp-version:
    #!/bin/bash
    set -euo pipefail
    CURRENT=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
    NEW="${CAPSEM_RELEASE_VERSION:-1.2.$(date +%s)}"
    echo "Stamping version: ${CURRENT} -> ${NEW}"
    sed -i '' "s/^version = \"${CURRENT}\"/version = \"${NEW}\"/" Cargo.toml
    sed -i '' "s/\"version\": \"${CURRENT}\"/\"version\": \"${NEW}\"/" crates/capsem-app/tauri.conf.json
    sed -i '' "s/^version = \"${CURRENT}\"/version = \"${NEW}\"/" pyproject.toml

# Compile all host binaries
_build-host:
    cargo build {{host_crates}}

# Codesign all host binaries (macOS only, needed for Virtualization.framework)
_sign: _build-host
    #!/bin/bash
    if [[ "$(uname -s)" == "Darwin" ]]; then
        for bin in {{host_binaries}}; do
            codesign --sign - --entitlements {{entitlements}} --force "$bin"
        done
    fi

# Ensure capsem-service daemon is running with the current binary.
# Kills any existing dev-owned instance (via pidfile -- never pkill-by-name)
# and relaunches fresh. Honors CAPSEM_HOME / CAPSEM_RUN_DIR env vars so
# `just test` and `just smoke` can run against an isolated test home
# without ever touching the user's locally installed capsem.
_ensure-service: _sign
    #!/bin/bash
    set -euo pipefail
    arch=$(uname -m)
    [[ "$arch" == "arm64" ]] || arch="x86_64"
    # Resolve capsem home + run dir from env, matching the Rust helpers.
    CAPSEM_HOME_DIR="${CAPSEM_HOME:-$HOME/.capsem}"
    RUN_DIR="${CAPSEM_RUN_DIR:-$CAPSEM_HOME_DIR/run}"
    mkdir -p "$RUN_DIR"
    PIDFILE="$RUN_DIR/service.pid"
    GATEWAY_PIDFILE="$RUN_DIR/gateway.pid"
    SOCKET="$RUN_DIR/service.sock"
    socket_owner_pids() {
        lsof -nU 2>/dev/null | awk -v socket="$SOCKET" 'index($0, socket) { print $2 }' | sort -u
    }
    kill_service_tree() {
        local pid="$1"
        if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then
            return
        fi
        kill "$pid" 2>/dev/null || true
        for _ in 1 2 3 4 5 6; do
            kill -0 "$pid" 2>/dev/null || break
            sleep 0.25
        done
        if kill -0 "$pid" 2>/dev/null; then
            pgrep -P "$pid" | xargs -r kill -9 2>/dev/null || true
            kill -9 "$pid" 2>/dev/null || true
        fi
    }
    pid_command() {
        local pid="$1"
        ps -p "$pid" -o command= 2>/dev/null || true
    }
    cleanup_runtime_processes() {
        # Kill ONLY the service this pidfile tracks -- no pkill by name.
        # Killing by pattern would take down a user's locally installed capsem
        # (or a parallel test run with a different CAPSEM_HOME).
        if [ -f "$PIDFILE" ]; then
            OLD_PID=$(cat "$PIDFILE" 2>/dev/null || true)
            kill_service_tree "$OLD_PID"
        fi
        if [ -f "$GATEWAY_PIDFILE" ]; then
            OLD_GATEWAY_PID=$(cat "$GATEWAY_PIDFILE" 2>/dev/null || true)
            kill_service_tree "$OLD_GATEWAY_PID"
        fi
        # A stale pidfile is not enough proof that the socket is free: a previous
        # isolated smoke/test service can survive with the same run dir and cause
        # the fresh service to exit as "already running" before it owns the gateway.
        if [ -S "$SOCKET" ]; then
            for SOCKET_PID in $(socket_owner_pids); do
                kill_service_tree "$SOCKET_PID"
            done
            for _ in 1 2 3 4 5 6 7 8; do
                [ -z "$(socket_owner_pids)" ] && break
                sleep 0.25
            done
            REMAINING_SOCKET_PIDS=$(socket_owner_pids)
            if [ -n "$REMAINING_SOCKET_PIDS" ]; then
                echo "ERROR: could not clear existing capsem-service socket owners: $REMAINING_SOCKET_PIDS" >&2
                exit 1
            fi
        fi
        if [ -f "$RUN_DIR/gateway.lock" ]; then
            LOCK_PID=$(cat "$RUN_DIR/gateway.lock" 2>/dev/null || true)
            if [ -z "$LOCK_PID" ] || ! kill -0 "$LOCK_PID" 2>/dev/null; then
                rm -f "$RUN_DIR/gateway.lock"
            else
                LOCK_CMD=$(pid_command "$LOCK_PID")
                if [[ "$LOCK_CMD" == *"capsem-gateway"* && "$LOCK_CMD" == *"$RUN_DIR"* ]]; then
                    kill_service_tree "$LOCK_PID"
                else
                    rm -f "$RUN_DIR/gateway.lock"
                fi
            fi
        fi
        rm -f "$PIDFILE" "$GATEWAY_PIDFILE" "$SOCKET" "$RUN_DIR/gateway.lock" "$RUN_DIR/gateway.token" "$RUN_DIR/gateway.port"
    }
    cleanup_runtime_processes
    # Symlink <capsem_home>/assets -> repo assets so installed tools (MCP, CLI)
    # see the same repacked initrd as the dev service.
    ASSETS_LINK="$CAPSEM_HOME_DIR/assets"
    DEV_ASSETS="$(cd "{{assets_dir}}" && pwd)"
    if [ -L "$ASSETS_LINK" ]; then
        CURRENT=$(readlink "$ASSETS_LINK")
        if [ "$CURRENT" != "$DEV_ASSETS" ]; then
            ln -sfn "$DEV_ASSETS" "$ASSETS_LINK"
            echo "Updated $ASSETS_LINK -> $DEV_ASSETS"
        fi
    elif [ -d "$ASSETS_LINK" ]; then
        # Real directory from install -- replace with symlink for dev.
        # Only happens on the default ~/.capsem layout; test homes start empty.
        rm -rf "$ASSETS_LINK.installed"
        mv "$ASSETS_LINK" "$ASSETS_LINK.installed"
        ln -sfn "$DEV_ASSETS" "$ASSETS_LINK"
        echo "Saved $ASSETS_LINK.installed, symlinked $ASSETS_LINK -> $DEV_ASSETS"
    else
        mkdir -p "$CAPSEM_HOME_DIR"
        ln -sfn "$DEV_ASSETS" "$ASSETS_LINK"
        echo "Symlinked $ASSETS_LINK -> $DEV_ASSETS"
    fi
    # Refresh the local development profile after every initrd repack. The
    # profile pins asset hashes, so leaving it stale makes the service reject
    # the freshly repacked initrd before the VM can boot.
    CAPSEM_ASSETS_DIR="${CAPSEM_ASSETS_DIR:-$DEV_ASSETS}" {{cli_binary}} setup --non-interactive --accept-detected
    cleanup_runtime_processes
    GATEWAY_ARGS=(--gateway-binary {{gateway_binary}})
    if [ -n "${CAPSEM_RUN_DIR:-}" ]; then
        # Isolated smoke/test services must not contend with a locally
        # installed gateway on the default developer port.
        GATEWAY_ARGS+=(--gateway-port 0)
    fi
    echo "Starting capsem-service (CAPSEM_HOME=$CAPSEM_HOME_DIR)..."
    cleanup_runtime_processes
    # Close fd 3 on the service; otherwise the backgrounded service inherits
    # the execution-lock fd from `just smoke` / `just test` and keeps the
    # flock held after the outer shell exits, blocking subsequent runs.
    RUST_LOG="${RUST_LOG:-capsem=debug}" nohup {{service_binary}} \
        --assets-dir {{assets_dir}}/$arch \
        --process-binary {{process_binary}} \
        "${GATEWAY_ARGS[@]}" \
        --foreground 3>&- >/dev/null 2>&1 &
    SVC_PID=$!
    echo "$SVC_PID" > "$PIDFILE"
    for i in $(seq 1 30); do
        if ! kill -0 "$SVC_PID" 2>/dev/null; then
            echo "ERROR: capsem-service exited during startup"
            rm -f "$PIDFILE"
            exit 1
        fi
        if [ -S "$SOCKET" ] && curl -s --unix-socket "$SOCKET" --max-time 2 http://localhost/list >/dev/null 2>&1; then
            if [ -n "${CAPSEM_RUN_DIR:-}" ]; then
                for _ in 1 2 3 4 5 6 7 8 9 10; do
                    [ -s "$RUN_DIR/gateway.token" ] && [ -s "$RUN_DIR/gateway.port" ] && break
                    sleep 0.25
                done
                if [ ! -s "$RUN_DIR/gateway.token" ] || [ ! -s "$RUN_DIR/gateway.port" ]; then
                    echo "ERROR: capsem-gateway did not publish token/port files"
                    kill "$SVC_PID" 2>/dev/null || true
                    rm -f "$PIDFILE"
                    exit 1
                fi
            fi
            echo "capsem-service running (PID $SVC_PID)"
            exit 0
        fi
        sleep 0.5
    done
    echo "ERROR: capsem-service did not start within 15s"
    kill $SVC_PID 2>/dev/null
    rm -f "$PIDFILE"
    exit 1

# Start service daemon + Tauri GUI with hot-reloading
ui: _ensure-setup _pnpm-install run-service
    #!/bin/bash
    set -euo pipefail
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "$HOME/.capsem/run/execution.lock"
    CAPSEM_ASSETS_DIR={{assets_dir}} cargo tauri dev --config crates/capsem-app/tauri.conf.json

# Frontend-only dev server with mock data (no Tauri/VM needed)
dev-frontend: _pnpm-install
    cd frontend && pnpm run dev

# Standalone terminal control-plane shell.
# App-owned controls: Alt+Left/Right switch sessions; Alt+1..9 jumps;
# Alt+n new, Alt+f fork, Alt+r resume, Alt+s suspend, Alt+c checkpoint,
# Alt+t stop, Alt+d delete, Alt+q quit;
# Alt+? help, Alt+i session info, Alt+l sessions. Plain q/Ctrl-C pass to the VM.
# Pass extra args after `--`: `just dev-tui -- --snapshot`.
dev-tui *ARGS:
    cargo run -p capsem-tui {{ARGS}}

# Build the Tauri desktop app (capsem-app) with a fresh frontend bundle.
# IMPORTANT: the Tauri binary embeds frontend/dist at cargo compile time via
# tauri::generate_context!(), so rebuilding only the frontend has no effect
# on the running binary. This recipe keeps the two in lockstep.
#   just build-ui          # debug binary at ./target/debug/capsem-app
#   just build-ui release  # release binary at ./target/release/capsem-app
build-ui profile="debug": _frontend-dist
    #!/bin/bash
    set -euo pipefail
    echo "=== capsem-app ({{profile}}) build ==="
    if [[ "{{profile}}" == "release" ]]; then
        cargo build -p capsem-app --release
        echo ""
        echo "Built ./target/release/capsem-app"
    else
        cargo build -p capsem-app
        echo ""
        echo "Built ./target/debug/capsem-app"
    fi

# Run the Tauri desktop app after a clean frontend+binary rebuild.
# Pass extra args after `--`: `just run-ui -- --connect <vm-id>`.
run-ui *ARGS: build-ui
    #!/bin/bash
    set -euo pipefail
    pkill -f "target/(debug|release)/capsem-app" 2>/dev/null || true
    sleep 1
    ./target/debug/capsem-app {{ARGS}}

# Start service daemon + open the TUI (~10s after first build)
shell: _check-assets _pack-initrd _ensure-service
    #!/bin/bash
    set -euo pipefail
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "$HOME/.capsem/run/execution.lock"
    {{cli_binary}} shell

# Start capsem-service daemon (builds, signs, launches or reuses running instance)
run-service: _check-assets _pack-initrd _ensure-service

# Execute a command in a fresh temporary VM (auto-provisioned and destroyed)
# Usage: just exec "echo hello"   or   just exec "ls -la"
exec +CMD: run-service
    #!/bin/bash
    set -euo pipefail
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "$HOME/.capsem/run/execution.lock"
    {{cli_binary}} run "{{CMD}}"


# Build kernel only for one arch (CI-facing primitive).
build-kernel arch profile=default_asset_profile: _install-tools
    #!/bin/bash
    set -euo pipefail
    test -f "{{profile}}" || { echo "ERROR: profile not found: {{profile}}" >&2; exit 1; }
    uv run capsem-admin image build "{{profile}}" --arch {{arch}} --template kernel --out {{assets_dir}}/ --json

# Build rootfs only for one arch (CI-facing primitive).
build-rootfs arch profile=default_asset_profile: _install-tools
    #!/bin/bash
    set -euo pipefail
    test -f "{{profile}}" || { echo "ERROR: profile not found: {{profile}}" >&2; exit 1; }
    uv run capsem-admin image build "{{profile}}" --arch {{arch}} --template rootfs --out {{assets_dir}}/ --json

# VM asset rebuild (kernel + rootfs). Default: both arches. Pass arch and profile to build one.
build-assets arch="" profile=default_asset_profile: _install-tools _clean-stale
    #!/bin/bash
    set -euo pipefail
    CAPSEM_SKIP_ASSET_CHECK=1 just doctor
    test -f "{{profile}}" || { echo "ERROR: profile not found: {{profile}}" >&2; exit 1; }
    if [[ -n "{{arch}}" ]]; then
        bash scripts/build-assets.sh --profile "{{profile}}" --assets-dir "{{assets_dir}}" --arch "{{arch}}"
    else
        bash scripts/build-assets.sh --profile "{{profile}}" --assets-dir "{{assets_dir}}"
    fi
    just _docker-gc

# Run vulnerability audits (cargo audit + pnpm audit). Fast standalone gate.
# `just test` runs these too; this recipe is a quick pre-push check.
audit: _install-tools _pnpm-install
    #!/bin/bash
    set -euo pipefail
    echo "=== cargo audit ==="
    cargo audit
    echo ""
    echo "=== pnpm audit ==="
    cd frontend && pnpm audit
    echo ""
    echo "Audits clean."

# Update all dependencies (Rust + npm) to latest compatible versions
update-deps: _pnpm-install
    #!/bin/bash
    set -euo pipefail
    echo "=== Cargo update ==="
    cargo update
    echo ""
    echo "=== Frontend update ==="
    cd frontend && pnpm update
    echo ""
    echo "Done. Run 'just smoke' to verify nothing broke."

# Run ALL tests: Rust + frontend + Python + injection + integration + bench + cross-compile + install e2e. No shortcuts.
#
# Runs against an isolated CAPSEM_HOME under target/test-home/ so the suite
# never kills or mutates the user's locally installed capsem. The flock is
# still honored for multi-agent coordination but now lives inside the test
# home, not the shared ~/.capsem/run.
# Show the latest preserved test-artifacts directory after a red `just test`.
# Lists files + sizes and prints the `cat` hint -- saves digging through
# `ls -lt test-artifacts/` after a failure.
test-artifacts:
    #!/usr/bin/env bash
    set -euo pipefail
    if [ ! -d test-artifacts ]; then
        echo "No test-artifacts/ directory yet -- nothing has failed."
        exit 0
    fi
    LATEST=$(ls -1t test-artifacts/ 2>/dev/null | head -1 || true)
    if [ -z "$LATEST" ]; then
        echo "test-artifacts/ is empty."
        exit 0
    fi
    DIR="test-artifacts/$LATEST"
    echo "Latest preserved failure: $DIR"
    echo
    echo "Top-level layout:"
    find "$DIR" -maxdepth 3 -type f -exec stat -f '  %z %N' {} \; 2>/dev/null \
        || find "$DIR" -maxdepth 3 -type f -printf '  %s %P\n'
    echo
    echo "Hint:"
    echo "  cat $DIR/.../service.log | less"
    echo "  cat $DIR/.../sessions/<vm>/process.log | less"

test: _install-tools _clean-stale _frontend-dist _generate-settings _check-assets _pack-initrd
    #!/bin/bash
    set -euo pipefail
    export CAPSEM_HOME="{{justfile_directory()}}/target/test-home/.capsem"
    export CAPSEM_RUN_DIR="$CAPSEM_HOME/run"
    export CAPSEM_ASSETS_DIR="{{justfile_directory()}}/{{assets_dir}}"
    export TMPDIR="{{justfile_directory()}}/target/tmp"
    # Lockfile lives OUTSIDE $CAPSEM_HOME so it survives `rm -rf $CAPSEM_HOME`
    # below. Acquired BEFORE the wipe: if a second `just test` were to run
    # past this line, the first's fd would be pinned to an unlinked inode
    # and the second would flock a brand-new inode unchallenged.
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "{{justfile_directory()}}/target/capsem-test-execution.lock"
    cleanup_isolated_home_processes() {
        [ -e "$CAPSEM_HOME" ] || return 0
        PIDS=$(lsof -n 2>/dev/null | awk -v home="$CAPSEM_HOME" 'index($0, home) { print $2 }' | sort -u)
        for PID in $PIDS; do
            [ "$PID" != "$$" ] || continue
            kill "$PID" 2>/dev/null || true
        done
        sleep 0.5
        for PID in $PIDS; do
            [ "$PID" != "$$" ] || continue
            kill -9 "$PID" 2>/dev/null || true
        done
    }
    cleanup_isolated_home_processes
    rm -rf "$CAPSEM_HOME"
    rm -rf "$TMPDIR"
    mkdir -p "$CAPSEM_RUN_DIR" "$CAPSEM_HOME/sessions" "$CAPSEM_HOME/logs" "$TMPDIR"

    # ---- Stage 1: parallel fast-fail (audits + lint + frontend) -------------
    # Cheap, independent, most-common failure class. Clippy (not cargo check)
    # is the Rust lint gate per CLAUDE.md -- it's a strict superset of check
    # and covers --all-targets. `set -e` does not trip on failed background
    # jobs, so aggregate with FAIL=1.
    echo "=== Audits + lint + frontend (parallel) ==="
    cargo audit & PID_CARGO_AUDIT=$!
    (cd frontend && pnpm audit) & PID_PNPM_AUDIT=$!
    cargo clippy --workspace --all-targets -- -D warnings & PID_CLIPPY=$!
    (
        cd frontend
        pnpm run check
        pnpm run test
    ) & PID_FE=$!
    FAIL=0
    wait $PID_CARGO_AUDIT || { echo "cargo audit failed"; FAIL=1; }
    wait $PID_PNPM_AUDIT  || { echo "pnpm audit failed";  FAIL=1; }
    wait $PID_CLIPPY      || { echo "cargo clippy failed (warnings = error)"; FAIL=1; }
    wait $PID_FE          || { echo "frontend (check/test/build) failed"; FAIL=1; }
    [ $FAIL -eq 0 ] || exit 1

    # ---- Stage 2: cross-arch agent cross-compile ----------------------------
    # _pack-initrd already built the host arch; this validates the non-host
    # arch compiles cleanly against musl, so a cross-arch regression surfaces
    # before the Docker-based cross-compile at Stage 7.
    echo "=== Cross-compile agent (both arches) ==="
    uv run capsem-builder agent

    # ---- Stage 3: Rust tests + coverage -------------------------------------
    # Threshold is 65, not 100. Some files (uninstall, completions) are intentionally
    # at 0% because they're thin shells over OS/CLI primitives. Some defensive paths
    # (capsem-process IPC handlers, run_shell exit cleanup) only exercise under live
    # VM traffic and are covered by integration tests under tests/, not unit tests.
    # The floor exists to catch a "we deleted half the test suite" regression, not to
    # gate every honest defensive-code addition.
    echo "=== Rust: test suite with coverage ==="
    cargo llvm-cov --workspace --no-cfg-coverage --fail-under-lines 65

    # ---- Stage 4: sign host binaries for VM tests ---------------------------
    echo "=== Sign binaries for integration tests ==="
    just _sign

    # ---- Stage 5: Python pytest, n=4 ----------------------------------------
    # Dogfooding canary: 4 concurrent VMs. --dist=loadfile keeps per-file
    # fixtures on the same worker. Any concurrency flake here is a Capsem-side
    # bug.
    #
    # Serial/timing tests are intentionally excluded from this phase and run
    # in Stage 6. They have their own load profiles and timing gates; mixing
    # them into n=4 turns the gates into host-contention measurements instead
    # of product regressions.
    #
    # --ignore=tests/capsem-recipes -- recipe meta-tests invoke `cargo build
    #   --workspace` via subprocess, which atomically replaces the codesigned
    #   binaries concurrent VM tests need. All their assertions are already
    #   covered by Stage 1 clippy + Stage 3 llvm-cov + Stage 4 _build-host.
    #   Still runnable standalone via `uv run pytest -m recipe`.
    # --ignore=tests/capsem-install -- install-suite tests also spawn `cargo
    #   build -p capsem` from within pytest. This directory is owned by
    #   Stage 7's `just test-install`, which runs it inside Docker with
    #   CAPSEM_DEB_INSTALLED=1 (the skip flag live_system tests respect).
    echo "=== Python: ALL tests (n=4 parallel) ==="
    # CAPSEM_REQUIRE_ARTIFACTS=1: fail the suite if any of assets/<arch>/
    # manifest.json, initrd.img, entitlements.plist, or target/linux-agent/
    # <arch>/ is missing. Stages 1-4 already produced them (this recipe
    # depends on _check-assets + _pack-initrd + _sign); if anything is
    # absent it means an earlier stage silently dropped its output, and
    # we want that to fail loudly here rather than manifest as a pile of
    # individually-skipped tests whose absence goes unnoticed.
    CAPSEM_REQUIRE_ARTIFACTS=1 uv run python -m pytest tests/ -v --tb=short -n 4 --dist=loadfile -m "not benchmark and not serial" \
        --ignore=tests/capsem-recipes \
        --ignore=tests/capsem-install \
        --ignore=tests/capsem-build-chain \
        --cov=src/capsem --cov-report=xml:codecov-python.xml --cov-fail-under=89

    echo "=== Python: Build chain tests (serial) ==="
    CAPSEM_REQUIRE_ARTIFACTS=1 uv run python -m pytest tests/capsem-build-chain/ -v --tb=short

    # ---- Stage 6: legacy VM scripts + bench ---------------------------------
    echo "=== Injection test ==="
    python3 scripts/injection_test.py --binary {{binary}} --assets {{assets_dir}}

    echo "=== Verify local asset manifest signature ==="
    bash scripts/verify-local-manifest-signature.sh {{assets_dir}} config/manifest-sign.pub

    echo "=== Integration test ==="
    python3 scripts/integration_test.py --binary {{binary}} --assets {{assets_dir}}

    echo "=== Serial timing + benchmarks ==="
    # Runs host-side timing gates and diagnostics serially, plus records
    # /tmp/capsem-benchmark.json to benchmarks/capsem-bench/data_<ver>_<arch>.json
    # on every run so we accumulate a baseline.
    CAPSEM_ASSETS_DIR={{assets_dir}} uv run python -m pytest \
        tests/capsem-serial/ \
        tests/capsem-e2e/test_e2e_lifecycle.py::TestDoctor::test_doctor_passes \
        -v --tb=short -m "serial or benchmark"

    # ---- Stage 7: Docker e2e ------------------------------------------------
    echo "=== Cross-compile Linux release (Docker) ==="
    just cross-compile

    echo "=== Install e2e tests (Docker + systemd) ==="
    just test-install

    # ---- Stage 8: cleanup ---------------------------------------------------
    echo "=== Pruning stale build artifacts ==="
    just _clean-stale

# Build the capsem-host-builder Docker image (cached, only rebuilds changed layers).
# See docker/Dockerfile.host-builder for contents.
build-host-image:
    #!/bin/bash
    set -euo pipefail
    echo "=== Building capsem-host-builder image ==="
    docker build \
        -t capsem-host-builder:latest \
        -f docker/Dockerfile.host-builder \
        docker/

# Remove cross-compilation image and cached volumes.
_clean-host-image:
    #!/bin/bash
    set -euo pipefail
    docker rmi capsem-host-builder:latest 2>/dev/null || true
    docker rmi capsem-install-test:latest 2>/dev/null || true
    for vol in capsem-cargo-registry capsem-cargo-git capsem-host-target-arm64 capsem-host-target-x86_64 capsem-rustup capsem-install-target capsem-install-cargo capsem-install-rustup; do
        docker volume rm "$vol" 2>/dev/null || true
    done
    echo "Cleaned host builder image and volumes."

# Build the full Linux release in a container (agent + deb).
# Uses the pre-built capsem-host-builder image (just build-host-image).
# Supports arm64 and x86_64 via native cross-compilation (no QEMU).
#
# The image runs natively on the host arch and cross-compiles via
# Rust --target + multiarch system libs. Named volumes cache cargo
# registry and build artifacts between runs. CARGO_TARGET_DIR=/cargo-target
# inside the container isolates from host macOS target/ directory.
#
# CI vs local divergences (keep in sync when changing either):
#   - CI runs on bare ubuntu runners; this runs in capsem-host-builder via docker
#   - Tauri signing keys: CI from secrets, local from private/tauri/
#   - See: .github/workflows/release.yaml build-app-linux job
cross-compile arch="": _clean-stale _check-assets _generate-settings
    #!/bin/bash
    set -euo pipefail
    ROOT="{{justfile_directory()}}"
    # Default to host architecture
    if [ -z "{{arch}}" ]; then
        TARGET_ARCH=$(uname -m | sed 's/aarch64/arm64/;s/x86_64/x86_64/')
    else
        TARGET_ARCH="{{arch}}"
    fi
    if [ "$TARGET_ARCH" != "arm64" ] && [ "$TARGET_ARCH" != "x86_64" ]; then
        echo "ERROR: unsupported arch '$TARGET_ARCH' (arm64 or x86_64)"
        exit 1
    fi
    # Ensure build image exists
    if ! docker image inspect capsem-host-builder:latest &>/dev/null; then
        echo "=== Build image not found, building... ==="
        just build-host-image
    fi
    # Sync container VM clock on macOS (prevents apt "not valid yet" errors)
    if [[ "$(uname -s)" = "Darwin" ]]; then
        NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
        docker run --rm --privileged alpine date -s "$NOW" 2>/dev/null || true
    fi
    # Map target arch to Rust triple, dpkg arch, and pkg-config paths
    case "$TARGET_ARCH" in
        x86_64)
            RUST_TARGET="x86_64-unknown-linux-gnu"
            DPKG_ARCH="amd64"
            PKG_CONFIG_PATH_CROSS="/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/share/pkgconfig"
            ;;
        arm64)
            RUST_TARGET="aarch64-unknown-linux-gnu"
            DPKG_ARCH="arm64"
            PKG_CONFIG_PATH_CROSS="/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig"
            ;;
    esac
    # Sync assets layout for Tauri build
    rm -rf assets/current
    if [ -d "assets/$TARGET_ARCH" ]; then
        cp -r "assets/$TARGET_ARCH" assets/current
        : > assets/B3SUMS
        for arch_dir in assets/*; do
            [ -d "$arch_dir" ] || continue
            arch_name=$(basename "$arch_dir")
            if [ -f "$arch_dir/vmlinuz" ] && [ -f "$arch_dir/initrd.img" ] && [ -f "$arch_dir/rootfs.squashfs" ]; then
                (cd assets && b3sum "$arch_name/vmlinuz" "$arch_name/initrd.img" "$arch_name/rootfs.squashfs" >> B3SUMS)
            fi
        done
        python3 scripts/gen_manifest.py assets Cargo.toml
        python3 scripts/create_hash_assets.py assets
        bash scripts/sync-dev-assets.sh assets assets
        bash scripts/verify-local-manifest-signature.sh assets config/manifest-sign.pub
        touch crates/capsem-app/build.rs
    fi
    # If the host has the real release signing keys under private/tauri/,
    # inject them into the container. Otherwise the container generates a
    # throwaway dev-only key inline -- the authoritative release keys
    # live in GitHub Actions secrets (TAURI_SIGNING_PRIVATE_KEY +
    # TAURI_SIGNING_PRIVATE_KEY_PASSWORD in
    # .github/workflows/release.yaml) and are only applied on publish.
    # Dev builds just need SOME key so `cargo tauri build` can complete.
    SIGNING_ARGS=()
    if [ -f "$ROOT/private/tauri/capsem.key" ] && [ -f "$ROOT/private/tauri/password.txt" ]; then
        TAURI_KEY=$(cat "$ROOT/private/tauri/capsem.key")
        TAURI_PWD=$(cat "$ROOT/private/tauri/password.txt")
        SIGNING_ARGS=(
            -e "TAURI_SIGNING_PRIVATE_KEY=$TAURI_KEY"
            -e "TAURI_SIGNING_PRIVATE_KEY_PASSWORD=$TAURI_PWD"
        )
    fi
    echo "=== Building Linux deb ($TARGET_ARCH via docker, target=$RUST_TARGET) ==="
    mkdir -p "$ROOT/dist"
    # KVM boot test: pass host virtualization devices if available (Linux host)
    # or skip on macOS/cross-arch builds.
    KVM_FLAG=""
    if [ -e /dev/kvm ]; then
        KVM_FLAG="--device /dev/kvm"
    fi
    VSOCK_FLAG=""
    if [ -e /dev/vhost-vsock ]; then
        VSOCK_FLAG="--device /dev/vhost-vsock"
        # Docker's default seccomp profile denies AF_VSOCK bind even when the
        # vhost-vsock device is passed through, so the KVM boot test cannot
        # accept guest vsock connections without this.
        VSOCK_SECURITY_FLAG="--security-opt seccomp=unconfined"
    else
        VSOCK_SECURITY_FLAG=""
    fi
    # macOS ships Bash 3.2, where expanding an empty array under nounset
    # raises "unbound variable". The signing args are intentionally optional.
    set +u
    docker run --rm \
        $KVM_FLAG \
        "${SIGNING_ARGS[@]}" \
        $VSOCK_FLAG \
        $VSOCK_SECURITY_FLAG \
        -e "TARGET_ARCH=$TARGET_ARCH" \
        -e "RUST_TARGET=$RUST_TARGET" \
        -e "DPKG_ARCH=$DPKG_ARCH" \
        -e "PKG_CONFIG_PATH=$PKG_CONFIG_PATH_CROSS" \
        -v "$ROOT:/src" \
        -v "capsem-cargo-registry:/usr/local/cargo/registry" \
        -v "capsem-cargo-git:/usr/local/cargo/git" \
        -v "capsem-host-target-$TARGET_ARCH:/cargo-target" \
        -v "capsem-frontend-node-modules-$TARGET_ARCH:/src/frontend/node_modules" \
        -v "capsem-rustup:/usr/local/rustup" \
        -w /src \
        capsem-host-builder:latest \
        bash -c "swap-dev-libs \$DPKG_ARCH && \
               echo '--- Build agent binaries ---' && \
               cargo build --release --target \$RUST_TARGET -p capsem-agent && \
               mkdir -p /cargo-target/linux-agent/\$TARGET_ARCH && \
               cp /cargo-target/\$RUST_TARGET/release/capsem-pty-agent /cargo-target/\$RUST_TARGET/release/capsem-mcp-server /cargo-target/\$RUST_TARGET/release/capsem-net-proxy /cargo-target/\$RUST_TARGET/release/capsem-dns-proxy /cargo-target/\$RUST_TARGET/release/capsem-sysutil /cargo-target/linux-agent/\$TARGET_ARCH/ && \
               echo '--- Build host binaries ---' && \
               cargo build --release --target \$RUST_TARGET {{host_crates}} && \
               UV_PROJECT_ENVIRONMENT=/cargo-target/capsem-package-venv bash scripts/prepare-admin-cli.sh /cargo-target/\$RUST_TARGET/release && \
               echo '--- Build frontend ---' && \
               cd frontend && CI=true pnpm install && pnpm build && cd .. && \
               echo '--- Resolve Tauri signing key ---' && \
               DEV_KEY=/cargo-target/dev-tauri-private && \
               if [ -z \"\${TAURI_SIGNING_PRIVATE_KEY:-}\" ]; then \
                   if [ ! -f \"\$DEV_KEY\" ]; then \
                       echo '    no host signing key; generating dev-only key (not for release distribution)' && \
                       cargo tauri signer generate --ci --force -w \"\$DEV_KEY\" -p 'dev' >/dev/null; \
                   else \
                       echo \"    reusing dev key at \$DEV_KEY\"; \
                   fi && \
                   export TAURI_SIGNING_PRIVATE_KEY=\$(cat \"\$DEV_KEY\") && \
                   export TAURI_SIGNING_PRIVATE_KEY_PASSWORD='dev'; \
               else \
                   echo '    using host-injected signing key'; \
               fi && \
               echo '--- Build Tauri app ---' && \
               DEB_DIR=/cargo-target/\$RUST_TARGET/release/bundle/deb && \
               rm -f \"\$DEB_DIR\"/*.deb && \
               cd crates/capsem-app && cargo tauri build --target \$RUST_TARGET --bundles deb && cd ../.. && \
               echo '--- Validate artifacts ---' && \
               DEBS=(\"\$DEB_DIR\"/*.deb) && \
               if [ \"\${#DEBS[@]}\" -ne 1 ] || [ ! -f \"\${DEBS[0]}\" ]; then \
                   echo \"ERROR: expected exactly one deb artifact in \$DEB_DIR\" >&2; \
                   ls -lah \"\$DEB_DIR\" >&2 || true; \
                   exit 1; \
               fi && \
               DEB=\"\${DEBS[0]}\" && \
               PACKAGE_VERSION=\$(sed -n 's/^version = \"\\(.*\\)\"/\\1/p' Cargo.toml | head -1) && \
               bash scripts/repack-deb.sh \"\$DEB\" /cargo-target/\$RUST_TARGET/release assets \"\$DEB\" && \
               UV_PROJECT_ENVIRONMENT=/cargo-target/capsem-package-venv uv run python scripts/verify_deb_payload.py \"\$DEB\" --version \"\$PACKAGE_VERSION\" --architecture \"\$DPKG_ARCH\" --minisign-pubkey assets/manifest-sign.dev.pub && \
               dpkg-deb --info \"\$DEB\" && \
               rm -f /src/dist/Capsem_*_\"\$DPKG_ARCH\".deb && \
               cp \"\$DEB\" /src/dist/ && \
               cp /cargo-target/linux-agent/\$TARGET_ARCH/* /src/dist/ && \
               echo '--- Boot test ---' && \
               if [ -e /dev/kvm ] && [ \"\$TARGET_ARCH\" = \"\$(uname -m | sed 's/aarch64/arm64/')\" ]; then \
                   echo 'KVM available + native arch: running boot test' && \
                   dpkg --unpack \"\$DEB\" && \
                   timeout 120 python3 scripts/doctor_session_test.py --binary /usr/bin/capsem --assets assets; \
               else \
                   echo 'Skipping boot test (no KVM or cross-arch -- CI will test)'; \
               fi"
    set -u
    echo ""
    echo "=== Artifacts ==="
    ls -lh "$ROOT/dist/"
    just _docker-gc

# Generate settings-schema.json, defaults.json, mcp-tools.json, and mock-data.generated.ts
_generate-settings:
    #!/bin/bash
    set -euo pipefail
    LOG="target/build.log"
    mkdir -p target
    echo "[generate] $(date +%H:%M:%S) exporting MCP tool defs" >> "$LOG"
    cargo run --bin mcp_export 2>>"$LOG" > config/mcp-tools.json
    echo "[generate] $(date +%H:%M:%S) generating schema + defaults + mock" >> "$LOG"
    uv run python scripts/generate_schema.py >> "$LOG" 2>&1

# Fast path: audit, doctor, injection, integration tests (no Docker, no cross-compile)
smoke: _install-tools _frontend-dist _check-assets _pack-initrd
    #!/bin/bash
    set -euo pipefail
    # Smoke runs against an isolated CAPSEM_HOME so it doesn't stomp on a
    # locally installed capsem daemon. _ensure-service is invoked below
    # (not as a just dep) so it inherits the exported env vars.
    export CAPSEM_HOME="{{justfile_directory()}}/target/test-home/.capsem"
    export CAPSEM_RUN_DIR="$CAPSEM_HOME/run"
    export CAPSEM_ASSETS_DIR="{{justfile_directory()}}/{{assets_dir}}"
    # Lockfile lives OUTSIDE $CAPSEM_HOME so it survives `rm -rf $CAPSEM_HOME`
    # below. Acquired BEFORE the wipe: if a second `just smoke` were to run
    # past this line, the first's fd would be pinned to an unlinked inode
    # and the second would flock a brand-new inode unchallenged.
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "{{justfile_directory()}}/target/capsem-test-execution.lock"
    # Wipe stale state so assertions that read <capsem_home>/logs or
    # <capsem_home>/sessions don't trip on artifacts from a previous run
    # (e.g. a 0-entry capsem-app launch log left by a crashed Tauri shell).
    # Matches the `just test` preamble; smoke inherited the leak when
    # CAPSEM_HOME isolation was introduced.
    cleanup_isolated_home_processes() {
        [ -e "$CAPSEM_HOME" ] || return 0
        PIDS=$(lsof -n 2>/dev/null | awk -v home="$CAPSEM_HOME" 'index($0, home) { print $2 }' | sort -u)
        for PID in $PIDS; do
            [ "$PID" != "$$" ] || continue
            kill "$PID" 2>/dev/null || true
        done
        sleep 0.5
        for PID in $PIDS; do
            [ "$PID" != "$$" ] || continue
            kill -9 "$PID" 2>/dev/null || true
        done
    }
    cleanup_isolated_home_processes
    rm -rf "$CAPSEM_HOME"
    mkdir -p "$CAPSEM_RUN_DIR" "$CAPSEM_HOME/sessions" "$CAPSEM_HOME/logs"
    just _ensure-service
    SMOKE_LOG="{{justfile_directory()}}/target/smoke.log"
    mkdir -p "$(dirname "$SMOKE_LOG")"
    exec > >(tee "$SMOKE_LOG") 2>&1
    SMOKE_START=$SECONDS
    step() { STEP_START=$SECONDS; echo "=== $1 ==="; }
    step_done() { echo "  -> $(( SECONDS - STEP_START ))s"; echo ""; }
    step "Rust clippy + audits + frontend lint (parallel)"
    # Clippy (superset of cargo check) is the lint gate per CLAUDE.md.
    # Frontend `pnpm run check` runs here too so a broken Svelte/TS type
    # fails smoke in seconds instead of only surfacing under `just test`.
    # Background jobs don't trip `set -e`, so aggregate via FAIL=1.
    cargo clippy --workspace --all-targets -- -D warnings & CLIPPY_PID=$!
    cargo audit & AUDIT_PID=$!
    (cd frontend && pnpm audit) & PNPM_AUDIT_PID=$!
    (cd frontend && pnpm run check) & FE_CHECK_PID=$!
    FAIL=0
    wait $CLIPPY_PID     || { echo "cargo clippy failed"; FAIL=1; }
    wait $AUDIT_PID      || { echo "cargo audit failed";  FAIL=1; }
    wait $PNPM_AUDIT_PID || { echo "pnpm audit failed";   FAIL=1; }
    wait $FE_CHECK_PID   || { echo "pnpm check failed";   FAIL=1; }
    [ $FAIL -eq 0 ] || exit 1
    step_done
    step "capsem-doctor --fast (in-VM diagnostics, no throughput)"
    {{cli_binary}} doctor --fast
    step_done
    step "Injection test"
    python3 scripts/injection_test.py --binary {{binary}} --assets {{assets_dir}}
    step_done
    step "Integration test"
    python3 scripts/integration_test.py --binary {{binary}} --assets {{assets_dir}}
    step_done
    step "Python integration tests (MCP + service + CLI + gateway, parallel groups)"
    # Pre-sign binaries so parallel test groups don't race on codesign
    for b in {{service_binary}} {{process_binary}}; do
        codesign --sign - --entitlements {{entitlements}} --force "$b" 2>/dev/null || true
    done
    # service+cli is the longest group (~67s serial) -- the big lever.
    # -n 2 + --dist=loadfile cuts it to ~36s. loadfile keeps all tests in
    # a file on the same worker so module-scoped fixtures don't rebuild.
    # Suspend/resume is host-resource sensitive under Apple VZ. Keep those
    # files out of the parallel phase and run them serially after the other
    # service/gateway/MCP tests finish; otherwise unrelated VMs can make
    # resume fail before the guest signals ready.
    MCP_SERIAL="tests/capsem-mcp/test_state_transitions.py"
    SVC_SERIAL=(
        "tests/capsem-service/test_svc_resume_paths.py"
        "tests/capsem-service/test_svc_suspend_corruption.py"
        "tests/capsem-service/test_svc_loop_device_after_resume.py"
    )
    # Keep the two VM-heavy groups from overlapping. Both service+CLI and MCP
    # boot/resume real VMs; running them at the same time can starve Apple VZ
    # enough that otherwise healthy service requests hit client timeouts.
    CAPSEM_TEST_RUN_ID=smoke-service-cli uv run python -m pytest tests/capsem-service/ tests/capsem-cli/ \
        -v --tb=short -m "integration" -n 2 --dist=loadfile \
        --ignore="${SVC_SERIAL[0]}" \
        --ignore="${SVC_SERIAL[1]}" \
        --ignore="${SVC_SERIAL[2]}" &
    PID_SVC=$!
    CAPSEM_TEST_RUN_ID=smoke-gateway uv run python -m pytest tests/capsem-gateway/ -v --tb=short -m "gateway" &
    PID_GW=$!
    FAIL=0
    wait $PID_SVC || FAIL=1
    wait $PID_GW || FAIL=1
    [ $FAIL -eq 0 ] || { echo "Python tests failed"; exit 1; }
    CAPSEM_TEST_RUN_ID=smoke-mcp uv run python -m pytest tests/capsem-mcp/ -v --tb=short -m "mcp" \
        --ignore="$MCP_SERIAL"
    CAPSEM_TEST_RUN_ID=smoke-mcp-serial uv run python -m pytest "$MCP_SERIAL" -v --tb=short -m "mcp"
    CAPSEM_TEST_RUN_ID=smoke-service-serial uv run python -m pytest "${SVC_SERIAL[@]}" -v --tb=short -m "integration"
    step_done
    echo "Smoke test passed in $(( SECONDS - SMOKE_START ))s"
    just _clean-stale

# Gateway unit + integration tests (no VM needed)
test-gateway:
    #!/bin/bash
    set -euo pipefail
    echo "=== Gateway: Rust unit tests ==="
    cargo test -p capsem-gateway -- --nocapture
    echo ""
    echo "=== Gateway: build binary ==="
    cargo build -p capsem-gateway
    echo ""
    echo "=== Gateway: Python integration tests (mock UDS) ==="
    uv run python -m pytest tests/capsem-gateway/ -v --tb=short -m "gateway and not e2e"
    echo ""
    echo "Gateway tests passed"

# Gateway E2E tests (requires capsem-service + VM assets)
test-gateway-e2e: _check-assets _pack-initrd _sign
    #!/bin/bash
    set -euo pipefail
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "$HOME/.capsem/run/execution.lock"
    cargo build -p capsem-gateway {{host_crates}}
    echo "=== Gateway: E2E tests (real service + VMs) ==="
    uv run python -m pytest tests/capsem-gateway/ -v --tb=short -m "gateway and e2e"

# Local HTML coverage report across all Rust crates
coverage:
    #!/bin/bash
    set -euo pipefail
    cargo llvm-cov --workspace --no-cfg-coverage --html
    echo "Coverage report: target/llvm-cov/html/index.html"
    open target/llvm-cov/html/index.html 2>/dev/null || true

# Run the standard artifact-recording benchmark suite.
benchmark: _ensure-setup _check-assets _pack-initrd _ensure-service
    #!/bin/bash
    set -euo pipefail
    source {{justfile_directory()}}/scripts/lib/exec_lock.sh
    acquire_exec_lock "$HOME/.capsem/run/execution.lock"
    echo "=== Preserve current benchmark artifacts ==="
    uv run python scripts/archive_superseded_benchmark_artifacts.py --archive-current-arch
    echo "=== Criterion microbenchmarks ==="
    cargo bench -p capsem-security-engine --bench security_engine_cel
    cargo bench -p capsem-core --bench security_packs
    uv run python scripts/archive_criterion_benchmarks.py
    echo "=== VM-originated and in-VM benchmark artifacts ==="
    CAPSEM_ASSETS_DIR={{assets_dir}} uv run python -m pytest tests/capsem-serial/ -v --tb=short -m benchmark
    echo "=== Archive superseded benchmark artifacts ==="
    uv run python scripts/archive_superseded_benchmark_artifacts.py

# Backward-compatible alias for the canonical benchmark suite.
bench: benchmark

# Compare committed benchmark artifacts across Linux x86_64 and macOS arm64.
benchmark-compare:
    uv run python scripts/compare_benchmark_artifacts.py

# Build package, runtime-clean local install, use the install.sh native command,
# then verify installed status, service, gateway, and guest DNS/HTTPS.
install: _pnpm-install _stamp-version _check-assets
    #!/bin/bash
    set -euo pipefail
    # Strip test-isolation env vars so the installer never bakes a transient
    # target/test-home path into the LaunchAgent / systemd unit. If the user
    # was just running `just test` in this shell and exports lingered, the
    # install would permanently embed a path that gets wiped on the next
    # test run. `capsem install` also refuses these vars defensively.
    unset CAPSEM_HOME CAPSEM_RUN_DIR CAPSEM_ASSETS_DIR
    ROOT="{{justfile_directory()}}"
    source "$ROOT/scripts/lib/exec_lock.sh"
    acquire_exec_lock "$HOME/.capsem/run/execution.lock"
    VERSION=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
    export CAPSEM_BUILD_TS=$(date +%y%m%d%H%M)
    INSTALL_ASSETS_DIR="$ROOT/.capsem-assets/install"

    CAPSEM_SETTINGS_BACKUP="$(mktemp -d "${TMPDIR:-/tmp}/capsem-settings.XXXXXX")"
    cleanup_settings_backup() {
        rm -rf "$CAPSEM_SETTINGS_BACKUP"
    }
    trap cleanup_settings_backup EXIT

    preserve_setting() {
        local rel="$1"
        local src="$HOME/.capsem/$rel"
        local dst="$CAPSEM_SETTINGS_BACKUP/$rel"
        if [ -f "$src" ]; then
            mkdir -p "$(dirname "$dst")"
            cp -p "$src" "$dst"
        elif [ -d "$src" ]; then
            mkdir -p "$(dirname "$dst")"
            cp -a "$src/." "$dst/"
        fi
    }

    restore_setting() {
        local rel="$1"
        local src="$CAPSEM_SETTINGS_BACKUP/$rel"
        local dst="$HOME/.capsem/$rel"
        if [ -f "$src" ]; then
            mkdir -p "$(dirname "$dst")"
            cp -p "$src" "$dst"
        elif [ -d "$src" ]; then
            mkdir -p "$dst"
            cp -a "$src/." "$dst/"
        fi
    }

    assert_clean_uninstall() {
        local failed=0
        if [ -d "$HOME/.capsem/bin" ]; then
            echo "ERROR: runtime bin dir still exists after uninstall:" >&2
            find "$HOME/.capsem/bin" -maxdepth 2 -print >&2 || true
            failed=1
        fi
        if [ -e "$HOME/Library/LaunchAgents/com.capsem.service.plist" ]; then
            echo "ERROR: LaunchAgent still exists after uninstall" >&2
            failed=1
        fi
        if [ -e "$HOME/.config/systemd/user/capsem.service" ]; then
            echo "ERROR: systemd user unit still exists after uninstall" >&2
            failed=1
        fi
        for name in capsem-service capsem-process capsem-gateway capsem-tray; do
            if pgrep -f "$HOME/.capsem/bin/$name" >/dev/null 2>&1; then
                echo "ERROR: $name from ~/.capsem/bin is still running after uninstall" >&2
                failed=1
            fi
        done
        if [ -d "$HOME/.capsem/run" ]; then
            local runtime_left
            runtime_left=$(find "$HOME/.capsem/run" -mindepth 1 -maxdepth 1 \
                ! -name persistent \
                ! -name persistent_registry.json \
                -print 2>/dev/null || true)
            if [ -n "$runtime_left" ]; then
                echo "ERROR: runtime run-state still exists after uninstall:" >&2
                echo "$runtime_left" >&2
                failed=1
            fi
        fi
        return "$failed"
    }

    assert_executable() {
        local path="$1"
        if [ ! -x "$path" ]; then
            echo "ERROR: expected executable missing after install: $path" >&2
            exit 1
        fi
    }

    remove_stale_path() {
        local path="$1"
        if [ -e "$path" ]; then
            rm -rf "$path" 2>/dev/null || sudo rm -rf "$path"
        fi
    }

    echo "=== Building release binaries (build=$CAPSEM_BUILD_TS) ==="
    cargo build --release {{host_crates}}

    echo "=== Rebuilding profile-derived VM assets ==="
    HOST_ARCH=$(uname -m | sed 's/aarch64/arm64/;s/amd64/x86_64/')
    just build-assets "$HOST_ARCH" "{{default_asset_profile}}"

    echo "=== Repacking VM assets ==="
    just _pack-initrd

    echo "=== Keeping existing local profile metadata coherent ==="
    if [ -x "$HOME/.capsem/bin/capsem" ] && [ -d "$HOME/.capsem/profiles/base" ] && [ -f "{{assets_dir}}/manifest.json" ]; then
        python3 scripts/materialize-install-profiles.py \
            "config/profiles/base" \
            "{{assets_dir}}" \
            "$HOME/.capsem/profiles/base" \
            "$HOME/.capsem/assets"
        if "$HOME/.capsem/bin/capsem" setup --non-interactive --accept-detected; then
            "$HOME/.capsem/bin/capsem" start >/dev/null 2>&1 || true
        else
            echo "WARNING: pre-package profile metadata repair failed; final package setup will retry." >&2
        fi
    fi

    echo "=== Snapshotting package asset payload ==="
    rm -rf "$INSTALL_ASSETS_DIR"
    mkdir -p "$INSTALL_ASSETS_DIR"
    bash scripts/sync-dev-assets.sh "{{assets_dir}}" "$INSTALL_ASSETS_DIR"

    echo "=== Clean uninstalling existing local Capsem ==="
    preserve_setting "service.toml"
    if [ -x "$HOME/.capsem/bin/capsem" ]; then
        if "$HOME/.capsem/bin/capsem" uninstall --yes; then
            echo "Existing local Capsem uninstalled."
        else
            echo "Installed capsem uninstall failed; retrying with freshly built CLI." >&2
        fi
    elif [ -e "$HOME/.capsem/bin/capsem" ]; then
        echo "Installed capsem exists but is not executable; retrying with freshly built CLI." >&2
    fi
    "$ROOT/target/release/capsem" uninstall --yes || true
    assert_clean_uninstall

    echo "=== Building frontend ==="
    cd frontend
    pnpm build
    cd ..
    # Load Tauri signing key if available (needed for updater artifacts).
    # If absent, disable updater artifacts via config override.
    TAURI_FLAGS=""
    if [ -f "private/tauri/capsem.key" ]; then
        export TAURI_SIGNING_PRIVATE_KEY=$(cat private/tauri/capsem.key)
        export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=$(cat private/tauri/password.txt 2>/dev/null || echo "")
    else
        TAURI_FLAGS="--config '{\"bundle\":{\"createUpdaterArtifacts\":false}}'"
    fi
    OS=$(uname -s)
    if [ "$OS" = "Darwin" ]; then
        echo "=== Building Capsem.app ==="
        remove_stale_path "target/release/bundle/macos/Capsem.app"
        eval cargo tauri build --bundles app $TAURI_FLAGS
        echo "=== Signing local asset manifest for package payload ==="
        bash scripts/sync-dev-assets.sh "$INSTALL_ASSETS_DIR" "$INSTALL_ASSETS_DIR"
        echo "=== Preparing capsem-admin package payload ==="
        bash scripts/prepare-admin-cli.sh "target/release"
        echo "=== Assembling .pkg (v$VERSION) ==="
        bash scripts/build-pkg.sh \
            "target/release/bundle/macos/Capsem.app" \
            "target/release" \
            "$INSTALL_ASSETS_DIR" \
            "$VERSION"
        PKG="packages/Capsem-$VERSION.pkg"
        echo "=== Installing .pkg ==="
        sudo installer -pkg "$PKG" -target /
    else
        echo "=== Building .deb ==="
        rm -f target/release/bundle/deb/*.deb
        eval cargo tauri build --bundles deb $TAURI_FLAGS
        echo "=== Signing local asset manifest for package payload ==="
        bash scripts/sync-dev-assets.sh "$INSTALL_ASSETS_DIR" "$INSTALL_ASSETS_DIR"
        echo "=== Preparing capsem-admin package payload ==="
        bash scripts/prepare-admin-cli.sh "target/release"
        DEB=$(ls -t target/release/bundle/deb/*.deb | head -1)
        bash scripts/repack-deb.sh "$DEB" "target/release" "$INSTALL_ASSETS_DIR"
        echo "=== Installing .deb ==="
        sudo apt install -y "$DEB"
    fi

    echo "=== Restoring preserved settings ==="
    restore_setting "service.toml"

    echo "=== Verifying installed layout ==="
    assert_executable "$HOME/.capsem/bin/capsem"
    assert_executable "$HOME/.capsem/bin/capsem-service"
    assert_executable "$HOME/.capsem/bin/capsem-process"
    assert_executable "$HOME/.capsem/bin/capsem-mcp"
    assert_executable "$HOME/.capsem/bin/capsem-mcp-aggregator"
    assert_executable "$HOME/.capsem/bin/capsem-mcp-builtin"
    assert_executable "$HOME/.capsem/bin/capsem-gateway"
    assert_executable "$HOME/.capsem/bin/capsem-tray"
    assert_executable "$HOME/.capsem/bin/capsem-tui"
    if [ ! -f "$HOME/.capsem/assets/manifest.json" ]; then
        echo "ERROR: installed asset manifest missing" >&2
        exit 1
    fi
    if [ ! -f "$HOME/.capsem/assets/manifest.json.minisig" ]; then
        echo "ERROR: installed asset manifest signature missing" >&2
        exit 1
    fi
    BUILT_VERSION=$("$ROOT/target/release/capsem" version)
    INSTALLED_VERSION=$("$HOME/.capsem/bin/capsem" version)
    if [ "$BUILT_VERSION" != "$INSTALLED_VERSION" ]; then
        echo "ERROR: installed capsem version does not match the current checkout" >&2
        echo "  built:     $BUILT_VERSION" >&2
        echo "  installed: $INSTALLED_VERSION" >&2
        exit 1
    fi

    echo "=== Syncing locally built assets into ~/.capsem/assets ==="
    bash scripts/sync-dev-assets.sh "$INSTALL_ASSETS_DIR" "$HOME/.capsem/assets"

    echo "=== Finalizing installed setup ==="
    "$HOME/.capsem/bin/capsem" setup --non-interactive --accept-detected

    echo "=== Restarting installed service ==="
    "$HOME/.capsem/bin/capsem" stop >/dev/null 2>&1 || true
    "$HOME/.capsem/bin/capsem" start

    echo "=== Verifying service health ==="
    HEALTHY=false
    for i in $(seq 1 60); do
        if [ -S "$HOME/.capsem/run/service.sock" ] && \
           curl -fsS --unix-socket "$HOME/.capsem/run/service.sock" --max-time 2 http://localhost/list >/dev/null 2>&1; then
            echo "Service is responding."
            HEALTHY=true
            break
        fi
        sleep 0.5
    done
    if [ "$HEALTHY" != "true" ]; then
        echo "ERROR: Service not responding after 30s." >&2
        if [ "$OS" = "Darwin" ]; then
            echo "Check: ~/Library/Logs/capsem/service.log" >&2
        else
            echo "Check: journalctl --user -u capsem" >&2
        fi
        exit 1
    fi

    echo "=== Verifying gateway health ==="
    GATEWAY_HEALTHY=false
    for i in $(seq 1 60); do
        if [ -f "$HOME/.capsem/run/gateway.port" ]; then
            GATEWAY_PORT=$(tr -d '[:space:]' < "$HOME/.capsem/run/gateway.port")
            if [[ "$GATEWAY_PORT" =~ ^[0-9]+$ ]] && \
               curl -fsS "http://127.0.0.1:$GATEWAY_PORT/health" >/dev/null 2>&1; then
                echo "Gateway is responding on port $GATEWAY_PORT."
                GATEWAY_HEALTHY=true
                break
            fi
        fi
        sleep 0.5
    done
    if [ "$GATEWAY_HEALTHY" != "true" ]; then
        echo "ERROR: Gateway not responding after 30s." >&2
        exit 1
    fi

    echo "=== Capturing installed status ==="
    python3 scripts/capture-install-status.py \
        --capsem-bin "$HOME/.capsem/bin/capsem" \
        --label just-install

    echo "=== Verifying guest DNS and HTTPS ==="
    "$HOME/.capsem/bin/capsem" run 'set -eux; getent hosts localhost; getent hosts elie.net; getent hosts generativelanguage.googleapis.com; curl -fsS --connect-timeout 10 https://elie.net >/dev/null; agy --version'

    echo "=== Pruning stale build artifacts ==="
    just _clean-stale

# Run install e2e tests in Docker (Linux + systemd).
# Builds the real .deb (Tauri + repack), installs with dpkg -i (exercises
# deb-postinst.sh), then runs the pytest suite against the installed layout.
test-install:
    #!/bin/bash
    # No _build-host dep: the container does its own `cargo build` (line ~847)
    # against the GTK/glib -dev libs baked into Dockerfile.host-builder.
    # Pre-building on the CI runner duplicated work and broke on Linux
    # runners that lack libglib2.0-dev/libgtk-3-dev (the failure mode that
    # masked the asset-URL bug for v1.0.1777065213).
    set -euo pipefail
    IMAGE="capsem-install-test"
    ASSETS_HOST="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "{{assets_dir}}")"
    WORKDIR_CONTAINER="/work/src"
    ASSETS_CONTAINER="$WORKDIR_CONTAINER/{{assets_dir}}"
    # `cross-compile` runs Docker GC after producing artifacts, which can
    # remove this local base image before the install e2e stage starts.
    if ! docker image inspect capsem-host-builder:latest >/dev/null 2>&1; then
        just build-host-image
    fi
    # Build the Docker image if needed
    if ! docker image inspect "$IMAGE" >/dev/null 2>&1; then
        echo "Building $IMAGE Docker image..."
        docker build -t "$IMAGE" -f docker/Dockerfile.install-test .
    fi
    # Durable disk cushion. Both checks are no-ops in the common case
    # (plenty of Colima headroom, cache under 25 GB) so they don't thrash
    # the build cache every run -- they only fire when we're about to
    # fail anyway.
    # (a) If Colima has <10 GB free on /var/lib/docker, reclaim images +
    #     build cache aggressively (no until= filter). Linux hosts skip.
    if command -v colima >/dev/null 2>&1 && colima status >/dev/null 2>&1; then
        FREE_GB=$(colima ssh -- df -BG /var/lib/docker </dev/null 2>/dev/null | awk 'NR==2{gsub("G","",$4); print $4}')
        if [[ "${FREE_GB:-}" =~ ^[0-9]+$ ]] && [ "$FREE_GB" -lt 10 ]; then
            echo "Low Colima disk (${FREE_GB} GB free) -- pruning images + build cache..."
            docker image prune -af >/dev/null 2>&1 || true
            docker builder prune -af >/dev/null 2>&1 || true
        fi
    fi
    # (b) If the persistent cargo-target volume has grown past 25 GB,
    #     reset it. It caches debug artifacts across runs, but every
    #     crate version bump leaves dead code behind and the volume
    #     grows unbounded otherwise.
    VOLUME_LINE=$(docker system df -v 2>/dev/null | grep "^capsem-install-target " || true)
    if [ -n "$VOLUME_LINE" ]; then
        VOLUME_SIZE=$(echo "$VOLUME_LINE" | awk '{print $NF}')
        VOLUME_GB=$(echo "$VOLUME_SIZE" | grep -oE '^[0-9]+' | head -1)
        if [[ "${VOLUME_GB:-}" =~ ^[0-9]+$ ]] && echo "$VOLUME_SIZE" | grep -q "GB$" && [ "$VOLUME_GB" -gt 25 ]; then
            echo "capsem-install-target is ${VOLUME_SIZE} -- resetting (>25 GB threshold)..."
            docker volume rm capsem-install-target >/dev/null 2>&1 || true
        fi
    fi
    # Stable container name + preemptive rm -f handles any container leaked
    # by a previous run that aborted before reaching cleanup (e.g. cargo
    # SIGTERM under Colima OOM). The EXIT trap below guarantees cleanup on
    # any exit path of *this* run so the leak can't start over.
    CONTAINER="capsem-install-test"
    docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
    trap 'docker rm -f "$CONTAINER" >/dev/null 2>&1 || true; just _docker-gc >/dev/null 2>&1 || true' EXIT
    echo "Starting systemd container..."
    docker run -d --name "$CONTAINER" \
        --privileged --cgroupns=host \
        -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
        --tmpfs /run --tmpfs /tmp \
        -v "$PWD":/checkout:ro \
        -v "$ASSETS_HOST":/asset-source:ro \
        -v capsem-install-target:/cargo-target \
        -v capsem-install-cargo:/usr/local/cargo/registry \
        -v capsem-install-rustup:/usr/local/rustup \
        "$IMAGE" /usr/lib/systemd/systemd
    # Wait for systemd to be ready
    for i in $(seq 1 30); do
        if docker exec "$CONTAINER" systemctl is-system-running --wait 2>/dev/null | grep -qE "running|degraded"; then
            break
        fi
        sleep 0.5
    done
    # Copy the checkout into container-local storage before building. The
    # install e2e loop writes frontend output, Python envs, generated assets,
    # and Debian bundles; keeping those writes off the bind mount prevents
    # host ownership drift and avoids large local uid/gid values in .deb ar
    # headers.
    docker exec "$CONTAINER" bash -c "set -euo pipefail; \
        rm -rf '$WORKDIR_CONTAINER'; \
        mkdir -p '$WORKDIR_CONTAINER' '$ASSETS_CONTAINER'; \
        cd /checkout; \
        tar \
            --exclude='./.venv' \
            --exclude='./target' \
            --exclude='./frontend/node_modules' \
            --exclude='./frontend/dist' \
            --exclude='./frontend/.astro' \
            --exclude='./dist' \
            --exclude='./tmp' \
            --exclude='./coverage' \
            --exclude='./{{assets_dir}}' \
            -cf - . | tar -C '$WORKDIR_CONTAINER' -xf -; \
        cd /asset-source; \
        tar -cf - . | tar -C '$ASSETS_CONTAINER' -xf -; \
        chown -R capsem:capsem /work"
    # Fix ownership for capsem user builds. /usr/local/rustup is included
    # because rustup self-updates (triggered by rust-toolchain.toml's
    # channel = "stable") try to write /usr/local/rustup/tmp/, which is
    # root-owned in the baked image -- without this chown, cargo build as
    # the capsem user dies with `Permission denied (os error 13)`.
    docker exec "$CONTAINER" bash -c "mkdir -p /cargo-target /run/user/1000 && chown -R capsem:capsem /cargo-target /usr/local/cargo /usr/local/rustup /home/capsem /run/user/1000"
    echo "Building host binaries..."
    docker exec -u capsem "$CONTAINER" bash -c \
        "cd '$WORKDIR_CONTAINER' && cargo build {{host_crates}}"
    echo "Preparing clean-checkout assets..."
    docker exec -u capsem -e ASSETS_CONTAINER="$ASSETS_CONTAINER" "$CONTAINER" bash -c \
        'cd /work/src && bash scripts/prepare-install-assets.sh "$ASSETS_CONTAINER" Cargo.toml "${INSTALL_ARCH:-$(uname -m)}"'
    echo "Building frontend..."
    docker exec -u capsem -e CI=true "$CONTAINER" bash -c \
        "cd '$WORKDIR_CONTAINER/frontend' && pnpm install && pnpm build"
    echo "Building Tauri .deb..."
    # Clear stale bundles before the build: /cargo-target is a persistent
    # Docker volume, and any previous version's .deb lingers there. The
    # subsequent `ls *.deb` pickup would otherwise match both the stale
    # and current files -- `ls -t | head -1` below is belt-and-braces for
    # the same class of bug.
    docker exec -u capsem "$CONTAINER" bash -c \
        "rm -f /cargo-target/debug/bundle/deb/*.deb"
    docker exec -u capsem "$CONTAINER" bash -c \
        "cd '$WORKDIR_CONTAINER' && cargo tauri build --debug --bundles deb --config '{\"bundle\":{\"createUpdaterArtifacts\":false}}'"
    echo "Repacking .deb with companion binaries..."
    docker exec -u capsem -e UV_PROJECT_ENVIRONMENT=/cargo-target/install-test-venv -e ASSETS_CONTAINER="$ASSETS_CONTAINER" "$CONTAINER" bash -c \
        'cd /work/src && bash scripts/prepare-admin-cli.sh /cargo-target/debug && DEB=$(ls -t /cargo-target/debug/bundle/deb/*.deb | head -1) && CAPSEM_INSTALL_PROFILE_ASSET_ROOT="$ASSETS_CONTAINER" bash scripts/repack-deb.sh "$DEB" /cargo-target/debug "$ASSETS_CONTAINER" "$DEB"'
    echo "Installing .deb via apt..."
    docker exec "$CONTAINER" bash -c \
        'DEB=$(ls -t /cargo-target/debug/bundle/deb/*.deb | head -1) && apt-get install -y "$DEB"'
    echo "Running install e2e tests..."
    docker exec -u capsem -e UV_PROJECT_ENVIRONMENT=/cargo-target/install-test-venv -e XDG_RUNTIME_DIR=/run/user/1000 -e CAPSEM_DEB_INSTALLED=1 -e CAPSEM_ASSETS_SRC="$ASSETS_CONTAINER" "$CONTAINER" bash -c \
        "cd '$WORKDIR_CONTAINER' && uv run --group dev python -m pytest tests/capsem-install/ -v --tb=short"

# Wait for CI to build and publish a tag.
# Usage: just release          (uses latest vX.Y.Z tag on HEAD)
#        just release v0.9.13  (explicit tag)
release tag="":
    #!/usr/bin/env bash
    set -euo pipefail
    if [ -n "{{tag}}" ]; then
        TAG="{{tag}}"
    else
        TAG=$(git tag --points-at HEAD 'v*' | sort -V | tail -1)
        if [ -z "$TAG" ]; then
            echo "Error: HEAD has no v* tag. Pass one explicitly: just release v0.9.13"
            exit 1
        fi
    fi
    echo "=== Release $TAG ==="
    RUN_ID=$(gh run list --workflow=release.yaml --json databaseId,headBranch,status \
        --jq ".[] | select(.headBranch==\"$TAG\") | .databaseId" | head -1)
    if [ -z "$RUN_ID" ]; then
        echo "Error: no release workflow run found for tag $TAG"
        echo "Push the tag first: git push origin $TAG"
        exit 1
    fi
    echo "CI run: $RUN_ID"
    STATUS=$(gh run view "$RUN_ID" --json status --jq .status)
    if [ "$STATUS" != "completed" ]; then
        echo "Waiting for CI..."
        gh run watch "$RUN_ID"
    fi
    CONCLUSION=$(gh run view "$RUN_ID" --json conclusion --jq .conclusion)
    if [ "$CONCLUSION" != "success" ]; then
        echo "Error: CI run $RUN_ID failed ($CONCLUSION)"
        echo "Check: gh run view $RUN_ID --log-failed"
        exit 1
    fi
    echo "=== Release $TAG published ==="
    echo "https://github.com/google/capsem/releases/tag/$TAG"

# Stamp version, commit, and tag locally.
# Runs test first (all validation gates) before creating the local tag.
# Prepare a release commit and local immutable tag. Push main + tag manually,
# then use `just release <tag>` to watch the tag-triggered release workflow.
cut-release: test _stamp-version
    #!/usr/bin/env bash
    set -euo pipefail
    NEW=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
    TAG="v${NEW}"
    TODAY=$(date +%Y-%m-%d)
    echo "=== Cutting release $TAG ==="
    # Stamp changelog: [Unreleased] -> [NEW] - TODAY
    sed -i '' "s/^## \[Unreleased\]/## [Unreleased]\n\n## [${NEW}] - ${TODAY}/" CHANGELOG.md
    # Extract latest release notes for the frontend boot screen
    uv run python3 scripts/extract-release-notes.py
    # Commit and tag locally. The actual push is deliberate/manual so the
    # release commit and immutable tag are visible before CI starts publishing.
    git add Cargo.toml crates/capsem-app/tauri.conf.json pyproject.toml uv.lock CHANGELOG.md LATEST_RELEASE.md
    git commit -m "release: v${NEW}"
    git tag "$TAG"
    echo "Release commit and local tag created: $TAG"
    echo ""
    echo "Manual publish commands:"
    echo "  git push origin HEAD:main"
    echo "  git push origin $TAG"
    echo "  just release $TAG"

# Check dev tools and dependencies. Pass "fix" to auto-fix.
doctor fix="": _pnpm-install
    #!/bin/bash
    if [ "{{fix}}" = "fix" ]; then
        scripts/doctor-common.sh --fix
    else
        scripts/doctor-common.sh
    fi

# Clean all build artifacts and report freed space
# Clean build artifacts. Pass "all" to also prune docker images/volumes.
clean all="":
    #!/bin/bash
    set -euo pipefail
    BEFORE=$(du -sk . 2>/dev/null | cut -f1)
    echo "=== Cleaning Capsem build artifacts ==="
    if [ -d target ]; then
        TARGET_SIZE=$(du -sh target 2>/dev/null | cut -f1)
        echo "  target/          ${TARGET_SIZE}"
        cargo clean
    fi
    for dir in frontend/dist frontend/node_modules tmp coverage; do
        if [ -d "$dir" ]; then
            DIR_SIZE=$(du -sh "$dir" 2>/dev/null | cut -f1)
            echo "  ${dir}/  ${DIR_SIZE}"
            rm -rf "$dir"
        fi
    done
    # Explicit removal of the isolated test home (also swept by `cargo clean`
    # when target/ is rebuilt, but listed here so it's visible in the log).
    if [ -d target/test-home ]; then
        echo "  target/test-home/   $(du -sh target/test-home 2>/dev/null | cut -f1)"
        rm -rf target/test-home
    fi
    # Leftover /tmp/capsem-test-* dirs from python helpers/service.py.
    if compgen -G "/tmp/capsem-test-*" >/dev/null; then
        TMP_COUNT=$(ls -d /tmp/capsem-test-* 2>/dev/null | wc -l | tr -d ' ')
        echo "  /tmp/capsem-test-*  ($TMP_COUNT entries)"
        rm -rf /tmp/capsem-test-*
    fi
    # Backup assets dir the dev _ensure-service created when it first found a
    # real ~/.capsem/assets/ (replaced with a symlink to the repo assets).
    if [ -d "$HOME/.capsem/assets.installed" ]; then
        echo "  ~/.capsem/assets.installed"
        rm -rf "$HOME/.capsem/assets.installed"
    fi
    if [[ "{{all}}" == "all" ]]; then
        just _clean-host-image
        if command -v docker &>/dev/null; then
            echo ""
            echo "=== Docker cleanup ==="
            docker system prune -af --volumes
        fi
    fi
    AFTER=$(du -sk . 2>/dev/null | cut -f1)
    FREED_KB=$((BEFORE - AFTER))
    if [ "$FREED_KB" -gt 1048576 ]; then
        echo ""
        echo "Freed $((FREED_KB / 1048576)) GB"
    elif [ "$FREED_KB" -gt 1024 ]; then
        echo ""
        echo "Freed $((FREED_KB / 1024)) MB"
    fi

# Inspect session DB integrity and event summary (latest by default)
inspect-session *args='':
    python3 scripts/check_session.py {{args}}

# View capsem-service logs
logs:
    tail -f ~/.capsem/run/service.log

# View logs for a specific sandbox (process + serial)
sandbox-logs id:
    {{cli_binary}} logs {{id}}

# TODO(forensics): replace last-logs with forensic log viewer from forensic sprint

# List recent sessions with event counts per table
list-sessions *args='':
    python3 scripts/list_sessions.py {{args}}

# Run a SQL query against a session DB (latest with a DB by default, or pass session ID)
query-session sql session_id='':
    #!/bin/bash
    set -euo pipefail
    SESSIONS_DIR="$HOME/.capsem/sessions"
    SID="{{session_id}}"
    if [ -z "$SID" ]; then
        # Find latest session that still has a session.db (skip vacuumed)
        SID=$(sqlite3 "$SESSIONS_DIR/main.db" \
          "SELECT id FROM sessions WHERE status != 'vacuumed' ORDER BY created_at DESC LIMIT 1" \
          2>/dev/null || true)
        # Fallback: try any session with a DB on disk
        if [ -z "$SID" ] || [ ! -f "$SESSIONS_DIR/$SID/session.db" ]; then
            for d in $(ls -1t "$SESSIONS_DIR" 2>/dev/null); do
                [ -f "$SESSIONS_DIR/$d/session.db" ] && SID="$d" && break
            done
        fi
    fi
    if [ -z "$SID" ]; then
        echo "No sessions with a session.db found" >&2; exit 1
    fi
    DB="$SESSIONS_DIR/$SID/session.db"
    if [ ! -f "$DB" ]; then
        echo "No session.db at $DB (session may be vacuumed)" >&2; exit 1
    fi
    echo "Session: $SID"
    sqlite3 -header -column "$DB" "{{sql}}"

# Update test fixture DB from a real session (scrubs API keys)
update-fixture src:
    #!/usr/bin/env bash
    set -euo pipefail
    src="{{src}}"
    dst="data/fixtures/test.db"
    pub="frontend/public/fixtures/test.db"
    # Checkpoint WAL so we get a single clean file
    sqlite3 "$src" "PRAGMA wal_checkpoint(TRUNCATE);"
    cp "$src" "$dst"
    # Scrub any leaked API keys (belt-and-suspenders)
    sqlite3 "$dst" "
        UPDATE net_events SET request_headers  = REPLACE(request_headers,  'x-api-key', 'x-api-key-REDACTED') WHERE request_headers  LIKE '%sk-%';
        UPDATE net_events SET request_headers  = REPLACE(request_headers,  'authorization', 'authorization-REDACTED') WHERE request_headers  LIKE '%Bearer%';
        UPDATE net_events SET request_body_preview  = '' WHERE request_body_preview  LIKE '%sk-%' OR request_body_preview  LIKE '%AIza%';
        UPDATE net_events SET response_body_preview = '' WHERE response_body_preview LIKE '%sk-%' OR response_body_preview LIKE '%AIza%';
    "
    # Verify no keys leaked
    count=$(sqlite3 "$dst" "SELECT COUNT(*) FROM (
        SELECT 1 FROM net_events WHERE request_headers  LIKE '%sk-ant-%' OR request_headers  LIKE '%AIza%'
        UNION ALL
        SELECT 1 FROM net_events WHERE request_body_preview LIKE '%sk-ant-%' OR request_body_preview LIKE '%AIza%'
        UNION ALL
        SELECT 1 FROM net_events WHERE response_body_preview LIKE '%sk-ant-%' OR response_body_preview LIKE '%AIza%'
    );")
    if [ "$count" -ne 0 ]; then
        echo "ERROR: Found $count rows with potential API keys -- aborting"
        exit 1
    fi
    # Remove WAL/SHM leftovers
    rm -f "$dst-wal" "$dst-shm"
    # Copy to frontend public
    cp "$dst" "$pub"
    echo "Updated fixture: $(sqlite3 "$dst" 'SELECT COUNT(*) FROM net_events') net_events, $(sqlite3 "$dst" 'SELECT COUNT(*) FROM model_calls') model_calls"

# Update model pricing data from pydantic/genai-prices
update-prices:
    curl -sL https://raw.githubusercontent.com/pydantic/genai-prices/main/prices/data_slim.json \
        -o config/genai-prices.json
    @echo "Updated config/genai-prices.json"

# Remove stale rootfs copies, orphan UDS sockets, and trim bloated incremental caches.
# See scripts/clean_stale.py for implementation (tested: tests/capsem-cleanup-script/).
_clean-stale:
    @uv run python3 scripts/clean_stale.py

# Auto-prune Docker after builds: stopped containers, dangling images, build cache >7d.
# Keeps named volumes (cross-compile cargo caches) and recent build cache for fast rebuilds.
_docker-gc:
    #!/bin/bash
    if ! command -v docker &>/dev/null; then exit 0; fi
    # Remove stopped containers
    CONTAINERS=$(docker container ls -aq --filter status=exited 2>/dev/null)
    if [ -n "$CONTAINERS" ]; then
        docker container rm $CONTAINERS >/dev/null 2>&1 || true
    fi
    # Remove unused images older than 72h
    docker image prune -af --filter until=72h >/dev/null 2>&1 || true
    # Prune build cache older than 72h
    docker builder prune -f --filter until=72h >/dev/null 2>&1 || true
    # Reclaim sparse disk space from Colima VM (fstrim punches holes in the raw disk)
    if command -v colima &>/dev/null && colima status &>/dev/null; then
        colima ssh -- sudo fstrim /mnt/lima-colima >/dev/null 2>&1 || true
    fi

# --- Internal helpers (hidden from `just --list`) ---

# Run doctor automatically on first use (creates .dev-setup sentinel)
_ensure-setup:
    #!/bin/bash
    if [ ! -f .dev-setup ]; then
        echo "First run detected -- running doctor..."
        echo ""
        just doctor
    fi

# Auto-install Rust targets, components, and cargo tools
_install-tools:
    #!/bin/bash
    set -euo pipefail
    # Musl targets for cross-compiling guest binaries
    if ! rustup target list --installed | grep -q aarch64-unknown-linux-musl; then
        echo "Installing aarch64-unknown-linux-musl target..."
        rustup target add aarch64-unknown-linux-musl
    fi
    if ! rustup target list --installed | grep -q x86_64-unknown-linux-musl; then
        echo "Installing x86_64-unknown-linux-musl target..."
        rustup target add x86_64-unknown-linux-musl
    fi
    # rust-lld linker (from llvm-tools component)
    if ! rustup component list --installed | grep -q llvm-tools; then
        echo "Installing llvm-tools (provides rust-lld)..."
        rustup component add llvm-tools
    fi
    # cargo-llvm-cov for coverage
    if ! command -v cargo-llvm-cov &>/dev/null; then
        echo "Installing cargo-llvm-cov..."
        cargo install cargo-llvm-cov
    fi
    # b3sum for BLAKE3 checksums
    if ! command -v b3sum &>/dev/null; then
        echo "Installing b3sum..."
        cargo install b3sum --locked
    fi
    # cargo-audit for vulnerability scanning
    if ! command -v cargo-audit &>/dev/null; then
        echo "Installing cargo-audit..."
        cargo install cargo-audit
    fi
    # Tauri CLI
    if ! cargo tauri --version &>/dev/null; then
        echo "Installing Tauri CLI..."
        cargo install tauri-cli
    fi
    # cargo-sbom for SPDX generation
    if ! command -v cargo-sbom &>/dev/null; then
        echo "Installing cargo-sbom..."
        cargo install cargo-sbom --locked
    fi

# Verify VM assets exist (vmlinuz, initrd.img, rootfs, image-inventory)
_check-assets:
    #!/bin/bash
    set -euo pipefail
    dir="{{assets_dir}}"
    # Map host architecture to asset directory name
    arch=$(uname -m | sed 's/aarch64/arm64/;s/arm64/arm64/')
    missing=()
    if [ -f "$dir/$arch/vmlinuz" ]; then
        # Per-arch layout: assets/{arch}/vmlinuz
        for f in vmlinuz initrd.img rootfs.squashfs image-inventory.json; do
            [ -f "$dir/$arch/$f" ] || missing+=("$arch/$f")
        done
    elif [ -f "$dir/vmlinuz" ]; then
        # Flat layout (legacy): assets/vmlinuz
        for f in vmlinuz initrd.img; do
            [ -f "$dir/$f" ] || missing+=("$f")
        done
        [ -f "$dir/rootfs.squashfs" ] || missing+=("rootfs.squashfs")
    else
        missing+=("vmlinuz (checked $dir/$arch/ and $dir/)")
    fi
    if [ ${#missing[@]} -gt 0 ]; then
        echo "Missing VM assets in $dir/: ${missing[*]}"
        echo "Building $arch assets (requires docker)..."
        just build-assets "$arch"
    fi

_pnpm-install:
    # CI=true suppresses pnpm's interactive "remove and reinstall
    # node_modules?" prompt, which hangs `just test` / `just smoke`
    # when the store layout drifts from the lockfile. Matches the
    # `CI=true pnpm install` already used in cross-compile and
    # test-install below.
    cd frontend && CI=true pnpm install --frozen-lockfile

_frontend-dist: _pnpm-install
    # Tauri's generate_context! macro reads frontend/dist at Rust compile time.
    # Keep this before any workspace clippy/test/build that includes capsem-app.
    cd frontend && pnpm build

_frontend: _frontend-dist

_compile: _clean-stale _frontend
    cargo build -p capsem

_sign-release: _compile
    #!/bin/bash
    set -euo pipefail
    if [[ "$(uname -s)" != "Darwin" ]]; then
        echo "  [skip] codesign (Linux -- not needed, using KVM)"
        exit 0
    fi
    if [[ ! -r "{{entitlements}}" ]]; then
        echo "ERROR: {{entitlements}} not found or not readable."
        echo "       This file should be checked into the repo. Try: git checkout {{entitlements}}"
        exit 1
    fi
    codesign --sign - --entitlements {{entitlements}} --force {{binary}}

_pack-initrd:
    #!/bin/bash
    set -euo pipefail
    ROOT="{{justfile_directory()}}"
    # Find initrd: per-arch layout first, then flat layout
    arch=$(uname -m | sed 's/aarch64/arm64/;s/arm64/arm64/')
    if [ -f "$ROOT/{{assets_dir}}/$arch/initrd.img" ]; then
        INITRD="$ROOT/{{assets_dir}}/$arch/initrd.img"
    elif [ -f "$ROOT/{{assets_dir}}/initrd.img" ]; then
        INITRD="$ROOT/{{assets_dir}}/initrd.img"
    else
        echo "ERROR: initrd.img not found. Run 'just build-assets' first."
        exit 1
    fi
    # Cross-compile guest binaries only if missing or source changed
    RELEASE_DIR="$ROOT/target/linux-agent/$arch"
    NEED_BUILD=false
    for b in capsem-pty-agent capsem-net-proxy capsem-dns-proxy capsem-mcp-server capsem-sysutil; do
        if [ ! -f "$RELEASE_DIR/$b" ]; then
            NEED_BUILD=true
            break
        fi
    done
    # Also rebuild if any agent source is newer than the binaries
    if [ "$NEED_BUILD" = "false" ] && [ -f "$RELEASE_DIR/capsem-pty-agent" ]; then
        NEWEST_SRC=$(find "$ROOT/crates/capsem-agent" "$ROOT/crates/capsem-proto" -name '*.rs' -newer "$RELEASE_DIR/capsem-pty-agent" 2>/dev/null | head -1)
        if [ -n "$NEWEST_SRC" ]; then
            NEED_BUILD=true
        fi
    fi
    if [ "$NEED_BUILD" = "true" ]; then
        echo "=== Cross-compile agent ==="
        if [ -d "$RELEASE_DIR" ]; then
            chmod u+w "$RELEASE_DIR"/capsem-* 2>/dev/null || true
        fi
        uv run capsem-builder agent --arch "$arch"
        echo ""
    else
        echo "=== Agent binaries up to date, skipping cross-compile ==="
    fi
    # Note: capsem-builder enforces 0o555 on the host after the container build
    # (src/capsem/builder/docker.py::enforce_guest_binary_perms). No redundant
    # chmod needed here.
    echo "=== Repack initrd ==="
    WORKDIR=$(mktemp -d)
    cd "$WORKDIR"
    gzip -dc "$INITRD" | cpio -id 2>/dev/null
    cp "$ROOT/guest/artifacts/capsem-init" init
    chmod 755 init
    # Verify binaries exist before repacking
    RELEASE_DIR="$ROOT/target/linux-agent/$arch"
    for b in capsem-pty-agent capsem-net-proxy capsem-dns-proxy capsem-mcp-server capsem-sysutil; do
        if [ ! -f "$RELEASE_DIR/$b" ]; then
            echo "ERROR: $b missing from $RELEASE_DIR"
            exit 1
        fi
        rm -f "$b"
        cp "$RELEASE_DIR/$b" .
        chmod 555 "$b"
    done
    rm -f capsem-doctor
    cp "$ROOT/guest/artifacts/capsem-doctor" capsem-doctor
    chmod 555 capsem-doctor
    rm -f capsem-bench
    cp "$ROOT/guest/artifacts/capsem-bench" capsem-bench
    chmod 555 capsem-bench
    rm -rf capsem_bench
    cp -r "$ROOT/guest/artifacts/capsem_bench" capsem_bench
    find capsem_bench -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true
    rm -f snapshots
    cp "$ROOT/guest/artifacts/snapshots" snapshots
    chmod 555 snapshots
    rm -rf diagnostics
    cp -r "$ROOT/guest/artifacts/diagnostics" diagnostics
    # Atomic write: shell `> "$INITRD"` is truncate-write-in-place on the
    # inode. `create_hash_assets.py` (run below) gives the unhashed
    # `initrd.img` a hash-named hardlink (e.g. `initrd-<hex16>.img`) that
    # shares the same inode. An in-place rewrite mutates that hardlink's
    # content too, so any concurrent VM mid-`VmConfig::build` reading the
    # old hash-named path sees new bytes that don't match the embedded
    # hash. Symptom: `hash mismatch for ...img: expected X, got Y` -- a
    # stress run hitting this loses two cycles per `_pack-initrd` race.
    # Write to a sibling tmp + atomic rename keeps the old inode (and
    # the old hash-named hardlink) intact until `_cleanup_stale` below
    # explicitly unlinks it.
    TMP="${INITRD}.tmp.$$"
    find . | cpio -o -H newc 2>/dev/null | gzip > "$TMP"
    mv "$TMP" "$INITRD"
    rm -rf "$WORKDIR"
    cd "$ROOT"
    # Regenerate checksums -- handle every complete per-arch layout so a
    # host-arch initrd repack does not erase the other arch's manifest map.
    ASSETS="$ROOT/{{assets_dir}}"
    if [ -d "$ASSETS/$arch" ]; then
        : > "$ASSETS/B3SUMS"
        for arch_dir in "$ASSETS"/*; do
            [ -d "$arch_dir" ] || continue
            arch_name=$(basename "$arch_dir")
            if [ -f "$arch_dir/vmlinuz" ] && [ -f "$arch_dir/initrd.img" ] && [ -f "$arch_dir/rootfs.squashfs" ]; then
                (cd "$ASSETS" && b3sum "$arch_name/vmlinuz" "$arch_name/initrd.img" "$arch_name/rootfs.squashfs" >> B3SUMS)
            fi
        done
    else
        (cd "$ASSETS" && b3sum vmlinuz initrd.img rootfs.squashfs > B3SUMS)
    fi
    # Generate manifest.json from B3SUMS + file sizes
    python3 "$ROOT/scripts/gen_manifest.py" "$ASSETS" "$ROOT/Cargo.toml"
    # Create hash-named copies so dev layout matches installed layout.
    python3 "$ROOT/scripts/create_hash_assets.py" "$ASSETS"
    # Sign the freshly regenerated local manifest so dev `run-service` and
    # `exec` can still exercise the same verified-manifest path as releases.
    bash "$ROOT/scripts/sync-dev-assets.sh" "$ASSETS" "$ASSETS"
    bash "$ROOT/scripts/verify-local-manifest-signature.sh" "$ASSETS" "$ROOT/config/manifest-sign.pub"
    # Force cargo to re-run build.rs so it picks up new manifest hashes
    touch "$ROOT/crates/capsem-app/build.rs"
    echo "initrd repacked (with agent + net-proxy + mcp-server + sysutil + doctor)"