chore(07-03): Stage deployment scripts and documentation updates

scripts/build-check.sh

@@ -1,68 +1,106 @@
 #!/bin/bash
-# Compare deployed container versions against local git HEAD
-# Warns if containers are stale (built from an older commit)
+# Gravl Build Status Checker
+#
+# Purpose:
+#   Verifies that deployed containers match the current git HEAD.
+#   Warns if containers are stale (built from older commits).
+#   Helps you catch situations where code was updated but not redeployed.
+#
+# How it works:
+#   1. Gets current local git commit (HEAD)
+#   2. Queries each container's build labels
+#   3. Compares container label commit vs local HEAD
+#   4. Reports status: "OK", "STALE", or "WARNING"
+#
+# Exit codes:
+#   0 = All checks completed (see output for individual status)
+#   (Warnings don't cause non-zero exit)
 #
 # Usage:
 #   ./scripts/build-check.sh
 #
-# What it shows:
-#   - Local git HEAD commit SHA
-#   - Each container's built commit SHA (from Docker labels)
-#   - Whether containers are up-to-date or stale
-#   - Warnings if labels are missing (pre-07-02 containers)
+# Example output:
+#   Local HEAD: abc1234 (abc1234567890abcdef...)
 #
-# Label fields read:
-#   - org.opencontainers.image.revision = Git commit SHA embedded by deploy.sh
-#   - org.opencontainers.image.created = Build timestamp (ISO 8601 format)
-#
-# Exit codes:
-#   0 = All containers up to date
-#   1+ = Warnings or stale containers detected
-#
-# See: /docs/DEPLOYMENT.md for troubleshooting
+#   [gravl-backend] Built: abc1234 on 2026-03-03T18:21:00Z
+#   [gravl-backend] OK: up to date
+#   [gravl-frontend] Built: abc1234 on 2026-03-03T18:21:00Z
+#   [gravl-frontend] OK: up to date
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(dirname "$SCRIPT_DIR")"
 
 cd "$REPO_DIR"
 
+# Get the current local git commit (what's checked out locally)
 LOCAL_COMMIT=$(git rev-parse HEAD)
 echo "Local HEAD: $(git rev-parse --short HEAD) ($LOCAL_COMMIT)"
 echo ""
 
-# Check a single container's build status
-# Args: $1 = container name
+# ============================================================================
+# check() helper function
+# ============================================================================
+# Queries a container's build labels and compares against local HEAD.
+#
+# Parameters:
+#   $1 = Container name (e.g., "gravl-backend")
+#
+# Label fields used:
+#   org.opencontainers.image.revision = commit hash when image was built
+#     Format: 40-character SHA (same as git rev-parse HEAD)
+#     Set by: scripts/deploy.sh -> docker compose build args
+#
+#   org.opencontainers.image.created = RFC3339 timestamp when image was built
+#     Format: 2026-03-03T18:21:00Z
+#     Set by: scripts/deploy.sh -> docker compose build args
+#     Purpose: Shows humans when the image was built (for diagnostics)
+#
+# Status outcomes:
+#   - "Not running": Container doesn't exist or isn't running
+#   - "WARNING": Container exists but has no revision label
+#     Fix: Re-deploy with scripts/deploy.sh
+#   - "OK": Container label commit = local HEAD (up to date)
+#   - "STALE": Container label commit != local HEAD
+#     Fix: Run scripts/deploy.sh to update container
 check() {
   local name="$1"
 
-  # Container not running
+  # Check if container exists and is running
   if ! docker inspect "$name" &>/dev/null; then
     echo "[$name] Not running"
     return
   fi
 
-  # Read Docker labels set by deploy.sh
-  # If labels are missing, container was built before phase 07-02
+  # Extract build labels from container config
+  # These labels are set in the docker-compose.yml build args,
+  # and the Dockerfile COPYs them into image labels.
   local commit date
   commit=$(docker inspect "$name" --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' 2>/dev/null)
   date=$(docker inspect "$name" --format '{{index .Config.Labels "org.opencontainers.image.created"}}' 2>/dev/null)
 
+  # Check if revision label exists
   if [ -z "$commit" ] || [ "$commit" = "unknown" ]; then
     echo "[$name] WARNING: no build label found — redeploy with scripts/deploy.sh to add tracking"
     return
   fi
 
-  # Display container info
+  # Display when this container's image was built
   echo "[$name] Built: ${commit:0:7} on ${date:-unknown}"
 
-  # Compare container commit to local HEAD
+  # Compare container's commit against local HEAD
+  # If they match, container is up to date.
+  # If they differ, code has changed locally but container hasn't been redeployed.
   if [ "$commit" = "$LOCAL_COMMIT" ]; then
-    echo "[$name] OK: up to date"
+    echo "[$name] ✓ OK: up to date"
   else
-    echo "[$name] STALE: container is behind local code — run scripts/deploy.sh"
+    echo "[$name] ⚠ STALE: container is behind local code — run scripts/deploy.sh"
   fi
 }
 
-# Check both containers
+# ============================================================================
+# Check Each Service
+# ============================================================================
+# These are the service names defined in docker-compose.yml.
+# Adjust if you rename services.
 check "gravl-backend"
 check "gravl-frontend"