Architecture Advisor

# Reference data populated at runtime by sync-references.sh
# Do not commit — consumers fetch this on first use.
references/

#!/usr/bin/env bash
# smoke-test.sh — End-to-end verification of the architecture-advisor sync workflow
#
# Tests:
#   1. Default sync populates expected directories
#   2. .sync-state.yml is valid and contains required fields
#   3. Status command works
#   4. Idempotent re-sync updates timestamp
#   5. Path mappings produce expected structure
#
# Usage:
#   bash scripts/smoke-test.sh
#
# Exit codes:
#   0 — all checks passed
#   1 — one or more checks failed

set -uo pipefail
# Note: no -e; the check() function handles pass/fail explicitly.

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SYNC_SCRIPT="$SCRIPT_DIR/sync-references.sh"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"

# --- Test workspace ---
# Work in a temp copy so we don't pollute the real skill directory
WORK_DIR="$(mktemp -d)"
cleanup() { rm -rf "$WORK_DIR"; }
trap cleanup EXIT

# Copy the skill (without any existing references/) to the temp directory
mkdir -p "$WORK_DIR/architecture-advisor/scripts"
cp "$SKILL_DIR/SKILL.md" "$WORK_DIR/architecture-advisor/"
cp "$SYNC_SCRIPT" "$WORK_DIR/architecture-advisor/scripts/"

TEST_SYNC="$WORK_DIR/architecture-advisor/scripts/sync-references.sh"
REFS_DIR="$WORK_DIR/architecture-advisor/references"

PASS=0
FAIL=0

check() {
  local label="$1"
  shift
  if "$@" >/dev/null 2>&1; then
    echo "  PASS: $label"
    PASS=$((PASS + 1))
  else
    echo "  FAIL: $label"
    FAIL=$((FAIL + 1))
  fi
}

# --- Portable YAML field extractor ---
yaml_field() {
  local file="$1" field="$2"
  grep "  *${field}:" "$file" | head -1 | sed 's/.*: *"\{0,1\}\([^"]*\)"\{0,1\}/\1/' | tr -d ' '
}

echo "=== Architecture Advisor Smoke Test ==="
echo "Working directory: $WORK_DIR"
echo ""

# ============================================================
# Test 1: Default sync populates expected directories
# ============================================================
echo "--- Test 1: Default sync ---"

bash "$TEST_SYNC" >/dev/null 2>&1
SYNC_EXIT=$?

check "sync script exits 0" test "$SYNC_EXIT" -eq 0
check "references/ created" test -d "$REFS_DIR"
check "reference-library/ present" test -d "$REFS_DIR/reference-library"
check "templates/ present" test -d "$REFS_DIR/templates"
check "catalogs/ present" test -d "$REFS_DIR/catalogs"
check "analysis/ present" test -d "$REFS_DIR/analysis"

# ============================================================
# Test 2: Expected catalog sources present
# ============================================================
echo ""
echo "--- Test 2: Catalog sources ---"

check "catalogs/TheKataLog/ present" test -d "$REFS_DIR/catalogs/TheKataLog"
check "catalogs/AOSA/ present" test -d "$REFS_DIR/catalogs/AOSA"
check "catalogs/RealWorldASPNET/ present" test -d "$REFS_DIR/catalogs/RealWorldASPNET"
check "catalogs/ReferenceArchitectures/ present" test -d "$REFS_DIR/catalogs/ReferenceArchitectures"
check "analysis/TheKataLog/ present" test -d "$REFS_DIR/analysis/TheKataLog"

# Spot-check key files
check "solution-spaces.md exists" test -f "$REFS_DIR/reference-library/solution-spaces.md"
check "problem-solution-matrix.md exists" test -f "$REFS_DIR/reference-library/problem-solution-matrix.md"
check "decision-navigator.md exists" test -f "$REFS_DIR/reference-library/decision-navigator.md"
check "TheKataLog _index.yaml exists" test -f "$REFS_DIR/catalogs/TheKataLog/_index.yaml"

# ============================================================
# Test 3: .sync-state.yml is valid
# ============================================================
echo ""
echo "--- Test 3: .sync-state.yml validation ---"

SYNC_STATE="$REFS_DIR/.sync-state.yml"

check ".sync-state.yml exists" test -f "$SYNC_STATE"
check "contains source: key" grep -q "^source:" "$SYNC_STATE"
check "contains sync: key" grep -q "^sync:" "$SYNC_STATE"
check "contains contents: key" grep -q "^contents:" "$SYNC_STATE"

commit_val="$(yaml_field "$SYNC_STATE" "commit" || true)"
check "commit is 40 hex chars ($commit_val)" bash -c "[[ '$commit_val' =~ ^[0-9a-f]{40}$ ]]"

mode_val="$(yaml_field "$SYNC_STATE" "mode" || true)"
check "mode is default ($mode_val)" test "$mode_val" = "default"

at_val="$(yaml_field "$SYNC_STATE" "at" || true)"
check "at is non-empty" test -n "$at_val"

# ============================================================
# Test 4: Status command works
# ============================================================
echo ""
echo "--- Test 4: Status command ---"

STATUS_OUTPUT="$(bash "$TEST_SYNC" --status 2>&1)"
STATUS_EXIT=$?

check "status exits 0" test "$STATUS_EXIT" -eq 0
check "status shows sync state header" bash -c "[[ '$STATUS_OUTPUT' == *'Sync State'* ]]"
check "status shows commit" bash -c "[[ '$STATUS_OUTPUT' == *'commit:'* ]]"

# ============================================================
# Test 5: Idempotent re-sync
# ============================================================
echo ""
echo "--- Test 5: Idempotent re-sync ---"

FIRST_AT="$at_val"

sleep 2

bash "$TEST_SYNC" >/dev/null 2>&1
RESYNC_EXIT=$?

SECOND_AT="$(yaml_field "$SYNC_STATE" "at" || true)"

check "re-sync exits 0" test "$RESYNC_EXIT" -eq 0
check "timestamp updated after re-sync" test "$FIRST_AT" != "$SECOND_AT"
check "reference-library still present" test -d "$REFS_DIR/reference-library"
check "catalogs still present" test -d "$REFS_DIR/catalogs"

# ============================================================
# Test 6: No evidence pool in default mode
# ============================================================
echo ""
echo "--- Test 6: Evidence pool absent in default mode ---"

if [ ! -d "$REFS_DIR/evidence-pool" ]; then
  echo "  PASS: evidence-pool/ not present (correct for default mode)"
  PASS=$((PASS + 1))
else
  echo "  FAIL: evidence-pool/ should not exist in default mode"
  FAIL=$((FAIL + 1))
fi

# ============================================================
# Summary
# ============================================================
echo ""
echo "=== Results: $PASS passed, $FAIL failed ==="

if [ "$FAIL" -gt 0 ]; then
  echo "SMOKE TEST FAILED"
  exit 1
else
  echo "SMOKE TEST PASSED"
  exit 0
fi

#!/usr/bin/env bash
# sync-references.sh — Fetch reference data from architecture-reference
#
# Sparse-clones the source repository and extracts reference data into the
# skill's references/ directory, per the Agent Skills spec (agentskills.io).
#
# Usage:
#   bash scripts/sync-references.sh [options]
#
# Modes:
#   (default)          Reference library, catalogs, analyses, templates (<1 MB)
#   --evidence-pool    Also includes full team submissions (~2.2 GB)
#   --status           Show current sync state without fetching
#
# Options:
#   --ref REF     Branch, tag, or commit to fetch (default: main)
#   --repo URL    Override source repository URL
#
# Requires: git, date
# Outputs:  references/ directory alongside this script's parent SKILL.md

set -euo pipefail

# --- Resolve paths ---
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
REFERENCES_DIR="$SKILL_DIR/references"

# --- Defaults ---
SOURCE_REPO="https://github.com/cristoslc/architecture-reference"
REF="main"
INCLUDE_EVIDENCE_POOL=false
STATUS_ONLY=false

# --- Parse arguments ---
while [ $# -gt 0 ]; do
  case "$1" in
    --evidence-pool) INCLUDE_EVIDENCE_POOL=true; shift ;;
    --status)        STATUS_ONLY=true; shift ;;
    --ref)           REF="${2:?--ref requires a value}"; shift 2 ;;
    --repo)          SOURCE_REPO="${2:?--repo requires a value}"; shift 2 ;;
    -h|--help)
      head -20 "$0" | grep '^#' | sed 's/^# \?//'
      exit 0
      ;;
    *)
      echo "Unknown option: $1" >&2
      exit 1
      ;;
  esac
done

# --- Status check ---
SYNC_STATE="$REFERENCES_DIR/.sync-state.yml"

if $STATUS_ONLY; then
  if [ -f "$SYNC_STATE" ]; then
    echo "=== Sync State ==="
    cat "$SYNC_STATE"
  else
    echo "No references synced yet. Run: bash scripts/sync-references.sh"
  fi
  exit 0
fi

# --- Portable ISO 8601 UTC timestamp ---
iso_timestamp() {
  date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ"
}

# --- Temp directory with cleanup ---
TMPDIR_WORK="$(mktemp -d)"
cleanup() { rm -rf "$TMPDIR_WORK"; }
trap cleanup EXIT

MODE="default"
$INCLUDE_EVIDENCE_POOL && MODE="evidence-pool"

echo "Syncing references (mode: $MODE) from $SOURCE_REPO (ref: $REF)..."

# --- Sparse clone ---
# Use --filter=blob:none for a treeless clone (downloads blobs on demand)
# then sparse-checkout to materialize only the paths we need.
git clone --depth 1 --filter=blob:none --sparse --quiet \
  "$SOURCE_REPO" "$TMPDIR_WORK/repo" 2>/dev/null || \
git clone --depth 1 --quiet "$SOURCE_REPO" "$TMPDIR_WORK/repo"

cd "$TMPDIR_WORK/repo"

# Checkout the requested ref if not default
if [ "$REF" != "main" ] && [ "$REF" != "HEAD" ]; then
  git fetch --depth 1 origin "$REF" --quiet 2>/dev/null || true
  git checkout --quiet "$REF" 2>/dev/null || true
fi

COMMIT_SHA="$(git rev-parse HEAD)"

# --- Configure sparse-checkout paths ---
# Default: reference library + catalogs + analyses + templates
SPARSE_PATHS="docs/reference-library
docs/templates
evidence-analysis/TheKataLog/docs/catalog
evidence-analysis/TheKataLog/docs/analysis
evidence-analysis/AOSA/docs/catalog
evidence-analysis/AOSA/docs/analysis
evidence-analysis/RealWorldASPNET/docs/catalog
evidence-analysis/RealWorldASPNET/docs/analysis
evidence-analysis/ReferenceArchitectures/docs/catalog
evidence-analysis/ReferenceArchitectures/docs/analysis"

if $INCLUDE_EVIDENCE_POOL; then
  SPARSE_PATHS="$SPARSE_PATHS
evidence-pool/TheKataLog"
fi

# Apply sparse-checkout
git sparse-checkout init --cone
echo "$SPARSE_PATHS" | while IFS= read -r p; do
  [ -n "$p" ] && echo "$p"
done | git sparse-checkout set --stdin

# --- Extract to references/ ---
# Clean previous references (preserve .sync-state.yml until we write the new one)
if [ -d "$REFERENCES_DIR" ]; then
  find "$REFERENCES_DIR" -mindepth 1 -not -name '.sync-state.yml' -delete 2>/dev/null || true
fi
mkdir -p "$REFERENCES_DIR"

# Reference library
if [ -d "docs/reference-library" ]; then
  cp -R docs/reference-library "$REFERENCES_DIR/reference-library"
  echo "  Synced: reference-library/"
fi

# Templates
if [ -d "docs/templates" ]; then
  cp -R docs/templates "$REFERENCES_DIR/templates"
  echo "  Synced: templates/"
fi

# Catalogs — flatten the 4 sources into references/catalogs/<source>/
mkdir -p "$REFERENCES_DIR/catalogs"
for source_dir in evidence-analysis/*/docs/catalog; do
  if [ -d "$source_dir" ]; then
    source_name="$(echo "$source_dir" | cut -d'/' -f2)"
    cp -R "$source_dir" "$REFERENCES_DIR/catalogs/$source_name"
    file_count=$(find "$REFERENCES_DIR/catalogs/$source_name" -name '*.yaml' | wc -l)
    echo "  Synced: catalogs/$source_name/ ($file_count YAML files)"
  fi
done

# Analyses — flatten similarly
mkdir -p "$REFERENCES_DIR/analysis"
for source_dir in evidence-analysis/*/docs/analysis; do
  if [ -d "$source_dir" ]; then
    source_name="$(echo "$source_dir" | cut -d'/' -f2)"
    cp -R "$source_dir" "$REFERENCES_DIR/analysis/$source_name"
    echo "  Synced: analysis/$source_name/"
  fi
done

# Evidence pool (optional)
if $INCLUDE_EVIDENCE_POOL; then
  if [ -d "evidence-pool/TheKataLog" ]; then
    cp -R evidence-pool/TheKataLog "$REFERENCES_DIR/evidence-pool"
    team_count=$(find "$REFERENCES_DIR/evidence-pool" -mindepth 2 -maxdepth 2 -type d | wc -l)
    echo "  Synced: evidence-pool/ ($team_count team directories)"
  fi
fi

# --- Write sync state ---
SYNCED_AT="$(iso_timestamp)"

cat > "$SYNC_STATE" <<YAML
# .sync-state.yml — Reference data provenance
# Machine-generated by sync-references.sh. Do not edit manually.

source:
  repository: ${SOURCE_REPO}
  ref: ${REF}
  commit: ${COMMIT_SHA}

sync:
  mode: ${MODE}
  at: "${SYNCED_AT}"
  by: sync-references.sh

contents:
  - reference-library
  - templates
  - catalogs
  - analysis
YAML

if [ -d "$REFERENCES_DIR/evidence-pool" ]; then
  echo "  - evidence-pool" >> "$SYNC_STATE"
fi

cd "$SKILL_DIR"

# --- Summary ---
REF_SIZE=$(du -sh "$REFERENCES_DIR" 2>/dev/null | cut -f1)
echo ""
echo "OK: References synced ($REF_SIZE)"
echo "  Commit: $COMMIT_SHA"
echo "  Mode:   $MODE"
echo "  Path:   $REFERENCES_DIR"
echo ""
echo "To update:  bash scripts/sync-references.sh"
echo "To check:   bash scripts/sync-references.sh --status"