Taskfile.yml

# Spinbox Containerd Runtime - Task Runner
#
# Quick Start:
#   task build           # Build the shim and initrd, fetch the pinned machine
#   task clean           # Clean build artifacts
#   task lint            # Lint code
#
# The machine — QEMU, the guest kernel, the firmware — is not built here. It is one
# versioned artefact from spin-stack/spin-machine, pinned in SPIN_MACHINE_VERSION below
# and fetched by `task machine`. To change it, change it there.
#
# Requirements:
#   - Go 1.23+
#   - Docker with buildx

version: '3'

silent: true

output: "prefixed"

vars:
  GO: go
  DOCKER: docker
  BUILDX: "{{.DOCKER}} buildx"
  MODULE_NAME:
    sh: go list -m
  ROOT_DIR:
    sh: pwd
  ARCH:
    sh: uname -m
  OS:
    sh: uname -s
  OUTPUT_DIR: _output
  BIN_DIR: bin
  SCRIPTS_DIR: hack
  BUILDKIT_CACHE_DIR: '{{.BUILDKIT_CACHE_DIR | default "/var/lib/spin-stack-buildkit-cache"}}'
  BUILDKIT_CACHE_INITRD: '{{.BUILDKIT_CACHE_DIR}}/initrd'

  # --- the machine -------------------------------------------------------------------
  # QEMU, the guest kernel and the firmware are one versioned artefact built elsewhere.
  # spinbox builds none of them: it builds the initrd, the shim and vminitd, which are the
  # software that runs *on* a machine, and pins the machine it runs on.
  #
  # Pinned by content as well as by version. Those artefacts go into the template
  # fingerprint by content, so a release that moved under us invalidates every template on
  # every host — which is correct, and must not happen by accident. Bump both together and
  # say in the commit why the machine changed.
  SPIN_MACHINE_VERSION: '{{.SPIN_MACHINE_VERSION | default "v20260908.02"}}'
  SPIN_MACHINE_SHA256: '{{.SPIN_MACHINE_SHA256 | default "835c193745db13d3dcbaa4574fa471d967335fc4249302de6e0489dfaba02bdb"}}'
  # A sibling checkout that has already built one wins over the published release, so
  # changing the machine is: build it there, `task build` here.
  SPIN_MACHINE_DIR: '{{.SPIN_MACHINE_DIR | default "../spin-machine"}}'

  # Version info (set via environment or computed)
  VERSION:
    sh: echo "${VERSION:-$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo dev)}"
  GIT_COMMIT:
    sh: git rev-parse HEAD 2>/dev/null || echo "unknown"
  BUILD_DATE:
    sh: date -u +"%Y-%m-%dT%H:%M:%SZ"

  # Build flags with version info
  VERSION_PKG: "github.com/spin-stack/spinbox/internal/version"
  VERSION_LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.GitCommit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
  LDFLAGS: "-s -w {{.VERSION_LDFLAGS}}"
  GO_BUILDTAGS: "no_grpc"
  GO_TAGS: '-tags "{{.GO_BUILDTAGS}}"'
  GO_LDFLAGS: "-ldflags '{{.LDFLAGS}}'"

  # Static build flags
  GO_STATIC_BUILDTAGS: "osusergo netgo static_build no_grpc"
  GO_STATIC_TAGS: '-tags "{{.GO_STATIC_BUILDTAGS}}"'
  GO_STATIC_LDFLAGS: "-ldflags '-extldflags \"-static\" {{.LDFLAGS}}'"

  # --- buf --------------------------------------------------------------------------
  # buf does not compile anything here — protobuild still does, from api/Protobuild.toml.
  # buf lints the schema, format-checks it and reports when the wire breaks. Pinned like
  # every other generator: `go install` at an exact version, into the same GOBIN that
  # hack/install-proto-tools puts protobuild and protoc-gen-go-ttrpc in.
  BUF_VERSION: v1.72.0
  GOBIN_DIR:
    sh: echo "${GOBIN:-$(go env GOPATH)/bin}"
  BUF: "{{.GOBIN_DIR}}/buf"

tasks:
  # ==========================================================================
  # Build Tasks
  # ==========================================================================

  build:go:
    internal: true
    cmds:
      - |
        set -eou pipefail
        echo "🐳 Building {{.NAME}}..."
        mkdir -p {{.OUTPUT_DIR}}
        CGO_ENABLED=0 GOOS=linux GOARCH=amd64 {{.GO}} build {{.GO_STATIC_TAGS}} {{.GO_STATIC_LDFLAGS}} -o {{.OUTPUT_DIR}}/{{.OUT}} {{.PKG}}
        echo "✓ {{.NAME}} built: {{.OUTPUT_DIR}}/{{.OUT}} (static)"

  build:
    desc: Build what spinbox makes (shim, commit tool, initrd) and fetch the machine it runs on
    deps:
      - build:shim
      - build:commit
      - build:initrd
    cmds:
      # After the Go binaries, because it is the one step that may reach the network and a
      # compile error should not wait for a download.
      - task: machine
      - cmd: 'echo "✓ Build complete"'

  build:shim:
    desc: Build containerd shim binary (static, Linux x86_64)
    sources:
      - cmd/containerd-shim-spinbox-v1/**
      - internal/**
      - pkg/**
      - go.mod
      - go.sum
    generates:
      - "{{.OUTPUT_DIR}}/containerd-shim-spinbox-v1"
    cmds:
      - task: build:go
        vars:
          NAME: containerd-shim-spinbox-v1
          OUT: containerd-shim-spinbox-v1
          PKG: ./cmd/containerd-shim-spinbox-v1
          GO_STATIC_TAGS: '-tags "osusergo netgo static_build"'

  build:commit:
    desc: Build spinbox-commit binary (static, Linux x86_64)
    sources:
      - cmd/spinbox-commit/**
      - go.mod
      - go.sum
    generates:
      - "{{.OUTPUT_DIR}}/spinbox-commit"
    cmds:
      - task: build:go
        vars:
          NAME: spinbox-commit
          OUT: spinbox-commit
          PKG: ./cmd/spinbox-commit
          GO_STATIC_TAGS: '-tags "osusergo netgo static_build"'

  build:vminitd:
    desc: Build vminitd binary (static, Linux x86_64)
    sources:
      - cmd/vminitd/**
      - internal/**
      - pkg/**
      - go.mod
      - go.sum
    generates:
      - "{{.OUTPUT_DIR}}/vminitd"
    cmds:
      - task: build:go
        vars:
          NAME: vminitd
          OUT: vminitd
          PKG: ./cmd/vminitd
          GO_STATIC_TAGS: '-tags "osusergo netgo static_build"'

  build:initrd:
    desc: Build initrd image
    cmds:
      - |
        set -eou pipefail
        echo "🐳 Building initrd..."
        # Bust the vminitd cache on what the build actually contains, not on the
        # commit it sits at. Keying on `git rev-parse HEAD` alone silently
        # returned the previous initrd whenever vminitd had uncommitted changes -
        # the build reported success, installed a stale binary, and the change
        # under test was simply absent.
        COMMIT_SHA=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
        WORKTREE_SHA=$(git diff HEAD -- cmd internal go.mod go.sum 2>/dev/null | sha256sum | cut -c1-12)
        UNTRACKED_SHA=$(git ls-files --others --exclude-standard -- cmd internal 2>/dev/null | sha256sum | cut -c1-12)
        COMMIT_SHA="${COMMIT_SHA}-${WORKTREE_SHA}-${UNTRACKED_SHA}"
        {{.BUILDX}} build \
          --file Dockerfile \
          --target initrd \
          --platform linux/amd64 \
          --cache-from type=local,src={{.BUILDKIT_CACHE_INITRD}} \
          --cache-to type=local,dest={{.BUILDKIT_CACHE_INITRD}},mode=max,compression=zstd \
          --build-arg VMINITD_CACHE_BUST="${COMMIT_SHA}" \
          --output type=local,dest={{.OUTPUT_DIR}} \
          .
        echo "✓ Initrd built: _output/spinbox-initrd (commit: ${COMMIT_SHA})"

  machine:
    desc: >-
      Put the pinned machine — QEMU, the guest kernel, the firmware — under _output/, from a
      sibling spin-machine checkout or from its published release. spinbox builds none of
      them; this is the only path by which one arrives.
    cmds:
      - |
        set -eou pipefail
        SPIN_MACHINE_VERSION="{{.SPIN_MACHINE_VERSION}}" \
        SPIN_MACHINE_SHA256="{{.SPIN_MACHINE_SHA256}}" \
        SPIN_MACHINE_DIR="{{.SPIN_MACHINE_DIR}}" \
        OUTPUT_DIR="{{.OUTPUT_DIR}}" \
          {{.SCRIPTS_DIR}}/spin-machine

  machine:image:
    desc: >-
      The machine, and the base image every VM's qcow2 chain stands on. Separate
      from `machine` because the image is 819 MB against the 60 the rest weighs,
      and only the lanes that boot a guest open it.
    cmds:
      - |
        set -eou pipefail
        SPIN_MACHINE_WITH_IMAGE=1 \
        SPIN_MACHINE_VERSION="{{.SPIN_MACHINE_VERSION}}" \
        SPIN_MACHINE_SHA256="{{.SPIN_MACHINE_SHA256}}" \
        SPIN_MACHINE_DIR="{{.SPIN_MACHINE_DIR}}" \
        OUTPUT_DIR="{{.OUTPUT_DIR}}" \
          {{.SCRIPTS_DIR}}/spin-machine

  machine:version:
    desc: Print the pinned machine version (the single source of truth for CI).
    silent: true
    cmds:
      - echo "{{.SPIN_MACHINE_VERSION}}"

  # ==========================================================================
  # Development Tasks
  # ==========================================================================

  # ==========================================================================
  # Validation Tasks
  # ==========================================================================

  validate:
    desc: Run all validation checks
    cmds:
      - task: lint
      - task: verify:vendor

  lint:
    desc: Lint code
    cmds:
      - |
        set -eou pipefail
        echo "🔍 Running golangci-lint with config: .golangci.yml"
        GOOS=linux golangci-lint run --config .golangci.yml ./...
        # The tagged files, compiled.
        #
        # Neither the lint above nor `go test ./...` looks at them, so a rename
        # that misses one is green here and fails in CI as `[build failed]`,
        # after five minutes of setting up a VM — the slowest lane in the
        # repository reporting the fastest kind of error there is. That happened.
        #
        # `go vet` and not golangci-lint with the tags: the break to catch is a
        # build break, and turning the full linter loose on files it has never
        # seen reports seven pre-existing style findings that have nothing to do
        # with whoever is running this.
        echo "🔍 Type-checking the tagged tests"
        GOOS=linux go vet -tags=integration,e2e ./...
        echo "✓ Linting passed"
      # The schema, which the Go linter cannot see: names, formatting, and what the
      # wire promised the last release.
      - task: lint:protos

  tools:buf:
    internal: true
    desc: Install the pinned buf
    status:
      - test -x {{.BUF}} && {{.BUF}} --version | grep -qx '{{.BUF_VERSION | trimPrefix "v"}}'
    cmds:
      - |
        set -eou pipefail
        echo "🐳 Installing buf {{.BUF_VERSION}}..."
        GOBIN={{.GOBIN_DIR}} {{.GO}} install github.com/bufbuild/buf/cmd/buf@{{.BUF_VERSION}}

  lint:protos:
    desc: Lint, format-check and compatibility-check the protobuf schema (buf STANDARD)
    deps:
      - tools:buf
    dir: api
    cmds:
      - "{{.BUF}} lint"
      - "{{.BUF}} format --diff --exit-code"
      # These protos went years without a linter, so `breaking` is the check that
      # says what that cost: it is the only one that can tell a rename from a
      # refactor. FILE is the level that catches one — the field numbers survive a
      # rename, every generated accessor and every wire name does not.
      #
      # Against main, because main is what the next release is built from. It needs
      # the history, so a CI checkout must not be shallow.
      #
      # `ref=origin/main` and not `branch=main`, because buf treats the path as a
      # *remote* and asks git for `refs/heads/main` inside it. A developer's
      # checkout has that; a pull request's does not — actions/checkout leaves HEAD
      # detached at the merge commit and creates no local branch — so the check
      # fails on every PR with what reads like an infrastructure fault:
      #
      #   Failure: could not clone file:///…/.git: exit status 128
      #   fatal: couldn't find remote ref main
      #
      # A push to main passes, because there HEAD *is* main — which is why this is
      # easy to miss: the lane is green exactly when it has nothing to compare.
      - "{{.BUF}} breaking --against '../.git#ref=origin/main,subdir=api'"

  integration:
    desc: Build release tarball and run containerd integration test
    vars:
      VERSION: '{{.VERSION | default "ci"}}'
      INTEGRATION_IMAGE: '{{.INTEGRATION_IMAGE | default "ghcr.io/spin-stack/spinbox/sandbox:latest"}}'
      INTEGRATION_RUNTIME: '{{.INTEGRATION_RUNTIME | default "io.containerd.spinbox.v1"}}'
      INTEGRATION_SNAPSHOTTER: '{{.INTEGRATION_SNAPSHOTTER | default "spin-erofs"}}'
    cmds:
      # The base image, which `task machine` leaves behind for weight: this lane
      # boots guests off a qcow2 chain standing on it, and is the only one that
      # does.
      - task: machine:image
      - task: release
        vars:
          VERSION: "{{.VERSION}}"
      - |
        set -eou pipefail
        VERSION="{{.VERSION}}"
        RELEASE_NAME="spinbox-${VERSION}-linux-x86_64"
        TARBALL="{{.OUTPUT_DIR}}/release/${RELEASE_NAME}.tar.gz"

        if [ ! -f "${TARBALL}" ]; then
          echo "👹 Error: release tarball not found: ${TARBALL}"
          exit 1
        fi

        WORKDIR="$(mktemp -d)"
        # Every later trap in this script must keep removing WORKDIR. There is one
        # EXIT trap and setting a new one replaces it, so a `trap 'cleanup_ctr' EXIT`
        # further down silently dropped this and every run left its unpacked release
        # tarball - about 294 MB - behind in /tmp. On a runner whose /tmp is a 23 GB
        # tmpfs that is 58 runs before the linker fails with ENOSPC, which is how it
        # was found.
        trap 'rm -rf "${WORKDIR}"' EXIT

        echo "📦 Verifying QEMU firmware in build output..."
        if [ -d "{{.OUTPUT_DIR}}/qemu" ]; then
          ls -la "{{.OUTPUT_DIR}}/qemu"
        else
          echo "👹 Error: {{.OUTPUT_DIR}}/qemu not found"
          exit 1
        fi

        TARBALL_LIST="${WORKDIR}/tar.list"
        if ! tar -tzf "${TARBALL}" > "${TARBALL_LIST}"; then
          echo "👹 Error: failed to read tarball contents"
          exit 1
        fi

        if ! grep -q "usr/share/spin-stack/qemu/bios-256k.bin" "${TARBALL_LIST}"; then
          echo "👹 Error: bios-256k.bin missing from release tarball"
          grep "usr/share/spin-stack/qemu" "${TARBALL_LIST}" || true
          exit 1
        fi

        tar -xzf "${TARBALL}" -C "${WORKDIR}"

        SUDO="${SUDO:-sudo}"
        ${SUDO} systemctl stop spinbox || true
        ${SUDO} systemctl stop spinbox-buildkit || true
        ${SUDO} systemctl stop spinbox-erofs-snapshotter.service || true
        ${SUDO} "${WORKDIR}/${RELEASE_NAME}/install.sh"
        ${SUDO} systemctl enable --now spinbox
        ${SUDO} systemctl reset-failed spinbox || true
        ${SUDO} systemctl enable --now spinbox-erofs-snapshotter.service
        ${SUDO} systemctl reset-failed spinbox-erofs-snapshotter.service || true

        if [ ! -e /dev/vsock ]; then
          echo "👹 Error: /dev/vsock not found"
          ${SUDO} lsmod | grep vhost_vsock || true
          exit 1
        fi

        echo "✓ /dev/vsock present"
        ${SUDO} lsmod | grep vhost_vsock || true

        SOCKET="/var/run/spin-stack/containerd.sock"

        for _ in $(seq 1 30); do
          if [ -S "${SOCKET}" ]; then
            break
          fi
          sleep 1
        done

        if [ ! -S "${SOCKET}" ]; then
          echo "👹 Error: containerd socket not ready"
          ${SUDO} systemctl status spinbox || true
          exit 1
        fi

        CTR_BIN="/usr/share/spin-stack/bin/ctr"
        CTR_NAMESPACE="spinbox-ci"
        CTR_ID="qbx-ci-$(date +%s)"

        ${SUDO} "${CTR_BIN}" \
          --address "${SOCKET}" \
          --namespace "${CTR_NAMESPACE}" \
          images pull \
          --snapshotter "{{.INTEGRATION_SNAPSHOTTER}}" \
          "{{.INTEGRATION_IMAGE}}"

        cleanup_ctr() {
          # Kill the task
          ${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" tasks kill --signal SIGKILL "${CTR_ID}" >/dev/null 2>&1 || true
          # Wait for task to stop (max 10 seconds)
          for _ in $(seq 1 10); do
            TASK_STATUS=$(${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" tasks list 2>/dev/null | awk -v id="${CTR_ID}" 'NR>1 && $1==id {print $3}')
            if [ -z "${TASK_STATUS}" ] || [ "${TASK_STATUS}" = "STOPPED" ]; then
              break
            fi
            sleep 1
          done
          ${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" tasks delete "${CTR_ID}" >/dev/null 2>&1 || true
          ${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" containers delete "${CTR_ID}" >/dev/null 2>&1 || true
        }
        trap 'cleanup_ctr; rm -rf "${WORKDIR}"' EXIT

        # Everything the VM said about why it did not come up. Defined once and called
        # from both failure paths: a `tasks start` that fails takes the script out through
        # `set -e`, so until now the only failure that printed anything was the *later*
        # one — a task that started and never reached RUNNING. The QMP handshake failing
        # is the earlier one, and it left the lane saying "failed to create shim task" and
        # nothing else.
        dump_vm_logs() {
          echo "---- spinbox logs ----"
          ${SUDO} journalctl -u spinbox --no-pager -n 200 || true
          echo "---- spinbox qemu.log (latest) ----"
          QEMU_LOG=$(ls -1t /var/log/spin-stack/*/qemu.log 2>/dev/null | head -n 1 || true)
          if [ -n "${QEMU_LOG:-}" ]; then
            ${SUDO} tail -n 200 "${QEMU_LOG}" || true
          else
            echo "No qemu.log found under /var/log/spin-stack/"
          fi
          echo "---- spinbox console.log (latest) ----"
          CONSOLE_LOG=$(ls -1t /var/log/spin-stack/*/console.log 2>/dev/null | head -n 1 || true)
          if [ -n "${CONSOLE_LOG:-}" ]; then
            ${SUDO} tail -n 200 "${CONSOLE_LOG}" || true
          else
            echo "No console.log found under /var/log/spin-stack/"
          fi
        }

        ${SUDO} "${CTR_BIN}" \
          --address "${SOCKET}" \
          --namespace "${CTR_NAMESPACE}" \
          containers create --privileged \
          --snapshotter "{{.INTEGRATION_SNAPSHOTTER}}" \
          --runtime "{{.INTEGRATION_RUNTIME}}" \
          "{{.INTEGRATION_IMAGE}}" \
          "${CTR_ID}" \
          /sbin/init

        if ! ${SUDO} "${CTR_BIN}" \
          --address "${SOCKET}" \
          --namespace "${CTR_NAMESPACE}" \
          tasks start --detach \
          "${CTR_ID}"; then
          echo "👹 Error: tasks start failed"
          dump_vm_logs
          exit 1
        fi

        STATUS=""
        for _ in $(seq 1 30); do
          STATUS=$(${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" tasks list 2>/dev/null | awk -v id="${CTR_ID}" 'NR>1 && $1==id {print $3}')
          if [ "${STATUS}" = "RUNNING" ]; then
            break
          fi
          sleep 1
        done

        if [ "${STATUS}" != "RUNNING" ]; then
          echo "👹 Error: task did not reach RUNNING state (status=${STATUS:-unknown})"
          ${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" tasks info "${CTR_ID}" || true
          ${SUDO} "${CTR_BIN}" --address "${SOCKET}" --namespace "${CTR_NAMESPACE}" tasks list || true
          dump_vm_logs
          exit 1
        fi

        cleanup_ctr
        trap 'rm -rf "${WORKDIR}"' EXIT

        TEST_ID="qbx-ci-$(date +%s)"
        ${SUDO} env \
          PATH="${PATH}" \
          SPINBOX_CONTAINERD_SOCKET="${SOCKET}" \
          SPINBOX_IMAGE="{{.INTEGRATION_IMAGE}}" \
          SPINBOX_RUNTIME="{{.INTEGRATION_RUNTIME}}" \
          SPINBOX_SNAPSHOTTER="{{.INTEGRATION_SNAPSHOTTER}}" \
          SPINBOX_FIFO_DIR="/run/spin-stack/containerd/fifo" \
          SPINBOX_TEST_ID="${TEST_ID}" \
          # ./internal/host/vm/qemu carries TestTemplateRestore, the only coverage
          # of the snapshot path: nothing in ./integration restores, because the
          # shim still always boots.
          #
          # -p 1 because both packages start VMs and each allocates vsock CIDs from
          # its own process, so run in parallel they pick the same CID and the
          # second one fails to bind with EADDRINUSE.
          go test -v -tags=integration -count=1 -p 1 ./integration ./internal/host/vm/qemu ./internal/host/volume -test.v || {
            echo "---- spinbox logs for ${TEST_ID} ----"
            ${SUDO} journalctl -u spinbox --no-pager -n 200 | grep "${TEST_ID}" || true
            echo "---- spinbox logs ----"
            ${SUDO} journalctl -u spinbox --no-pager -n 200 || true
            echo "---- spinbox qemu.log (latest) ----"
            QEMU_LOG=$(ls -1t /var/log/spin-stack/*/qemu.log 2>/dev/null | head -n 1 || true)
            if [ -n "${QEMU_LOG:-}" ]; then
              ${SUDO} tail -n 200 "${QEMU_LOG}" || true
            else
              echo "No qemu.log found under /var/log/spin-stack/"
            fi
            echo "---- spinbox console.log (latest) ----"
            CONSOLE_LOG=$(ls -1t /var/log/spin-stack/*/console.log 2>/dev/null | head -n 1 || true)
            if [ -n "${CONSOLE_LOG:-}" ]; then
              ${SUDO} tail -n 200 "${CONSOLE_LOG}" || true
            else
              echo "No console.log found under /var/log/spin-stack/"
            fi
            exit 1
          }

        if [ "${CLEANUP:-0}" = "1" ]; then
          ${SUDO} systemctl stop spinbox || true
          ${SUDO} systemctl stop spinbox-erofs-snapshotter.service || true
          ${SUDO} "${WORKDIR}/${RELEASE_NAME}/uninstall.sh" || true
        fi

  # ==========================================================================
  # Setup and Tool Installation
  # ==========================================================================

  setup:
    desc: Install all required development tools
    cmds:
      - |
        set -eou pipefail
        {{.SCRIPTS_DIR}}/setup

  setup:cache:
    desc: Setup BuildKit cache directory with proper permissions
    cmds:
      - |
        set -eou pipefail
        {{.SCRIPTS_DIR}}/setup-buildkit-cache

  # ==========================================================================
  # Protobuf Tasks (optional)
  # ==========================================================================

  protos:
    desc: Generate protobuf files
    sources:
      - api/**/*.proto
      - go.mod
      - go.sum
    generates:
      - api/**/*.pb.go
    cmds:
      - |
        set -eou pipefail
        echo "🐳 Generating protobufs..."

        # protobuild requires GOPATH mode - ensure symlinks exist
        MODULE_PATH=$(grep '^module ' go.mod | awk '{print $2}')
        GOPATH_DIR="${HOME}/go/src/${MODULE_PATH}"

        # These are remade on every run rather than created when missing. They
        # point into the module cache, so a guarded "create it once" leaves a
        # stale link behind after a dependency bump - and a broken symlink is not
        # a directory, so the guard never fires again and the task fails the same
        # way forever. Remaking them is a syscall.
        echo "  → Creating GOPATH symlink for protobuild..."
        mkdir -p "$(dirname "${GOPATH_DIR}")"
        ln -sfn "$(pwd)" "${GOPATH_DIR}"
        echo "    ✓ Symlink created: ${GOPATH_DIR} -> $(pwd)"

        # Create symlink for containerd/api dependency (needed for proto imports)
        CONTAINERD_API_DIR="${HOME}/go/src/github.com/containerd/containerd/api"
        echo "  → Creating containerd/api symlink for proto imports..."
        # -json and sed, not -f '{{.Dir}}': go-task templates the braces away
        # before the shell sees them, go list falls back to its default output,
        # and the symlink ends up pointing at the literal string
        # "github.com/containerd/containerd/api v1.11.1".
        CONTAINERD_API_MOD=$(go list -m -json github.com/containerd/containerd/api | sed -n 's/.*"Dir": "\(.*\)".*/\1/p')
        mkdir -p "$(dirname "${CONTAINERD_API_DIR}")"
        ln -sfn "${CONTAINERD_API_MOD}" "${CONTAINERD_API_DIR}"

        # containerd's event.proto imports "types/fieldpath.proto" - a path
        # relative to its own module root, which is not an include path here.
        # protobuild's include list is fixed in api/Protobuild.toml and cannot
        # name a module cache directory, so the path is made to resolve under the
        # GOPATH include that protoc already gets.
        ln -sfn "${CONTAINERD_API_MOD}/types" "${HOME}/go/src/types"
        echo "    ✓ Symlink created: ${CONTAINERD_API_DIR}"

        # Save original directory
        ORIGINAL_DIR="$(pwd)"

        # Run protobuild from GOPATH location (required for correct import paths)
        # Note: We must run in a subshell with PWD set to prevent symlink resolution
        (
          cd "${GOPATH_DIR}/api"
          export PATH="${GOPATH_DIR}/bin:${HOME}/go/bin:${PATH}"
          export PWD="${GOPATH_DIR}/api"

          # Run protobuild - it should use GOPATH paths
          protobuild --quiet ${MODULE_PATH}/api/...
        )

        # Fix Go acronyms in generated files
        # The subshell above exported ~/go/bin onto PATH; this runs outside it.
        export PATH="${HOME}/go/bin:${PATH}"
        go-fix-acronym -w -a '^Os' $(find api/ -name '*.pb.go')
        go-fix-acronym -w -a '(Id|Io|Uuid|Os)$$' $(find api/ -name '*.pb.go')

        echo "✓ Protobufs generated"

  check:protos:
    desc: Check if protobufs need regeneration
    cmds:
      - task: protos
      - |
        set -eou pipefail
        echo "🐳 Checking protobuf changes..."
        if [ -n "$(git status --short | grep '.pb.go')" ]; then
          echo "👹 Error: Protobuf files are out of date"
          echo "   Run 'task protos' to regenerate"
          exit 1
        fi
        echo "✓ Protobufs are up to date"

  # ==========================================================================
  # Cleanup Tasks
  # ==========================================================================

  clean:
    desc: Clean build artifacts
    cmds:
      - |
        set -eou pipefail
        echo "🧹 Cleaning build artifacts..."
        rm -rf {{.OUTPUT_DIR}}
        echo "✓ Clean complete"

  # ==========================================================================
  # Utility Tasks
  # ==========================================================================

  setup:buildx:
    desc: Setup Docker Buildx builder for spinbox
    cmds:
      - |
        set -eou pipefail
        BUILDER_NAME="spinbox-builder"

        if docker buildx inspect "${BUILDER_NAME}" &>/dev/null; then
          echo "✓ Builder '${BUILDER_NAME}' already exists"
          docker buildx use "${BUILDER_NAME}"
        else
          echo "→ Creating builder '${BUILDER_NAME}'..."
          docker buildx create \
            --name "${BUILDER_NAME}" \
            --driver docker-container \
            --driver-opt network=host \
            --driver-opt image=moby/buildkit:latest \
            --buildkitd-flags '--allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host' \
            --use
          docker buildx inspect --bootstrap
          echo "✓ Builder '${BUILDER_NAME}' created and active"
        fi

  verify:vendor:
    desc: Verify go.mod/go.sum are up to date
    cmds:
      - |
        set -eou pipefail
        echo "🐳 Verifying vendor files..."
        TMPDIR=$(mktemp -d)
        trap "rm -rf $TMPDIR" EXIT

        cp -R . $TMPDIR/spinbox
        cd $TMPDIR/spinbox
        {{.GO}} mod tidy
        {{.GO}} mod verify

        if ! diff -u go.mod "{{.ROOT_DIR}}/go.mod"; then
          echo "👹 Error: go.mod is out of date"
          echo "   Run 'go mod tidy' to update"
          exit 1
        fi

        if ! diff -u go.sum "{{.ROOT_DIR}}/go.sum"; then
          echo "👹 Error: go.sum is out of date"
          echo "   Run 'go mod tidy' to update"
          exit 1
        fi

        echo "✓ Vendor files are up to date"

  # ==========================================================================
  # All-in-one Tasks
  # ==========================================================================

  all:
    desc: Build and validate everything
    cmds:
      - task: build
      - task: validate
      - cmd: echo "✓ All tasks complete"

  default:
    desc: Default task (build everything)
    cmds:
      - task: build

  # ==========================================================================
  # Release Tasks
  # ==========================================================================

  release:
    desc: Create release tarball
    vars:
      VERSION:
        sh: echo "${VERSION:-$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo dev)}"
    cmds:
      - task: build
      - |
        set -eou pipefail
        VERSION="{{.VERSION}}" {{.SCRIPTS_DIR}}/release

  release:image:
    desc: Build and push sandbox image to GitHub Container Registry
    vars:
      VERSION:
        sh: echo "${VERSION:-$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo dev)}"
      GITHUB_REPOSITORY: '{{.GITHUB_REPOSITORY | default "spin-stack/spinbox"}}'
      IMAGE: 'ghcr.io/{{.GITHUB_REPOSITORY}}/sandbox'
    cmds:
      - |
        set -eou pipefail
        echo "Building {{.IMAGE}}:{{.VERSION}}"
        {{.DOCKER}} build --platform linux/amd64 \
          --label "org.opencontainers.image.version={{.VERSION}}" \
          --label "org.opencontainers.image.source=https://github.com/{{.GITHUB_REPOSITORY}}" \
          --label "org.opencontainers.image.description=Sandbox image for spinbox" \
          -t {{.IMAGE}}:{{.VERSION}} \
          images/sandbox
      - |
        set -eou pipefail
        echo "Tagging {{.IMAGE}}:{{.VERSION}} as latest"
        {{.DOCKER}} tag {{.IMAGE}}:{{.VERSION}} {{.IMAGE}}:latest
      - |
        set -eou pipefail
        echo "Pushing {{.IMAGE}}:{{.VERSION}}"
        {{.DOCKER}} push {{.IMAGE}}:{{.VERSION}}
        {{.DOCKER}} push {{.IMAGE}}:latest
        echo ""
        echo "Released:"
        echo "  {{.IMAGE}}:{{.VERSION}}"
        echo "  {{.IMAGE}}:latest"