chore: add validation Makefile, healthcheck, demo compose and CI workflow (issue #68)

Author: bashSunny101

.github/workflows/ci-validate.yml

@@ -0,0 +1,25 @@
+name: CI - Docs validation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python (for some tools if needed)
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y curl docker.io docker-compose-plugin shellcheck protobuf-compiler
+      - name: Run validation
+        run: |
+          make validate
+          make shellcheck

Makefile

@@ -0,0 +1,14 @@
+SHELL := /bin/bash
+.PHONY: validate shellcheck quick-start
+
+validate:
+	@echo "Running project validation..."
+	./scripts/validate-setup.sh
+
+shellcheck:
+	@command -v shellcheck >/dev/null 2>&1 || { echo "shellcheck not found"; exit 2; }
+	@shellcheck scripts/*.sh || true
+
+quick-start:
+	@echo "Quick start (delegates to scripts/quick-start.sh)"
+	@./scripts/quick-start.sh

demo/psa/README.md

@@ -0,0 +1,19 @@
+# PSA demo: minimal placeholder
+
+This folder contains a minimal placeholder `docker-compose.yml` that demonstrates how
+to provide a one-command demo orchestration. It's intentionally tiny and should be
+replaced with real demo services for PSA.
+
+Quick start:
+
+```sh
+cd demo/psa
+docker compose up -d
+docker compose ps
+```
+
+Health check example:
+
+```sh
+./../../scripts/healthcheck.sh http://localhost:8080/health || true
+```

demo/psa/docker-compose.yml

@@ -0,0 +1,6 @@
+version: '3.8'
+services:
+  psa-demo-placeholder:
+    image: busybox:latest
+    command: ["sh", "-c", "while true; do echo psa-demo running; sleep 60; done"]
+    restart: unless-stopped

scripts/healthcheck.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# scripts/healthcheck.sh - simple service health check examples
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <url>"
+  exit 2
+fi
+
+URL=$1
+
+if command -v curl >/dev/null 2>&1; then
+  status=$(curl -s -o /dev/null -w "%{http_code}" "$URL" || true)
+  if [[ "$status" =~ ^2 ]]; then
+    echo "HEALTHY: $URL returned $status"
+    exit 0
+  else
+    echo "UNHEALTHY: $URL returned $status"
+    exit 1
+  fi
+else
+  echo "curl not installed; install curl to run health checks"
+  exit 2
+fi