chore: release 0.3.1

.github/actions/build-image/action.yml

@@ -82,7 +82,7 @@ runs:
   using: composite
   steps:
     - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3.12.0
+      uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd  # v4.0.0
 
     - name: Set up environment
       uses: ./.github/actions/setup-env
@@ -107,7 +107,7 @@ runs:
 
     - name: Extract metadata
       id: meta
-      uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051  # v5.10.0
+      uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf  # v6.0.0
       with:
         images: ${{ inputs.registry }}
         tags: |
@@ -124,7 +124,7 @@ runs:
 
     - name: Build image (tar output)
       if: inputs.output-type == 'tar'
-      uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+      uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
       with:
         context: ./build
         file: ./build/Containerfile
@@ -174,7 +174,7 @@ runs:
 
     - name: Build image (registry output)
       if: inputs.output-type == 'registry'
-      uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+      uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
       with:
         context: ./build
         file: ./build/Containerfile

.github/actions/setup-env/action.yml

@@ -7,15 +7,19 @@
 # - hadolint (for Containerfile linting in pre-commit)
 # - BATS + helper libraries (for shell script testing)
 #
-# IMPORTANT: The caller must checkout the repository before using this action.
-# This action does NOT checkout code, allowing callers to control ref, token,
-# persist-credentials, and other checkout options.
+# IMPORTANT:
+# - This action does NOT checkout code, allowing callers to control ref, token,
+#   persist-credentials, and other checkout options.
+# - Checkout is only required for operations that read repository files
+#   (for example, sync-dependencies or devcontainer CLI version lookup).
 #
 # Inputs:
+#   install-python:           Install Python (default: true)
+#   python-version:           Python version fallback when pyproject.toml is unavailable (default: '3.12')
 #   sync-dependencies:        Run uv sync to install project deps (default: false)
 #   install-podman:           Install podman (default: false)
 #   install-node:             Install Node.js (default: false)
-#   node-version:             Node.js version (default: '20')
+#   node-version:             Node.js version (default: '24')
 #   install-devcontainer-cli: Install devcontainer CLI + docker-compose wrapper (default: false)
 #   install-hadolint:         Install hadolint binary (default: false)
 #   install-taplo:            Install taplo TOML linter/formatter (default: false)
@@ -25,10 +29,15 @@
 #   uv-version: The version of uv that was installed
 #
 # Usage:
-#   # Minimal (Python + uv only)
+#   # Default (Python + uv only)
 #   - uses: actions/checkout@v4
 #   - uses: ./.github/actions/setup-env
 #
+#   # uv only (skip Python setup)
+#   - uses: ./.github/actions/setup-env
+#     with:
+#       install-python: 'false'
+#
 #   # With project dependencies
 #   - uses: actions/checkout@v4
 #   - uses: ./.github/actions/setup-env
@@ -47,6 +56,14 @@ name: 'Setup Environment'
 description: 'Set up CI environment with Python, uv, and optional tools (podman, Node.js, devcontainer CLI, hadolint, BATS)'
 
 inputs:
+  install-python:
+    description: 'Install Python runtime'
+    required: false
+    default: 'true'
+  python-version:
+    description: 'Python version fallback when pyproject.toml is unavailable'
+    required: false
+    default: '3.12'
   sync-dependencies:
     description: 'Run uv sync to install project dependencies'
     required: false
@@ -62,7 +79,7 @@ inputs:
   node-version:
     description: 'Node.js version (when install-node is true)'
     required: false
-    default: '20'
+    default: '24'
   install-devcontainer-cli:
     description: 'Install @devcontainers/cli and docker-compose wrapper (requires Node.js)'
     required: false
@@ -87,31 +104,145 @@ inputs:
 outputs:
   uv-version:
     description: 'Version of uv installed'
-    value: ${{ steps.setup-uv.outputs.uv-version }}
+    value: ${{ steps.setup-uv-retry.outputs.uv-version || steps.setup-uv.outputs.uv-version }}
 
 runs:
   using: composite
   steps:
     # ── Python ───────────────────────────────────────────────────────────
-    - name: "Set up Python"
+    - name: "Set up Python from pyproject"
+      if: inputs.install-python == 'true' && hashFiles('pyproject.toml') != ''
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
       with:
         python-version-file: "pyproject.toml"
 
+    - name: "Set up Python fallback"
+      if: inputs.install-python == 'true' && hashFiles('pyproject.toml') == ''
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
     # ── uv ─────────────────────────────────────────────────────────────
     - name: Install uv
       id: setup-uv
+      continue-on-error: true
+      uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098  # v7
+      with:
+        enable-cache: true
+        # Install a specific version of uv.
+        version: "0.10.0"
+
+    - name: Wait before retrying uv install
+      if: steps.setup-uv.outcome == 'failure'
+      shell: bash
+      run: sleep 15
+
+    - name: Install uv (retry)
+      id: setup-uv-retry
+      if: steps.setup-uv.outcome == 'failure'
       uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098  # v7
       with:
         enable-cache: true
         # Install a specific version of uv.
         version: "0.10.0"
 
+    # ── retry() shell helper ───────────────────────────────────────────
+    - name: Export retry helper function
+      shell: bash
+      run: |
+        set -euo pipefail
+        RETRY_HELPER="$RUNNER_TEMP/setup-env-retry.sh"
+        PREV_BASH_ENV="${BASH_ENV:-}"
+
+        cat > "$RETRY_HELPER" <<'EOF'
+        retry() {
+          local retries=3
+          local backoff=1
+          local max_backoff=60
+          local rc=1
+
+          while [ "$#" -gt 0 ]; do
+            case "$1" in
+              --retries)
+                retries="$2"
+                shift 2
+                ;;
+              --backoff)
+                backoff="$2"
+                shift 2
+                ;;
+              --max-backoff)
+                max_backoff="$2"
+                shift 2
+                ;;
+              --)
+                shift
+                break
+                ;;
+              *)
+                echo "ERROR: Unknown retry option '$1'"
+                return 2
+                ;;
+            esac
+          done
+
+          if [ "$#" -eq 0 ]; then
+            echo "ERROR: retry requires a command after '--'"
+            return 2
+          fi
+
+          local attempt=1
+          local current_backoff="$backoff"
+          while [ "$attempt" -le "$retries" ]; do
+            if "$@"; then
+              return 0
+            fi
+            rc=$?
+            if [ "$attempt" -lt "$retries" ]; then
+              local wait="$current_backoff"
+              if [ "$wait" -gt "$max_backoff" ]; then
+                wait="$max_backoff"
+              fi
+              echo "Retry $attempt/$retries failed (exit $rc), waiting ${wait}s..."
+              sleep "$wait"
+              current_backoff=$((current_backoff * 2))
+            fi
+            attempt=$((attempt + 1))
+          done
+
+          echo "ERROR: Command failed after $retries attempts: $*"
+          return "$rc"
+        }
+        export -f retry
+        EOF
+
+        if [ -n "$PREV_BASH_ENV" ] && [ -f "$PREV_BASH_ENV" ] && [ "$PREV_BASH_ENV" != "$RETRY_HELPER" ]; then
+          {
+            echo "source \"$PREV_BASH_ENV\""
+            cat "$RETRY_HELPER"
+          } > "${RETRY_HELPER}.merged"
+          mv "${RETRY_HELPER}.merged" "$RETRY_HELPER"
+        fi
+
+        echo "BASH_ENV=$RETRY_HELPER" >> "$GITHUB_ENV"
+
     # ── Python dependencies ───────────────────────────────────────────────
     - name: Sync Python dependencies
       if: inputs.sync-dependencies == 'true'
       shell: bash
-      run: uv sync --frozen --all-extras
+      run: |
+        set -euo pipefail
+
+        if uv sync --frozen --all-extras; then
+          :
+        else
+          rc=$?
+          echo "WARNING: uv sync failed (exit $rc), clearing cache and .venv before retry..."
+          uv cache clean
+          rm -rf .venv
+          echo "Retrying uv sync..."
+          uv sync --frozen --all-extras
+        fi
 
     # ── Podman ──────────────────────────────────────────────────────────
     - name: Install podman
@@ -130,7 +261,7 @@ runs:
     # Also installed when install-devcontainer-cli is true (npm is required)
     - name: Install Node.js
       if: inputs.install-node == 'true' || inputs.install-devcontainer-cli == 'true'
-      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+      uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
       with:
         node-version: ${{ inputs.node-version }}
 
@@ -162,8 +293,10 @@ runs:
         BIN_FILE="hadolint-${ARCH}"
         SHA_FILE="${BIN_FILE}.sha256"
 
-        curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
-        curl -fsSL "${BASE_URL}/${SHA_FILE}" -o "${SHA_FILE}"
+        retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
+        retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL "${BASE_URL}/${SHA_FILE}" -o "${SHA_FILE}"
 
         EXPECTED_SHA="$(awk '{print $1}' "${SHA_FILE}")"
         echo "${EXPECTED_SHA}  ${BIN_FILE}" | sha256sum -c -
@@ -189,11 +322,17 @@ runs:
             ;;
         esac
 
-        TAPLO_VERSION="$(curl -fsSL https://api.github.com/repos/tamasfe/taplo/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')"
+        TAPLO_VERSION="$(retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL https://api.github.com/repos/tamasfe/taplo/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')"
+        if [ -z "${TAPLO_VERSION:-}" ]; then
+          echo "ERROR: Failed to resolve Taplo version from GitHub releases API"
+          exit 1
+        fi
         BASE_URL="https://github.com/tamasfe/taplo/releases/download/${TAPLO_VERSION}"
         BIN_FILE="taplo-linux-${ARCH}.gz"
 
-        curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
+        retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
         gunzip "${BIN_FILE}"
         sudo install -m 0755 "taplo-linux-${ARCH}" /usr/local/bin/taplo
         rm -f "taplo-linux-${ARCH}"

.github/actions/test-image/action.yml

@@ -68,7 +68,7 @@ runs:
   using: composite
   steps:
     - name: Checkout code
-      uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
       with:
         ref: ${{ inputs.ref || github.ref }}
 
@@ -125,21 +125,8 @@ runs:
         echo "Pulling image: $IMAGE_TAG"
 
         # Retry logic for podman pull (network flakiness)
-        RETRIES=3
-        for i in $(seq 1 $RETRIES); do
-          if podman pull "$IMAGE_TAG"; then
-            echo "Image pulled successfully"
-            break
-          else
-            if [ $i -lt $RETRIES ]; then
-              echo "Pull failed, retrying ($i/$RETRIES)..."
-              sleep 3
-            else
-              echo "Pull failed after $RETRIES attempts"
-              exit 1
-            fi
-          fi
-        done
+        uv run retry --retries 3 --backoff 3 --max-backoff 3 -- podman pull "$IMAGE_TAG"
+        echo "Image pulled successfully"
 
     - name: Verify image is available
       if: inputs.image-source == 'local'

.github/actions/test-integration/action.yml

@@ -46,7 +46,7 @@ runs:
   using: composite
   steps:
     - name: Checkout code
-      uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
       with:
         ref: ${{ inputs.ref || github.ref }}
 

.github/actions/test-project/action.yml

@@ -39,7 +39,7 @@ runs:
   using: composite
   steps:
     - name: Checkout code
-      uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
     - name: Set up test environment
       uses: ./.github/actions/setup-env
@@ -51,7 +51,7 @@ runs:
 
     - name: Cache pre-commit hooks
       if: inputs.suite == 'all' || inputs.suite == 'lint'
-      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830  # v4
+      uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
       with:
         path: ~/.cache/pre-commit
         key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
@@ -147,7 +147,7 @@ runs:
 
     - name: Upload coverage report
       if: always() && inputs.suite == 'all'
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
       with:
         name: coverage-report
         path: coverage.xml