feat: Add just task runner to ensure reproducibility of CI

.github/check-license-headers.yaml

@@ -53,6 +53,8 @@
       "cliff.toml",
       "clippy.toml",
       "**/tests/compile_*/**",
+      "justfile",
+      "run-just.sh",
     ],
   }
 ]

.github/workflows/ci.yaml

@@ -250,26 +250,10 @@ jobs:
       - uses: actions/checkout@v4
       - uses: DeterminateSystems/nix-installer-action@786fff0690178f1234e4e1fe9b536e94f5433196 #v20
       - uses: DeterminateSystems/magic-nix-cache-action@565684385bcd71bad329742eefe8d12f2e765b39 #v13
-      - name: Check golang flake input is up to date
-        working-directory: ffi
-        run: |
-          nix flake update golang
-          if ! git diff --exit-code flake.lock; then
-            echo "Error: ffi/flake.lock is out of date. Run 'nix flake update golang' in the ffi directory and commit the changes."
-            exit 1
-          fi
-      - name: Test build equivalency between Nix and Cargo
-        run: bash -x ./ffi/test-build-equivalency.sh
-      - name: Test Go FFI bindings
-        working-directory: ffi
-        # - cgocheck2 is expensive but provides complete pointer checks
-        # - use hash mode ethhash since the flake builds with `--features ethhash,logger`
-        # - run golang outside a nix shell to validate viability without the env setup performed by a nix shell
-        run: |
-          GOLANG="nix run $PWD#go"
-          cd result/ffi
-          GOEXPERIMENT=cgocheck2 TEST_FIREWOOD_HASH_MODE=ethhash ${GOLANG} test ./...
-        shell: bash
+      - name: Check that FFI flake is up-to-date
+        run: ./run-just.sh check-ffi-flake
+      - name: Test nix build of Golang FFI bindings
+        run: ./run-just.sh test-ffi-nix
 
   firewood-ethhash-differential-fuzz:
     needs: build

ffi/flake.nix

@@ -116,13 +116,19 @@
         program = "${go}/bin/go";
       };
 
+      apps.just = {
+        type = "app";
+        program = "${pkgs.just}/bin/just";
+      };
+
       devShells.default = craneLib.devShell {
         inputsFrom = [ firewood-ffi ];
 
         packages = with pkgs; [
           firewood-ffi
-          rustToolchain
           go
+          just
+          rustToolchain
         ];
 
         shellHook = ''

ffi/go.mod

@@ -4,7 +4,7 @@ go 1.24
 
 // Changes to the toolchain version should be replicated in:
 //   - ffi/go.mod (here)
-//   - ffi/flake.nix (update golang.url to a version of avalanchego's nix/go/flake.nix that uses the desired version and run `nix flake update golang`)
+//   - ffi/flake.nix (update golang.url to a version of avalanchego's nix/go/flake.nix that uses the desired version and run `just update-ffi-flake`)
 //   - ffi/tests/eth/go.mod
 //   - ffi/tests/firewood/go.mod
 toolchain go1.24.9

justfile

@@ -0,0 +1,82 @@
+# List available recipes
+default:
+    @just --list
+
+# Build ffi with nix
+build-ffi-nix: check-nix
+    cd ffi && nix build
+
+# Check if the git branch is clean
+check-clean-branch:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    git add --all
+    git update-index --really-refresh >> /dev/null
+
+    # Show the status of the working tree.
+    git status --short
+
+    # Exits if any uncommitted changes are found.
+    git diff-index --quiet HEAD
+
+# Check if the FFI flake (requires clean git tree)
+check-ffi-flake: check-nix
+    ./run-just.sh update-check-ffi-flake
+    ./run-just.sh check-clean-branch
+
+# Check if nix is installed
+check-nix:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if ! command -v nix &> /dev/null; then
+        echo "Error: 'nix' is not installed." >&2
+        echo "" >&2
+        echo "To install nix:" >&2
+        echo "  - Visit: https://github.com/DeterminateSystems/nix-installer" >&2
+        echo "  - Or run: curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install" >&2
+        exit 1
+    fi
+
+# Run all checks of ffi built with nix
+test-ffi-nix: test-ffi-nix-build-equivalency test-ffi-nix-go-bindings
+
+# Test ffi build equivalency between nix and cargo
+test-ffi-nix-build-equivalency: check-nix
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    echo "Testing ffi build equivalency between nix and cargo"
+
+    bash -x ./ffi/test-build-equivalency.sh
+
+# Test golang ffi bindings using the nix-built artifacts
+test-ffi-nix-go-bindings: build-ffi-nix
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    echo "Running ffi tests against bindings built by nix..."
+
+    cd ffi
+
+    # Need to capture the flake path before changing directories to
+    # result/ffi because `result` is a nix store symlink so ../../
+    # won't resolve to the ffi path containing the flake.
+    FLAKE_PATH="$PWD"
+
+    # This runs golang outside a nix shell to validate viability
+    # without the env setup performed by a nix shell
+    GO="nix run $FLAKE_PATH#go"
+
+    cd result/ffi
+
+    # - cgocheck2 is expensive but provides complete pointer checks
+    # - use hash mode ethhash since the flake builds with `--features ethhash,logger`
+    GOEXPERIMENT=cgocheck2 TEST_FIREWOOD_HASH_MODE=ethhash ${GO} test ./...
+
+# Ensure the FFI flake is up-to-date
+update-check-ffi-flake: check-nix
+    #!/usr/bin/env bash
+    set -euo pipefail
+    cd ffi
+    nix flake update golang

run-just.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v just &> /dev/null; then
+    exec just "$@"
+elif command -v nix &> /dev/null; then
+    exec nix run ./ffi#just -- "$@"
+else
+    echo "Error: Neither 'just' nor 'nix' is installed." >&2
+    echo "" >&2
+    echo "Please install one of the following:" >&2
+    echo "" >&2
+    echo "Option 1 - Install just:" >&2
+    echo "  - Visit: https://github.com/casey/just#installation" >&2
+    echo "  - Or use cargo: cargo install just" >&2
+    echo "" >&2
+    echo "Option 2 - Install nix:" >&2
+    echo "  - Visit: https://github.com/DeterminateSystems/nix-installer" >&2
+    echo "  - Or run: curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install" >&2
+    exit 1
+fi