Sync upstream, migrate org refs, introduce go.work workspace & example modules

.github/workflows/auto-bump-modules.yml

@@ -0,0 +1,184 @@
+name: Auto Bump Module Dependencies
+
+on:
+  workflow_dispatch:
+    inputs:
+      coreVersion:
+        description: 'Core modular version (e.g. v1.9.0)'
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      coreVersion:
+        required: true
+        type: string
+    secrets:
+      GH_TOKEN:
+        required: true
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: read
+  checks: write
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    env:
+      GOTOOLCHAIN: auto
+      CGO_ENABLED: 0
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Remove go.work files
+        run: |
+          git rm -f go.work || true
+          git rm -f go.work.sum || true
+          rm -f go.work go.work.sum || true
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '^1.25'
+          check-latest: true
+
+      - name: Determine version
+        id: ver
+        run: |
+          V='${{ inputs.coreVersion || github.event.inputs.coreVersion }}'
+          [[ $V == v* ]] || V="v$V"
+          echo "Using core version $V"
+          echo "core_version=$V" >> $GITHUB_OUTPUT
+
+      - name: Update module go.mod files
+        run: |
+          set -euo pipefail
+          CORE=${{ steps.ver.outputs.core_version }}
+          UPDATED=0
+          for mod in modules/*/go.mod; do
+            [ -f "$mod" ] || continue
+            dir=$(dirname "$mod")
+            # If the require line exists with a version different from CORE, update via go mod edit (portable, avoids sed incompat)
+            if grep -q "github.com/GoCodeAlone/modular v" "$mod" && ! grep -q "github.com/GoCodeAlone/modular ${CORE}" "$mod"; then
+              (cd "$dir" && go mod edit -require=github.com/GoCodeAlone/modular@${CORE})
+              UPDATED=1
+            fi
+            # Drop any replace directive pointing to local modular path to avoid accidental pinning
+            (cd "$dir" && go mod edit -dropreplace=github.com/GoCodeAlone/modular 2>/dev/null || true)
+          done
+          if [ "$UPDATED" = 0 ]; then
+            echo "No module files needed updating"
+          else
+            echo "Module go.mod files updated to ${CORE}"
+          fi
+
+      - name: Go mod tidy each module
+        run: |
+          set -euo pipefail
+          for dir in modules/*/; do
+            [ -f "$dir/go.mod" ] || continue
+            echo "Tidying $dir"
+            (cd "$dir" && go mod tidy)
+          done
+
+      - name: Go mod tidy each example
+        run: |
+          set -euo pipefail
+          for dir in examples/*/; do
+            [ -f "$dir/go.mod" ] || continue
+            echo "Tidying $dir"
+            (cd "$dir" && go mod tidy)
+          done
+
+      - name: Go mod tidy root (defensive)
+        run: |
+          set -euo pipefail
+          if [ -f go.mod ]; then
+            echo "Tidying root module"
+            go mod tidy
+          fi
+
+      - name: Go mod tidy modcli
+        run: |
+          set -euo pipefail
+          if [ -f cmd/modcli/go.mod ]; then
+            echo "Tidying cmd/modcli"
+            (cd cmd/modcli && go mod tidy)
+          fi
+
+      - name: Update documentation version references
+        run: |
+          set -euo pipefail
+          CORE=${{ steps.ver.outputs.core_version }}
+          OLD=$(git grep -h -o 'github.com/GoCodeAlone/modular v[0-9]\+\.[0-9]\+\.[0-9]\+' -- '*.md' | grep -v $CORE | head -n1 | awk '{print $1}' || true)
+          # Replace any explicit old version with current in markdown examples
+          if [ -n "$OLD" ]; then
+            find . -name '*.md' -print0 | xargs -0 sed -i "" -E "s#github.com/GoCodeAlone/modular v[0-9]+\.[0-9]+\.[0-9]+#github.com/GoCodeAlone/modular ${CORE}#g" || find . -name '*.md' -print0 | xargs -0 sed -i -E "s#github.com/GoCodeAlone/modular v[0-9]+\.[0-9]+\.[0-9]+#github.com/GoCodeAlone/modular ${CORE}#g"
+          fi
+
+      - name: Create PR
+        id: pr
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          CORE=${{ steps.ver.outputs.core_version }}
+          BRANCH=auto/bump-modules-${CORE}
+          git config user.name 'github-actions'
+          git config user.email 'github-actions@users.noreply.github.com'
+          # Stage and commit changes first on detached HEAD (checkout provided by actions/checkout)
+          if git diff --quiet; then
+            echo "No changes to commit"
+            echo "created=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+          git add .
+          git commit -m "chore: bump module dependencies to ${CORE}" 
+          # Create or reset branch name to current commit (safe overwrite of existing remote branch)
+          git branch -f "$BRANCH"
+          git checkout -B "$BRANCH"
+          echo "Pushing branch $BRANCH (force-with-lease)"
+          if ! git push --force-with-lease origin "$BRANCH"; then
+            git push --force origin "$BRANCH"
+          fi
+          PR_URL=$(gh pr view "$BRANCH" --json url --jq .url 2>/dev/null || gh pr create --title "chore: bump module dependencies to ${CORE}" --body "Automated update of module go.mod files and docs to ${CORE}." --head "$BRANCH" --base main --draft=false)
+          echo "pr_url=$PR_URL" >> $GITHUB_OUTPUT
+          echo "created=true" >> $GITHUB_OUTPUT
+
+      - name: Run full tests (core + modules + examples + CLI)
+        if: steps.pr.outputs.created == 'true'
+        run: |
+          set -euo pipefail
+          echo "Enabling CGO for race builds"
+          export CGO_ENABLED=1
+          if command -v golangci-lint >/dev/null 2>&1; then golangci-lint run; fi
+          go test ./... -count=1 -race -timeout=15m
+          for module in modules/*/; do
+            if [ -f "$module/go.mod" ]; then
+              echo "Testing $module"; (cd "$module" && go test ./... -count=1 -race -timeout=15m)
+            fi
+          done
+          for example in examples/*/; do
+            if [ -f "$example/go.mod" ]; then
+              echo "Testing $example"; (cd "$example" && go test ./... -count=1 -race -timeout=15m)
+            fi
+          done
+          (cd cmd/modcli && go test ./... -count=1 -race -timeout=15m)
+
+
+      - name: Merge PR
+        if: steps.pr.outputs.created == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          PR=${{ steps.pr.outputs.pr_url }}
+          [ -z "$PR" ] && { echo 'No PR URL'; exit 0; }
+          # Try to enable auto-merge first; if policies block it, attempt an admin squash merge; otherwise leave PR open
+            if ! gh pr merge "$PR" --squash --delete-branch --auto; then
+              gh pr merge "$PR" --squash --delete-branch --admin || echo "Merge deferred: branch policies prevent automatic merge"
+            fi

.github/workflows/bdd-matrix.yml

@@ -0,0 +1,214 @@
+name: BDD Matrix
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '**.go'
+      - 'go.*'
+      - 'modules/**'
+      - '.github/workflows/bdd-matrix.yml'
+  push:
+    branches: [ main ]
+    paths:
+      - '**.go'
+      - 'go.*'
+      - 'modules/**'
+      - '.github/workflows/bdd-matrix.yml'
+  workflow_dispatch:
+
+env:
+  GO_VERSION: '^1.25'
+
+jobs:
+  # Discover modules (reused for matrix)
+  discover:
+    runs-on: ubuntu-latest
+    outputs:
+      modules: ${{ steps.set-matrix.outputs.modules }}
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - id: set-matrix
+        run: |
+          ALL_MODULES=$(find modules -maxdepth 1 -mindepth 1 -type d -exec basename {} \; | sort)
+          MODULES_JSON=$(echo "$ALL_MODULES" | tr ' ' '\n' | grep -v '^$' | jq -R . | jq -s .)
+          echo "Modules: $MODULES_JSON"
+          {
+            echo "matrix<<EOF"; echo "{\"module\":$MODULES_JSON}"; echo "EOF"; } >> $GITHUB_OUTPUT
+          { echo "modules<<EOF"; echo "$MODULES_JSON"; echo "EOF"; } >> $GITHUB_OUTPUT
+
+  # Core framework BDD tests (single job)
+  core-bdd:
+    runs-on: ubuntu-latest
+    needs: discover
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          check-latest: true
+          cache: true
+      - name: Run core framework BDD tests
+        run: |
+          set -e
+          echo '=== Core Framework BDD Tests ==='
+          export CGO_ENABLED=1
+          export GORACE=halt_on_error=1
+          go test -race -v -coverprofile=core-bdd-coverage.txt -covermode=atomic -run 'TestApplicationLifecycle|TestConfigurationManagement|TestBaseConfigBDDFeatures|TestLoggerDecorator' .
+      - name: Upload core BDD coverage
+        uses: codecov/codecov-action@fdcc8476540edceab3de004e990f80d881c6cc00 # v5.5.0 pinned
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: GoCodeAlone/modular
+          files: core-bdd-coverage.txt
+          flags: core-bdd
+      - name: Persist core BDD coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: core-bdd-coverage
+          path: core-bdd-coverage.txt
+
+  # Run each module's BDD tests in parallel matrix
+  module-bdd:
+    runs-on: ubuntu-latest
+    needs: discover
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover.outputs.matrix) }}
+    name: BDD ${{ matrix.module }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          check-latest: true
+          cache: true
+      - name: Run BDD tests
+        working-directory: modules/${{ matrix.module }}
+        run: |
+          echo "=== BDD for ${{ matrix.module }} ==="
+          # Run BDD-focused Go tests (naming convention: *BDD*)
+          export CGO_ENABLED=1
+          export GORACE=halt_on_error=1
+          set -euo pipefail
+          # Modules expected to contain BDD tests (update as coverage grows)
+          EXPECTED_BDD_MODULES=(reverseproxy httpserver scheduler cache auth database eventbus)
+          expected=false
+          for m in "${EXPECTED_BDD_MODULES[@]}"; do
+            if [ "$m" = "${{ matrix.module }}" ]; then expected=true; break; fi
+          done
+          if go test -race -v -coverprofile=bdd-${{ matrix.module }}-coverage.txt -covermode=atomic -run '.*BDD|.*Module' .; then
+            echo "BDD tests executed for ${{ matrix.module }}"
+          else
+            echo "::error title=BDD Tests Failed::go test command failed for ${{ matrix.module }}" >&2
+            exit 1
+          fi
+          if [ ! -s bdd-${{ matrix.module }}-coverage.txt ]; then
+            if [ "$expected" = true ]; then
+              echo "::error title=Missing Expected BDD Tests::Module ${{ matrix.module }} is in EXPECTED_BDD_MODULES but produced no BDD coverage" >&2
+              exit 1
+            else
+              echo "::notice title=No BDD Tests Detected::No matching BDD tests for non-BDD module ${{ matrix.module }}" >&2
+              echo 'mode: atomic' > bdd-${{ matrix.module }}-coverage.txt
+            fi
+          fi
+      - name: Upload module BDD coverage
+        if: always()
+        uses: codecov/codecov-action@fdcc8476540edceab3de004e990f80d881c6cc00 # v5.5.0 pinned
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: GoCodeAlone/modular
+          files: modules/${{ matrix.module }}/bdd-${{ matrix.module }}-coverage.txt
+          flags: bdd-${{ matrix.module }}
+      - name: Persist module BDD coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bdd-${{ matrix.module }}-coverage
+          path: modules/${{ matrix.module }}/bdd-${{ matrix.module }}-coverage.txt
+
+  # Summary job collates results
+  summary:
+    if: always()
+    needs: [core-bdd, module-bdd, discover]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository (for merge script)
+        uses: actions/checkout@v5
+      - name: Summarize
+        run: |
+          echo '# BDD Matrix Summary' >> $GITHUB_STEP_SUMMARY
+          echo '' >> $GITHUB_STEP_SUMMARY
+          echo 'Core BDD Job: ${{ needs.core-bdd.result }}' >> $GITHUB_STEP_SUMMARY
+          echo '' >> $GITHUB_STEP_SUMMARY
+          echo 'Modules (parallel) overall result: ${{ needs.module-bdd.result }}' >> $GITHUB_STEP_SUMMARY
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@v5
+        with:
+          path: bdd-coverage
+      - name: Merge BDD coverage
+        run: |
+          set -euo pipefail
+          ls -R bdd-coverage || true
+          shopt -s globstar nullglob
+          FILES=(bdd-coverage/**/*.txt)
+          if [ ${#FILES[@]} -eq 0 ]; then
+            echo "No coverage files found to merge" >&2
+            # Nothing to do (don't fail)
+            exit 0
+          fi
+          echo "Found ${#FILES[@]} coverage profiles"
+          # Prefer central script if present, else inline merge
+          if [ -f scripts/merge-coverprofiles.sh ]; then
+            chmod +x scripts/merge-coverprofiles.sh
+            if ! ./scripts/merge-coverprofiles.sh merged-bdd-coverage.txt "${FILES[@]}"; then
+              echo "[warn] merge-coverprofiles.sh failed, falling back to inline merge" >&2
+            else
+              echo "Merged via script"; exit 0
+            fi
+          else
+            echo "[info] merge-coverprofiles.sh not found, using inline merge" >&2
+          fi
+          # Inline merge fallback
+          OUT=merged-bdd-coverage.txt
+          FIRST=1
+          : > "$OUT"
+          for f in "${FILES[@]}"; do
+            [ -f "$f" ] || { echo "[warn] Missing profile $f" >&2; continue; }
+            if [ $FIRST -eq 1 ]; then
+              cat "$f" >> "$OUT"; FIRST=0
+            else
+              { grep -v '^mode:' "$f" || true; } >> "$OUT"
+            fi
+          done
+          # Ensure a mode line exists at top
+          if ! grep -q '^mode:' "$OUT"; then
+            echo 'mode: atomic' | cat - "$OUT" > "$OUT.tmp" && mv "$OUT.tmp" "$OUT"
+          fi
+          # Never fail this step due to merge nuances
+          true
+          echo "Merged (fallback) into $OUT from ${#FILES[@]} files" >&2
+      - name: Upload merged BDD coverage
+        if: always()
+        uses: codecov/codecov-action@fdcc8476540edceab3de004e990f80d881c6cc00 # v5.5.0 pinned
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: GoCodeAlone/modular
+          files: merged-bdd-coverage.txt
+          flags: merged-bdd
+      - name: Persist merged BDD coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-bdd-coverage
+          path: merged-bdd-coverage.txt