container-superposition 0.1.6 → 0.1.8

package/overlays/dotnet/setup.sh

@@ -3,6 +3,15 @@
 
 set -e
 
+# Source shared setup utilities (provides run_spinner)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+# Suppress the .NET SDK first-run welcome banner and telemetry noise
+export DOTNET_NOLOGO=1
+export DOTNET_CLI_TELEMETRY_OPTOUT=1
+export DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1
+
 # Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
 OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
 
@@ -21,20 +30,18 @@ if [ -f ".devcontainer/global-tools-${OVERLAY_NAME}.txt" ]; then
         if [[ "$line" =~ ^(.+)::(.+)$ ]]; then
             tool="${BASH_REMATCH[1]}"
             version="${BASH_REMATCH[2]}"
-            echo "  Installing $tool version $version..."
-            dotnet tool install --global "$tool" --version "$version" || echo "  ⚠️  $tool already installed or failed"
+            run_spinner "$tool@$version" dotnet tool install --global "$tool" --version "$version" || true
         else
             tool="$line"
-            echo "  Installing $tool..."
-            dotnet tool install --global "$tool" || echo "  ⚠️  $tool already installed or failed"
+            run_spinner "$tool" dotnet tool install --global "$tool" || true
         fi
     done < ".devcontainer/global-tools-${OVERLAY_NAME}.txt"
 else
     # Fallback to hardcoded list
     echo "📦 Installing default .NET global tools..."
-    dotnet tool install --global dotnet-ef || echo "dotnet-ef already installed"
-    dotnet tool install --global dotnet-format || echo "dotnet-format already installed"
-    dotnet tool install --global dotnet-outdated-tool || echo "dotnet-outdated-tool already installed"
+    run_spinner "dotnet-ef" dotnet tool install --global dotnet-ef || true
+    run_spinner "dotnet-format" dotnet tool install --global dotnet-format || true
+    run_spinner "dotnet-outdated-tool" dotnet tool install --global dotnet-outdated-tool || true
 fi
 
 # Verify installations

package/overlays/duckdb/devcontainer.patch.json

@@ -5,6 +5,5 @@
             "apt": "wget unzip",
             "apk": "wget unzip"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-duckdb.sh"
+    }
 }

package/overlays/gcloud/devcontainer.patch.json

@@ -1,11 +1,5 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "features": {
-        "ghcr.io/devcontainers/features/google-cloud-cli:1": {
-            "version": "latest",
-            "installGkeGcloudAuthPlugin": true
-        }
-    },
     "customizations": {
         "vscode": {
             "extensions": ["googlecloudtools.cloudcode"]

package/overlays/gcloud/setup.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Google Cloud CLI setup script
+
+set -e
+
+echo "☁️  Setting up Google Cloud CLI..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+if command -v apk >/dev/null 2>&1; then
+    # Alpine Linux — no official gcloud apt repo; install via tarball
+    apk add --no-cache python3 curl
+    curl -sSL https://sdk.cloud.google.com | CLOUDSDK_CORE_DISABLE_PROMPTS=1 bash -s -- --disable-prompts --install-dir=/usr/local
+    ln -sf /usr/local/google-cloud-sdk/bin/gcloud /usr/local/bin/gcloud
+    ln -sf /usr/local/google-cloud-sdk/bin/gsutil /usr/local/bin/gsutil
+elif command -v apt-get >/dev/null 2>&1; then
+    # Debian/Ubuntu — add Google Cloud apt repo using modern signed-by method
+    # The Google Cloud key is already in binary (non-armored) format — write directly.
+    sudo mkdir -p /usr/share/keyrings /etc/apt/sources.list.d
+    curl -fsSL "https://packages.cloud.google.com/apt/doc/apt-key.gpg" \
+        | sudo tee /usr/share/keyrings/cloud.google.gpg >/dev/null
+    echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
+        | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list >/dev/null
+
+    # Single lock acquisition: install prereqs + add repo + install gcloud in one pass
+    acquire_apt_lock
+    # Pass env vars explicitly — sudo strips them by default.
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get update -qq
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get install -y -qq --no-install-recommends apt-transport-https ca-certificates gnupg curl
+    # apt index already fresh — install gcloud packages without a second apt-get update
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get install -y -qq --no-install-recommends \
+        google-cloud-cli \
+        google-cloud-cli-gke-gcloud-auth-plugin
+    sudo apt-get clean
+    sudo rm -rf /var/lib/apt/lists/*
+    release_apt_lock
+else
+    echo "⚠️  Unsupported package manager, skipping gcloud installation"
+    exit 0
+fi
+
+if command -v gcloud >/dev/null 2>&1; then
+    echo "✓ gcloud installed: $(gcloud --version | head -1)"
+else
+    echo "✗ gcloud installation failed"
+    exit 1
+fi
+
+echo "✓ gcloud setup complete"

package/overlays/gemini-cli/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing Google Gemini CLI..."
 
 # Install @google/gemini-cli globally

package/overlays/git-helpers/devcontainer.patch.json

@@ -6,7 +6,8 @@
             "version": "os-provided"
         },
         "ghcr.io/devcontainers/features/git-lfs:1": {
-            "version": "latest"
+            "version": "latest",
+            "autoPull": false
         },
         "ghcr.io/devcontainers/features/github-cli:1": {
             "version": "latest"

package/overlays/go/setup.sh

@@ -3,25 +3,26 @@
 
 set -e
 
-echo "🔧 Setting up Go development environment..."
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
 
-# Install common Go tools
+echo "🔧 Setting up Go development environment..."
 echo "📦 Installing Go development tools..."
 
-# gopls (Language Server)
-go install golang.org/x/tools/gopls@latest || echo "⚠️ gopls installation failed"
-
-# delve (Debugger)
-go install github.com/go-delve/delve/cmd/dlv@latest || echo "⚠️ delve installation failed"
+run_spinner "gopls (language server)"   go install golang.org/x/tools/gopls@latest
+run_spinner "delve (debugger)"          go install github.com/go-delve/delve/cmd/dlv@latest
 
-# golangci-lint (Linter) - install via go install for security
-go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest || echo "⚠️ golangci-lint installation failed"
-
-# gofumpt (Formatter)
-go install mvdan.cc/gofumpt@latest || echo "⚠️ gofumpt installation failed"
+# golangci-lint — use official installer to avoid gold linker issues on arm64
+if ! command -v golangci-lint &>/dev/null; then
+    run_spinner "golangci-lint" \
+        bash -c 'curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b "$(go env GOPATH)/bin"'
+else
+    echo "  ℹ️  golangci-lint already installed: $(golangci-lint version --short 2>/dev/null || true)"
+fi
 
-# staticcheck (Static analyzer)
-go install honnef.co/go/tools/cmd/staticcheck@latest || echo "⚠️ staticcheck installation failed"
+run_spinner "gofumpt (formatter)"      go install mvdan.cc/gofumpt@latest
+run_spinner "staticcheck (analyzer)"   go install honnef.co/go/tools/cmd/staticcheck@latest
 
 # Install project dependencies if go.mod exists
 if [ -f "go.mod" ]; then

package/overlays/jaeger/overlay.yml

@@ -30,3 +30,5 @@ ports:
       description: Jaeger HTTP receiver
       onAutoForward: ignore
 order: 1
+imports:
+    - .shared/otel/instrumentation.env

package/overlays/just/setup.sh

@@ -9,31 +9,19 @@ echo "⚡ Setting up just task runner..."
 JUST_VERSION="1.25.2"
 ARCH=$(uname -m)
 
-# SHA256 checksums for just v1.25.2
-if [ "$ARCH" = "x86_64" ]; then
-    ARCH="x86_64"
-    CHECKSUM="6804798c3744fd1ce563840ee9fe14ae53c74b3cc7b8536da3f87751d7f85501"
-elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
+if [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
     ARCH="aarch64"
-    CHECKSUM="f287a95846131ce8de65181b0b1ec0a0b7db4f6f8d393b3b548f70fcb5a4b0ee"
+elif [ "$ARCH" = "x86_64" ]; then
+    ARCH="x86_64"
 else
-    echo "⚠️  Unsupported architecture: $ARCH"
+    echo "⚠️  Unsupported architecture: $ARCH, falling back to x86_64"
     ARCH="x86_64"
-    CHECKSUM="6804798c3744fd1ce563840ee9fe14ae53c74b3cc7b8536da3f87751d7f85501"
 fi
 
 echo "📦 Downloading just v${JUST_VERSION} for ${ARCH}..."
-curl -L "https://github.com/casey/just/releases/download/${JUST_VERSION}/just-${JUST_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" \
+curl -fsSL "https://github.com/casey/just/releases/download/${JUST_VERSION}/just-${JUST_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" \
     -o /tmp/just.tar.gz
 
-# Verify checksum
-echo "🔐 Verifying checksum..."
-echo "${CHECKSUM}  /tmp/just.tar.gz" | sha256sum -c - || {
-    echo "✗ Checksum verification failed"
-    rm /tmp/just.tar.gz
-    exit 1
-}
-
 # Extract and install
 tar -xzf /tmp/just.tar.gz -C /tmp
 sudo mv /tmp/just /usr/local/bin/

package/overlays/k3d/README.md

@@ -0,0 +1,201 @@
+# k3d Overlay
+
+Installs [k3d](https://k3d.io), a lightweight wrapper that runs [k3s](https://k3s.io) (Rancher's minimal Kubernetes distribution) in Docker containers, enabling fast local Kubernetes clusters for development.
+
+> **Note:** This overlay conflicts with `kind` because both tools create local Kubernetes clusters using Docker containers. Choose `k3d` for faster startup and lower resource usage, or `kind` for full Kubernetes conformance.
+
+## Features
+
+- **k3d CLI** — Create, manage, and delete local k3s clusters from the terminal
+- **Fast cluster startup** — Clusters spin up in seconds, compared to heavier alternatives
+- **Low resource usage** — k3s has a smaller memory and CPU footprint than full Kubernetes
+- **Multi-node clusters** — Simulate multi-node topologies with server and agent nodes
+- **Load balancer included** — Built-in k3s service load balancer for `LoadBalancer` services
+- **Port and volume mapping** — Map host ports and directories into the cluster easily
+
+## How It Works
+
+k3d is installed as a static binary in the devcontainer during `setup.sh`. It requires Docker (provided by the `docker-in-docker` dependency) to create k3s nodes as Docker containers.
+
+**Dependencies:**
+
+- `docker-in-docker` (required) — Provides the Docker daemon that k3d uses to launch k3s nodes
+
+**Suggested overlays:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm for interacting with k3d clusters
+
+## Installation
+
+k3d is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads the k3d binary for your architecture (amd64/arm64)
+- Installs to `/usr/local/bin/k3d`
+- Verifies Docker access
+
+## Common Commands
+
+### Cluster Management
+
+```bash
+# Create a single-node cluster (control plane + agent in one node)
+k3d cluster create dev
+
+# Create a cluster with multiple agents
+k3d cluster create dev --agents 2
+
+# Create with a specific k3s version
+k3d cluster create dev --image rancher/k3s:v1.30.0-k3s1
+
+# Create with port mapping (host 8080 → cluster LoadBalancer 80)
+k3d cluster create dev -p "8080:80@loadbalancer"
+
+# List all clusters
+k3d cluster list
+
+# Start/stop a cluster
+k3d cluster start dev
+k3d cluster stop dev
+
+# Delete a cluster
+k3d cluster delete dev
+```
+
+### Working with Clusters
+
+```bash
+# Merge k3d kubeconfig into default kubeconfig
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# Get kubeconfig for a specific cluster
+k3d kubeconfig get dev
+
+# Import a Docker image into the cluster (avoids registry push/pull)
+docker build -t myapp:dev .
+k3d image import myapp:dev --cluster dev
+```
+
+### kubectl Integration
+
+```bash
+# Use kubectl with the k3d cluster
+kubectl cluster-info --context k3d-dev
+
+# Deploy a workload
+kubectl create deployment nginx --image=nginx
+kubectl expose deployment nginx --port=80 --type=LoadBalancer
+
+# Port-forward for direct access
+kubectl port-forward service/nginx 8080:80
+```
+
+## Configuration
+
+### Multi-Node Cluster
+
+```bash
+k3d cluster create dev \
+  --servers 1 \
+  --agents 3 \
+  --k3s-arg "--disable=traefik@server:*"
+```
+
+### Volume Mounts
+
+```bash
+# Mount a local directory into all nodes
+k3d cluster create dev \
+  --volume "${PWD}:/app@all"
+```
+
+### Port Mapping
+
+```bash
+# Expose ports 80 and 443 through the cluster load balancer
+k3d cluster create dev \
+  -p "80:80@loadbalancer" \
+  -p "443:443@loadbalancer"
+```
+
+## Benefits vs kind
+
+| Feature               | k3d (this overlay)          | kind                         |
+| --------------------- | --------------------------- | ---------------------------- |
+| **Distribution**      | k3s (lightweight variant)   | ✅ Full Kubernetes           |
+| **Startup speed**     | ✅ Faster (~15–30 s)        | Moderate (~30–60 s)          |
+| **Resource usage**    | ✅ Lower (~256 MB RAM/node) | Higher (~512 MB+ RAM/node)   |
+| **Conformance**       | High (not 100%)             | ✅ 100% CNCF conformant      |
+| **Port mapping**      | ✅ Built-in load balancer   | Manual NodePort/port-forward |
+| **Production parity** | Sufficient for most apps    | ✅ Identical to production   |
+
+**Choose k3d when:**
+
+- Fast iteration cycles are more important than 100% conformance
+- System resources are limited
+- You want built-in load balancer for easy port mapping
+
+**Choose kind when:**
+
+- You need guaranteed Kubernetes API compatibility
+- Developing Kubernetes operators or controllers
+- Testing for production environments
+
+## Use Cases
+
+- **Rapid Kubernetes development** — Fast cluster creation and teardown for iterative development
+- **Helm chart testing** — Deploy and test Helm charts locally before pushing
+- **CI/CD prototyping** — Simulate cluster deployments in low-resource environments
+- **Multi-node testing** — Test workloads across multiple nodes on a single machine
+- **Learning Kubernetes** — Explore Kubernetes concepts with minimal overhead
+
+**Integrates well with:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm package manager
+- `tilt` — Live reload for Kubernetes workloads
+- `skaffold` — Build/deploy automation for Kubernetes
+- `terraform` — IaC for cluster configuration
+
+## Troubleshooting
+
+### Cluster Creation Fails
+
+```bash
+# Ensure Docker daemon is running
+docker info
+
+# Check Docker has sufficient resources
+docker system df
+```
+
+### `kubectl` Cannot Connect
+
+```bash
+# Ensure kubeconfig is merged
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# Verify cluster is running
+k3d cluster list
+kubectl cluster-info --context k3d-dev
+```
+
+### Image Not Found in Cluster
+
+```bash
+# Import local images directly (avoids registry round-trip)
+k3d image import myapp:latest --cluster dev
+```
+
+## References
+
+- [k3d Documentation](https://k3d.io)
+- [k3d GitHub](https://github.com/k3d-io/k3d)
+- [k3s Documentation](https://docs.k3s.io)
+- [Kubernetes Documentation](https://kubernetes.io/docs/)
+
+**Related Overlays:**
+
+- `docker-in-docker` — Required: provides the Docker daemon for k3d
+- [`kubectl-helm`](../kubectl-helm/README.md) — Kubernetes CLI and Helm
+- [`kind`](../kind/README.md) — Full-conformance K8s alternative (conflicts)
+- [`tilt`](../tilt/README.md) — Live reload for Kubernetes development
+- [`skaffold`](../skaffold/README.md) — K8s build and deploy automation

package/overlays/k3d/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    }
+}

package/overlays/k3d/overlay.yml

@@ -0,0 +1,19 @@
+id: k3d
+name: k3d
+description: Lightweight local Kubernetes clusters using k3s in Docker
+category: cloud
+supports: []
+requires:
+    - docker-in-docker
+suggests:
+    - kubectl-helm
+conflicts:
+    - kind
+tags:
+    - cloud
+    - kubernetes
+    - k8s
+    - k3d
+    - k3s
+    - testing
+ports: []

package/overlays/k3d/setup.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Setup script for k3d
+
+set -e
+
+echo "🔧 Setting up k3d..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
+
+# Install k3d
+K3D_VERSION="${K3D_VERSION:-v5.7.4}"
+echo "📦 Installing k3d ${K3D_VERSION}..."
+
+install_binary \
+    "https://github.com/k3d-io/k3d/releases/download/${K3D_VERSION}/k3d-linux-${CS_ARCH}" \
+    "k3d"
+
+# Verify installation
+if command -v k3d &>/dev/null; then
+    echo "✅ k3d installed successfully"
+    k3d version
+else
+    echo "❌ k3d installation failed"
+    exit 1
+fi
+
+echo "✅ k3d setup complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   k3d cluster create dev"

package/overlays/k3d/verify.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Verification script for k3d overlay
+# Confirms k3d is installed
+
+set -e
+
+echo "🔍 Verifying k3d overlay..."
+echo ""
+
+# Check k3d is installed
+echo "1️⃣ Checking k3d installation..."
+if command -v k3d &>/dev/null; then
+    k3d version
+    echo "   ✅ k3d is installed"
+else
+    echo "   ❌ k3d is not installed"
+    exit 1
+fi
+
+# Check Docker is available (required for k3d)
+echo ""
+echo "2️⃣ Checking Docker availability..."
+if ! command -v docker &>/dev/null; then
+    echo "   ❌ Docker CLI not found"
+    exit 1
+fi
+if docker version --format '{{.Server.Version}}' &>/dev/null; then
+    echo "   ✅ Docker is available"
+else
+    echo "   ❌ Docker daemon not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ k3d overlay verification complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   k3d cluster create dev"

package/overlays/keycloak/docker-compose.yml

@@ -15,18 +15,20 @@ services:
             KC_HTTP_PORT: 8180
             KC_HOSTNAME_STRICT: 'false'
             KC_HTTP_ENABLED: 'true'
+            KC_HEALTH_ENABLED: 'true'
         ports:
             - '${KEYCLOAK_PORT:-8180}:8180'
         depends_on:
-            - postgres
+            postgres:
+                condition: service_healthy
         networks:
             - devnet
         healthcheck:
-            test: ['CMD-SHELL', 'curl -sf http://localhost:8180/health/ready || exit 1']
+            test: ['CMD-SHELL', 'curl -sf http://localhost:9000/health/ready || exit 1']
             interval: 15s
             timeout: 10s
-            retries: 10
-            start_period: 60s
+            retries: 15
+            start_period: 90s
 
 networks:
     devnet:

package/overlays/keycloak/verify.sh

@@ -20,10 +20,11 @@ echo ""
 echo "2️⃣ Checking Keycloak service..."
 KEYCLOAK_HOST="${KEYCLOAK_HOST:-keycloak}"
 KEYCLOAK_PORT="${KEYCLOAK_PORT:-8180}"
+KEYCLOAK_MGMT_PORT="${KEYCLOAK_MGMT_PORT:-9000}"
 KEYCLOAK_READY=false
 
-for i in {1..40}; do
-    if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_PORT}/health/ready" &> /dev/null; then
+for i in {1..80}; do
+    if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_MGMT_PORT}/health/ready" &> /dev/null; then
         echo "   ✅ Keycloak service is ready"
         KEYCLOAK_READY=true
         break
@@ -32,7 +33,7 @@ for i in {1..40}; do
 done
 
 if [ "$KEYCLOAK_READY" = false ]; then
-    echo "   ❌ Keycloak service not ready after 2 minutes"
+    echo "   ❌ Keycloak service not ready after 4 minutes"
     echo "   ℹ️  Keycloak can take a while to start on first run"
     exit 1
 fi

package/overlays/kind/devcontainer.patch.json

@@ -5,6 +5,5 @@
             "apt": "curl",
             "apk": "curl"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-kind.sh"
+    }
 }

package/overlays/kind/setup.sh

@@ -5,28 +5,19 @@ set -e
 
 echo "🔧 Setting up kind (Kubernetes in Docker)..."
 
-# Detect architecture
-ARCH=$(uname -m)
-case $ARCH in
-    x86_64)
-        KIND_ARCH="amd64"
-        ;;
-    aarch64|arm64)
-        KIND_ARCH="arm64"
-        ;;
-    *)
-        echo "❌ Unsupported architecture: $ARCH"
-        exit 1
-        ;;
-esac
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
 
 # Install kind
 KIND_VERSION="${KIND_VERSION:-v0.22.0}"
 echo "📦 Installing kind ${KIND_VERSION}..."
 
-curl -Lo /tmp/kind "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-${KIND_ARCH}"
-chmod +x /tmp/kind
-sudo mv /tmp/kind /usr/local/bin/kind
+install_binary \
+    "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-${CS_ARCH}" \
+    "kind"
 
 # Verify installation
 if command -v kind &> /dev/null; then

package/overlays/minio/setup.sh

@@ -7,25 +7,17 @@ echo "🔧 Setting up MinIO client..."
 
 # Install MinIO client (mc)
 echo "📦 Installing MinIO client (mc)..."
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
 if ! command -v mc &> /dev/null; then
-    # Pin to a specific version for security and reproducibility
-    MC_VERSION="RELEASE.2024-11-17T19-35-25Z"
-    MC_URL="https://dl.min.io/client/mc/release/linux-amd64/archive/mc.${MC_VERSION}"
-    MC_CHECKSUM="27e18faeabd9a0c8066e3b4aadb13a2c0ae4dac09a1e24defe34c99a11b59e26"
-    
-    echo "   Downloading MinIO client version ${MC_VERSION}..."
-    wget -q "${MC_URL}" -O /tmp/mc
-    
-    # Verify checksum
-    echo "   Verifying checksum..."
-    echo "${MC_CHECKSUM}  /tmp/mc" | sha256sum -c - || {
-        echo "   ❌ Checksum verification failed!"
-        rm -f /tmp/mc
-        exit 1
-    }
-    
-    sudo install /tmp/mc /usr/local/bin/
-    rm /tmp/mc
+    MC_VERSION="${MC_VERSION:-RELEASE.2024-11-17T19-35-25Z}"
+    detect_arch
+    echo "   Downloading MinIO client version ${MC_VERSION} for ${CS_ARCH}..."
+    install_binary \
+        "https://dl.min.io/client/mc/release/linux-${CS_ARCH}/archive/mc.${MC_VERSION}" \
+        "mc"
     echo "   ✅ MinIO client installed (${MC_VERSION})"
 else
     echo "   ✅ MinIO client already installed"